# 后端架构与业务逻辑

**我是卡若。**

当前后端为独立项目 **soul-api**（Go + Gin + GORM），提供全部 `/api/*` 接口，与 soul-admin、小程序对接。

## 1. 技术栈（当前）

| 项目 | 技术 | 说明 |
|------|------|------|
| **soul-api** | Go 1.25 + Gin + GORM + MySQL | 独立 API 服务，路径与现网一致，响应 camelCase |

## 2. soul-api 目录结构

\`\`\`
soul-api/
├── cmd/
│   └── server/
│       └── main.go              # 入口
├── internal/
│   ├── config/                  # 配置（环境变量）
│   ├── database/                # 数据库连接 (GORM)
│   ├── handler/                 # API 处理函数（按业务拆分）
│   │   ├── admin.go, admin_chapters.go, admin_withdrawals.go ...
│   │   ├── auth.go, user.go, book.go, orders.go
│   │   ├── withdraw.go, referral.go, distribution.go
│   │   ├── config.go, db.go, miniprogram.go ...
│   ├── middleware/              # 中间件（CORS、鉴权、限流、安全头）
│   ├── model/                   # 数据模型（GORM + json 标签 camelCase）
│   │   ├── user.go, order.go, chapter.go, withdrawal.go ...
│   └── router/
│       └── router.go            # 路由注册，路径与现网 /api/* 一致
├── .env, .env.example
├── go.mod, go.sum
└── Makefile
\`\`\`

## 3. 核心业务模块（在 handler 中实现）

- **鉴权**：`/api/admin` 登录与鉴权，管理端 Cookie/Token；小程序走 `/api/miniprogram/login` 等。
- **用户**：`/api/user/profile`、`/api/user/update`、`/api/user/track`、`/api/user/purchase-status` 等。
- **书籍/章节**：`/api/book/*`（目录、章节、搜索、统计）。
- **订单与支付**：`/api/orders`、`/api/miniprogram/pay`、支付回调等。
- **分销与提现**：`/api/referral/*`、`/api/distribution/*`、`/api/withdraw/*`、`/api/admin/withdrawals`。
- **配置与内容**：`/api/config`、`/api/content`、`/api/db/config`、`/api/db/book` 等。
- **管理端**：`/api/admin/*`（章节、分销概览、提现审核等）、`/api/db/*`（用户、配置、初始化等）。

## 4. 接口与字段规范

- **路径**：与现网完全一致（如 `GET /api/user/profile`、`PUT /api/admin/withdrawals`），便于前端只改 baseUrl 切换后端。
- **请求/响应字段**：一律**小写开头驼峰（camelCase）**。
  - Go 结构体：`json:"userId"`、`json:"createdAt"`、`json:"referralCode"`。
  - 数据库列名：保持 snake_case（如 `user_id`、`created_at`），仅在 GORM 与 SQL 中使用，不暴露给前端。
- **统一响应**：成功可返回 `gin.H{"success": true, "data": ...}`；失败 `gin.H{"success": false, "error": "..."}`。

## 5. 数据库与配置

- **数据库**：MySQL，GORM 连接；表结构可与原 Next/Prisma 保持一致，便于迁移。
- **配置**：环境变量（.env），如 `DB_*`、`PORT`、`CORS_ORIGINS`、`JWT_SECRET` 等；敏感信息不提交仓库。

## 6. 扩展性

- **鉴权**：管理端已用 `middleware.AdminAuth()` 保护 `/api/admin/*`、`/api/db/*`。
- **CORS**：已配置 AllowOrigins/AllowCredentials，支持 soul-admin 与小程序跨域。
- **限流**：可按需在 middleware 中增加 rate limit。

---
**卡若说：**
soul-api 是唯一对外后端，功能明确、路径与字段规范统一，便于多端复用与维护。