# 全栈应用开发规范

## 项目结构

```
src/
├── client/       # 前端代码 (React + Vite)
├── server/       # 后端代码 (Hono + TypeORM)
│   ├── api/      # API路由
│   ├── migrations/ # 数据库迁移脚本
│   ├── modules/  # 业务模块
│   └── middleware/ # 中间件
```

## 技术栈

### 前端
- React 18
- TypeScript (严格模式)
- Vite 构建工具

### 后端
- Hono 框架
- TypeORM (MySQL)
- Redis (缓存/会话管理)

## 开发规范

1. **TypeScript严格模式**
   - 启用所有严格类型检查选项
   - 避免使用`any`类型

2. **模块化组织**
   - 按功能划分模块
   - 每个模块包含:
     - 实体定义
     - 服务层
     - 路由控制器

3. **接口定义**
   - 清晰的DTO(Data Transfer Object)定义
   - 统一的API响应格式
   - 完善的Swagger文档

4. **数据库规范**
   - 使用迁移脚本管理表结构变更
   - 实体类与数据库表严格映射

5. **Hono OpenAPI规范**
   - 使用`@hono/zod-openapi`的`createRoute`创建路由
   - 每个路由必须包含:
     - 请求方法(method)和路径(path)
     - 请求体验证(使用Zod模式):
       ```typescript
       request: {
         body: {
           content: {
             'application/json': {
               schema: YourZodSchema
             }
           }
         }
       }
       ```
     - 响应定义(必须包含200/400/500等状态码):
       ```typescript
       responses: {
         200: {
           description: '成功响应描述',
           content: {
             'application/json': {
               schema: SuccessSchema
             }
           }
         },
         400: {
           description: '客户端错误',
           content: {
             'application/json': {
               schema: ErrorSchema
             }
           }
         }
       }
       ```
   - 错误响应必须使用统一格式:
     ```typescript
     {
       code: number,  // HTTP状态码
       message: string  // 错误描述
     }
     ```
   - 实际响应必须与OpenAPI定义完全一致
   - 使用中间件统一处理错误格式
   - 示例完整路由定义:
     ```typescript
     const route = createRoute({
       method: 'post',
       path: '/example',
100|        request: {
101|          body: {
102|            content: {
103|              'application/json': {
104|                schema: ExampleSchema
105|              }
106|            }
107|          }
108|        },
109|        responses: {
110|          200: { /*...*/ },
111|          400: { /*...*/ },
112|          500: { /*...*/ }
113|        }
114|      });
115|      ```