# SproutGate（萌芽账户认证中心）

前后端分离的统一账户与轻量用户中心：注册登录、邮箱验证、找回密码、副邮箱、签到与资料管理；管理员可维护用户与签到配置。数据以 JSON 文件落盘，适合自建与小规模部署。

## 架构一览

| 部分 | 技术栈 | 目录 | 说明 |
|------|--------|------|------|
| 前端 | React 18 + Vite 5 | [`sproutgate-frontend/`](./sproutgate-frontend/) | 用户门户、公开用户页、管理后台；`VITE_API_BASE` 指向后端 |
| 后端 | Go + Gin | [`sproutgate-backend/`](./sproutgate-backend/) | REST API、JWT、CORS；默认端口 `8080` |
| 数据 | JSON 文件 | [`sproutgate-backend/data/`](./sproutgate-backend/data/) | `config/`（管理员、认证、邮件等）、`users/`（用户记录） |

### 前端路由与模块

- **`/`** — [`UserPortal`](./sproutgate-frontend/src/components/UserPortal.jsx)：登录、注册、验证邮件、OAuth 式 `redirect_uri` 回跳等流程。
- **`/user` / `/user/:account`** — [`PublicUserPage`](./sproutgate-frontend/src/components/PublicUserPage.jsx)：公开资料展示（Markdown 等）。
- **`/admin`** — [`AdminPanel`](./sproutgate-frontend/src/components/AdminPanel.jsx)：用户 CRUD、签到配置；请求头携带管理员 Token（见下文配置）。

启动页与全局壳层见 [`App.jsx`](./sproutgate-frontend/src/App.jsx)、[`SplashScreen`](./sproutgate-frontend/src/components/SplashScreen.jsx)。

### 后端能力摘要

- **认证**：登录、注册、邮箱验证、忘记/重置密码、副邮箱申请与验证、JWT 校验、`/api/auth/me`、签到、资料更新。
- **公开接口**：按账号获取公开用户信息；`GET /api/public/registration-policy` 查询是否强制邀请码注册。
- **管理接口**：`/api/admin/*`（需 `X-Admin-Token`），用户管理、签到与**注册策略/邀请码**（`data/config/registration.json`）。
- **运维**：`GET /` 与 `GET /api`（JSON 服务说明）、`GET /api/health`、`GET /api/docs`（返回 [`API_DOCS.md`](./sproutgate-backend/API_DOCS.md)）。

完整契约见 [`sproutgate-backend/API_DOCS.md`](./sproutgate-backend/API_DOCS.md)（文内 **「统一登录前端：查询参数」**、**「回跳 URL」**、**`POST /api/auth/login` / `verify` / `me`** 等章节为第三方接入主参考）。

## 环境要求

- **后端**：Go 1.21+（以 `go.mod` 为准）
- **前端**：Node.js 18+（建议 LTS）

## 快速开始

### 方式一：根目录脚本（推荐本地开发）

**Windows**

```bat
sproutgate.bat dev
```

**macOS / Linux**

```bash
chmod +x sproutgate.sh
./sproutgate.sh dev
```

会启动后端 `go run .` 与前端 `npm run dev`（前端默认 `5173`，后端默认 `8080`）。

仅构建前端：

```bat
sproutgate.bat build
```

```bash
./sproutgate.sh build
```

### 方式二：手动分别启动

**后端**

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

**前端**

```bash
cd sproutgate-frontend
npm install
npm run dev
```

### 前端连接后端

在 `sproutgate-frontend/.env`（自行创建）中设置：

```env
VITE_API_BASE=http://localhost:8080
```

生产环境改为实际 API 地址即可。

### 配置与安全

- 管理员 Token、JWT 密钥、邮件 SMTP 等位于 **`sproutgate-backend/data/config/`**（如 `admin.json`、`auth.json`、`email.json`）。**部署到公网前请务必修改默认值，且不要将真实密钥提交到仓库。**
- 进入管理员后台：在任意页面顶栏 **连续点击 Logo 五次**（约 2.6 秒内），在弹窗中输入与 `admin.json` 一致的 Token；也可直接使用 `http://localhost:5173/admin?token=<Token>`（Token 会写入本地后再请求接口）。

### 可选：Docker 仅跑后端 API

在 `sproutgate-backend` 目录：

```bash
docker compose up -d --build
```

默认将容器内 `8080` 映射到主机 `28080`（可通过环境变量 `AUTH_API_PORT` 修改）。数据目录通过卷挂载到 `./data`。

## 环境变量（后端）

| 变量 | 说明 |
|------|------|
| `PORT` | 监听端口，默认 `8080` |
| `DATA_DIR` | 数据根目录；不设置时使用仓库内默认 `data` 布局 |

## 仓库维护说明

更细的目录约定、代码风格与 PR 建议见 **[`AGENTS.md`](./AGENTS.md)**。

## 许可证

若仓库未包含 `LICENSE` 文件，使用前请与维护者确认授权方式。