From e39569ba078387c4351b12ecbedf1114442a41c1 Mon Sep 17 00:00:00 2001 From: zemion Date: Sat, 1 Aug 2026 08:55:50 +0200 Subject: [PATCH] Sync Repo-docs-CONCEPT from project files --- Repo-docs-CONCEPT.-.md | 183 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 183 insertions(+) create mode 100644 Repo-docs-CONCEPT.-.md diff --git a/Repo-docs-CONCEPT.-.md b/Repo-docs-CONCEPT.-.md new file mode 100644 index 0000000..9c58b1d --- /dev/null +++ b/Repo-docs-CONCEPT.-.md @@ -0,0 +1,183 @@ + + +> Mirrored from `/mnt/DATA/git/govoplan-cases/docs/CONCEPT.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# govoplan-cases Concept + +## Purpose + +`govoplan-cases` is the formal administrative case module. It creates a durable +container for a procedure such as a permit application, inspection, complaint, +grant request, or internal administrative matter. + +The case is not the workflow engine and not the file store. It is the stable +record that ties together participants, status, assignments, deadlines, +evidence, decisions, communications, audit events, and retention references. + +## Ownership + +The module owns: + +- case identifiers, references, titles, types, and status +- case-local party references and role labels such as applicant, respondent, + beneficiary, and representative, using a shared Parties contract when present +- case metadata and tags +- due dates, service-level targets, and milestone dates +- links to evidence provided by other modules +- case comments and internal notes once the collaboration boundary is decided +- case-level access checks and resource ACL contributions +- case event emission for lifecycle changes +- case summary APIs and WebUI route contributions + +The module does not own: + +- form submissions and validation, owned by forms/forms-runtime +- binary file storage, owned by files or DMS +- workflow state machines and transition execution, owned by workflow +- work queues and task assignment semantics, owned by tasks +- generated documents, owned by templates/DMS +- appointments, mail, notifications, postbox, payments, or ledger postings +- identity/contact/organization masters, representation powers, formal + institutional decision semantics, mandates, or jurisdiction + +## Core Contracts + +The module should integrate through: + +- module manifest metadata, route factories, permissions, and migrations +- a `cases.access` or similar case access capability for resource checks +- a `cases.summary` capability for dashboards and cross-module previews +- shared party, mandate, service, and decision reference DTOs when those + providers are available +- events such as `case.created`, `case.updated`, `case.status_changed`, + `case.assigned`, and `case.closed` +- commands such as `cases.open`, `cases.update_status`, `cases.link_evidence`, + and `cases.assign` +- DTOs with stable IDs and labels, not ORM objects + +Other modules should link to a case by stable references: + +```json +{ + "case_id": "case-uuid", + "tenant_id": "tenant-uuid", + "relation": "submission" +} +``` + +## Reference Journey + +Permit-to-payment MVP: + +1. Portal/forms runtime receives a public application. +2. Workflow asks cases to create a case record. +3. Files/DMS links uploaded evidence to the case. +4. Tasks assigns an internal review task. +5. Workflow moves the case from intake to review to appointment to decision. +6. Templates generates the permit or decision document and links it to the case. +7. Payments links payment evidence. +8. Audit and records retain the case history. + +## MVP Slice + +The first implementation should provide: + +- case type registry with a minimal tenant-local configuration +- create/list/read/update case APIs +- status values with a simple configurable catalog +- parties stored as stable procedure-party references with a compatibility + path for direct identity/organization references; assignments remain + responsibility references +- evidence links as module/resource references +- case timeline from local events plus linked audit event IDs +- basic WebUI list/detail route +- resource ACL provider for case read/update +- tenant summary provider for dashboard counts + +## Permissions + +Candidate scopes: + +- `cases:case:read` +- `cases:case:create` +- `cases:case:update` +- `cases:case:assign` +- `cases:case:close` +- `cases:case:admin` + +Access decisions should combine tenant permissions, case ownership/assignment, +and explicit case shares when those are introduced. + +## Data Model Sketch + +Candidate tables: + +- `cases` +- `case_parties` +- `case_assignments` +- `case_evidence_links` +- `case_timeline_entries` +- `case_type_definitions` +- `case_status_definitions` + +`case_parties` is a compatibility seed for a Cases-only composition. It must +not grow a second identity/contact master or duplicate effective-dated powers +of representation. Once a shared Parties provider exists, Cases should retain +the provider reference plus the minimal immutable role/evidence snapshot needed +to reconstruct the case. + +The implemented headless compatibility path therefore accepts only a stable +subject reference, case-local role, effective interval, permitted/preferred +channels, delivery flag, evidence, and immutable contact snapshot references. +It cannot model representation powers. When `parties.resolver` is available, +Cases uses its effective, tenant-scoped party and representation records and +rejects mismatched procedures or conflicting active role assignments. +Shared Core revision helpers keep corrections, expiry, supersession, and +revocation immutable and OCC-guarded. Representation revocation has its own +effective timestamp so a historical delivery decision can be reconstructed. + +`cases.service_intake` consumes a published, effective shared Service +definition. It requires one case binding and preserves the exact Service +version plus its responsible unit/function, Mandate, jurisdictions, legal +bases, required evidence, deadlines, forms, workflows, and result bindings in +a governed intake plan. It does not copy or persist the Service definition. + +Cases links formal Decision records and may retain a current outcome/status +projection. It does not own decision authority, rule versions, reasoning, +correction, revocation, or remedy semantics. + +Evidence links should store only stable module/resource references and display +metadata snapshots. The owning module remains responsible for the real object. + +## WebUI + +Initial route contributions: + +- `/cases` +- `/cases/:caseId` + +The case detail view should expose extension points for linked forms, files, +tasks, workflow state, appointments, documents, communication, payment evidence, +and audit timeline. Extension points must be declarative; no direct UI imports +from sibling modules. + +## Tests + +Minimum tests: + +- core can start with cases present and sibling modules absent +- creating a case emits a case event and audit event +- case ACL blocks unauthorized read/update +- evidence links accept only module/resource references +- optional modules can contribute detail panels without direct imports +- migration metadata registers through the module manifest + +## Open Decisions + +- Whether comments belong in cases, tasks, or a collaboration module. +- Whether case type/status catalogs are fully configurable in MVP or seeded. +- How records/legal-hold integration should own retention of closed cases. +- Whether case shares are local to cases or use a generic resource ACL module.