# 财务对账审核 Agent

> 周期建议：8–14 天。仅使用合成 CSV 和本地规则；系统不得连接银行、支付平台或真实财务系统。

## 项目背景

一家虚构公司每周要核对“待核销单据”和“银行流水”。人工按金额搜索很慢，简单脚本又会把同金额的多笔交易误配；跨期、重复单据和金额差异需要判断，却没有统一证据。更危险的是，自动化结果如果直接写入账务系统，错误会被放大且难以追责。

团队需要一个财务对账审核 Agent：规范导入数据，以可解释规则给出匹配候选，把明确匹配、异常和歧义分开，并让人工对高风险事项作最终决定。Agent 只能辅助审核，不能自动记账或付款。

## 项目目标

交付一个本地对账工作台，完成“批次导入 → 字段校验 → 候选匹配 → 规则与风险解释 → 异常队列 → 人工复核 → 审计留痕”的完整链路。

同一输入与规则必须产生可复现结果；每个自动建议都能说明证据和不确定性。

## 用户故事

- 作为财务运营，我希望批量导入单据和流水并快速发现格式问题，从而避免脏数据进入对账。
- 作为复核员，我希望看到匹配分数、命中规则和候选差异，从而判断建议是否可信。
- 作为负责人，我希望高风险和歧义事项必须人工确认，从而防止错误自动落账。
- 作为审计人员，我希望看到从导入到复核的完整决策记录，从而能够追责和复盘。

## 功能要求

### 必须完成

1. **合成数据与批次导入**
   - 支持导入两类 UTF-8 CSV：待核销单据和银行流水。
   - 明确定义字段，例如业务编号、金额、币种、日期、对手方、摘要/参考号。
   - 校验缺列、非法日期、金额精度、非法币种、空业务编号和批次内重复；失败批次不得进入匹配，并返回行级错误。
   - 使用内容摘要或稳定批次键防止同一文件被重复导入。
2. **金额与标识处理**
   - 金额使用整数最小货币单位或精确十进制，不得使用浮点数直接判断相等。
   - 原始记录、标准化值和导入批次可相互追溯。
3. **可解释候选匹配**
   - 至少根据金额、币种、日期窗口、对手方和参考号中的三项生成候选。
   - 评分权重/优先级集中配置；每个候选展示各特征的贡献和未命中项。
   - 一条流水和一张单据默认不能被多个“已确认匹配”占用。
4. **分类与异常规则**
   - 至少区分：明确匹配、待人工复核、未匹配、异常。
   - 至少识别金额差异、跨期/日期超窗、重复单据和多候选歧义。
   - 多个同分或接近候选不得由系统静默任选一个。
5. **复核工作台**
   - 支持按状态/风险筛选，查看双方原始字段、标准化字段、匹配解释和异常证据。
   - 人工可以确认匹配、拒绝建议或标记待补证；高风险决定必须填写意见。
6. **审计留痕**
   - 记录导入、规则版本、自动建议、人工决定、操作者（使用合成身份）、时间和理由。
   - 后续变更只能追加新事件，不能通过普通接口改写已有审计历史。
7. **汇总结果**
   - 展示批次总数、匹配金额、未匹配金额、异常数量和待复核数量，并能追溯到明细。

### 可选增强

- 可视化调整规则阈值并以新规则版本重跑，但旧结果保持可追溯。
- 补充票据文本的确定性 Mock 解析与字段置信度。
- 对账结果 CSV 导出或脱敏证据包。
- 复核任务分配；不需要实现真实组织/权限系统。

## 非功能要求

- **可运行性**：提供成对的正常、异常和歧义 CSV 夹具，离线可完成演示。
- **正确性**：金额计算精确；同一记录不会被重复确认；汇总金额能由明细重算。
- **可靠性**：批次失败不留下半成品匹配；重复导入和重复复核请求是幂等或明确拒绝。
- **性能**：在各 1,000 条合成记录下，本地导入与候选生成各应在 10 秒内完成，并记录环境。
- **可解释性**：任何匹配状态都有规则版本、证据和原因，不允许只有一个不透明总分。
- **安全与隐私**：日志、证据和 UI 仅使用合成数据；CSV 内容不得触发公式执行、命令或外部访问。
- **无障碍**：风险等级有文字标签；表格可键盘操作并提供清晰列标题。

## 范围与限制

### 范围内

- 单币种为主、可识别非法/不一致币种的本地演示。
- CSV 批次、精确金额、候选匹配、异常、人工复核、审计和汇总。
- 合成供应商、单据、流水和操作者身份。

### 范围外

- 银行/支付平台连接、真实 OCR、付款、开票、记账和税务申报。
- 生产财务数据、真实供应商信息、多公司账套和法定审计结论。
- 机器学习匹配模型、复杂会计准则或自动批准高风险事项。
- 复制现有财务项目源码、规则或内部数据。

