X-Financial/document/development/agent plan/14_financial_document_canonical_model.md

财务单据标准模型

1. 为什么需要标准模型

OCR、MCP、用户填写、业务数据库可能都描述同一张发票，但字段名和格式不同。

如果没有标准模型：

• 规则无法复用。
• Agent 难以解释。
• Hermes 难以批量统计。
• MCP 返回结果难以合并。

这里要区分两层：

• 标准模型：定义 Agent、规则、MCP、OCR、数据库之间统一交换的数据结构。
• 业务数据库表：定义 MVP 阶段真正落库存储、查询和统计所依赖的最小业务表。

如果只有标准模型，没有最小业务表，User Agent 和 Hermes 仍然无法完成报销、应收、应付的查询、解释、巡检和统计。

2. 标准对象

第一版建议定义这些对象：

Invoice
Receipt
ReimbursementRequest
PaymentRequest
AccountsReceivableRecord
AccountsPayableRecord
BankTransaction
Contract
Customer
Vendor
Employee
CostCenter

3. Invoice 标准模型

{
  "invoice_id": "",
  "invoice_code": "",
  "invoice_number": "",
  "invoice_type": "",
  "seller_name": "",
  "seller_tax_no": "",
  "buyer_name": "",
  "buyer_tax_no": "",
  "issue_date": "",
  "total_amount": 0,
  "tax_amount": 0,
  "currency": "CNY",
  "verify_status": "",
  "ocr_confidence": 0,
  "source_document_id": ""
}

4. ReimbursementRequest 标准模型

{
  "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": [],
  "attachments": [],
  "risk_flags": []
}

说明：

• reason、location、occurred_at 是报销查询、规则解释、风险识别的最小必要字段。
• 如果一张报销单包含多条费用明细，应在数据库层拆到明细表，但对外仍可聚合为一个 ReimbursementRequest。

5. AccountsReceivableRecord 标准模型

{
  "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 标准模型

{
  "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 标准模型

{
  "transaction_id": "",
  "bank_account": "",
  "transaction_date": "",
  "amount": 0,
  "currency": "CNY",
  "counterparty_name": "",
  "summary": "",
  "matched_object_type": "",
  "matched_object_id": "",
  "match_status": ""
}

8. MVP 最小业务表设计建议

标准模型不等于数据库表，但 MVP 至少要有以下业务表，才能支撑 Day 5 和 Day 6。

8.1 报销主表 expense_claims

建议字段：

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

建议字段：

id
claim_id
item_date
item_type
item_reason
item_location
item_amount
invoice_id
created_at
updated_at

适用场景：

• 一单多明细。
• 重复报销匹配。
• 与发票 OCR 结果逐条比对。

8.3 应收主表 accounts_receivable

建议字段：

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

建议字段：

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. 字段来源优先级

建议优先级：

人工确认字段
  > MCP 验真字段
  > 业务系统字段
  > OCR 字段
  > LLM 推断字段

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

10. 与语义本体关系

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

标准模型承载对象的结构化字段。

ontology.entities[].type = invoice
  -> 映射到 Invoice 标准模型

补充映射建议：

ontology.scenario = expense
  -> 查询 expense_claims / expense_claim_items

ontology.scenario = accounts_receivable
  -> 查询 accounts_receivable

ontology.scenario = accounts_payable
  -> 查询 accounts_payable

11. 开发阶段建议

Step 1: 定义 Invoice 标准模型
Step 2: 定义 ReimbursementRequest 标准模型
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: 建立字段血缘和置信度