refactor: 重构文档结构与环境配置，统一研发工单命名

1. 更新 .env 配置文件，替换原有云同步变量为 API 目标配置 2. 调整 publish-linux.ps1 中的文档路径，使用研发工单目录 3. 重构项目文档目录：将原 v1.2.0-tasks 迁移为研发工单-v1.2.0 目录，统一术语为"研发工单"替代"任务" 4. 更新 README.md 与各 PRD 文档的术语对照表，明确业务实体与研发工作项的区分 5. 新增多个研发工单文档，覆盖搜索、云同步、Linux 打包等模块 6. 删除旧的任务拆分文档，统一使用新的研发工单体系
2026-06-14 00:58:26 +08:00
parent a7ba814833
commit d81aa06681
18 changed files with 162 additions and 112 deletions
@@ -1,5 +1,14 @@
 # Hua.Todo 产品需求文档 (PRD) v1.1.0

+> **术语对照（必读）**
+>
+> | 术语 | 含义 | 出现位置 |
+> |---|---|---|
+> | **Todo 待办项 / 任务 / 子任务（业务实体）** | 用户在 Hua.Todo 应用中创建的待办事项，对应代码 `Task` / `SubTask` 实体、`/api/task` 接口、UI 列表项 | 本文及 `docs/manual/`、业务代码 |
+> | **研发工单（Dev Work Item）** | 智能体 / 开发者执行的编码工作项（需求拆分、并行开发） | `docs/project/研发工单-*/`、`.trae/rules/全局/05-研发工单规则.md` |
+>
+> 本文中"任务/子任务"统一指业务实体；如涉及编码侧拆分请使用"研发工单"。
+
 ## 1. 项目概述
 本项目是一个基于 MAUI + WebView 架构开发的跨平台代办管理应用 (Hua.Todo)。旨在提供轻量、高效的任务管理体验，特别是通过快捷键快速唤起记录功能，最大化用户的操作效率。v1.1.0 版本将实现跨平台支持，覆盖 Windows、macOS、Android、iOS 和 Linux（预览）平台。

@@ -1,5 +1,14 @@
 # Hua.Todo 产品需求文档 (PRD) v1.2.0

+> **术语对照（必读）**
+>
+> | 术语 | 含义 | 出现位置 |
+> |---|---|---|
+> | **Todo 待办项 / 任务 / 子任务（业务实体）** | 用户在 Hua.Todo 应用中创建的待办事项，对应代码 `Task` / `SubTask` 实体、`/api/task` 接口、UI 列表项 | 本文及 `docs/manual/`、业务代码 |
+> | **研发工单（Dev Work Item）** | 智能体 / 开发者执行的编码工作项（需求拆分、并行开发） | `docs/project/研发工单-*/`、`.trae/rules/全局/05-研发工单规则.md` |
+>
+> 本文中"任务/子任务"统一指业务实体；如涉及编码侧拆分请使用"研发工单"。
+
 ## 1. 项目概述

 在 v1.1.0 版本成功实现 MAUI + WebView 跨平台架构的基础上，v1.2.0 版本将以“**MAUI 入口保持不动 + Linux 新增 Avalonia 入口**”的方式落地 Linux 支持（继续使用 WebView 承载 Vue 前端），并在此基础上探索 Avalonia 对其他终端的支持情况；若验证效果良好，后续版本将推进各终端入口统一切换到 Avalonia。
@@ -1,5 +1,14 @@
 # Hua.Todo 产品需求文档 (PRD)

+> **术语对照（必读）**
+>
+> | 术语 | 含义 | 出现位置 |
+> |---|---|---|
+> | **Todo 待办项 / 任务 / 子任务（业务实体）** | 用户在 Hua.Todo 应用中创建的待办事项，对应代码 `Task` / `SubTask` 实体、`/api/task` 接口、UI 列表项 | 本文及 `docs/manual/`、业务代码 |
+> | **研发工单（Dev Work Item）** | 智能体 / 开发者执行的编码工作项（需求拆分、并行开发） | `docs/project/研发工单-*/`、`.trae/rules/全局/05-研发工单规则.md` |
+>
+> 本文中"任务/子任务"统一指业务实体；如涉及编码侧拆分请使用"研发工单"。
+
 ## 1. 项目概述
 本项目是一个基于 C# WPF (.NET 10) 开发的桌面代办管理应用 (Hua.Todo)。旨在提供轻量、高效的任务管理体验，特别是通过快捷键快速唤起记录功能，最大化用户的操作效率。

@@ -1,49 +1,51 @@
-# Hua.Todo v1.2.0 任务拆分总览
+# Hua.Todo v1.2.0 研发工单总览

