ShaoHua
9223ceca50
- 规则重组：全局/ 下 8 个规则合并为 6 个（01+02→01，05+06→04），序号顺延 - 新增项目规则 05-多入口功能同步规范（UI/语音入口覆盖检查） - 新增 MCP 服务基础设施：Mcp/ 目录（DI 注册、端点扩展、动态工具描述符）、单元测试 - v1.3.0 工单文档：03 系列（会议任务拆分）、04（富文本描述与附件管理） - MCP 接口与前端集成指南：docs/manual/08、09
61 lines
3.5 KiB
Markdown
61 lines
3.5 KiB
Markdown
# 业务命名规范（Hua.Todo 专属）
|
||
|
||
> 适用范围：本规则属于 **项目规则**（仅 Hua.Todo 项目生效）。
|
||
>
|
||
> 本文档规定 **业务实体**（Todo 待办项相关）与 **编码工作项**（研发工单）在代码、文档、提交信息中的命名边界。
|
||
> 全局术语规则参见 [.trae/rules/全局/04-研发工单全流程规范.md](../全局/04-研发工单全流程规范.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. [ ] 提交信息是否避免了歧义"任务"用法？
|