/releasing-test

name: releasing-test
description: Use when 把任何批次的改动发到 Prismer 测试环境（test.docbrew.cn / APP_ENV=test），或听到「发测试 / 发 test / 上测试环境 / deploy test / 打 ali-k8s-test tag」。涉及 develop 部署、test 迁移通道、runner 节流时必读。

发测试环境（releasing-test）

铁律

**develop 是测试环境的唯一常规通道；`ali-k8s-test-*` tag 是紧急通道。** 违反字面规则就是违反规则本意——不存在「这次情况特殊」。

门槛顺序（逐步过，任何一步红则停；跳步必须记录理由，无理由跳步=违纪）

1. **本地门 = CI check 阶段四件套**（2026-09-04 教训：`npm run check` 只覆盖前两件，本地绿≠CI 绿）：

• `npx eslint . --max-warnings 3591`（**warnings 棘轮**，随债清偿下调；新代码零新警告）
• `npx tsc --noEmit` 0 错
• `npm run test:sandbox:node`（node:test sandbox 套件）
• `npm run acs:e2e-smoke:dry-run`
• 加跑 `npm run test:unit`（vitest 根套件）与本批自带的新测试

2. **分支纪律硬门（三条断言，逐条贴命令输出，不满足不得进步骤 3）**：

• 断言 A：`git fetch origin` 后 `git rev-parse develop origin/develop` 两值相等（本地 develop 不滞后）。⚠️ 本地 develop 检出于**宿主工作树** `/Users/prismer/workspace/pcrefactor/prismercloud`——本工作树不能 checkout develop，须在宿主目录 `git pull --ff-only`
• 断言 B：**基点必须在 develop 第一父线上**（= 从 develop 切出，不是从旧 feature 线续接）。命令：`git rev-list --first-parent origin/develop | grep -qx "$(git merge-base <工作分支> origin/develop)"` 出口 0 才合格。2026-09-07 owner 裁决：拓扑形状就是规范面，**撤销**此前的「内容等价」豁免——tree 无差也不行（实证：avatar 波基点 4bc4b4293 在第二父线=不合格；样例 merge823 第二波基点 9f82c85e3 是第一父线 merge 节点=合格）。不合格 → 从 origin/develop 新切分支，把未并 commits cherry-pick 过去（见下节「切出」）
• 断言 C：`git rev-list --count origin/develop..<工作分支>` 输出 = 本批预期 commit 数（防止把并行在飞/不明内容夹带进 MR）

3. **迁移前置**：比对 `src/im/sql/` 与 test 账本。有 pending → 走下方迁移通道，**先迁后发**；无 → 汇报里显式写「本批无迁移」。 4. **MR**：feature → develop。描述必含四件，缺一件不 merge：

• ①分组清单（每组一行：组名 / 内容 / 关键 SHA）
• ②post-merge ops（迁移是否已上 test；是否需 prisma regen）
• ③桌面影响面（共享 `src/app/workspace/**` 改动 + 桌面重建义务）
• ④既有红归属（known-red 测试列明，不许混进本批）
• merge API 需带 `sha=<源分支 HEAD>`（项目开了防漂移校验）

5. **merge**：MR 合并 → develop push 自动触发 `ali_k8s_deploy_test`（check 阶段全量跑）。**禁止为快直打 tag**。合并成功后**立即**执行本地 develop 同步（不是下次发版的起点动作）：宿主工作树 `/Users/prismer/workspace/pcrefactor/prismercloud` 里 `git fetch origin && git merge --ff-only origin/develop`，贴 `git rev-parse develop origin/develop` 双值相等输出。⚠️ 2026-09-07 违例记录：连续两轮只操作远端 develop、本地 develop 滞后一个 merge 才被发现——本地/远端视图收敛是每次 merge 的收尾义务。 6. **节流**：列全部 running/pending pipelines，只留目标链，其余取消（含 feature push / MR head 派生）。 7. **冒烟 + 留证**：test.docbrew.cn 200 + 本批功能面抽查；raw 证据（管线快照 / 迁移 trace / 保护操作响应）落 `/tmp/<release-name>/` 并在汇报中引用。

分支生命周期（owner 定规：分支形状是验收面）

**规范最小单元形状**（样例 `9f82c85e3 → 51eeb3ad8`，2026-08-27 merge823 波）：

*   <merge> Merge branch 'feature/X' into 'develop'
|\
| * 7±3 个主题聚焦 commits（test+fix/feat 混排，一波一个主题）
|/
*   <上一个 merge 节点>   ← develop 是一条 merge 直线

• **切出**：同一产品主线只维护一个长期 feature/work 分支（CLAUDE.md 分支纪律），**后续修复追加到同一分支、同一 MR 线**，不得为每个修复新建分支名。每波发版前把长期分支**同步到 develop 第一父线**：`scripts/ops/prismer-branch-discipline.sh sync <长期分支>`（ff develop → rebase 长期分支；基点=新 develop tip）。样例 merge823 连续两波=同一分支名，第二波同步到第一波 merge 节点（9f82c85e3，第一父线）后继续——不是新建分支。新分支名只用于**新主题主线**。⚠️ 2026-09-07 违例记录：auth 503 修复为绕开并行会话占用，新开 feature/auth-hydration-503 + 临时 worktree cherry-pick——违反单长期分支纪律（内容经 MR !165 合法入 develop 不追回；教训：并行占用→等安静 sync 长期分支，不另立门户）。
• **多写入者纪律**：并行会话占用同一 worktree/分支时，rebase/sync 类操作必须等其安静；修复类改动**修完立即原子提交**，sync 时机由控制器协调。
• **合入后**：长期分支继续承载下一波——下一波开始前先 sync 到新 develop tip；**载具型 `fix/*`（迁移/热修）用完必删**（解除 API 保护 → 删远端 → 删本地）。无 sync 的连续同名 merge 是僵尸信号（merge 次数应=波次数，每波前都有 sync）。
• **收尾五件事**（每次 merge 后立即做，不留到下次）：①宿主工作树 ff 本地 develop；②工作分支与 develop 的关系收敛（下一波基点=新 develop tip）；③删本轮载具分支；④清本轮产生的孤儿 worktree（`git worktree list` 逐个核对）与 lint-staged stash；⑤切回工作分支确认 `git status` clean（并行会话的在飞文件只列不碰）。

