diff --git a/.gitignore b/.gitignore index 74a0e74..12d6f65 100644 --- a/.gitignore +++ b/.gitignore @@ -366,11 +366,3 @@ FodyWeavers.xsd /Hua.Todo/Output /src/Hua.Todo.Maui/Output /src/Hua.Todo.Host/Hua.Todo.db -/src/Hua.Todo.Host/Hua.Todo.db-shm -/src/Hua.Todo.Host/Hua.Todo.db-wal -/.artifacts/buildcheck -/.trae -/.artifacts -/.android-sdk -/src/Hua.Todo.Avalonia/wwwroot -/src/Hua.Todo.Avalonia/wwwroot diff --git a/.trae/coordination/00-README.md b/.trae/coordination/00-README.md new file mode 100644 index 0000000..c12449c --- /dev/null +++ b/.trae/coordination/00-README.md @@ -0,0 +1,18 @@ +# 协调目录（并行 solo 专用） + +该目录用于解决两类问题： + +- 文件冲突：多窗口并行时明确"谁是 Writer"，其他人不直接改同一文件 +- 编译中途状态：确保阶段性交付保持可编译（绿线），必要时通过隔离策略推进 + +## 目录约定 + +- `01-ownership.md`：文件/目录所有权登记（Writer 表） +- `02-shared-files.md`：本阶段共享文件清单（由 Integrator 维护） +- `handoff/`：非 Writer 提交的差异建议/交接说明（Integrator 负责落盘） +- `wip/`：编译中途状态说明（为什么隔离、隔离方式、收敛条件） + +## 使用规则 + +- 所有权与共享文件清单优先使用"仓库相对路径" +- 禁止记录或提交构建产物目录中的文件路径（如 `bin/`、`obj/`、`node_modules/`、`dist/` 等） diff --git a/.trae/coordination/01-ownership.md b/.trae/coordination/01-ownership.md new file mode 100644 index 0000000..9236736 --- /dev/null +++ b/.trae/coordination/01-ownership.md @@ -0,0 +1,14 @@ +# 文件/目录所有权（Writer）登记 + +规则： + +- 同一时段内，同一个文件只能有一个 Writer +- 非 Writer 不编辑该文件；需要修改时，提交到 `.trae\coordination\handoff\` 由 Writer/Integrator 落盘 +- 路径建议使用仓库相对路径；每次扩大修改范围，先更新登记再改代码 + +## 当前所有权 + +> 状态：空（无进行中的并行任务）。新增并行任务时按下方表头格式追加记录行；任务验收后由 Integrator 清空。 + +| Path（仓库相对路径） | Writer | 任务/窗口标识 | 备注 | +|---|---|---|---| diff --git a/.trae/coordination/02-shared-files.md b/.trae/coordination/02-shared-files.md new file mode 100644 index 0000000..a62015b --- /dev/null +++ b/.trae/coordination/02-shared-files.md @@ -0,0 +1,11 @@ +# 本阶段共享文件清单（Integrator 维护） + +规则： + +- 本文件只由 Integrator 修改，避免反复冲突 +- 清单内每条必须是"仓库相对路径"，并说明为什么共享（入口/协议/配置/依赖锁等） +- 所有共享文件必须同时出现在各自任务的 Touch List 中，并标注 Writer 为 Integrator + +## 共享文件 + +> 状态：空（无进行中的并行任务）。Integrator 在新阶段开始时按"路径：为什么共享"格式追加；阶段结束后清空。 diff --git a/.trae/memory/01-project_memory.md b/.trae/memory/01-project_memory.md new file mode 100644 index 0000000..64ca5f0 --- /dev/null +++ b/.trae/memory/01-project_memory.md @@ -0,0 +1,28 @@ +# 项目记忆（长期沉淀） + +> 本文件保存**长期不变 / 不易频繁更新**的项目元信息。 +> 当前实现进度、工单状态、未完结事项等"短期快照"请见 [.trae/rules/项目/04-即时状态记忆.md](../rules/项目/04-即时状态记忆.md)。 +> 项目划分、依赖方向、运行模式见 [.trae/rules/项目/01-项目架构.md](../rules/项目/01-项目架构.md)。 + +## 关键依赖版本（含具体小版本号） + +- **运行时**：.NET 10.0（SDK 10.0.201） +- **C# 语言**：C# 13 +- **EF Core**：10.0（SQLite Provider） +- **API 文档**：Swashbuckle 10.1.7 +- **前端**：Vue 3 / TypeScript 5 / Vite 5；Axios + Pinia +- **桌面**：Avalonia（Linux/Windows/macOS） +- **跨平台原生**：MAUI（Android/iOS/Windows/macOS） + +## 重要历史决策（不在即时状态记忆中重复记录） + +- **.NET 10 适配**：针对 .NET 10 预览版特性（如 Windows TFM bug）进行规避与适配 +- **Android 稳定性**：移除自动初始化 Provider，解决 AndroidX 相关崩溃 +- **多平台构建开关**：通过 `Directory.Build.props` 优化非目标平台的构建依赖 +- **跨平台热键平台拆分**：Avalonia 与 MAUI 各自实现 `IGlobalHotKeyService`，平台目录分离 + +## 历史变更时间轴 + +- 2026-04-10：项目初始化与基础记忆建立 +- 2026-04-13：升级至 v1.2.8，同步 CloudSync 与 DynamicApi 文档 +- 2026-06：术语统一与目录中文化（详见 `04-即时状态记忆.md` § 五） diff --git a/.trae/rules/commenting.md b/.trae/rules/commenting.md new file mode 100644 index 0000000..9c3139c --- /dev/null +++ b/.trae/rules/commenting.md @@ -0,0 +1,33 @@ +--- +alwaysApply: true +description: 强制项目注释规范（C# / TypeScript）：新增或修改代码必须补全必要注释，便于维护与跨平台开发。 +--- + +# 注释规范（必须遵守） + +## 通用 + +- 新增或修改的代码必须包含足够注释，使“不了解该模块的人”也能理解其职责、边界与关键决策。 +- 优先使用 **XML 文档注释**（`///`），而不是随意的行内注释。 +- 不允许无意义注释（例如“初始化变量”“进入方法”）。注释必须解释“为什么/约束/边界/副作用”。 +- 不允许出现“TODO/FIXME”但无上下文或无处理方案的注释。 + +## C#（.NET / MAUI） + +- 所有 `public` / `protected` 的 **类、接口、方法、属性** 必须提供 XML 文档注释，至少包含： + - `summary`：一句话说明用途 + - 对关键参数/返回值：`param` / `returns` + - 对异常或副作用：在 `summary` 中明确说明（例如会注册系统钩子/会启动后台服务） +- 对 **跨平台逻辑**： + - 禁止在同一文件内混写多个平台的大段 `#if` 实现；应优先使用 `partial`、接口与平台目录分离。 + - 平台分离后的公共入口处必须说明“平台差异在哪里、默认实现是什么、为什么这么做”。 +- 对 **异步/后台任务**： + - 必须说明启动时机、错误处理策略、是否需要 UI 线程、以及是否可并发/可重入。 +- 对 **安全/隐私**： + - 禁止在日志或注释中输出密钥、Token、用户隐私信息。 + +## TypeScript / Vue（前端） + +- 对导出的函数/类型必须有注释，解释用途与输入输出。 +- 对“与后端/MAUI 交互”的协议字段（例如全局变量、事件名）必须注释说明来源与约束。 + diff --git a/.trae/rules/documentation_sync.md b/.trae/rules/documentation_sync.md new file mode 100644 index 0000000..9d7b666 --- /dev/null +++ b/.trae/rules/documentation_sync.md @@ -0,0 +1,34 @@ +--- +alwaysApply: true +description: 强制文档同步规范：每次变更代码（如新增功能、修改接口、调整架构等）必须同步更新 README.md 和 docs 目录下的相关文档。 +--- + +# 文档同步规范（必须遵守） + +## 通用原则 + +- **代码即文档，文档随代码**：文档不是静态的，它必须真实反映当前代码的状态。 +- **及时性**：在提交代码变更的同时（或紧随其后），必须完成相关文档的更新。 +- **准确性**：确保文档中的示例代码、接口说明、安装步骤与实际代码完全一致。 +- **协作友好（局部修改）**：当并行处理多个任务/需求时，更新文档应尽量只修改与本任务直接相关的段落/小节，避免对不相关内容做无意义的重排、改写或格式化；如必须调整非关联内容，应拆分为独立的变更说明清楚原因与影响范围。 + +## 更新范围 + +- **README.md**： + - 如果变更涉及核心功能点（Features）、安装步骤（Installation）、快速开始（Quick Start）或 API 端点（API Endpoints），必须同步更新。 + - 变更涉及技术栈调整或项目结构变化时需更新。 +- **docs/ 目录文档**： + - **接口变更**：若修改了 API，需同步更新 [技术设计文档](docs/技术设计文档.md) 中的接口部分。 + - **功能新增/调整**：需在 [产品需求文档](docs/产品需求文档.md) 和 [技术栈与模块](docs/技术栈与模块.md) 中体现。 + - **架构/模式变更**：需更新 [技术设计文档](docs/技术设计文档.md)。 + - **代码规范**：若引入了新的编码模式或工具，需更新 [代码规范文档](docs/代码规范文档.md)。 + - **版本记录**：所有非琐碎的变更必须在 [版本记录.md](docs/版本记录.md) 中添加记录。 + +## 检查清单 + +1. [ ] 是否有新增的 API 端点？（更新 README 和技术设计文档） +2. [ ] 是否修改了现有的业务逻辑或数据结构？（更新技术设计文档） +3. [ ] 是否有新增的功能模块？（更新产品需求文档和技术栈说明） +4. [ ] 是否调整了开发环境或依赖？（更新 README） +5. [ ] 是否在 [版本记录.md](docs/版本记录.md) 中记录了本次变更？ +6. [ ] 文档变更是否保持“局部修改”，只影响与本任务相关的段落/小节？（避免无关重排/改写） diff --git a/.trae/rules/全局/01-智能体记忆.md b/.trae/rules/全局/01-智能体记忆.md new file mode 100644 index 0000000..d2d2869 --- /dev/null +++ b/.trae/rules/全局/01-智能体记忆.md @@ -0,0 +1,53 @@ +# 智能体记忆与规范同步规则（必须遵守） + +> 适用范围：本规则属于 **全局规则**（语义层面跨项目可复用），关注智能体如何维护记忆与同步规范，与具体项目业务无关。 +> +> `.trae/` 整体目录结构与各子目录职责见 [.trae/索引.md](../../索引.md)，本文件不再重复描述。 + +## 记忆存储 + +- 智能体的记忆必须存放在 `.trae/memory` 文件夹中 +- 记忆应按对话日期或主题进行组织，便于后续查询和参考 +- 记忆内容应包含对话历史、关键决策、重要代码片段和规范调整等信息 +- **项目即时状态**（当前实现到哪一步、未完结事项、临时决策快照）应同步写入 `.trae/rules/项目/04-即时状态记忆.md`，便于其他智能体或开发者快速对齐 + +## 规范同步 + +- 每次对话中涉及到的语法或规范相关内容，必须同步整理到 `.trae/rules` 目录下的对应文件中 + - **通用规范**（注释、文档同步、工单流程、并行冲突）→ 写入 `.trae/rules/全局/` + - **项目专属**（业务命名、架构边界、数据模型、即时状态）→ 写入 `.trae/rules/项目/` +- 若涉及到新的规范或规则，应创建新的规则文件进行记录 +- 规范同步应及时、准确，确保规则文件能真实反映当前项目的编码规范和最佳实践 + +## 文件命名规则（强制） + +`.trae/` 下所有子目录中**新增的文件必须沿用 `NN-名称.md` 序号格式**，否则视为不合规： + +- **格式**：两位数字 + 连字符 + 中文/英文名称 + `.md`，例如 `08-XXX规范.md` +- **序号取值**：紧接当前目录已有最大序号 +1，不得跳号、不得重复 +- **入口/索引文件例外**：`.trae/索引.md` 这类目录入口文件不带序号 +- **重排禁止**：除非整体重构，否则不得重排已有文件的序号；新增只能追加在末尾 +- **同步更新索引**：每次新增文件后，必须在 [.trae/索引.md](../../索引.md) 的对应章节同步追加该文件的链接与一句话职责说明 +- **跨目录创建**：在 `coordination/`、`memory/` 下新增文件时同样适用本规则 + +### 各子目录当前最大序号速查 + +| 子目录 | 当前最大序号 | 下一个可用 | +|---|---|---| +| `rules/全局/` | 07 | 08 | +| `rules/项目/` | 04 | 05 | +| `memory/` | 01 | 02 | +| `coordination/` | 02 | 03 | + +## 实现要求 + +- 智能体应定期检查并更新规则文件，确保其与项目实际情况保持一致 +- 当发现规范冲突或需要调整时，应及时记录并通知相关人员 +- 记忆存储和规范同步应作为智能体的核心功能，贯穿于整个开发过程 + +## 路径规范 + +- 所有 Markdown 文档中不应使用绝对路径，应使用相对路径 +- 相对路径应以项目根目录为基准，例如 `.trae/memory` 而非绝对路径 +- 确保路径格式统一，使用正斜杠 (`/`) 作为路径分隔符，避免使用反斜杠 (`\`) +- 智能体在生成或修改文档时，应自动检查并替换绝对路径为相对路径 diff --git a/.trae/rules/全局/02-记忆存储规范.md b/.trae/rules/全局/02-记忆存储规范.md new file mode 100644 index 0000000..6480b6a --- /dev/null +++ b/.trae/rules/全局/02-记忆存储规范.md @@ -0,0 +1,33 @@ +# 记忆存储规范 + +> 适用范围：本规则属于 **全局规则**（跨项目通用），约束 `.trae/memory/` 的使用方式。 + +## 存储结构 +- 记忆文件应存放在 `.trae/memory` 文件夹中 +- 避免使用与日期相关的文件名，使用通用的描述性文件名 +- 文件命名采用 `NN-名称.md` 序号格式 +- 记忆内容应包含对话历史、关键决策、重要代码片段和规范调整等信息 + +## 内容规范 +- 记忆文件应保持简洁明了，重点记录重要的开发决策和规范变更 +- 避免存储冗余信息，只记录对项目有价值的内容 +- 定期清理过时的记忆文件，保持存储空间的合理使用 + +## 与"项目即时状态"的边界 +- `.trae/memory/` 偏向**长期保留**的对话产物与决策记录 +- `.trae/rules/项目/04-即时状态记忆.md` 偏向**当前快照**（实现进度、未完结事项），更新频率高 +- 二者不要重复存放同一份信息；以"是否需要长期沉淀"为判定标准 + +## memory/ 生命周期 + +研发工单验收完成后，对 `memory/` 的处理遵循以下原则： + +- **追加而非覆盖**：将本次工单中产生的、值得**长期沉淀**的内容（架构决策、关键避坑经验、引入的新依赖与版本）追加到对应文件 +- **不存放过程信息**：实现进度、待办勾选、临时决策这些短期信息应留在 [04-即时状态记忆.md](../项目/04-即时状态记忆.md)，不进 `memory/` +- **不删长期内容**：除非内容已被证伪或过时，否则不删除既有条目；过时内容用"已废弃 / 已被 XX 取代"的形式保留语义而非物理删除 +- **新增文件序号化**：当主题足够独立时新建 `NN-名称.md`（序号紧接当前最大值），并在 [.trae/索引.md](../../索引.md) 的 `memory/` 章节同步追加链接 + +## 访问权限 +- 记忆文件仅供开发团队内部参考使用 +- 确保记忆文件中的敏感信息得到适当保护 +- 遵循项目的版本控制和代码管理规范 diff --git a/.trae/rules/全局/03-注释规范.md b/.trae/rules/全局/03-注释规范.md new file mode 100644 index 0000000..883a67c --- /dev/null +++ b/.trae/rules/全局/03-注释规范.md @@ -0,0 +1,34 @@ +--- +alwaysApply: true +description: 强制项目注释规范（C# / TypeScript）：新增或修改代码必须补全必要注释，便于维护与跨平台开发。 +--- + +# 注释规范（必须遵守） + +> 适用范围：本规则属于 **全局规则**（跨项目通用），针对 C# / TypeScript / Vue 代码的注释要求。 + +## 通用 + +- 新增或修改的代码必须包含足够注释，使"不了解该模块的人"也能理解其职责、边界与关键决策。 +- 优先使用 **XML 文档注释**（`///`），而不是随意的行内注释。 +- 不允许无意义注释（例如"初始化变量""进入方法"）。注释必须解释"为什么/约束/边界/副作用"。 +- 不允许出现"TODO/FIXME"但无上下文或无处理方案的注释。 + +## C#（.NET / MAUI） + +- 所有 `public` / `protected` 的 **类、接口、方法、属性** 必须提供 XML 文档注释，至少包含： + - `summary`：一句话说明用途 + - 对关键参数/返回值：`param` / `returns` + - 对异常或副作用：在 `summary` 中明确说明（例如会注册系统钩子/会启动后台服务） +- 对 **跨平台逻辑**： + - 禁止在同一文件内混写多个平台的大段 `#if` 实现；应优先使用 `partial`、接口与平台目录分离。 + - 平台分离后的公共入口处必须说明"平台差异在哪里、默认实现是什么、为什么这么做"。 +- 对 **异步/后台任务**： + - 必须说明启动时机、错误处理策略、是否需要 UI 线程、以及是否可并发/可重入。 +- 对 **安全/隐私**： + - 禁止在日志或注释中输出密钥、Token、用户隐私信息。 + +## TypeScript / Vue（前端） + +- 对导出的函数/类型必须有注释，解释用途与输入输出。 +- 对"与后端/MAUI 交互"的协议字段（例如全局变量、事件名）必须注释说明来源与约束。 diff --git a/.trae/rules/全局/04-文档同步规范.md b/.trae/rules/全局/04-文档同步规范.md new file mode 100644 index 0000000..ddd34f7 --- /dev/null +++ b/.trae/rules/全局/04-文档同步规范.md @@ -0,0 +1,38 @@ +--- +alwaysApply: true +description: 强制文档同步规范：每次变更代码（如新增功能、修改接口、调整架构等）必须同步更新 README.md 和 docs 目录下的相关文档。 +--- + +# 文档同步规范（必须遵守） + +> 适用范围：本规则属于 **全局规则**（跨项目通用）。 + +## 通用原则 + +- **代码即文档，文档随代码**：文档不是静态的，它必须真实反映当前代码的状态。 +- **及时性**：在提交代码变更的同时（或紧随其后），必须完成相关文档的更新。 +- **准确性**：确保文档中的示例代码、接口说明、安装步骤与实际代码完全一致。 +- **协作友好（局部修改）**：当并行处理多个研发工单/需求时，更新文档应尽量只修改与本工单直接相关的段落/小节，避免对不相关内容做无意义的重排、改写或格式化；如必须调整非关联内容，应拆分为独立的变更说明清楚原因与影响范围。 + +> 术语澄清：本规范中"研发工单"指编码工作项；项目业务里的"任务/Todo 待办项"是用户域实体，二者不要混淆。详见 [05-研发工单规则.md](./05-研发工单规则.md)。 + +## 更新范围 + +- **README.md**： + - 如果变更涉及核心功能点（Features）、安装步骤（Installation）、快速开始（Quick Start）或 API 端点（API Endpoints），必须同步更新。 + - 变更涉及技术栈调整或项目结构变化时需更新。 +- **docs/ 目录文档**： + - **接口变更**：若修改了 API，需同步更新 [技术设计文档](docs/技术设计文档.md) 中的接口部分。 + - **功能新增/调整**：需在 [产品需求文档](docs/产品需求文档.md) 和 [技术栈与模块](docs/技术栈与模块.md) 中体现。 + - **架构/模式变更**：需更新 [技术设计文档](docs/技术设计文档.md)。 + - **代码规范**：若引入了新的编码模式或工具，需更新 [代码规范文档](docs/代码规范文档.md)。 + - **版本记录**：所有非琐碎的变更必须在 [版本记录.md](docs/版本记录.md) 中添加记录。 + +## 检查清单 + +1. [ ] 是否有新增的 API 端点？（更新 README 和技术设计文档） +2. [ ] 是否修改了现有的业务逻辑或数据结构？（更新技术设计文档） +3. [ ] 是否有新增的功能模块？（更新产品需求文档和技术栈说明） +4. [ ] 是否调整了开发环境或依赖？（更新 README） +5. [ ] 是否在 [版本记录.md](docs/版本记录.md) 中记录了本次变更？ +6. [ ] 文档变更是否保持"局部修改"，只影响与本工单相关的段落/小节？（避免无关重排/改写） diff --git a/.trae/rules/全局/05-研发工单规则.md b/.trae/rules/全局/05-研发工单规则.md new file mode 100644 index 0000000..418f659 --- /dev/null +++ b/.trae/rules/全局/05-研发工单规则.md @@ -0,0 +1,129 @@ +# 研发工单同步规则汇总（Dev Work Item Rules） + +> 适用范围：本规则属于 **全局规则**（跨项目通用），关注智能体如何拆分编码工作。 + +> ⚠️ 术语澄清（必读） +> +> 本项目存在两类"任务"概念，必须严格区分，避免命名混淆： +> +> | 术语 | 含义 | 适用范围 | +> |---|---|---| +> | **研发工单（Dev Work Item）** | 智能体 / 开发者执行的**编码工作项**（拆分需求、并行开发、集成等） | 本规则文档的全部内容 | +> | **Todo 待办项（Todo Item）** | Hua.Todo 项目**业务领域**中用户创建的待办事项（数据库实体、API 资源、UI 列表项） | 业务代码、产品需求文档、技术设计文档 | +> +> 本文档中所有"研发工单 / 工单 / 子工单"均指**编码工作项**，与业务侧的 Todo 待办项无关。 +> 在代码、文档与对话中，凡涉及编码侧拆分时，**必须使用"研发工单"或"工单"**，禁止再使用"任务"二字以避免与 Todo 待办项混淆。 +> +> 业务侧由于历史原因仍保留 `Task` / `SubTask` 等代码标识符（API、实体、UI），这些属于 Todo 待办项语义，**不在本规范替换范围内**。 +> +> 本汇总文件是 [06-研发工单拆分规范.md](./06-研发工单拆分规范.md) 与 [07-并行窗口冲突规约.md](./07-并行窗口冲突规约.md) 的对外索引，详细规则以这两份源文件为准。 + +--- + +## 一、研发工单拆分规范 + +### 适用时机 +- 当需求需要先通读项目/产品/技术文档再开始实现时，必须先输出**研发工单拆分文档** + +### 输出要求 +1. **先读完所有相关文档**：包括 `docs/`、`docs/project/` 下与本次需求相关的内容 +2. **先写工单拆分，再动手实现**：研发工单拆分产出是后续执行的入口与对齐依据 +3. **新增专属文件夹**：在 `docs/project` 下新建 `研发工单-<主题>-<日期或版本>` 文件夹 +4. **可并行工单拆分**：能同步执行的工单必须拆到不同 Markdown 文件中 +5. **文件带序号**：按执行顺序编号（`01-xxx.md`、`02-xxx.md`） + +### 每个研发工单文件必须包含 +- 目标 / 范围（做什么、不做什么） +- 前置条件（依赖哪些结论 / 接口 / 文档） +- 验收标准（可执行的验证点） +- 风险与回滚（如有） + +### 子工单完成标记要求 +- 子工单完成后，必须在 `00-工单总览.md` 中标注"已完成" +- 维护"待验证表"，记录每个子工单的"待验证 / 已验证"状态 + +--- + +## 二、并行窗口冲突规约 + +### 核心原则 +1. **先声明后修改**：修改前先声明 Touch List 与共享文件策略 +2. **文件所有权唯一**：同一时段内一个文件只能由一个窗口修改 +3. **共享文件单点修改**：高耦合 / 共享入口的改动集中到集成窗口完成 +4. **绿线优先**：任何可落盘的变更必须保持可编译 + +### Touch List 要求 +- 精确到文件路径 +- 标注修改类型（新增 / 小改 / 重构 / 接口变更 / 配置变更） +- 标注是否为共享文件 +- 使用相对路径：`src\\` + +### 共享文件判定标准（满足其一即为共享） +- 项目入口 / 启动逻辑、依赖注入注册、全局路由 +- 公共配置、公共协议与 DTO、公共组件 / 样式 +- 解决方案文件（`.sln`、`.csproj`）、锁文件、全局配置 + +### Writer 约束 +- 非 Writer 窗口不得编辑共享文件 +- 非 Writer 只能提供"差异建议"给 Writer 落盘 + +### 协调目录 +固定目录：`.trae\coordination\` +- `01-ownership.md`：文件所有权登记表 +- `02-shared-files.md`：共享文件清单（集成窗口维护） +- `handoff\`：差异建议 / 交接说明 +- `wip\`：编译中途状态说明 + +### 编译绿线规则 +- 不得提交破坏编译的变更 +- 临时隔离手段（按优先级）： + 1. 新功能先放在新文件中，不在入口路径启用 + 2. 通过显式开关控制，默认关闭 + 3. 通过依赖注入分支或特性开关隔离 +- 接口演进采用"双写 / 兼容期"策略 + +--- + +## 三、推荐文档结构 + +``` +docs/project/研发工单-<主题>-<版本>/ +├── 00-工单总览.md # 背景、目标、关键决策、并行分组、待验证表 +├── 01-并行工单A.md +├── 02-并行工单B.md +└── 03-串行工单C.md +``` + +> 注意：上述目录与文件名中的"工单"指**研发工单**，与业务侧 Todo 待办项无关。 + +--- + +## 四、检查清单 + +### 研发工单拆分检查 +1. [ ] 是否已阅读完所有相关文档？ +2. [ ] 是否在 `docs/project` 下新建了专属文件夹（命名以"研发工单-"开头）？ +3. [ ] 是否产出 `00-工单总览.md`？ +4. [ ] 是否将可并行工单拆分为不同 md 文件？ +5. [ ] 是否所有 md 文件都带有连续序号？ +6. [ ] 子工单完成后是否在总览中标注"已完成"并更新待验证表？ + +### 并行冲突检查 +1. [ ] 每个研发工单 md 是否已写 Touch List（精确到文件）？ +2. [ ] Touch List 中的共享文件是否指定了唯一 Writer？ +3. [ ] 是否避免了对共享文件的无意义格式化 / 重排？ +4. [ ] 当前改动是否保持可编译（绿线）？ +5. [ ] 若涉及接口演进，是否采用兼容期策略？ + +--- + +## 五、与业务侧 Todo 待办项的边界 + +- 代码、注释、提交信息中描述**编码工作**时：使用"研发工单 / 工单 / 子工单" +- 代码、注释、提交信息中描述**业务功能**时：使用"Todo 待办项 / Todo Item / 父子任务（业务实体）" +- 文档命名前缀： + - 编码侧：`研发工单-<主题>-<版本>/` + - 业务侧（如有）：遵循 `docs/` 既有命名习惯，禁止使用"研发工单"前缀 +- 提交信息示例： + - ✅ `feat(todo): 新增 Todo 待办项截止日期字段（研发工单 02-后端模型）` + - ❌ `feat: 完成任务 02`（"任务"歧义，禁用） diff --git a/.trae/rules/全局/06-研发工单拆分规范.md b/.trae/rules/全局/06-研发工单拆分规范.md new file mode 100644 index 0000000..cc0684d --- /dev/null +++ b/.trae/rules/全局/06-研发工单拆分规范.md @@ -0,0 +1,57 @@ +--- +alwaysApply: false +--- +# 研发工单拆分输出规范（必须遵守） + +> 适用范围：本规则属于 **全局规则**（跨项目通用）。 + +> ⚠️ 术语澄清：本规范中的「研发工单（Dev Work Item）」专指智能体 / 开发者执行的**编码工作项**，与 Hua.Todo 项目业务领域中的「Todo 待办项」是两个完全不同的概念。 +> 详见 [05-研发工单规则.md](./05-研发工单规则.md)。 +> 凡涉及编码侧拆分时，**必须使用「研发工单」或「工单」**，禁止使用「任务」二字以避免与 Todo 待办项混淆。 + +## 适用时机 + +- 当需求需要先通读项目/产品/技术文档再开始实现时，必须先输出研发工单拆分文档，再开始写代码或改配置。 + +## 输出要求 + +- **先读完所有相关文档**：包括但不限于 `docs/`、`docs/project/` 下与本次需求相关的内容。 +- **先写工单拆分，再动手实现**：研发工单拆分产出是后续执行的入口与对齐依据。 +- **新增一个专属文件夹**：在 `docs/project` 下新建一个文件夹存放本次研发工单拆分文档。 + - 文件夹命名建议：`研发工单-<主题>-<日期或版本>`（保持可检索、避免与既有文档冲突）。 +- **可并行的工单要拆成不同 md**：能同步执行（相互无依赖/弱依赖）的工单，必须拆到不同的 Markdown 文件中，便于并行推进与分工。 +- **文件必须带序号**：同一文件夹下的 md 文件按执行顺序编号，序号从小到大。 + - 文件名建议：`01-xxx.md`、`02-xxx.md`、`03-xxx.md`。 +- **每个研发工单文件至少包含**： + - 目标/范围（做什么、不做什么） + - 前置条件（依赖哪些结论/接口/文档） + - 验收标准（怎么判断完成，包含可执行的验证点） + - 风险与回滚（如有） +- **子工单完成后的标记要求**： + - 当任一子工单（例如 `01-*`/`02-*`/`03-*`）完成实现后，必须在对应版本的 `00-工单总览.md` 中同步标注"已完成"。 + - 同时必须维护一张"待验证表"（可用 Markdown 表格），对每个子工单给出"待验证/已验证"状态，避免实现完成但验收未闭环。 +- **并行冲突规避要求**：当工单会被分发到多个 solo 窗口并行推进时，每个研发工单文件必须额外包含： + - 触碰文件清单（Touch List，精确到文件） + - 共享文件策略（哪些是共享文件、唯一 Writer 是谁、如何与集成窗口对接） + - 编译绿线策略（如何确保阶段性交付不破坏编译） + +## 推荐结构（模板） + +- `00-工单总览.md` + - 背景与目标 + - 关键决策与约束 + - 并行分组说明（哪些文件可同步做） + - 待验证表（每个子工单的"待验证/已验证"状态） +- `01-<并行工单A>.md` +- `02-<并行工单B>.md` +- `03-<串行工单C>.md` + +## 最小检查清单 + +1. [ ] 是否确认已阅读完所有相关文档？ +2. [ ] 是否在 `docs/project` 下新建了本次专属文件夹（命名以"研发工单-"开头）？ +3. [ ] 是否产出 `00-工单总览.md`（或等价总览文件）？ +4. [ ] 是否将可并行工单拆分为不同 md 文件？ +5. [ ] 是否所有 md 文件都带有连续序号？ +6. [ ] 并行工单是否为每个研发工单文件补充了 Touch List/共享文件策略/编译绿线策略？ +7. [ ] 子工单完成后，是否在对应版本的 `00-工单总览.md` 标注"已完成"，并在"待验证表"里更新状态？ diff --git a/.trae/rules/全局/07-并行窗口冲突规约.md b/.trae/rules/全局/07-并行窗口冲突规约.md new file mode 100644 index 0000000..e64a8d0 --- /dev/null +++ b/.trae/rules/全局/07-并行窗口冲突规约.md @@ -0,0 +1,115 @@ +--- +alwaysApply: false +description: +--- +# 并行 solo 窗口冲突规约（必须遵守） + +> 适用范围：本规则属于 **全局规则**（跨项目通用）。 + +> ⚠️ 术语澄清：本规范中的「研发工单（Dev Work Item）」专指智能体 / 开发者执行的**编码工作项**，与 Hua.Todo 项目业务领域中的「Todo 待办项」是两个完全不同的概念。 +> 详见 [05-研发工单规则.md](./05-研发工单规则.md)。 +> 凡涉及编码侧拆分时，**必须使用「研发工单」或「工单」**，禁止使用「任务」二字以避免与 Todo 待办项混淆。 + +## 适用范围 + +- 当同一个版本/需求被拆分为多个并行研发工单，并由多个 solo 窗口同时推进时适用。 +- 目标是同时降低两类风险： + - **文件冲突**：多人同时改同一文件/相邻行导致冲突。 + - **编译区间冲突**：A 窗口引入的未完成变更破坏编译，阻塞 B 窗口集成与验证。 + +## 核心原则 + +- **先声明后修改**：任何代码改动前，先在研发工单文档中声明"触碰文件清单（Touch List）"与"共享文件策略"。 +- **文件所有权唯一**：同一时段内，一个文件只能被一个窗口作为"写入者（Writer）"修改。 +- **共享文件单点修改**：涉及高耦合/共享入口的改动，集中到一个"集成窗口（Integrator）"完成，其他窗口只做准备工作（新文件/独立模块/文档/测试）。 +- **绿线优先（可编译）**：任何可落盘、可合入的变更必须保持可编译；临时状态必须通过"隔离手段"而不是破坏编译来实现。 + +## Touch List（触碰文件清单） + +- 每个并行研发工单 md 必须在开头包含一个明确的 Touch List，至少包含： + - 新增/修改/删除的文件路径（精确到文件，必须写"准确目录"） + - 预期修改类型（新增/小改/重构/接口变更/配置变更） + - 是否为共享文件（是/否） +- Touch List 必须保持可检索与可更新：变更范围扩大时，必须先更新 Touch List 再改代码。 + +### 目录书写要求（必须遵守） + +- Touch List 内每一条必须使用以下两种格式之一： + - **仓库相对路径（推荐）**：`src\\` + - **绝对路径（可选）**：`\src\\`（`` 为本机仓库根目录） +- Touch List 禁止包含构建产物与临时目录中的文件（这些文件不应被手工修改，且极易产生冲突），包括但不限于： + - `**\bin\**`、`**\obj\**` + - `**\node_modules\**` + - `**\.vite\**`、`**\dist\**` + +### Touch List 模板（复制即可用） + +- Touch List: + - `src\\`（共享：否｜Writer：本窗口） + - `src\\`（共享：是｜Writer：<窗口名>） + - `docs\`（共享：是/否｜Writer：<窗口名>） + - `.trae\`（共享：是｜Writer：<窗口名>） + +## 文件所有权与共享文件策略 + +- **默认规则**：Touch List 中标记为"共享文件"的条目，必须指定唯一 Writer。 +- **Writer 约束**： + - 非 Writer 窗口不得编辑该共享文件（包括格式化、重排 import、无关重构）。 + - 需要对共享文件提出修改时，非 Writer 只能提供"差异建议"（文字说明/伪代码/小片段）交给 Writer 落盘。 +- **共享文件判定（满足其一即为共享）**： + - 项目入口/启动逻辑、依赖注入注册、全局路由/导航、公共配置、公共协议与 DTO、公共组件/样式、跨模块公共工具 + - 解决方案/项目文件（如 `.sln`、`.csproj`）、锁文件、全局配置文件（如 `appsettings*`、构建脚本） + +## 协调目录（必须遵守） + +- 为了让"文件冲突"和"编译中途状态"可操作、可对齐，仓库内必须固定保留一个专用协调目录： + - `.trae\coordination\` +- 该目录只用于协作对齐，不承载业务实现代码；多人可在不同文件中写入，避免互相踩踏。 +- 并行推进时必须使用该目录中的文件记录"谁在改什么"和"中途状态怎么保证不破坏编译"： + - `.trae\coordination\01-ownership.md`：文件/目录所有权（Writer）登记表 + - `.trae\coordination\02-shared-files.md`：本阶段共享文件清单（只有 Integrator 维护） + - `.trae\coordination\handoff\`：非 Writer 提交的差异建议/交接说明（Integrator 落盘） + - `.trae\coordination\wip\`：编译中途状态说明（为什么需要隔离、如何保证绿线、何时收敛） + +## 目录分区与低冲突写法 + +- 优先通过"新增文件"完成并行开发，减少在同一文件内的交错修改。 +- 需要扩展既有逻辑时，优先选择低冲突策略： + - C#：新增类/partial 文件、扩展方法、接口实现分文件、平台目录分离 + - TypeScript/Vue：新增模块/组件文件，避免在同一大文件内做多处改动 +- 禁止在非必要情况下对共享文件做纯格式化、纯重排或无收益重构（这些改动高度易冲突且难以 review）。 + +## 编译绿线（避免编译区间冲突） + +- **不得提交/合入破坏编译的变更**：包括缺失类型、未实现接口、引用不存在、配置缺项导致启动失败等。 +- **允许的临时隔离手段（按优先级）**： + 1. 新功能先放在新文件/新类中，不在入口路径上启用 + 2. 通过显式开关控制启用（配置/运行时开关），默认关闭 + 3. 通过依赖注入分支注册或特性开关隔离，默认不触发 +- 当必须进行接口演进时，采用"双写/兼容期"策略： + - 先新增（保持旧接口可用）→ 再迁移调用方 → 最后清理旧接口 + +## 合入顺序与集成职责 + +- 每个并行阶段必须明确一个集成窗口（Integrator），负责： + - 处理共享文件的实际落盘与冲突消解 + - 保持主干/集成分支持续可编译、可运行 +- 其他窗口提交的成果应尽量以"新增文件 + 最小修改点"的方式交付，降低集成成本。 + +## 任务验收后 coordination 清理 + +研发工单验收完成、并行阶段结束后，**Integrator 必须**对 `.trae/coordination/` 做收尾清理： + +- **清空记录行**：将 `01-ownership.md` 与 `02-shared-files.md` 中的运行时记录行删除，仅保留文件顶部说明、表头与示例占位行（让下一轮并行可以直接复用） +- **归档 handoff/wip**：删除已落盘消化掉的 `handoff/` 与 `wip/` 内容；如有需要长期沉淀的关键决策，迁移到 [.trae/memory/](../../memory) 对应文件中 +- **不删除文件本身**：`00-README.md`、`01-ownership.md`、`02-shared-files.md` 三个常驻文件保留，仅清空内容 +- **冲突收尾确认**：清理前确保所有共享文件已合入主干、Touch List 已不再被任何窗口引用 +- **同步项目状态**：在 [.trae/rules/项目/04-即时状态记忆.md](../项目/04-即时状态记忆.md) 的"工单状态快照"中将相关工单标记为已验证 + +## 最小检查清单 + +1. [ ] 每个研发工单 md 是否已写 Touch List（精确到文件）？ +2. [ ] Touch List 中的共享文件是否指定了唯一 Writer？ +3. [ ] 是否避免了对共享文件的无意义格式化/重排？ +4. [ ] 当前改动是否保持可编译（绿线）？ +5. [ ] 若涉及接口演进，是否采用兼容期策略而非一次性破坏式变更？ diff --git a/.trae/rules/项目/01-项目架构.md b/.trae/rules/项目/01-项目架构.md new file mode 100644 index 0000000..4f8b772 --- /dev/null +++ b/.trae/rules/项目/01-项目架构.md @@ -0,0 +1,75 @@ +# 项目架构（Hua.Todo 专属） + +> 适用范围：本规则属于 **项目规则**（仅 Hua.Todo 项目生效）。 +> +> 描述当前仓库的项目划分、依赖方向、运行模式与跨平台策略，供智能体在做改动时快速对齐架构边界。 +> 完整设计参见 [docs/manual/01-技术设计文档.md](../../../docs/manual/01-技术设计文档.md) 与 [docs/manual/03-技术栈与模块.md](../../../docs/manual/03-技术栈与模块.md)。 + +## 一、项目清单（src/） + +| 项目 | 类型 | 职责 | 平台 | +|---|---|---|---| +| [Hua.Todo.Core](file:///d:/Proj/6.Hua.Todo/src/Hua.Todo.Core) | 类库 | 领域实体、仓储接口（`TaskEntity`、`UserEntity`、`SecurityPolicyEntity`、`AuditLogEntity`、`ITaskRepository` 等） | netstandard / net | +| [Hua.Todo.Application](file:///d:/Proj/6.Hua.Todo/src/Hua.Todo.Application) | 类库（共享层） | EF Core `TodoDbContext`、`TaskService`/`TaskRepository`、动态 API（`DynamicApi/`）、云同步（`CloudSync/`）、迁移 | net | +| [Hua.Todo.Host](file:///d:/Proj/6.Hua.Todo/src/Hua.Todo.Host) | ASP.NET 服务端 | 独立服务端宿主，承载本地动态 API + 云同步端点 + Admin 管理后台静态资源 | Windows/Linux 等服务器 | +| [Hua.Todo.Maui](file:///d:/Proj/6.Hua.Todo/src/Hua.Todo.Maui) | MAUI 客户端 | Windows / macOS / iOS / Android 入口；内嵌 WebServer + WebView 承载 Vue 前端 | 多端 | +| [Hua.Todo.Avalonia](file:///d:/Proj/6.Hua.Todo/src/Hua.Todo.Avalonia) | Avalonia 客户端 | Linux / Windows 桌面入口；内嵌 WebServer + `WebView.Avalonia` 承载 Vue 前端 | 桌面（含 Linux） | +| [Hua.Todo.Web](file:///d:/Proj/6.Hua.Todo/src/Hua.Todo.Web) | Vite + Vue 3 前端 | 同一份前端构建产物，被多个宿主以静态资源形式承载 | 浏览器/WebView | + +## 二、依赖方向（必须保持单向） + +``` +Hua.Todo.Core + ↑ +Hua.Todo.Application + ↑ + ├── Hua.Todo.Host (服务端注册 AddCloudSyncServer + 动态 API) + ├── Hua.Todo.Maui (客户端，仅注册 AddApplicationServices) + └── Hua.Todo.Avalonia (客户端，仅注册 AddApplicationServices) + +Hua.Todo.Web (无 .NET 依赖；通过 HTTP/同源调用上述任一宿主) +``` + +- **禁止反向依赖**：Core 不得引用 Application；Application 不得引用任何宿主项目。 +- **客户端不暴露云同步端点**：MAUI / Avalonia 只调用 `AddApplicationServices()`，不调用 `AddCloudSyncServer()`，详见 [docs/project/研发工单-v1.2.0/08-cloud_sync_refactor_plan.md](../../../docs/project/研发工单-v1.2.0/08-cloud_sync_refactor_plan.md)。 + +## 三、两种运行模式 + +### 模式 A：嵌入式（MAUI / Avalonia + WebView） +- 启动内嵌 Kestrel WebServer（默认端口 5057），托管 Vue 前端的静态产物（`wwwroot/`）+ 本地 `/api/*` +- WebView 加载 `HostUrl`（生产）或 `ForEndUrl`（开发，例如 Vite dev server） +- 注入：`window.__API_BASE_URL__ = "${HostUrl}/api"`、`window.mauiInterop` +- 默认 SQLite 路径：`LocalApplicationData/Hua.Todo/Hua.Todo.db`（避免安装目录无写权限） +- 不暴露云同步端点；登录/同步走外部 Host + +### 模式 B：独立服务端（Hua.Todo.Host） +- 独立部署的 ASP.NET 应用，端口 `:5173`（Vite proxy 目标） +- 同时注册 `AddApplicationServices()` + `AddCloudSyncServer()`，对外提供： + - `/api/*`：本地任务 API（动态 API） + - `/auth/*`、`/tasks/*`、`/sync`、`/security/policy`、`/cloud-sync/probe`：云同步端点 + - `/admin/*`：管理后台前端静态资源 +- 数据库：`src/Hua.Todo.Host/Hua.Todo.db`（开发/测试用） + +## 四、跨平台原则 + +- **业务逻辑统一在 Application 层**，宿主项目只做 DI 装配与平台桥接 +- **平台差异通过接口 + 平台目录**实现（例：`IGlobalHotKeyService` 在 MAUI 与 Avalonia 各有自己的 `Platforms/` 子目录实现） +- **前端只有一份**：Vue 项目通过不同的 `.env.*` 文件区分模式（`.env.development` / `.env.maui` / `.env.production`） + +## 五、关键扩展点 + +| 扩展点 | 位置 | +|---|---| +| DI 注册总入口 | [Hua.Todo.Application/ServiceCollectionExtensions.cs](file:///d:/Proj/6.Hua.Todo/src/Hua.Todo.Application/ServiceCollectionExtensions.cs) | +| 云同步 DI | `Hua.Todo.Application/CloudSync/CloudSyncServiceCollectionExtensions.cs` | +| 云同步端点 | `Hua.Todo.Application/CloudSync/CloudSyncEndpointExtensions.cs` | +| 动态 API 中间件 | `Hua.Todo.Application/DynamicApi/DynamicApiMiddleware.cs` | +| 嵌入式 WebServer | `Hua.Todo.{Maui,Avalonia}/Services/EmbeddedWebServerService.cs` | +| 全局快捷键平台实现 | `Hua.Todo.{Maui,Avalonia}/Services/Platforms/*GlobalHotKeyService.cs` | + +## 六、版本统一策略 + +- 全局版本号通过根目录 `Directory.Build.props` 集中管理（当前 `1.2.3`） +- Inno Setup 安装包：`src/Hua.Todo.Maui/setup.iss`、`src/Hua.Todo.Avalonia/setup.iss` +- Linux：`publish-linux.ps1` 产出 `.tar.gz`；`pack/linux/` 含 Flatpak 基础结构 +- 详见 [docs/project/研发工单-v1.2.0/02.1-版本统一与打包方案.md](../../../docs/project/研发工单-v1.2.0/02.1-版本统一与打包方案.md) diff --git a/.trae/rules/项目/02-业务命名规范.md b/.trae/rules/项目/02-业务命名规范.md new file mode 100644 index 0000000..719ab1c --- /dev/null +++ b/.trae/rules/项目/02-业务命名规范.md @@ -0,0 +1,60 @@ +# 业务命名规范（Hua.Todo 专属） + +> 适用范围：本规则属于 **项目规则**（仅 Hua.Todo 项目生效）。 +> +> 本文档规定 **业务实体**（Todo 待办项相关）与 **编码工作项**（研发工单）在代码、文档、提交信息中的命名边界。 +> 全局术语规则参见 [.trae/rules/全局/05-研发工单规则.md](../全局/05-研发工单规则.md)。 + +## 一、术语对照（核心） + +| 概念 | 含义 | 代码标识符 | 文档用语 | +|---|---|---|---| +| **Todo 待办项 / 业务任务** | 用户在 Hua.Todo 中创建的待办事项 | `Task` / `SubTask` / `TaskEntity` / `TaskItem` / `TaskService` / `TaskRepository` | "Todo 待办项 / 任务 / 子任务（业务实体）" | +| **研发工单（Dev Work Item）** | 智能体/开发者执行的编码工作项 | 无（仅文档层概念） | "研发工单 / 工单 / 子工单" | + +## 二、代码命名约定（已固化，不要改名） + +> 以下标识符已落入 API 契约、数据库表、前端类型，**禁止以"统一术语"为由进行重命名**。 + +### 2.1 .NET / C# 侧 +- 实体：`TaskEntity`（位于 [Hua.Todo.Core/Entities/TaskEntity.cs](file:///d:/Proj/6.Hua.Todo/src/Hua.Todo.Core/Entities/TaskEntity.cs)） +- 字段：`ParentTaskId`（父子任务关系）、`Priority`、`UserId` +- 服务：`ITaskService` / `TaskService`、`ITaskRepository` / `TaskRepository` +- 云同步 DTO：`CloudTaskItem`（位于 `Hua.Todo.Application/CloudSync/Models/TaskSyncDtos.cs`） +- 用户固定 ID：`TodoUserIds.LocalUserId = "local"`（见 `Hua.Todo.Core/Entities/TodoUserIds.cs`） + +### 2.2 前端（Vue/TS）侧 +- 类型：`TaskItem` / `TaskNode`（位于 [Hua.Todo.Web/src/types/task.ts](file:///d:/Proj/6.Hua.Todo/src/Hua.Todo.Web/src/types/task.ts)） +- 组件：`TaskList.vue` / `TaskItem.vue` / `TaskEditDialog.vue` +- API 模块：`api/tasks.ts`、`api/cloudSync.ts` + +### 2.3 HTTP API 路由 +- 本地动态 API：`/api/task`、`/api/task/{parentTaskId}/subtasks`（由 `Hua.Todo.Application/DynamicApi` 自动暴露） +- 云端：`GET /tasks`、`POST /sync`、`POST /cloud-sync/probe` +- 见 [docs/manual/01-技术设计文档.md](../../../docs/manual/01-技术设计文档.md)、[docs/project/研发工单-v1.2.0/04-CloudSync-服务端基础能力.md](../../../docs/project/研发工单-v1.2.0/04-CloudSync-服务端基础能力.md) + +### 2.4 数据库表 +- `Tasks`、`Users`、`UserSessions`、`SecurityPolicies`、`AuditLogs` +- 迁移文件位于 `Hua.Todo.Application/Migrations/` + +## 三、新增代码命名指引 + +### 3.1 与 Todo 业务相关的新代码 +- 沿用 `Task` / `SubTask` 词根，与既有命名保持一致 +- 如：`TaskFilterService`、`SubTaskCounter`、`TaskExportDto` + +### 3.2 与研发工单/工程基础设施相关的新代码 +- 不要使用 `Task` 词根（避免与业务实体撞名） +- 如果是 .NET 异步方法，可使用 `Async` 后缀但不要把方法/类型主体命名为 `Task` + +### 3.3 文档与提交信息 +- 业务变更：`feat(todo): 新增 Todo 待办项截止日期字段` +- 工程变更：`chore(workitem): 拆分 v1.2.0 研发工单 02-后端模型` +- 严禁含糊措辞：`feat: 完成任务 02`（"任务"歧义） + +## 四、命名一致性检查清单 + +1. [ ] 新增类/接口是否复用了已有 `Task*` 命名习惯？ +2. [ ] HTTP 路由是否与既有 `/api/task` / `/tasks` 风格一致？ +3. [ ] 文档段落是否在首次出现"任务"时明确指向 Todo 待办项还是研发工单？ +4. [ ] 提交信息是否避免了歧义"任务"用法？ diff --git a/.trae/rules/项目/03-数据模型与迁移约束.md b/.trae/rules/项目/03-数据模型与迁移约束.md new file mode 100644 index 0000000..d53320e --- /dev/null +++ b/.trae/rules/项目/03-数据模型与迁移约束.md @@ -0,0 +1,99 @@ +# 数据模型与迁移约束（Hua.Todo 专属） + +> 适用范围：本规则属于 **项目规则**（仅 Hua.Todo 项目生效）。 +> +> 描述当前数据库实体、字段约束、EF Core 迁移历史，约束智能体在改 schema 时遵循的纪律。 + +## 一、技术栈 + +- ORM：**EF Core** +- 数据库：**SQLite**（嵌入式与 Host 开发都走 SQLite；生产 Host 可切其他后端） +- DbContext：[TodoDbContext](file:///d:/Proj/6.Hua.Todo/src/Hua.Todo.Application/Data/TodoDbContext.cs) +- 迁移目录：`Hua.Todo.Application/Migrations/` +- **表名规范**：遵循 ABP 模板规范，格式为 `T_{实体名}s`，如 `T_Tasks`、`T_Users` + +## 二、当前实体清单（src/Hua.Todo.Core/Entities/） + +### 2.1 TaskEntity（待重构为 ABP 基类） + +> ⚠️ **重大变更预警**：TaskEntity 计划继承 `FullAuditedEntityWithUser`，重构后将包含 ABP 全部审计字段。此改为破坏性变更，详见 [09-CloudSync-同步策略改进方案.md](../../../docs/project/研发工单-v1.2.0/09-CloudSync-同步策略改进方案.md)。 + +**重构前（当前）**： + +| 字段 | 类型 | 说明 | +|---|---|---| +| `Id` | `int` | 主键（待改为 Guid） | +| `UserId` | `Guid` | 任务所属用户 | +| `Title` | `string` | 标题 | +| `Priority` | `TaskPriority` | 优先级枚举 | +| `IsCompleted` | `bool` | 是否完成 | +| `CreatedAt` | `DateTime` | 创建时间 | +| `UpdatedAt` | `DateTime` | 更新时间 | +| `ParentTaskId` | `int?` | 父任务ID（待改为 Guid?） | + +**重构后（ABP 标准）**： + +继承 `FullAuditedEntityWithUser` 后自动获得： + +| ABP 审计字段 | 类型 | 说明 | +|---|---|---| +| `Id` | `Guid` | 主键（强制 Guid） | +| `ExtraProperties` | `ExtraPropertyDictionary` | 扩展属性（基类提供） | +| `ConcurrencyStamp` | `string?` | 并发戳 | +| `CreationTime` | `DateTime` | 创建时间 | +| `CreatorId` | `Guid?` | 创建人 | +| `LastModificationTime` | `DateTime?` | 最后修改时间 | +| `LastModifierId` | `Guid?` | 最后修改人 | +| `IsDeleted` | `bool` | 软删除标记 | +| `DeletionTime` | `DateTime?` | 删除时间 | +| `DeleterId` | `Guid?` | 删除人 | + +业务字段保留：`UserId`、`Title`、`Priority`、`IsCompleted`、`ParentTaskId` + +### 2.2 其他实体 + +| 实体 | 关键字段 | 约束 | +|---|---|---| +| `TaskPriority` | 枚举 | Priority 字段对应类型 | +| `UserEntity` | `Id`、`UserName`、`PasswordHash`、`PasswordSalt`、`Role`、`MustChangePassword` | 唯一索引：`UserName` | +| `UserSessionEntity` | `SessionId`、`UserId`、`ExpiresAtUtc`、`IsStepUp`、`StepUpExpiresAtUtc` | session token 由 DB 管理（非纯 JWT） | +| `SecurityPolicyEntity` | `UserId`、`AllowPersist`、`AllowSync`、`SecondFactorExpiryMinutes`、`IsTrustedDeviceOnly` | 与 User 一对一 | +| `AuditLogEntity` | `Id`、`UserId`、`Action`、`OccurredAtUtc`、`Details` | 关键安全事件 | +| `TodoUserIds` | `LocalUserId = "local"` | 静态常量类，非实体 | + +## 三、迁移历史（按时间） + +| 迁移 | 含义 | +|---|---| +| `20260313044926_InitialCreate` | 初始 Tasks 表 | +| `20260313092658_AddParentTaskId` | 父子任务字段 | +| `20260406172936_AddCloudSyncCoreEntities` | Users / UserSessions / SecurityPolicies | +| `20260406173734_AddAllowSyncToSecurityPolicy` | `AllowSync` 字段 | +| `20260413140347_UpdateSecurityEntities` | 安全实体调整 | +| `20260413140753_AddAuditLogs` | AuditLogs 表 | +| `20260424164713_AddPasswordSaltToUsers` | 密码加盐 | +| `20260510171230_AddMustChangePasswordToUsers` | 强制改密标志 | +| `MakeTaskEntityAbpCompatible`（待创建） | 重构为继承 ABP 基类，新增审计字段，主键从 `int` 改为 `Guid` | + +## 四、改 schema 必须遵守的纪律 + +1. **禁止手改 `*ModelSnapshot.cs`**：使用 `dotnet ef migrations add` 命令生成 +2. **迁移命名以动词开头**：`AddXxx` / `UpdateXxx` / `RemoveXxx` / `RenameXxx` +3. **避免破坏性迁移**：删除字段前先确认数据已被业务层迁移；优先采用"双写/兼容期" +4. **嵌入式宿主启动时自动 Migrate**：见 `EmbeddedWebServerService.cs` 中的 `db.Database.Migrate()` 调用；任何破坏迁移幂等性的改动都会让客户端启动失败 +5. **业务字段命名沿用 `Task*` 词根**（即业务实体），编码工作侧不要在实体上用 `Task` 词根之外的同义词 +6. **`UserId` 字段不可为空**：本地模式使用 `TodoUserIds.LocalUserId = "local"`，云端模式使用真实用户 GUID 字符串 + +## 五、DTO 与实体的映射边界 + +- **实体（Entity）**：仅在 `Hua.Todo.Core` / `Hua.Todo.Application/Data` 内部使用 +- **DTO（Models）**：跨进程边界（HTTP API、WebView 注入）使用，位于 `Hua.Todo.Application/CloudSync/Models/` 与 `Hua.Todo.Application/Models/` +- **不要把实体直接序列化为 API 响应**：避免暴露内部字段、避免循环引用 + +## 六、检查清单（schema 变更） + +1. [ ] 是否新增了 EF Core 迁移（而非手改快照）？ +2. [ ] 迁移名称是否以 `AddXxx`/`UpdateXxx`/`RemoveXxx` 开头？ +3. [ ] 是否在 [docs/manual/01-技术设计文档.md](../../../docs/manual/01-技术设计文档.md) 中同步更新数据模型描述？ +4. [ ] 是否在 [docs/manual/06-版本记录.md](../../../docs/manual/06-版本记录.md) 中追加非琐碎变更条目？ +5. [ ] 是否在嵌入式宿主上验证了启动时 Migrate 不报错？ diff --git a/.trae/rules/项目/04-即时状态记忆.md b/.trae/rules/项目/04-即时状态记忆.md new file mode 100644 index 0000000..ebb3990 --- /dev/null +++ b/.trae/rules/项目/04-即时状态记忆.md @@ -0,0 +1,62 @@ +# 即时状态记忆（Hua.Todo 专属） + +> 适用范围：本规则属于 **项目规则**（仅 Hua.Todo 项目生效）。 +> +> 本文档保存"当前实现到哪一步、未完结事项、临时决策"等**短期快照**，用于跨会话/跨智能体快速对齐。 +> 与 [.trae/memory/](../../memory) 的差别：memory 偏长期沉淀，此处偏即时状态，更新频率高。 +> +> **维护要求**：智能体每完成一个研发工单或观察到状态变化时，必须更新本文件的对应章节。 + +--- + +## 一、当前活跃版本 + +- **进行中版本**：v1.2.0 +- **研发工单总览**：[docs/project/研发工单-v1.2.0/00-工单总览.md](../../../docs/project/研发工单-v1.2.0/00-工单总览.md) +- **PRD**：[docs/project/产品需求文档-1.2.0.md](../../../docs/project/产品需求文档-1.2.0.md) + +## 二、v1.2.0 工单状态快照 + +| 子工单 | 实现状态 | 验证状态 | 简要说明 | +|---|---|---|---| +| 01 - Linux Avalonia 入口 + WebView | 已完成 | 待验证 | `WebView.Avalonia` + `WebView.Avalonia.Desktop`；Linux 依赖 GTK + WebKitGTK | +| 02 - Linux 打包/交付 | 已落地 | 待验证 | `publish-linux.ps1` 产 `.tar.gz`；Flatpak 基础结构在 `pack/linux/` | +| 02.1 - 版本统一打包 | 已落地 | 待验证 | `Directory.Build.props` 统一版本；Avalonia 新增 `setup.iss` | +| 03 - Search 关键词检索 | 已完成 | 待验证 | 主界面搜索框，按 Todo 标题包含匹配；Esc 清空；英文不分大小写 | +| 04 - 云同步 服务端基础能力 | 已完成 | 已验证 | API 契约固化；`Tasks` 表加 `UserId` 隔离；RBAC + step-up | +| 05 - 云同步 客户端配置/工作流 | 已完成 | 待验证 | 新增"云同步设置"弹窗：地址保存探测、登录/登出、登录后只读展示云端 Todo | +| 06 - 安全与可控落盘 | 未标注 | 待验证 | 框架就绪（`SecurityPolicy`），客户端落盘策略尚未充分覆盖 | +| 06.1 - 服务端安全设计 | 已设计 | 待实现 | Argon2id/JWT/审计日志/Admin 管理后台规划 | +| 07 - 文档同步与验收 | 进行中 | 进行中 | README/docs 已基本对齐；术语对照刚完成 | +| 08 - cloud_sync 重构 | 已设计 | 待实现 | "同源 Host"方案，Vite proxy 补 `/auth` `/tasks` `/sync` `/security` `/cloud-sync` | +| 09 - CloudSync 同步策略改进 | 已实现 | 待验证 | TaskEntity 继承 ABP 基类；软删除修复（SaveChangesAsync）；前端类型和 cloudSync.ts 已更新；新增 guid.ts | + +## 三、关键临时决策 + +- **MAUI 端不暴露云同步端点**：`MauiProgram.cs` 仅注册 `AddApplicationServices()`，不调 `AddCloudSyncServer()`。云同步端点只在 `Hua.Todo.Host` 暴露。 +- **本地用户 ID 固定为 `"local"`**：嵌入式模式下 `Tasks.UserId = TodoUserIds.LocalUserId`，与云端用户隔离逻辑共存而不冲突。 +- **SQLite WAL 模式**：嵌入式宿主启动时强制开启 WAL，降低锁冲突。 +- **数据库路径**：默认 `LocalApplicationData/Hua.Todo/Hua.Todo.db`（避免安装目录无写权限）；Host 模式使用 `src/Hua.Todo.Host/Hua.Todo.db`（开发/测试）。 + +## 四、已知未完结事项 / 待办 + +- [ ] 06 客户端"内存模式"在 `allowPersist=false` 时的端到端落盘清理（含 token、同步队列）尚未充分验证 +- [ ] 06.1 设计中的 Admin 管理后台前端（位于 `Hua.Todo.Host/wwwroot/admin/`）当前仅有 `index.html` 占位，需 Vue 3 + Vite 实现 +- [ ] 08 同源 Host 改造：`cloudClient.ts` 的 baseURL 解耦、Vite proxy 端点补全 +- [ ] Linux Flatpak/AppImage 自包含产物在干净环境的实测验证（v1.2.0 验收 Linux 部分仍为"待验证"） +- [x] CloudSync UNIQUE 约束修复（2026-06-14）：修复了 `existingTasks` 查询在事务外导致并发重同步时 `T_Tasks.Id` UNIQUE 约束冲突；新增 7 个测试（含 5 个 SQLite 集成测试） + +## 五、最近一次重大重构（如有） + +- **术语统一与目录中文化**（2026-06）： + - `.trae/rules/` 全部中文文件名 + 拆分为 `全局/` 和 `项目/` 两个子目录 + - `docs/project/v1.2.0-tasks/` → `docs/project/研发工单-v1.2.0/`，`00-任务总览.md` → `00-工单总览.md` + - 在 PRD 顶部加入"研发工单 vs Todo 待办项"术语对照表 + - 业务代码 `Task`/`SubTask` 标识符**保持不动**（已固化于 API、DB、UI） +- **`.trae` 子目录文件序号化**（2026-06）： + - `.trae/rules/全局/`、`.trae/rules/项目/`、`.trae/coordination/`、`.trae/memory/` 下所有文件加 `NN-` 序号前缀 + - `.trae/索引.md` 不带序号（入口文件） + +--- + +> **更新约定**：每次智能体修改本文件时，必须更新顶部的"进行中版本"和"工单状态快照"两节，确保信息不过时。 diff --git a/.trae/索引.md b/.trae/索引.md new file mode 100644 index 0000000..fa0790e --- /dev/null +++ b/.trae/索引.md @@ -0,0 +1,74 @@ +# .trae 目录索引 + +> 本文件是 `.trae/` 目录的总入口，描述各子目录与关键文件的职责，便于智能体与开发者快速定位。 +> +> 关于 TRAE 官方"全局规则 vs 项目规则"：TRAE IDE 的"全局规则"由设置中心保存到用户级、**不入仓**；本仓库 `.trae/rules/` 下的所有内容（含子目录）都会被 TRAE 识别为**项目规则**。下面的子目录 `全局/` 与 `项目/` 是项目内部的**语义分组**，不改变 TRAE 的加载语义。 +> +> 子目录嵌套深度受 TRAE 官方限制：`.trae/rules/` 下最多 3 层嵌套。 +> +> 文件命名约定：每个子目录内文件以 `NN-名称.md` 格式编号（两位数字），编号反映**阅读优先级 / 依赖顺序**。索引文件本身不带序号。 +> +> ⚠️ **新增文件必须遵守命名规则**：序号 = 当前目录最大值 + 1，不得跳号或重复，并需同步更新本索引文件中的对应章节。详见 [01-智能体记忆.md](./rules/全局/01-智能体记忆.md#文件命名规则强制)。 +> +> ⚠️ **任务完成后清理义务**：研发工单验收完成后，必须清理 `coordination/` 中的临时记录行（保留文件与表头），并按需追加 `memory/` 的长期记忆条目。详见 [07-并行窗口冲突规约.md](./rules/全局/07-并行窗口冲突规约.md#任务验收后-coordination-清理) 与 [02-记忆存储规范.md](./rules/全局/02-记忆存储规范.md#memory-生命周期)。 + +--- + +## 整体结构 + +``` +.trae/ +├── 索引.md ← 本文件（目录入口） +├── rules/ +│ ├── 全局/ ← 通用规范（跨项目可复用的方法论） +│ └── 项目/ ← Hua.Todo 专属（业务/架构/状态/数据） +├── memory/ ← 长期记忆数据（决策、对话产物） +└── coordination/ ← 多 solo 窗口协作目录（运行时登记表） +``` + +--- + +## rules/全局/ — 通用规范（与具体项目无关） + +| 文件 | 职责 | +|---|---| +| [01-智能体记忆.md](./rules/全局/01-智能体记忆.md) | 智能体记忆/规范同步机制（**不含目录总览，由本索引文件承担**） | +| [02-记忆存储规范.md](./rules/全局/02-记忆存储规范.md) | `.trae/memory/` 的使用方式 | +| [03-注释规范.md](./rules/全局/03-注释规范.md) | C# / TypeScript / Vue 代码注释要求 | +| [04-文档同步规范.md](./rules/全局/04-文档同步规范.md) | 代码变更同步 README/docs 的硬性要求 | +| [05-研发工单规则.md](./rules/全局/05-研发工单规则.md) | 研发工单术语与边界（编码工作项 vs Todo 待办项） | +| [06-研发工单拆分规范.md](./rules/全局/06-研发工单拆分规范.md) | 工单拆分目录与文件结构 | +| [07-并行窗口冲突规约.md](./rules/全局/07-并行窗口冲突规约.md) | 并行 solo 窗口下的 Touch List / Writer / 绿线策略 | + +--- + +## rules/项目/ — Hua.Todo 专属 + +| 文件 | 职责 | +|---|---| +| [01-项目架构.md](./rules/项目/01-项目架构.md) | src/ 五大项目划分、依赖方向、两种运行模式 | +| [02-业务命名规范.md](./rules/项目/02-业务命名规范.md) | `Task`/`SubTask`/`TaskEntity` 等代码标识符与"研发工单"边界 | +| [03-数据模型与迁移约束.md](./rules/项目/03-数据模型与迁移约束.md) | EF Core 实体清单、迁移历史、改 schema 纪律 | +| [04-即时状态记忆.md](./rules/项目/04-即时状态记忆.md) | 当前活跃版本 / 工单状态快照 / 临时决策 / 未完结事项 | + +--- + +## memory/ — 长期记忆 + +- 用途：长期沉淀的对话产物、关键开发决策、不再频繁更新的项目快照 +- 与"项目即时状态"的边界：[04-即时状态记忆.md](./rules/项目/04-即时状态记忆.md) 偏当前快照、更新频率高；`memory/` 偏长期保留 +- 维护规约：详见 [02-记忆存储规范.md](./rules/全局/02-记忆存储规范.md) +- 文件： + - [01-project_memory.md](./memory/01-project_memory.md)：依赖小版本号、历史决策、变更时间轴 + +--- + +## coordination/ — 多窗口协作运行时目录 + +- 用途：并行 solo 窗口下的"谁在改什么"登记表与共享文件清单（**运行时数据，非冷文档**） +- 协作协议详见 [07-并行窗口冲突规约.md](./rules/全局/07-并行窗口冲突规约.md) +- 文件： + - [00-README.md](./coordination/00-README.md)：目录约定 + - [01-ownership.md](./coordination/01-ownership.md)：文件/目录所有权（Writer）登记 + - [02-shared-files.md](./coordination/02-shared-files.md)：本阶段共享文件清单（Integrator 维护） + - `handoff/`、`wip/`：差异建议交接 / 编译中途状态（按需新建） diff --git a/Hua.Todo.slnx b/Hua.Todo.slnx index 5a72ee9..c1f8009 100644 --- a/Hua.Todo.slnx +++ b/Hua.Todo.slnx @@ -6,12 +6,13 @@ - - + + + - + diff --git a/README.md b/README.md index f35fa29..278081f 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,30 @@ -# Hua.Todo 跨平台代办管理应用 v1.2.8 +# Hua.Todo 跨平台代办管理应用 -一个基于 **WebView 容器（MAUI / Avalonia）+ 嵌入式 ASP.NET Core WebServer** 架构开发的跨平台代办管理应用，支持 **Windows、macOS、Android、iOS 和 Linux** 平台。通过 HTTP API 实现前后端通信，提供轻量、高效的任务管理体验。 +一个基于 MAUI + WebView 架构开发的跨平台代办管理应用，支持 Windows、macOS、Android、iOS 和 Linux（预览）平台。通过 HTTP API 实现前后端通信，提供轻量、高效的任务管理体验。 ## 🚀 功能特点 ### 核心功能 -- **跨平台支持**：基于 MAUI + Avalonia + WebView 架构，覆盖 Windows、macOS、Android、iOS 和 Linux 五大平台 -- **任务管理**：支持任务创建、编辑、删除、完成状态切换，以及子任务管理 -- **任务排序**：支持按创建时间、完成时间、优先级排序，可切换升序/降序 -- **云同步 (CloudSync)**：支持手动配置服务端地址并登录后拉取/推送云端任务，支持安全策略配置（内存模式、同步开关、二次认证、受信任设备限制） -- **用户管理与权限**：支持多用户管理、RBAC 细粒度权限控制（6 个权限点）、管理员密码加盐存储、首次登录强制修改密码 -- **审计日志**：记录所有安全事件（登录/注销/密码修改/引导等），支持管理员查询 -- **会话管理**：Bearer Token 认证，支持二次认证（step-up）提升权限，Token 即时失效 -- **关键词检索**：支持按任务标题实时过滤，支持 Esc 清空，大小写不敏感 -- **本地数据持久化**：使用 SQLite 数据库保存数据（WAL 模式优化），支持 DateTime 兼容性解析 -- **离线模式**：支持完全离线使用，数据优先保存于本地；安全策略禁止时可切换为内存模式不落盘 -- **动态 API**：后端自动生成 RESTful API 并集成 Swagger UI，便于联调与调试 -- **全局快捷键**：支持系统级快捷键快速唤起应用，修饰键与主键均可配置 -- **系统托盘**：支持最小化到系统托盘，关闭窗口隐藏到托盘，托盘菜单快捷操作 +- **跨平台支持**：基于 MAUI + WebView 架构，支持 Windows、macOS、Android、iOS 和 Linux（预览） +- **任务管理**：支持创建、编辑、删除、完成状态切换 +- **优先级管理**：支持高、中、低三种优先级设置，通过颜色直观区分 +- **任务状态跟踪**：清晰标记任务完成状态，支持过滤查看（全部/进行中/已完成） +- **本地数据持久化**：使用 SQLite 数据库保存数据，支持完全离线使用 +- **HTTP API 通信**：前后端通过 RESTful API 进行数据交互 ## 📦 安装与使用 ### 环境要求 -- **后端**：.NET 10 SDK + Visual Studio 2022 或更高版本 -- **前端**：Node.js 18+ + npm 或 yarn +- **后端**： + - .NET 10 SDK + - Visual Studio 2022 或更高版本 +- **前端**： + - Node.js 18+ + - npm 或 yarn ### 快速开始 -#### 1. 克隆项目 +#### 1. 克隆或下载项目 ```bash git clone <仓库地址> cd Hua.Todo @@ -39,8 +36,7 @@ cd src/Hua.Todo.Host dotnet restore dotnet run ``` -API 将在 `http://localhost:5173` 启动 -开发环境下提供 Swagger UI：`http://localhost:5173/swagger` +API 将在 `http://localhost:5173` 启动 #### 3. 启动前端 Web ```bash @@ -48,38 +44,10 @@ cd src/Hua.Todo.Web npm install npm run dev ``` -前端将在 `http://localhost:5174` 启动，并自动代理 `/api` 请求到后端 - -#### 4. 启动 MAUI 客户端（Windows 三件套开发） -推荐使用脚本一键启动： -```powershell -.\start-dev.ps1 -``` - -### 构建与发布 - -#### Windows 交付产物 -```powershell -# 生成 Windows 安装包（Inno Setup） -.\publish-windows.ps1 -``` -输出：`src/Hua.Todo.Maui/Output/Hua.Todo_Setup_vX.Y.Z.exe` - -#### Linux 交付产物 -```powershell -# 生成 Linux 发布包 -.\publish-linux.ps1 -``` -或使用统一发布脚本： -```powershell -# 默认发布 Windows + Linux -.\publish.ps1 -# 仅发布 Windows -.\publish.ps1 -Windows -``` +前端将在 `http://localhost:5174` 启动，并自动代理 `/api` 请求到 `http://localhost:5173` ### 使用说明 -- **添加任务**：在前端界面输入任务内容，设置优先级，点击添加按钮 +- **添加任务**：在前端界面中输入任务内容，设置优先级，点击添加按钮 - **管理任务**：查看任务列表，支持按状态过滤（全部/进行中/已完成） - **完成任务**：点击任务前的复选框切换完成状态 - **删除任务**：点击删除按钮移除任务 @@ -89,88 +57,33 @@ npm run dev ### 项目结构 ``` Hua.Todo/ -├── pack/ # 打包与交付产物（Linux/安装包等） ├── docs/ # 文档目录 │ ├── manual/ # 用户/开发者手册 │ └── project/ # 项目进度/需求文档 ├── src/ # 源代码目录 │ ├── Hua.Todo.Core/ # 领域实体与基础接口 │ ├── Hua.Todo.Application/ # 业务逻辑与应用层实现 -│ │ ├── CloudSync/ # 云同步模块 -│ │ ├── Data/ # 数据访问层 -│ │ └── DynamicApi/ # 动态 API 生成 │ ├── Hua.Todo.Host/ # 后端 API 宿主项目 (Kestrel) │ ├── Hua.Todo.Web/ # 前端 Web 项目 (Vue.js 3 + Vite) -│ ├── Hua.Todo.Maui/ # 跨平台客户端 (Windows/Android/iOS/macOS) -│ └── Hua.Todo.Avalonia/ # 桌面客户端 (Windows/macOS/Linux) +│ ├── Hua.Todo.Maui/ # 跨平台客户端项目 (Windows/Android/iOS/macOS) +│ └── Hua.Todo.slnx # 解决方案文件 ├── .gitignore # Git 忽略文件 └── README.md # 项目说明文档 ``` -### 技术栈 - -| 分类 | 技术 | -|------|------| -| 后端语言 | C# 13 (.NET 10) | -| UI 框架 | MAUI + Avalonia | -| 服务器 | Kestrel (ASP.NET Core) | -| 数据访问 | Entity Framework Core 10 | -| 数据库 | SQLite | -| 前端框架 | Vue.js 3 + TypeScript | -| 构建工具 | Vite 5+ | -| HTTP 客户端 | Axios | - ### API 端点 - -#### 任务管理 -| 方法 | 端点 | 说明 | -|------|------|------| -| GET | `/api/task` | 获取任务列表（默认：全部） | -| GET | `/api/task/active` | 获取未完成任务 | -| GET | `/api/task/completed` | 获取已完成任务 | -| GET | `/api/task/{id}` | 获取单个任务 | -| POST | `/api/task` | 创建任务 | -| PUT | `/api/task` | 更新任务（通过 Body 内的 id 定位） | -| PATCH | `/api/task/{id}/toggle` | 切换完成状态 | -| DELETE | `/api/task/{id}` | 删除任务 | -| GET | `/api/task/{parentTaskId}/subtasks` | 获取子任务列表 | - -#### 云同步（Host 模式） -| 方法 | 端点 | 说明 | -|------|------|------| -| POST | `/auth/bootstrap` | 初始化管理员（仅首次） | -| POST | `/auth/login` | 用户登录 | -| POST | `/auth/logout` | 用户注销 | -| POST | `/auth/step-up` | 二次验证（提升权限） | -| POST | `/auth/change-password` | 修改密码 | -| GET | `/tasks/` | 获取云端任务（只读） | -| POST | `/sync/` | 推送/拉取合并同步 | -| GET | `/security/policy` | 获取安全策略 | -| PUT | `/security/policy` | 更新安全策略 | -| POST | `/cloud-sync/probe` | 服务端可达性探测 | -| GET | `/admin/users` | 获取用户列表 | -| POST | `/admin/users` | 创建用户 | -| POST | `/admin/users/{userId}/reset-password` | 重置用户密码 | -| DELETE | `/admin/users/{userId}` | 删除用户 | -| GET | `/admin/sessions` | 获取活跃会话列表 | -| DELETE | `/admin/sessions/{sessionId}` | 强制终止会话 | -| GET | `/admin/audit-logs` | 获取审计日志 | -| GET | `/admin` | 管理后台入口 | - -## 📊 模块说明 - -- **Hua.Todo.Core**：领域实体层，定义核心实体、枚举及仓储接口 -- **Hua.Todo.Application**：应用层，包含业务逻辑、动态 API 生成、云同步服务 -- **Hua.Todo.Host**：后端 API 宿主，提供独立运行时环境 -- **Hua.Todo.Web**：前端 Web 项目，基于 Vue.js 3 + TypeScript + Vite -- **Hua.Todo.Maui**：跨平台客户端，支持 Windows、Android、iOS 和 macOS -- **Hua.Todo.Avalonia**：桌面客户端，专注 Linux 平台支持，同时兼容 Windows/macOS +- `GET /api/tasks` - 获取任务列表 +- `GET /api/tasks/{id}` - 获取单个任务 +- `POST /api/tasks` - 创建任务 +- `PUT /api/tasks/{id}` - 更新任务 +- `PATCH /api/tasks/{id}/complete` - 切换完成状态 +- `DELETE /api/tasks/{id}` - 删除任务 ## 🤝 交流与贡献 - **QQ 交流群**：2167048911 (Hua.Todo 交流群) - **项目地址**：[Hua.Todo](https://git.we965.cn/Tools/Hua.Todo) -- **贡献指南**：欢迎提交 Pull Request +- **贡献指南**：欢迎提交 Pull Request，详见 [其他信息](docs/manual/其他信息.md) ## 📄 开源协议 @@ -179,18 +92,16 @@ Hua.Todo/ ## 📚 更多文档 ### 用户与开发者手册 -- [技术栈与模块说明](docs/manual/03-技术栈与模块.md) -- [版本更新历史](docs/manual/06-版本记录.md) -- [技术设计文档](docs/manual/01-技术设计文档.md) -- [代码规范文档](docs/manual/04-代码规范文档.md) -- [部署文档](docs/manual/05-部署文档.md) -- [其他信息](docs/manual/07-其他信息.md) +- [技术栈与模块说明](docs/manual/技术栈与模块.md) +- [版本更新历史](docs/manual/版本记录.md) +- [技术设计文档](docs/manual/技术设计文档.md) +- [代码规范文档](docs/manual/代码规范文档.md) +- [其他信息 (贡献、许可证、联系方式)](docs/manual/其他信息.md) ### 项目进度与需求 - [产品需求文档](docs/project/产品需求文档.md) -- [v1.2.0 研发工单总览](docs/project/研发工单-v1.2.0/00-工单总览.md) +- [Android 离线排查计划](docs/project/Android_NotFound_排查计划.md) - [实现对比文档](docs/project/实现对比文档.md) --- - -**Hua.Todo** - 跨平台任务管理，让效率无处不在！ \ No newline at end of file +**Hua.Todo** - 跨平台任务管理，让效率无处不在！ diff --git a/docs/manual/代码规范文档.md b/docs/manual/代码规范文档.md new file mode 100644 index 0000000..0498a51 --- /dev/null +++ b/docs/manual/代码规范文档.md @@ -0,0 +1,675 @@ +# Hua.Todo 代码规范文档 v1.1.0 + +## 1. 概述 +本文档定义 Hua.Todo 项目的代码规范，包括 C#、JavaScript/TypeScript、Vue.js 和其他相关技术的编码标准。遵循这些规范有助于提高代码质量、可读性和可维护性。 + +## 2. 通用规范 + +### 2.1 命名约定 +- **使用有意义的名称**: 变量、函数、类名应清晰表达其用途 +- **避免缩写**: 除非是广泛认知的缩写（如 ID、URL、API） +- **一致性**: 在整个项目中保持命名风格一致 + +### 2.2 注释规范 +- **公共 API 必须添加 XML 文档注释** +- **复杂逻辑添加行内注释** +- **避免注释显而易见的代码** +- **保持注释与代码同步更新** + +### 2.3 代码格式化 +- **使用统一的代码格式化工具** +- **保持一致的缩进和空格** +- **每行代码不超过 120 字符** +- **文件末尾保留一个空行** + +## 3. C# 代码规范 + +### 3.1 命名规范 + +#### 类和接口 +```csharp +// 类名使用 PascalCase +public class TaskService +{ +} + +// 接口名使用 PascalCase，以 I 开头 +public interface ITaskService +{ +} +``` + +#### 方法和属性 +```csharp +// 方法名使用 PascalCase +public Task> GetTasksAsync() +{ +} + +// 属性名使用 PascalCase +public string Title { get; set; } +``` + +#### 变量和参数 +```csharp +// 私有字段使用 _camelCase +private readonly ITaskRepository _taskRepository; + +// 局部变量使用 camelCase +var taskList = await GetTasksAsync(); + +// 方法参数使用 camelCase +public void CreateTask(string title, TaskPriority priority) +{ +} +``` + +#### 常量 +```csharp +// 常量使用 PascalCase +public const int MaxTaskTitleLength = 200; +``` + +### 3.2 代码组织 + +#### 文件结构 +```csharp +// 1. using 语句（按字母顺序） +using System; +using System.Collections.Generic; +using System.Threading.Tasks; + +// 2. 命名空间 +namespace Hua.Todo.Api.Services; + +// 3. XML 文档注释 +/// +/// 任务服务实现 +/// +public class TaskService : ITaskService +{ + // 4. 私有字段 + private readonly ITaskRepository _taskRepository; + + // 5. 构造函数 + public TaskService(ITaskRepository taskRepository) + { + _taskRepository = taskRepository; + } + + // 6. 公共方法 + public async Task> GetTasksAsync() + { + // 实现 + } + + // 7. 私有方法 + private bool ValidateTask(Task task) + { + // 实现 + } +} +``` + +#### 命名空间组织 +- 每个文件只包含一个命名空间 +- 命名空间结构应与目录结构一致 +- 使用 `.` 分隔层级 + +### 3.3 编码规范 + +#### 异步编程 +```csharp +// 异步方法应以 Async 结尾 +public async Task GetTaskByIdAsync(int id) +{ + return await _taskRepository.GetByIdAsync(id); +} + +// 使用 await 而非 .Result 或 .Wait +var task = await GetTaskByIdAsync(id); + +// 使用 ConfigureAwait(false) 在库代码中 +public async Task> GetTasksAsync() +{ + return await _taskRepository.GetAllAsync().ConfigureAwait(false); +} +``` + +#### 依赖注入 +```csharp +// 优先使用构造函数注入 +public class TaskService : ITaskService +{ + private readonly ITaskRepository _taskRepository; + private readonly ILogger _logger; + + public TaskService(ITaskRepository taskRepository, ILogger logger) + { + _taskRepository = taskRepository; + _logger = logger; + } +} +``` + +#### 异常处理 +```csharp +// 使用具体的异常类型 +public async Task GetTaskByIdAsync(int id) +{ + var task = await _taskRepository.GetByIdAsync(id); + + if (task == null) + { + throw new NotFoundException($"Task with id {id} not found"); + } + + return task; +} + +// 使用 using 语句管理资源 +using var context = new TodoDbContext(); +``` + +#### LINQ 使用 +```csharp +// 优先使用方法语法 +var completedTasks = tasks.Where(t => t.IsCompleted).ToList(); + +// 复杂查询使用查询语法 +var query = from task in tasks + where task.IsCompleted + orderby task.CreatedAt descending + select task; +``` + +### 3.4 文档注释 +```csharp +/// +/// 获取指定 ID 的任务 +/// +/// 任务 ID +/// 任务对象 +/// 当任务不存在时抛出 +public async Task GetTaskByIdAsync(int id) +{ + // 实现 +} +``` + +## 4. JavaScript/TypeScript 代码规范 + +### 4.1 命名规范 + +#### 变量和函数 +```typescript +// 变量使用 camelCase +const taskList = []; +let currentTask = null; + +// 函数使用 camelCase +function getTasks() { + // 实现 +} + +// 常量使用 UPPER_SNAKE_CASE +const MAX_TASK_TITLE_LENGTH = 200; +``` + +#### 类和接口 +```typescript +// 类名使用 PascalCase +class TaskService { + // 实现 +} + +// 接口名使用 PascalCase +interface Task { + id: number; + title: string; +} + +// 类型别名使用 PascalCase +type TaskPriority = 'high' | 'medium' | 'low'; +``` + +### 4.2 代码组织 + +#### 文件结构 +```typescript +// 1. 导入语句 +import { ref, computed } from 'vue'; +import { useTaskStore } from '@/stores/tasks'; +import type { Task } from '@/types/task'; + +// 2. 类型定义 +interface TaskForm { + title: string; + priority: TaskPriority; +} + +// 3. 常量定义 +const DEFAULT_PRIORITY: TaskPriority = 'medium'; + +// 4. 组合式函数或组件 +export function useTasks() { + // 实现 +} +``` + +#### 模块导入 +```typescript +// 优先使用 ES6 模块语法 +import { ref } from 'vue'; +import axios from 'axios'; + +// 导出使用具名导出 +export function useTasks() { + // 实现 +} + +export default useTasks; +``` + +### 4.3 TypeScript 规范 + +#### 类型定义 +```typescript +// 为所有函数参数和返回值添加类型 +function getTaskById(id: number): Task | null { + // 实现 +} + +// 使用接口定义对象类型 +interface Task { + id: number; + title: string; + priority: TaskPriority; + isCompleted: boolean; + createdAt: Date; +} + +// 使用类型别名定义联合类型 +type TaskPriority = 'high' | 'medium' | 'low'; + +// 使用泛型提高代码复用性 +interface ApiResponse { + data: T; + message: string; +} +``` + +#### 类型断言 +```typescript +// 优先使用类型守卫而非类型断言 +function isTask(obj: unknown): obj is Task { + return typeof obj === 'object' && obj !== null && 'id' in obj; +} + +// 避免使用 as any +const task = response.data as Task; // 避免 +``` + +### 4.4 异步编程 +```typescript +// 使用 async/await 而非 Promise 链 +async function getTasks(): Promise { + const response = await axios.get('/api/tasks'); + return response.data; +} + +// 错误处理 +try { + const tasks = await getTasks(); +} catch (error) { + console.error('Failed to fetch tasks:', error); +} +``` + +## 5. Vue.js 代码规范 + +### 5.1 组件命名 +```vue + + + + +``` + +### 5.2 组件结构 +```vue + + + + + +``` + +### 5.3 组合式函数规范 +```typescript +// composables/useTasks.ts +import { ref, computed } from 'vue'; +import { useTaskStore } from '@/stores/tasks'; + +export function useTasks() { + const taskStore = useTaskStore(); + const loading = ref(false); + const error = ref(null); + + const tasks = computed(() => taskStore.tasks); + const completedTasks = computed(() => taskStore.completedTasks); + + const fetchTasks = async () => { + loading.value = true; + error.value = null; + + try { + await taskStore.fetchTasks(); + } catch (err) { + error.value = 'Failed to fetch tasks'; + console.error(err); + } finally { + loading.value = false; + } + }; + + return { + tasks, + completedTasks, + loading, + error, + fetchTasks + }; +} +``` + +### 5.4 状态管理规范 +```typescript +// stores/tasks.ts +import { defineStore } from 'pinia'; +import { ref, computed } from 'vue'; +import type { Task } from '@/types/task'; + +export const useTaskStore = defineStore('tasks', () => { + // State + const tasks = ref([]); + const loading = ref(false); + const error = ref(null); + + // Getters + const activeTasks = computed(() => + tasks.value.filter(task => !task.isCompleted) + ); + + const completedTasks = computed(() => + tasks.value.filter(task => task.isCompleted) + ); + + // Actions + async function fetchTasks() { + loading.value = true; + try { + const response = await fetch('/api/tasks'); + tasks.value = await response.json(); + } catch (err) { + error.value = 'Failed to fetch tasks'; + } finally { + loading.value = false; + } + } + + return { + tasks, + loading, + error, + activeTasks, + completedTasks, + fetchTasks + }; +}); +``` + +## 6. API 设计规范 + +### 6.1 RESTful API 设计 +```csharp +// 使用名词复数形式 +[HttpGet("tasks")] +public async Task>> GetTasks() +{ +} + +// 使用资源 ID +[HttpGet("tasks/{id}")] +public async Task> GetTask(int id) +{ +} + +// 使用 HTTP 方法表示操作 +[HttpPost("tasks")] +public async Task> CreateTask(CreateTaskDto dto) +{ +} + +[HttpPut("tasks/{id}")] +public async Task> UpdateTask(int id, UpdateTaskDto dto) +{ +} + +[HttpDelete("tasks/{id}")] +public async Task DeleteTask(int id) +{ +} +``` + +### 6.2 响应格式 +```csharp +// 统一的响应格式 +public class ApiResponse +{ + public bool Success { get; set; } + public T Data { get; set; } + public string Message { get; set; } + public List Errors { get; set; } +} + +// 成功响应 +return Ok(new ApiResponse +{ + Success = true, + Data = task, + Message = "Task created successfully" +}); + +// 错误响应 +return BadRequest(new ApiResponse +{ + Success = false, + Message = "Validation failed", + Errors = new List { "Title is required" } +}); +``` + +## 7. Git 提交规范 + +### 7.1 提交信息格式 +``` +(): + + + +