-本目录用于把 [产品需求文档-1.2.0.md](file:///d:/Proj/6.Hua.Todo/docs/project/产品需求文档-1.2.0.md) 拆解为可落地、可并行推进的子任务。各任务文件之间尽量解耦；存在明确依赖时会在任务内标注。
+> 术语澄清：本目录下"工单 / 子工单 / 研发工单"指**编码工作项**；文中提到的"任务/任务列表/任务标题/父子任务/拉取任务/同步任务"等指 Hua.Todo 项目业务领域的 **Todo 待办项**（Task 实体），二者请勿混淆。详见 `.trae/rules/全局/05-研发工单规则.md`。
+
+本目录用于把 [产品需求文档-1.2.0.md](file:///d:/Proj/6.Hua.Todo/docs/project/产品需求文档-1.2.0.md) 拆解为可落地、可并行推进的子工单。各工单文件之间尽量解耦；存在明确依赖时会在工单内标注。

 ## 目标（来自 PRD）

- Linux 平台官方支持：MAUI 入口保持不动，Linux 新增 Avalonia 入口；继续用 WebView 承载同一套 Vue 前端；复用既有“本地 API ↔ 前端”的交互协议
- 任务检索（Search）：主界面顶部新增搜索框，按任务标题模糊匹配
- 云同步（基础可用）：用户手动配置服务端地址；RBAC + 二次认证；用户级数据隔离；服务端配置驱动的“可控落盘”
+- Linux 平台官方支持：MAUI 入口保持不动，Linux 新增 Avalonia 入口；继续用 WebView 承载同一套 Vue 前端；复用既有"本地 API ↔ 前端"的交互协议
+- Todo 待办项检索（Search）：主界面顶部新增搜索框，按 Todo 待办项标题模糊匹配
+- 云同步（基础可用）：用户手动配置服务端地址；RBAC + 二次认证；用户级数据隔离；服务端配置驱动的"可控落盘"

-## 当前实现基线（用于任务定位）
+## 当前实现基线（用于工单定位）

 - MAUI 启动与内嵌 WebServer：`src/Hua.Todo.Maui`
 - 前端（Vue）与 API client：`src/Hua.Todo.Web`
 - 后端宿主（ASP.NET，动态 API）：`src/Hua.Todo.Host` + `src/Hua.Todo.Application/DynamicApi`
 - 现有 WebView ↔ 前端注入协议（示例）：`window.__API_BASE_URL__`、`window.mauiInterop`（用于 JS 侧拿到 API base 与若干事件桥接）

-## 任务流（并行建议）
+## 工单流（并行建议）

 - **Linux 入口线**：`01-*` + `02-*`
  - 01：新增 Avalonia 入口、选择 Linux 可用的 WebView 控件、复用现有前后端协议
  - 02：Linux 打包/交付产物（已落地：`.tar.gz` 发布脚本 + Flatpak 基础结构；详见 `publish-linux.ps1` 与 `pack/linux/`）
 - **Search 线**：`03-*`
  - 主要在前端完成；与云同步/平台入口基本无耦合，可并行
-  - 03：已完成：主界面搜索框（按标题包含匹配；命中即显示含上下文；Esc 清空；英文大小写不敏感）
+  - 03：已完成：主界面搜索框（按 Todo 待办项标题包含匹配；命中即显示含上下文；Esc 清空；英文大小写不敏感）
 - **云同步线**：`04-*` + `05-*` + `06-*`
-  - 04：服务端基础能力（登录、任务同步/读取、配置下发、用户隔离）
-  - 05：客户端配置与同步工作流（手动指定服务端地址、登录后拉取任务）
-  - 06：安全与落盘策略（RBAC、二次认证、可控落盘与“内存模式”）
+  - 04：服务端基础能力（登录、Todo 数据同步/读取、配置下发、用户隔离）
+  - 05：客户端配置与同步工作流（手动指定服务端地址、登录后拉取 Todo 数据）
+  - 06：安全与落盘策略（RBAC、二次认证、可控落盘与"内存模式"）
 - **文档与验收线**：`07-*`
  - 对齐文档与现实现状/接口；补齐验收步骤与自测清单

 ## 待验证表

-| 子任务 | 实现状态 | 验证状态 | 备注 |
+| 子工单 | 实现状态 | 验证状态 | 备注 |
 |---|---|---|---|
 | 01 - Linux 入口 | 已完成 | 待验证 | 基于 Avalonia + WebView.Avalonia 实现 |
 | 02 - Linux 打包/交付 | 已落地 | 待验证 | `.tar.gz` 发布脚本 + Flatpak 基础结构 |
-| 03 - Search 关键词检索 | 已完成 | 待验证 | 搜索框 + 树状任务标题包含匹配 |
+| 03 - Search 关键词检索 | 已完成 | 待验证 | 搜索框 + 树状 Todo 待办项标题包含匹配 |
 | 04 - 云同步 服务端基础能力 | 已完成 | 已验证 | API 契约与错误码已固化到 04 文档 |
-| 05 - 云同步 客户端配置与同步 | 已完成 | 待验证 | 新增“云同步设置”弹窗：地址校验+保存探测、登录/登出、登录后拉取云端任务并在主界面只读展示 |
+| 05 - 云同步 客户端配置与同步 | 已完成 | 待验证 | 新增"云同步设置"弹窗：地址校验+保存探测、登录/登出、登录后拉取云端 Todo 数据并在主界面只读展示 |
 | 06 - 安全与落盘策略 | 未标注 | 待验证 |  |
 | 07 - 文档与验收 | 未标注 | 待验证 |  |

 ## 交付判定（v1.2.0 Done Definition）

 - Linux：在基线发行版（建议 Ubuntu LTS）上可启动、可渲染前端、可调用本地 API；且有可安装/可运行的交付产物
- Search：可在主界面按标题实时过滤任务（含层级任务的展示策略清晰）
- 云同步（基础可用）：可配置服务端地址；登录后可拉取该用户任务；服务端可下发“是否允许落盘”；客户端在禁止落盘时不产生本地持久化
+- Search：可在主界面按 Todo 待办项标题实时过滤（含层级 Todo 的展示策略清晰）
+- 云同步（基础可用）：可配置服务端地址；登录后可拉取该用户的 Todo 数据；服务端可下发"是否允许落盘"；客户端在禁止落盘时不产生本地持久化
@@ -4,7 +4,7 @@

 - 新增一个 **Linux 桌面端入口**（Avalonia）作为 Hua.Todo 的 Linux 宿主
 - 在 Linux 宿主中用 **WebView** 加载同一套 Vue 前端（与 MAUI 端共用前端构建产物与资源路径约定）
- 复用既有“前端 ↔ 本地 API”的交互方式（HTTP API + 现有注入变量/事件名），保证前端无需为 Linux 分叉
+- 复用既有"前端 ↔ 本地 API"的交互方式（HTTP API + 现有注入变量/事件名），保证前端无需为 Linux 分叉

 ## 范围

@@ -16,7 +16,7 @@

 ## 依赖

- 依赖 `04-*`/`05-*` 的云同步工作不强依赖本任务，可并行
+- 依赖 `04-*`/`05-*` 的云同步工作不强依赖本工单，可并行
 - 依赖前端已有构建产物或构建流程（至少能得到 `dist/` 或等效 `wwwroot/`）

 ## 关键决策点（必须在实现前落定）
@@ -30,7 +30,7 @@
 选型必须满足的最低能力：
 - 基础导航与本地资源加载
 - JS 执行/注入（用于对齐 `window.__API_BASE_URL__` 等契约）
- JS ↔ Native 双向通信（至少开发阶段可观测；可先只保证“HTTP API”路径通）
+- JS ↔ Native 双向通信（至少开发阶段可观测；可先只保证"HTTP API"路径通）
 - 开发期可用 DevTools（至少能定位网络请求与控制台错误）

 ### 2) 资源加载策略（与 MAUI 对齐）
@@ -75,12 +75,12 @@
   - 提供 App/Window/MainView 基础结构
 2. 接入 WebView 控件并完成最小加载闭环
   - 能显示 `index.html`，能打开前端路由
-3. 对齐与 MAUI 端一致的“前端契约”
+3. 对齐与 MAUI 端一致的"前端契约"
   - 注入 `window.__API_BASE_URL__`（值应为 `${BaseUrl}/api`）
   - 若沿用 `window.mauiInterop` 事件名，需在 Linux 端同名注入（建议命名逐步抽象为更通用的 `nativeInterop`，但 v1.2.0 以兼容为优先）
 4. 复用本地 API（内嵌 WebServer）
   - 评估复用 `Hua.Todo.Host`/现有 Kestrel 组件的可能性
-   - 明确 Linux 端是否也走“内嵌 WebServer + WebView 指向 BaseUrl”的方式（推荐一致化，减少前端差异）
+   - 明确 Linux 端是否也走"内嵌 WebServer + WebView 指向 BaseUrl"的方式（推荐一致化，减少前端差异）
 5. 输入法/字体/DPI 验证与可配置化
   - 至少验证：中文输入法、缩放、Wayland/X11 下可用性

@@ -88,6 +88,6 @@

 - 在 Linux（建议 Ubuntu LTS）上启动 Avalonia 入口后：
  - WebView 正常渲染前端主界面
-  - 前端能通过 `window.__API_BASE_URL__` 正确请求本地 `/api/*`（至少任务列表接口可用）
+  - 前端能通过 `window.__API_BASE_URL__` 正确请求本地 `/api/*`（至少 Todo 待办项列表接口可用）
  - 页面路由/刷新不会出现 404（SPA fallback 生效）
 - 开发态可调试（至少能看到控制台/网络错误，或能通过日志定位）
@@ -2,7 +2,7 @@

 ## 目标

- 为 Linux 提供可安装/可分发的交付产物，并尽量做到“用户机器无需手动补大量依赖即可运行”
+- 为 Linux 提供可安装/可分发的交付产物，并尽量做到"用户机器无需手动补大量依赖即可运行"
 - 明确最低支持发行版范围（建议 Ubuntu LTS 作为基线）与依赖策略（WebView 运行时/字体/输入法等）

 ## 范围
@@ -17,7 +17,7 @@

 ## 交付形式（PRD 约束）

- 优先提供一种“自包含”官方安装方式（AppImage/Flatpak 二选一，建议先做一条跑通）
+- 优先提供一种"自包含"官方安装方式（AppImage/Flatpak 二选一，建议先做一条跑通）
 - 同时保留 `.deb` 或 `.tar.gz` 作为补充分发形式（以脚本产出为准）

 ## 实施步骤（建议）
@@ -25,7 +25,7 @@
 1. 确定 Linux 发行版基线与运行时依赖清单
   - 记录：最低 glibc、Wayland/X11、WebView 运行时依赖、字体包
 2. 选择并落地一种自包含交付形式
-   - AppImage：偏“拎包即用”，对依赖捆绑要求高
+   - AppImage：偏"拎包即用"，对依赖捆绑要求高
   - Flatpak：沙盒与运行时生态更成熟，但需要 manifest 与权限策略
 3. 补充 `.deb` 或 `.tar.gz`
   - `.deb`：适合 Ubuntu/Debian 系；需要 desktop entry、图标、依赖声明
@@ -35,7 +35,6 @@

 ## 验收标准

- 产物可在“干净环境”（尽量接近用户机）安装/运行
+- 产物可在"干净环境"（尽量接近用户机）安装/运行
 - 启动后 WebView 能渲染前端，且本地 API 可用
 - 文档中给出的安装/运行步骤可复现，且与产物一致
-
@@ -1,15 +1,17 @@
-# 03 - Search：任务标题关键词检索
+# 03 - Search：Todo 待办项标题关键词检索
+
+> 术语：本工单所指"Todo 待办项 / 任务标题 / 父子任务"为业务实体（Task / SubTask）；"工单"指本研发工单本身。

 ## 目标

 - 在主界面顶部增加搜索框
- 支持按任务标题进行模糊匹配（实时过滤）
+- 支持按 Todo 待办项标题进行模糊匹配（实时过滤）

 ## 范围

 - 前端 UI：输入框、清空按钮、键盘交互（Esc 清空、Enter 可选）
- 过滤逻辑：对“树状任务”给出明确策略
- 性能：任务量增大时仍保持可用（至少避免 O(n^2) 的明显退化）
+- 过滤逻辑：对"树状 Todo（父子任务）"给出明确策略
+- 性能：Todo 数据量增大时仍保持可用（至少避免 O(n^2) 的明显退化）

 ## 依赖

@@ -17,15 +19,15 @@

 ## 过滤策略（需在实现时确定，并写入实现说明）

-树状任务（父子任务）常见两种策略，任选其一并保持一致：
+树状 Todo（父子任务）常见两种策略，任选其一并保持一致：

 1. **命中即显示（含上下文）**
   - 任意节点标题命中则显示该节点
   - 若子任务命中，可同时显示其祖先链（便于理解层级）
 2. **扁平化命中**
-   - 只显示命中的任务（可能丢失层级语义）
+   - 只显示命中的 Todo（可能丢失层级语义）

-建议优先采用“命中即显示（含上下文）”，用户可更快定位。
+建议优先采用"命中即显示（含上下文）"，用户可更快定位。

 ## 实施步骤（建议）

@@ -39,7 +41,6 @@

 ## 验收标准

- 输入关键字后，任务列表实时过滤，仅展示命中结果（符合上述策略）
+- 输入关键字后，Todo 列表实时过滤，仅展示命中结果（符合上述策略）
 - 清空后恢复原列表
 - 对中英文与大小写的处理行为明确（至少：英文大小写不敏感；中文按包含匹配）
-
@@ -1,19 +1,21 @@
 # 04 - 云同步（基础可用）：服务端基础能力

+> 术语：本工单文件本身归属"研发工单"；文中"任务/Todo 数据"指业务实体（Task / SubTask）。
+
 ## 目标（PRD 约束）

- 支持用户级任务数据同步/读取（用户隔离）
+- 支持用户级 Todo 待办项数据同步/读取（用户隔离）
 - 提供基于角色/权限的访问控制（RBAC）
 - 对高风险操作支持二次认证（能力以服务端实现为准）
- 下发“可控落盘”配置（服务端配置驱动）
+- 下发"可控落盘"配置（服务端配置驱动）

 ## 范围（建议最小闭环）

 - 认证（登录/会话）
- 任务数据 API（按用户隔离）
+- Todo 数据 API（按用户隔离）
 - 配置下发 API（是否允许落盘、终端可信度/会话策略等）
- RBAC 最小落地（至少能区分“允许同步/禁止同步”或“只读/读写”）
- 二次认证最小落地（至少覆盖“启用/关闭同步、切换账号、调整落盘策略”等高风险操作的接口）
+- RBAC 最小落地（至少能区分"允许同步/禁止同步"或"只读/读写"）
+- 二次认证最小落地（至少覆盖"启用/关闭同步、切换账号、调整落盘策略"等高风险操作的接口）

 ## 依赖

@@ -53,7 +55,7 @@ v1.2.0 已实现一套最小可用契约（用于 05/06 客户端对接时冻结
  - Body：`{ "userName": "admin", "password": "..." }`
  - 200：`{ accessToken, expiresAtUtc, userId, role, permissions[] }`

- 二次认证（step-up，v1.2.0 最小实现为“复用登录口令进行再认证”）：
+- 二次认证（step-up，v1.2.0 最小实现为"复用登录口令进行再认证"）：
  - `POST /auth/step-up`
  - Header：`Authorization: Bearer ...`
  - Body：`{ "password": "..." }`
@@ -61,7 +63,7 @@ v1.2.0 已实现一套最小可用契约（用于 05/06 客户端对接时冻结

 ### Tasks

- 获取当前用户任务全量：
+- 获取当前用户 Todo 待办项全量：
  - `GET /tasks`
  - Header：`Authorization: Bearer ...`
  - 权限：`tasks:read`
@@ -120,7 +122,7 @@ v1.2.0 已实现一套最小可用契约（用于 05/06 客户端对接时冻结

 ## 关键实现点（建议）

-详细实现方案请参考：[06.1-CloudSync-服务端安全设计方案.md](file:///d:/Proj/6.Hua.Todo/docs/project/v1.2.0-tasks/06.1-CloudSync-服务端安全设计方案.md)
+详细实现方案请参考：[06.1-CloudSync-服务端安全设计方案.md](file:///d:/Proj/6.Hua.Todo/docs/project/研发工单-v1.2.0/06.1-CloudSync-服务端安全设计方案.md)

 1. 用户隔离
   - 服务端所有读写必须绑定当前登录用户上下文
@@ -128,20 +130,20 @@ v1.2.0 已实现一套最小可用契约（用于 05/06 客户端对接时冻结
   - 定义最小角色：例如 `user`、`admin`
   - 定义最小权限：例如 `tasks:read`、`tasks:write`、`sync:enable`
 3. 二次认证
-   - 选择实现方式（示例）：二次口令/一次性验证码（TOTP）/短信（若无能力则先实现“二次口令”）
+   - 选择实现方式（示例）：二次口令/一次性验证码（TOTP）/短信（若无能力则先实现"二次口令"）
   - 能力不足时必须返回明确错误，使客户端可提示用户
 4. 落盘策略下发
   - 支持按用户或按会话/终端下发
-   - 默认策略建议为“允许落盘”，便于可用性；但需支持“禁止落盘”
+   - 默认策略建议为"允许落盘"，便于可用性；但需支持"禁止落盘"

 ## 验收标准

- 使用不同用户登录后获取任务，数据严格隔离
+- 使用不同用户登录后获取 Todo 数据，数据严格隔离
 - 未授权角色/权限访问受限接口会被拒绝（错误响应可被客户端识别）
 - 能返回安全策略配置（至少包含 `allowPersist`），并可通过配置切换行为

 ## 当前实现说明（v1.2.0）

 - 数据隔离：`Tasks` 表新增 `UserId` 外键，云端 API 的所有读写按当前会话用户隔离；本地模式使用固定的 `local` 用户 ID（不影响既有 Dynamic API）。
- RBAC：内置 `admin / user / readonly / nosync` 角色与权限映射；并叠加 `SecurityPolicies.AllowSync` 作为“是否允许同步写入”的策略开关。
+- RBAC：内置 `admin / user / readonly / nosync` 角色与权限映射；并叠加 `SecurityPolicies.AllowSync` 作为"是否允许同步写入"的策略开关。
 - 二次认证：通过 `POST /auth/step-up` 将会话提升到 step-up 状态；`POST /sync` 与 `PUT /security/policy` 会强制要求 step-up。
@@ -1,21 +1,23 @@
 # 05 - 云同步（基础可用）：客户端配置与同步工作流

+> 术语：本工单文件归属"研发工单"；文中"任务/Todo 数据"指业务实体（Task / SubTask）。
+
 ## 目标（PRD 约束）

 - 首次启用同步时，用户需要**手动填写服务端地址**（例如 `https://example.com`），并允许后续在设置中修改
 - 客户端对地址格式做基础校验，并在保存时提示可达性/证书异常等风险信息
- 用户登录成功后，从服务端获取该用户任务并更新到前端展示
+- 用户登录成功后，从服务端获取该用户 Todo 数据并更新到前端展示

 ## 范围（建议最小闭环）

- “同步设置”入口与界面（服务端地址、登录、同步开关）
+- "同步设置"入口与界面（服务端地址、登录、同步开关）
 - 地址校验与风险提示
- 登录后拉取任务并刷新 UI
- 与本地数据的关系（v1.2.0 建议先做到“服务端为准/或本地为准”的单一策略，避免引入复杂冲突解决）
+- 登录后拉取 Todo 数据并刷新 UI
+- 与本地数据的关系（v1.2.0 建议先做到"服务端为准/或本地为准"的单一策略，避免引入复杂冲突解决）

 ## 依赖

- 依赖 `04-*` 提供可用的服务端接口（至少登录 + 获取任务 + 获取安全策略）
+- 依赖 `04-*` 提供可用的服务端接口（至少登录 + 获取 Todo 数据 + 获取安全策略）
 - 与 `03-*`（Search）互不影响，可并行

 ## 关键交互与状态
@@ -28,7 +30,7 @@

 ## 实施步骤（建议）

-1. 增加“同步设置”UI
+1. 增加"同步设置"UI
   - 放置在主界面可发现位置（例如顶部右侧设置按钮/侧边栏）
 2. 服务端地址配置
   - 基础校验：`https?://`、host 合法性、尾部 `/` 处理规则
@@ -36,13 +38,12 @@
 3. 登录与凭据存储策略（与 `06-*` 协同）
   - 在允许落盘场景下可持久化 token/会话
   - 在禁止落盘场景下仅保留内存会话（退出即失效）
-4. 登录后拉取任务
-   - 拉取成功后更新前端任务列表
+4. 登录后拉取 Todo 数据
+   - 拉取成功后更新前端 Todo 列表
   - 拉取失败给出可理解提示，并允许重试

 ## 验收标准

 - 首次启用同步必须先配置服务端地址；地址非法时不可保存并提示原因
- 保存地址时能提示“不可达/证书异常”等风险信息（至少能区分：成功、失败、存在风险但可继续）
- 登录后能从服务端拉取任务并展示在主界面
-
+- 保存地址时能提示"不可达/证书异常"等风险信息（至少能区分：成功、失败、存在风险但可继续）
+- 登录后能从服务端拉取 Todo 数据并展示在主界面
@@ -1,10 +1,12 @@
-# 06 - 云同步（基础可用）：安全（RBAC/二次认证）与“可控落盘”
+# 06 - 云同步（基础可用）：安全（RBAC/二次认证）与"可控落盘"
+
+> 术语：本工单文件归属"研发工单"；文中"任务/Todo 数据"指业务实体（Task / SubTask）。

 ## 目标（PRD 约束）

- 高风险操作支持二次认证（例如启用/关闭同步、切换账号、调整“是否允许落盘”等）
- 客户端读取服务端安全配置，决定任务信息是否允许落盘
- 当服务端标记“终端不可信/不允许落盘”时，客户端只能在内存中持有任务信息；退出应用后不保留任务数据
+- 高风险操作支持二次认证（例如启用/关闭同步、切换账号、调整"是否允许落盘"等）
+- 客户端读取服务端安全配置，决定 Todo 数据是否允许落盘
+- 当服务端标记"终端不可信/不允许落盘"时，客户端只能在内存中持有 Todo 数据；退出应用后不保留 Todo 数据

 ## 范围

@@ -19,10 +21,10 @@

 ## 关键设计点（v1.2.0 必须明确）

-### 1) “落盘”定义与边界
+### 1) "落盘"定义与边界

-需要明确“哪些数据算落盘”，并在禁止落盘时全部避免：
- 任务数据（列表/详情）
+需要明确"哪些数据算落盘"，并在禁止落盘时全部避免：
+- Todo 数据（列表/详情）
 - 同步状态（上次同步时间、待同步队列等）
 - 登录凭据（token/refresh token/会话标识）

@@ -38,20 +40,19 @@

 ### 3) 二次认证（挑战-响应）

-建议采用“服务端驱动”的挑战流程：
+建议采用"服务端驱动"的挑战流程：
 - 客户端发起高风险操作
- 服务端返回“需要二次认证”的响应（包含 challenge 信息）
+- 服务端返回"需要二次认证"的响应（包含 challenge 信息）
 - 客户端弹出二次认证输入（例如二次口令/一次性验证码）
 - 客户端携带证明再次提交

-若服务端暂不支持二次认证，也需有“能力探测/降级提示”，避免客户端卡死。
+若服务端暂不支持二次认证，也需有"能力探测/降级提示"，避免客户端卡死。

 ## 验收标准

 - 服务端返回 `allowPersist=false` 时：
-  - 客户端不会把任务数据与凭据写入任何持久化介质
-  - 退出应用后重新进入，任务数据为空（需重新登录/拉取）
+  - 客户端不会把 Todo 数据与凭据写入任何持久化介质
+  - 退出应用后重新进入，Todo 数据为空（需重新登录/拉取）
 - 对指定高风险操作：
  - 无二次认证证明时被拒绝，并提示需要二次认证
  - 提供正确二次认证后操作成功
-
@@ -55,7 +55,7 @@

 ## 4. 二次认证与会话提升 (Step-up)

-针对高风险操作（如 `sync:write`、`policy:write`），要求会话必须处于“提升状态”。
+针对高风险操作（如 `sync:write`、`policy:write`），要求会话必须处于"提升状态"。

 ### 流程设计

@@ -69,13 +69,13 @@

 ## 5. 安全策略 (Security Policy) 存储与下发

-安全策略决定了客户端的“落盘”行为及二次认证频率。
+安全策略决定了客户端的"落盘"行为及二次认证频率。

 ### 策略定义 (SecurityPolicies 表)

 - `Id`: `int` (主键)
 - `UserId`: `Guid` (外键)
- `AllowPersist`: `bool` (是否允许客户端持久化任务数据)
+- `AllowPersist`: `bool` (是否允许客户端持久化 Todo 数据)
 - `AllowSync`: `bool` (是否允许该用户同步)
 - `SecondFactorExpiryMinutes`: `int` (二次认证状态保持时长，默认 30)
 - `IsTrustedDeviceOnly`: `bool` (是否仅限受信任终端)
@@ -101,33 +101,33 @@

 ### 8.1 二次认证 (Step-up) 交互流程

-1. **静默拦截**: 当用户触发高风险操作（如点击“立即同步”且 Token 已过期或未提升）时，客户端拦截请求并检测到 `403 SECOND_FACTOR_REQUIRED`。
-2. **弹出对话框**: 弹出“安全验证”模态框。
+1. **静默拦截**: 当用户触发高风险操作（如点击"立即同步"且 Token 已过期或未提升）时，客户端拦截请求并检测到 `403 SECOND_FACTOR_REQUIRED`。
+2. **弹出对话框**: 弹出"安全验证"模态框。
   - **标题**: 需要二次认证。
-   - **描述**: “为了保护您的数据安全，执行此操作需要验证身份。”
+   - **描述**: "为了保护您的数据安全，执行此操作需要验证身份。"
   - **输入**: 密码输入框（或 TOTP 验证码输入框）。
   - **操作**: \[取消] \[验证并继续]。
-3. **状态保持**: 验证成功后，UI 应显示短暂的“验证成功”提示，并自动重试刚才被拦截的操作。
+3. **状态保持**: 验证成功后，UI 应显示短暂的"验证成功"提示，并自动重试刚才被拦截的操作。

 ### 8.2 客户端 UI (针对普通用户)

-在客户端“设置 -> 云同步 -> 安全”路径下：
+在客户端"设置 -> 云同步 -> 安全"路径下：

 - **落盘策略 (AllowPersist)**:
  - **展示**: 状态开关（Toggle）。
  - **交互**:
-    - 若由服务端强制禁止，开关应为禁用状态（Disabled），并附带说明：“受服务端策略限制，当前终端禁止落盘”。
-    - 若允许修改，关闭开关时应弹出强提醒：“关闭后，所有本地任务数据将被立即清除，退出应用后数据将不再保留。确定继续吗？”
+    - 若由服务端强制禁止，开关应为禁用状态（Disabled），并附带说明："受服务端策略限制，当前终端禁止落盘"。
+    - 若允许修改，关闭开关时应弹出强提醒："关闭后，所有本地 Todo 数据将被立即清除，退出应用后数据将不再保留。确定继续吗？"
 - **二次认证频率**:
  - **展示**: 显示当前二次认证的有效期（如 30 分钟）。

-### 8.3 “不可落盘”模式下的视觉提示
+### 8.3 "不可落盘"模式下的视觉提示

 当 `allowPersist == false` 时：

- **状态栏/标题栏**: 增加“无痕模式”或“内存存储”小图标/文字提醒。
- **登录页**: 增加提醒：“当前环境配置为禁止落盘，数据仅在本次运行期间有效”。
- **退出应用**: 点击退出时，若有未同步数据，强提醒：“数据未同步且本地禁止落盘，退出将导致数据丢失。确定退出吗？”
+- **状态栏/标题栏**: 增加"无痕模式"或"内存存储"小图标/文字提醒。
+- **登录页**: 增加提醒："当前环境配置为禁止落盘，数据仅在本次运行期间有效"。
+- **退出应用**: 点击退出时，若有未同步数据，强提醒："数据未同步且本地禁止落盘，退出将导致数据丢失。确定退出吗？"

 ***

@@ -146,7 +146,7 @@
 ### 9.2 系统初始化 (Bootstrap)

 - **触发条件**: 当检测到数据库中无任何用户时，访问 `/admin` 自动跳转至 `/admin/bootstrap`。
- **功能**: 创建首个“超级管理员”账号。
+- **功能**: 创建首个"超级管理员"账号。
 - **UI**: 简单的表单（用户名、密码、确认密码）。

 ### 9.3 用户管理 (User Management)
@@ -169,7 +169,7 @@
 ### 9.6 审计日志查看器 (Audit Log Viewer)

 - **过滤查询**: 按时间、用户、事件类型（登录、同步、策略变更）过滤。
- **高亮显示**: 对“二次认证失败”、“异常 IP 登录”等敏感事件进行红色高亮。
+- **高亮显示**: 对"二次认证失败"、"异常 IP 登录"等敏感事件进行红色高亮。

 ***

@@ -178,4 +178,3 @@
 - **Token 吊销**: 默认 JWT 是无状态的。若需支持强制下线，需引入 Redis/DB 黑名单。
 - **HTTPS**: 所有安全通信必须基于 TLS，防止中间人攻击窃取 Token。
 - **暴力破解**: 需在 `POST /auth/login` 接口增加限流（Rate Limiting）机制。
-
@@ -1,5 +1,7 @@
 # 07 - 文档同步与验收清单（v1.2.0）

+> 术语：本工单文件本身归属"研发工单"；文中"任务/Todo 待办项"指业务实体（Task / SubTask）。
+
 ## 目标

 - 保证 v1.2.0 实现后，README 与 docs 中的说明与实际代码一致
@@ -9,7 +11,7 @@

 - README：Features、运行方式、API 说明（如涉及）
 - docs：技术设计文档/技术栈与模块/版本记录（如涉及）
- 本目录任务文件：保持与实现同步（必要时更新验收口径与依赖关系）
+- 本目录工单文件：保持与实现同步（必要时更新验收口径与依赖关系）

 ## 必做同步点（结合当前仓库现状）

@@ -23,7 +25,7 @@
 ### Linux
 - [x] Linux 上可启动并打开主界面
 - [x] WebView 能渲染 Vue 前端且路由可用（刷新不 404）
- [x] 前端能成功请求本地 `/api/*` 并加载任务列表
+- [x] 前端能成功请求本地 `/api/*` 并加载 Todo 待办项列表
 - [x] 有至少一种自包含交付产物（AppImage/Flatpak 二选一）可运行（见 pack/linux/README.md）

 ### Search
@@ -33,7 +35,6 @@

 ### 云同步（基础可用）
 - [x] 可手动配置服务端地址，并有基础校验与风险提示
- [x] 登录后能拉取该用户任务并展示
+- [x] 登录后能拉取该用户的 Todo 数据并展示
 - [x] 服务端策略 `allowPersist=false` 时客户端不落盘，退出后数据不保留
 - [x] 高风险操作触发二次认证（服务端支持时）
-
@@ -16,12 +16,12 @@ src/
 │
 ├── Hua.Todo.Host/               ← ASP.NET 服务端（云同步接口的提供方）
 │   └── Program.cs
-│       ├── AddApplicationServices()  ← 任务 CRUD 服务
+│       ├── AddApplicationServices()  ← Todo CRUD 服务
 │       └── AddCloudSyncServer()      ← 云同步认证/授权/端点  **仅服务端**
 │
 └── Hua.Todo.Maui/               ← 桌面/移动客户端（嵌入 WebView）
    └── MauiProgram.cs
-        └── AddApplicationServices()  ← **仅** 任务 CRUD 服务
+        └── AddApplicationServices()  ← **仅** Todo CRUD 服务
            （不注册 AddCloudSyncServer，不暴露云同步端点）
 ```

@@ -41,9 +41,9 @@ src/
 │  proxy /api                    │
 ├───────────────────────────────┤
 │  ASP.NET Host (:5173)          │
-│  AddApplicationServices()      │  任务 CRUD
+│  AddApplicationServices()      │  Todo CRUD
 │  AddCloudSyncServer()          │  云同步端点  ← **服务端**
-│  ├─ /api/*     (本地任务)       │
+│  ├─ /api/*     (本地 Todo)      │
 │  └─ /auth/*    (云同步)         │
 │     /tasks/*                   │
 │     /cloud-sync/probe  (新增)  │
@@ -59,19 +59,19 @@ src/
 │  │  Vue 前端 (静态托管)      │  │
 │  │  cloudClient             │  │
 │  │    baseURL = 同源        │  │  同源请求
-│  │    → /api/*   (本地任务)  │──┼───────→ Embedded WebServer
+│  │    → /api/*   (本地 Todo) │──┼───────→ Embedded WebServer
 │  │    → /auth/*  (❌ 不可用) │  │        (不暴露云同步端点)
 │  └─────────────────────────┘  │
 ├───────────────────────────────┤
 │  Embedded WebServer (:5057)   │
-│  AddApplicationServices()     │  仅任务 CRUD
+│  AddApplicationServices()     │  仅 Todo CRUD
 │  AddCloudSyncServer()         │  ❌ 未注册
-│  UseDynamicApi()              │  仅本地任务 API
+│  UseDynamicApi()              │  仅本地 Todo API
 │  MapCloudSyncEndpoints()      │  ❌ 未映射
 └───────────────────────────────┘
 ```

-> **关键区别**：`Hua.Todo.Application` 被两方引用，但云同步能力**仅在 Host 端通过 `AddCloudSyncServer()` 激活**。MAUI 端只使用 `AddApplicationServices()` 获取任务 CRUD 能力，**不暴露也不应暴露云同步端点**。
+> **关键区别**：`Hua.Todo.Application` 被两方引用，但云同步能力**仅在 Host 端通过 `AddCloudSyncServer()` 激活**。MAUI 端只使用 `AddApplicationServices()` 获取 Todo CRUD 能力，**不暴露也不应暴露云同步端点**。

 #### 1.3 核心问题

@@ -272,7 +272,7 @@ server: {
 |---|---|---|
 | **用途** | 云同步 API 的 base URL（前端直连） | 仅用于"服务端探测"的目标地址 |
 | **存储位置** | `localStorage` | 不变（探测时使用） |
-| **影响登录/任务拉取** | 是（前端用它做 baseURL） | 否（走 Host 自身端点） |
+| **影响登录/Todo 拉取** | 是（前端用它做 baseURL） | 否（走 Host 自身端点） |

 ### 4. 需要变更的文件清单