CTMS Desktop Release Stabilization Checklist

状态: active 适用范围: Web 与 macOS Desktop 统一客户端发布最后更新: 2026-07-01

本清单用于第一、二阶段桌面端能力完成后的准发布稳定化。它不引入离线登录、本地业务数据存储、内嵌后端服务或离线同步。

1. 发布链路门禁

发布候选提交必须从同一 Git 提交构建 Web 与 Desktop 制品，并完成以下检查：

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 通过。
在正式 release tag 和签名环境中执行 npm run desktop:release-readiness:check，确认 tag、构建元数据、签名/公证变量、updater 私钥和生产 artifact HTTPS 基址齐备。
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:macos-release -- --ci。
正式 updater feed 先执行 npm run desktop:update-feed:create -- --artifact <CTMS.app.tar.gz> --base-url <versioned-https-artifact-prefix> --output-dir <release-dir> 生成 latest.json 与 SHA256SUMS.txt。
正式 updater feed 执行 npm run desktop:update-feed:check -- --feed <release-dir>/latest.json --artifacts-dir <release-dir>，并确认 checksum manifest、updater artifact、.sig 和 latest.json 均通过校验。
不可变制品先上传，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 门禁。
signed macOS release candidate workflow 只允许从 vX.Y.Z tag 运行，并包含签名环境检查、Universal macOS 构建、update feed 生成、checksum 校验和 verified release directory 上传。

人工复审还必须确认：

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 端到端人工回归矩阵、最小窗口体验验收和系统通知/自动更新真实环境验证。

7. 2026-07-02 发布稳定化推进记录

本次推进补齐了发布链路自动化，不改变桌面端产品边界：

新增 npm run desktop:build:macos-release，封装 Universal macOS app/dmg release candidate 构建命令。
新增 npm run desktop:update-feed:create，从签名 updater artifact 和 .sig 生成 latest.json、复制发布目录文件并生成 SHA256SUMS.txt。
npm run desktop:update-feed:check 在传入 --artifacts-dir 时要求并校验 SHA256SUMS.txt。
新增 npm run desktop:release-readiness:check，在正式签名候选构建前检查 release tag、构建元数据、签名/公证变量、updater 私钥和生产 artifact HTTPS 基址。
新增 .github/workflows/desktop-release-candidate.yml，在 release tag 上执行签名候选构建、feed 生成、feed 校验并上传 verified release directory。
npm run desktop:release:check 已检查上述脚本和 workflow，避免发布链路回退。

仍未自动完成、正式发布前必须人工确认：

Apple Developer 凭据、证书、签名身份、公证结果和组织 updater 私钥。
生产下载源的不可变制品上传和线上 latest.json 原子替换。
真实环境下的自动更新安装、系统通知、单实例和完整人工回归。

8. 2026-07-02 端到端回归优化记录

本轮端到端优化仍保持在线桌面客户端边界，不引入离线、本地业务存储或本地权限裁决。

已完成的自动化收口：

服务器地址切换时，桌面设置页调用 auth.logout({ rememberCurrentStudy: false })，避免退出时把旧服务器项目记入当前用户的最近项目；随后继续清除当前项目上下文。
系统通知轮询在部分通知显示失败时，先 ack 已成功显示的通知，再让失败项通过租约重试，贴合“显示成功后 ack；失败等待重试”的回归预期。
自动更新管理器新增稍后提醒 24 小时抑制、安装失败可重试、检查失败不打断业务和未启用更新状态的单元覆盖。
新增相关单元测试覆盖服务器切换不记忆旧项目、通知权限未授权不领取、部分通知失败时只 ack 成功项，以及自动更新失败恢复路径。

仍需人工或真实环境验证：

Keychain/凭据库 30 天在线会话恢复。
原生附件上传、下载、保存和打开。
系统通知授权/拒绝的 OS 级交互。
单实例重复启动聚焦主窗口。
签名 release 构建下的自动更新 feed、验签、安装和重启实物流。

10 KiB Raw Blame History Unescape Escape