diff --git a/.trae/rules/documentation_sync.md b/.trae/rules/documentation_sync.md index 807ec31..9d7b666 100644 --- a/.trae/rules/documentation_sync.md +++ b/.trae/rules/documentation_sync.md @@ -10,6 +10,7 @@ description: 强制文档同步规范:每次变更代码(如新增功能、 - **代码即文档,文档随代码**:文档不是静态的,它必须真实反映当前代码的状态。 - **及时性**:在提交代码变更的同时(或紧随其后),必须完成相关文档的更新。 - **准确性**:确保文档中的示例代码、接口说明、安装步骤与实际代码完全一致。 +- **协作友好(局部修改)**:当并行处理多个任务/需求时,更新文档应尽量只修改与本任务直接相关的段落/小节,避免对不相关内容做无意义的重排、改写或格式化;如必须调整非关联内容,应拆分为独立的变更说明清楚原因与影响范围。 ## 更新范围 @@ -30,3 +31,4 @@ description: 强制文档同步规范:每次变更代码(如新增功能、 3. [ ] 是否有新增的功能模块?(更新产品需求文档和技术栈说明) 4. [ ] 是否调整了开发环境或依赖?(更新 README) 5. [ ] 是否在 [版本记录.md](docs/版本记录.md) 中记录了本次变更? +6. [ ] 文档变更是否保持“局部修改”,只影响与本任务相关的段落/小节?(避免无关重排/改写) diff --git a/docs/manual/技术设计文档.md b/docs/manual/技术设计文档.md index 9e1a582..8359708 100644 --- a/docs/manual/技术设计文档.md +++ b/docs/manual/技术设计文档.md @@ -310,6 +310,7 @@ CREATE TABLE Settings ( - **Windows**: WebView2 运行时要求 - **macOS**: 代码签名和公证 - **移动端**: 应用商店发布配置 +- **Linux**: .NET MAUI 无官方 Linux 目标,需要引入独立桌面宿主(例如基于 WebKitGTK 的方案)并处理运行时依赖与打包格式 ## 9. 性能优化 diff --git a/docs/manual/版本记录.md b/docs/manual/版本记录.md index ffb0614..7f2b355 100644 --- a/docs/manual/版本记录.md +++ b/docs/manual/版本记录.md @@ -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 格式数据备份与迁移(延期到后续版本)。 + diff --git a/docs/project/产品需求文档-1.2.0.md b/docs/project/产品需求文档-1.2.0.md index 8958278..cedd8ec 100644 --- a/docs/project/产品需求文档-1.2.0.md +++ b/docs/project/产品需求文档-1.2.0.md @@ -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 对后台进程的限制可能导致提醒不准时。 +- **凭据与合规**:第三方服务鉴权方式差异大,且必须保证凭据安全存储与最小化权限。 +- **终端可信度与数据落盘**:若需支持“不信任终端不落盘”,需要明确“可信度判定与配置下发”的服务端策略,并保证客户端在无落盘场景下的可用性与体验。