Skip to main content

PRD-010: Case Workflow — Relatório Final e Decisão (Final Report & Decision)

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 — eighth/terminal phase, backfilled from the rebuild roadmap (interim PRD). Decision gate + outcome + close merged into one transactional slice.

1. Context & Business Rationale​

The terminal phase (FINAL_REPORT → CLOSED): the instructor drafts the Relatório Final with a proposed sanction, then the assigned decider approves it at the single enforced gate — which in one transactional act sets the outcome, closes the case, and triggers notification of the arguido and representative structures.

Part of the Case Workflow theme (theme: case-workflow, label workflow: relatório final (8/8)). This is the one phase whose gate is unconditionally enforced (a case cannot reach CLOSED without it).

Sourcing: the firm brief (_poc/firm-qa.md). PoC autopsy: outcomes & proposal, conditional branching, phase deadlines.

2. Problem Statement​

There is no server-side way to produce a reasoned final report, enforce that only the assigned decider can close the case, validate justa causa on a dismissal, or make setting-the-outcome-and-closing a single atomic act with notifications that fire only on commit.

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

3.1 Goals​

  • Produce the Relatório Final deliverable (proven/unproven facts, proportionality, fundamentação, proposed sanction).
  • Enforce the decision gate (assigned decider only), validate justa causa on an expulsive outcome.
  • Set the outcome, transition to CLOSED, and notify — all in one transactional commit.

3.2 Non-Goals​

  • The dossier export (shared epic).
  • The sanction enum's final membership (tracked as an open question here, resolved with counsel).

3.3 Success Metrics​

Metric TypeMetric DefinitionBaselineTarget
PrimaryCase closed only via an authorized, reasoned decisionPoC: bypassable100% gated
Guard RailClose without the decider gatePoC: possibleImpossible
Guard RailOutcome set / close / notify partially appliedPoC: non-atomicOne transaction

4. User Personas & Actors​

4.1 Instrutor (Primary)​

  • Role: drafts the Relatório Final and proposes the sanction.

4.2 Decider / decider role (Primary)​

  • Role: the only actor who can approve the decision and close the case.

4.3 Arguido + representative structures (notified)​

5. User Stories​

  • As an instrutor, I want to produce the Relatório Final (proven/unproven facts, proportionality, fundamentação, proposed sanction), so the decider has a reasoned basis to decide. → #87
  • As the decider, I want to approve (or reject) the decision at the single enforced gate — where approval sets the outcome, closes the case transactionally, validates justa causa on a dismissal, and notifies the arguido + representative structures on commit — so the closure is lawful and atomic. → #91

6. System Requirements​

6.1 Final report​

  • SYS-REQ-101: The Relatório Final shall generate via the deliverable mechanism with escaped fields.
  • SYS-REQ-102: It shall carry a proposed outcome from the sanction set.

6.2 Decision gate & close​

  • SYS-REQ-201: Only the assigned decider shall approve; others 403.
  • SYS-REQ-202: A case shall not transition to CLOSED without this gate approved.
  • SYS-REQ-203: On an expulsive outcome, justa causa shall be affirmed.
  • SYS-REQ-204: Setting the outcome and closing shall be one transactional transition to CLOSED; notifications shall fire on commit (a reject returns for redraft, not closure).
  • SYS-REQ-205: The 30-day post-evidence decision clock shall be tracked and surfaced.

7. Workflow​

(from Evidence phase / Pareceres)
        │
        ▼
FINAL_REPORT ── draft Relatório Final { facts, proportionality, fundamentação, proposedOutcome }
        │
        ▼
decision gate (decider only, 403 others)
        ├─ reject ──► back for redraft
        └─ approve ─► set outcome ∈ {Arquivado|Advertência|Suspensão|Despedimento|Outro}
                       (justa causa affirmed if expulsive)
                       → CLOSED  [one transaction]
                       → notify arguido + representative structures (on commit)

8. Open Questions​

  • Sanction ladder. The set (Arquivado/Advertência/Suspensão/Despedimento/Outro) may be a simplification — confirm against the CT's full ladder (e.g. repreensão registada, perda de dias de férias, multa) with counsel before freezing the enum.

9. Edge Cases & Exception Handling​

  • Non-decider attempts approval → 403.
  • Decision after the 30-day clock — surfaced; confirm the legal consequence with counsel.
  • Reject → redraft loop, case stays open.

10. Given-When-Then Acceptance Criteria​

Draft the final report (#87)

  • The final report generates via the deliverable mechanism with escaped fields.
  • It carries a proposed outcome from the sanction set (pending counsel confirmation of the full ladder).

Decide the case & close (#91)

  • Only the assigned decider can approve; others get 403.
  • A case cannot transition to CLOSED without this gate approved.
  • On an expulsive outcome, justa causa must be affirmed.
  • Setting the outcome and closing is one transactional transition to CLOSED; notifications fire on commit.
  • The 30-day decision clock is tracked and surfaced.
  • The arguido and representative structures are notified of the decision.

11. Technical Constraints & Dependencies​

  • Blocked by: the evidence phase (5–6/8) and, when triggered, the mandatory opinions (7/8); case-role authorization (Tenancy & RBAC #26) for the decider gate.
  • Reuses the deliverable mechanism and the E15 domain-event handlers (notifications on commit).