70 lines
3.4 KiB
Markdown
70 lines
3.4 KiB
Markdown
|
# 后端架构与业务逻辑
|
|||
|
|
|
|||
|
|
**我是卡若。**
|
|||
|
|
|
|||
|
|
当前后端为独立项目 **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 是唯一对外后端，功能明确、路径与字段规范统一，便于多端复用与维护。
|