Partner Sign-Off and Final Archiving

The back half of the workflow is three states and two decisions. The analysis is settled and the review is done; what remains is the firm’s formal document, the final sign-off, and the close-out — after which the study is a record, not a working object.

One naming note up front, because it trips people: there is no state called “Partner Sign Off”. The machine runs Report Generated → Document Generated → Signed Off → Archived (app/constants/workflow.py), and those are the labels the UI prints.

What lands in the state

The study arrives at Report Generated when a reviewer approves it and the Excel report task actually stores the workbook — the approval defers the transition for exactly that reason. So every study at this state carries its workbook file id on the record, and nothing else has changed: no user can push a study forward out of Report Generated, because the role list for that state is empty. It is a system leg.

The final document: what produces Document Generated

POST /api/v1/studies/{id}/final-document queues the on-demand document job. It is the partner’s action — Partner, Firm Admin, or Superadmin (FINAL_DOCUMENT_ROLES) — and it is what creates the next state:

• What it builds. The seven-chapter Word master report with its twelve annexures, plus the branded client-facing PDF, from one content stream — the two files cannot disagree on a figure or a chapter. The Word document is the primary artefact; the PDF leg is best-effort — if it fails, the Word document is still stored, the failure is recorded on the job, and the PDF id is simply absent. Treat a missing PDF as “no PDF available”, not as an error.
• What it collects first. The popup takes the engagement details — prepared-by, prepared-for, report date, comparable years, the database used, the search regions, the corporate-background schedules (group entities and shareholding) — and the narrative slots the report engine is allowed to have written for it: purpose of study, company overview, transaction description, and the FAR narrative.
• Where it reads from. The study’s persisted analysis_data and parameters, merged with those engagement fields, with the reviewer’s effective verdicts applied. It is reproducible from the record.
• Where it is allowed. From In Review, Report Generated, Document Generated, Signed Off or Archived — the states with a complete result set. From Draft, Processing, Rejected or Failed it is refused with a 409, and a study with no analysis_data is refused the same way. The report queue is capped at five; a full queue is refused rather than queued silently.
• What it persists. The job runs on the report queue (poll GET /jobs/{id}), then stores report_docx_file_id and, when it succeeded, report_pdf_file_id on the study.

The document does touch the state machine — at two points. The canonical REPORT_GENERATED → DOCUMENT_GENERATED transition is performed by this task, and so is the leg before it when the study has not been approved yet: a document requested at In Review builds the Excel workbook in the same run (a study already holding a workbook is not rebuilt) and records IN_REVIEW → REPORT_GENERATED → DOCUMENT_GENERATED, one audit entry per leg. That is what keeps sign-off reachable — SIGNED_OFF needs Document Generated, and a study left at In Review holding a client-facing document could only get there by spending a second generation. If the workbook leg fails, the Word report is still stored and the state is left alone, with the reason on the job. Once a study is at Document Generated or later, a re-generation overwrites the files and leaves the workflow state exactly where it was. So the document is not a side action on a settled study: producing Document Generated is its job, re-producing it is not.

The mechanics and the engagement fields are in Final Document Generation; the workbook’s own structure is in The Excel Report.

The sign-off decision

Sign-off is available only at Document Generated — the button does not render before the formal document exists, so the practice cannot approve a study it has not yet documented. The decision belongs to Partner, Firm Admin, or Superadmin (a superadmin on the studies they created).

• Sign off — DOCUMENT_GENERATED → SIGNED_OFF, a single audited transition: actor, role, timestamp, notes.
• Send back — not available from here. The reverse transitions the machine allows are In Review → Rejected and Processing → Draft, and nothing else. Once the workbook is built, there is no return leg: a change to the analysis means a new study with its own record, and a change to the deliverable means re-generating the document from the record as it stands. If a partner disagrees with the review, the decision had to be made at In Review, where the reject right also sits with the partner role.

A study with locked_at set cannot be signed off or archived; the lock is the archive, and it is one-way.

Archiving: the close-out

Signing off makes the study ready; archiving closes it. The archive is the narrowest gate in the workflow: Partner or Superadmin only — checked ahead of the role lists, so a Firm Admin may sign a study off and may not archive it. A superadmin’s rights, including this one, are scoped to the studies they created.

The SIGNED_OFF → ARCHIVED transition:

• Sets the lock — locked_at and locked_by are written on the study. From that moment the study accepts no updates; an edit attempt is rejected, not silently ignored, and no transition out of Archived exists (Archived is the one state the machine marks terminal).
• Is audited — the transition, the actor, the role and the timestamp join every other move in the study’s log.

What the archive preserves

Preserved	What it is
The analysis data	The settled statistics, the tested party position, the conclusion, the pool counts — the run’s output as the review left it, including the recomputed figures after committed overrides
The comparable record	Every screened company with its verdict, its reason, and any reviewer override with its audit entry
The parameters	The PLI, the method, the years, the filters, the percentiles — the configuration the run executed
The report files	The Excel workbook, the Word master document and, where the best-effort leg succeeded, the branded PDF — file ids on the study, files in storage
The audit trail	Every transition, the deferred report request, every edit, assignment, override and rejection — the chronology that explains the record

One boundary worth knowing: the raw dump — the normalised source data behind the run — does not ride into the archive as a promise. The report task purges the stored dump as soon as the workbook is uploaded, and any dump still held is bounded by the per-tenant retention window (seven days by default, settable by the firm from one day) measured from the study’s in_review_at. Everything in the table above survives; the raw dump is not in the table. A rebuild that needs the dump needs a re-run — which is the practical argument for generating the deliverables while the study is at Report Generated, not months later.

FAQ

Can anything change after archiving? No. The archived study is immutable: no field edits, no overrides, no transitions. The record is final, and that finality is what the archive exists to provide — a changed study is a new study, with its own record.

Who can archive? Partner, and Superadmin on their own studies. The firm admin carries the document and sign-off rights; the close-out is not among them.

Is the Word report generated automatically at approval? No — and that matters for sequencing. The Excel workbook is the deliverable the workflow builds on approval. The Word master report (and its PDF sibling) is an explicit, engagement-configured action, and until it has run the study is still at Report Generated with no sign-off button.

Can the document be regenerated after sign-off? Yes. The action is permitted from Signed Off and from Archived; it replaces the stored files and leaves the workflow state untouched.

What does the partner see before deciding? The settled results — range, tested party position, conclusion — the comparable record with its final verdicts and rationale, the workbook, and the generated document. The sign-off is made on the record, and the record is complete at this state.