144 lines
8.2 KiB
Markdown
144 lines
8.2 KiB
Markdown
# 阶段 ⑦ 交付与发布（Delivery & Release）
|
||
|
||
> **定义**：让当前结果在**真实交付边界**被接受——真实的评审、必需的 CI、合并、发布——且高风险动作有风险匹配的审批、副作用有可用的回滚/恢复路径。本地测试与 agent 一句"done"属于阶段 ⑥，不属于交付。
|
||
> **输入**：⑥ 已通过的实现（验证记录 + 门禁结果 + 审查结论）。
|
||
> **输出**：已接受的修订 + 构建/安装包 + 发布记录 + 审计。
|
||
> **进入下一阶段（⑧ 学习与沉淀）**：交付边界接受完成、发布记录落档。
|
||
|
||
---
|
||
|
||
## 1. 要求（Requirements）
|
||
|
||
### 1.1 进入条件
|
||
- 阶段 ⑥ 全部质量门通过，无未解决阻塞项。
|
||
|
||
### 1.2 完成条件（DoD）
|
||
- [ ] 真实接受边界（合并/发布/部署）绑定到**当前修订**，有修订级决策证据（不是"跑过 CI"而是"这个 revision 合并了/发布了"）
|
||
- [ ] 每个高风险动作（发布、删除、生产数据、外发、签名）在副作用**之前**获得所需审批并留审计
|
||
- [ ] 实际副作用有风险匹配的回滚/恢复路径（回滚、恢复、重试、补偿、幂等重放、安全中止之一）且含 owner 与后置条件
|
||
- [ ] 发布记录（版本、变更、产物、验证）落档
|
||
|
||
---
|
||
|
||
## 2. 规则（Rules）
|
||
|
||
### 2.1 接受边界
|
||
|
||
| 编号 | 规则 |
|
||
|---|---|
|
||
| R-7.1 | **真实边界证据**：把真实接受决策绑定到当前修订与目标分支/环境。本地测试、自测、agent 完成声明均不是交付证据；外部边界打不开时记 `Unobserved`，不编造缺失的 PR/部署。 |
|
||
| R-7.2 | **合并路径**：改动经默认分支可比较的 diff 进入（分支/PR 或等价受控路径）；直接在默认分支开发、无可评审 base diff 属交付缺陷。 |
|
||
| R-7.3 | **必需检查绑定**：合并前必需检查对最终修订全绿，且与本地命令一致或有明确差异说明。 |
|
||
|
||
### 2.2 高风险审批
|
||
|
||
| 编号 | 规则 |
|
||
|---|---|
|
||
| R-7.4 | 破坏性/特权/外部/不可逆/共享状态/凭据/发布/生产动作，在效果发生**前**取得所需的人或策略 owner 决策；安全拒绝 + 可用升级路径是正确的控制行为，不是失败。 |
|
||
| R-7.5 | 高风险动作留审计：谁、何时、什么、批准人/策略、审计引用。 |
|
||
| R-7.6 | 确认无高风险动作时记 `N/A`（须经检查证明），不允许无理由的 N/A 阻塞结果。 |
|
||
|
||
### 2.3 回滚与恢复
|
||
|
||
| 编号 | 规则 |
|
||
|---|---|
|
||
| R-7.7 | 每个实际副作用有风险比例匹配的回滚/恢复路径，且绑定到受影响资源/入口/owner/后置条件。 |
|
||
| R-7.8 | 回滚/恢复须可验证（安全模拟、演练、可比的保留任务或实际恢复结果）；禁止仅为提高证据强度而执行破坏性回滚。 |
|
||
| R-7.9 | 恢复路径对失败与超时也要可运行（清理不得只在成功路径执行）。 |
|
||
|
||
---
|
||
|
||
## 3. 输出规范
|
||
|
||
### 3.1 发布流程（本仓）
|
||
|
||
> 发布链唯一权威：`docs/release-process.md`（ci-local 门禁 / release.mjs / 四包发布 / pack-audit / install-acceptance / 签名 / OTA）；签名细节 `docs/release-signing.md`；本地最短路径 `docs/local-build-quickstart.md`。以下为阶段 ⑦ 在本仓的落地步骤，任一步非零即中止。
|
||
|
||
```text
|
||
Step 0 离线门禁（提交/合并/发布前必过）
|
||
Windows: build\ci-local.ps1 · macOS/Linux: build/ci-local.sh → run-local-ci.mjs 八步：
|
||
① 删 release/ → ② npm ci 离线干净安装 → ③ npm run ci:check
|
||
（build:verify:runtime → vitest 全量 → build）→ ④ playwright E2E（不重构建）
|
||
→ ⑤ electron-builder --publish never 打安装包 → ⑥ package:audit
|
||
（asar 禁 dist/mac-*、release/、.map/.d.ts/.ts；体积预算 140 MiB）
|
||
→ ⑦ verify-packaged-app（extraResources 五件断言 + 真启动 5s 冒烟）
|
||
→ ⑧ write-build-report（逐产物 SHA-256 → build-report + SHA256SUMS）
|
||
|
||
Step 1 版本与变更（SDK 四包发布时）
|
||
node scripts/release.mjs --registry <内网源URL> [--bump patch|minor|major]
|
||
[--skip-publish] [--dry-run]
|
||
九步编排：install → build（拓扑序 api→agent-sdk→account→web-ui）
|
||
→ sync-web-ui-dist（dist/renderer → packages/web-ui/dist，断言 index.html 字节一致）
|
||
→ test → pack-audit → bump（四包+根 lockstep，dk-* 互引钉新版，再生 lockfile）
|
||
→ publish-sdks.mjs 逐包 npm publish 内网源 → install-acceptance
|
||
→ npm run package
|
||
日常验证用 --dry-run --skip-publish（shouldPublish 独立纯函数，零副作用有测试断言）
|
||
|
||
Step 2 构建安装包 + 产物审计
|
||
npm run package = build + electron-builder --publish never + package:audit + pack:sdks
|
||
审计（scripts/pack-audit.mjs）：tarball 顶层 ⊆ {dist, bin, README, LICENSE, package.json}；
|
||
零测试产物；dk-account 防误发（registry 锁内网 GitLab）；公开三包无 /account/ 路径泄漏
|
||
安装验收（scripts/install-acceptance.mjs）：spawn dk-web → listening banner →
|
||
GET /health 200 + GET / 200 含 <div id="root"> + 入口 JS 200
|
||
|
||
Step 3 签名与公证（对外发布 / CI 打 Git tag 触发）
|
||
build/sign-local.sh（mac/Linux）/ build/sign-local.ps1（Windows）→ run-signing-build.mjs
|
||
（仅 darwin/win32；保留 APPLE_*/CSC_* 变量且不设断网）
|
||
npm ci → build → electron-builder --config.forceCodeSigning=true → package:audit
|
||
→ 验签：mac codesign --verify --deep --strict；win Get-AuthenticodeSignature 双件 Valid
|
||
→ 有 APPLE_APP_SPECIFIC_PASSWORD 时 DMG 公证 + stapler 装订 → 冒烟 + 构建报告
|
||
|
||
Step 4 OTA 更新（走 OTA 通道时）
|
||
npm run ota:manifest（scripts/ota/generate-manifest.mjs）：扫 release/ 安装包算 SHA-256
|
||
→ scripts/ota/latest.json；强制单一版本、单平台唯一；缺平台填全 0（运行侧 A6 守卫拒绝）
|
||
|
||
Step 5 发布记录落档
|
||
build-report + SHA256SUMS（产物校验值）· 版本与变更（release.mjs bump）·
|
||
验证摘要（⑥ 门禁结果绑定修订）· 审批人/审计引用（高风险动作）
|
||
```
|
||
|
||
> 合并/发布边界绑定：改动经默认分支（`build`）可比较的 diff 进入；必需检查（ci-local 全链）对最终修订全绿。本仓无 CHANGELOG/RELEASE_NOTES 文件，版本与变更由 `scripts/release.mjs` 编排。
|
||
|
||
### 3.2 交付记录模板
|
||
|
||
```text
|
||
目标边界： 分支 / 环境 / 发布通道
|
||
修订绑定： 合并/发布的 revision 与决策证据（PR 号 / 发布记录）
|
||
高风险动作： 动作 | 审批人/策略 | 时间 | 审计引用
|
||
回滚路径： 受影响资源 | 路径 | owner | 后置条件 | 验证方式
|
||
验证摘要： ⑥ 的门禁结果绑定
|
||
残余风险： 未覆盖边界、需人工确认项
|
||
```
|
||
|
||
### 3.3 交付物清单
|
||
- 合并/发布证据（绑定修订）
|
||
- 构建产物 + 审计记录（build-report / SHA256SUMS / package:audit 结果）
|
||
- 发布记录（版本/变更/验证/审批）
|
||
- 回滚路径文档（高风险动作必填）
|
||
|
||
---
|
||
|
||
## 4. 反模式
|
||
|
||
- **本地验证冒充交付**：只有本地测试支持交付声明。
|
||
- **先斩后奏的审批**：效果发生了才补审批，或自查自批。
|
||
- **回滚路径悬空**：有"看起来像回滚"的文件/命令，但连不上实际资源/修订/权限/后置条件（文件名匹配不算证据）。
|
||
- **只走发布后自动化**：仅在推到默认分支/发布时跑的检查不算接受时验证。
|
||
- **无边界的高危可达性**：默认路径能触达生产/凭据/破坏性命令而无边界。
|
||
|
||
---
|
||
|
||
## 5. 轻量路径（小改动）
|
||
|
||
- 内部改动：合并路径 + 必需检查即可，无发布/回滚部分（记 N/A 需检查证明）。
|
||
- 任何触达发布/生产/凭据的动作：审批与审计条款不可省略。
|
||
|
||
---
|
||
|
||
## 6. 相关文档
|
||
|
||
- 输入：阶段 ⑥ [06-validation.md](06-validation.md)
|
||
- 发布链唯一权威与签名：`docs/release-process.md`、`docs/release-signing.md`（本仓无 CHANGELOG/RELEASE_NOTES 文件，版本与变更由 `scripts/release.mjs` 编排）
|
||
- 本地/CI 补充：`docs/local-build-quickstart.md`、`docs/ci-runner-setup.md`、`docs/architecture/reproducible-build-baseline.md`
|
||
- 完成后进入：阶段 ⑧ [08-learning.md](08-learning.md)
|