Skip to main content

PRD-007: Case Workflow — Consulta do Processo (File Inspection)

Author: MLT backend team | Date: 2026-08-19 | Status: Draft | Version: v0.1.0

Revision History​

VersionDateAuthorDescription of Change
v0.1.02026-08-19MLT backend teamInitial draft — fourth phase (thin), backfilled from the rebuild roadmap (interim PRD).

1. Context & Business Rationale​

Consulta do Processo (CONSULTATION_PORTAL, a thin phase) gives the arguido and their counsel access to the case file so they can prepare a defence — disponibilização dos autos. Access happens through the external token portal within a visibility window, is logged (registo de acesso), and certidões (certified copies) can be issued on request.

Part of the Case Workflow theme (theme: case-workflow, label workflow: consulta do processo (4/8)). Consumes the external portal capability (E08).

Sourcing: the firm brief (_poc/firm-qa.md). PoC autopsy: portal flow.

2. Problem Statement​

The arguido has a right to inspect the file, but there is no server-side way to expose selected items to an external party within a bounded window, log who accessed what, or issue certified copies.

3. Goals, Non-Goals, and Success Metrics​

3.1 Goals​

  • Expose selected case items to the arguido/counsel within a visibility window.
  • Log every portal access (actor + timestamp).
  • Issue certidões/copies on request, themselves audited.

3.2 Non-Goals​

  • The external portal mechanism itself (E08 — this phase consumes it).
  • The arguido's written defence (5–6/8).

3.3 Success Metrics​

Metric TypeMetric DefinitionBaselineTarget
PrimaryFile made inspectable to the arguido within a bounded windowPoC: ad hoc100% windowed
Guard RailAccess outside the windowPoC: uncontrolledDenied

4. User Personas & Actors​

4.1 Arguido / counsel (Primary, external)​

  • Role: inspect the disclosed case file through the portal; may request certidões.

4.2 Case Manager (Secondary)​

  • Role: selects which items are disclosed and the visibility window.

5. User Stories​

  • As a case manager, I want to disclose selected case items to the arguido/counsel through the portal within a visibility window, so they can inspect the file lawfully. → #61
  • As the arguido/counsel, when I consult a disclosed item the system records that consultation server-side, so the registo de acesso is a trustworthy legal record. → the consultation command lives in the External Portal (E08); the firm reads the log back via #112.
  • As a case manager, I want certidões (certified copies) issuable on request and themselves audited. → #62

6. System Requirements​

6.1 Disclosure​

  • SYS-REQ-101: Selected case items shall become visible to the invited party within the window.
  • SYS-REQ-102: Items outside the window shall not be accessible.

6.2 Access log & certidões​

  • SYS-REQ-201: Each portal consultation by the arguido/counsel shall be recorded in a server-owned DB log (not web analytics) with actor + item + timestamp.
  • SYS-REQ-202: The consultation shall be modelled as a command (it is a legally recordable act that mutates state), not a query. Shape (same as the dossier export): POST …/consultations {itemId} authorizes (token + disclosed-to-party #61 + in-window), records the access, and returns a single-use reqId; GET …/consultations/{reqId}/content is a pure query that streams the bytes. The access row is written at the POST — invariant logged-iff-granted. Internal reads (the firm browsing the case in the admin app) stay pure queries. The POST command lives in the External Portal epic (E08); the firm reads the log via GET /access-log (#112).
  • SYS-REQ-203: A certidão/copy shall be issuable on request (for an item disclosed to the party) and shall itself be audited.

7. Workflow​

(from Nota de Culpa served)
        │
        ▼
CONSULTATION_PORTAL ── disclose items { itemIds, visibleFrom, visibleUntil? }   (#61)
        │
        ├─ POST /consultations { itemId }  (command, E08)
        │     guard: token +OTP · disclosed to party · in-window
        │     → record access (actor, item, at) + return { reqId }   [logged-iff-granted]
        │     GET /consultations/{reqId}/content  (query) → stream bytes
        ├─ certidão requested → issued + audited   (#62)
        │
        └─ firm reads registo de acesso ── GET /access-log   (#112)
        ▼
RESPONSE_WINDOW  (phase 5/8)

8. Open Questions​

  • Resolved (2026-08-19): access log vs analytics → first-class server-owned DB log, not Google Analytics. GA is anonymous, off-system, and has no retention guarantee, so it cannot be the legal record of the right of defence. The consultation is modelled as a command that records the access at the authorizing POST (see SYS-REQ-202); the firm reads it back via #112.

9. Edge Cases & Exception Handling​

  • Access attempt after visibleUntil — denied.
  • Certidão requested for an item not disclosed to the party — rejected.

10. Given-When-Then Acceptance Criteria​

Make the case file visible via the portal (#61)

  • Selected case items become visible to the invited party within the window.
  • Items outside the window are not accessible.

Log access + issue certidões (#62)

  • Each access by the arguido/counsel is logged with actor + timestamp.
  • A certidão/copy can be issued and is itself audited.

11. Technical Constraints & Dependencies​

  • Blocked by: "Notify the arguido + proof of receipt" (3/8) and the External portal (E08, not yet cut).
  • Access/certidão auditing writes into the shared audit ledger (#44).