# 新实体创建流程规范

## 流程概述

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

- **标准通用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开发流程规范](./11-standard-crud.md)
## 自定义复杂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开发流程规范](./11-custom-crud.md)
## 注意事项

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