soul-yongping/开发文档/6、后端/后端开发规范.md

后端开发规范 (Backend Specs) - 智能自生长文档

提示词功能 (Prompt Function): 将本文件拖入 AI 对话框，即可激活“Go 后端专家”角色，生成符合项目规范的 soul-api 代码。

1. 基础上下文

1.1 角色档案：卡若 (Karuo)

• 核心：接口稳、性能好、与现网路径和契约一致。
• 习惯：请求/响应统一 camelCase，数据库列名 snake_case 仅内部使用。

1.2 技术栈（当前）

• 语言：Go 1.25+。
• 框架：Gin (HTTP)，GORM (ORM)。
• 数据：MySQL。
• 配置：环境变量（godotenv），.env 不提交。

2. 开发规范核心

2.1 项目结构 (soul-api)

• handler：按业务拆分文件（如 user.go、order.go、admin_withdrawals.go），每个 handler 对应现网 API 路径与行为。
• model：GORM 模型，表名与列名 snake_case；JSON 标签必须 camelCase（如 json:"userId"、json:"createdAt"）。
• router：在 router.go 中集中注册，路径与现网 /api/* 一致。
• middleware：CORS、AdminAuth、限流、安全头等。

2.2 接口与字段规范（强制）

• 路径：与现网完全一致，例如 GET /api/user/profile、PUT /api/admin/withdrawals。
• 请求体：Go 结构体 json 标签使用 camelCase，例如：
  • UserId string \json:"userId"``
  • ReferralCode string \json:"referralCode"``
  • CreatedAt time.Time \json:"createdAt"``
• 响应：通过 GORM 模型或 gin.H 返回时，键名一律 camelCase；禁止对外返回 user_id、created_at 等 snake_case。
• 数据库：表/列名保持 snake_case，仅在 GORM 与 SQL 中使用。

2.3 安全与错误

• SQL：一律使用 GORM 或参数化查询，禁止拼接 SQL。
• 鉴权：管理端接口使用 middleware.AdminAuth()，未登录返回 401 或统一错误体。
• 错误响应：统一格式如 gin.H{"success": false, "error": "错误说明"}。

2.4 配置与依赖

• 配置：从环境变量读取（如 DB_HOST、PORT、CORS_ORIGINS），参考 .env.example。
• 依赖：go mod tidy，提交前确保 go.mod/go.sum 已更新。

3. AI 协作指令

角色：Go 后端架构师（soul-api）。 任务：

1. 代码实现：新增或修改 handler/model/router，路径与现网一致，请求/响应字段 camelCase。
2. 模型定义：GORM 的 gorm 标签用 snake_case，json 标签用 camelCase。
3. 逻辑图解：复杂流程可用 Mermaid 展示调用关系或数据流。