完善初始化更新

README.md

@@ -1,40 +1,120 @@
-# 萌芽账户认证中心（SproutGate）
+# SproutGate（萌芽账户认证中心）
 
-前后端分离的统一账户认证中心：
-- 前端：React（`sproutgate-frontend`）
-- 后端：Golang + Gin（`sproutgate-backend`）
-- 数据：`data/` 与子目录 JSON 文件存储
+前后端分离的统一账户与轻量用户中心：注册登录、邮箱验证、找回密码、副邮箱、签到与资料管理；管理员可维护用户与签到配置。数据以 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 .
 ```
 
-默认端口 `8080`，默认管理员 Token：`shumengya520`（位于 `sproutgate-backend/data/config/admin.json`）。
-邮件发送配置位于 `sproutgate-backend/data/config/email.json`。
+**前端**
 
-### 前端
 ```bash
 cd sproutgate-frontend
 npm install
 npm run dev
 ```
 
-如需自定义后端地址，新增 `sproutgate-frontend/.env`：
-```
+### 前端连接后端
+
+在 `sproutgate-frontend/.env`（自行创建）中设置：
+
+```env
 VITE_API_BASE=http://localhost:8080
 ```
 
-### 管理员地址
-```
-http://localhost:5173/admin?token=shumengya520
+生产环境改为实际 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
 ```
 
-## API 文档
+默认将容器内 `8080` 映射到主机 `28080`（可通过环境变量 `AUTH_API_PORT` 修改）。数据目录通过卷挂载到 `./data`。
 
-- 文件：`sproutgate-backend/API_DOCS.md`
-- 在线：`GET /api/docs`
+## 环境变量（后端）
+
+| 变量 | 说明 |
+|------|------|
+| `PORT` | 监听端口，默认 `8080` |
+| `DATA_DIR` | 数据根目录；不设置时使用仓库内默认 `data` 布局 |
+
+## 仓库维护说明
+
+更细的目录约定、代码风格与 PR 建议见 **[`AGENTS.md`](./AGENTS.md)**。
+
+## 许可证
+
+若仓库未包含 `LICENSE` 文件，使用前请与维护者确认授权方式。