完善桌面端界面、发布检查与邮箱域名同步

docs/audits/desktop-release-stabilization-checklist.md

@@ -2,7 +2,7 @@
 
 状态: `active`
 适用范围: Web 与 macOS Desktop 统一客户端发布
-最后更新: `2026-06-30`
+最后更新: `2026-07-01`
 
 本清单用于第一、二阶段桌面端能力完成后的准发布稳定化。它不引入离线登录、本地业务数据存储、内嵌后端服务或离线同步。
 
@@ -14,6 +14,7 @@
 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
@@ -26,11 +27,12 @@ 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 注入。
+- [ ] `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` 后执行 `npm run desktop:build -- --bundles app`。
-- [ ] 不可变制品先上传，`latest.json` 最后原子替换。
+- [ ] 设置 `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. 安全边界复审
@@ -46,6 +48,8 @@ npm run desktop:build:app
 - [ ] 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 门禁。
 
 人工复审还必须确认：
 
@@ -82,6 +86,7 @@ npm run desktop:build:app
 - [ ] 通知开关显示 OS 权限状态。
 - [ ] 手动检查更新能反馈“已是最新版本”、未启用更新或检查失败。
 - [ ] 关键弹窗、表单、按钮在最小窗口尺寸 `1180x760` 下不重叠、不溢出。
+- [ ] 更新弹窗只显示版本、发布日期和通用 release notes，不展示 token、下载链接或业务详情。
 
 ## 5. 不允许项
 
@@ -89,3 +94,34 @@ npm run desktop:build:app
 - [ ] 不在桌面端保存 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 端到端人工回归矩阵、最小窗口体验验收和系统通知/自动更新真实环境验证。

docs/branch-governance.md

@@ -89,11 +89,13 @@ Rules:
   `desktop-release` branches.
 - Web and Desktop changes both follow `feature/*` -> `dev` -> `main` ->
   `release`.
-- A platform-specific feature branch is allowed while work is in progress, for
-  example `feature/desktop-file-picker`, but it must merge back into `dev`.
-- `codex/ctms-desktop` is a temporary desktop integration branch. After the
-  Tauri baseline is accepted into `dev`, new desktop work must use short-lived
-  feature branches from the current `dev`.
+- A platform-specific feature or agent task branch is allowed while work is in
+  progress, for example `feature/desktop-file-picker` or
+  `codex/desktop-menu-polish`, but it must merge back into `dev`.
+- `codex/ctms-desktop` was the temporary desktop integration branch for the
+  Tauri baseline. It is no longer a current desktop mainline. Do not commit,
+  rebase, or push new desktop work to it unless explicitly cleaning up the
+  historical branch after its accepted changes are present on `dev`.
 - Platform differences belong behind `frontend/src/runtime/`. Shared business
   modules must not import Tauri APIs directly.
 - A release tag identifies one product source state. Web and Desktop artifacts

docs/desktop-project-plan.md

@@ -10,8 +10,8 @@
 
 - 技术路线固定为 Tauri。
 - 第一开发目标是 macOS 桌面端。
-- Windows 需要作为长期适配约束保留，但不是第一阶段交付目标。
-- 当前只做第一阶段和第二阶段。
+- Windows 仍只作为第二阶段兼容性验证目标，未获明确批准前不发布正式安装包。
+- 当前桌面端工作只允许在第一、二阶段边界内做修复、稳定化、体验收口和发布准备，不新增第三阶段能力。
 - 不做离线功能。
 - 不在桌面 App 内嵌本地后端服务。
 - 不在桌面 App 内嵌或分发本地数据库来保存 CTMS 业务数据。
@@ -30,83 +30,41 @@
 
 桌面端应复用现有前端代码和 API 契约。任何共享适配层都应保持小而明确，并可测试。
 
-## 第一阶段：macOS 在线桌面客户端
+## 已完成阶段边界
 
-第一阶段交付一个面向现有 CTMS 服务的 macOS 桌面壳。
+第一阶段 macOS 在线桌面壳和第二阶段原生能力主体改造已经形成。详细历史方案见 [`desktop-phase-1-design.md`](desktop-phase-1-design.md) 和 [`desktop-phase-2-design.md`](desktop-phase-2-design.md)。
 
-详细方案见 [`desktop-phase-1-design.md`](desktop-phase-1-design.md)。
+后续不再按第一阶段空白项目初始化 Tauri，也不再扩展第二阶段以外的新桌面产品能力。当前允许推进的工作仅包括：
 
-范围：
+- 修复既有 Tauri、运行时适配层、文件、通知、凭据、更新、菜单/快捷键和打包问题。
+- 稳定 Web 与 Desktop 共用业务代码，确保平台差异继续收敛在 `frontend/src/runtime/` 后面。
+- 完成 macOS 正式发布前的签名、公证、updater 签名、制品发布、CI 门禁和人工回归。
+- 做 Windows 第二阶段兼容性验证，但不发布正式 Windows 安装包。
 
-- 在现有前端工程中加入 Tauri 项目结构。
-- 将当前 Vue/Vite 应用运行在 Tauri 桌面窗口中。
-- 连接已有 CTMS 后端，支持 HTTP/HTTPS。
-- 为桌面端提供可配置的服务端地址处理。
-- 保持当前登录、角色权限、项目上下文和审计行为。
-- 所有业务数据读写仍发生在服务端。
-- 产出 macOS 开发构建，并明确后续签名、公证、正式发布路径。
+仍然不允许：
 
-不做：
-
-- 离线登录。
-- 离线浏览项目。
-- 本地 PostgreSQL、SQLite、IndexedDB 业务数据持久化或本地 API 镜像。
-- 桌面端重写 CTMS 页面。
-- Windows 安装包交付。
-- 自动更新实现，除非被明确提升到第二阶段任务。
-
-退出标准：
-
-- macOS App 可以启动 CTMS UI。
-- macOS App 可以连接指定 CTMS 后端。
-- 登录和常规在线流程与 Web 端行为一致。
-- Web 构建仍可用，不被 Tauri API 强耦合。
-- 桌面端运行时边界已文档化。
-
-## 第二阶段：桌面端能力增强
-
-第二阶段在不改变在线优先产品边界的前提下，增加原生桌面能力。
-
-详细方案见 [`desktop-phase-2-design.md`](desktop-phase-2-design.md)。
-
-范围：
-
-- 在附件等场景中引入原生文件选择、下载、打开能力。
-- 基于服务端在线数据提供系统通知能力。
-- 使用 Tauri 兼容方式实现安全的桌面端 token/session 存储。
-- 单实例启动行为。
-- 在支持、审计或排障需要时暴露桌面 App 版本、平台、客户端类型等元数据。
-- 为签名后的桌面版本设计并实现自动更新。
-- 为 Windows 适配做准备，包括路径处理、安装器假设、CI 打包设计。
-
-不做：
-
-- 离线队列。
-- 业务数据后台同步。
-- 用于离线使用的本地业务数据缓存。
-- 绕过后端的本地权限裁决。
-- 本地审计日志缓存后再回放。
-
-退出标准：
-
-- 桌面专属能力隔离在适配层之后。
-- Web 运行时不依赖桌面 API，仍可正常工作。
-- 桌面端 session 存储和文件操作有清晰安全边界。
-- macOS 打包路径可重复执行。
-- Windows 打包要求在实现前已经文档化。
+- 离线登录、离线浏览、离线队列、离线同步或本地优先工作流。
+- 本地 PostgreSQL、SQLite、IndexedDB 业务数据缓存或本地 API 镜像。
+- 内嵌 Python/FastAPI 后端服务。
+- 绕过后端做本地权限裁决、本地审计缓存或审计回放。
+- 为桌面端复制或重写一套独立业务 UI。
 
 ## 架构方向
 
 使用运行时适配层，不在业务页面里散落平台判断。
 
-建议的适配层边界：
+当前已采用并必须继续保持的适配层边界：
 
 - `platform`：识别 Web、macOS 桌面端、Windows 桌面端。
 - `apiBaseUrl`：分别解析 Web 和桌面端的服务端 API 地址。
-- `storage`：隔离浏览器存储与桌面安全存储。
+- `desktopServerConfig`：管理桌面服务端地址配置和切换事件。
+- `secureSessionStorage`：隔离浏览器 token 存储与桌面系统凭据库。
 - `files`：隔离浏览器上传下载与原生文件能力。
 - `notifications`：隔离 Web 通知与桌面系统通知。
+- `updates`：隔离桌面自动更新检查与安装入口。
 - `appMetadata`：在可用时提供桌面 App 版本、平台、构建通道。
+- `desktopMenu` 和 `desktopUiPreferences`：承接桌面菜单命令、最近访问和收藏等桌面体验状态。
+- `clientRuntime`：作为业务侧获取平台能力的聚合入口。
 
 业务模块应调用这些适配层，而不是直接调用 Tauri API。Tauri command 应保持窄职责，不包含 CTMS 业务规则。
 
@@ -116,7 +74,7 @@
 - 非本地服务连接优先使用 HTTPS。
 - 认证与授权决策保留在后端。
 - 审计敏感决策保留在后端。
-- 第二阶段开始处理敏感凭据时，必须使用明确批准的安全存储方案。
+- 敏感凭据必须继续使用明确批准的安全存储方案。
 - 不向前端暴露宽泛文件系统访问权限。
 - Tauri 权限保持最小化，并按功能精确授权。
 - 每个新增 Tauri command 都需要被视为桌面端安全边界的一部分进行审查。
@@ -126,10 +84,50 @@
 桌面端工作在以下位置开发：
 
 - Worktree：`/Users/zcc/MyCTMS/ctms-dev/worktrees/ctms-desktop`
-- 短期分支：`codex/<任务名称>`，必须从最新 `dev` 创建
+- 短期分支：Agent 默认使用 `codex/<任务名称>`，也可按任务类型使用 `feature/*`、`fix/*`、`docs/*` 或 `release-prep/*`；所有普通桌面端工作都必须从最新 `dev` 创建
 
-`codex/ctms-desktop` 仅是第一阶段 Tauri 基线临时集成分支。基线合入
-`dev` 后，第二阶段工作不得继续把它作为长期桌面主线。
+当前代码状态：Tauri 基线和第二阶段原生能力已经形成，后续桌面端工作默认是第二阶段范围内的修复、稳定化、体验收口和发布准备。`codex/ctms-desktop` 是历史临时集成分支，不再作为当前工作线；不得继续向该分支提交、变基或推送新的桌面端工作，除非用户明确要求做收尾或删除分支。
+
+## 2026-07-01 审查结论与后续方向
+
+本轮审查结论：桌面端已经完成从 Tauri 接入基线到第二阶段原生能力的主体改造，不再按空白桌面项目推进。当前重点不是扩展离线或本地业务能力，而是围绕既有在线桌面客户端做准发布稳定化。
+
+已形成的能力边界：
+
+- Tauri 工程、macOS App/DMG/updater artifacts 配置已经存在。
+- `frontend/src/runtime/` 已作为平台能力统一入口，业务代码不得绕过该适配层直接使用 Tauri API。
+- 桌面服务器地址、API baseURL、客户端元数据请求头、安全 session 存储、原生文件能力、系统通知、单实例、菜单/快捷键和自动更新入口已经形成。
+- 后端已经包含桌面通知订阅/投递状态、相关 API 和客户端诊断请求头支持。
+- 已有 `npm run version:check`、`npm run runtime:check`、`npm run desktop:release:check` 等门禁用于约束版本、运行时边界和桌面发布安全边界。
+
+后续优化优先级：
+
+1. 发布稳定化：补齐 macOS 签名、公证、组织 updater 私钥签名、release tag 构建变量注入、不可变制品上传和 `latest.json` 原子替换。
+2. 端到端回归：按 `docs/audits/desktop-release-stabilization-checklist.md` 覆盖服务器配置、服务器切换清会话、Keychain/凭据库、附件上传下载、系统通知、单实例和自动更新失败恢复。
+3. 安全复审：持续确认 token 不进入 URL、日志、系统通知正文、下载链接或明文持久化；Tauri command、capability、CSP 和 updater 改动必须同步评估发布门禁。
+4. 桌面体验收口：重点检查登录、服务器设置、个人中心诊断信息、通知开关、更新弹窗和最小窗口 `1180x760` 下的布局稳定性。
+5. CI 与发布流程：Web 与 Desktop 必须从同一提交、同一语义化版本号和同一正式标签构建；发布候选应执行本文档列出的相关质量门禁。
+6. Windows 兼容验证：仅作为第二阶段兼容性目标，验证 Credential Manager、路径处理、通知/updater 编译、WebView2 和安装器假设；未获明确批准前不发布正式 Windows 安装包。
+
+如果后续任务试图新增离线登录、本地业务数据存储、内嵌后端、本地业务队列、离线同步或绕过后端权限审计，应先修改并评审本计划书，不能直接实现。
+
+## 当前质量门禁
+
+前端或桌面端代码变更应按影响范围执行相关检查。发布、桌面端适配层、Tauri 配置或安全边界相关变更至少考虑：
+
+```bash
+cd frontend
+npm run version: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
+```
+
+正式桌面发布构建仍必须使用组织批准的 updater 签名私钥和 Apple 签名/公证流程；未签名或 ad-hoc 构建只能作为内部验证构建描述。文档-only 变更可以不执行完整代码门禁，但必须在结果说明中明确未运行。
 
 ## 每次开发前必须执行的检查
 
@@ -140,5 +138,7 @@
 - 确认任务不会引入离线能力。
 - 确认实现不会破坏 Web 运行时。
 - 确认 Tauri API 使用被隔离在适配层之后，除非有明确记录的理由。
+- 确认不会重复初始化 Tauri 或绕过既有 `frontend/src/runtime/` 运行时边界。
+- 涉及 Tauri 权限、CSP、updater、凭据、文件或通知能力时，确认桌面发布检查脚本和发布清单是否需要同步更新。
 
 如果用户请求与本文档冲突，先停止实现并确认范围，不要直接推进。

docs/guides/branch-maintenance-sop-zh.md

@@ -51,7 +51,7 @@ windows-main
 | 生产热修复 | `hotfix/<问题名称>` | `hotfix/login-loop` |
 | 文档调整 | `docs/<文档名称>` | `docs/release-sop` |
 | 发布准备 | `release-prep/<版本号>` | `release-prep/v1.2.0` |
-| 临时集成 | `codex/<任务名称>` | `codex/ctms-desktop` |
+| Agent 临时任务 | `codex/<任务名称>` | `codex/desktop-menu-polish` |
 
 分支名称使用小写英文和连字符，不使用个人姓名、日期或模糊名称。
 
@@ -180,33 +180,17 @@ git push origin --delete feature/<功能名称>
 
 工作树正在使用的分支不能直接删除，应先切换分支或移除对应工作树。
 
-## 五、当前桌面集成分支处理流程
+## 五、历史桌面集成分支约束
 
-`codex/ctms-desktop` 是临时桌面集成分支，不作为长期桌面主线。
+`codex/ctms-desktop` 是第一阶段 Tauri 基线使用过的历史临时集成分支，不作为当前桌面端工作线，也不作为长期桌面主线。
 
-处理步骤：
+当前约束：
 
-```bash
-git status
-git add <本次桌面端和治理优化相关文件>
-git diff --cached --check
-git commit -m "refactor(client): 统一网页端和桌面端发布流程"
-git fetch origin
-git rebase origin/dev
-git push origin codex/ctms-desktop
-```
-
-创建：
-
-```text
-codex/ctms-desktop -> dev
-```
-
-合并并验证 `dev` 后：
-
-- 删除远程 `codex/ctms-desktop`
-- 不再从该分支继续开发
-- 后续桌面功能从最新 `dev` 创建短期 `feature/*` 分支
+- 不得继续向 `codex/ctms-desktop` 提交、变基或推送新的桌面端工作。
+- 如本地或远程仍保留该分支，只能用于追溯历史或在确认已合入 `dev` 后删除。
+- 后续桌面功能、修复、稳定化和发布准备必须从最新 `dev` 创建短期 `feature/*`、`fix/*`、`docs/*`、`release-prep/*` 或 `codex/*` 分支。
+- Agent 创建分支默认使用 `codex/<任务名称>`，并在任务合入 `dev` 后删除。
+- 如果工作区处于 detached HEAD 或包含尚未归属到分支的提交，执行分支切换、提交、推送或变基前必须先确认目标基线和处理方式。
 
 ## 六、从 `dev` 晋级到 `main`
 

docs/guides/client-release.md

@@ -64,6 +64,7 @@ release/security gate before promotion:
 ```bash
 cd frontend
 npm run version:check
+npm run release:env:check
 npm run runtime:check
 npm run desktop:release:check
 npm run ui:contract
@@ -73,10 +74,12 @@ npm run build
 npm run desktop:build:app
 ```
 
+`release:env:check` verifies build channel and commit metadata, and can be
+made strict for signed Desktop builds with `REQUIRE_DESKTOP_SIGNING=true`.
 `desktop:release:check` statically verifies the Tauri bundle, updater public
-key, CSP, capability scopes, command allowlist, query-token ban, and secure
-session token boundary. The full manual release, security, regression, and
-Desktop UX checklist lives in
+key, CSP, capability scopes, command allowlist, query-token ban, generic system
+notification boundary, CI gate coverage, and secure session token boundary. The
+full manual release, security, regression, and Desktop UX checklist lives in
 `docs/audits/desktop-release-stabilization-checklist.md`.
 
 ## Promotion
@@ -120,8 +123,9 @@ The release pipeline must:
 3. sign and notarize the macOS app;
 4. produce updater artifacts and `.sig` files with the updater private key;
 5. generate `latest.json` and a checksum manifest;
-6. upload immutable artifacts first;
-7. atomically replace `latest.json` last.
+6. verify the feed with `npm run desktop:update-feed:check -- --feed <latest.json> --artifacts-dir <artifact-dir>`;
+7. upload immutable artifacts first;
+8. atomically replace `latest.json` last.
 
 For Universal macOS artifacts, `latest.json` must provide both
 `darwin-aarch64` and `darwin-x86_64` entries pointing at the same Universal
@@ -149,6 +153,9 @@ Windows validation must cover:
 cd frontend
 npm ci
 npm run version:check
+export VITE_BUILD_CHANNEL=release
+export VITE_BUILD_COMMIT="$(git rev-parse HEAD)"
+npm run release:env:check
 npm run runtime:check
 npm run desktop:release:check
 npm run ui:contract
@@ -158,7 +165,10 @@ npm run build
 npm run desktop:build:app
 export TAURI_SIGNING_PRIVATE_KEY="$UPDATER_PRIVATE_KEY"
 export TAURI_SIGNING_PRIVATE_KEY_PASSWORD="$UPDATER_PRIVATE_KEY_PASSWORD"
+export REQUIRE_DESKTOP_SIGNING=true
+npm run release:env:check
 npm run desktop:build -- --bundles app
+npm run desktop:update-feed:check -- --feed src-tauri/target/release/bundle/latest.json --artifacts-dir src-tauri/target/release/bundle
 ```
 
 The Desktop build must run on macOS for the current first-phase target. A signed