第08课：CLAUDE.md，让 Claude 永远记住你的规矩

第02课的 prompt：
"……查看项目中现有接口的验证方式和错误响应格式，保持一致……"

第04课的纠正：
"API 调用不要直接写在组件里，移到 src/services/ 里，参照 userService 的写法"

第05课的 prompt：
"……参照 src/modules/user/ 下现有代码的结构和风格……"

第06课的并行任务：
"……参照项目现有的校验方式……日志格式参照 src/utils/logger.ts……"

第07课的验证指令：
"……对比项目现有代码，确认风格一致……"

给订单模块加一个按日期范围查询的接口。

要求：
- 接口路径按 RESTful 规范设计
- 使用 NestJS 框架的 Controller + Service + Repository 分层
- 数据库用 TypeORM，查询用 QueryBuilder 不要用 raw SQL
- 分页用游标方式，不用 OFFSET
- 接口参数用 DTO 类做校验，用 class-validator 装饰器
- 错误返回用项目统一的 AppError 类，格式是 { code, msg, data }
- 日志用项目的 LoggerService，不要用 console.log
- 返回的时间字段统一用 ISO 8601 格式
- TypeScript 严格模式，不允许 any 类型
- 文件放在 src/modules/order/ 下
- 写完整的单元测试，测试框架用 Jest
- 测试命名用 should_xxx_when_xxx 格式

补充：参照 src/modules/user/ 下的代码风格。

给订单模块加一个按日期范围查询的接口。
支持按开始日期和结束日期筛选，返回分页结果。

你的项目根目录/
├── src/
├── package.json
├── tsconfig.json
├── CLAUDE.md          ← 放在这里
└── ...

你的项目根目录/
├── CLAUDE.md                    ← 项目级规范（全局生效）
├── src/
│   ├── modules/
│   │   ├── order/
│   │   │   └── CLAUDE.md        ← 订单模块专用规范
│   │   └── payment/
│   │       └── CLAUDE.md        ← 支付模块专用规范

# 项目概览

这是一个电商后台管理系统的后端服务。

技术栈：
- 运行环境：Node.js 20 + TypeScript 5.x
- 框架：NestJS 10
- 数据库：MySQL 8.0 + TypeORM
- 缓存：Redis 7
- 测试：Jest + Supertest
- API 文档：Swagger (nestjs/swagger)

项目结构：
- src/modules/     → 业务模块（每个模块包含 controller/service/repository/dto/entity）
- src/common/      → 公共组件（guards/filters/interceptors/decorators）
- src/utils/       → 工具函数
- src/config/      → 配置文件

# 代码规范

## 命名规则
- 文件名：kebab-case（如 order-item.service.ts）
- 类名：PascalCase（如 OrderItemService）
- 函数/变量：camelCase（如 getOrderList）
- 常量：UPPER_SNAKE_CASE（如 MAX_RETRY_COUNT）
- 数据库表/字段：snake_case（如 order_item, created_at）

## TypeScript 规则
- 严格模式（strict: true），不允许使用 any 类型
- 优先使用 interface 而非 type（除非需要联合类型或工具类型）
- 函数返回类型必须显式标注
- 使用 readonly 修饰不可变属性

## 代码组织
- 每个业务模块独立目录，包含完整的 controller/service/repository/dto/entity
- 公共逻辑放 src/common/，工具函数放 src/utils/
- 不要在 controller 里写业务逻辑，controller 只负责参数校验和调用 service
- 不要在 service 里直接写 SQL，通过 repository 操作数据库

## import 顺序
1. Node.js 内置模块
2. 第三方库
3. 项目内部模块（@/common, @/utils）
4. 当前模块内文件

每组之间空一行。

# 错误处理

## 错误类
使用项目统一的 AppError 类（src/common/errors/app-error.ts）：
\`\`\`typescript
throw new AppError(ErrorCode.ORDER_NOT_FOUND, '订单不存在');
\`\`\`
不要直接 throw new Error()。

## 错误响应格式
所有接口的错误响应统一为：
\`\`\`json
{
  "code": 40401,
  "msg": "订单不存在",
  "data": null
}
\`\`\`

## 错误码规范
- 4xxxx：客户端错误（参数错误、权限不足等）
- 5xxxx：服务端错误（内部异常、第三方服务失败等）
- 前两位是 HTTP 状态码，后三位是业务码

## 日志规范
使用 LoggerService（src/utils/logger.service.ts），不要用 console.log。

\`\`\`typescript
this.logger.info('创建订单', { userId, orderData });
this.logger.error('支付失败', { orderId, error: err.message });
\`\`\`

日志中禁止出现：密码、token、完整手机号、完整身份证号。
手机号脱敏格式：138****1234。