新实体创建流程规范

流程概述

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

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

适用场景选择

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

标准通用CRUD开发流程

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

开发步骤概要

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

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

自定义复杂CRUD开发流程

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

开发步骤概要

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

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

注意事项

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