doc:输出1.2.0版本需求文档

2026-04-07 00:21:15 +08:00
parent 141b3112a4
commit 1d62916076
4 changed files with 61 additions and 45 deletions
@@ -10,6 +10,7 @@ description: 强制文档同步规范：每次变更代码（如新增功能、
 - **代码即文档，文档随代码**：文档不是静态的，它必须真实反映当前代码的状态。
 - **及时性**：在提交代码变更的同时（或紧随其后），必须完成相关文档的更新。
 - **准确性**：确保文档中的示例代码、接口说明、安装步骤与实际代码完全一致。
+- **协作友好（局部修改）**：当并行处理多个任务/需求时，更新文档应尽量只修改与本任务直接相关的段落/小节，避免对不相关内容做无意义的重排、改写或格式化；如必须调整非关联内容，应拆分为独立的变更说明清楚原因与影响范围。

 ## 更新范围

@@ -30,3 +31,4 @@ description: 强制文档同步规范：每次变更代码（如新增功能、
 3. [ ] 是否有新增的功能模块？（更新产品需求文档和技术栈说明）
 4. [ ] 是否调整了开发环境或依赖？（更新 README）
 5. [ ] 是否在 [版本记录.md](docs/版本记录.md) 中记录了本次变更？
+6. [ ] 文档变更是否保持“局部修改”，只影响与本任务相关的段落/小节？（避免无关重排/改写）
@@ -310,6 +310,7 @@ CREATE TABLE Settings (
 - **Windows**: WebView2 运行时要求
 - **macOS**: 代码签名和公证
 - **移动端**: 应用商店发布配置
+- **Linux**: .NET MAUI 无官方 Linux 目标，需要引入独立桌面宿主（例如基于 WebKitGTK 的方案）并处理运行时依赖与打包格式

 ## 9. 性能优化

@@ -3,17 +3,22 @@
 ## 🔄 版本更新

 ### 版本策略
+
 - 采用语义化版本号：`MAJOR.MINOR.PATCH`
 - v1.0.0：初始 WPF 版本
 - v1.1.0：MAUI + WebView 跨平台版本
 - v1.2.0 (规划中)：Linux 支持与增强功能

 ### v1.1.1 (2026-04-06)
+
 - **文档规范增强**：新增文档同步规则，强制代码变更与文档更新保持同步。
 - **项目结构说明校准**：修正 README.md 和技术文档中对 `Hua.Todo.Host`、`Hua.Todo.Application` 等模块的路径与职责描述。
 - **端口配置校准**：修正文档中关于前端与后端 API 的端口说明（5173/5174）。
+- **PRD 校准**：移除 v1.2.0 PRD 中“本地迭代不支持”表述与“数据迁移（导入/导出）”小节。
+- **PRD 校准**：移除 v1.2.0 PRD 中“云同步”需求。

 ### v1.1.0 更新内容
+
 - 重构为 MAUI + WebView 架构
 - 实现跨平台支持 (Windows, macOS, Android, iOS)
 - 使用 HTTP API 进行前后端通信
@@ -22,9 +27,10 @@
 - 实现子任务支持

 ### v1.2.0 规划内容 (即将推出)
+
 - **Linux 官方支持**：正式适配 Linux 平台。
- **搜索与过滤**：支持按标题搜索、按优先级和状态过滤。
- **本地提醒**：支持设置任务提醒时间并发送本地通知。
+- **关键词检索**：支持按任务标题关键词搜索。
 - **标签系统**：引入多标签支持，提升任务组织效率。
 - **暗色模式**：全平台适配暗色/深色主题。
- **数据导出导入**：支持 JSON 格式数据备份与迁移。
+- **数据导出导入（后续）**：支持 JSON 格式数据备份与迁移（延期到后续版本）。
+
@@ -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 对后台进程的限制可能导致提醒不准时。
+- **凭据与合规**：第三方服务鉴权方式差异大，且必须保证凭据安全存储与最小化权限。
+- **终端可信度与数据落盘**：若需支持“不信任终端不落盘”，需要明确“可信度判定与配置下发”的服务端策略，并保证客户端在无落盘场景下的可用性与体验。