Savings And Audit Determinism

Savings/audit is the first-priority LeafEnterprise product lane. The backend must fully automate the manual savings analysis and claims audit workflow while preserving calculation lineage and workbook deliverable readiness.

LeafEnterprise owns this lane end to end. Frontend pages, Domo-facing dashboards, AI assistants, workbook exports, and PDFs must all consume the same backend scope and evidence posture.

Authority Model

Area	Authority
Scope	Backend-resolved client_context, not browser query fallbacks.
Queueability	Governed run plan and exact scope resolution.
Report data	SQL-backed report context plus governed packets.
AI optimization	Deterministic recommendation engine first, Azure OpenAI module copilot second.
Workbook	LeafEnterprise/report_workbook.py and GET /api/client-report-xlsx.
Dashboard payload	Backend-produced report/context/optimization payloads, not Domo formulas.

Reproducible Run Contract

Every savings/audit run must be explainable by this chain:

flowchart LR
  ITR[ITR or operator request] --> Scope[Resolved run scope]
  Scope --> Rows[Source rows and filters]
  Rows --> Math[Named formulas]
  Scope --> Evidence[Contract/rebate/pricing evidence status]
  Math --> Report[Report payload]
  Evidence --> Report
  Report --> Dashboard[Scoped dashboard]
  Report --> Workbook[Workbook/PDF]
  Report --> Optimization[AI Optimization]

If any link is missing, the backend should return a blocked or partial state. It should not fill gaps with Domo values, AI guesses, prior workbook formulas, or zeroes that look like valid business values.

Determinism Rules

• Do not silently fan out an ITR across multiple queueable scopes.
• Require one exact governed scope before queueing, export, or final ITR-governed workbook delivery.
• Preserve source_request_number, selected_scope_key, and selected_scope_kind through Savings, AI Optimization, workbook export, and optimization PDF export.
• Treat workbook export quality as a deliverable contract, not just a file-generation success.
• Keep deterministic recommendation and action previews available even when AI provider calls fail.
• Publish dashboard payloads from backend scope and evidence status; do not let the dashboard recompute savings or merge scopes.
• Return explicit blocked, partial, candidate_only, or modeled_with_gaps states when evidence cannot support final claims.

Dashboard And Deliverable Parity

The scoped dashboard, interactive report, workbook export, PDF export, and optimization payload must agree on the same:

Contract	Required parity
Scope	PBM, TPA/broker, group, date window, run id, and source request.
Metrics	Source rows and named formulas used for top-line totals and segmentations.
Evidence	Contract, pricing, rebate, packet, Domo, and Salesforce states.
Readiness	Whether outputs are final, partial, blocked, or candidate-only.
Lineage	Trace ids, queue ids, run ids, source record ids, and artifact ids when available.

The frontend can choose presentation density, but it must not change these facts.

Key API Surfaces

Route	Role
GET /api/client-report	Interactive report payload.
GET /api/client-report/context	Authoritative report context, run lineage, AI handoff, workbook export posture.
POST /api/client-report/queue	Internal queue-refresh path for a governed savings/audit scope.
GET /api/optimize	Evidence-first AI optimization payload.
GET /api/client-report-xlsx	Final workbook artifact lane.

Validation

Use focused tests for the changed behavior, then validate the report/export route:

python -m pytest tests/test_report_workbook.py tests/test_pocket_consultant.py
python scripts\smoke_client_portal.py --base-url http://127.0.0.1:8787