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

Reimbursement / Invoice / OCR

Source Docs

Read docs/报销发票附件规则.md before changing reimbursement, invoice, OCR, duplicate detection or attachment behavior.

Rules

• PDF invoice OCR is the maintained main path.
• Image OCR remains frozen unless a later Trellis task explicitly reopens it.
• Do not write raw invoice images, sensitive form values or full OCR payloads to repo docs, Issue CSV, Trellis task files or chat.
• Reimbursement flow tests should cover upload/OCR, duplicate handling, submission, approval, payment batch, receipt attachment and AP export when the Trellis task scope touches those areas.

Scenario: Payment Batch Receipt Attention Count

1. Scope / Trigger

• Trigger: payment list pages need a first-screen 待补回单 metric without loading or exposing every receipt attachment.
• Applies to payment batch list/detail APIs and the PC 付款 page.

2. Signatures

• GET /api/payment-batches returns each batch with receiptAttachmentCount: number.
• GET /api/payment-batches/:id returns the same field on data.item.
• The count comes from Prisma _count.receipt_attachments; the list response must not include receipt file names, hashes, storage paths or download URLs.

3. Contracts

• Only users who can read payment batches may receive the count.
• Frontend 待补回单 is list-level attention: batch status is reviewed or failed, at least one pending/failed item resolves to bank channel, and receiptAttachmentCount is 0.
• Receipt preview, upload, delete and download stay in the selected batch detail panel and continue to use receipt attachment endpoints with their own permission, governance and audit checks.

4. Validation & Error Matrix

• payment_batch_v1 disabled -> existing 409 VALID_001.
• Reader lacks batch permission -> existing 403 PERM_001.
• Count missing from an older mocked payload -> frontend treats it as 0 for backward-compatible tests, but real backend responses should include it.

5. Good/Base/Bad Cases

• Good: a reviewed bank batch with no receipt contributes 1 to 待补回单.
• Base: a reviewed bank batch with uploaded receipt contributes 0.
• Bad: counting only the currently selected batch, which hides missing receipts elsewhere in the list.

6. Tests Required

• Server focused route tests when payment batch mapping changes.
• cd client && npm run typecheck && npm run build.
• Focused Playwright around 付款, 应付账款, 票据 and finance ledger tools.

7. Wrong vs Correct

Wrong

const selectedNeedsReceipt = selectedBatch && selectedReceiptCount === 0 ? 1 : 0;

Correct

const needsReceipt = batches.filter((batch) =>
  ["reviewed", "failed"].includes(batch.status) &&
  (batch.receiptAttachmentCount ?? 0) === 0 &&
  batch.items.some((item) => (item.paymentChannelOverride ?? batch.defaultPaymentChannel) === "bank"),
).length;