---
alwaysApply: true
---

# 🤖 AI友好的Elysia开发规则体系

## 快速开始 🚀

### 1. 对于开发者

**首次使用：**
1. 阅读 `ai-friendly-elysia-rules.md` 了解规范
2. 查看 `ai-development-workflow.md` 学习如何与AI协作
3. 在项目中导入支持文件

**日常开发：**
```typescript
// 使用标准错误码
import { ERROR_CODES } from '@/constants/error-codes';

// 使用响应工具
import { successResponse, errorResponse, BusinessError } from '@/utils/response.helper';
```

### 2. 对于AI助手

**工作原则：**
- 严格遵循 `ai-friendly-elysia-rules.md` 规范
- 按照 `ai-development-workflow.md` 工作流程
- 确保代码质量和一致性

**开发顺序：**
1. Schema定义（最高优先级）
2. Response格式
3. Service层实现
4. Controller层实现
5. 测试用例

## 核心优势 💪

### 1. 一致性
- 统一的文件结构
- 标准的命名规范
- 一致的错误处理

### 2. 类型安全
- TypeBox Schema + TypeScript类型
- 编译时类型检查
- 运行时参数验证

### 3. 可维护性
- 清晰的模块划分
- 完整的文档注释
- 系统化的测试

### 4. AI友好
- 语义清晰的代码结构
- 明确的依赖关系
- 标准化的模式

## 使用示例 📝

### 创建新模块

当你需要创建新的业务模块时，告诉AI助手：

```
功能：用户管理
模块：user
接口：注册、登录、获取个人信息、修改个人信息
认证：登录后的接口需要JWT认证
特殊要求：密码需要加密存储
```

AI助手会自动创建：
- `src/modules/user/user.schema.ts`
- `src/modules/user/user.response.ts`
- `src/modules/user/user.service.ts`
- `src/modules/user/user.controller.ts`
- `src/modules/user/user.test.ts`

### 修改现有功能

```
修改用户查询接口，添加分页功能，每页最多50条记录
```

AI助手会：
1. 分析现有代码
2. 更新Schema定义
3. 修改Service逻辑
4. 更新Controller
5. 补充测试用例

## 代码质量保证 ✅

### 自动检查项
- [ ] TypeScript类型正确性
- [ ] Schema验证完整性
- [ ] 错误处理覆盖
- [ ] 响应格式一致性
- [ ] 命名规范符合标准
- [ ] 文档注释完整

### 人工Review项
- [ ] 业务逻辑正确性
- [ ] 安全性考虑
- [ ] 性能优化
- [ ] 用户体验

## 最佳实践 🌟

### 1. 需求描述
```
✅ 清晰：实现用户注册接口，包含邮箱验证和密码强度检查
❌ 模糊：做一个用户功能
```

### 2. 错误处理
```typescript
// ✅ 使用标准错误类
throw new BusinessError('用户名已存在', ERROR_CODES.USER_ALREADY_EXISTS);

// ❌ 直接抛出Error
throw new Error('用户名已存在');
```

### 3. 响应格式
```typescript
// ✅ 使用工具函数
return successResponse(userData, '查询成功');

// ❌ 手动构造
return { code: 'SUCCESS', message: '查询成功', data: userData };
```

## 性能考虑 ⚡

### 数据库优化
- 使用索引优化查询
- 避免N+1查询问题
- 合理使用连接池

### 缓存策略
- 热点数据Redis缓存
- 适当的缓存过期时间
- 缓存穿透防护

### 并发处理
- 避免阻塞操作
- 合理的超时设置
- 资源清理

## 故障排除 🔧

### 常见问题

1. **类型错误**
   - 检查Schema定义
   - 确认类型导出
   - 验证导入路径

2. **运行时错误**
   - 查看错误日志
   - 检查参数验证
   - 确认业务逻辑

3. **性能问题**
   - 分析慢查询
   - 检查缓存命中率
   - 监控资源使用

### 调试技巧

```typescript
// 添加调试日志
Logger.debug(`处理用户请求: ${JSON.stringify(params)}`);

// 性能监控
const startTime = Date.now();
// ... 业务逻辑
Logger.info(`操作耗时: ${Date.now() - startTime}ms`);
```

## 版本历史 📚

- **v1.0.0** - 初始版本，包含核心规范
- **v1.1.0** - 添加AI协作指南
- **v1.2.0** - 完善错误处理和响应格式

