ShaoHua
cf96c56bed
本次提交完成了多项清理与规范工作： 1. 移除默认管理员硬编码配置与云同步相关代码 2. 简化前端与MAUI端的配置，关闭静态资源托管以外的冗余功能 3. 清理.gitignore与协调目录，移除临时文件与冗余规则 4. 统一项目命名规范，修正包名与版本号 5. 重构后端数据模型，移除ABP审计字段与云同步相关逻辑 6. 简化WebView配置与系统栏样式，移除不必要的平台检测代码 7. 更新文档与规则文件，完善项目规范与版本记录
130 lines
5.7 KiB
Markdown
130 lines
5.7 KiB
Markdown
# 研发工单同步规则汇总（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\<module>\<file>`
|
||
|
||
### 共享文件判定标准（满足其一即为共享）
|
||
- 项目入口 / 启动逻辑、依赖注入注册、全局路由
|
||
- 公共配置、公共协议与 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`（"任务"歧义，禁用）
|