droboticflow/docs/delivery-index-batches.md

4.5 KiB
Raw Permalink Blame History

不可变总 JSON 交付批次

此能力为本地实现,尚未上线;部署及工作流启用以具体发布记录和授权为准。

原生打包需要新 package 镜像,且 PART_INDEX_DELIVERY=true、DELIVERY_JSON_V3=true;源索引修订另需 SOURCE_INDEX_DELIVERY=true。三个开关默认关闭。旧已交付目录保持不变,不能把 v3 补入已完成的旧目录。原生产物通过已有目录发布协议生成两个 JSON 及 worker 完成清单;它不复制媒体。

<冻结项目交付根>/index-batches/<snapshotId>/
  delivery_index.json                    # 本批次最后写入
  <captureId>/
    annotation_manifest.json             # 此采集 part/history 完成后写入
    part0001.json
    part0001.review-history.json
    part0002.json
    part0002.review-history.json

delivery_index.json 的 entries[].path、captures[].manifestPath 相对批次项目根。 annotation_manifest.json 的 entries[].path、parts[].path、reviewHistoryPath 相对采集交付目录。 sourceMetadata.path 与 calibration[].path 相对 capture.prefix 指向的原始采集目录,标定只带真实文件名,不再额外拼 calibration 或采集名。 源索引 sources[].workspaceKey 保留固定修订与 SHA 引用,解析基准为 workspace,不冒充原始 meta 的路径。

主 part 的 captureId 为原始采集文件夹名,partId 为 part 文件夹名,revision 钉住已验收修订。 审核历史只在独立文件。有效 taskLabel/taskLabelId 保留,空值省略。 segments[].contentKind 为 described、invalid_marked、gap_placeholder;内部流转 status 不导出。 classification.descriptionStatus 为:有非无效非空文本 described;全部无效 invalid_only;无效与留空混合且无有效描述 invalid_and_blank;否则 empty_confirmed。contentCounts 给出三种内容数量,绝不把动作数组非空当作有描述。

summary 的片数、时长、验收与最大 acceptedAt 只针对本批次。时长按 taskSplit 的秒区间汇总,验收时间按实际时间值比较。expectedPartCount 来自原始目录完整分页列举,undeliveredParts 和 partial_run/full_run 不等同于“本批次发布已完成”。全舍弃且无交付物的 part 继续走既有 no_deliverables 契约,本批次不把它冒充已交付 part。

管理操作

沿用 tools/drobotic-pull 登录、CSRF 和退出,不在命令参数中放密码。显式选择 package ID,绝不自动猜最新修订或从不同交付目标混合数据。

# 只读预览:打印 snapshotId、根目录和总索引,不写对象存储。
drobotic-pull --api https://platform.example --email admin@example.com \
  --project project-xxx --index-package package-part1 --index-package package-part2

# 审阅预览后用完全相同的选择和 snapshotId 发布;这是明确的存储写操作。
drobotic-pull --api https://platform.example --email admin@example.com \
  --project project-xxx --index-package package-part1 --index-package package-part2 \
  --publish-index <预览的snapshotId>

# 下载指定批次,沿用 SHA 校验、签名刷新与文件级续传。
drobotic-pull --api https://platform.example --email admin@example.com \
  --directory 'bos://bucket/<冻结项目根>/index-batches/<snapshotId>' \
  --connection storage-xxx --output ./deliveries

接口为 GET /api/delivery-index-batches?projectId=...&packageId=...&packageId=... 和 POST /api/delivery-index-batches,请求体 projectId/packageIds/snapshotId。 仅组织管理员可操作,发布连接必须属于当前组织,或具备既有部署映射中明确的交付写授权(连接归属、deliveryPrefixes 和每个来源运行的 writePrefixes 同时匹配);只读委派不提供写权限,原始输入前缀始终不写。目标从冻结 part 目标推导,不能由调用者指定;与原始采集、其他交付目标、启用的接入监听前缀重叠即拒绝。

最多 100 个 part、单 JSON 8 MiB、批次 64 MiB、原始目录列举 50000 对象;超限报错,不静默截断。发布逐对象条件创建并读回逐字节校验;中断后使用同一 snapshotId 重试。没有总索引的半成品不能下载;不自动清理、覆盖旧批次。证据变化返回 409,重新预览。旧批次下载不重新推导“当前最新包”。

合成双 part 示例可用 PYTHONPATH=. python tests/backend/export_delivery_v3_fixture.py <新的本地输出目录> 生成。它使用真实算子入口,明确标记 synthetic,不能当客户真实业务验收。