40 lines
2.2 KiB
Markdown
40 lines
2.2 KiB
Markdown
# 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.
|