# 新实体创建流程规范

## 完整开发流程

1. **创建实体**
   - 位置: `src/server/modules/[模块名]/[实体名].entity.ts`
   - 参考已有实体文件如`user.entity.ts`
   - 注意: 必须包含Zod Schema定义

2. **创建Service**
   - 位置: `src/server/modules/[模块名]/[实体名].service.ts`
   - 通过构造函数注入DataSource
   - 使用实体Schema进行输入输出验证

3. **创建API路由**
   - 目录结构:
     ```
     src/server/api/[实体名]/
     ├── get.ts       # 列表
     ├── post.ts      # 创建
     ├── [id]/
     │   ├── get.ts   # 详情
     │   ├── put.ts   # 更新
     │   └── delete.ts # 删除
     └── index.ts     # 路由聚合
     ```
   - 必须使用实体Schema作为请求/响应Schema
   - 参考`users`模块的实现

4. **注册路由**
   - 在`src/server/api.ts`中添加路由注册

5. **创建客户端API**
   - 在`src/client/api.ts`中添加客户端定义

6. **前端调用**
   - 在页面组件(如`pages_users.tsx`)中:
     - 使用`InferResponseType`提取响应类型
     - 使用`InferRequestType`提取请求类型
     - 示例:
       ```typescript
       type EntityResponse = InferResponseType<typeof entityClient.$get, 200>;
       type CreateRequest = InferRequestType<typeof entityClient.$post>['json'];
       ```

## 注意事项

1. 实体Schema必须在实体文件中定义，路由中直接引用，不要重复定义
2. 前端表格/表单字段必须与实体定义保持一致
3. 确保所有API调用都有正确的类型推断
4. 参考现有模块实现保持风格一致