update: 2026-03-28 21:00

README.md

@@ -1,36 +1,89 @@
 # SproutGate（萌芽账户认证中心）
 
-前后端分离的统一账户与轻量用户中心：注册登录、邮箱验证、找回密码、副邮箱、签到与资料管理；管理员可维护用户与签到配置。数据以 JSON 文件落盘，适合自建与小规模部署。
+前后端分离的统一账户与轻量用户中心：注册登录、邮箱验证、找回密码、副邮箱、签到与资料管理；管理员可维护用户、签到与注册/邀请码策略。数据以 **JSON 文件落盘**（无传统数据库），适合自建与小规模部署。第三方站点（如万象口袋）通过 **OAuth 式查询参数** 与 **JWT / 校验接口** 接入，详见 [`sproutgate-backend/API_DOCS.md`](./sproutgate-backend/API_DOCS.md)。
 
-## 架构一览
+---
+
+## 架构总览
+
+```mermaid
+flowchart LR
+  subgraph client [浏览器]
+    FE[React + Vite SPA]
+  end
+  subgraph api [sproutgate-backend]
+    Gin[Gin HTTP]
+    H[handlers]
+    S[storage JSON]
+    J[auth JWT]
+    Gin --> H --> S
+    H --> J
+  end
+  FE -->|HTTPS /api| Gin
+  S --> FS[(data/config + data/users)]
+```
 
 | 部分 | 技术栈 | 目录 | 说明 |
 |------|--------|------|------|
-| 前端 | React 18 + Vite 5 | [`sproutgate-frontend/`](./sproutgate-frontend/) | 用户门户、公开用户页、管理后台；`VITE_API_BASE` 指向后端 |
+| 前端 | React 18 + Vite 5 | [`sproutgate-frontend/`](./sproutgate-frontend/) | 无 `react-router`；由 [`App.jsx`](./sproutgate-frontend/src/App.jsx) 按 `pathname` 切换视图；`VITE_API_BASE` 指向后端 |
-| 后端 | Go + Gin | [`sproutgate-backend/`](./sproutgate-backend/) | REST API、JWT、CORS；默认端口 `8080` |
+| 后端 | Go 1.20 + Gin | [`sproutgate-backend/`](./sproutgate-backend/) | 单体 REST；默认端口 `8080`；CORS 放行常用头（含 `Authorization`、`X-Admin-Token`、`X-Auth-Client*`） |
-| 数据 | JSON 文件 | [`sproutgate-backend/data/`](./sproutgate-backend/data/) | `config/`（管理员、认证、邮件等）、`users/`（用户记录） |
+| 数据 | JSON 文件 | [`sproutgate-backend/data/`](./sproutgate-backend/data/) | `config/`（`admin.json`、`auth.json` 含 JWT 密钥、`email.json`、`checkin.json`、`registration.json` 等）、`users/`（用户记录） |
 
-### 前端路由与模块
+---
 
