Cheng Zhou
130 lines
7.3 KiB
Markdown
130 lines
7.3 KiB
Markdown
# CTMS Desktop Release Stabilization Checklist
|
||
|
||
状态: `active`
|
||
适用范围: Web 与 macOS Desktop 统一客户端发布
|
||
最后更新: `2026-07-01`
|
||
|
||
本清单用于第一、二阶段桌面端能力完成后的准发布稳定化。它不引入离线登录、本地业务数据存储、内嵌后端服务或离线同步。
|
||
|
||
## 1. 发布链路门禁
|
||
|
||
发布候选提交必须从同一 Git 提交构建 Web 与 Desktop 制品，并完成以下检查：
|
||
|
||
```bash
|
||
cd frontend
|
||
npm ci
|
||
npm run version:check
|
||
npm run release:env:check
|
||
npm run runtime:check
|
||
npm run desktop:release:check
|
||
npm run ui:contract
|
||
npm run type-check
|
||
npm run test:unit
|
||
npm run build
|
||
npm run desktop:build:app
|
||
```
|
||
|
||
正式发布还必须确认：
|
||
|
||
- [ ] `frontend/package.json`、`package-lock.json`、Tauri 配置、Cargo manifest/lock 版本一致。
|
||
- [ ] `VITE_BUILD_CHANNEL=release` 和 `VITE_BUILD_COMMIT=<release tag commit>` 由 CI 注入，且 `npm run release:env:check` 通过。
|
||
- [ ] macOS app 已签名和公证。
|
||
- [ ] updater `.sig` 使用组织 CI secret 或密钥库中的私钥生成，私钥未进入仓库。
|
||
- [ ] 设置 `TAURI_SIGNING_PRIVATE_KEY`、`TAURI_SIGNING_PRIVATE_KEY_PASSWORD` 和 Apple 签名/公证变量后，以 `REQUIRE_DESKTOP_SIGNING=true` 再次执行 `npm run release:env:check`，随后执行 `npm run desktop:build -- --bundles app`。
|
||
- [ ] 正式 updater feed 执行 `npm run desktop:update-feed:check -- --feed <latest.json> --artifacts-dir <artifact-dir>`。
|
||
- [ ] 不可变制品先上传，`latest.json` 最后原子替换；若 feed 校验未通过，不替换线上 `latest.json`。
|
||
- [ ] Web 与 Desktop 制品记录同一产品版本、Git 标签和完整提交 SHA。
|
||
|
||
## 2. 安全边界复审
|
||
|
||
自动门禁 `npm run desktop:release:check` 覆盖以下静态约束：
|
||
|
||
- [ ] Tauri bundle 启用 `app`、`dmg` 和 updater artifacts。
|
||
- [ ] updater public key 已配置。
|
||
- [ ] CSP 禁止 wildcard source、`unsafe-eval`、宽泛 HTTP API 访问和 `object-src`。
|
||
- [ ] Tauri capability 不包含 shell 权限、持久文件系统 scope 或宽泛目录读写。
|
||
- [ ] 文件系统与 opener scope 只允许 `$TEMP/ctms-desktop/**`。
|
||
- [ ] 单实例插件先于其他桌面插件注册。
|
||
- [ ] Tauri command 白名单仅包含凭据和更新命令。
|
||
- [ ] 前端源码不通过 query string 传递 token。
|
||
- [ ] `ctms_token` 只允许由 `secureSessionStorage` 处理。
|
||
- [ ] 系统通知只能通过 `frontend/src/runtime/notifications.ts` 发送，标题和正文保持通用。
|
||
- [ ] CI release 候选 workflow 包含 version/runtime/desktop/ui/type/unit/build/desktop app smoke 门禁。
|
||
|
||
人工复审还必须确认：
|
||
|
||
- [ ] token 不出现在 URL、日志、系统通知正文、下载链接或持久化业务缓存中。
|
||
- [ ] 桌面端通知正文只显示通用内容，不包含项目、文件或版本详情。
|
||
- [ ] 服务端权限、审计和业务数据持久化仍由 FastAPI 后端裁决。
|
||
- [ ] Web 运行时不直接导入 Tauri API。
|
||
|
||
## 3. 端到端回归矩阵
|
||
|
||
| 场景 | Web | macOS Desktop | 预期 |
|
||
| --- | --- | --- | --- |
|
||
| 登录与项目恢复 | 必测 | 必测 | 登录成功后恢复可访问项目；401 后重新登录 |
|
||
| 30 天免登录 | 不适用 | 必测 | 关闭并重启 App 后复用系统凭据库中的后端在线会话；超过 30 天或 `/me` 校验失败后重新登录 |
|
||
| 服务器地址未配置 | 不适用 | 必测 | 自动进入服务器设置，不进入业务页 |
|
||
| 服务器地址切换 | 不适用 | 必测 | 清除当前会话和项目上下文，要求重新登录 |
|
||
| 服务端不可达 | 必测 | 必测 | 显示可恢复错误，不进入离线模式 |
|
||
| 附件上传 | 必测 | 必测 | Web 使用浏览器文件选择，Desktop 使用原生选择 |
|
||
| 附件下载/保存/打开 | 必测 | 必测 | 使用 Authorization header；无 `?token=` |
|
||
| 临时文件清理 | 不适用 | 必测 | 启动时清理 `$TEMP/ctms-desktop/**` |
|
||
| 系统通知开启 | 不适用 | 必测 | 用户主动开启后请求 OS 权限并创建订阅 |
|
||
| 系统通知拒绝 | 不适用 | 必测 | 开关回退，提示系统权限未开启 |
|
||
| 通知领取与 ack | 不适用 | 必测 | 显示成功后 ack；失败等待租约重试 |
|
||
| 单实例重复启动 | 不适用 | 必测 | 恢复、显示并聚焦主窗口 |
|
||
| 自动更新检查 | 不适用 | 必测 | release 通道按当前 CTMS origin 派生清单 |
|
||
| 更新稍后提醒 | 不适用 | 必测 | 同版本 24 小时内不重复提示 |
|
||
| 更新安装失败 | 不适用 | 必测 | 不打断业务录入，显示可排障错误 |
|
||
|
||
## 4. 桌面体验验收
|
||
|
||
- [ ] 登录页显示当前桌面服务器地址，长 URL 不撑破登录面板。
|
||
- [ ] 30 天免登录仍只保存系统凭据库会话记录，不保存密码，不把 token 写入 URL、日志、通知正文或业务缓存。
|
||
- [ ] 服务器设置页显示当前服务器、连接检查状态、HTTP 错误、超时和网络失败原因。
|
||
- [ ] 个人中心显示客户端类型、版本、平台、构建通道、提交、服务器和能力状态。
|
||
- [ ] 个人中心可复制诊断信息，内容不包含 token 或业务敏感数据。
|
||
- [ ] 通知开关显示 OS 权限状态。
|
||
- [ ] 手动检查更新能反馈“已是最新版本”、未启用更新或检查失败。
|
||
- [ ] 关键弹窗、表单、按钮在最小窗口尺寸 `1180x760` 下不重叠、不溢出。
|
||
- [ ] 更新弹窗只显示版本、发布日期和通用 release notes，不展示 token、下载链接或业务详情。
|
||
|
||
## 5. 不允许项
|
||
|
||
- [ ] 不实现离线登录、离线浏览、离线队列或离线同步。
|
||
- [ ] 不在桌面端保存 CTMS 业务数据副本。
|
||
- [ ] 不内嵌 FastAPI、PostgreSQL、SQLite 或本地业务 API 镜像。
|
||
- [ ] 不绕过后端做本地权限裁决或本地审计回放。
|
||
|
||
## 6. 2026-07-01 收尾验证记录
|
||
|
||
本轮收尾验证在 `/Users/zcc/MyCTMS/ctms-dev/worktrees/ctms-desktop` 的 detached HEAD `c923f887` 上执行，包含当前工作区文档与 CI 门禁调整。
|
||
|
||
已通过的自动门禁：
|
||
|
||
- `cd frontend && npm run version:check`
|
||
- `cd frontend && npm run release:env:check`
|
||
- `cd frontend && npm run runtime:check`
|
||
- `cd frontend && npm run desktop:release:check`
|
||
- `cd frontend && npm run ui:contract`
|
||
- `cd frontend && npm run type-check`
|
||
- `cd frontend && npm run test:unit`
|
||
- `cd frontend && npm run build`
|
||
- `cd frontend && npm run desktop:build:app`
|
||
- `cd frontend && node --check scripts/verify-desktop-update-feed.mjs`
|
||
|
||
验证结论：
|
||
|
||
- Tauri 运行时边界、release 静态安全门禁、构建元数据预检、版本一致性和 UI 合约均通过。
|
||
- Web 生产构建和未签名 macOS `.app` smoke 构建均可重复执行。
|
||
- 当前 CI 已补齐 `npm run release:env:check` 和 `npm run ui:contract`，tag 构建会将 `VITE_BUILD_CHANNEL` 规范为 `release` 并校验 tag 与版本号一致。
|
||
- updater feed 校验脚本已完成语法检查；正式 `latest.json` 需要在签名 updater artifacts 生成后执行实物校验。
|
||
|
||
仍需正式发布前人工确认：
|
||
|
||
- macOS 签名、公证、Apple Developer 凭据和组织 updater 私钥。
|
||
- 签名后的 updater artifacts、`.sig`、checksum manifest 和 `latest.json` 在真实发布目录内通过 `npm run desktop:update-feed:check`。
|
||
- 不可变制品上传完成后，再原子替换线上 `latest.json`。
|
||
- Desktop 端到端人工回归矩阵、最小窗口体验验收和系统通知/自动更新真实环境验证。
|