# 业务命名规范（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. [ ] 提交信息是否避免了歧义"任务"用法？