V4 plan created: Adding many-to-many links between Documents & People in the UI. Also adding some new tables for Document Type, Person role.

2026-08-09 13:29:50 -05:00
parent e6549277c6
commit 5753eb0135
13 changed files with 1356 additions and 0 deletions
@@ -0,0 +1,104 @@
+# Error Handling Policy (Version 4)
+
+This document defines canonical error-handling behavior for V4 document-person relationship expansion.
+
+V4 keeps V3 transcription error behavior and adds policy/conflict handling for role extensibility, suggestion lifecycle transitions, and exclusivity enforcement.
+
+## Error Handling Objectives
+
+- Provide clear, actionable conflict and validation feedback for relationship write operations.
+- Prevent partial, silent, or destructive relationship mutations when policy checks fail.
+- Preserve suggestion review auditability with deterministic accept/reject outcomes.
+- Keep consistent API/UI/service error envelopes across relationship workflows.
+
+## Scope and Authority
+
+Governs relationship-related error behavior in:
+
+- NiceGUI document/person relationship views,
+- FastAPI relationship and suggestion endpoints,
+- domain services for relationship sync and suggestion review,
+- persistence constraints for role, state, and exclusivity invariants.
+
+## Relationship Error Taxonomy
+
+| Category | Definition | Retriable |
+| --- | --- | --- |
+| `validation_error` | Payload shape/type invalid, unknown role/state, malformed IDs | no |
+| `not_found_error` | Target `Document`, `Person`, role, or suggestion record does not exist | no |
+| `conflict_error` | Write violates uniqueness or exclusivity policy | no |
+| `suggestion_state_error` | Invalid suggestion transition (for example accept after reject) | no |
+| `policy_violation_error` | Action blocked by configured role matrix or governance rule | no |
+| `infrastructure_transient_error` | Temporary DB or network instability during relationship operation | yes |
+| `infrastructure_persistent_error` | Persistent DB/configuration failure | no |
+| `internal_unexpected_error` | Unhandled exception/logic defect | no |
+
+## Deterministic Conflict Behavior
+
+When relationship writes fail policy checks:
+
+1. Reject the full write operation (no partial apply).
+2. Return structured conflict details including conflicting role pair and target identifiers.
+3. Preserve existing canonical relationships unchanged.
+
+When suggestion transitions fail:
+
+1. Reject invalid state transition.
+2. Return current state and allowed next actions.
+3. Preserve suggestion record integrity.
+
+## API Error Response Contract
+
+Relationship endpoints return a structured envelope:
+
+^^^json
+{
+  "error_id": "err_uuid_12345",
+  "category": "conflict_error",
+  "message": "Role assignment violates exclusivity policy.",
+  "suggestion": "Remove recipient role before assigning author for this person on this document.",
+  "details": {
+    "document_id": "...",
+    "person_id": "...",
+    "attempted_role": "author",
+    "conflicting_role": "recipient",
+    "policy_rule": "author+recipient exclusive"
+  },
+  "timestamp": "2026-08-09T15:00:00Z"
+}
+^^^
+
+HTTP status mappings:
+
+- `validation_error` -> `400`
+- `not_found_error` -> `404`
+- `conflict_error`, `suggestion_state_error`, `policy_violation_error` -> `409`
+- `infrastructure_transient_error` -> `503`
+- `infrastructure_persistent_error`, `internal_unexpected_error` -> `500`
+
+## UI Error Presentation Rules
+
+- Display concise conflict summary with actionable next step.
+- Keep user edits in context (do not discard form state when feasible).
+- Differentiate between validation issues, policy conflicts, and infrastructure failures.
+- For bulk role sync operations, show per-item conflict context when multiple failures occur.
+
+## Logging and Audit Expectations
+
+- Log relationship write failures with correlation IDs.
+- Log suggestion acceptance/rejection outcomes with actor and timestamp where available.
+- Log policy matrix violations with deterministic machine-readable context.
+
+## Relationship-Specific Retry Guidance
+
+- Do not auto-retry policy or conflict failures.
+- Permit user-driven retry only after input changes.
+- Retry infrastructure transient failures with bounded policy in service layer if operation is idempotent.
+
+## Related Local References
+
+- [V4 Scope Boundary](scope_boundary_v4.md)
+- [V4 Requirements](requirements_v4.md)
+- [V4 Schema](schema_v4.md)
+- [V4 Architecture](architecture_v4.md)
+- [V3 Error Handling](../error_handling_v3.md)