file-starter/.roo/rules/11-entity-creation.md

新实体创建流程规范

完整开发流程

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提取请求类型

     • 示例:

       type EntityResponse = InferResponseType<typeof entityClient.$get, 200>;
       type CreateRequest = InferRequestType<typeof entityClient.$post>['json'];
       

注意事项

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