# 项目级命名词典与边界模板

这份文档不是固定规则入口。固定不变的第五章规则已经放进 always-on 的 `coding-style.md`。

这里专门承载项目特有、会随业务变化的内容：

- 业务词典
- 历史别名兼容
- 某些目录的命名例外
- 类型后缀禁用表和替代方案
- 当前项目的文件命名分层表

## 1. 适用原则

- 先读规则文件 `coding-style.md`，这里不重复抄固定规则。
- 这里的每一项都应当是“当前项目特有事实”，不是通用工程常识。
- 如果某项约束对所有项目都成立，应上收回规则文件，而不是继续堆在本文。

## 2. 业务词典

先维护“一个概念一个名字”的项目词典。

| 业务概念 | 统一名称 | 禁止混用的别名 | 说明 |
| --- | --- | --- | --- |
| 用户 | `user` | `member`、`customer`、`client` | 如果确实是不同角色，拆成独立概念 |
| 商品 | `product` | `goods`、`item`、`commodity` | 只保留业务正式名词 |
| 订单 | `order` | `bill`、`trade` | 支付单可单独定义 `paymentOrder` |
| 优惠券 | `coupon` | `voucher`、`ticket` | 如果有券模板，再单独定义 `couponTemplate` |

补齐项目自己的业务词典时，至少回答：

- 这个概念在页面、接口、数据库、测试里是否同名。
- 是否已经存在历史别名；如果有，兼容层放在哪里。
- 新增同义词时，是新概念还是旧概念的脏别名。

## 3. 项目文件命名分层表

先按目录层级声明规则，再允许新增文件。

| 路径 / 资产类型 | 命名规则 | 示例 | 禁止情况 |
| --- | --- | --- | --- |
| React / Vue 页面组件 | `PascalCase` | `UserProfilePage.tsx` | 与同层 `user-profile-page.tsx` 混用 |
| 通用 hooks | `camelCase` 且以 `use` 开头 | `useUserProfile.ts` | `userHook.ts`、`getUserHook.ts` |
| 纯工具函数 | `camelCase` | `formatPrice.ts` | `dealData.ts`、`tool.ts` |
| 测试文件 | 跟随被测对象 + `.test` / `.spec` | `formatPrice.test.ts` | `test1.ts` |
| 文档模板 | `kebab-case` | `code-style-and-naming.md` | `codeStyle.md`、`code_style.md` |

新增文件前必须回答：

- 这个文件属于页面、feature、shared、contract、testing 还是 scripts。
- 同目录现有文件使用什么规则。
- 如果要破例，为什么不能沿用当前目录规则。

## 4. 项目特有命名例外

这里只记录项目例外，不重复写通用函数命名原则。

- 哪些历史目录仍在使用旧命名风格：
- 哪些生成代码目录允许例外：
- 哪些第三方契约文件不按项目规则命名：
- 哪些 legacy 字段名必须保留原样：

## 5. 类型命名边界

同一个项目里，`Entity`、`DTO`、`Response`、`FormValues`、`ViewModel` 这些后缀必须先定义边界。

| 类型后缀 | 用途 | 不该承载什么 |
| --- | --- | --- |
| `Entity` | 持久化模型 / 数据库实体 | 前端展示字段 |
| `Dto` / `DTO` | 服务边界输入输出 | ORM 细节、UI 状态 |
| `Response` | API 返回结构 | 表单临时状态 |
| `Request` | API 请求参数 | 数据库存储字段 |
| `FormValues` | 表单输入态 | 服务端完整实体 |
| `ViewModel` | 页面展示聚合模型 | 持久化约束 |

如果项目不使用这些后缀中的某些项，要在这里明确写：

- 禁止使用哪些后缀。
- 统一替代方案是什么。
- 历史遗留命名如何兼容。

## 6. 新增命名前必须确认

实现前先确认这 5 件事：

1. 这个名词是否已在业务词典中定义。
2. 同类文件在当前目录如何命名。
3. 这个函数名是否表达了主动作和对象。
4. 这个类型属于哪一层边界，是否需要后缀。
5. 是否会和历史别名、旧接口字段或数据库字段冲突。

## 7. 自动化与人工门禁

建议自动化命令：

```text
lint
typecheck
format
test
git diff --check
```

Harness 侧至少保留两层约束：

- `coding-style.md` 默认自动加载固定规则。
- `CURRENT_TASK.md` 和本文记录当前项目 / 当前任务的特有词典与边界。
- `style-lint.ps1` 同时检查规则文件和项目级模板是否完整。

## 8. 评审检查单

- 同一业务概念是否出现多个别名。
- 同层文件是否混用了多套命名风格。
- 新函数名是否仍然依赖 `do/process/check` 这类模糊词。
- `User`、`UserInfo`、`UserData`、`UserModel` 之类类型是否有明确边界。
- 新增字段、接口、测试数据、文档是否与统一名词同步。
