ShaoHua
65cee20006
- 新增 00-目录与导读.md 双入口导航 - 用户面(01-04)：项目介绍、安装指南、版本记录、其他信息 - 开发者面(05-10)：技术栈、构建、架构、云同步、代码规范、MCP - 拆分旧01为 01(用户)+05(开发者)；旧02为 02(用户)+06(开发者) - 合并旧08+09 MCP文档为 10-MCP服务集成 - 同步更新 README.md 与 .trae/rules/项目/ 交叉引用
3.5 KiB
3.5 KiB
业务命名规范（Hua.Todo 专属）
适用范围：本规则属于 项目规则（仅 Hua.Todo 项目生效）。
本文档规定 业务实体（Todo 待办项相关）与 编码工作项（研发工单）在代码、文档、提交信息中的命名边界。 全局术语规则参见 .trae/rules/全局/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） - 字段：
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） - 组件：
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/05-技术栈与项目结构.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（"任务"歧义）
四、命名一致性检查清单
- 新增类/接口是否复用了已有
Task*命名习惯？ - HTTP 路由是否与既有
/api/task//tasks风格一致？ - 文档段落是否在首次出现"任务"时明确指向 Todo 待办项还是研发工单？
- 提交信息是否避免了歧义"任务"用法？