# 数据契约与治理要求 ## 1. 推荐数据表 ### 1.1 语义本体 ```text semantic_ontology_schemas ``` 字段： ```text id schema_version schema_json status created_by created_at updated_at ``` ```text semantic_parse_logs ``` 字段： ```text id source user_id raw_text ontology_json confidence parse_strategy created_at ``` ### 1.2 Agent 资产 ```text agent_rules agent_skills agent_mcp_services agent_tasks ``` 通用字段： ```text id code name description status owner reviewer config_json created_at updated_at ``` ### 1.3 版本与审核 ```text agent_asset_versions ``` 字段： ```text id asset_type asset_id version content change_note created_by created_at ``` ```text agent_asset_reviews ``` 字段： ```text id asset_type asset_id version reviewer review_status review_note reviewed_at ``` ### 1.4 运行日志 ```text agent_runs ``` 字段： ```text id agent source task_id user_id ontology_json status started_at finished_at result_summary error_message ``` ```text agent_tool_calls ``` 字段： ```text id run_id tool_type tool_name request_json response_json status 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 语义解析 ```text POST /api/v1/semantic/parse ``` 请求： ```json { "source": "user_message", "text": "这张发票为什么被拦截？", "context": { "user_id": "emp_001", "current_page": "reimbursement_detail" } } ``` 响应： ```json { "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 执行 ```text POST /api/v1/agent/orchestrate ``` 请求： ```json { "source": "user_message", "ontology": {}, "context": {} } ``` 响应： ```json { "agent": "user_agent", "tools_called": [], "answer": "", "requires_confirmation": false, "audit_id": "" } ``` ### 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 ``` 请求： ```json { "task_code": "daily_risk_scan", "ontology": {}, "dry_run": false, "context_json": { "folder": "报销制度", "changed_only": true, "force": false } } ``` 响应： ```json { "run_id": "", "status": "accepted" } ``` 补充： - Hermes 任务应优先调用系统后台 Hermes CLI 或等价 Hermes 进程。 - `changed_only=true` 时，只处理知识库中发生变化的文档。 - 文档变化判断至少包含 `original_name`、`stored_name`、`sha256`、`version_number`、`updated_at`。 - 若文档无变化，应返回 `unchanged_skipped`，而不是重新形成 LLM Wiki。 ## 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` 实施原则： - 先确保“能收、能存、能找回原件” - 再确保“能识别、能验真、能回填” - 最后做“能解释、能审计、能批量巡检”