docs(agent-plan): update architecture docs and remove weekly_execution_details

- Update 00_README.md: refresh architecture overview - Update 02_semantic_ontology.md: expand semantic layer design - Update 04_orchestrator_and_runtime_flow.md: add runtime flow details - Update 05_development_roadmap.md: refine milestone timeline - Update 06_data_contracts_and_governance.md: add contract specifications - Update 10_evaluation_and_testset.md: add evaluation framework - Update 11_ocr_invoice_architecture.md: enhance OCR architecture - Update 14_financial_document_canonical_model.md: complete model design - Remove weekly_execution_details/: deprecated in favor of agent week plan
2026-05-12 01:20:53 +00:00
parent 0b63be2d39
commit 9b88ee2901
17 changed files with 1071 additions and 1871 deletions
--- a/plan/06_data_contracts_and_governance.md
+++ b/plan/06_data_contracts_and_governance.md
@@ -33,6 +33,7 @@ user_id
 raw_text
 ontology_json
 confidence
+parse_strategy
 created_at
 ```

@@ -136,6 +137,58 @@ duration_ms
 created_at
 ```

+### 1.5 财务业务主表
+
+```text
+expense_claims
+expense_claim_items
+accounts_receivable
+accounts_payable
+approval_records
+```
+
+治理要求：
+
+- `expense_claims` 作为报销主表，不再继续扩张 `reimbursement_requests`。
+- `expense_claim_items` 作为报销明细最小粒度，OCR 匹配、风险识别、票据挂接都优先挂到该粒度。
+- `accounts_receivable` 与 `accounts_payable` 保持独立，避免因为 Agent 语义层接入而混用口径。
+
+### 1.6 票据与文件资产表
+
+```text
+document_assets
+document_asset_versions
+document_derivatives
+expense_item_documents
+document_access_logs
+```
+
+职责：
+
+- `document_assets`：原始附件主索引
+- `document_asset_versions`：原件版本留痕
+- `document_derivatives`：预览件、缩略图、脱敏件、逐页图片
+- `expense_item_documents`：报销明细与票据关联
+- `document_access_logs`：预览、下载、导出审计
+
+### 1.7 OCR、验真与风险表
+
+```text
+document_ocr_results
+invoice_structured_records
+invoice_verification_records
+risk_events
+risk_actions
+```
+
+职责：
+
+- `document_ocr_results`：每次 OCR 执行快照
+- `invoice_structured_records`：标准化发票字段
+- `invoice_verification_records`：发票验真结果留痕
+- `risk_events`：风险命中事实
+- `risk_actions`：风险处置动作
+
 ## 2. API 契约

 ### 2.1 语义解析
@@ -168,6 +221,7 @@ POST /api/v1/semantic/parse
  "time_range": {},
  "constraints": {},
  "risk_signals": ["unknown"],
+  "parse_strategy": "llm_primary",
  "next_step": "run_rule"
 }
 ```
@@ -200,7 +254,45 @@ POST /api/v1/agent/orchestrate
 }
 ```

