chore: sync

sproutgate-backend/API_DOCS.md

@@ -0,0 +1,296 @@
+# 萌芽账户认证中心 API 文档
+
+基础地址：`http://<host>:8080`
+
+## 认证与统一登录
+
+### 登录获取统一令牌
+`POST /api/auth/login`
+
+请求：
+```json
+{
+  "account": "demo",
+  "password": "demo123"
+}
+```
+
+响应：
+```json
+{
+  "token": "jwt-token",
+  "expiresAt": "2026-03-14T12:00:00Z",
+  "user": {
+    "account": "demo",
+    "username": "示例用户",
+    "email": "demo@example.com",
+    "level": 0,
+    "sproutCoins": 10,
+    "secondaryEmails": ["demo2@example.com"],
+    "phone": "13800000000",
+    "avatarUrl": "https://example.com/avatar.png",
+    "bio": "### 简介",
+    "createdAt": "2026-03-14T12:00:00Z",
+    "updatedAt": "2026-03-14T12:00:00Z"
+  }
+}
+```
+
+### 校验令牌
+`POST /api/auth/verify`
+
+请求：
+```json
+{
+  "token": "jwt-token"
+}
+```
+
+响应：
+```json
+{
+  "valid": true,
+  "user": { "account": "demo", "...": "..." }
+}
+```
+
+### 获取当前用户信息
+`GET /api/auth/me`
+
+请求头：
+`Authorization: Bearer <jwt-token>`
+
+响应：
+```json
+{
+  "user": { "account": "demo", "...": "..." }
+}
+```
+
+> 说明：密码不会返回。
+
+### 更新当前用户资料
+`PUT /api/auth/profile`
+
+请求头：
+`Authorization: Bearer <jwt-token>`
+
+请求（字段可选）：
+```json
+{
+  "password": "newpass",
+  "username": "新昵称",
+  "phone": "13800000000",
+  "avatarUrl": "https://example.com/avatar.png",
+  "bio": "### 新简介"
+}
+```
+
+响应：
+```json
+{
+  "user": { "account": "demo", "...": "..." }
+}
+```
+
+### 注册账号（发送邮箱验证码）
+`POST /api/auth/register`
+
+请求：
+```json
+{
+  "account": "demo",
+  "password": "demo123",
+  "username": "示例用户",
+  "email": "demo@example.com"
+}
+```
+
+响应：
+```json
+{
+  "sent": true,
+  "expiresAt": "2026-03-14T12:10:00Z"
+}
+```
+
+### 验证邮箱并完成注册
+`POST /api/auth/verify-email`
+
+请求：
+```json
+{
+  "account": "demo",
+  "code": "123456"
+}
+```
+
+响应：
+```json
+{
+  "created": true,
+  "user": { "account": "demo", "...": "..." }
+}
+```
+
+### 忘记密码（发送重置验证码）
+`POST /api/auth/forgot-password`
+
+请求：
+```json
+{
+  "account": "demo",
+  "email": "demo@example.com"
+}
+```
+
+响应：
+```json
+{
+  "sent": true,
+  "expiresAt": "2026-03-14T12:10:00Z"
+}
+```
+
+### 重置密码
+`POST /api/auth/reset-password`
+
+请求：
+```json
+{
+  "account": "demo",
+  "code": "123456",
+  "newPassword": "newpass"
+}
+```
+
+响应：
+```json
+{ "reset": true }
+```
+
+### 申请添加辅助邮箱（发送验证码）
+`POST /api/auth/secondary-email/request`
+
+请求头：
+`Authorization: Bearer <jwt-token>`
+
+请求：
+```json
+{
+  "email": "demo2@example.com"
+}
+```
+
+响应：
+```json
+{
+  "sent": true,
+  "expiresAt": "2026-03-14T12:10:00Z"
+}
+```
+
+### 验证辅助邮箱
+`POST /api/auth/secondary-email/verify`
+
+请求头：
+`Authorization: Bearer <jwt-token>`
+
+请求：
+```json
+{
+  "email": "demo2@example.com",
+  "code": "123456"
+}
+```
+
+响应：
+```json
+{
+  "verified": true,
+  "user": { "account": "demo", "...": "..." }
+}
+```
+
+## 管理端接口（需要管理员 Token）
+
+管理员 Token 存放在 `data/config/admin.json` 中，默认值为 `shumengya520`。
+请求时可使用以下任一方式携带：
+- Query：`?token=shumengya520`
+- Header：`X-Admin-Token: shumengya520`
+- Header：`Authorization: Bearer shumengya520`
+
+### 获取用户列表
+`GET /api/admin/users`
+
+响应：
+```json
+{
+  "total": 1,
+  "users": [{ "account": "demo", "...": "..." }]
+}
+```
+
+### 新建用户
+`POST /api/admin/users`
+
+请求：
+```json
+{
+  "account": "demo",
+  "password": "demo123",
+  "username": "示例用户",
+  "email": "demo@example.com",
+  "level": 0,
+  "sproutCoins": 10,
+  "secondaryEmails": ["demo2@example.com"],
+  "phone": "13800000000",
+  "avatarUrl": "https://example.com/avatar.png",
+  "bio": "### 简介"
+}
+```
+
+### 更新用户
+`PUT /api/admin/users/{account}`
+
+请求（字段可选）：
+```json
+{
+  "password": "newpass",
+  "username": "新昵称",
+  "level": 1,
+  "secondaryEmails": ["demo2@example.com"],
+  "sproutCoins": 99
+}
+```
+
+### 删除用户
+`DELETE /api/admin/users/{account}`
+
+响应：
+```json
+{ "deleted": true }
+```
+
+## 数据存储说明
+
+- 用户数据：`data/users/*.json`
+- 注册待验证：`data/pending/*.json`
+- 密码重置记录：`data/reset/*.json`
+- 辅助邮箱验证：`data/secondary/*.json`
+- 管理员 Token：`data/config/admin.json`
+- JWT 配置：`data/config/auth.json`
+- 邮件配置：`data/config/email.json`
+
+## 快速联调用示例
+
+```bash
+# 登录
+curl -X POST http://localhost:8080/api/auth/login \
+  -H 'Content-Type: application/json' \
+  -d '{"account":"demo","password":"demo123"}'
+
+# 使用令牌获取用户信息
+curl http://localhost:8080/api/auth/me \
+  -H 'Authorization: Bearer <jwt-token>'
+```