记录真实报销首跑风险（07-27-yang-jun-reimbursement-readiness）

.trellis/spec/hyb-oa/reimbursement-invoice-ocr.md

@@ -32,6 +32,8 @@ duplicate detection or attachment behavior.
 - Database: `InvoicePool.ocr_provider` is a non-null `OcrProvider` with schema
   default `tencent`; `ocr_attempts`, `ocr_last_requested_at`,
   `ocr_completed_at` and extracted invoice fields carry the execution evidence.
+- Duplicate index: `@@unique([file_sha256, ocr_provider, ocr_type])` partitions
+  the SHA-256 namespace by provider and OCR type.
 
 ### 3. Contracts
 
@@ -47,6 +49,13 @@ duplicate detection or attachment behavior.
   finance checks the PDF original manually. SHA-256 duplicate detection remains
   active; invoice-code/number duplicate detection is unavailable for blank
   metadata.
+- A future nullable/off-provider migration must not change only the stored
+  provider value. Backfill historical rows to one canonical namespace or replace
+  the composite unique key with an intentional file-level uniqueness contract;
+  otherwise the same bytes can be uploaded once before and once after migration.
+- Before changing provider semantics, count historical `mock` rows uploaded by
+  non-test employees. Any such rows need an explicit dedupe/review plan because
+  their provider namespace already differs from current default rows.
 - A config-only provider switch keeps `BUILD_SHA` unchanged. Recreate every
   process that actually loads OCR config: server only when `JOBS_ENABLED=true`
   and no worker exists; server plus worker when an independent worker already
@@ -65,6 +74,8 @@ duplicate detection or attachment behavior.
 - `ocr_provider=tencent` with attempts `0`, null request/completion timestamps
   and null extracted fields -> historical schema-default finding, not evidence
   of a Tencent request.
+- Provider enum/default or unique-key change without backfill/index redesign ->
+  block migration review because it splits the duplicate-detection namespace.
 - Blank metadata cannot bind or submit -> keep the test draft, clean it through
   normal APIs, then plan a code change; do not add an emergency production
   database edit.
@@ -84,6 +95,9 @@ duplicate detection or attachment behavior.
 - Assert upload status is `available` under `OCR_PROVIDER=off`.
 - Assert invoice code, number, date, buyer, seller and all amount fields are
   null; assert attempts are `0` and request/completion timestamps are null.
+- Migration tests for provider semantics must upload identical bytes on both
+  sides of the migration and assert that the second upload is still rejected or
+  reuses the canonical row.
 - Bind to a reimbursement with one valid item, submit through the real workflow,
   return instead of approve, delete the draft and archive the released invoice.
 - Final read-only checks: test accounts archived, active sessions `0`, test