复核与确认

说明 Numora 文档的复核模型、确认语义、并发控制与下游执行前置条件。

范围

本页说明 Numora 在 OCR 提取完成后如何处理人工复核。

内容包括：

status 与 review_state 的区别
approve 动作的含义
reject 与 retry-push 的适用场景
如何通过乐观并发控制避免基于旧数据确认

两层复核语义

document 资源中有两层相关但不同的概念：

status 表示文档当前处于生命周期的哪个阶段
review_state 表示复核人员已经显式确认了哪些内容

例如，一个文档仍然可能处于 review_required，但 review_state 已经记录了部分字段或部分行项目已被人工确认。

`review_state` 对象

对外 review_state 应为 null 或标准化对象：

{
  "version": 1,
  "confirmed_general_field_names": ["invoice_number", "invoice_date"],
  "confirmed_line_item_ids": ["li_1", "li_2"]
}

约定：

version 用于后续扩展，避免未来变更破坏客户端。
confirmed_general_field_names 保存文档结果中的标准化字段名。
confirmed_line_item_ids 保存结果中返回的稳定行项目标识。
如果两个数组都为空，标准化后应返回 null。

当前复核语义

当前 Numora 应用已经遵循以下规则：

OCR 提取完成后，文档会进入内部 for_review，对外应映射为 review_required
执行确认后，文档会被标记为 reviewed 且 finalized
对已确认文档再次编辑，会把它重新送回复核队列
只有 reviewed 且 finalized 的文档，才允许进入下游推送或人工触发工作流

关于生命周期状态映射，请继续阅读文档生命周期。

Approve 动作

POST /v1/documents/{id}/actions/approve

当提取结果已经可以作为最终确认结果时，使用这个动作。

建议请求体：

{
  "expected_updated_at": "2026-03-21T14:20:00.000Z",
  "review_state": {
    "version": 1,
    "confirmed_general_field_names": ["invoice_number", "invoice_date"],
    "confirmed_line_item_ids": ["li_1"]
  }
}

建议响应体：

{
  "id": "doc_01jpwq4q9m7q4q2k8dax1x1q5n",
  "status": "reviewed",
  "updated_at": "2026-03-21T14:20:03.119Z",
  "review_state": {
    "version": 1,
    "confirmed_general_field_names": ["invoice_number", "invoice_date"],
    "confirmed_line_item_ids": ["li_1"]
  }
}

approve 应满足幂等语义。对同一份最新文档重复执行相同确认，不应产生重复的下游副作用。

Reject 与 Retry-Push 动作

Numora 在公开 document 资源上预留了三个动作动词：

approve：将复核结果正式确认
reject：将文档送回 review_required，取消 finalized，并阻止新的下游交付
retry-push：对已经 reviewed 的文档重新发起下游交付，并创建新的排队 run

在当前开发者预览阶段：

approve：确认结果，并允许 reviewed 后的自动化执行
reject：把文档退回 review_required
retry-push：为已 reviewed 的文档重新排队下游 workflow run，并把 document.status 临时映射为 push_pending

并发控制

建议客户端对复核动作统一使用乐观并发控制。

推荐模式：

先读取最新的 document 或 result 资源
保存其中的 updated_at
执行 approve 时把它作为 expected_updated_at 一并提交
如果服务端返回 409 conflict，先重新拉取最新资源，再决定是否重试

建议冲突响应：

{
  "error": {
    "code": "conflict",
    "message": "approve conflict",
    "request_id": "req_01jpwqkshg6x8j9k9j29m8n0n4"
  },
  "updated_at": "2026-03-21T14:21:12.000Z"
}

下游执行门槛

确认动作不只是一个界面标签，它决定文档是否可以进入下游执行。

对于首阶段 CRM 交付主路径，这也意味着客户端可以直接从“已 reviewed 的文档 + delivery outbox”开始，而不必把 POST /v1/documents 当作必经第一步。

推荐契约为：

review_required 文档仍可继续修正或补充
reviewed 文档被视为已确认结果
对已经确认过的文档再次编辑，应回退到 review_required
下游推送和人工触发工作流应要求文档同时满足 reviewed 与 finalized