跳转至

单证识别架构

单证识别现在是 Fusion run 输出的回顾与持久化边界。Fusion 子系统负责创建和执行 run；ai_service/document_recognition 负责把可识别的 Fusion structured output 持久化为单证识别 projection，并提供字段回顾、问题列表、摘要和下载元数据。

当前主链路

flowchart LR
  FusionRun["Fusion run completed"] --> Persist["PersistFusionDocumentRecognitionRunUseCase"]
  Persist --> Projection["Document recognition persisted projection"]
  Projection --> Detail["GET /document-recognition/runs/{run_id}"]
  Detail --> Timeline["GET /document-recognition/runs/{run_id}/field-reviews/{field_id}/revisions"]
  Detail --> Review["PATCH /document-recognition/runs/{run_id}/field-reviews/{field_id}"]
  Review --> Ledger["Append revision ledger entry"]
  Ledger --> Recalculate["Recalculate review counters"]
  Recalculate --> Projection
  Projection --> Admin["Admin overview / runs"]

分层边界

domain/

  • 定义单证识别 run、field review、issue、summary 的投影模型。
  • 不依赖 FastAPI、SQLAlchemy、MinIO 或 Fusion runtime。

application/

  • use_cases/review_runs.py：把 Fusion run 输出持久化为单证识别投影，并处理字段回顾更新。
  • projections.py：从 Fusion structured output 合成 summary、issue、field review 和 preview payload。
  • ports/：repository / asset store 抽象。

infrastructure/

  • persistence/document_recognition_repository.py：查询 Fusion run，读写回顾投影。
  • persistence/legacy_document_extraction_job_bridge.py：临时复用历史 review storage 表，并把旧存储命名隔离在 infrastructure 层。
  • storage/minio_document_asset_store.py：文档资产读写。

interfaces/http/

  • runs.py：公开的 /document-recognition/runs* run/review API。
  • admin.py：管理端 overview / runs。
  • serialization.py：把 persisted projection 转为 HTTP response。
  • HTTP 层不创建 runtime 作业，也不决定 runtime family。

Fusion 输出模型

Document Recognition 会读取 Fusion run 的 persisted inputs/outputs：

  • source input 决定 source_filename、source_media_type 和 source object key。
  • structured JSON output 决定 document fields、summary 和 result object key。
  • governance context / failed status 会转成 validation issue。

当前支持两类 structured output：

  • fields[] / tables[] 风格 payload
  • canonical document_field_set named-field object payload

Review Persistence

字段 review 当前态仍复用既有 field-review row，但每次有效修改都会追加一条 append-only revision ledger。这样可以同时满足：

  • run projection 继续由当前 field-review row 驱动 review_status、corrected_field_count 与 workspace_output
  • 前端按需读取单字段 timeline，而不必把完整历史塞进所有 run detail
  • 对没有 ledger 的历史旧 run 继续保留 baseline 快照，并显式标记为 unrecorded

关键代码入口

路径 作用
ai_service/document_recognition/application/use_cases/review_runs.py Fusion run projection 与字段回顾用例
ai_service/document_recognition/application/projections.py summary / issue / field review 归一化
ai_service/document_recognition/infrastructure/persistence/document_recognition_repository.py SQLAlchemy 仓库适配器
ai_service/document_recognition/infrastructure/persistence/legacy_document_extraction_job_bridge.py 历史 review storage bridge
ai_service/document_recognition/interfaces/http/runs.py document-recognition run/review API
ai_service/document_recognition/interfaces/http/admin.py 管理端总览与运行列表

常见改动应该去哪里

想改 Fusion 输出识别规则

看 application/projections.py。

想改字段回顾持久化规则

看 application/use_cases/review_runs.py、infrastructure/persistence/document_recognition_repository.py 和 storage/model_domains/jobs.py。

想改 API 返回字段

看 interfaces/http/schemas.py 和 interfaces/http/serialization.py。