跳转至

Outlook Index Fusion Workspace

outlook-index 现在不再只是静态票据 mock。当前实现已经把页面切到 canonical document-recognition API，并把 Fusion 收敛为底层 runtime 实现。

当前能力

  • 当前 demo workspace 外壳仍会先校验 admin session；未登录时显示登录页，但底层 document-recognition API 本身是公开的
  • 支持通过 ?agent_id=...&run_id=... 深链打开指定单证识别 run；同时兼容旧的 ?agentId=...&recognitionRunId=... 链接
  • 地址栏现在还会同步 surface 和 manage_run_id，刷新后会尽量恢复到相同 surface / agent / run 上下文，而不是回到首页默认态
  • 顶部 Runtime 控件从 GET /api/document-recognition/runtime-agents 加载可选 runtime，并以 agent name 作为主要选择入口
  • Runtime selector 支持按 name、description 或 agent_id 搜索；用户不需要手动复制内部 ID
  • 先读取 GET /api/document-recognition/runtime-agents/{runtime_agent_id}，再根据 upload_slot_resolution 判断当前 runtime 是否可上传
  • 通过 multipart/form-data 调用 POST /api/document-recognition/runs
  • 在页面内轮询 GET /api/document-recognition/runs/{run_id}，并展示 canonical workspace_output
  • 历史记录来源统一切到 GET /api/document-recognition/runs?runtime_agent_id=...
  • 点击字段或表格单元时，左侧 viewer 会切换到目标页并显示 bbox 高亮
  • 字段修正现在会先进入 operate/footer 的待同步列表；用户点击 Approve & Sync 后，会先看到一个简洁的确认弹窗，再通过 PATCH /api/document-recognition/runs/{run_id}/field-reviews/{field_id} 批量写回并重新拉取 run detail
  • history 视图不再停留在文件列表；打开历史 run 后会恢复 viewer，并展示该 run 的完整字段 inspector
  • history 视图中的字段列表直接来自 run detail field_reviews，不会受 MANAGE 布局隐藏状态影响
  • history 视图允许对任意字段继续修订，仍沿用 canonical field-review PATCH 路径，不新增第二写入口
  • history 视图会按需调用 GET /api/document-recognition/runs/{run_id}/field-reviews/{field_id}/revisions 读取单字段 timeline，而不是把完整历史塞进 run detail
  • 对于功能上线前没有 revision ledger 的旧 run，history 视图仍会展示 baseline 字段快照，并明确标记“未记录历史”
  • 历史记录回看时，会先通过单证识别 run 的 source_document_url / source_pdf_url 取回 blob，再在前端恢复 PDF / image 预览
  • PDF 预览使用前端 canvas 渲染页图层，再叠加 bbox overlay；这样 bbox 坐标才能与 PDF 页面内容对齐
  • PDF 预览改成渐进式页渲染：首次打开时优先渲染当前页（默认第一页），再按当前页附近逐步补页，而不是先把整份 PDF 全部 rasterize 完再显示
  • PDF 页面在 viewer 内按真实页数连续纵向滚动，页码状态跟随滚动位置更新；字段联动时会滚动到目标页顶部
  • viewer 会把远离当前页的已渲染 PDF 页图退回占位态，需要时再重渲染，以控制长文档的前端内存与 CPU 占用
  • 历史 job 只有在对象存储中的源文件仍然存在时，才能恢复原文档预览；仅有 extraction job 列表记录并不等于原始文件一定还能下载
  • 顶部导航已经拆成 OPERATE / MANAGE / MAINTAIN 三个 surface；MANAGE 会进入独立的管理页面壳层，MAINTAIN 目前仍是占位页
  • MANAGE 现在是浏览器本地的布局编辑器：用户可以选择一条成功历史 run，创建 section，把稳定字段拖入 section，调整字段宽高、显示模式、label、chip 显示开关，以及 section 的 flow / grid 布局模式
  • MANAGE 使用浏览器 localStorage 保存布局，作用域按 agent_id + version_id 隔离；布局不会写回后端，也不会跨浏览器同步
  • MANAGE 的 grid 模式支持为字段设置显式的 column start / row start，因此可以刻意留空某些网格位置；flow 模式仍保持自动补位
  • MANAGE 只编辑 field layout；tables 继续保持 OPERATE 中的独立 pane 展示和 bbox 联动，不进入布局编辑器
  • 当字段身份无法稳定区分时，这些字段会以 ambiguous 状态展示给用户查看，但不会进入持久化布局
  • OPERATE 现在按 sectioned form 渲染字段，未放入 section 的字段会进入 unplaced 区域；隐藏字段不会在 OPERATE 中展示
  • OPERATE 的字段值修正会先作为浏览器本地草稿按 agent_id + run_id 保存，刷新后可恢复；只有在 footer 中点击 Approve & Sync 并确认后，字段变更才会通过 canonical field-review PATCH 写回后端
  • footer 左侧现在是文件级 pager，序号对应的是当前 workspace 待审队列里的位置；该队列由后端 pending_field_count > 0 推导，成功 sync 后如果当前 run 已无 pending 字段，会自动从工作区消失并切到下一个待审文件
  • 表格单元编辑目前仍只有浏览器本地草稿，不会随 Approve & Sync 一起提交；footer 会把这类 local-only 变更单独列出来
  • MANAGE 仍不是全字段审阅工具；history inspector 会无视 layout 隐藏状态，单独承担“查看全部字段并继续修订”的职责

