从识别到落库，中间不是一步赋值，而是一组可验证的业务闸门。
摘要｜在 Microi吾码AI 的 OCR 链路里，Code=1 表示请求已经通过租户绑定、供应商调用、响应解析与统一结果构造；它不是“这张票据可以入账”的业务判决。真正落库前，还要补上内容非空、字段规则、交叉核对、主数据匹配、幂等、权限、事务与审计。
✦先把 Code=1 翻译准确
最危险的误解，是把技术成功当成业务真实。当前 OCR 实现会在文件校验、租户配置解析、供应商调用、响应解析与置信度过滤完成后返回统一结果；这一刻只说明链路给出了可消费的数据。
边界｜Code=1 回答的是“网关是否成功产出结果”，没有回答“供应商是谁、金额是否正确、单据是否重复、当前用户是否有权写这张业务表”。
确定性流程图：业务判断位于 OCR 网关出口之后。
var ocr = await V8.OCR.Recognize({ FileByteBase64: V8.Param.FileByteBase64, FileName: V8.Param.FileName }); if (!ocr || ocr.Code !== 1 || !ocr.Data || !ocr.Data.Text) { return { Code: 0, Msg: '未得到可进入业务校验的文本。' }; }✦统一结果解决了接口问题，不解决领域问题
公开请求模型只接收文件、方向校正与阈值等安全参数；Endpoint、Headers、ApiKey、Provider 不在调用参数中。租户包装器还会强制回填当前 OsClient，避免脚本把 OCR 变成任意 HTTP 代理。
返回模型提供 Text、AverageConfidence、PageCount、Pages、Regions、Polygon 与 TraceId。这些字段适合继续处理，但没有发票号码唯一性、供应商主数据、税额勾稽、订单归属或审批状态等业务字段。
统一协议提升可用性，但不会凭空生成行业语义。
源码事实｜OCR 模块的主链路负责 HTTP、解析、归一、阈值、大小与超时边界；在该模块中没有 FormEngine 新增、更新、删除或 SQL 写入。
✦一个反直觉边界：成功也可能没有可用文本
当前源码先构造 Code=1 的统一结果，再执行 MinimumConfidence 过滤。过滤会重建每页 Regions、Text 与平均置信度，却不会把 Code 改成失败。由此可以推导：若所有区域都低于阈值，结果可能仍为 Code=1，但 Text 为空。
源码静态证据：空文本边界成立；现有用例只覆盖部分过滤，未直接覆盖“全部过滤为空”。
- 检查 Data 与 Text 是否存在，不能只看 Code。
- 检查目标字段是否从明确区域映射，而不是仅靠整段文本猜测。
- 低于业务阈值时转人工复核，不要静默写入空值或默认值。
不要外推｜“源码允许出现这个边界”不等于“生产中一定发生过”；没有真实供应商与生产样本证据时，文章只陈述可证明的控制流。
✦写表前，至少补齐五道业务闸门
OCR 结果应被视为候选事实。可落库状态应由业务服务或受控接口引擎计算，而不是由识别返回码直接触发。下面五步适用于票据、合同、证照和质检单等常见场景。
工程建议：校验、核对、主数据、幂等权限、事务审计逐步收敛。
- 字段规则：必填、类型、长度、日期与金额范围正确。
- 交叉核对：含税金额、税额、明细合计与票面关系一致。
- 主数据匹配：供应商、客户、物料和组织编码来自权威记录。
- 幂等与权限：同一单据只产生一个结果，且操作者拥有表与行权限。
- 事务与审计：写入、关联、状态变化和复核意见可追溯。
职责｜这些闸门是接入方的业务设计建议，不是把现有 V8.OCR 描述成已经内置发票验真、主数据匹配或自动入账。
✦幂等、权限和事务要独立设计
文件上传重试、移动网络重放或人工重复点击，都可能让同一内容被识别多次。幂等键应来自稳定业务标识与文件指纹，状态机至少区分 Received、Recognized、NeedsReview、Committed 与 Rejected。
错误也应分层：网络超时可以在幂等保护下重试；响应结构异常需要隔离并告警；字段冲突进入人工复核；权限不足则直接拒绝。把这些情况全部折叠成一次“识别失败”，会让重试策略、责任归属和审计证据同时失真。
BusinessWritable = TechnicalSuccess AND NonEmptyContent AND DomainValidationPassed AND MasterDataMatched AND Authorized AND IdempotencyWon只有抢占幂等状态的一次请求可以进入事务；其余请求读取已存在状态。权限必须从当前可信身份与目标记录归属重新计算，不能相信 OCR 文本里的部门、姓名或账号。
审计最小集｜建议记录文件指纹、OCR TraceId、规则版本、人工复核人、写入目标 Id 与最终状态；不要在普通日志中保存完整 Base64、密钥或未经脱敏的全文。
✦这次证据能证明到哪里
本地真实证据：既有 Release 程序集 8/8；当前源码测试未启动，原因是无关 API 文件编译错误。
归档的 Release 测试结果包含 8 个 Passed：覆盖 Jint await、基础与高稳定协议归一、页数上限、部分置信度过滤、公开契约和升级幂等。它证明该程序集中的这些用例通过，不代表当前源码已重新编译通过。
对当前源码执行同一筛选测试时，OCR 等依赖项目先成功编译，随后 Microi.net.Api 的 GlobalExceptionHandler.cs 第 208 行出现 CS0117，测试进程因此没有启动。该错误与 OCR 代码不在同一文件，也不能被忽略后冒充“当前源码 8/8”。
证据边界：源码静态事实、既有程序集测试、当前构建状态、真实生产行为分别陈述。
尚未验证｜本轮没有连接真实 PaddleX 服务，没有测 PDF、旋转图、多页极限或生产识别准确率；任何命中率、延迟与线上稳定性数字都不在结论中。
✦把接入拆成“识别”和“提交”两段
更稳妥的落地方式，是让识别接口只产生候选记录与 TraceId，让独立校验步骤产生业务决定，再由受权提交动作完成事务写入。这样既能复核，也能重放规则，而不会重复调用供应商。
- Recognize：保存最小候选结果与识别状态。
- Validate：执行领域规则、主数据匹配与风险分流。
- Commit：校验权限和幂等状态，在事务内写表并留痕。
- Review：低置信或冲突数据进入人工队列后再提交。
结论｜Code=1 是可信处理链的起点，不是业务信任的终点。只有当识别、校验、授权、幂等、事务与审计全部闭环，OCR 数据才具备写入业务表的资格。
本文7张技术图卡背景由AI生成；流程图与测试卡片为基于当前工作区源码和测试结果的确定性渲染。
