文档生命周期
说明 Numora 当前内部 OCR 状态如何映射到未来对外 API 的 document.status 模型。
范围
本页说明文档在 Numora 中的流转过程。
同时会明确区分两层状态：
- 当前应用内部已经在使用的 OCR 状态
- 未来对外 API 暴露的标准化
document.status
为什么会有两层状态
当前 Numora 应用存储的是偏 OCR 子系统的内部状态，它们更直接反映提取与复核链路。
对外 API 则应暴露一组更小、更稳定的状态模型，方便外部开发者理解，也避免泄露内部实现细节。
当前内部 OCR 状态
当前应用内部使用以下 OCR 状态：
pendingprocessingfor_reviewreviewedfailed
这些值描述的是现有 OCR 子系统中的提取与复核流程。
对外 document.status 模型
对外 API 应将内部状态归一化为以下 document.status：
processingreview_requiredreviewedpush_pendingpush_succeededpush_failedfailed
在首个公开版本里，前 3 个核心状态通常就足以覆盖文档处理主链路。push_* 状态则用于后续把下游回写结果也合并进文档资源时。
状态映射
| 当前内部 OCR 状态 | 未来对外 document.status | 含义 |
|---|---|---|
pending | processing | 文档已经被接收，但提取任务还未完成。 |
processing | processing | OCR 提取或后台处理仍在进行中。 |
for_review | review_required | 提取已经完成，文档正在等待人工复核或确认。 |
reviewed | reviewed | 人工复核已经完成，结果已被确认。 |
failed | failed | OCR 提取或必要处理步骤失败。 |
未来的回写状态扩展
当对外 API 开始在文档资源上暴露下游交付状态时，reviewed 之后可能进一步扩展为：
push_pendingpush_succeededpush_failed
这些状态描述的是“结果写入下游系统”的执行情况，而不是 OCR 提取本身。
推荐生命周期路径
提取并复核
最常见的生命周期是：
pending -> processing -> for_review -> reviewed
对外 API 视角下可归一化为：
processing -> review_required -> reviewed
提取失败
如果 OCR 提取失败：
pending -> processing -> failed
对外 API 视角下为：
processing -> failed
复核完成并进入下游回写
如果文档后续还会进入写回流程：
pending -> processing -> for_review -> reviewed -> push_pending -> push_succeeded
或者：
pending -> processing -> for_review -> reviewed -> push_pending -> push_failed
实现说明
- 当前 OCR 子系统把
for_review、reviewed、failed视为 OCR 维度的终态。 - 对外 API 不应直接把内部 OCR 状态名原样暴露给开发者，只要已经存在更稳定的标准化状态。
- 在对外文档中，
review_required应明确被定义为内部for_review的外部等价状态。