Releasing Test

发测试环境（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）

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

波次含 sdk/prismer/**（daemon/runtime 源）变更时，cloud 部署不携带 runtime——daemon 拉的是签名 bundle（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 fingerprint）才手动点。
• 桌面：共享 src/app/workspace/** / AppProvider 改动 → renderer 重建义务（npm run dev:desktop:renderer）；桌面 shell OTA 是独立 desktop-test-* tag 轴，本仓不发。
• 发版汇报必须显式回答四问：①本波有无 runtime 源变更 ②是否需要 pack+promote（谁授权 promote）③sandbox 镜像是否重建 ④桌面重建义务。

侧通道操作 runbook（2026-09-07 实操沉淀——检查清单不等于操作手册，逐条照做）

Runtime promote（pack 之后的 HUMAN 门）

• 变量传递的正路：POST /projects/:id/pipeline JSON body 带 variables:[{key,value}] 建新管线（pipeline 级变量）→ 等 pack 成功 → POST /jobs/:id/play 点 promote（继承管线变量）。不要再手点 UI——UI 里忘了填变量就白烧一次 job。
• API 坑：play 只对 manual 状态有效；failed job 再 play = 400 Unplayable Job；retry 不带新变量。form-urlencoded 的 variables[][key] 不会被接受（job 起来但变量空，test -n 秒败）——只用 JSON body。
• approval-id 语义：RUNTIME_RELEASE_APPROVAL_ID 是自由格式审计串（任意非空有意义标识），记录在 promote 动作上；不是某个注册表 id。
• 幂等：pack 脚本对同 identity 的既有 draft 行是 no-op（不重传不降级）——重开管线无副作用。
• 证据：promote 成功后 im_runtime_releases 行 status=ga；daemon 通过 /api/runtime/update/bundle/:version OTA 拉取。
• 审批链全自动（2026-09-07 实测闭环，G1 同构）：runtime_rollout_approval CI job（fix/* 手动）在 ci-home 上一步做完：铸 admin 身份（tanwenxuan@ceresman.com，Nacos test JWT_SECRET + 公网端点 DATABASE_URL 重拼）→ 锚点 work_item 任务（审批必须挂 conversationId/taskId；工作区三级解析：显式 > 名下首个 > 新建 ops-anchor team）→ POST /api/im/approvals（category=ota_rollout + metadata.target 四字段：channel/version/sha256/storageKey，buildContentAddressedRuntimeStorageKey 计算）→ POST decision approve（决定物化，comment 留痕 owner 授权）→ DELETE 锚点任务 → 下载 pack artifact（JOB-TOKEN，job id 指 pack 成功那次）→ publish-daemon-runtime-release.ts --promote-existing --status=ga --approval-id=<id>（前置双 prisma generate；resolve_daemon_release_database_url 锚点给 DB）。id 全程 shell 变量 + 0600 文件，不出 job 不进 artifact（安全复审要求）。
• 回归：test_api_regression CI job 同法：铸 session JWT（mintSessionJwt 全量 claim，test-identity 最小 JWT 会被 apiGuard 拒）→ POST /api/keys 建一次性 key → test-all-apis --env test → DELETE 吊销。curl 全部 --http1.1（CI→test 域 HTTP/2 流 PROTOCOL_ERROR 断连，实测）。