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. 标准对象

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

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

## 3. Invoice 标准模型

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

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

```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
{
  "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`

建议字段：

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

建议优先级：

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

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

## 10. 与语义本体关系

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

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

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

补充映射建议：

```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: 定义 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: 建立字段血缘和置信度
```