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

39 lines
3.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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。