-- **`/`** — [`UserPortal`](./sproutgate-frontend/src/components/UserPortal.jsx)：登录、注册、验证邮件、OAuth 式 `redirect_uri` 回跳等流程。
+## 后端代码结构（`sproutgate-backend/`）
-- **`/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)。
+| 包 / 目录 | 职责 |
+|-----------|------|
+| [`main.go`](./sproutgate-backend/main.go) | 初始化 [`storage.Store`](./sproutgate-backend/internal/storage/storage.go)、注册路由、监听 `PORT` |
+| [`internal/handlers/`](./sproutgate-backend/internal/handlers/) | HTTP 处理：`auth_login`、`auth_password`、`profile`、`checkin`、`admin`、`public_registration`、`registration_admin`、`secondary_email`、`auth_client` 等；[`handler.go`](./sproutgate-backend/internal/handlers/handler.go) 聚合依赖 |
+| [`internal/storage/`](./sproutgate-backend/internal/storage/storage.go) | 数据目录布局、读写 JSON、待验证/重置令牌等 |
+| [`internal/models/`](./sproutgate-backend/internal/models/) | `User`、`Activity`、待审核、副邮箱、接入方元数据等结构体 |
+| [`internal/auth/jwt.go`](./sproutgate-backend/internal/auth/jwt.go) | JWT 签发与解析（HS256） |
+| [`internal/email/mailer.go`](./sproutgate-backend/internal/email/mailer.go) | SMTP 发信（配置来自 `data/config/email.json`） |
+| [`internal/clientgeo/`](./sproutgate-backend/internal/clientgeo/clientgeo.go) | 与访问来源等辅助逻辑配合（请求头见 `main.go` CORS） |
 
-### 后端能力摘要
+**API 前缀（与 [`main.go`](./sproutgate-backend/main.go) 一致）**
 
-- **认证**：登录、注册、邮箱验证、忘记/重置密码、副邮箱申请与验证、JWT 校验、`/api/auth/me`、签到、资料更新。
+| 前缀 | 说明 |
-- **公开接口**：按账号获取公开用户信息；`GET /api/public/registration-policy` 查询是否强制邀请码注册。
+|------|------|
-- **管理接口**：`/api/admin/*`（需 `X-Admin-Token`），用户管理、签到与**注册策略/邀请码**（`data/config/registration.json`）。
+| `/api/auth/*` | 登录、注册、邮箱验证、忘记/重置密码、副邮箱、`POST /verify`、`GET /me`、签到、`PUT /profile`；可带 `X-Auth-Client` / `X-Auth-Client-Name` 记录第三方应用 |
-- **运维**：`GET /` 与 `GET /api`（JSON 服务说明）、`GET /api/health`、`GET /api/docs`（返回 [`API_DOCS.md`](./sproutgate-backend/API_DOCS.md)）。
+| `/api/public/*` | 公开用户资料、注册策略（是否强制邀请码等） |
+| `/api/admin/*` | 需 [`AdminMiddleware`](./sproutgate-backend/internal/handlers/admin.go)：请求头 `X-Admin-Token` 或 Query `token`，与用户 JWT 分离 |
 
-完整契约见 [`sproutgate-backend/API_DOCS.md`](./sproutgate-backend/API_DOCS.md)（文内 **「统一登录前端：查询参数」**、**「回跳 URL」**、**`POST /api/auth/login` / `verify` / `me`** 等章节为第三方接入主参考）。
+**运维与文档**：`GET /`、`GET /api`（JSON 服务说明）、`GET /api/health`、`GET /api/docs`（返回仓库内 `API_DOCS.md`）。
+
+---
+
+## 前端代码结构（`sproutgate-frontend/`）
+
+| 路径 | 说明 |
+|------|------|
+| [`src/App.jsx`](./sproutgate-frontend/src/App.jsx) | 根组件：根据路径渲染门户 / 公开用户页 / 管理端；顶栏 **连点 Logo** 进入管理员流程 |
+| [`src/config.js`](./sproutgate-frontend/src/config.js) | `VITE_API_BASE`、开发与生产默认 API 地址 |
+| [`src/components/UserPortal.jsx`](./sproutgate-frontend/src/components/UserPortal.jsx) | `/`：登录、注册、邮件验证、`redirect_uri` 统一登录回跳等 |
+| [`src/components/PublicUserPage.jsx`](./sproutgate-frontend/src/components/PublicUserPage.jsx) | `/user`、`/user/:account`：公开资料 |
+| [`src/components/AdminPanel.jsx`](./sproutgate-frontend/src/components/AdminPanel.jsx) | `/admin`：用户与签到、注册策略管理 |
+
+---
+
+## 认证与安全（摘要）
+
+1. **用户会话**：登录成功后签发 JWT（`Authorization: Bearer`）；受保护接口解析 JWT 后按 `account` 加载用户；封禁等状态见 handlers 内校验。
+2. **令牌校验**：`POST /api/auth/verify` 供第三方后端校验用户 token（见 API 文档）。
+3. **管理员**：与业务 JWT 独立，使用 **`X-Admin-Token`**（或 Query `token`）与 `data/config/admin.json` 比对。
+4. **第三方统一登录门户**：入口 URL 查询参数 `redirect_uri`、`client_id`、`client_name` 等；前端通过 `sessionStorage` 与请求头 **`X-Auth-Client`** / **`X-Auth-Client-Name`** 与后端协同（CORS 已允许上述头）。
+
+部署到公网前：**修改默认 JWT 密钥、管理员 Token、SMTP 密码**，且勿将含真实密钥的 `data/config` 提交到公开仓库。
+
+---
 
 ## 环境要求
 
-- **后端**：Go 1.21+（以 `go.mod` 为准）
+- **后端**：Go **1.20+**（以 [`sproutgate-backend/go.mod`](./sproutgate-backend/go.mod) 为准）
-- **前端**：Node.js 18+（建议 LTS）
+- **前端**：Node.js **18+**（建议 LTS）
+
+---
 
 ## 快速开始
 
@@ -49,7 +102,7 @@ chmod +x sproutgate.sh
 ./sproutgate.sh dev
 ```
 
-会启动后端 `go run .` 与前端 `npm run dev`（前端默认 `5173`，后端默认 `8080`）。
+会启动后端 `go run .` 与前端 `npm run dev`（前端默认 **5173**，后端默认 **8080**）。
 
 仅构建前端：
 
@@ -87,7 +140,7 @@ npm run dev
 VITE_API_BASE=http://localhost:8080
 ```
 
-生产环境改为实际 API 地址即可。
+生产环境改为实际 API 地址（如 `https://auth.api.example.com`）。
 
 ### 配置与安全
 
@@ -96,24 +149,33 @@ VITE_API_BASE=http://localhost:8080
 
 ### 可选：Docker 仅跑后端 API
 
-在 `sproutgate-backend` 目录：
+在 [`sproutgate-backend`](./sproutgate-backend) 目录：
 
 ```bash
 docker compose up -d --build
 ```
 
-默认将容器内 `8080` 映射到主机 `28080`（可通过环境变量 `AUTH_API_PORT` 修改）。数据目录通过卷挂载到 `./data`。
+默认将容器内 `8080` 映射到主机 **`28080`**（可通过环境变量 **`AUTH_API_PORT`** 修改）。数据目录通过卷挂载到 **`./data`**。
+
+---
 
 ## 环境变量（后端）
 
 | 变量 | 说明 |
 |------|------|
 | `PORT` | 监听端口，默认 `8080` |
-| `DATA_DIR` | 数据根目录；不设置时使用仓库内默认 `data` 布局 |
+| `DATA_DIR` | 数据根目录；不设置时使用仓库内相对路径下的 `data` 布局 |
 
-## 仓库维护说明
+---
 
-更细的目录约定、代码风格与 PR 建议见 **[`AGENTS.md`](./AGENTS.md)**。
+## 相关文档
+
+| 文档 | 内容 |
+|------|------|
+| [`sproutgate-backend/API_DOCS.md`](./sproutgate-backend/API_DOCS.md) | HTTP 接口契约（第三方接入主参考） |
+| [`AGENTS.md`](./AGENTS.md) | 目录约定、协作与 PR 建议 |
+
+---
 
 ## 许可证
 

sproutgate-backend/main.go

@@ -17,7 +17,7 @@ func main() {
 	dataDir := os.Getenv("DATA_DIR")
 	store, err := storage.NewStore(dataDir)
 	if err != nil {
-		log.Fatalf("failed to init storage: %v", err)
+		log.Fatalf("初始化储存失败: %v", err)
 	}
 
 	router := gin.Default()