tydata-server/.cursor/rules/api.mdc

# Cursor 工作流程和规范

## 目录结构说明

### API 定义目录 (`app/main/api/desc/`)
```
desc/
├── admin/                # 后台管理接口
│   ├── admin_user.api   # 管理员用户相关接口
│   ├── platform_user.api # 平台用户相关接口
│   ├── order.api        # 订单管理接口
│   ├── promotion.api    # 促销活动接口
│   ├── menu.api         # 菜单管理接口
│   ├── role.api         # 角色权限接口
│   └── auth.api         # 后台认证接口
│
├── front/               # 前台业务接口
│   ├── user.api        # 用户相关接口
│   ├── product.api     # 产品相关接口
│   ├── pay.api         # 支付相关接口
│   ├── query.api       # 查询相关接口
│   ├── auth/           # 前台认证相关子模块
│   ├── product/        # 产品相关子模块
│   ├── query/          # 查询相关子模块
│   ├── user/           # 用户相关子模块
│   └── pay/            # 支付相关子模块
│
└── main.api            # API 主入口文件，用于引入所有子模块
```

### 目录规范
1. 后台管理接口统一放在 `admin/` 目录下
   - 所有后台管理相关的 API 定义文件都放在此目录
   - 文件名应清晰表明模块功能，如 `order.api`、`user.api` 等
   - 后台接口统一使用 `/api/v1/admin/` 前缀

2. 前台业务接口统一放在 `front/` 目录下
   - 所有面向用户的 API 定义文件都放在此目录
   - 可以根据业务模块创建子目录，如 `user/`、`product/` 等
   - 前台接口统一使用 `/api/v1/` 前缀

3. 主入口文件 `main.api`
   - 用于引入所有子模块的 API 定义
   - 保持清晰的模块分类和注释

## API 开发流程

### 1. API 定义
- 根据业务类型选择正确的目录：
  - 后台管理接口：`app/main/api/desc/admin/` 目录
  - 前台业务接口：`app/main/api/desc/front/` 目录
- 创建新的 `.api` 文件，遵循以下命名规范：
  - 后台接口：`[模块名].api`，如 `order.api`、`user.api`
  - 前台接口：`[模块名].api`，如 `product.api`、`pay.api`
- API 定义规范：
  - 使用 RESTful 风格
  - 请求/响应结构体命名规范：`[模块名][操作名][Req/Resp]`
  - 字段类型使用 string 而不是 int64 来存储枚举值
  - 添加必要的注释说明
  - 请求/响应参数定义规范：
    ```go
    type (
        // 创建类请求（必填字段）
        AdminCreateXXXReq {
            Field1 string `json:"field1"`           // 字段1说明
            Field2 int64  `json:"field2"`           // 字段2说明
            Field3 string `json:"field3"`           // 字段3说明
        }

        // 更新类请求（可选字段使用指针类型）
        AdminUpdateXXXReq {
            Id     int64   `path:"id"`                    // ID（路径参数）
            Field1 *string `json:"field1,optional"`       // 字段1说明（可选）
            Field2 *int64  `json:"field2,optional"`       // 字段2说明（可选）
            Field3 *string `json:"field3,optional"`       // 字段3说明（可选）
        }

        // 查询列表请求（分页参数 + 可选查询条件）
        AdminGetXXXListReq {
            Page     int64   `form:"page"`                // 页码
            PageSize int64   `form:"pageSize"`            // 每页数量
            Field1   *string `form:"field1,optional"`     // 查询条件1（可选）
            Field2   *int64  `form:"field2,optional"`     // 查询条件2（可选）
            Field3   *string `form:"field3,optional"`     // 查询条件3（可选）
        }

        // 列表项结构体（用于列表响应）
        XXXListItem {
            Id        int64  `json:"id"`                  // ID
            Field1    string `json:"field1"`              // 字段1
            Field2    string `json:"field2"`              // 字段2
            Field3    string `json:"field3"`              // 字段3
            CreateTime string `json:"create_time"`        // 创建时间
            UpdateTime string `json:"update_time"`        // 更新时间
        }

        // 列表响应
        AdminGetXXXListResp {
            Total int64        `json:"total"`             // 总数
            Items []XXXListItem `json:"items"`            // 列表数据
        }
    )
    ```

  - 参数定义注意事项：
    1. 创建类请求（Create）：
       - 所有字段都是必填的，使用普通类型（非指针）
       - 使用 `json` 标签，不需要 `optional` 标记
       - 必须添加字段说明注释

    2. 更新类请求（Update）：
       - 除 ID 外的所有字段都是可选的，使用指针类型（如 `*string`、`*int64`）
       - 使用 `json` 标签，并添加 `optional` 标记
       - ID 字段使用 `path` 标签，因为是路径参数
       - 必须添加字段说明注释

    3. 查询列表请求（GetList）：
       - 分页参数（page、pageSize）使用普通类型
       - 查询条件字段都是可选的，使用指针类型
       - 使用 `form` 标签，并添加 `optional` 标记
       - 必须添加字段说明注释

    4. 响应结构体：
       - 列表响应使用 `Total` 和 `Items` 字段
       - 列表项使用单独的结构体定义
       - 时间字段统一使用 string 类型
       - 必须添加字段说明注释

    5. 标签使用规范：
       - 路径参数：`path:"id"`
       - JSON 参数：`json:"field_name"`
       - 表单参数：`form:"field_name"`
       - 可选字段：添加 `optional` 标记
       - 所有字段必须添加说明注释

  - 示例：
    ```go
    // 通知管理接口
    @server(
        prefix: /api/v1/admin/notification
        group: admin_notification
    )
    service main {
        // 创建通知
        @handler AdminCreateNotification
        post /create (AdminCreateNotificationReq) returns (AdminCreateNotificationResp)

        // 更新通知
        @handler AdminUpdateNotification
        put /update/:id (AdminUpdateNotificationReq) returns (AdminUpdateNotificationResp)

        // 获取通知列表
        @handler AdminGetNotificationList
        get /list (AdminGetNotificationListReq) returns (AdminGetNotificationListResp)
    }
    ```

### 2. 引入 API
- 在 `app/main/api/main.api` 中引入新定义的 API 文件：
  ```go
  import "desc/order.api"
  ```

### 3. 生成代码
- 在项目根目录运行 `gen_api.ps1` 脚本生成相关代码：
  ```powershell
  ./gen_api.ps1
  ```
- 生成的文件包括：
  - `app/main/api/internal/handler/` - 处理器
  - `app/main/api/internal/logic/` - 业务逻辑
  - `app/main/api/internal/svc/` - 服务上下文
  - `app/main/api/internal/types/` - 类型定义

### 4. 实现业务逻辑
- 在 `app/main/api/internal/logic/` 目录下实现各个接口的业务逻辑
- 具体实现规范请参考 `logic.mdc` 文件

## 注意事项
1. 所有枚举类型使用 string 而不是 int64
2. 错误处理必须使用 errors.Wrapf 和 xerr 包
3. 涉及多表操作时使用事务
4. 并发操作时注意使用互斥锁保护共享资源
5. 时间类型统一使用 "2006-01-02 15:04:05" 格式
6. 代码生成后需要检查并完善业务逻辑实现
7. 保持代码风格统一，添加必要的注释