记住：好的规范不是限制，而是让团队更高效协作的基础！ 🎯 # 🤖 AI友好的Elysia开发规则体系

## 快速开始 🚀

### 1. 对于开发者

**首次使用：**
1. 阅读 `ai-friendly-elysia-rules.md` 了解规范
2. 查看 `ai-development-workflow.md` 学习如何与AI协作
3. 在项目中导入支持文件

**日常开发：**
```typescript
// 使用标准错误码
import { ERROR_CODES } from '@/constants/error-codes';

// 使用响应工具
import { successResponse, errorResponse, BusinessError } from '@/utils/response.helper';
```

### 2. 对于AI助手

**工作原则：**
- 严格遵循 `ai-friendly-elysia-rules.md` 规范
- 按照 `ai-development-workflow.md` 工作流程
- 确保代码质量和一致性

**开发顺序：**
1. Schema定义（最高优先级）
2. Response格式
3. Service层实现
4. Controller层实现
5. 测试用例

## 核心优势 💪

### 1. 一致性
- 统一的文件结构
- 标准的命名规范
- 一致的错误处理

### 2. 类型安全
- TypeBox Schema + TypeScript类型
- 编译时类型检查
- 运行时参数验证

### 3. 可维护性
- 清晰的模块划分
- 完整的文档注释
- 系统化的测试

### 4. AI友好
- 语义清晰的代码结构
- 明确的依赖关系
- 标准化的模式

## 使用示例 📝

### 创建新模块

当你需要创建新的业务模块时，告诉AI助手：

```
功能：用户管理
模块：user
接口：注册、登录、获取个人信息、修改个人信息
认证：登录后的接口需要JWT认证
特殊要求：密码需要加密存储
```

AI助手会自动创建：
- `src/modules/user/user.schema.ts`
- `src/modules/user/user.response.ts`
- `src/modules/user/user.service.ts`
- `src/modules/user/user.controller.ts`
- `src/modules/user/user.test.ts`

### 修改现有功能

```
修改用户查询接口，添加分页功能，每页最多50条记录
```

AI助手会：
1. 分析现有代码
2. 更新Schema定义
3. 修改Service逻辑
4. 更新Controller
5. 补充测试用例

## 代码质量保证 ✅

### 自动检查项
- [ ] TypeScript类型正确性
- [ ] Schema验证完整性
- [ ] 错误处理覆盖
- [ ] 响应格式一致性
- [ ] 命名规范符合标准
- [ ] 文档注释完整

### 人工Review项
- [ ] 业务逻辑正确性
- [ ] 安全性考虑
- [ ] 性能优化
- [ ] 用户体验

## 最佳实践 🌟

### 1. 需求描述
```
✅ 清晰：实现用户注册接口，包含邮箱验证和密码强度检查
❌ 模糊：做一个用户功能
```

### 2. 错误处理
```typescript
// ✅ 使用标准错误类
throw new BusinessError('用户名已存在', ERROR_CODES.USER_ALREADY_EXISTS);

// ❌ 直接抛出Error
throw new Error('用户名已存在');
```

### 3. 响应格式
```typescript
// ✅ 使用工具函数
return successResponse(userData, '查询成功');

// ❌ 手动构造
return { code: 'SUCCESS', message: '查询成功', data: userData };
```

## 性能考虑 ⚡

### 数据库优化
- 使用索引优化查询
- 避免N+1查询问题
- 合理使用连接池

### 缓存策略
- 热点数据Redis缓存
- 适当的缓存过期时间
- 缓存穿透防护

### 并发处理
- 避免阻塞操作
- 合理的超时设置
- 资源清理

## 故障排除 🔧

### 常见问题

1. **类型错误**
   - 检查Schema定义
   - 确认类型导出
   - 验证导入路径

2. **运行时错误**
   - 查看错误日志
   - 检查参数验证
   - 确认业务逻辑

3. **性能问题**
   - 分析慢查询
   - 检查缓存命中率
   - 监控资源使用

### 调试技巧

```typescript
// 添加调试日志
Logger.debug(`处理用户请求: ${JSON.stringify(params)}`);

// 性能监控
const startTime = Date.now();
// ... 业务逻辑
Logger.info(`操作耗时: ${Date.now() - startTime}ms`);
```

## 版本历史 📚

- **v1.0.0** - 初始版本，包含核心规范
- **v1.1.0** - 添加AI协作指南
- **v1.2.0** - 完善错误处理和响应格式

记住：好的规范不是限制，而是让团队更高效协作的基础！ 🎯