refactor: 重构待办事项模块结构与命名
This commit is contained in:
ShaoHua
@@ -1,33 +0,0 @@
|
||||
---
|
||||
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 交互”的协议字段（例如全局变量、事件名）必须注释说明来源与约束。
|
||||
|
||||
@@ -1,34 +0,0 @@
|
||||
---
|
||||
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. [ ] 文档变更是否保持“局部修改”，只影响与本任务相关的段落/小节？（避免无关重排/改写）
|
||||
@@ -1,99 +0,0 @@
|
||||
---
|
||||
alwaysApply: false
|
||||
description:
|
||||
---
|
||||
# 并行 solo 窗口冲突规约（必须遵守）
|
||||
|
||||
## 适用范围
|
||||
|
||||
- 当同一个版本/需求被拆分为多个并行任务，并由多个 solo 窗口同时推进时适用。
|
||||
- 目标是同时降低两类风险：
|
||||
- **文件冲突**：多人同时改同一文件/相邻行导致冲突。
|
||||
- **编译区间冲突**：A 窗口引入的未完成变更破坏编译，阻塞 B 窗口集成与验证。
|
||||
|
||||
## 核心原则
|
||||
|
||||
- **先声明后修改**：任何代码改动前，先在任务文档中声明“触碰文件清单（Touch List）”与“共享文件策略”。
|
||||
- **文件所有权唯一**：同一时段内，一个文件只能被一个窗口作为“写入者（Writer）”修改。
|
||||
- **共享文件单点修改**：涉及高耦合/共享入口的改动，集中到一个“集成窗口（Integrator）”完成，其他窗口只做准备工作（新文件/独立模块/文档/测试）。
|
||||
- **绿线优先（可编译）**：任何可落盘、可合入的变更必须保持可编译；临时状态必须通过“隔离手段”而不是破坏编译来实现。
|
||||
|
||||
## Touch List（触碰文件清单）
|
||||
|
||||
- 每个并行任务 md 必须在开头包含一个明确的 Touch List，至少包含：
|
||||
- 新增/修改/删除的文件路径（精确到文件，必须写“准确目录”）
|
||||
- 预期修改类型（新增/小改/重构/接口变更/配置变更）
|
||||
- 是否为共享文件（是/否）
|
||||
- Touch List 必须保持可检索与可更新：变更范围扩大时，必须先更新 Touch List 再改代码。
|
||||
|
||||
### 目录书写要求（必须遵守）
|
||||
|
||||
- Touch List 内每一条必须使用以下两种格式之一：
|
||||
- **仓库相对路径（推荐）**：`src\<module>\<file>`
|
||||
- **绝对路径（可选）**：`<repo-root>\src\<module>\<file>`（`<repo-root>` 为本机仓库根目录）
|
||||
- Touch List 禁止包含构建产物与临时目录中的文件（这些文件不应被手工修改，且极易产生冲突），包括但不限于：
|
||||
- `**\bin\**`、`**\obj\**`
|
||||
- `**\node_modules\**`
|
||||
- `**\.vite\**`、`**\dist\**`
|
||||
|
||||
### Touch List 模板（复制即可用）
|
||||
|
||||
- Touch List:
|
||||
- `src\<module>\<file>`（共享：否｜Writer：本窗口）
|
||||
- `src\<module>\<file>`（共享：是｜Writer：<窗口名>）
|
||||
- `docs\<file>`（共享：是/否｜Writer：<窗口名>）
|
||||
- `.trae\<file>`（共享：是｜Writer：<窗口名>）
|
||||
|
||||
## 文件所有权与共享文件策略
|
||||
|
||||
- **默认规则**：Touch List 中标记为“共享文件”的条目，必须指定唯一 Writer。
|
||||
- **Writer 约束**：
|
||||
- 非 Writer 窗口不得编辑该共享文件（包括格式化、重排 import、无关重构）。
|
||||
- 需要对共享文件提出修改时，非 Writer 只能提供“差异建议”（文字说明/伪代码/小片段）交给 Writer 落盘。
|
||||
- **共享文件判定（满足其一即为共享）**：
|
||||
- 项目入口/启动逻辑、依赖注入注册、全局路由/导航、公共配置、公共协议与 DTO、公共组件/样式、跨模块公共工具
|
||||
- 解决方案/项目文件（如 `.sln`、`.csproj`）、锁文件、全局配置文件（如 `appsettings*`、构建脚本）
|
||||
|
||||
## 协调目录（必须遵守）
|
||||
|
||||
- 为了让“文件冲突”和“编译中途状态”可操作、可对齐，仓库内必须固定保留一个专用协调目录：
|
||||
- `.trae\coordination\`
|
||||
- 该目录只用于协作对齐，不承载业务实现代码；多人可在不同文件中写入，避免互相踩踏。
|
||||
- 并行推进时必须使用该目录中的文件记录“谁在改什么”和“中途状态怎么保证不破坏编译”：
|
||||
- `.trae\coordination\ownership.md`：文件/目录所有权（Writer）登记表
|
||||
- `.trae\coordination\shared-files.md`：本阶段共享文件清单（只有 Integrator 维护）
|
||||
- `.trae\coordination\handoff\`：非 Writer 提交的差异建议/交接说明（Integrator 落盘）
|
||||
- `.trae\coordination\wip\`：编译中途状态说明（为什么需要隔离、如何保证绿线、何时收敛）
|
||||
|
||||
## 目录分区与低冲突写法
|
||||
|
||||
- 优先通过“新增文件”完成并行开发，减少在同一文件内的交错修改。
|
||||
- 需要扩展既有逻辑时，优先选择低冲突策略：
|
||||
- C#：新增类/partial 文件、扩展方法、接口实现分文件、平台目录分离
|
||||
- TypeScript/Vue：新增模块/组件文件，避免在同一大文件内做多处改动
|
||||
- 禁止在非必要情况下对共享文件做纯格式化、纯重排或无收益重构（这些改动高度易冲突且难以 review）。
|
||||
|
||||
## 编译绿线（避免编译区间冲突）
|
||||
|
||||
- **不得提交/合入破坏编译的变更**：包括缺失类型、未实现接口、引用不存在、配置缺项导致启动失败等。
|
||||
- **允许的临时隔离手段（按优先级）**：
|
||||
1. 新功能先放在新文件/新类中，不在入口路径上启用
|
||||
2. 通过显式开关控制启用（配置/运行时开关），默认关闭
|
||||
3. 通过依赖注入分支注册或特性开关隔离，默认不触发
|
||||
- 当必须进行接口演进时，采用“双写/兼容期”策略：
|
||||
- 先新增（保持旧接口可用）→ 再迁移调用方 → 最后清理旧接口
|
||||
|
||||
## 合入顺序与集成职责
|
||||
|
||||
- 每个并行阶段必须明确一个集成窗口（Integrator），负责：
|
||||
- 处理共享文件的实际落盘与冲突消解
|
||||
- 保持主干/集成分支持续可编译、可运行
|
||||
- 其他窗口提交的成果应尽量以“新增文件 + 最小修改点”的方式交付，降低集成成本。
|
||||
|
||||
## 最小检查清单
|
||||
|
||||
1. [ ] 每个任务 md 是否已写 Touch List（精确到文件）？
|
||||
2. [ ] Touch List 中的共享文件是否指定了唯一 Writer？
|
||||
3. [ ] 是否避免了对共享文件的无意义格式化/重排？
|
||||
4. [ ] 当前改动是否保持可编译（绿线）？
|
||||
5. [ ] 若涉及接口演进，是否采用兼容期策略而非一次性破坏式变更？
|
||||
@@ -1,50 +0,0 @@
|
||||
---
|
||||
alwaysApply: false
|
||||
---
|
||||
# 任务拆分输出规范（必须遵守）
|
||||
|
||||
## 适用时机
|
||||
|
||||
- 当需求需要先通读项目/产品/技术文档再开始实现时，必须先输出任务拆分文档，再开始写代码或改配置。
|
||||
|
||||
## 输出要求
|
||||
|
||||
- **先读完所有相关文档**：包括但不限于 `docs/`、`docs/project/` 下与本次需求相关的内容。
|
||||
- **先写任务拆分，再动手实现**：任务拆分产出是后续执行的入口与对齐依据。
|
||||
- **新增一个专属文件夹**：在 `d:\Proj\6.Hua.Todo\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` 标注“已完成”，并在“待验证表”里更新状态？
|
||||
Reference in New Issue
Block a user