前端结构

  • outlook-index/src/components/fusion/FusionWorkspace.tsx
  • 工作台主状态：runtime agent、runtime detail、upload slot、run、polling、history、字段 timeline、bbox 选中态
  • outlook-index/src/components/fusion/FusionResultPane.tsx
  • 结果 pane 与 history inspector：run 列表、全字段修订入口、单字段 revision timeline
  • outlook-index/src/manage/ManagePage.tsx
  • 布局编辑器：section 管理、字段拖拽、字段展示设置、浏览器本地自动保存
  • outlook-index/src/manage/layout-schema.ts
  • 布局 schema 类型与默认规则
  • outlook-index/src/manage/layout-reconcile.ts
  • 选中 run 字段与本地 layout schema 的 reconciliation
  • outlook-index/src/manage/layout-storage.ts
  • 浏览器本地布局读写与容错
  • outlook-index/shared/api/documentRecognition.ts
  • canonical document-recognition runtime/run/field-review 的前端适配层
  • ai_service/document_recognition/interfaces/http/router.py
  • document-recognition HTTP 入口与 admin history 真相源
  • outlook-index/src/lib/fusion-output.ts
  • workspace_output 输出规范化与字段 identity 生成
  • outlook-index/src/components/fusion/FusionSectionedForm.tsx
  • OPERATE 字段 section 渲染
  • outlook-index/src/components/fusion/FusionFieldRenderer.tsx
  • 单字段表单壳层渲染
  • outlook-index/src/components/viewer/*
  • 文档预览与 bbox overlay 组件

本地联调

开发模式下，Vite 会把 /api/* 代理到 VITE_API_PROXY_TARGET，默认是 http://localhost:3000，也就是 demo-backend。

由于 outlook-index 现在使用 multipart 上传，demo-backend 也同步支持把 multipart /document-recognition/runs 请求透传给 ai_service。 同时，当前页面壳层仍使用 admin session 控制 demo 入口，但 /document-recognition/runtime-agents* 与 /document-recognition/runs* 自身不要求登录。

Runtime 选择语义

outlook-index 的 UI 以 agent name 帮助用户选择 runtime，但 API、深链、历史记录和本地布局作用域仍使用稳定的 agent_id。 如果 URL 或 localStorage 中保存的 agent_id 已不在 /document-recognition/runtime-agents 返回列表中，页面会提示该 runtime 已不可用，并要求用户重新按名称选择一个已注册 runtime 后再上传。