# BitBybit CAD Studio 发布 Runbook

基线：FreeCAD `1.1.1`（提交 `0108fd4b4850cc46e625b60e53cea7a7bbe69f8d`），Chrome `150`，COOP/COEP 隔离上下文，sqlite-opfs 持久化。

## 发布前

1. 使用锁定 Node/npm 环境运行 `./npmw run verify`。
2. 确认 `./npmw run check:release-closure` 输出 G0-G9 全部通过。
3. 受控本地发布使用 `.secrets/release-signing-private.pem`（权限 `600`，已被 Git 忽略）和默认 key id `bitbybit-local-release-2026`；先执行 `./npmw run check:release-signing-key`，再执行 `./npmw run build && ./npmw run generate:release-artifacts`。CI/发布机也可注入 `RELEASE_SIGNING_PRIVATE_KEY`、`RELEASE_SIGNING_KEY_ID`，入口会校验其 Ed25519 类型及与仓库公钥的一致性。
4. 只发布 `dist/`、`config/sbom.cdx.json`、`config/release-artifacts.json` 和对应公钥；私钥不得进入仓库或静态资源。密钥轮换必须同时更新受控私钥和 `config/release-signing-public.pem`，然后重新生成清单。

## 部署

保持 `Cross-Origin-Opener-Policy: same-origin`、`Cross-Origin-Embedder-Policy: require-corp`、`Cross-Origin-Resource-Policy: same-origin`、`Permissions-Policy` 和 CSP。Service Worker cache 名称由构建产物固定为 `bitbybit-cad-shell-v1`；哈希资源和 OCCT/SQLite WASM 必须存在于 precache。

## 升级、回滚与诊断

先保留旧 cache 和旧发布清单，再切换新版本。首装/升级/离线/缓存清理使用 `./npmw run test:chrome-offline` 复核；项目 schema 迁移与整事务回滚使用 `./npmw run check:project-migration` 和 `./npmw run check:chrome-opfs-migration`。若签名或 SBOM 校验失败，停止切换并回滚至上一份已签名清单；不得以 unsigned-development 产物替代。

出现 Worker/WASM 崩溃或 stale 结果时运行 `./npmw run check:chrome-fault-injection`，确认恢复状态和资源计数；出现格式/权限问题时运行 `./npmw run check:chrome-security`。浏览器不满足隔离或 OPFS 能力时显示明确降级/导出路径，不伪装为完整兼容。
