# SproutGate 后端文档

## 技术栈

- **语言**：Go 1.20+
- **Web 框架**：Gin；跨域中间件 **`github.com/gin-contrib/cors`**
- **数据存储**：MySQL（通过 GORM + `gorm.io/driver/mysql`）
- **JWT**：`github.com/golang-jwt/jwt/v5`
- **密码哈希**：`golang.org/x/crypto/bcrypt`

业务数据与配置均保存在 MySQL 中，**不再使用** `data/users/*.json` 与 `data/config/*.json` 作为运行时数据源。仓库中的 `data/` 仅可作迁移脚本输入或本地备份参考。

## 目录结构（要点）

| 路径 | 说明 |
|------|------|
| `main.go` | 入口：连接数据库、初始化 `Store`、注册路由 |
| `internal/database/` | MySQL 连接（`DB_DSN` 或 `DB_HOST`/`DB_USER`/`DB_PASSWORD`/`DB_NAME`/`DB_PORT`，支持 `.env` 本地加载） |
| `internal/handlers/` | HTTP 处理：认证、资料、签到、公开页、管理端等 |
| `internal/models/` | 领域模型（用户、待激活、重置密码、辅助邮箱等） |
| `internal/storage/` | 持久化：`Store` + GORM 模型与业务方法 |
| `internal/auth/` | JWT 签发与校验 |
| `internal/email/` | 发信 |
| `cmd/migrate/` | 一次性工具：将旧版 JSON `data/` 导入 MySQL |

## 环境与数据库

代码中**不再内置任何数据库地址或账号密码**，连接参数完全来自环境变量，连接字符串优先级：**`DB_DSN` > `DB_HOST`/`DB_PORT`/`DB_USER`/`DB_PASSWORD`/`DB_NAME`**。

1. **若设置 `DB_DSN`**：直接使用该完整 DSN（适合 CI、容器或临时切换）。
2. **否则**：用 `DB_HOST`/`DB_USER`/`DB_PASSWORD` 拼接 DSN，`DB_HOST`/`DB_USER`/`DB_PASSWORD` 三者缺一即报错退出；`DB_PORT` 默认 `3306`，`DB_NAME` 默认 `sproutgate`（开发、生产统一用这个库名，仅 host/账号不同）。

本地开发时，在 `sproutgate-backend/.env`（已在 `.gitignore` 中忽略，不会提交）里写：

```
DB_HOST=10.1.1.100
DB_PORT=3306
DB_USER=sproutgate-test
DB_PASSWORD=sproutgate-test
DB_NAME=sproutgate
```

`go run .` / `go run ./cmd/migrate` 启动时会自动从当前目录读取并加载 `.env`（已存在的环境变量不会被覆盖）；生产部署通过容器/`docker-compose` 环境变量注入，不依赖 `.env` 文件。

其它常用环境变量：

| 变量 | 说明 | 默认 |
|------|------|------|
| `PORT` | HTTP 监听端口 | `8080` |
| `APP_ENV` | 仅影响 `/api/health` 返回的 `env` 字段，不再决定数据库选择 | 空则 health 中为 `development` |
| `GIN_MODE` | `release` 时 GORM 日志级别更安静（警告级） | debug 模式 |
| `DB_DSN` | 完整 MySQL DSN，覆盖 `DB_HOST` 等单项配置 | 未设置 |
| `DB_HOST` / `DB_PORT` / `DB_USER` / `DB_PASSWORD` / `DB_NAME` | MySQL 连接参数；`DB_HOST`/`DB_USER`/`DB_PASSWORD` 必填，无内置默认值 | `DB_PORT=3306`，`DB_NAME=sproutgate` |
| `GEO_LOOKUP_URL` | `GET /api/auth/me` 未带 `X-Visit-Location` 时，服务端按 IP 请求该基址反查展示地理位置（实现见 `internal/clientgeo`，会拼接 `?ip=`） | 默认 `https://cf-ip-geo.smyhub.com/api` |

**建议**：生产部署通过 `docker-compose.yml` 旁的 `.env`（同样被 `.gitignore` 忽略）注入 `DB_HOST`/`DB_USER`/`DB_PASSWORD`，不要把真实账号密码写进任何会提交到仓库的文件。

## 数据库表（AutoMigrate）

