X-Financial/document/development/agent plan/06_data_contracts_and_governance.md

数据契约与治理要求

1. 推荐数据表

1.1 语义本体

semantic_ontology_schemas

字段：

id
schema_version
schema_json
status
created_by
created_at
updated_at

semantic_parse_logs

字段：

id
source
user_id
raw_text
ontology_json
confidence
parse_strategy
created_at

1.2 Agent 资产

agent_rules
agent_skills
agent_mcp_services
agent_tasks

通用字段：

id
code
name
description
status
owner
reviewer
config_json
created_at
updated_at

1.3 版本与审核

agent_asset_versions

字段：

id
asset_type
asset_id
version
content
change_note
created_by
created_at

agent_asset_reviews

字段：

id
asset_type
asset_id
version
reviewer
review_status
review_note
reviewed_at

1.4 运行日志

agent_runs

字段：

id
agent
source
task_id
user_id
ontology_json
status
started_at
finished_at
result_summary
error_message

agent_tool_calls

字段：

id
run_id
tool_type
tool_name
request_json
response_json
status
duration_ms
created_at

1.5 财务业务主表

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 票据与文件资产表

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、验真与风险表

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 语义解析

POST /api/v1/semantic/parse

请求：

{
  "source": "user_message",
  "text": "这张发票为什么被拦截？",
  "context": {
    "user_id": "emp_001",
    "current_page": "reimbursement_detail"
  }
}

响应：

{
  "domain": "reimbursement",
  "scenario": "invoice_validation",
  "intent": "explain",
  "entities": [],
  "time_range": {},
  "constraints": {},
  "risk_signals": ["unknown"],
  "parse_strategy": "llm_primary",
  "next_step": "run_rule"
}

2.2 Orchestrator 执行

POST /api/v1/agent/orchestrate

请求：

{
  "source": "user_message",
  "ontology": {},
  "context": {}
}

响应：

{
  "agent": "user_agent",
  "tools_called": [],
  "answer": "",
  "requires_confirmation": false,
  "audit_id": ""
}

2.3 文件上传契约

POST /api/v1/documents/upload

请求：

{
  "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"
    }
  ]
}

响应：

{
  "documents": [
    {
      "document_id": "",
      "version_no": 1,
      "storage_status": "stored",
      "ocr_status": "pending"
    }
  ]
}

2.4 Hermes 任务

POST /api/v1/hermes/tasks/run

请求：

{
  "task_code": "daily_risk_scan",
  "ontology": {},
  "dry_run": false
}

响应：

{
  "run_id": "",
  "status": "accepted"
}

3. 安全原则

3.1 最小权限

Agent 调工具时不能使用超级权限。

权限来源：

• 用户权限
• 任务权限
• 服务账号权限

3.2 高风险动作确认

以下动作必须确认：

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

3.3 审计不可省略

必须记录：

• 谁触发
• 输入是什么
• 解析结果是什么
• 调了哪些工具
• 输出是什么
• 是否确认

3.4 文件存储治理

必须遵守：

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

3.5 敏感数据治理

对于发票、行程单、合同、付款凭证中的敏感信息：

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

3.6 AI 证据治理

Agent 和 OCR 相关能力必须遵守：

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

4. 数据质量要求

4.1 关键唯一性

• expense_claims.claim_no 唯一
• document_assets.sha256 可重复但必须可检索
• document_asset_versions(document_id, version_no) 唯一
• invoice_structured_records.duplicate_fingerprint 必须可索引

4.2 时间与状态字段

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

4.3 可追溯性

任一笔报销单、发票或风险结论，至少应能追到：

• 原始输入文本
• 原始附件
• 结构化结果
• 规则或模型判断
• 人工修正动作

5. 实施优先级

第一优先级：

• expense_claims
• expense_claim_items
• document_assets
• document_asset_versions
• expense_item_documents

第二优先级：

• document_ocr_results
• invoice_structured_records
• invoice_verification_records
• document_derivatives

第三优先级：

• risk_events
• risk_actions
• document_access_logs

实施原则：

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