zhouchengcheng/ctms
1
1
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity
Files
3a866accd907b03d457a1684bfe127b6f82f3680
ctms/docs/audits/desktop-release-stabilization-checklist.md
T
Cheng Zhou 3a866accd9 完善桌面体验与系统通知收口
2026-07-08 20:46:56 +08:00

16 KiB
Raw Blame History

CTMS Desktop Release Stabilization Checklist

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

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

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 发送，标题和正文保持通用。
  • 通知 capability 只暴露权限查询、权限请求和发送通知，不使用 notification:default。
  • opener capability 只允许打开 $TEMP/ctms-desktop/** 下的临时文件，不开放 URL 或 reveal 权限。
  • updater capability 不直接暴露给 WebView，自动更新只走受控 Tauri command。
  • 更新弹窗 release notes 过滤 URL、token 查询参数和 Authorization/Bearer 形态文本。
  • 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 小时抑制、安装失败可重试、检查失败不打断业务和未启用更新状态的单元覆盖。
  • 附件 API 新增 blob 下载、multipart 上传和删除端点单元覆盖，确保下载凭据继续由 axios Authorization header 承载而不是进入 URL。
  • 文件任务反馈 helper 新增选择、保存、取消保存和打开的单元覆盖，约束桌面保存/打开继续走 frontend/src/runtime/ 适配层。
  • Keychain/凭据库会话新增旧浏览器 token 迁移、未配置服务器不读取凭据、本地 30 天上限、服务器切换删除旧服务器凭据，以及恢复 token 必须先经 /me 校验的单元覆盖。
  • 桌面发布门禁新增单实例重复启动处理校验，要求重复启动时恢复、显示并聚焦 main 窗口。
  • 会话刷新后的跨窗口 token 更新不再写入 localStorage fallback，只通过内存态 BroadcastChannel 通知，避免 token 进入明文广播缓存。
  • desktop:release:check 新增 session broadcast 静态门禁，防止 TOKEN_UPDATED payload 回退写入 localStorage。
  • 新增相关单元测试覆盖服务器切换不记忆旧项目、通知权限未授权不领取、部分通知失败时只 ack 成功项、系统通知未发起时不 ack、自动更新失败恢复路径、附件文件流契约、30 天在线会话恢复边界、单实例恢复行为和 token 广播存储边界。

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

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

9. 2026-07-02 安全边界复审记录

本轮安全复审在端到端自动化收口之后推进，不改变桌面端在线客户端边界。

已完成的安全边界收口：

  • Tauri notification capability 从 notification:default 收敛为 notification:allow-is-permission-granted、notification:allow-request-permission 和 notification:allow-notify。
  • desktop:release:check 新增 capability 最小化约束，拒绝 notification:default、opener URL/reveal 权限和 WebView 直连 updater 权限。
  • desktop:release:check 将 token URL 检查扩展到 token 与 access_token 查询参数，并扩大日志敏感词检查到 token、access_token、authorization 和 bearer。
  • 更新弹窗 release notes 增加清理逻辑，过滤 URL、token 查询参数、access_token、Authorization 和 Bearer 形态文本，避免 feed 内容把下载链接或凭据样式文本带入 UI。
  • 凭据库 Rust 单测新增带凭据 server origin 拒绝，以及 Keychain/Credential Manager account 不暴露原始服务器 origin 的覆盖。

仍需人工复审确认：

  • 真实生产 release notes 内容保持通用，不写入项目、文件、下载链接或敏感业务详情。
  • 正式签名、公证和 updater feed 环境继续使用组织 secret，不在日志、artifact 或配置中泄露私钥材料。

10. 2026-07-02 桌面体验收口记录

本轮体验收口聚焦登录、服务器设置、个人中心诊断、系统偏好和最小窗口布局稳定性，不改变业务能力边界。

已完成的体验收口：

  • 个人中心新增只读客户端诊断信息，展示客户端类型、版本、平台、构建通道、提交、服务器和能力状态，并支持复制诊断信息。
  • 登录页在桌面最小窗口附近收紧左右分栏 padding 和卡片宽度，长服务器地址继续在登录面板内换行，不撑破布局。
  • 服务器设置页增加面板内滚动和健康检查 URL 换行约束，避免 1180x760 下长 URL 或错误信息溢出。
  • 系统偏好通知/更新控制区允许换行，长状态说明使用 overflow-wrap，避免按钮和权限状态标签在窄视口重叠。
  • 个人中心对话框内容区改为内部滚动，诊断值使用强制换行，避免新增诊断信息后超过最小窗口高度。
  • 通知权限运行时改为优先读取 WebView Notification.permission 的 granted/denied 状态；请求权限返回 default 时保持“待授权”，不再误标为“已拒绝”。
  • 系统偏好通知页已移除授权成功态的固定标签文案，开启状态只由开关表达；待授权、已拒绝和不可用状态继续显示提示标签。
  • 系统偏好通知页新增“测试通知”命令，完整走 frontend/src/runtime/notifications.ts -> @tauri-apps/plugin-notification 的系统通知发送链路；测试通知文案为固定通用内容，不包含项目、文件、token 或其他敏感业务信息。
  • showSystemNotification 和测试通知调用会在发送前确认系统通知权限，只有真正发起系统通知时才返回成功；桌面通知轮询据此只 ack 已实际发起系统通知的后端通知。
  • 真实 macOS .app 已验证系统偏好通知开关可调用系统通知权限并生效。验证截图见 /Users/zcc/Library/Application Support/CleanShot/media/media_boKznpjOwt/CleanShot 2026-07-02 at 11.07.52@2x.png。
  • Layout.desktop.test.ts 新增静态契约覆盖个人中心诊断、登录页最小窗口断点、服务器设置滚动和偏好页控制区换行约束。
  • notifications.test.ts 新增授权、拒绝、待授权、取消授权请求和测试通知发送链路的单元覆盖。

仍需人工体验验收：

  • 在真实 macOS .app 中以 1180x760 检查登录页、服务器设置、个人中心、系统偏好和更新弹窗无重叠、无横向溢出。
  • 在真实系统通知权限拒绝流程中确认权限状态提示、开关回退和错误提示与 OS 状态一致。
Reference in New Issue View Git Blame Copy Permalink