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