# 萌芽小店 · 后端

基于 **Go + Gin + GORM** 构建的 RESTful API 服务，负责商品管理、订单处理、用户认证、聊天消息等核心业务。

## 技术依赖

| 包 | 版本 | 用途 |
|----|------|------|
| gin | v1.9 | HTTP 路由框架 |
| gorm | v1.31 | ORM |
| gorm/driver/mysql | v1.6 | MySQL 驱动 |
| go-sql-driver/mysql | v1.9 | 底层 MySQL 连接 |
| gin-contrib/cors | latest | CORS 中间件 |
| google/uuid | latest | UUID 生成 |

## 目录结构

```
mengyastore-backend/
├── main.go                          # 程序入口，路由注册
├── cmd/
│   └── migrate/
│       └── main.go                  # 一次性 JSON→MySQL 数据迁移脚本
├── data/
│   └── json/
│       └── settings.json            # 服务配置（adminToken、DSN 等）
├── internal/
│   ├── config/
│   │   └── config.go                # 配置加载
│   ├── database/
│   │   ├── db.go                    # GORM 初始化 + AutoMigrate
│   │   └── models.go                # 数据库行结构体（GORM 模型）
│   ├── models/
│   │   ├── product.go               # 业务模型 Product
│   │   ├── order.go                 # 业务模型 Order
│   │   └── chat.go                  # 业务模型 ChatMessage
│   ├── storage/
│   │   ├── jsonstore.go             # 商品存储（GORM 实现）
│   │   ├── orderstore.go            # 订单存储
│   │   ├── sitestore.go             # 站点设置存储
│   │   ├── wishliststore.go         # 收藏夹存储
│   │   └── chatstore.go             # 聊天消息存储（含内存级频率限制）
│   ├── handlers/
│   │   ├── admin.go                 # AdminHandler 结构体 + requireAdmin
│   │   ├── admin_product.go         # 商品 CRUD 接口
│   │   ├── admin_site.go            # 维护模式接口
│   │   ├── admin_orders.go          # 订单管理接口
│   │   ├── admin_chat.go            # 管理员聊天接口
│   │   ├── public.go                # 公开接口（商品列表、浏览量）
│   │   ├── order.go                 # 下单、确认订单接口
│   │   ├── stats.go                 # 统计信息接口
│   │   ├── wishlist.go              # 收藏夹接口（用户）
│   │   └── chat.go                  # 聊天接口（用户）
│   └── auth/
│       └── sproutgate.go            # SproutGate OAuth 客户端
```

## API 路由一览

### 公开接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/health` | 健康检查 |
| GET | `/api/products` | 获取商品列表（仅 active） |
| POST | `/api/products/:id/view` | 记录商品浏览量 |
| GET | `/api/stats` | 获取总订单数和总访问量 |
| POST | `/api/site/visit` | 记录站点访问 |
| GET | `/api/site/maintenance` | 获取维护状态 |
| POST | `/api/checkout` | 创建订单（生成支付二维码） |
| GET | `/api/orders` | 获取当前用户订单（需 Bearer token） |
| POST | `/api/orders/:id/confirm` | 确认付款（触发发货） |

### 收藏夹（需登录）

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/wishlist` | 获取收藏商品 ID 列表 |
| POST | `/api/wishlist` | 添加收藏 |
| DELETE | `/api/wishlist/:id` | 取消收藏 |

### 聊天（需登录）

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/chat/messages` | 获取自己的聊天记录 |
| POST | `/api/chat/messages` | 发送消息（1 秒频率限制） |

