跳转至

单证识别运行时

Document Recognition 不再拥有作业执行运行时。运行时创建和执行由 Fusion 子系统负责，本模块只消费已持久化的 Fusion run input/output，并生成可回顾、可修改、可持久化的单证识别 projection。

运行阶段

stateDiagram-v2
    [*] --> fusion_run_created
    fusion_run_created --> fusion_run_completed
    fusion_run_completed --> persist_projection
    persist_projection --> review_required
    review_required --> in_review
    in_review --> reviewed
    review_required --> flagged
    flagged --> in_review
    reviewed --> [*]

当前运行特点

  • Fusion run 是识别结果来源。
  • 只有被 admin registry 注册的 Fusion agent，才会被视为 document-recognition runtime。
  • GET /document-recognition/runtime-agents 返回当前可选 runtime agent 的名称、描述与状态。
  • GET /document-recognition/runtime-agents/{runtime_agent_id} 返回当前 published 版本、fusion_input_contract、fusion_execution_policy 与上传槽位解析摘要。
  • POST /document-recognition/runs 负责校验 registry、解析 published 版本与上传槽位，并创建底层 Fusion run。
  • 管理端 registry 写入只允许具备 document_recognition.write 的管理员执行，并写入 admin audit；该操作不要求密码重输 challenge。
  • /document-recognition/runs/{run_id} 会按需把 Fusion output 持久化为 review projection。
  • /document-recognition/runs/{run_id} 同时返回 canonical workspace_output，供 Outlook Index 直接渲染字段、表格与 bbox。
  • /document-recognition/runs/{run_id} 的 field_reviews[] 会附带轻量 revision summary，但不会默认内联完整 timeline。
  • 字段 review 更新会刷新 run-level review counters 和 summary projection，并在字段发生有效变化时写入 append-only revision ledger。
  • GET /document-recognition/runs/{run_id}/field-reviews/{field_id}/revisions 用于按需读取单字段 timeline；没有 ledger 的旧 run 也会返回 baseline 快照与 history_status=unrecorded。
  • 旧 review storage 只通过 infrastructure bridge 复用。

Fusion Run Projection

Document Recognition 从 Fusion run 读取：

  • fusion_run_inputs：source file name、MIME type、object key
  • fusion_run_outputs：structured JSON result、result object key
  • fusion_runs.governance_context_json：validation issue context
  • fusion_runs.status/error_message：run lifecycle 和失败信息

状态语义

  • completed：Fusion run 已完成，projection 可生成。
  • failed：Fusion run 失败，projection 会保留错误 issue。
  • review_required：projection 生成后仍有字段等待人工处理。
  • in_review：部分字段已处理。
  • reviewed：全部字段已接受或修正。
  • flagged：存在需跟进字段。

Consumer 视角

调用方应使用：

  • GET /document-recognition/runtime-agents
  • GET /document-recognition/runtime-agents/{runtime_agent_id}
  • POST /document-recognition/runs
  • GET /document-recognition/runs
  • GET /document-recognition/runs/{run_id}
  • PATCH /document-recognition/runs/{run_id}/field-reviews/{field_id}
  • GET /document-recognition/runs/{run_id}/field-reviews/{field_id}/revisions
  • GET /document-recognition/runs/{run_id}/source-document
  • GET /document-recognition/runs/{run_id}/source-pdf
  • GET /document-recognition/runs/{run_id}/result

这些 canonical routes 当前直接以公开 surface 提供，不再维护额外的前缀别名。 旧 /agents/{agent_id}/extraction-jobs 不再由 ai_service/document_recognition 包注册。

管理端使用以下接口维护 runtime registry：

  • GET /admin/document-recognition/runtime-agents
  • GET /admin/document-recognition/runtime-agent-candidates
  • PUT /admin/document-recognition/runtime-agents/{agent_id}
  • DELETE /admin/document-recognition/runtime-agents/{agent_id}

PUT / DELETE 继续以 agent_id 作为稳定标识，服务端不会接受 agent name 作为 registry 主键。 这些写入需要管理员会话和 document_recognition.write，成功和失败都会进入 admin_action_audits，但不再要求 x-admin-challenge-token。