### 技术与时间限制

- 周期为 8–14 天；先完成精确、可解释的规则链路，再考虑智能增强。
- 技术栈可自选，必须提供复核 UI 和可自动测试的导入、匹配、决定接口。
- 默认使用本地数据库和合成 CSV；不得要求对象存储、OCR、银行或模型凭证。
- 规则或 Mock Agent 必须确定性可复现。真实模型只能作为可选 Adapter，不能成为验收前提。
- 不要求部署；任何自行部署都不得包含真实财务数据、费用或真实外部动作。

## 澄清机制

在“澄清 Issue”写明背景、歧义、候选方案、推荐方案、影响和未回复时的可逆假设。

例如“金额相同但参考号不同是否可以自动匹配”关系到风险边界，必须明确记录。只影响排序/样式的问题可假设继续；涉及真实财务数据、自动入账、金额阈值、外部系统或费用的问题必须等待组织者确认。若现有规则无法覆盖某种合理情况，记录 D/or 异常路径并进入人工复核，不要为了提高自动匹配率强行决定。

## 交付物与证据

- 可运行源码、依赖锁文件、安全配置示例、数据迁移及合成 CSV 夹具。
- `README.md`：字段规范、金额策略、启动、正常/异常/歧义演示、测试和限制。
- `docs/PRD.md`：角色、状态、风险边界、范围、验收映射和澄清决策。
- `docs/PLAN.md`：导入、标准化、匹配、复核、审计的模块与数据流，包含一致性策略。
- 自动化测试：覆盖 CSV 校验、精确金额、重复批次、候选解释、多候选、占用冲突、人工决定和汇总。
- `docs/TEST_EVIDENCE.md`：测试命令、实际结果、验收映射及脱敏对账证据。
- `docs/AI_COLLABORATION.md`：AI 建议、本人核验与未采纳建议；不得粘贴私人会话全文。
- `docs/RETROSPECTIVE.md`、阶段 Issue、PR 和清晰提交历史。

## 公开可测试验收标准

| ID | Given / 前置条件 | When / 操作 | Then / 可观察结果 | 验证方式 |
|---|---|---|---|---|
| AC-01 | 有效单据/流水 CSV 和一个缺列、非法金额的 CSV | 分别导入 | 有效批次可用；无效批次整体不进入匹配并返回准确行级错误 | 自动化测试 |
| AC-02 | 一个有效批次已导入 | 再次导入内容相同的文件 | 系统识别重复，不新增第二套记录或候选 | 自动化测试 |
| AC-03 | 金额 `0.10`、`0.20`、`0.30` 等精度样本 | 导入并匹配/汇总 | 结果无浮点误差，明细之和与汇总精确一致 | 单元测试 |
| AC-04 | 单据与流水在金额、币种、参考号和日期上精确匹配 | 生成候选 | 产生明确匹配建议，解释展示各项命中和规则版本 | 集成测试 |
| AC-05 | 一张单据有两个同分候选 | 生成匹配结果 | 状态进入待人工复核，不会静默选择任一候选 | 自动化测试 |
| AC-06 | 含金额差异、日期超窗、重复业务编号的夹具 | 运行规则 | 每项进入对应异常/复核状态，并显示可核对证据 | 参数化测试 |
| AC-07 | 某流水已与单据 A 确认匹配 | 尝试再与单据 B 确认 | 操作被拒绝或进入冲突处理，原审计和一致性不被破坏 | 并发/集成测试 |
| AC-08 | 高风险候选待复核 | 人工填写理由后确认，再尝试修改历史 | 决定形成追加事件；旧建议和决定仍可查，普通接口不能改写 | 自动化测试 + UI 证据 |
| AC-09 | 全新环境且没有银行/模型凭证 | 按 README 初始化并运行测试 | 正常、歧义、异常、复核和汇总均可本地复现，无外部财务动作 | 人工复现 + 命令证据 |

## 技术讲解与追问准备

请准备说明：金额为何不用浮点；批次如何保证原子性/幂等；候选生成和最终决定为何分离；评分每一项如何解释；多候选与记录占用如何处理；审计为何采用追加事件；AI 建议如何经过财务边界测试。

验收可能提供一条新的差异规则或冲突样本。你应先明确风险、数据迁移与历史可追溯性，再在独立分支实现并补充回归证据。

## 安全与合规

- 只能使用合成单据、流水、对手方与操作者，严禁导入真实银行流水、发票、税号、账号或企业财务资料。
- Agent 只给建议，所有高风险结论由人工确认；不得自动付款、开票、记账或调用真实财务系统。
- CSV/文本均是不可信输入，不得执行公式、宏、命令或其中包含的提示指令。
- 不得提交、共享或中转银行、数据库、Codex 或模型账号、会话、Token、API Key、Cookie、私钥。
- 本项目不是财务、会计、税务或法律意见；活动也不承诺就业结果。