clientflow_backend/docs/document_reconciliation_v2.md

Document Reconciliation v2

After a group is completely classified, opportunity_document_links is the sole authority for document selection. During rollout the canonical resolver uses legacy fields for a whole (opportunity_id, document_kind) group until every legacy document in that group has a current v2 link. It never mixes both authorities inside a group. commercial_documents.opportunity_id, role, is_primary and is_active are dual-write compatibility fields only.

Deployment

1. Deploy this compatibility code first. It can run before migration 007.
2. Run python scripts/preflight_document_reconciliation_v2.py; stop on any blocker.
3. Run python scripts/apply_migrations.py --dry-run and review the pending migration.
4. Run python scripts/apply_migrations.py against the intended database.
5. Keep all consumers on this compatible release. Do not deploy v2-exclusive readers.
6. Dry-run group batches and archive JSON/CSV: python scripts/migrate_document_reconciliation_v2.py --dry-run --batch-size 500 --output-json /safe/path/batch.json.
7. Apply complete group batches. Resume with the emitted composite checkpoint, --resume-from 'OPPORTUNITY_UUID|document_kind'. A group is checkpointed only after all its documents commit.
8. --only-unambiguous still writes REVIEW_REQUIRED links (option B), so groups never become partially invisible. Resolve reviews in the admin UI.
9. Verify no legacy-resolved groups remain, then v2-exclusive readers may be deployed.

Rollback

Rollback application code first and stop every v2 consumer. Export opportunity_document_link_events; confirm all legacy compatibility fields are filled. In a dedicated psql session set clientflow.v2_consumers_active='off' and clientflow.document_ledger_exported='on', then execute migrations/007_document_reconciliation_v2_down.sql. The down migration checks these conditions and removes dependent line columns, trigger/function, events, command claims and links in dependency order. The ledger is lost after export; manual decisions made only in v2 must be reconciled before rollback. Neither migration changes remote Jasmin documents.

CSRF remains separate security debt; this change reuses existing admin authentication and does not claim to add CSRF protection.