droboticflow/docs/architecture/source-validation-admission.md
Codex 14a84d3015
Some checks are pending
web-ci / checks (push) Waiting to run
web-ci / pool-search-mongo (push) Waiting to run
🛡️ Distinguish historical proof metadata gaps from source conflicts
2026-11-11 17:35:58 -08:00

9.4 KiB
Raw Permalink Blame History

源数据校验与标注准入

2026-11-02:修复文件已接入、后台校验失败而任务仍能领取的问题。接入文件规则见采集布局契约,固定源与媒体校验沿用 ADR 0010。

状态与准入

  • “文件齐全”只证明所选目录的必需对象存在、非空并稳定,不代表 PTS、IMU、视频或 meta 内容有效。
  • 所有标注任务(含旧模板、缺少旧版标志的任务)领取前必须有本任务、组织、项目及 Run 匹配的完整源校验证据:作业为 completed 且包含实际完整校验成功后写入的 sourceFingerprint。仅有旧时间轴的 completed 不构成放行依据。缺记录、缺完整证据、排队、运行或失败均不进入可领取集合;既有后台队列负责实际校验,不在轮询或领取时重复解析整个源文件。
  • 本任务当前切片/送检 outbox 所引用的源证书作业如果排队或失败,同样阻断分配。新 outbox 明确保存私有 sourceIndex 标志;已物化的 materialization.sourceIndex 也构成必须有证书的证据。已知源索引任务缺少所需作业时不放行。
  • 历史物理切片 outbox 也带 sourceFingerprint,该字段单独存在不能证明它已完成源校验。新旧任务均需要完整证据;未知格式、元数据不足或无法完整校验的旧任务保持阻断,不能以旧路径兜底放行。已领取任务的工作区、草稿、归属及审核历史不因此清空或回池。
  • 随机候选列表、可领取数量与最终原子领取都核对同一条件,指定领取也在存储层核对。失败不会清空任务、解除已有归属或重写标注草稿。指定领取以持久化的当前源状态为准;即使 outbox 变化未改变任务版本,陈旧领取快照也不能覆盖新作业。管理员仍可查看异常任务和既有资料。

诊断与恢复

任务详情和状态返回兼容新增字段 sourceValidation:status、code、message、required、retryAllowed。状态为 valid / pending / failed / unverified。frame-timeline 被阻断时返回 422,稳定错误码为 source_validation_pending / source_validation_failed / source_validation_unverified,同一摘要位于 details.sourceValidation。

普通操作者只看到安全的具体事实,例如 IMU 行号、非法类型或视频与时间戳不一致;不透传凭证、路径、堆栈或整段后台日志。源数据提供方负责修复,管理员在确认后重新校验。工作区保留必要阻断提示与恢复操作,不增加常驻教程。

组织管理员调用 POST /api/plugins/annotation-qa/tasks/{id}/source-validation-retries,提交 { "sourceRepaired": true }。服务端再次校验组织和任务权限。已有排队/运行中的校验拒绝重复重置;重新校验不等于已恢复,只有校验完成才能再次分配。

源索引恢复由任务 ID 的校验作业完整验证当前源版本并固定其证书;记录实际成功的 sourceFingerprint 和被替代的旧 outbox 指纹 supersededSourceFingerprint。旧 source-v1:A 作业仍保留失败事实,不以 B 的验证结果把 A 改成成功。该替代只适用于确切旧指纹 A;之后 C 的排队、缺证书或失败不能继承 B 的放行。

修复过程不改写已有切片/标注内容、不替换审核冻结版本、不自动重放旧失败送检。用户可按原流程继续编辑或确认处理;旧处理输入与当前源不一致时仍要求重新确认。

工作台若在已通过的任务中发现新的源校验错误,会按读取时的作业代次把该记录标为失败。新一轮重校验开始后,迟到的旧请求或旧校验器不能覆盖它。存储写入与领取使用既有项目写保护;不持锁解析视频。读取取消、超时或网络故障不作为内容错误撤销准入。

旧任务缺少校验记录或完整证据时显示待校验,不能领取。新增任务自动排入完整校验;已经排队的旧时间轴作业也必须完整校验后才能发布成功证据。既有 completed 记录不会在读取时自动重置、补造指纹或发起大规模回填,需通过明确的重校验入口补验。只有历史 materialization.sourceIndex 标志、没有 outbox 指纹的任务,明确重校验成功且记录当前源指纹后才能恢复;后续出现新 outbox 指纹仍必须核对其校验状态。

