跳转至

单证识别运行时

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
    review_required --> rejected
    in_review --> rejected
    flagged --> rejected
    fusion_run_created --> fusion_run_failed
    fusion_run_failed --> rerun_created
    rejected --> rerun_created
    rerun_created --> fusion_run_created
    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。
  • POST /document-recognition/runs/{run_id}/reject 用于把 completed、unsynced 的坏结果标记为 review_status=rejected，并写入 document-level review event；该操作不会把执行状态改成 failed。
  • POST /document-recognition/runs/{run_id}/rerun 用于从 failed 或 rejected source run 创建新的 run，并写入 source/target rerun lineage；普通 run list/detail 不默认返回 lineage 字段。
  • 旧 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：存在需跟进字段。
  • rejected：Fusion run 已完成，但操作员判定抽取结果不可用；它仍然是 status=completed，可以触发 rerun。

Rerun Lineage

Rerun 是新的 run attempt，不是原地覆盖。后端会读取 source run 的源对象、文件名、MIME type、runtime agent 与上传槽位上下文，再走标准 run creation path 创建 target run。

每次 rerun 都会在 document_extraction_job_rerun_links 写入一条直接关系：

  • source_run_id：原始 failed 或 rejected run
  • target_run_id：新创建的 run
  • source_status_snapshot / source_review_status_snapshot：创建 rerun 时的 source 状态快照

如果需要从 source run 反查 target runs，使用 GET /document-recognition/runs?source_run_id=...。普通 DocumentRecognitionRunResponse 会在 rerun target 上返回 rerun_source_run_id，用于 UI 标识这条记录来自哪个 source run。

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?source_run_id={source_run_id}
  • GET /document-recognition/runs/{run_id}
  • POST /document-recognition/runs/{run_id}/reject
  • POST /document-recognition/runs/{run_id}/rerun
  • 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。