feat: deliver agent foundation day 1

2026-05-11 03:51:24 +00:00
parent f738b6cdd4
commit b2beeaa136
54 changed files with 6747 additions and 1724 deletions
--- a/plan/14_financial_document_canonical_model.md
+++ b/plan/14_financial_document_canonical_model.md
@@ -11,6 +11,13 @@ OCR、MCP、用户填写、业务数据库可能都描述同一张发票，但
 - Hermes 难以批量统计。
 - MCP 返回结果难以合并。

+这里要区分两层：
+
+- 标准模型：定义 Agent、规则、MCP、OCR、数据库之间统一交换的数据结构。
+- 业务数据库表：定义 MVP 阶段真正落库存储、查询和统计所依赖的最小业务表。
+
+如果只有标准模型，没有最小业务表，User Agent 和 Hermes 仍然无法完成报销、应收、应付的查询、解释、巡检和统计。
+
 ## 2. 标准对象

 第一版建议定义这些对象：
@@ -20,6 +27,8 @@ Invoice
 Receipt
 ReimbursementRequest
 PaymentRequest
+AccountsReceivableRecord
+AccountsPayableRecord
 BankTransaction
 Contract
 Customer
@@ -57,11 +66,17 @@ CostCenter
  "request_id": "",
  "request_no": "",
  "employee_id": "",
+  "employee_name": "",
  "department_id": "",
+  "department_name": "",
+  "project_code": "",
  "expense_type": "",
+  "reason": "",
+  "location": "",
  "amount": 0,
  "currency": "CNY",
  "status": "",
+  "occurred_at": "",
  "submitted_at": "",
  "approval_stage": "",
  "invoices": [],
@@ -70,7 +85,55 @@ CostCenter
 }
 ```

-## 5. BankTransaction 标准模型
+说明：
+
+- `reason`、`location`、`occurred_at` 是报销查询、规则解释、风险识别的最小必要字段。
+- 如果一张报销单包含多条费用明细，应在数据库层拆到明细表，但对外仍可聚合为一个 `ReimbursementRequest`。
+
+## 5. AccountsReceivableRecord 标准模型
+
+```json
+{
+  "ar_id": "",
+  "document_no": "",
+  "customer_id": "",
+  "customer_name": "",
+  "contract_no": "",
+  "invoice_no": "",
+  "amount_receivable": 0,
+  "amount_received": 0,
+  "amount_outstanding": 0,
+  "currency": "CNY",
+  "due_date": "",
+  "posting_date": "",
+  "status": "",
+  "aging_days": 0,
+  "risk_flags": []
+}
+```
+
+## 6. AccountsPayableRecord 标准模型
+
+```json
+{
+  "ap_id": "",
+  "document_no": "",
+  "vendor_id": "",
+  "vendor_name": "",
+  "invoice_no": "",
+  "amount_payable": 0,
+  "amount_paid": 0,
+  "amount_outstanding": 0,
+  "currency": "CNY",
+  "due_date": "",
+  "posting_date": "",
+  "status": "",
+  "aging_days": 0,
+  "risk_flags": []
+}
+```
+
+## 7. BankTransaction 标准模型

 ```json
 {
@@ -87,7 +150,133 @@ CostCenter
 }
 ```

-## 6. 字段来源优先级
+## 8. MVP 最小业务表设计建议
+
+标准模型不等于数据库表，但 MVP 至少要有以下业务表，才能支撑 Day 5 和 Day 6。
+
+### 8.1 报销主表 `expense_claims`
+
+建议字段：
+
+```text
+id
+claim_no
+employee_id
+employee_name
+department_id
+department_name
+project_code
+expense_type
+reason
+location
+amount
+currency
+invoice_count
+occurred_at
+submitted_at
+status
+approval_stage
+risk_flags_json
+created_at
+updated_at
+```
+
+适用场景：
+
+- 查询员工报销金额、状态、进度。
+- 解释报销为什么被拦截。
+- 识别超标、重复、异常等风险。
+
+### 8.2 报销明细表 `expense_claim_items`
+
+建议字段：
+
+```text
+id
+claim_id
+item_date
+item_type
+item_reason
+item_location
+item_amount
+invoice_id
+created_at
+updated_at
+```
+
+适用场景：
+
+- 一单多明细。
+- 重复报销匹配。
+- 与发票 OCR 结果逐条比对。
+
+### 8.3 应收主表 `accounts_receivable`
+
+建议字段：
+
+```text
+id
+receivable_no
+customer_id
+customer_name
+contract_no
+invoice_no
+amount_receivable
+amount_received
+amount_outstanding
+currency
+posting_date
+due_date
+aging_days
+status
+risk_flags_json
+created_at
+updated_at
+```
+
+适用场景：
+
+- 客户应收查询。
+- 账龄分析。
+- 逾期风险巡检。
+
+### 8.4 应付主表 `accounts_payable`
+
+建议字段：
+
+```text
+id
+payable_no
+vendor_id
+vendor_name
+invoice_no
+amount_payable
+amount_paid
+amount_outstanding
+currency
+posting_date
+due_date
+aging_days
+status
+risk_flags_json
+created_at
+updated_at
+```
+
+适用场景：
+
+- 供应商待付款查询。
+- 付款状态查询。
+- 逾期应付和异常付款巡检。
+
+### 8.5 MVP 设计边界
+
+- 不要求一次建完整 ERP 总账、分录、核销、凭证体系。
+- 第一周只要求支撑查询、解释、统计、风险识别的最小字段。
+- 如果现有业务系统已有对应表或 API，优先复用，不重复造表。
+- 如果当前环境没有真实业务数据源，可先建立 Mock 表，但字段命名应尽量贴近最终标准模型。
+
+## 9. 字段来源优先级

 建议优先级：

@@ -101,7 +290,7 @@ CostCenter

 LLM 推断字段必须标记来源和置信度。

-## 7. 与语义本体关系
+## 10. 与语义本体关系

 语义本体识别的是用户意图和对象。

@@ -112,15 +301,28 @@ ontology.entities[].type = invoice
  -> 映射到 Invoice 标准模型
 ```

-## 8. 开发阶段建议
+补充映射建议：
+
+```text
+ontology.scenario = expense
+  -> 查询 expense_claims / expense_claim_items
+
+ontology.scenario = accounts_receivable
+  -> 查询 accounts_receivable
+
+ontology.scenario = accounts_payable
+  -> 查询 accounts_payable
+```
+
+## 11. 开发阶段建议

 ```text
 Step 1: 定义 Invoice 标准模型
 Step 2: 定义 ReimbursementRequest 标准模型
-Step 3: OCR 输出映射到 Invoice
-Step 4: MCP 输出映射到 Invoice
-Step 5: 规则中心基于标准模型执行
-Step 6: 扩展 AR/AP 标准模型
-Step 7: 建立字段血缘和置信度
+Step 3: 定义 AccountsReceivableRecord / AccountsPayableRecord 标准模型
+Step 4: 设计 MVP 最小业务表 expense_claims / expense_claim_items / accounts_receivable / accounts_payable
+Step 5: OCR 输出映射到 Invoice
+Step 6: MCP 输出映射到 Invoice 或 AR/AP 标准模型
+Step 7: 规则中心基于标准模型执行
+Step 8: 建立字段血缘和置信度
 ```
-