doc:输出1.2.0版本需求文档

2026-04-07 00:21:15 +08:00
parent 141b3112a4
commit 18d37fdd24
13 changed files with 485 additions and 45 deletions
@@ -0,0 +1,37 @@
+# Hua.Todo v1.2.0 任务拆分总览
+
+本目录用于把 [产品需求文档-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 + 二次认证；用户级数据隔离；服务端配置驱动的“可控落盘”
+
+## 当前实现基线（用于任务定位）
+
+- 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 打包/交付产物（优先自包含：AppImage/Flatpak 之一；补充 .deb/.tar.gz）
+- **Search 线**：`03-*`
+  - 主要在前端完成；与云同步/平台入口基本无耦合，可并行
+- **云同步线**：`04-*` + `05-*` + `06-*`
+  - 04：服务端基础能力（登录、任务同步/读取、配置下发、用户隔离）
+  - 05：客户端配置与同步工作流（手动指定服务端地址、登录后拉取任务）
+  - 06：安全与落盘策略（RBAC、二次认证、可控落盘与“内存模式”）
+- **文档与验收线**：`07-*`
+  - 对齐文档与现实现状/接口；补齐验收步骤与自测清单
+
+## 交付判定（v1.2.0 Done Definition）
+
+- Linux：在基线发行版（建议 Ubuntu LTS）上可启动、可渲染前端、可调用本地 API；且有可安装/可运行的交付产物
+- Search：可在主界面按标题实时过滤任务（含层级任务的展示策略清晰）
+- 云同步（基础可用）：可配置服务端地址；登录后可拉取该用户任务；服务端可下发“是否允许落盘”；客户端在禁止落盘时不产生本地持久化
+
@@ -0,0 +1,64 @@
+# 01 - Linux：Avalonia 入口 + WebView 承载 Vue
+
+## 目标
+
+- 新增一个 **Linux 桌面端入口**（Avalonia）作为 Hua.Todo 的 Linux 宿主
+- 在 Linux 宿主中用 **WebView** 加载同一套 Vue 前端（与 MAUI 端共用前端构建产物与资源路径约定）
+- 复用既有“前端 ↔ 本地 API”的交互方式（HTTP API + 现有注入变量/事件名），保证前端无需为 Linux 分叉
+
+## 范围
+
+- 新增/调整项目结构以容纳 Avalonia 入口（建议新项目：`src/Hua.Todo.Avalonia` 或 `src/Hua.Todo.Desktop.Avalonia`）
+- 在 Avalonia 中接入可在 Linux 运行的 WebView 控件（需要先调研与选型）
+- 确保能正确加载：
+  - 内嵌 WebServer 的 `BaseUrl`
+  - 以及前端静态资源（开发态/生产态策略需明确）
+
+## 依赖
+
+- 依赖 `04-*`/`05-*` 的云同步工作不强依赖本任务，可并行
+- 依赖前端已有构建产物或构建流程（至少能得到 `dist/` 或等效 `wwwroot/`）
+
+## 关键决策点（必须在实现前落定）
+
+### 1) Avalonia/Linux 可用的 WebView 方案选型
+
+候选方向（示例，最终以调研结果为准）：
+- WebKitGTK 系（Linux 依赖较重，但适配面广）
+- Chromium 系（体积/依赖/许可成本需评估）
+
+选型必须满足的最低能力：
+- 基础导航与本地资源加载
+- JS 执行/注入（用于对齐 `window.__API_BASE_URL__` 等契约）
+- JS ↔ Native 双向通信（至少开发阶段可观测；可先只保证“HTTP API”路径通）
+- 开发期可用 DevTools（至少能定位网络请求与控制台错误）
+
+### 2) 资源加载策略（与 MAUI 对齐）
+
+需要明确并实现两种模式：
+- 开发态：Avalonia WebView 指向前端 dev server（例如 `http://localhost:5173`）或指向本地 WebServer
+- 生产态：加载随应用交付的静态资源（`wwwroot`）并确保 SPA fallback 生效（访问非 `/assets/*` 的路由能回到 `index.html`）
+
+## 实施步骤（建议）
+
+1. 新建 Avalonia 宿主项目
+   - 提供 App/Window/MainView 基础结构
+2. 接入 WebView 控件并完成最小加载闭环
+   - 能显示 `index.html`，能打开前端路由
+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”的方式（推荐一致化，减少前端差异）
+5. 输入法/字体/DPI 验证与可配置化
+   - 至少验证：中文输入法、缩放、Wayland/X11 下可用性
+
+## 验收标准
+
+- 在 Linux（建议 Ubuntu LTS）上启动 Avalonia 入口后：
+  - WebView 正常渲染前端主界面
+  - 前端能通过 `window.__API_BASE_URL__` 正确请求本地 `/api/*`（至少任务列表接口可用）
+  - 页面路由/刷新不会出现 404（SPA fallback 生效）
+- 开发态可调试（至少能看到控制台/网络错误，或能通过日志定位）
+
@@ -0,0 +1,41 @@
+# 02 - Linux：打包、依赖与交付产物
+
+## 目标
+
+- 为 Linux 提供可安装/可分发的交付产物，并尽量做到“用户机器无需手动补大量依赖即可运行”
+- 明确最低支持发行版范围（建议 Ubuntu LTS 作为基线）与依赖策略（WebView 运行时/字体/输入法等）
+
+## 范围
+
+- 构建脚本与产物输出
+- 运行时依赖打包策略（尤其是 WebView 相关）
+- 基础安装/运行说明（README / docs 更新）
+
+## 依赖
+
+- 依赖 `01-*`（Avalonia 入口与 WebView 方案已定、并能在开发机运行）
+
+## 交付形式（PRD 约束）
+
+- 优先提供一种“自包含”官方安装方式（AppImage/Flatpak 二选一，建议先做一条跑通）
+- 同时保留 `.deb` 或 `.tar.gz` 作为补充分发形式（以脚本产出为准）
+
+## 实施步骤（建议）
+
+1. 确定 Linux 发行版基线与运行时依赖清单
+   - 记录：最低 glibc、Wayland/X11、WebView 运行时依赖、字体包
+2. 选择并落地一种自包含交付形式
+   - AppImage：偏“拎包即用”，对依赖捆绑要求高
+   - Flatpak：沙盒与运行时生态更成熟，但需要 manifest 与权限策略
+3. 补充 `.deb` 或 `.tar.gz`
+   - `.deb`：适合 Ubuntu/Debian 系；需要 desktop entry、图标、依赖声明
+   - `.tar.gz`：最通用；需要启动脚本与依赖说明
+4. 增加启动前自检（可选但推荐）
+   - 发现关键依赖缺失时给出清晰错误提示与修复建议
+
+## 验收标准
+
+- 产物可在“干净环境”（尽量接近用户机）安装/运行
+- 启动后 WebView 能渲染前端，且本地 API 可用
+- 文档中给出的安装/运行步骤可复现，且与产物一致
+
@@ -0,0 +1,45 @@
+# 03 - Search：任务标题关键词检索
+
+## 目标
+
+- 在主界面顶部增加搜索框
+- 支持按任务标题进行模糊匹配（实时过滤）
+
+## 范围
+
+- 前端 UI：输入框、清空按钮、键盘交互（Esc 清空、Enter 可选）
+- 过滤逻辑：对“树状任务”给出明确策略
+- 性能：任务量增大时仍保持可用（至少避免 O(n^2) 的明显退化）
+
+## 依赖
+
+- 不依赖 Linux/Avalonia 或云同步，可独立并行完成
+
+## 过滤策略（需在实现时确定，并写入实现说明）
+
+树状任务（父子任务）常见两种策略，任选其一并保持一致：
+
+1. **命中即显示（含上下文）**
+   - 任意节点标题命中则显示该节点
+   - 若子任务命中，可同时显示其祖先链（便于理解层级）
+2. **扁平化命中**
+   - 只显示命中的任务（可能丢失层级语义）
+
+建议优先采用“命中即显示（含上下文）”，用户可更快定位。
+
+## 实施步骤（建议）
+
+1. 确定搜索框放置位置（主界面顶部）
+2. 增加 `searchQuery` 状态与派生 `filteredTasks`
+3. 将过滤逻辑接入现有列表渲染
+4. 补充交互细节
+   - 输入时实时过滤
+   - 清空按钮
+   - Esc 清空、保持输入焦点（可选）
+
+## 验收标准
+
+- 输入关键字后，任务列表实时过滤，仅展示命中结果（符合上述策略）
+- 清空后恢复原列表
+- 对中英文与大小写的处理行为明确（至少：英文大小写不敏感；中文按包含匹配）
+
@@ -0,0 +1,51 @@
+# 04 - 云同步（基础可用）：服务端基础能力
+
+## 目标（PRD 约束）
+
+- 支持用户级任务数据同步/读取（用户隔离）
+- 提供基于角色/权限的访问控制（RBAC）
+- 对高风险操作支持二次认证（能力以服务端实现为准）
+- 下发“可控落盘”配置（服务端配置驱动）
+
+## 范围（建议最小闭环）
+
+- 认证（登录/会话）
+- 任务数据 API（按用户隔离）
+- 配置下发 API（是否允许落盘、终端可信度/会话策略等）
+- RBAC 最小落地（至少能区分“允许同步/禁止同步”或“只读/读写”）
+- 二次认证最小落地（至少覆盖“启用/关闭同步、切换账号、调整落盘策略”等高风险操作的接口）
+
+## 依赖
+
+- 与 `05-*`（客户端）可并行推进，但需要尽早冻结 API 契约（字段名/响应结构/错误码）
+
+## 接口契约（需要在实现前先写清楚）
+
+建议输出一份“云同步 API 契约”并固化到 docs（便于客户端对接）。至少包含：
+- 登录：`POST /auth/login`（或等效）
+- 获取用户任务：`GET /tasks`（或等效，支持增量/版本号是加分项，但 v1.2.0 可先全量）
+- 上传/同步：`POST /sync`（或按任务粒度的增删改接口）
+- 获取安全配置：`GET /security/policy`
+  - 返回字段至少包含：`allowPersist`（是否允许落盘）
+  - 可扩展：`deviceTrust`、`sessionTtl`、`requireSecondFactorFor` 等
+
+## 关键实现点（建议）
+
+1. 用户隔离
+   - 服务端所有读写必须绑定当前登录用户上下文
+2. 权限模型（RBAC）
+   - 定义最小角色：例如 `user`、`admin`
+   - 定义最小权限：例如 `tasks:read`、`tasks:write`、`sync:enable`
+3. 二次认证
+   - 选择实现方式（示例）：二次口令/一次性验证码（TOTP）/短信（若无能力则先实现“二次口令”）
+   - 能力不足时必须返回明确错误，使客户端可提示用户
+4. 落盘策略下发
+   - 支持按用户或按会话/终端下发
+   - 默认策略建议为“允许落盘”，便于可用性；但需支持“禁止落盘”
+
+## 验收标准
+
+- 使用不同用户登录后获取任务，数据严格隔离
+- 未授权角色/权限访问受限接口会被拒绝（错误响应可被客户端识别）
+- 能返回安全策略配置（至少包含 `allowPersist`），并可通过配置切换行为
+
@@ -0,0 +1,48 @@
+# 05 - 云同步（基础可用）：客户端配置与同步工作流
+
+## 目标（PRD 约束）
+
+- 首次启用同步时，用户需要**手动填写服务端地址**（例如 `https://example.com`），并允许后续在设置中修改
+- 客户端对地址格式做基础校验，并在保存时提示可达性/证书异常等风险信息
+- 用户登录成功后，从服务端获取该用户任务并更新到前端展示
+
+## 范围（建议最小闭环）
+
+- “同步设置”入口与界面（服务端地址、登录、同步开关）
+- 地址校验与风险提示
+- 登录后拉取任务并刷新 UI
+- 与本地数据的关系（v1.2.0 建议先做到“服务端为准/或本地为准”的单一策略，避免引入复杂冲突解决）
+
+## 依赖
+
+- 依赖 `04-*` 提供可用的服务端接口（至少登录 + 获取任务 + 获取安全策略）
+- 与 `03-*`（Search）互不影响，可并行
+
+## 关键交互与状态
+
+需要定义并贯穿实现的状态机（至少包含）：
+- 未配置服务端地址
+- 已配置未登录
+- 已登录（可同步）
+- 同步中/同步失败/同步成功（含失败原因）
+
+## 实施步骤（建议）
+
+1. 增加“同步设置”UI
+   - 放置在主界面可发现位置（例如顶部右侧设置按钮/侧边栏）
+2. 服务端地址配置
+   - 基础校验：`https?://`、host 合法性、尾部 `/` 处理规则
+   - 保存时探测：尝试请求服务端健康检查或登录端点（并提示证书异常/不可达等）
+3. 登录与凭据存储策略（与 `06-*` 协同）
+   - 在允许落盘场景下可持久化 token/会话
+   - 在禁止落盘场景下仅保留内存会话（退出即失效）
+4. 登录后拉取任务
+   - 拉取成功后更新前端任务列表
+   - 拉取失败给出可理解提示，并允许重试
+
+## 验收标准
+
+- 首次启用同步必须先配置服务端地址；地址非法时不可保存并提示原因
+- 保存地址时能提示“不可达/证书异常”等风险信息（至少能区分：成功、失败、存在风险但可继续）
+- 登录后能从服务端拉取任务并展示在主界面
+
@@ -0,0 +1,56 @@
+# 06 - 云同步（基础可用）：安全（RBAC/二次认证）与“可控落盘”
+
+## 目标（PRD 约束）
+
+- 高风险操作支持二次认证（例如启用/关闭同步、切换账号、调整“是否允许落盘”等）
+- 客户端读取服务端安全配置，决定任务信息是否允许落盘
+- 当服务端标记“终端不可信/不允许落盘”时，客户端只能在内存中持有任务信息；退出应用后不保留任务数据
+
+## 范围
+
+- 客户端：落盘策略切换（持久化 ↔ 内存）、高风险操作二次确认/二次认证 UI
+- 服务端：策略下发 + 二次认证挑战/校验接口（与 `04-*` 协作）
+
+## 依赖
+
+- 依赖 `04-*` 提供策略下发与二次认证能力（至少一种实现）
+- 依赖 `05-*` 的基础登录/同步 UI 入口
+
+## 关键设计点（v1.2.0 必须明确）
+
+### 1) “落盘”定义与边界
+
+需要明确“哪些数据算落盘”，并在禁止落盘时全部避免：
+- 任务数据（列表/详情）
+- 同步状态（上次同步时间、待同步队列等）
+- 登录凭据（token/refresh token/会话标识）
+
+### 2) 本地存储抽象
+
+建议把前端（或宿主）本地存储封装为可替换实现：
+- 允许落盘：使用现有 localStorage/SQLite 等
+- 禁止落盘：使用内存实现（刷新/退出即清空）
+
+要求：
+- 切换策略时行为可预期（例如从允许 → 禁止：立即清空已落盘数据并提示用户）
+- 不在日志或 UI 中暴露敏感信息
+
+### 3) 二次认证（挑战-响应）
+
+建议采用“服务端驱动”的挑战流程：
+- 客户端发起高风险操作
+- 服务端返回“需要二次认证”的响应（包含 challenge 信息）
+- 客户端弹出二次认证输入（例如二次口令/一次性验证码）
+- 客户端携带证明再次提交
+
+若服务端暂不支持二次认证，也需有“能力探测/降级提示”，避免客户端卡死。
+
+## 验收标准
+
+- 服务端返回 `allowPersist=false` 时：
+  - 客户端不会把任务数据与凭据写入任何持久化介质
+  - 退出应用后重新进入，任务数据为空（需重新登录/拉取）
+- 对指定高风险操作：
+  - 无二次认证证明时被拒绝，并提示需要二次认证
+  - 提供正确二次认证后操作成功
+
@@ -0,0 +1,39 @@
+# 07 - 文档同步与验收清单（v1.2.0）
+
+## 目标
+
+- 保证 v1.2.0 实现后，README 与 docs 中的说明与实际代码一致
+- 为 Linux / Search / 云同步提供可复现的验收步骤
+
+## 范围
+
+- README：Features、运行方式、API 说明（如涉及）
+- docs：技术设计文档/技术栈与模块/版本记录（如涉及）
+- 本目录任务文件：保持与实现同步（必要时更新验收口径与依赖关系）
+
+## 必做同步点（结合当前仓库现状）
+
+- **API 端点与项目结构**：对齐实际实现（避免文档仍描述不存在的项目或旧端点）
+- **Linux 入口说明**：新增 Avalonia 入口的构建/运行/打包方式
+- **云同步说明**：服务端地址配置、登录、落盘策略与安全机制（RBAC/二次认证）的用户可理解描述
+- **版本记录**：在 `docs/版本记录.md` 增加 v1.2.0 非琐碎变更条目
+
+## 验收清单（建议逐项勾选）
+
+### Linux
+- [ ] Linux 上可启动并打开主界面
+- [ ] WebView 能渲染 Vue 前端且路由可用（刷新不 404）
+- [ ] 前端能成功请求本地 `/api/*` 并加载任务列表
+- [ ] 有至少一种自包含交付产物（AppImage/Flatpak 二选一）可运行
+
+### Search
+- [ ] 主界面有搜索框
+- [ ] 输入关键字后列表实时过滤（层级策略符合 `03-*` 定义）
+- [ ] 清空后恢复原列表
+
+### 云同步（基础可用）
+- [ ] 可手动配置服务端地址，并有基础校验与风险提示
+- [ ] 登录后能拉取该用户任务并展示
+- [ ] 服务端策略 `allowPersist=false` 时客户端不落盘，退出后数据不保留
+- [ ] 高风险操作触发二次认证（服务端支持时）
+
@@ -1,77 +1,84 @@
 # Hua.Todo 产品需求文档 (PRD) v1.2.0

 ## 1. 项目概述
-在 v1.1.0 版本成功实现 MAUI + WebView 跨平台架构的基础上，v1.2.0 版本将重点提升任务管理的精细化程度，完善平台支持（Linux），并增强用户体验（暗色模式、提醒功能）。
+
+在 v1.1.0 版本成功实现 MAUI + WebView 跨平台架构的基础上，v1.2.0 版本将以“**MAUI 入口保持不动 + Linux 新增 Avalonia 入口**”的方式落地 Linux 支持（继续使用 WebView 承载 Vue 前端），并在此基础上探索 Avalonia 对其他终端的支持情况；若验证效果良好，后续版本将推进各终端入口统一切换到 Avalonia。

 ## 2. 核心目标
+
 - **完善平台覆盖**：正式支持 Linux 平台。
- **增强任务组织**：引入搜索、过滤和标签系统。
- **提升交互体验**：支持本地通知提醒及暗色模式。
- **数据安全保障**：实现基础的数据导入导出功能。
+- **增强任务组织**：引入搜索。
+- **云同步（基础可用）**：支持用户级任务数据同步与“可控落盘”（在不信任终端场景下可禁止落盘）。

 ## 3. 功能需求

 ### 3.1 平台支持：Linux 官方支持
+
+- **客户端框架迁移**：保持原 MAUI 项目不动，实现 Avalonia 对 Linux 端支持，并探索 Avalonia 对 Android 和其他平台的支持。
+- **终端入口策略（v1.2.0）**：
+  - **保持 MAUI 入口不动**：Windows/macOS/iOS/Android 继续沿用现有 MAUI 入口与 WebView 方案，保证迭代稳定性。
+  - **Linux 使用 Avalonia 作为入口**：新增 Avalonia 桌面端宿主作为 Linux 入口，继续用 WebView 承载同一套 Vue 前端，并复用既有“本地 API ↔ 前端”的交互协议。
+  - **评估全端切换可行性**：在完成 Linux 入口落地后，评估 Avalonia 在 Windows/macOS（以及后续 Android 等）的稳定性、WebView 兼容性与打包成本；若效果良好，后续版本将各终端入口统一切换到 Avalonia。
 - **适配性**：确保 WebView 在 Linux 环境下的正常渲染与交互。
 - **打包部署**：提供 Linux 平台的打包脚本（如 .deb 或 .tar.gz）。

-### 3.2 任务检索与过滤 (Search & Filter)
+### 3.2 任务检索 (Search)
+
 - **关键词搜索**：在主界面顶部增加搜索框，支持按任务标题模糊匹配。
- **高级过滤**：
-  - 按优先级过滤（高、中、低）。
-  - 按标签过滤。
-  - 按创建/完成时间段过滤。

-### 3.3 本地提醒 (Local Reminders)
- **提醒设置**：在任务编辑界面增加“提醒时间”字段。
- **通知触发**：当达到提醒时间时，通过平台原生 API 发送本地通知（Notification）。
- **状态反馈**：已过期的提醒任务在列表中有明显的视觉标识。
+### 3.3 云同步（基础可用）

-### 3.4 标签系统 (Tag System)
- **多标签支持**：一个任务可关联多个标签。
- **标签管理**：支持自定义标签名称和颜色。
- **快速归类**：通过标签快速筛选相关任务。
+#### 3.3.1 服务端地址配置（用户手动指定）

-### 3.5 主题增强：暗色模式 (Dark Mode)
- **自动切换**：根据系统主题自动切换浅色/深色模式。
- **手动控制**：在设置中提供手动切换开关。
- **UI 适配**：Vue 前端及 MAUI 原生部分均需完成暗色模式适配。
+- **用户手动指定服务端地址**：首次启用同步时，用户需要手动填写服务端地址（例如 `https://example.com`），并允许后续在设置中修改。
+- **地址有效性提示**：客户端需对地址格式做基础校验，并在保存时提示可达性/证书异常等风险信息。

-### 3.6 数据迁移 (Data Migration)
- **导出功能**：支持将所有任务数据导出为 JSON 格式文件。
- **导入功能**：支持从 JSON 文件恢复数据，解决跨设备迁移问题。
+#### 3.3.2 权限与二次认证（RBAC + 二次认证）
+
+- **RBAC 权限模型**：服务端必须提供基于角色/权限的访问控制（Role-Based Access Control），以支持后续按功能、数据域进行授权。
+- **二次认证**：对高风险操作（例如启用/关闭同步、切换账号、调整“是否允许落盘”等安全相关配置）应支持二次认证机制（例如二次口令/一次性验证码等），具体实现以服务端能力为准。
+
+#### 3.3.3 基于用户的数据隔离
+
+- **用户级数据隔离**：服务端必须按用户隔离任务数据，任何同步、检索与配置读取都必须绑定当前登录用户上下文。
+- **最小权限原则**：客户端仅请求完成任务同步所需的最小权限范围，避免默认授予不必要的数据访问能力。
+
+#### 3.3.4 同步工作流（登录后获取任务 + 可控落盘）
+
+- **登录后拉取任务**：用户登录成功后，客户端从服务端获取该用户的任务信息并更新到前端展示。
+- **服务端配置驱动的落盘策略**：客户端需读取服务端针对该用户（或该会话/终端）的安全配置，决定任务信息是否允许落盘到本地存储。
+- **不信任终端禁止落盘**：当服务端标记“终端不可信/不允许落盘”时，客户端只能在内存中持有任务信息；退出应用后不保留任务数据。

 ## 4. 技术实现要点

 ### 4.1 Linux 适配
- 使用 WebKitGTK 作为 WebView 容器。
- 适配 Linux 下的全局快捷键实现。

-### 4.2 本地通知
- 使用 `Plugin.LocalNotification` 或 MAUI 自带的通知机制（取决于 .NET 10 的最新支持）。
- 确保后台服务在移动端能准时触发提醒。
+v1.1.0 起客户端使用 **MAUI WebView** 承载 Vue 前端；在 v1.2.0 中，保持现有 MAUI 入口不动，同时为 Linux 新增 **Avalonia 桌面端**入口，并继续以 WebView 承载同一套 Vue 前端。后续将基于 Linux 端落地经验评估 Avalonia 对 Windows/macOS（以及后续 Android 等）的覆盖与稳定性，满足条件后推进全端入口统一。

-### 4.3 标签数据结构
- 在 `TaskEntity` 中增加 `Tags` 关联（多对多关系或简单的 JSON 存储）。
+#### 4.1.1 Linux 解决方案（Avalonia 入口 + WebView 承载 Vue）

-### 4.4 主题管理
- 使用 CSS Variables (Custom Properties) 管理前端主题颜色。
- 监听 `(prefers-color-scheme: dark)` 媒体查询。
+- **入口与架构**：Linux 端新增 Avalonia 桌面宿主作为应用入口；加载同一套 Vue 前端，并保持与现有 MAUI 端一致的“前端调用本地 API”协议与数据模型，确保业务逻辑与 UI 复用。
+- **WebView 方案**：选用可在 Avalonia/Linux 运行的 WebView 控件承载前端（以 WebKitGTK/Chromium 系为候选实现），统一约束：支持基础导航/本地资源加载、JS ↔ Native 双向通信、DevTools（至少开发环境可用）。
+- **发行版与依赖策略**：定义最低支持范围（例如 Ubuntu LTS 系列作为基线），并将 WebView 运行时依赖纳入打包交付（避免用户手动安装大量依赖导致不可用）。
+- **输入法/字体/DPI**：提供默认 CJK 字体与渲染配置，验证 IME、缩放、Wayland/X11 关键组合；遇到环境差异时以“可配置 + 明确降级”保证可用性。
+- **快捷键策略**：全局快捷键在 Linux 上采用“尽力而为”的可插拔实现；在 Wayland 等受限环境下自动降级为应用内快捷键，并在设置中提供可配置与提示。
+- **交付形式**：优先提供一种“自包含”的交付产物（例如 AppImage/Flatpak 之一）作为官方安装方式，同时保留 `.deb/.tar.gz` 作为补充分发形式（以脚本产出为准）。

 ## 5. 版本规划

 ### 5.1 v1.2.0 目标
+
 - [ ] Linux 平台完整支持与打包脚本。
- [ ] 搜索框及多维过滤功能。
- [ ] 本地提醒（提醒时间设置与通知触发）。
- [ ] 基础标签功能（创建、关联、过滤）。
- [ ] 全局暗色模式适配。
- [ ] 数据导入导出（JSON）。
+- [ ] 搜索框（关键词检索）。
+- [ ] 云同步（基础可用：用户手动配置服务端地址、RBAC + 二次认证、用户级数据隔离、服务端配置驱动的可控落盘）。

 ### 5.2 后续版本规划
- **v1.3.0**：云同步功能（接入第三方云盘或自建服务）。
- **v1.4.0**：统计图表（任务完成趋势、时间分配分析）。
+
+- **v1.3.0**：数据导入导出（JSON）、统计图表（任务完成趋势、时间分配分析）。
+- **v1.4.0**：高级过滤（优先级/时间段）与更丰富的视图（如看板/日历）。

 ## 6. 风险评估
+
 - **Linux 碎片化**：不同发行版下 WebView 的依赖库可能不一致。
- **移动端后台限制**：Android/iOS 对后台进程的限制可能导致提醒不准时。
+- **凭据与合规**：第三方服务鉴权方式差异大，且必须保证凭据安全存储与最小化权限。
+- **终端可信度与数据落盘**：若需支持“不信任终端不落盘”，需要明确“可信度判定与配置下发”的服务端策略，并保证客户端在无落盘场景下的可用性与体验。