### 管理员接口（需 `?token=xxx` 或 `Authorization: <token>`）

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/admin/token` | 获取令牌（用于验证） |
| GET | `/api/admin/products` | 获取全部商品（含卡密） |
| POST | `/api/admin/products` | 创建商品 |
| PUT | `/api/admin/products/:id` | 编辑商品 |
| PATCH | `/api/admin/products/:id/status` | 切换上下架 |
| DELETE | `/api/admin/products/:id` | 删除商品 |
| POST | `/api/admin/site/maintenance` | 设置维护模式 |
| GET | `/api/admin/orders` | 获取全部订单 |
| DELETE | `/api/admin/orders/:id` | 删除订单 |
| GET | `/api/admin/chat` | 获取全部用户对话 |
| GET | `/api/admin/chat/:account` | 获取指定用户对话 |
| POST | `/api/admin/chat/:account` | 管理员回复 |
| DELETE | `/api/admin/chat/:account` | 清除对话 |

## 数据库表结构

### products

| 字段 | 类型 | 说明 |
|------|------|------|
| id | varchar(36) | UUID 主键 |
| name | varchar(255) | 商品名称 |
| price | double | 原价 |
| discount_price | double | 折扣价（0 = 无折扣）|
| tags | json | 标签数组 |
| cover_url | varchar(500) | 封面图 URL |
| screenshot_urls | json | 截图 URL 数组（最多 5 张）|
| verification_url | varchar(500) | 验证链接 |
| description | text | Markdown 描述 |
| active | tinyint(1) | 是否上架 |
| require_login | tinyint(1) | 是否必须登录购买 |
| max_per_account | bigint | 每账户最大购买数（0=不限）|
| total_sold | bigint | 累计销量 |
| view_count | bigint | 累计浏览量 |
| delivery_mode | varchar(20) | 发货模式：`auto` / `manual` |
| show_note | tinyint(1) | 下单时显示备注输入框 |
| show_contact | tinyint(1) | 下单时显示联系方式输入框 |
| created_at | datetime(3) | 创建时间 |

### product_codes

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint unsigned | 自增主键 |
| product_id | varchar(36) | 关联商品 ID（索引）|
| code | text | 卡密内容 |

### orders

| 字段 | 类型 | 说明 |
|------|------|------|
| id | varchar(36) | UUID 主键 |
| product_id | varchar(36) | 商品 ID（索引）|
| product_name | varchar(255) | 商品名称快照 |
| user_account | varchar(255) | 用户账号（可空，匿名）|
| user_name | varchar(255) | 用户昵称 |
| quantity | bigint | 购买数量 |
| delivered_codes | json | 已发放卡密 |
| status | varchar(20) | `pending` / `completed` |
| delivery_mode | varchar(20) | `auto` / `manual` |
| note | text | 用户备注 |
| contact_phone | varchar(50) | 联系手机号 |
| contact_email | varchar(255) | 联系邮箱 |
| created_at | datetime(3) | 下单时间 |

### site_settings

键值对存储，当前使用的键：

| Key | 说明 |
|-----|------|
| `totalVisits` | 总访问量 |
| `maintenance` | 维护模式（`true` / `false`）|
| `maintenanceReason` | 维护原因文本 |

### wishlists

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint unsigned | 自增主键 |
| account_id | varchar(255) | 用户账号（唯一索引）|
| product_id | varchar(36) | 商品 ID（联合唯一）|

### chat_messages

| 字段 | 类型 | 说明 |
|------|------|------|
| id | varchar(36) | UUID 主键 |
| account_id | varchar(255) | 用户账号（索引）|
| account_name | varchar(255) | 用户昵称 |
| content | text | 消息内容 |
| sent_at | datetime(3) | 发送时间 |
| from_admin | tinyint(1) | 是否来自管理员 |

## 配置文件

`data/json/settings.json`：

```json
{
  "adminToken": "你的管理员令牌",
  "authApiUrl": "https://auth.api.shumengya.top",
  "databaseDsn": ""
}
```

`databaseDsn` 为空时自动使用测试数据库。也可以通过环境变量 `DATABASE_DSN` 覆盖。

## 发货逻辑

### 自动发货（`deliveryMode = "auto"`）

1. `POST /api/checkout` → 从 `product_codes` 提取指定数量的卡密
2. 商品 `quantity` 减少，卡密从数据库删除
3. 卡密保存到订单 `delivered_codes`
4. 用户 `POST /api/orders/:id/confirm` 确认付款后，订单状态变为 `completed`，响应中返回卡密内容
5. 同时调用 `IncrementSold` 增加销量统计

### 手动发货（`deliveryMode = "manual"`）

1. `POST /api/checkout` → 创建订单，不提取卡密
2. 用户 `POST /api/orders/:id/confirm` 后，订单变为 `completed`，但 `delivered_codes` 为空
3. 管理员在后台查看订单的备注、手机号、邮箱后手动发货

## 本地开发

```bash
go run .               # 启动服务（默认 :8080）
go build -o mengyastore-backend.exe .  # 构建可执行文件
go run ./cmd/migrate/main.go           # 迁移旧 JSON 数据到数据库
```

### 切换数据库

```bash
# 测试库（默认）
# host: 10.1.1.100:3306 / db: mengyastore-test

# 生产库
set DATABASE_DSN=mengyastore:mengyastore@tcp(192.168.1.100:3306)/mengyastore?charset=utf8mb4&parseTime=True&loc=Local
./mengyastore-backend.exe
```

## 认证说明

### 用户认证

通过 SproutGate OAuth 服务验证 Bearer Token：

```go
result, err := authClient.VerifyToken(token)
// result.Valid, result.User.Account, result.User.Username
```

### 管理员认证

管理员令牌通过查询参数或 Authorization 头传入：

```
GET /api/admin/products?token=xxx
Authorization: xxx
```

令牌与 `settings.json` 中的 `adminToken` 比对。