test 迁移通道（本地不可达 PolarDB）

• 本地直连 test 库被白名单拒（`reading initial communication packet` 断连）——不要在本地跑 sync。
• 通道：`fix/<name>-test-migration` 分支（指向同内容）→ **先** API 加保护（Maintainers/40）→ **后** push / API 建管线。顺序反了管线拿不到受保护 NACOS 变量，须取消重建。
• 管线内 manual 双闸：`test_migration_preflight`（dry-run，核对 pending 清单与预期一致）→ `test_migration_apply`。
• PolarDB 雷区：无 `INFORMATION_SCHEMA.CHECK_CONSTRAINTS`。写迁移自问「PolarDB 上成立吗」（`scripts/ops/README-test-migration-pitfalls.md`）。

紧急通道（唯一例外）

仅当 owner 原话授权走紧急通道：tag `ali-k8s-test-YYYYMMDD-v<X.Y.Z>`（X.Y.Z = `cat /VERSION`，同版本重发加 `-rN`），打在 **develop merge 后的 commit** 上。迁移照常前置、节流照常执行、**事后必须补 develop/MR 正规化**。汇报引用 owner 授权原文。 **注意：tag 管线不跑 check 阶段**（`$CI_COMMIT_TAG → when: never`）——紧急通道绕过的不只是可见性，还有 eslint 棘轮/t0/runtime 全部质量门（2026-09-04 实测：tag 通道放行的内容在 develop 通道 check 阶段 6 红 + 14 warnings 超棘轮）。事后正规化 MR 会把这些全数暴露，欠的检查终归要还。

合理化反驳表（2026-09-04 真实违纪沉淀：直打 tag 绕过 develop/MR）

| 借口 | 现实 | |---|---| | 「CLAUDE.md 表里 tag 也是发版路径」 | 表里 tag 行是紧急/受控通道；`ali_k8s_deploy_test` 的 develop 规则才是常规。 | | 「用户说发，我就发」 | 用户授权的是发版动作，不是豁免流程；拿授权当豁免=越权。 | | 「管线绿了=发版成功」 | 管线绿只是构建部署绿；develop/MR/可见性是发版义务的一部分。tag 管线绿更弱——它连 check 阶段都没跑。 | | 「迁移我走了受控通道，流程就没问题」 | 迁移通道与发版通道独立记账，一个合规抵不了另一个越权。 | | 「MR 描述义务太重，先发后补」 | 描述义务是 owner 的审计面；缺了它这次发版不可审计。 | | 「tag 不动共享分支，更轻」 | 「轻」正是它被定为紧急通道的原因——绕过了所有人的可见性。 | | 「本地 npm run check 绿了」 | 本地门 ≠ CI check 门：CI 还跑 sandbox node 套件、acs dry-run、t0 三包、runtime 套件与 warnings 棘轮。本地必须跑等价四件套。 |

Runtime / SDK 变更的双通道发版（cloud deploy ≠ runtime 通道）

波次含 `sdk/prismer/**`（daemon/runtime 源）变更时，**cloud 部署不携带 runtime**——daemon 拉的是签名 bundle（OTA）。两条通道独立记账：

| 通道 | 触发 | 产物 | 覆盖 | |---|---|---|---| | cloud | develop merge → `ali_k8s_deploy_test` | 容器镜像 | Next.js + in-process IM | | runtime | tag `runtime-test-YYYYMMDD-vX.Y.Z` → `pack_runtime_bundle` | 签名 bundle 上传 + `im_runtime_releases` 行（**status=draft**） | daemon/agent pod OTA |

• **`ali-k8s-test-*` tag 不触发 pack_runtime_bundle**（CI `only:` 清单实证）——ACK cloud 发版与 runtime 打包是两个 tag 轴。
• pack 之后还有一道 **HUMAN gate**：`promote_test_runtime_release`（manual，需 `RUNTIME_RELEASE_APPROVAL_ID`，artifact 来自 pack）——draft 对在跑 fleet 零影响，promote 才是生效点。**无 owner 原话授权不得代点/代建 tag**。
• 判据：`git diff $(git merge-base <分支> origin/develop) origin/develop --stat -- sdk/prismer/src` 非空 = 有未走 runtime 通道的 daemon 变更（cloud 已发新、daemon 仍旧 = 版本倾斜；本项目缺 protocolVersion 协商，见 daemon version skew 教训）。
• sandbox 镜像：`build_sandbox_image` manual 挂 `ali-k8s-test/prod` tag——**仅当波次动了镜像内容**（native floor / 系统工具；JS 插件模块不进 image fingerpri