R121/A1-A6 沉淀Agent交付文档和Skill

docs/reimbursement-invoice-rules.md

@@ -0,0 +1,116 @@
+# 报销、发票与附件规则
+
+本文是 hyb-oa 报销主链路的业务事实源，面向 10 人以下国内科技公司。目标是让员工少选项、财务少核错、管理员少配置。
+
+## 总原则
+
+- PC 与手机功能一致，只允许布局和控件形态不同。
+- 普通员工看到的是“添加发票”“上传附件”“提交审批”，不看到“绑定整单”“发票池”“ERP 同步”等内部概念。
+- 发票是报销凭证，附件是补充材料，二者不能混用。
+- 已经报销、他人已报销、重复上传的发票不能加入新的报销单。
+- 服务端必须强约束，前端只负责友好提示。
+
+## 发票状态
+
+发票主要状态：
+
+- `pending_ocr`：已上传，正在识别。
+- `available`：可添加到报销单。
+- `bound`：已添加到报销单。
+- `ocr_failed`：识别失败，需要重试或人工处理。
+- `archived`：已归档，不可添加；若 `archived_reason=used_complete`，视为已报销。
+
+前端展示时使用中文业务表达：
+
+- `pending_ocr`：识别中。
+- `available`：可添加。
+- `bound`：已添加。
+- `ocr_failed`：识别失败。
+- `archived`：已归档或已报销。
+
+## 上传与 OCR
+
+- PDF 和图片均可上传；若走腾讯 OCR，PDF 可先转图片再识别，具体实现以当前 OCR provider 能力为准。
+- 上传后页面必须显示明确状态，不应长期停留在“上传中”。
+- OCR 完成后，添加发票弹窗应自动刷新并尝试添加可用发票。
+- OCR 失败、重复、已使用、他人已使用都要显示可理解原因。
+- 刷新按钮必须有明显反馈，不能让用户误以为没点中。
+
+## 查重规则
+
+公司级查重优先级：
+
+- 相同 `file_sha256`。
+- OCR 后相同 `invoice_code + invoice_number`。
+- 后续支持数电票号码时，应加入同等优先级的唯一识别字段。
+
+不可添加场景：
+
+- 同一公司已有相同可用发票。
+- 同一公司已有相同发票正在识别。
+- 同一公司已有相同发票识别失败。
+- 同一公司已有相同发票被其他人上传。
+- 同一公司已有相同发票处于 `bound` 或已完成报销归档。
+
+普通流程不开放“强制重复添加”。管理员例外处理必须保留审计字段和原因。
+
+## 添加到报销单
+
+服务端必须校验：
+
+- 当前用户有发票上传/报销编辑权限。
+- 发票属于报销单申请人或可被当前角色合法处理。
+- 发票状态为可添加。
+- 发票未被其他报销单、差旅单或归档流程占用。
+- `linkedItemId` 若传入，必须属于当前报销单。
+
+明细匹配规则：
+
+- 报销单只有一条明细时，自动添加到该明细。
+- 多条明细时，优先按发票金额唯一匹配。
+- 无法唯一匹配但发票金额存在时，自动创建新明细。
+- 发票金额缺失时，阻断自动创建并提示需要先处理发票信息。
+
+## 移除与删除
+
+- 草稿和驳回状态允许移除发票，移除后发票回到可用状态。
+- 审批中使用撤回，不提供删除。
+- 已通过、已支付、已归档的报销单不允许普通用户删除。
+- 删除草稿时，已添加发票应释放为可用，附件随报销单删除。
+
+## 附件材料
+
+附件用于支付截图、合同、订单、聊天记录、情况说明等非发票材料。
+
+规则：
+
+- 支持 PDF、JPG、PNG、WEBP。
+- 支持多文件上传。
+- 不参与发票 OCR。
+- 不参与发票查重。
+- 草稿和驳回状态可上传、查看、删除。
+- 提交后审批人和财务可查看。
+
+## PC 与手机体验
+
+PC 端：
+
+- 适合明细编辑、批量查看、财务复核和台账导出。
+- 报销详情分区展示：摘要、明细、发票、附件、审批流、预算与审核提示。
+
+手机/企业微信端：
+
+- 适合新建、继续编辑草稿、拍照/上传发票、补充附件、提交审批、查状态。
+- 不显示桌面表格。
+- 添加发票不默认聚焦搜索框，不自动弹键盘。
+- 底部操作区紧凑，选中态使用品牌实心色。
+
+## 自动化验收
+
+每次改报销/发票/附件至少验证：
+
+- 后端单测覆盖上传、查重、添加、移除、附件上传/下载/删除。
+- 前端 `typecheck` 和 `build`。
+- Playwright PC 报销详情。
+- Playwright mobile/wecom UA 报销详情。
+- 视觉检查无 PC 壳、无表格误入、无黑色大块导航、无“绑定整单/不绑定明细/发票池/OCR”等普通用户文案。