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

3.7 KiB
Raw Blame History

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。

后果

后台可以成为小程序发布的统一入口,但仍需微信审核,不可能保证点击后立即上线。系统会增加发布任务、凭证和审计维护成本;换取可追踪、可重试、可审计的机械流程,并避免每次内容编辑都人工重新上传代码。