From 9b35b8e7a72f437297dd0dc4cb176155bb80749d Mon Sep 17 00:00:00 2001 From: que01 Date: Tue, 13 Oct 2026 17:12:47 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E7=A1=AE=E8=AE=A4=E5=B0=8F=E7=A8=8B?= =?UTF-8?q?=E5=BA=8F=E5=8F=91=E5=B8=83=E4=B8=AD=E5=BF=83=E6=9E=B6=E6=9E=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/adr/0023-wechat-miniapp-release.md | 76 +++++++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 docs/adr/0023-wechat-miniapp-release.md diff --git a/docs/adr/0023-wechat-miniapp-release.md b/docs/adr/0023-wechat-miniapp-release.md new file mode 100644 index 0000000..6bfbce9 --- /dev/null +++ b/docs/adr/0023-wechat-miniapp-release.md @@ -0,0 +1,76 @@ +# 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。 + +## 后果 + +后台可以成为小程序发布的统一入口,但仍需微信审核,不可能保证点击后立即上线。系统会增加发布任务、凭证和审计维护成本;换取可追踪、可重试、可审计的机械流程,并避免每次内容编辑都人工重新上传代码。