Files
persionalBrand/docs/adr/0030-miniapp-build-upload-attempts.md

3.0 KiB
Raw Permalink Blame History

0030 小程序构建与上传 attempt

状态

已采纳

背景

小程序发布任务原本以一个聚合 status 表达构建、上传、微信审核和发布,同时用 buildStatus 表示有限构建进度。构建和上传请求在 API 进程内同步执行;进程退出可能留下永久 building,重试可能读取共享产物目录中的旧包,不同品牌的并行构建也可能覆盖相同模板目录。

决策

  • 在 MiniAppReleaseTask 上新增独立 uploadStatus 和 reviewStatus,保留现有 status 作为兼容聚合状态,不在本次迁移中破坏旧 API 消费方。
  • 新增 MiniAppReleaseAttempt,每个 build/upload 操作分别有单调序号、随机 lease token、租约过期时间、heartbeat、开始/结束时间、日志、产物路径、微信 external id 和明确终态。
  • 同一任务和阶段最多有一个有效 lease;有效 lease 拒绝并发,过期 lease 被标记 timed_out 后才允许下一次 attempt。只有持有匹配 lease token 的运行可更新或结束 attempt。
  • 构建产物按 brandSlug/templateKey@templateVersion/attemptId 隔离。一次 attempt 只能上传自己的 app.json 产物;不能回退到模板共享目录或其他 attempt 的产物。
  • 构建超时必须终止子进程并落终态;上传沿用隔离子进程和超时机制。进程意外退出时,lease 到期提供恢复边界。
  • 历史 status 可推导的阶段状态由 additive migration 回填;不推断微信审核以外的业务事实。

考虑过的方案

  • 只在现有行上加 buildStatus/uploadStatus:无法区分重试、并发执行和进程重启后的旧执行者,也无法审计每次产物。
  • 将旧 status 直接替换为多维状态:会破坏现有 API Client、Admin 和历史记录兼容,且仍不能表达一次次尝试。
  • 仅靠目录名隔离产物:能避免覆盖,但不能防止数据库并发抢占、过期进程回写或查询终态不一致。

后果

  • API 列表/latest 查询需要包含 attempt 记录;Admin 同时展示聚合状态和各阶段状态。
  • attempt 表随任务删除级联,历史任务保留其 attempt 作为审计证据。
  • 目前 Admin 触发请求仍同步等待 build/upload 结束;lease 与持久化记录为后续 worker/队列化提供基础,但本 ADR 不宣称已实现异步 worker 或重启后自动恢复执行。
  • 真实微信上传成功必须以返回的 weappUploadId 作为外部证据;本地 build 成功不等于上传或审核成功。

迁移计划

  1. additive migration 新增阶段 enum、attempt 表及历史状态回填,旧读路径继续工作。
  2. 所有新 build/upload 路径写 attempt;Admin 和 shared client 同步读取新字段。
  3. 完成 API/worker 重启、并行品牌、超时与旧产物故障注入,并记录实际微信上传结果。
  4. 只有在调用方迁移完成并有 API contract test 后,才另行评估移除聚合 status 和旧 build 兼容字段;删除必须使用单独 migration。