Files
persionalBrand/docs/adr/0023-wechat-miniapp-release.md

77 lines
3.7 KiB
Markdown
Raw Permalink 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.
# 0023 小程序版本发布中心
## 状态
Accepted
## 背景
当前后台可以发布品牌内容快照,小程序运行时通过生产 API 读取已发布内容。修改头像、主理人姓名等内容不应要求重新上传小程序代码;但小程序代码版本、审核和正式发布目前仍依赖人工操作,发布链路不完整。
微信小程序的代码上传、提交审核和正式发布需要服务端凭证、固定 AppID 以及受控的构建产物。生产 API 不应直接暴露 AppSecret,也不应在 VPS 上临时拉源码构建。
## 决策
新增“小程序发布中心”,由后台管理发布任务和状态;代码构建与微信代码上传优先放在受控的 CI 或专用发布 Worker 中。第一版只支持一个微信 AppID,后续再扩展多品牌或多 AppID。
品牌内容发布和小程序代码发布保持独立:
- 内容发布生成品牌 release snapshot,小程序通过 API 获取最新已发布内容;
- 代码发布生成小程序版本,负责上传代码、提交审核、查询审核状态和正式发布;
- 两者分别记录版本号、操作者、时间和结果,不把内容版本伪装成代码版本。
## 范围
第一阶段包含:
- 微信 AppID、AppSecret 和上传凭证的服务端配置校验;
- 小程序发布任务记录及状态机:`built`、`uploaded`、`under_review`、`rejected`、`approved`、`published`、`failed`;
- 后台发布历史、当前版本、错误信息和可重试操作;
- 发布前的 API 地址、`brandSlug`、模板资源、媒体资源和版本构建检查;
- 后端接口的授权、幂等、审计日志和集成测试。
第二阶段包含:
- 微信代码上传、提交审核、审核状态查询和正式发布;
- 审核通过后的明确确认发布;
- 发布产物校验、构建日志和失败重试。
不包含:
- 让每次品牌内容修改都重新编译小程序;
- 在生产 API VPS 上安装微信开发者工具并临时构建;
- 把 AppSecret、上传密钥或 access token 写入数据库明文、前端或 Git;
- 第一版支持多个微信 AppID 的复杂租户体系。
## 发布状态
发布任务必须按以下方向流转:
`built` -> `uploaded` -> `under_review` -> `approved` -> `published`
失败状态可以记录为 `failed` 并重试;`rejected` 需要修复后重新构建,不允许绕过审核直接发布。重复请求必须复用进行中的任务或安全返回已完成结果。
## 安全与可靠性
- 所有管理接口验证管理员身份和发布权限;
- 微信凭证只通过环境变量或 Secret Manager 注入;
- access token 服务端缓存,不返回浏览器;
- 记录操作者、代码版本、内容版本、微信返回码和 requestId;
- 发布前执行构建、模板、域名和媒体资源检查;
- 发布失败保留构建产物、日志和错误信息,不自动破坏上一线上版本;
- 内容发布和代码发布可以独立回滚或重试。
## 实施顺序
1. 在当前 `main` 的必要修复完成后创建 `feat/wechat-miniapp-release` 分支。
2. 确认微信 AppID、代码上传凭证、CI/Worker 运行位置和权限。
3. 定义数据库模型、API 合约和状态机,先完成授权与幂等测试。
4. 实现服务端微信发布适配器和发布任务。
5. 实现后台发布历史、状态、错误和重试界面。
6. 用测试小程序完成上传、审核和正式发布验证。
7. 通过 staging 验收后,才接入生产 AppID。
## 后果
后台可以成为小程序发布的统一入口,但仍需微信审核,不可能保证点击后立即上线。系统会增加发布任务、凭证和审计维护成本;换取可追踪、可重试、可审计的机械流程,并避免每次内容编辑都人工重新上传代码。