后端架构与业务逻辑

我是卡若。

当前后端为独立项目 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 是唯一对外后端，功能明确、路径与字段规范统一，便于多端复用与维护。

3.4 KiB Raw Blame History Unescape Escape