Add end-to-end workflow documentation (WORKFLOWS.md)

Practical guide walking the case from intake through closed: per-stage walkthroughs (Intake → Active → Discovery → Pre-Trial → Closed), cross-cutting flows (Documents → e-Sign → e-File, AI agents comparison, time & billing, deadlines, conflict gate, portal access), roles, troubleshooting, menu map. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-30 20:43:10 +00:00
parent 49358183e7
commit 13cf3fe201
1 changed files with 509 additions and 0 deletions
--- a/WORKFLOWS.md
+++ b/WORKFLOWS.md
@@ -0,0 +1,509 @@
+# ActiveBlue Family Law — End-to-End Workflows
+
+How a case moves from intake through final order, what each role does at each
+stage, and which buttons / menus to click. Targets the live build on
+`192.168.2.9:8069`, database `db1`. Florida 11th Circuit (Miami-Dade).
+
+---
+
+## Stage map at a glance
+
+```
+  Intake ─►  Active ─►  Discovery ─►  Pre-Trial ─►  Closed
+    │           │            │             │            │
+    │           │            │             │            └─ archive, bill, retention
+    │           │            │             └─ pretrial stmt, exhibits, witnesses, mediation
+    │           │            └─ interrogatories, production, depositions
+    │           └─ serve, mandatory disclosure (FL 12.932), initial hearings
+    └─ conflict check, questionnaire, fee-waiver assessment
+```
+
+Move stages via the Kanban (drag) or the status bar on the case form. Each
+transition automatically runs the **Paralegal agent**, which (1) generates the
+stage's task batch, (2) recalculates deadlines, (3) cross-references statutes
+to the case's issue tags, and (4) posts a chatter summary.
+
+The case **cannot leave Intake until the conflict-of-interest check passes**
+(or an administrator overrides it with a written justification).
+
+---
+
+## One-time configuration (before your first case)
+
+Settings → Technical → System Parameters:
+
+| Key | Value | Used by |
+|---|---|---|
+| `fl_ai.claude_api_key` | `sk-ant-…` | AI engine, Paralegal agent, Attorney agent |
+| `fl_timesheet.default_hourly_rate` | e.g. `350` | Time & Billing totals when employee has no rate set |
+| `fl_efiling.portal_url` | `https://eportal.flcourts.org` (default) | Open e-Filing Portal button |
+| `web.base.url` | your Odoo base URL | Signing-portal link in emails |
+
+Per-employee: open the employee record, set **Family Law Billing Rate ($/hr)**.
+
+Python dependencies in the container (already required by code paths):
+`anthropic`, `pikepdf`, `PyMuPDF`. Install with
+`docker exec -u root odoo-web-1 pip install anthropic pikepdf PyMuPDF`.
+
+---
+
+## STAGE 1 — Intake
+
+**Goal:** capture parties, screen for conflicts, decide if pro se vs attorney
+referral, assess fee-waiver eligibility, identify legal issues.
+
+### 1.1 Create the case
+
+Two paths:
+
+- **Family Law → Cases → New Case (Intake Wizard)** — guided form covering
+  case type, parties, children, basic facts.
+- **Family Law → Cases → All Cases → New** — direct creation of `fl.case`.
+
+Required at create time: `case_type` and `petitioner_id`. `respondent_id` is
+strongly recommended (drives conflict screening and downstream service).
+
+### 1.2 What the system does automatically on create
+
+1. **Conflict-of-interest check** runs first
+   - Compares petitioner / respondent / party names against parties on every
+     other open case (folded stages excluded).
+   - Exact partner-id match → instant conflict. Otherwise fuzzy match
+     (difflib ≥ 0.85).
+   - Conflict found → red banner on the case, Kanban "Conflict" badge,
+     `conflict_check_passed = False`, **case is locked at Intake**.
+   - Clear → `conflict_check_passed = True`, case can advance.
+
+2. **Project auto-created** with case-type task templates.
+
+3. **Paralegal agent** generates the Intake task batch:
+   - Run conflict-of-interest check (the audit record)
+   - Complete client intake questionnaire
+   - Assess fee-waiver eligibility (FL 57.082)
+
+4. **Fee waiver eligibility** computed quickly from petitioner income vs
+   200% FPL; chatter note if eligible.
+
+5. **DV flag** (if set) posts a safety banner with mediation/representation
+   guidance and the Miami DV hotlines, forces `attorney_referral_flag`.
+
+### 1.3 Resolving a flagged conflict
+
+Open the conflict check record from the case's "Conflict of Interest" group
+(Parties tab) or via **Cases → Conflict Checks**.
+
+- Review the match list and similarity scores.
+- If proceeding is safe, an **administrator** writes a justification and
+  clicks **Override Conflict** → state becomes "override",
+  `conflict_check_passed = True`, audit entry posted to chatter.
+- Never silently pass a conflict — the override leaves a permanent record.
+
+### 1.4 Fill in the questionnaire (Parties tab)
+
+For each party (One2many "Party Details"):
+
+- Employment type and gross monthly income.
+- Statutory deductions (federal tax withholding, mandatory retirement,
+  health insurance self-only, other court-ordered support) → Odoo computes
+  net monthly income per FL 61.30(3).
+- **Income imputation** (FL 61.30(2)(b)) if voluntarily un/under-employed —
+  set `income_imputed`, an imputed amount, and document the basis.
+- **Lifestyle inconsistency** flag if income vs lifestyle is suspect
+  (Barner v. Barner) — Attorney agent will incorporate this.
+
+### 1.5 Run the AI passes
+
+- **Paralegal Review** (header button) — Claude procedural briefing
+  (best-effort; falls back to a rule-based summary if the API is unavailable).
+  Useful to see "what should we be doing now?" at any time.
+- **AI tab → Generate Attorney Strategy Memo** (admin) — substantive memo.
+  Identifies the top 3–5 statutes and case law (from the seeded library only,
+  no hallucinated citations), drafts petitioner arguments, opposing
+  counterarguments, procedural risks, and a substantial-change assessment for
+  modifications. Stored as `fl.analysis` of type "attorney", linked from
+  `case.attorney_memo_id`.
+
+### 1.6 Advance to Active
+
+Drag the case to **Active** on the Kanban (or click the status bar). If
+`conflict_check_passed` is still False you'll get a blocking error — go back
+and resolve the conflict.
+
+---
+
+## STAGE 2 — Active
+
+**Goal:** serve the respondent, exchange mandatory disclosure, schedule the
+initial hearings, generate and file the petition.
+
+### 2.1 Automatic on stage entry
+
+Paralegal agent generates the Active task batch:
+
+- Effect service of process
+- Serve mandatory disclosure (FL-12.932) within 45 days of service
+- Schedule initial hearings (case management, temporary relief)
+
+### 2.2 Filing date and service date drive deadlines
+
+Set `filing_date` on the case → deadline engine generates filing-anchored
+deadlines (30-day target service, 120-day FL 1.070 max service, parenting
+class for petitioner if minor children).
+
+Set `service_date` → service-anchored deadlines are generated/recalculated:
+
+| Deadline | Offset | Statute |
+|---|---|---|
+| Respondent answer due | service + 20 days | FL 1.140 |
+| Mandatory disclosure exchange | service + 45 days | FL 12.285 |
+| Certificate of mandatory disclosure | service + 45 days | FL 12.932 |
+| Discovery opens | service + 20 days | FL 12.280 |
+| Respondent parenting class | service + 60 days | FL 61.21 |
+
+Each `fl.deadline` syncs to a `calendar.event` (visible in the case's
+Deadlines tab and on the user's calendar). Daily cron sends 7/3/1-day and
+overdue alerts to the case chatter.
+
+### 2.3 If respondent doesn't answer by day 20
+
+A daily cron (FL 12.922 / FL 1.500) automatically:
+
+1. Creates a "File Motion for Default" deadline (5 days out).
+2. Adds an urgent project task with filing instructions.
+3. Posts a "DEFAULT JUDGMENT WINDOW OPEN" alert to the case chatter.
+
+### 2.4 Generate and file court documents
+
+Each case document maps to a QWeb PDF report:
+
+| Document | Form | Menu / Action |
+|---|---|---|
+| Financial Affidavit (Short) | FL-12.902(b) | Reports → on `fl.document` |
+| Financial Affidavit (Long) | FL-12.902(c) | "" |
+| Child Support Worksheet | FL-12.902(e) | "" |
+| Motion to Modify | — | "" |
+| Notice of SSN | FL-12.930(a) | "" |
+| Mandatory Disclosure Certificate | FL-12.932 | "" |
+| Notice of Deposition | — | "" |
+| Motion to Compel | FL 1.380 | "" |
+| Income Withholding | FL 61.1301 | "" |
+| Parenting Plan | FL-12.995(a) | "" |
+| Application for Civil Indigent Status | FL 57.082 | "" |
+| Motion for Default | FL 12.922 | "" |
+
+To get a signed, filed PDF, use **Filings tab → Request Signature** then
+**Prepare e-Filing** (full walkthrough in *Cross-cutting flows: Documents → 
+e-Sign → e-File* below).
+
+### 2.5 Fee waiver application
+
+If the case shows "Fee Waiver Potentially Eligible" (200% FPL test), open the
+Fees & Expenses tab → **Create Fee Waiver Application**. Complete household
+size and income; eligibility is computed against the FL 57.082 threshold and
+the document flows through draft → submitted → approved/denied. Generate the
+QWeb PDF and file with the clerk.
+
+### 2.6 Move to Discovery when ready
+
+Drag to **Discovery** when initial service + mandatory disclosure are in
+hand and you need formal discovery. Typically also after the Attorney agent
+has rated complexity as `medium` or higher.
+
+---
+
+## STAGE 3 — Discovery
+
+**Goal:** Interrogatories, requests for production, depositions, motions to
+compel as needed.
+
+### 3.1 Automatic on stage entry
+
+Paralegal agent generates the Discovery task batch:
+
+- Draft interrogatories
+- Draft requests for production
+- Schedule depositions where income or facts are disputed
+
+### 3.2 Discovery Suggest wizard
+
+From the case → **Run Discovery Suggest Wizard** (or Cases → Discovery →
+specific tools). The wizard reads:
+
+- Case's issue tags (`issue_tag_ids`)
+- Complexity (from the latest analysis or rule-based fallback)
+- Active flags (DV, income imputation, respondent has counsel)
+
+…and proposes a tailored discovery package: interrogatory sets directed to
+the opposing party, document requests, deposition notices, third-party
+subpoenas (e.g., employer when income is disputed).
+
+Each selected line creates an `fl.discovery` item linked to the case. The
+wizard posts a chatter summary of everything generated.
+
+### 3.3 Discovery items lifecycle (`fl.discovery`)
+
+- States: draft → served → responded → complete (or → motion-to-compel /
+  deemed-admissions when overdue).
+- 30-day response clock from service; **daily cron** fires alerts for overdue
+  responses and flags admissions deemed under FL 1.370 when the deadline lapses.
+- Track objections and motion-to-compel status per item.
+
+### 3.4 Depositions (`fl.deposition`)
+
+- States: draft → noticed → confirmed → completed (or cancelled / no-show /
+  continued).
+- **Notice validity** is computed (FL 1.310(b): ≥10 days notice). Search
+  filters expose "Invalid Notice" — fix before serving.
+- Duces tecum (document subpoena): tracked separately.
+- Generate the Notice of Deposition PDF and route through e-Sign / e-File.
+
+### 3.5 Move to Pre-Trial
+
+When discovery is essentially closed (responses in, depositions taken or
+waived), advance the stage.
+
+---
+
+## STAGE 4 — Pre-Trial
+
+**Goal:** Pretrial statement, exhibits, witnesses, mediation, support
+calculation, parenting plan, threshold test for modifications.
+
+### 4.1 Automatic on stage entry
+
+Paralegal agent generates the Pre-Trial task batch:
+
+- Prepare pretrial statement
+- Compile exhibit list
+- Compile witness list
+- Schedule mediation (separate rooms if DV flagged — FL 44.102)
+
+### 4.2 Child support calculation (FL 61.30)
+
+Open **Case → Open Calculator** (or AI tab → Calculator stat button).
+
+- Pulls petitioner / respondent effective monthly income (uses imputed if set).
+- Children, day-care, health insurance for children, tax exemption assumptions.
+- **Substantial timesharing** kicks in when either parent has > 73 overnights
+  (FL 61.30(11)(b)) — automatically detected from `petitioner_overnights`.
+- Result → `case.calculated_support`.
+
+For **modifications**, the Support tab also runs the threshold test
+(FL 61.30(1)(b)): change must be both ≥ $50 AND ≥ 15%. The case shows a clear
+"QUALIFIES" / "DOES NOT QUALIFY" panel with the math.
+
+### 4.3 Mediation scheduling
+
+Add `fl.hearing` of type "Mediation" (Hearings tab). If `domestic_violence_flag`
+is set, you get a separate-rooms reminder. Court-ordered mediation is the
+default in family law cases (FL 44.102).
+
+### 4.4 Pretrial statement, exhibit and witness lists
+
+Use the project tasks generated by the paralegal agent as the checklist.
+Documents and exhibits go through the standard Documents → e-Sign → e-File
+flow.
+
+### 4.5 Move to Closed when the final order is entered
+
+---
+
+## STAGE 5 — Closed
+
+**Goal:** Capture the new order, generate income withholding, reconcile
+billing, archive the case, send retention notice.
+
+### 5.1 Automatic on stage entry
+
+Paralegal agent generates the Closed task batch:
+
+- Complete archive checklist
+- Reconcile billing
+- Send file retention notice
+
+### 5.2 Post-order: income withholding (FL 61.1301)
+
+Set `new_order_amount` and `new_order_date` on the case → an
+`fl.income.withholding` record is auto-created (mandatory under FL 61.1301
+unless good cause or written agreement). Generate the Income Withholding PDF
+and serve.
+
+`retroactivity_date` is computed = `filing_date` (FL 61.30(17)).
+
+### 5.3 Reconcile billing
+
+Time & Billing tab shows:
+
+- `total_billable_hours` — sum of billable timesheet entries
+- `total_billable_amount` — billable hours × rate
+- `total_ai_audit_hours` — non-billable AI agent time (for audit trail)
+
+Add manual time entries inline (date, who, hours, description, billable).
+The wrapped `account.analytic.line` records flow into standard Odoo
+Accounting for invoicing.
+
+### 5.4 File retention notice
+
+Use the Document workflow to generate a closing letter to the client with
+the retention/destruction policy.
+
+---
+
+## Cross-cutting flows
+
+### A. Documents → e-Sign → e-File
+
+The "paperwork pipeline" — every court document follows the same path.
+
+1. **Generate** the document. From the case Documents area (Filings tab or
+   `fl.document` form), pick the document type (e.g., Financial Affidavit
+   Long). Use **Print → [Report]** to render the QWeb PDF, or the document
+   auto-renders when a signature request is created.
+
+2. **Request Signature** (Filings tab → "Request Signature" button). On the
+   `fl.signature.request` form:
+   - Pick the document and signer (`signer_partner_id`).
+   - Click **Render PDF** to generate the unsigned PDF (or skip — clicking
+     "Send to Signer" will render automatically).
+   - Click **Send to Signer**. An email goes out with a one-time link
+     `https://<your-host>/familylaw/sign/<token>` (token is 256-bit; expires
+     in 14 days; cron sweeps expired links hourly).
+
+3. **Signer signs** at the portal page (no login required):
+   - The unsigned PDF is shown in an iframe.
+   - The signer draws on the HTML5 canvas pad (mouse/trackpad/finger).
+   - "Submit Signature" posts the PNG to the server; PyMuPDF embeds it at
+     the per-report `_SIGNATURE_COORDS` rectangle.
+   - The signed PDF is attached to the `fl.document` (state → "signed"); the
+     request state → "signed"; case chatter logs the event with signer IP.
+
+   The signer can also Decline with an optional reason; the request closes.
+
+4. **Re-validate PDF/A** on the signed PDF (signature form has a button) if
+   it's bound for e-filing. Uses the same `pikepdf` check as the e-Filing
+   model.
+
+5. **Prepare e-Filing** (Filings tab → "Prepare e-Filing"). The wizard:
+   - Picks the signed PDF (or any attachment).
+   - Generates the 11th Circuit-compliant filename:
+     `{LastName}_{CaseNumber}_{DocType}_{YYYYMMDD}.pdf`.
+   - Auto-validates PDF/A.
+
+6. **Submit on the FL e-Filing Portal**. From the `fl.efiling.submission`
+   form:
+   - Click **Open e-Filing Portal** — opens `eportal.flcourts.org` in a new
+     tab, deep-linked with the case number if available.
+   - Upload the signed PDF on the portal, complete the filing, copy the
+     portal confirmation #.
+   - Back in Odoo, paste the confirmation # and click **Mark Submitted**.
+   - When the clerk acts, click **Clerk Accepted** (which also marks the
+     `fl.document` as filed) or **Clerk Rejected** (note the reason).
+
+The Submit via API button is reserved for Phase 2 and currently refuses to
+call any unconfirmed endpoint — assisted submission is the supported flow.
+
+### B. AI agents — when to use which
+
+| Agent | Trigger | What it produces | Cost |
+|---|---|---|---|
+| **Paralegal — auto** | Every stage transition (including case creation) | Stage task batch, deadline recalc, statute cross-ref, rule-based chatter summary | No AI call |
+| **Paralegal — manual** ("Paralegal Review" button) | On demand | Same as above + Claude procedural briefing | 1 Claude call |
+| **AI Engine** ("Run AI Analysis" header → wizard) | On demand | Rule-based issue tagging + caselaw matching + Claude case-summary analysis (`fl.analysis` type `engine`) | 1 Claude call |
+| **Attorney — manual** (AI tab → "Generate Attorney Strategy Memo") | On demand, admin | Substantive strategy memo: top 3–5 statutes (linked to `fl.statute`), top 3–5 case law (linked to `fl.caselaw`), petitioner arguments + opposing counterarguments, risk narrative, substantial-change assessment, attorney-referral flag | 1 Claude call (longer prompt) |
+
+All agents log non-billable audit time to `fl.timesheet` (`ai_agent` field
+identifies which agent) and fall back to rule-based output if Claude is
+unavailable. AI failures never block the user workflow.
+
+### C. Time & Billing
+
+- **Manual entry**: Case → Time & Billing tab → add row. Date, employee,
+  hours, billable flag, description.
+- **AI audit time**: posted automatically by each agent run (paralegal ~0.05h
+  AI / 0.01h rule-based; attorney ~0.1h AI / 0.02h fallback). Marked
+  non-billable; visible in the same tab and on the **Cases → Timesheets**
+  list (filter: AI Audit).
+- Rate resolves to `hr.employee.fl_hourly_rate` (per person) or the firm
+  default param.
+- Each timesheet entry wraps an `account.analytic.line`, so it shows up in
+  Odoo Accounting and flows into invoicing in the usual way.
+
+### D. Deadlines & calendar
+
+- Defined in `fl.deadline`; each one syncs to a `calendar.event` (default 1h
+  block at 08:00).
+- Decoration in the Deadlines tab: red for overdue, yellow for ≤ 7 days.
+- Daily cron posts 7-day, 3-day, 1-day, and overdue alerts to the case chatter.
+- The case header shows "Next Deadline" and "Overdue Deadlines"; the Kanban
+  card shows the count.
+
+### E. Conflict-of-interest gate
+
+- Runs on case creation. Also accessible via header **Run Conflict Check**.
+- Admin override only, with a written justification (audit-logged).
+- Visible globally under **Cases → Conflict Checks** (default filter: open
+  conflicts).
+
+### F. Portal access (clients)
+
+Petitioner / respondent users (groups `group_portal_petitioner` /
+`group_portal_respondent`) can sign in and see:
+
+- `/my/cases` — their case(s)
+- `/my/cases/<id>` — case detail with deadlines and timeline
+- `/my/cases/calculator` — interactive FL 61.30 calculator
+- `/my/cases/caselaw` — searchable FL case law library
+
+To grant portal access, on the party record (Parties tab → party row) link a
+`partner.user_ids` to that party's partner.
+
+---
+
+## Roles — who does what
+
+| Role | Group | Typical day |
+|---|---|---|
+| Admin / Attorney | `group_admin` | Open Attorney Strategy Memo; review/override conflicts; review filings before submission; review billing |
+| Paralegal | `group_paralegal` | Drives the case stage-by-stage; runs Paralegal Review for procedural questions; manages discovery, depositions, deadlines; prepares court documents, signatures, filings; logs billable time |
+| Portal Petitioner | `group_portal_petitioner` | Sees own case; signs court documents on the portal page when sent a link |
+| Portal Respondent | `group_portal_respondent` | Sees own case (read-only beyond their party record) |
+
+---
+
+## Quick troubleshooting
+
+| Symptom | Where to look |
+|---|---|
+| Can't move case past Intake | Conflict check failed — open the conflict record, admin override with justification |
+| "anthropic not installed" / no AI summary | `pip install anthropic` in `odoo-web-1`; set `fl_ai.claude_api_key` system parameter |
+| Signature page errors | `pip install PyMuPDF`; check `web.base.url` is set so the email link is correct |
+| PDF/A check always warns | Source PDFs are not PDF/A-compliant — wkhtmltopdf output is plain PDF. Run them through a PDF/A converter (e.g., Ghostscript `pdfa.ps`) before signing/filing if the clerk rejects them. The pikepdf check is pragmatic (markers + OutputIntents), not full veraPDF conformance. |
+| e-Filing API button errors | By design — confirm portal endpoint, set `fl_efiling.api_endpoint`, then Phase 2 work is needed to wire real submission. Until then, use Open Portal + Mark Submitted. |
+| Paralegal agent fires twice on Intake | Once from `create()`, once from the first stage-write. Tasks are idempotent (same-name guard) so no duplicates are actually created. |
+| Deadline alerts not firing | Check **Settings → Technical → Scheduled Actions** for "FL Family Law: Daily Deadline Alerts" — `active = True`, last run within 24h |
+
+---
+
+## Reference: menus
+
+```
+Family Law
+├── Cases
+│   ├── All Cases
+│   ├── New Case (Intake Wizard)
+│   ├── Deadlines
+│   ├── Hearings
+│   ├── Depositions
+│   ├── Discovery
+│   ├── Conflict Checks
+│   ├── Timesheets
+│   ├── e-Filings
+│   └── Signature Requests
+├── Support Calculator
+│   ├── Calculations
+│   └── FL DCF Schedule  (admin)
+├── Case Law Library
+└── Configuration  (admin)
+    ├── FL Statute Index
+    └── Issue Tags
+```