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

新实体创建流程规范

流程概述

实体创建流程分为两种模式，根据业务复杂度选择合适的实现方式：

• 标准通用CRUD：适用于简单数据模型，使用GenericCrudService和createCrudRoutes快速生成基础CRUD接口
• 自定义复杂CRUD：适用于包含复杂业务逻辑的实体，需要手动实现服务方法和路由处理

适用场景选择

类型	适用场景	技术选型
标准通用CRUD	简单数据管理、无复杂业务逻辑、基础CRUD操作	GenericCrudService + createCrudRoutes
自定义复杂CRUD	复杂业务规则、多表关联操作、特殊权限控制、非标准数据处理	自定义Service + 手动路由实现

标准通用CRUD开发流程

适用于简单数据模型，无复杂业务逻辑，仅需基础CRUD操作的场景。采用GenericCrudService和createCrudRoutes快速生成接口。

开发步骤概要

1. 创建实体：在src/server/modules/[模块名]/[实体名].entity.ts定义实体类和在src/server/modules/[模块名]/[实体名].schema.ts定义实体Zod Schema
2. 注册实体：在src/server/data-source.ts中注册新实体
3. 创建Service：继承GenericCrudService实现基础CRUD操作
4. 创建API路由：使用createCrudRoutes快速生成CRUD路由
5. 注册路由：在src/server/api.ts中注册路由
6. 创建客户端API：在src/client/api.ts中定义客户端调用方法
7. 前端调用：在页面组件中使用类型化API调用
8. 注册路由和菜单：
   • 管理后台：在src/client/admin/routes.tsx中添加路由配置，在src/client/admin/menu.tsx中添加菜单配置
   • 前台：在src/client/home/routes.tsx中添加路由配置

详细流程请参见标准通用CRUD开发流程规范

自定义复杂CRUD开发流程

适用于包含复杂业务逻辑的实体，需要手动实现服务方法和路由处理的场景，如复杂业务规则、多表关联操作、特殊权限控制等。

开发步骤概要

1. 创建实体：在src/server/modules/[模块名]/[实体名].entity.ts定义实体类和在src/server/modules/[模块名]/[实体名].schema.ts定义实体Zod Schema
2. 注册实体：在src/server/data-source.ts中注册新实体
3. 创建自定义Service：实现包含复杂业务逻辑的数据访问方法
4. 创建自定义API路由：手动实现CRUD路由及处理逻辑
5. 注册路由：在src/server/api.ts中注册路由
6. 创建客户端API：在src/client/api.ts中定义客户端调用方法
7. 前端调用：在页面组件中使用类型化API调用
8. 注册路由和菜单：
   • 管理后台：在src/client/admin/routes.tsx中添加路由配置，在src/client/admin/menu.tsx中添加菜单配置
   • 前台：在src/client/home/routes.tsx中添加路由配置

详细流程请参见自定义复杂CRUD开发流程规范

注意事项

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