BeeX 配置与版本统一发布流程
管理后台中所有会影响用户、资金或客户端行为的配置与版本，都必须沿同一条晋级链路发布。测试环境是唯一编辑入口，生产环境只接收已经验收的候选版本。
1. 修改测试配置仅在
id-test 编辑并保存2. 发布测试冻结测试快照并完成测试环境验收
3. 转移线上复制已验收快照，生成生产候选
4. 灰度测试在生产环境验证候选，不允许跳过
5. 正式发布验收通过后切换为生产全量版本
一、统一原则
| 规则 | 系统行为 | 解决的问题 |
|---|---|---|
| 测试环境是唯一编辑入口 | 生产环境隐藏编辑和回滚入口；后端同时拒绝生产环境直接保存。 | 避免运营绕过测试直接修改线上资金规则。 |
| 测试发布生成不可变快照 | 记录字段值、来源规则版本、SHA256、操作人和时间。 | 保证线上候选与测试通过的内容一致。 |
| 转移线上不等于发布 | 只生成 PROD_DRAFT 或生产 DRAFT，不会立即影响线上用户。 | 避免“转移”被误解为全量上线。 |
| 必须经过灰度阶段 | 后端禁止从生产候选直接正式发布。 | 把线上真实环境验收变成硬门禁。 |
| 操作全程可追溯 | 保存来源版本、发布人、测试人、灰度人、正式发布人和各阶段时间。 | 出现资金或客户端问题时可以还原发布过程。 |
不能做：在生产环境直接编辑配置、把测试通过直接当成线上发布、跳过生产灰度、重新手工录入一份“看起来相同”的线上配置。
二、状态机
stateDiagram-v2
[*] --> TEST_EDITING: "测试环境编辑"
TEST_EDITING --> TEST_PUBLISHED: "发布测试 / 冻结快照"
TEST_PUBLISHED --> PROD_DRAFT: "转移线上"
PROD_DRAFT --> GRAY: "开始灰度"
GRAY --> PUBLISHED: "正式发布"
TEST_EDITING --> TEST_EDITING: "继续修改"
TEST_PUBLISHED --> TEST_EDITING: "发现问题，回测试修改"
PROD_DRAFT --> TEST_EDITING: "候选不通过，回测试重新发布"
GRAY --> TEST_EDITING: "灰度不通过，停止候选并回测试"
| 阶段 | 配置中心 | H5 离线包 | 是否影响生产全量用户 |
|---|---|---|---|
| TEST_PUBLISHED | 测试配置快照已冻结 | 测试包已验收并发布到测试版本池 | 否 |
| PROD_DRAFT / DRAFT | 生产候选快照 | 生产候选包 | 否 |
| GRAY | 候选快照进入生产验收阶段 | 白名单或百分比用户可命中 | 配置：否；H5：仅灰度人群 |
| PUBLISHED | 全量生产规则生效 | 普通生产用户可命中 | 是 |
三、配置中心发布
- 在管理后台切换到“印尼测试”，编辑配置并保存。保存只修改测试环境。
- 点击“发布测试”，填写测试说明。服务端读取当前模块值，生成带 SHA256 的
TEST_PUBLISHED快照。 - 测试通过后点击“转移线上”。生产管理服务校验来源环境、阶段和 SHA256，只创建
PROD_DRAFT候选。 - 切换到“印尼正式”，在“生产发布对照”中同时查看“线上生效值”和“生产候选值”。页面逐项标出差异、来源测试版本、操作人、转移时间，以及随快照转移的测试账号覆盖等结构化配置；确认无误后点击“开始灰度”。
- 完成生产环境验收后点击“正式发布”；服务端才把候选值写入生产生效规则。
配置灰度的当前真实含义：佣金、提现等配置目前是全局规则，没有按用户选择配置版本的能力。因此
GRAY 阶段只锁定候选快照并记录生产验收，不能提前写入生产规则。生产页面左侧明确标识“当前用户正在使用”的线上值，右侧展示待发布候选；只有 PUBLISHED 才会全量生效。这是资金安全门禁，不是假装存在用户级灰度。配置发布接口
| 动作 | 接口 | 门禁 |
|---|---|---|
| 发布测试 | POST /api/v1/admin/config-console/modules/{moduleKey}/test-publish | 只能在测试环境 |
| 转移线上 | POST /api/v1/admin/config-console/modules/{moduleKey}/import-production | 来源必须为 TEST_PUBLISHED，SHA256 必须一致 |
| 开始灰度 | POST /api/v1/admin/config-console/releases/{releaseId}/gray | 只能由 PROD_DRAFT 进入 |
| 正式发布 | POST /api/v1/admin/config-console/releases/{releaseId}/publish | 只能由 GRAY 进入 |
四、H5 离线包发布
- 云效统一流水线
4987658checkout 一次 commit，并用同一个 H5 版本号同时生成INTERNAL与RELEASE两个 ZIP。 INTERNAL只适用于 Native88.88.88，包内包含生产与 id-test 两组配置并默认生产；RELEASE只包含生产配置。- 测试人员用 88 App 安装 INTERNAL，分别验证生产与 id-test，填写设备、Native 版本和说明，标记
TEST_PASSED后发布内部版本。 - 点击“转移线上”时，管理后台查找同版本、同完整 commit 的预构建 RELEASE 候选。候选不存在或 commit 不同则失败，不允许二次构建。
- 在正式 RELEASE 版本池配置用户、联盟码、设备白名单或 1-99% 稳定比例，候选进入
GRAY。 - 灰度验收通过后点击“正式发布”，RELEASE 状态进入
PUBLISHED。
H5 是真实灰度：生产
GRAY 的 RELEASE 只对命中白名单或稳定百分比的人群下发；其他正式 App 继续使用上一版 PUBLISHED。两个维度必须分开：Native 版本决定包渠道：精确
88.88.88 永远拿 INTERNAL，其余版本永远拿 RELEASE；API Host 与请求 envCode 不得决定渠道。只有 INTERNAL 在启动后读取 Native 当前业务环境并选择包内配置。权威版本池：INTERNAL 的发布状态以内部版本池为准，RELEASE 的发布与灰度状态以线上版本池为准。请求落到非权威 API 时由服务端携带内部令牌转发查询；转发失败只返回“暂无更新”，不得改查另一个渠道。
五、操作时序
sequenceDiagram
actor Operator as "运营/研发"
participant CI as "统一 H5 流水线"
participant Internal as "INTERNAL 版本池"
participant Release as "RELEASE 版本池"
participant App88 as "88.88.88 App"
participant ProdApp as "正式 App"
Operator->>CI: "指定一个 commit，运行一次"
CI->>Internal: "登记 INTERNAL"
CI->>Release: "登记同版本、同 commit RELEASE 候选"
Operator->>Internal: "发布内部版本并验收"
App88->>Internal: "任一 API 内部路由到 INTERNAL 权威版本池"
Internal-->>App88: "只下发 INTERNAL"
Operator->>Release: "转移线上：只关联预构建候选"
Release->>Release: "校验同版本、同 commit，不重建"
Operator->>Release: "开始灰度"
ProdApp->>Release: "任一 API 内部路由到 RELEASE 权威版本池"
Release-->>ProdApp: "命中灰度目标才下发新 RELEASE"
Operator->>Release: "正式发布"
Release-->>ProdApp: "全量下发 RELEASE"
六、验收清单
| 检查项 | 通过标准 |
|---|---|
| 生产直接编辑 | 页面无编辑/回滚按钮，绕过页面调用接口仍被拒绝。 |
| 测试发布 | 发布记录包含模块值、SHA256、来源版本、操作人和时间。 |
| 重复转移 | 同一测试发布记录重复点击不会产生不同的生产候选。 |
| 跳级发布 | PROD_DRAFT 不能直接正式发布；必须先进入 GRAY。 |
| 配置灰度安全 | 点击“开始灰度”不修改生产全量规则；正式发布时才写入。 |
| H5 灰度隔离 | 灰度用户拿新包，非灰度用户继续拿旧 PUBLISHED。 |
| 审计 | 每个阶段都能看到操作人、时间、说明和来源版本。 |