159 lines
5.9 KiB
Markdown
159 lines
5.9 KiB
Markdown
# 萌芽小店 · 后端（mengyastore-backend-go）
|
||
|
||
基于 **Go + Gin + GORM** 的 REST API：商品与**发货方式**、订单、SproutGate 用户校验、站点设置、聊天、收藏夹；可选 **RabbitMQ** 发送订单邮件、可选 **Redis**；管理端提供 **系统状态** 聚合接口。
|
||
|
||
## 技术依赖（核心）
|
||
|
||
| 包 | / 用途 |
|
||
|----|--------|
|
||
| gin | HTTP 路由 |
|
||
| gorm.io/gorm + driver/mysql | MySQL |
|
||
| gin-contrib/cors | CORS |
|
||
| google/uuid | 订单 ID |
|
||
| github.com/rabbitmq/amqp091-go | RabbitMQ（可选） |
|
||
| github.com/redis/go-redis/v9 | Redis 探测（可选） |
|
||
| github.com/joho/godotenv | `.env` 加载 |
|
||
|
||
## 目录结构（与仓库一致）
|
||
|
||
```
|
||
mengyastore-backend-go/
|
||
├── main.go # 路由注册、MQ 生命周期
|
||
├── docker-compose.yml
|
||
├── init.sql # 可选：建库参考
|
||
├── cmd/migrate/main.go # JSON → MySQL 历史数据迁移
|
||
├── internal/
|
||
│ ├── auth/sproutgate.go
|
||
│ ├── cache/ # Redis 等扩展
|
||
│ ├── config/config.go # 环境变量与默认值（APP_ENV、DSN、MQ、Redis…）
|
||
│ ├── database/db.go # Open + AutoMigrate
|
||
│ ├── database/models.go # GORM 表模型
|
||
│ ├── email/
|
||
│ ├── mq/ # 连接、拓扑、Publish、Consumer、断线重连
|
||
│ ├── models/ # JSON 业务模型
|
||
│ ├── storage/ # Product / Order / Site / Wishlist / Chat
|
||
│ └── handlers/
|
||
│ ├── public.go
|
||
│ ├── order.go
|
||
│ ├── stats.go
|
||
│ ├── wishlist.go
|
||
│ ├── chat.go
|
||
│ ├── admin.go
|
||
│ ├── admin_product.go
|
||
│ ├── admin_orders.go
|
||
│ ├── admin_site.go
|
||
│ ├── admin_chat.go
|
||
│ └── admin_status.go # GET /api/admin/system-status
|
||
```
|
||
|
||
## API 路由一览
|
||
|
||
### 公开
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/health` | 健康检查（可含 rabbitmq 状态） |
|
||
| GET | `/api/products` | 上架商品列表（无卡密、无 `fixedContent`） |
|
||
| POST | `/api/products/:id/view` | 记录浏览 |
|
||
| GET | `/api/stats` | 订单数、访问量等 |
|
||
| POST | `/api/site/visit` | 站点访问计数 |
|
||
| GET | `/api/site/maintenance` | 维护状态 |
|
||
| POST | `/api/checkout` | 创建订单（卡密扣库或固定内容填充 `delivered_codes`） |
|
||
| GET | `/api/orders` | 当前用户订单（Bearer） |
|
||
| POST | `/api/orders/:id/confirm` | 确认订单（返回发货内容等） |
|
||
|
||
### 收藏夹（Bearer）
|
||
|
||
| GET | `/api/wishlist` |
|
||
| POST | `/api/wishlist` |
|
||
| DELETE | `/api/wishlist/:id` |
|
||
|
||
### 聊天（Bearer）
|
||
|
||
| GET | `/api/chat/messages` |
|
||
| POST | `/api/chat/messages` |
|
||
|
||
### 管理端（`X-Admin-Token` / `Authorization` / `?token=`）
|
||
|
||
| POST | `/api/admin/verify` | 校验 token，返回 `valid` |
|
||
| GET/POST | `/api/admin/products` … | 商品 CRUD（见 payload 含 `fulfillmentType`、`fixedContent`） |
|
||
| PUT | `/api/admin/products/:id` |
|
||
| PATCH | `/api/admin/products/:id/status` |
|
||
| DELETE | `/api/admin/products/:id` |
|
||
| POST | `/api/admin/site/maintenance` |
|
||
| GET/POST | `/api/admin/site/smtp` |
|
||
| GET | `/api/admin/orders` |
|
||
| DELETE | `/api/admin/orders/:id` |
|
||
| GET … POST … DELETE | `/api/admin/chat`… | 会话与回复 |
|
||
| **GET** | **`/api/admin/system-status`** | **backend / mysql / redis / rabbitmq 摘要** |
|
||
|
||
> 文档中若出现已废弃的 `GET /api/admin/token`，以仓库 `main.go` 为准。
|
||
|
||
## 数据库表（字段摘要）
|
||
|
||
### products
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| fulfillment_type | `card` 卡密逐条；`fixed` 固定内容（不限库存） |
|
||
| fixed_content | 固定发货正文（网盘链接、说明等）；公开接口不返回 |
|
||
| delivery_mode | 订单维度习惯字段：`auto` / `manual`（与 fulfillment 独立） |
|
||
| 其余 | name, price, discount_price, tags, cover_url, screenshot_urls, description, active, require_login, max_per_account, total_sold, view_count, show_note, show_contact … |
|
||
|
||
### product_codes
|
||
|
||
卡密一行一条；`fulfillment_type = fixed` 时可为空。
|
||
|
||
### orders
|
||
|
||
含 `delivered_codes`（JSON）、`notify_email`、`delivery_mode`、`status` 等。
|
||
|
||
### site_settings
|
||
|
||
KV：如 `totalVisits`、`maintenance`、`smtpHost`、`smtpPassword` 等；缺失键时 `sitestore.get` 不报错（不向日志刷 ErrRecordNotFound：`Find` 替代 `First`）。
|
||
|
||
## 配置说明
|
||
|
||
配置由 **`config.Load()`** 从环境变量读取，可选 **`./.env`**（或 `ENV_FILE` 指定）。
|
||
|
||
要点：
|
||
|
||
- `DATABASE_DSN` 为空时按 `APP_ENV` 使用内建测试/生产默认 DSN（仅开发便利）。
|
||
- RabbitMQ、Redis 开关与地址见 `config.go` 注释。
|
||
- `HTTP_LISTEN_ADDR`、`PUBLIC_API_BASE_URL` 供系统状态 JSON 展示。
|
||
|
||
## 发货与订单逻辑
|
||
|
||
### fulfillment_type = `card`（默认）
|
||
|
||
1. `POST /api/checkout` 校验库存 ≥ 购买数量。
|
||
2. 从 `product_codes` 取出对应条数写入订单 `delivered_codes`，并 `Update` 商品去掉已发码。
|
||
3. 销量 `IncrementSold`；邮件/MQ 通知。
|
||
|
||
### fulfillment_type = `fixed`
|
||
|
||
1. 不校验卡密条数；不修改 `product_codes`。
|
||
2. 将 `fixed_content` 复制 `quantity` 次填入 `delivered_codes`（与多件购买展示一致）。
|
||
3. 仍 `IncrementSold`；邮件/MQ 同自动发货路径。
|
||
|
||
### delivery_mode（订单）
|
||
|
||
业务上仍可区分用户确认后展示「等待人工发货」等；与 `fulfillment_type` 正交。
|
||
|
||
## RabbitMQ 说明
|
||
|
||
- 启用时声明交换机/队列/绑定；订单邮件可 `Publish`，失败降级直发 SMTP。
|
||
- **504 channel closed** 等可回收错误：客户端会 **重连** 并在成功后 **重启消费协程**（见 `internal/mq/client.go`）。
|
||
|
||
## 本地开发
|
||
|
||
```bash
|
||
go run .
|
||
go build -o mengyastore-backend.exe .
|
||
go run ./cmd/migrate/main.go # 按需迁移旧 JSON
|
||
```
|
||
|
||
---
|
||
|
||
维护时请以 **`main.go` 与 `internal/database/models.go`** 为最终准据；本文随版本迭代更新。
|