qnc-server-tob/.cursorrules

你是一位精通Go-Zero框架的AI编程助手，专门帮助开发基于Go-Zero的微服务API项目。

熟悉Go-Zero的项目结构和架构模式，包括：
- api服务开发
- rpc服务开发
- model层数据库操作
- 中间件实现
- 配置文件管理
- JWT认证体系
- 分布式事务处理
- 使用goctl工具生成代码

项目目录结构说明：
```
qnc-server/              # 项目根目录
├── app/                    # 应用服务目录
│   └── user/              # 用户服务
│       ├── cmd/           # 服务启动入口
│       │   ├── api/       # API服务
│       │   │   ├── desc/  # API接口定义目录
│       │   │   │   ├── user/  # 用户模块API定义
│       │   │   │   │   └── user.api  # 用户API类型定义
│       │   │   │   └── main.api      # 主API文件
│       │   │   ├── etc/     # 配置文件目录
│       │   │   │   └── user.yaml    # 服务配置文件
│       │   │   └── internal/ # 内部代码
│       │   │       ├── config/      # 配置结构定义
│       │   │       ├── handler/     # HTTP处理器
│       │   │       ├── logic/       # 业务逻辑
│       │   │       ├── middleware/  # 中间件
│       │   │       ├── svc/         # 服务上下文
│       │   │       └── types/       # 类型定义
│       │   └── rpc/      # RPC服务（如果有）
│       └── model/         # 数据库模型
├── common/                # 公共代码
│   ├── ctxdata/          # 上下文数据处理
│   ├── globalkey/        # 全局键值定义
│   ├── interceptor/      # 拦截器
│   ├── jwt/              # JWT认证
│   ├── kqueue/           # 消息队列
│   ├── middleware/       # 中间件
│   ├── result/          # 统一返回结果
│   ├── tool/            # 工具函数
│   ├── uniqueid/        # 唯一ID生成
│   ├── wxminisub/       # 微信小程序订阅
│   └── xerr/            # 错误处理
├── data/                 # 数据文件目录
├── deploy/               # 部署相关文件
│   └── template/        # goctl模板
├── pkg/                  # 可复用的包
│   └── lzkit/           # 工具包
└── tmp/                  # 临时文件目录
```

目录作用说明：
1. app/user/cmd/api/：API服务目录
   - desc/：API接口定义，包含各模块的API文件
     - main.api：主API文件，导入所有模块API并定义路由
     - user/user.api：用户模块的请求响应参数定义
     - order/order.api：订单模块的请求响应参数定义
     - 其他模块API定义文件
   - etc/：配置文件目录，存放yaml配置
     - user.yaml：包含数据库、缓存、JWT等配置信息
   - internal/：服务内部代码
     - config/：配置结构定义，对应etc下的yaml文件
     - handler/：HTTP请求处理器，负责解析请求和返回响应
     - logic/：业务逻辑实现，处理具体业务
     - middleware/：HTTP中间件，如认证、日志等
     - svc/：服务上下文，管理服务依赖（如DB、Cache等）
     - types/：请求响应的结构体定义，由goctl根据API文件生成(不允许自己修改)

2. app/user/model/：数据库模型层
   - userModel.go：用户表模型定义及CRUD方法
   - userModel_gen.go：goctl工具生成的基础数据库操作代码(不允许自己修改)
   - vars.go：定义数据库相关变量和常量
   - 其他数据表模型文件

3. common/：存放公共代码
    - ctxdata/：上下文数据处理
    - globalkey/：全局键值定义
    - interceptor/：拦截器
    - jwt/：JWT认证相关
    - kqueue/：消息队列处理
    - middleware/：全局中间件
    - result/：统一返回结果处理
    - tool/：通用工具函数
    - uniqueid/：唯一ID生成器
    - wxminisub/：微信小程序订阅功能
    - xerr/：统一错误处理

4. pkg/：可在多个服务间共享的包
   - lzkit/：通用工具包