自动排队以实际插入新任务为界,Mongo 使用写入结果判定,不先做无锁存在性猜测。已有任务的普通投影更新(包括详情 GET 恢复已完成送检)、状态/历史读取及重启读取,均不为缺失的校验记录补队,不重置已有排队、运行、完成或失败记录。若新任务落库后排队失败,创建操作返回错误,任务保持未核验、不可领取;通过明确的重校验入口恢复,普通读取或投影重试不冒充创建或补验授权。

当前 outbox 带源指纹时,物理切片与源索引模式都必须找到同指纹的完整成功证据:可由任务校验记录或对应的源证书作业提供;源索引模式原有证书要求继续生效。任务的 A 证据不能放行后来 B 的 outbox,明确记录的 supersededSourceFingerprint 仅替代其确指的旧版本,不能延伸至 C。Go 准入、Mongo 聚合、批量状态及详情/时间轴响应使用相同规则;当前证据正在排队或运行时保持待校验,完成但缺少当前版本证据时为未核验,已知失败仍显示失败。

只读委托映射仍可解析已有时间轴,但若没有完整校验所需的合法固定源输出位置,不得标记成功或领取;需要由管理员明确配置输出权限,不能擅自扩大源目录权限。

上线须同时升级 API 与校验器;旧校验器只能产生时间轴成功时,新 API 仍会阻断。历史补验会增加视频解码、源文件读取及固定源副本成本,应先盘点待补验任务,再按现有校验并发分批执行,生产补验需另行授权。严格准入启用后,可领取数可能减少,这是排除未完整校验任务后的结果,不应通过忽略缺证据记录恢复数量。已领取任务保持占位和已保存内容,补验通过后继续原任务,不重跑整条工作流、不自动重放失败送检。

源文件由责任方明确修复;平台不自动改写、舍弃或删除源文件。舍弃仍需原有明确业务操作。

查询成本与兼容

普通轮询只读取状态记录;领取列表和计数按候选身份使用现有 ID 索引,进入聚合前投影必要字段,不传输标注大载荷。没有新增长期权限缓存或生产索引。

本地 1,200 条任务、每条 64 KiB subject 的 Mongo 夹具,原始 subject 共 75 MiB,候选 JSON 为约 0.49 MiB。新增状态关联比原来不做准入判断的计数更贵;实际对照数值见验证记录。该测试不能替代 120 人完整作业验收。

接口新增字段可由旧客户端忽略。恢复作业需要理解 revalidateSource 的新版校验器;旧校验器仅完成时间轴而未提供源指纹证明时,新 API 保持未核验,不据此放行。发布须协调 API、校验器及接入算子版本;未执行生产回填、生产源修复或上线。

2026-11-11:隔离异常任务、旧任务限界过渡

用户确认优先保障正常开工,将看板和查询优化与全面强制补验分开发布。默认仍为严格完整源校验;仅 API 与切片处理器显式设置相同 ANNOTATION_LEGACY_SOURCE_CUTOFF=2026-11-12T00:00:00Z 时启用本次过渡。该 UTC 边界对应洛杉矶 11 月 11 日 16:00,生产配置须随具体发布计划审批。

过渡仅适用于截止时间前创建、状态 completed、没有完整源指纹且未标记完整重校验的旧时间轴,以及没有源索引物化/作业的原物理流程。任何已知失败、排队或运行的关联源作业、跨组织/项目/Run 记录、已知指纹不匹配均继续阻断。新任务、显式完整补验和源索引流程维持严格校验;读取不触发补验。

列表仍返回服务端可领取判定;空 sourceValidationStatus 仅表示没有准入阻断,不是完整源证书。任务详情对过渡记录返回 unverified、required=false,不写造假的 fingerprint,不将后台作业改成成功。异常任务保留工作区、草稿、归属及审核历史,不清空、不自动回池;管理员保留异常查询入口。

后台补验/源修复按独立固定清单及生产数据授权执行;补验状态不通过改写旧时间轴成功证据来隐藏失败。实际补验期间进入严格校验的任务可能暂时阻断,须有明确窗口或使用独立受审查的后台审计方案,不能声称无中断。收紧回严格默认前,先核对旧任务和公共池的真实证书准备度;移除配置会重新阻断尚未完成补验的旧任务,不能盲目回退。

旧时间轴或源作业的空指纹不等于已知非空指纹冲突:两条旧 completed 记录都在截止时间前、均非完整重校验、且没有源索引时,可使用同一过渡规则,仍呈现未完整校验。反之,已有匹配当前 outbox、同组织/项目/Run 的完整源作业证明时,不要求旧时间轴重复持有同一指纹;这是真实完整证明,不是源索引流程的豁免。任何失败、活动作业、非空指纹冲突、显式重校验尚未完成仍阻断。