-### 2.3 Hermes 任务
+### 2.3 文件上传契约
+
+```text
+POST /api/v1/documents/upload
+```
+
+请求：
+
+```json
+{
+  "biz_domain": "expense",
+  "biz_object_type": "expense_claim",
+  "biz_object_id": "claim_001",
+  "upload_source": "user_workbench",
+  "files": [
+    {
+      "filename": "invoice.jpg",
+      "mime_type": "image/jpeg"
+    }
+  ]
+}
+```
+
+响应：
+
+```json
+{
+  "documents": [
+    {
+      "document_id": "",
+      "version_no": 1,
+      "storage_status": "stored",
+      "ocr_status": "pending"
+    }
+  ]
+}
+```
+
+### 2.4 Hermes 任务

 ```text
 POST /api/v1/hermes/tasks/run
@@ -233,102 +325,109 @@ Agent 调工具时不能使用超级权限。

 权限来源：

- 用户权限。
- 任务权限。
- 服务账号权限。
+- 用户权限
+- 任务权限
+- 服务账号权限

 ### 3.2 高风险动作确认

 以下动作必须确认：

- 提交报销。
- 发起付款。
- 生成正式审批意见。
- 发布规则。
- 发布知识库。
- 创建外部通知。
+- 提交报销
+- 发起付款
+- 生成正式审批意见
+- 发布规则
+- 发布知识库
+- 创建外部通知

 ### 3.3 审计不可省略

 必须记录：

- 谁触发。
- 输入是什么。
- 解析结果是什么。
- 调了哪些工具。
- 输出是什么。
- 是否确认。
- 是否失败。
+- 谁触发
+- 输入是什么
+- 解析结果是什么
+- 调了哪些工具
+- 输出是什么
+- 是否确认

-## 4. 数据治理
+### 3.4 文件存储治理

-### 4.1 脱敏
+必须遵守：

-Hermes 批处理尽量使用脱敏快照。
+- 原始文件二进制不落业务主表，不存入大字段 blob。
+- 所有文件必须有 `storage_provider`、`storage_key`、`sha256`、`file_size_bytes`、`mime_type`。
+- 原件不可覆盖，只能新增版本。
+- 删除默认是解除业务关联或逻辑删除，物理删除必须走审计流程。
+- 对象存储访问必须使用签名 URL 或后端代理，不直接暴露固定公网地址。

-敏感字段：
+### 3.5 敏感数据治理

- 身份证。
- 银行卡。
- 手机号。
- 个人住址。
- 个人发票抬头中的敏感信息。
+对于发票、行程单、合同、付款凭证中的敏感信息：

-### 4.2 数据保留
+- 应支持脱敏衍生件
+- 应记录查看与下载行为
+- 应区分申请人、审批人、财务、管理员可见范围
+- 应支持争议单据 `legal_hold` 保留策略

-建议：
+### 3.6 AI 证据治理

- Agent 运行日志保留 180 天。
- 工具调用详细请求保留 90 天。
- 错误日志保留 365 天。
- 审核记录永久保留。
+Agent 和 OCR 相关能力必须遵守：

-### 4.3 版本治理
+- 未经 OCR/VLM 实际解析，不得假设附件内容已知。
+- Agent 输出若引用发票金额、号码、日期，必须能追溯到 `invoice_structured_records` 或人工修正记录。
+- 风险解释若引用“重复报销”“金额不一致”等判断，必须能追溯到 `risk_events.evidence_json`。

-规则、技能、MCP、任务都应版本化。
+## 4. 数据质量要求

-规则版本尤其重要：
+### 4.1 关键唯一性

- 当前版本必须明确。
- 历史版本可查看。
- 切换版本需要确认。
- 上线版本必须审核通过。
+- `expense_claims.claim_no` 唯一
+- `document_assets.sha256` 可重复但必须可检索
+- `document_asset_versions(document_id, version_no)` 唯一
+- `invoice_structured_records.duplicate_fingerprint` 必须可索引

-## 5. 发布策略
+### 4.2 时间与状态字段

-### 5.1 第一阶段
+- 所有业务主表必须有 `created_at`、`updated_at`
+- 文件上传、OCR、验真、风控、处置必须有独立时间戳
+- 状态字段应使用受控枚举，不允许前端自由拼写

-只允许只读能力：
+### 4.3 可追溯性

- 查知识库。
- 查状态。
- 看规则。
- 看任务报告。
+任一笔报销单、发票或风险结论，至少应能追到：

-### 5.2 第二阶段
+- 原始输入文本
+- 原始附件
+- 结构化结果
+- 规则或模型判断
+- 人工修正动作

-允许生成草稿：
+## 5. 实施优先级

- 报销草稿。
- 付款申请草稿。
- 审批意见草稿。
- 知识候选草稿。
+第一优先级：

-### 5.3 第三阶段
+- `expense_claims`
+- `expense_claim_items`
+- `document_assets`
+- `document_asset_versions`
+- `expense_item_documents`

-允许确认后执行：
+第二优先级：

- 用户确认后提交报销。
- 审批人确认后写入审批意见。
- 管理员确认后发布知识。
- 管理员确认后上线规则。
+- `document_ocr_results`
+- `invoice_structured_records`
+- `invoice_verification_records`
+- `document_derivatives`

-### 5.4 禁止项
+第三优先级：

-长期禁止：
+- `risk_events`
+- `risk_actions`
+- `document_access_logs`

- Agent 自动最终审批。
- Agent 自动付款。
- Agent 自动绕过规则。
- Agent 自动修改财务核心数据。
+实施原则：

+- 先确保“能收、能存、能找回原件”
+- 再确保“能识别、能验真、能回填”
+- 最后做“能解释、能审计、能批量巡检”