144 lines
4.6 KiB
Markdown
144 lines
4.6 KiB
Markdown
# 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 parties and role labels such as applicant, assignee, reviewer, and owner
|
|
- 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
|
|
|
|
## 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
|
|
- 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 and assignments stored as access subject 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`
|
|
|
|
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.
|