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/.trae/rules/task_breakdown.md b/.trae/rules/task_breakdown.md new file mode 100644 index 0000000..f5540a6 --- /dev/null +++ b/.trae/rules/task_breakdown.md @@ -0,0 +1,43 @@ +--- +alwaysApply: false +description: 强制任务拆分输出规范:阅读完所有文档后,先产出拆分后的任务 Markdown,并按可并行执行拆分为多个带序号的 md 文件,统一放入 docs/project 下的新建文件夹。 +--- + +# 任务拆分输出规范(必须遵守) + +## 适用时机 + +- 当需求需要先通读项目/产品/技术文档再开始实现时,必须先输出任务拆分文档,再开始写代码或改配置。 + +## 输出要求 + +- **先读完所有相关文档**:包括但不限于 `docs/`、`docs/project/` 下与本次需求相关的内容。 +- **先写任务拆分,再动手实现**:任务拆分产出是后续执行的入口与对齐依据。 +- **新增一个专属文件夹**:在 `d:\Proj\6.Hua.Todo\docs\project` 下新建一个文件夹存放本次任务拆分文档。 + - 文件夹命名建议:`任务拆分-<主题>-<日期或版本>`(保持可检索、避免与既有文档冲突)。 +- **可并行的任务要拆成不同 md**:能同步执行(相互无依赖/弱依赖)的任务,必须拆到不同的 Markdown 文件中,便于并行推进与分工。 +- **文件必须带序号**:同一文件夹下的 md 文件按执行顺序编号,序号从小到大。 + - 文件名建议:`01-xxx.md`、`02-xxx.md`、`03-xxx.md`。 +- **每个任务文件至少包含**: + - 目标/范围(做什么、不做什么) + - 前置条件(依赖哪些结论/接口/文档) + - 验收标准(怎么判断完成,包含可执行的验证点) + - 风险与回滚(如有) + +## 推荐结构(模板) + +- `00-总览.md` + - 背景与目标 + - 关键决策与约束 + - 并行分组说明(哪些文件可同步做) +- `01-<并行任务A>.md` +- `02-<并行任务B>.md` +- `03-<串行任务C>.md` + +## 最小检查清单 + +1. [ ] 是否确认已阅读完所有相关文档? +2. [ ] 是否在 `docs/project` 下新建了本次专属文件夹? +3. [ ] 是否产出 `00-总览.md`(或等价总览文件)? +4. [ ] 是否将可并行任务拆分为不同 md 文件? +5. [ ] 是否所有 md 文件都带有连续序号? 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/v1.2.0-tasks/00-任务总览.md b/docs/project/v1.2.0-tasks/00-任务总览.md new file mode 100644 index 0000000..2cce752 --- /dev/null +++ b/docs/project/v1.2.0-tasks/00-任务总览.md @@ -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:可在主界面按标题实时过滤任务(含层级任务的展示策略清晰) +- 云同步(基础可用):可配置服务端地址;登录后可拉取该用户任务;服务端可下发“是否允许落盘”;客户端在禁止落盘时不产生本地持久化 + diff --git a/docs/project/v1.2.0-tasks/01-Linux-Avalonia入口与WebView.md b/docs/project/v1.2.0-tasks/01-Linux-Avalonia入口与WebView.md new file mode 100644 index 0000000..15da2ca --- /dev/null +++ b/docs/project/v1.2.0-tasks/01-Linux-Avalonia入口与WebView.md @@ -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 生效) +- 开发态可调试(至少能看到控制台/网络错误,或能通过日志定位) + diff --git a/docs/project/v1.2.0-tasks/02-Linux-打包与交付.md b/docs/project/v1.2.0-tasks/02-Linux-打包与交付.md new file mode 100644 index 0000000..45d7de8 --- /dev/null +++ b/docs/project/v1.2.0-tasks/02-Linux-打包与交付.md @@ -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 可用 +- 文档中给出的安装/运行步骤可复现,且与产物一致 + diff --git a/docs/project/v1.2.0-tasks/03-Search-关键词检索.md b/docs/project/v1.2.0-tasks/03-Search-关键词检索.md new file mode 100644 index 0000000..4f8d4a0 --- /dev/null +++ b/docs/project/v1.2.0-tasks/03-Search-关键词检索.md @@ -0,0 +1,45 @@ +# 03 - Search:任务标题关键词检索 + +## 目标 + +- 在主界面顶部增加搜索框 +- 支持按任务标题进行模糊匹配(实时过滤) + +## 范围 + +- 前端 UI:输入框、清空按钮、键盘交互(Esc 清空、Enter 可选) +- 过滤逻辑:对“树状任务”给出明确策略 +- 性能:任务量增大时仍保持可用(至少避免 O(n^2) 的明显退化) + +## 依赖 + +- 不依赖 Linux/Avalonia 或云同步,可独立并行完成 + +## 过滤策略(需在实现时确定,并写入实现说明) + +树状任务(父子任务)常见两种策略,任选其一并保持一致: + +1. **命中即显示(含上下文)** + - 任意节点标题命中则显示该节点 + - 若子任务命中,可同时显示其祖先链(便于理解层级) +2. **扁平化命中** + - 只显示命中的任务(可能丢失层级语义) + +建议优先采用“命中即显示(含上下文)”,用户可更快定位。 + +## 实施步骤(建议) + +1. 确定搜索框放置位置(主界面顶部) +2. 增加 `searchQuery` 状态与派生 `filteredTasks` +3. 将过滤逻辑接入现有列表渲染 +4. 补充交互细节 + - 输入时实时过滤 + - 清空按钮 + - Esc 清空、保持输入焦点(可选) + +## 验收标准 + +- 输入关键字后,任务列表实时过滤,仅展示命中结果(符合上述策略) +- 清空后恢复原列表 +- 对中英文与大小写的处理行为明确(至少:英文大小写不敏感;中文按包含匹配) + diff --git a/docs/project/v1.2.0-tasks/04-CloudSync-服务端基础能力.md b/docs/project/v1.2.0-tasks/04-CloudSync-服务端基础能力.md new file mode 100644 index 0000000..c442cd6 --- /dev/null +++ b/docs/project/v1.2.0-tasks/04-CloudSync-服务端基础能力.md @@ -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`),并可通过配置切换行为 + diff --git a/docs/project/v1.2.0-tasks/05-CloudSync-客户端配置与工作流.md b/docs/project/v1.2.0-tasks/05-CloudSync-客户端配置与工作流.md new file mode 100644 index 0000000..d55d52b --- /dev/null +++ b/docs/project/v1.2.0-tasks/05-CloudSync-客户端配置与工作流.md @@ -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. 登录后拉取任务 + - 拉取成功后更新前端任务列表 + - 拉取失败给出可理解提示,并允许重试 + +## 验收标准 + +- 首次启用同步必须先配置服务端地址;地址非法时不可保存并提示原因 +- 保存地址时能提示“不可达/证书异常”等风险信息(至少能区分:成功、失败、存在风险但可继续) +- 登录后能从服务端拉取任务并展示在主界面 + diff --git a/docs/project/v1.2.0-tasks/06-CloudSync-安全与可控落盘.md b/docs/project/v1.2.0-tasks/06-CloudSync-安全与可控落盘.md new file mode 100644 index 0000000..f57ab71 --- /dev/null +++ b/docs/project/v1.2.0-tasks/06-CloudSync-安全与可控落盘.md @@ -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` 时: + - 客户端不会把任务数据与凭据写入任何持久化介质 + - 退出应用后重新进入,任务数据为空(需重新登录/拉取) +- 对指定高风险操作: + - 无二次认证证明时被拒绝,并提示需要二次认证 + - 提供正确二次认证后操作成功 + diff --git a/docs/project/v1.2.0-tasks/07-文档同步与验收清单.md b/docs/project/v1.2.0-tasks/07-文档同步与验收清单.md new file mode 100644 index 0000000..63375bd --- /dev/null +++ b/docs/project/v1.2.0-tasks/07-文档同步与验收清单.md @@ -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` 时客户端不落盘,退出后数据不保留 +- [ ] 高风险操作触发二次认证(服务端支持时) + 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 对后台进程的限制可能导致提醒不准时。 +- **凭据与合规**:第三方服务鉴权方式差异大,且必须保证凭据安全存储与最小化权限。 +- **终端可信度与数据落盘**:若需支持“不信任终端不落盘”,需要明确“可信度判定与配置下发”的服务端策略,并保证客户端在无落盘场景下的可用性与体验。