应用启动与 `migrate` 工具均会同步下列表结构（GORM `AutoMigrate`）：

| 表名 | 用途 |
|------|------|
| `users` | 用户主数据；签到/访问时间列表、`auth_clients` 等以 JSON 文本列存储 |
| `pending_users` | 注册邮箱验证流程中的待激活用户 |
| `password_resets` | 忘记密码验证码 |
| `secondary_email_verifications` | 绑定辅助邮箱验证码 |
| `app_configs` | 键值配置：`admin`、`auth`、`email`、`checkin`、`registration`（JSON） |
| `invite_codes` | 注册邀请码 |
| `profile_likes` | 公开用户主页点赞明细（点赞者、被赞者、自然日等） |
| `profile_like_daily_quota` | 点赞者当日已用额度（与代码常量 `MaxProfileLikesPerDay` 配合） |

管理员令牌、JWT Secret、邮件 SMTP、签到奖励、是否强制邀请码等，均从 `app_configs` / `invite_codes` 读写，首次无记录时由 `Store` 按逻辑补全默认项。

## 从旧 JSON 迁移到 MySQL

在 **`sproutgate-backend`** 目录下：

```bash
# 导入到 .env（或当前环境变量）指向的库
go run ./cmd/migrate --data-dir ./data
```

Windows PowerShell 示例（临时指定生产库连接参数）：

```powershell
$env:DB_HOST = "192.168.1.100"
$env:DB_USER = "sproutgate"
$env:DB_PASSWORD = "<生产密码>"
go run ./cmd/migrate --data-dir ./data
Remove-Item Env:DB_HOST, Env:DB_USER, Env:DB_PASSWORD   # 可选：清除变量，避免影响本机其它命令
```

迁移内容：`data/config/*.json`（写入 `app_configs` 与 `invite_codes`）、`data/users/*.json`（写入 `users`）。对已存在主键执行 **UPSERT**：同账号、同配置键会更新为迁移文件中的值。

## HTTP 路由速览

- **`GET /`**、**`GET /api`**：API 简要说明 JSON（`main.go` 内嵌字段，含 `version`、`routePrefixes` 等）。**当前未注册**单独返回 Markdown 的 `/api/docs` 路由；对外长文档见仓库根目录 **`萌芽账户认证中心-第三方应用API接入文档.md`**。
- **`GET /api/health`**：`{ "status": "ok", "env": "<APP_ENV 或 development>" }`。
- **`/api/auth/*`**：登录、注册、邮箱验证、忘记/重置密码、辅助邮箱、令牌校验、`/me`、签到、更新资料等；可选请求头 `X-Auth-Client`、`X-Auth-Client-Name`（记录第三方应用接入）。
- **`/api/public/*`**：
  - **`GET /api/public/users`**：公开用户目录（未封禁；默认按 `createdAt` 升序）。
  - **`GET /api/public/users/:account`**：公开资料 + 累计赞数；若带合法 Bearer，可附加「是否已赞今日」「当日剩余可点赞人数」等浏览者上下文。
  - **`POST /api/public/users/:account/like`**：登录用户给指定主页点赞（不能赞自己；每人每主页每日一次；每自然日每名用户最多给 **5** 位不同用户点赞，常量见 `internal/storage/profile_likes.go`）。
  - **`GET /api/public/registration-policy`**：是否强制邀请码等。
- **`/api/admin/*`**：需 **`X-Admin-Token`**（或 Query `token`）：用户 CRUD、签到配置、注册策略与邀请码管理。

允许的 CORS 自定义头包含：`Authorization`、`X-Admin-Token`、`X-Visit-Ip`、`X-Visit-Location`、`X-Auth-Client`、`X-Auth-Client-Name` 等。

## 本地开发命令

```bash
cd sproutgate-backend
go mod tidy
go run .
```

默认监听 `:8080`。前端开发时请将 `VITE_API_BASE` 指向本服务（详见仓库根目录下 `sproutgate-frontend/前端文档.md`）。

## 安全提示

- 勿将生产 `DB_DSN`、SMTP 密码、真实 `admin` 令牌提交到版本库。
- 旧版 `data/config/email.json` 等若含真实口令，迁移后应以环境或运维密钥管理为准，并限制数据库与 SMTP 账号权限。