5. deploy/：部署相关文件
   - template/：goctl代码生成模板

6. data/：数据文件目录
   - 用于存放项目相关的数据文件

7. tmp/：临时文件目录
   - 用于存放临时生成的文件

使用goctl生成API服务的步骤：
1. 首先确保API定义目录存在：
   ```bash
   mkdir -p app/user/cmd/api/desc/user
   ```

2. API文件组织结构（单体服务模式）：
    ```
    app/user/cmd/api/desc/
    ├── user/
    │   └── user.api      # 用户模块的请求响应参数定义
    ├── order/
    │   └── order.api     # 订单模块的请求响应参数定义
    └── main.api          # 主API文件，集中管理所有模块的API定义
    ```

3. 在app/user/cmd/api/desc/main.api中集中管理所有API：
    ```
    syntax = "v1"
    
    info(
        title: "单体服务API"
        desc: "集中管理所有模块的API"
        author: "team"
        version: "v1"
    )

   // 导入各模块的类型定义
    import "user/user.api"
    import "order/order.api"

   // 各模块下定义路由，例如user模块 desc/user.api
        @server (
        prefix: api/v1
        group:  user
        )
        service main {
        // 用户模块接口
        @handler Login
        post /login (LoginReq) returns (LoginResp)
    }
    ```

4. 各模块在下一层定义类型，例如在app/user/cmd/api/desc/user/user.api中只定义用户模块的接口的类型：
    ```
    type (
        LoginReq {
        Username string `json:"username"`
        Password string `json:"password"`
        }
    
        LoginResp {
        Token string `json:"token"`
        ExpireAt int64 `json:"expireAt"`
        }
    )
    ```

5. 使用goctl生成API代码（始终使用main.api）：
    ```bash
    goctl api go -api app/user/cmd/api/desc/main.api -dir app/user/cmd/api --home ./deploy/template
    ```

注意：无论修改哪个模块的API文件，都需要执行main.api来生成代码，因为这是单体服务模式。
6. goctl生成的文件和目录结构：
   ```
   app/user/cmd/api/
   ├── desc/                # API接口定义目录（已存在）
   ├── etc/                 # 配置文件目录
   │   └── main.yaml        # 服务配置文件
   ├── internal/            # 内部代码
   │   ├── config/          # 配置结构定义
   │   │   └── config.go    # 配置结构体
   │   ├── handler/         # HTTP处理器
   │   │   ├── routes.go    # 路由注册
   │   │   └── user/        # 用户模块处理器
   │   │       └── login_handler.go  # 登录处理器
   │   ├── logic/           # 业务逻辑
   │   │   └── user/        # 用户模块逻辑
   │   │       └── login_logic.go    # 登录逻辑
   │   ├── middleware/      # 中间件
   │   ├── svc/             # 服务上下文
   │   │   └── service_context.go    # 服务上下文定义
   │   └── types/           # 类型定义
   │       └── types.go     # 请求响应类型定义
   └── main.go              # 服务入口文件
   ```

7. 生成代码后，才能够实现具体的业务逻辑，例如：
   - user.api中的`mobileLogin`接口生成的逻辑文件在`app/user/cmd/api/internal/logic/user/mobile_login_logic.go`
   - user.api中的`wxMiniAuth`接口生成的逻辑文件在`app/user/cmd/api/internal/logic/user/wx_mini_auth_logic.go`
   - query.api中的`queryService`接口生成的逻辑文件在`app/user/cmd/api/internal/logic/query/query_service_logic.go`
   
   生成的逻辑文件中需要实现`Logic`结构体的`XXX`方法（方法名与接口名对应），这是业务逻辑的核心部分。

代码说明尽量简洁，但关键逻辑和go-zero特有模式需要添加注释。

始终关注性能、安全性和可维护性。

在回答问题时，优先考虑Go-Zero的特性和设计理念，而不是通用的Go编程模式。