feat: sync project
This commit is contained in:
378
sproutgate-API_DOCS.md
Normal file
378
sproutgate-API_DOCS.md
Normal file
@@ -0,0 +1,378 @@
|
||||
# 萌芽账户认证中心 API 文档
|
||||
|
||||
接入地址：
|
||||
- 统一登录前端：`https://auth.shumengya.top`
|
||||
- 后端 API：`https://auth.api.shumengya.top`
|
||||
- 本地开发 API：`http://<host>:8080`
|
||||
|
||||
对外接入建议：
|
||||
1. 第三方应用按钮跳转到统一登录前端。
|
||||
2. 登录成功后回跳到业务站点。
|
||||
3. 业务站点使用回跳带回的 `token` 调用后端 API。
|
||||
|
||||
示例按钮：
|
||||
```html
|
||||
<a href="https://auth.shumengya.top/?redirect_uri=https%3A%2F%2Fapp.example.com%2Fauth%2Fcallback&state=abc123">
|
||||
使用萌芽统一账户认证登录
|
||||
</a>
|
||||
```
|
||||
|
||||
回跳说明：
|
||||
- 用户已登录时，统一登录前端会提示“继续授权”或“切换账号”。
|
||||
- 登录成功后会回跳到 `redirect_uri`，并在 URL `#fragment` 中带上 `token`、`account`、`username`、`state`。
|
||||
- 第三方应用建议先调用 `GET /api/auth/verify` 或 `GET /api/auth/me` 校验令牌。
|
||||
|
||||
## 认证与统一登录
|
||||
|
||||
### 登录获取统一令牌
|
||||
`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", "...": "..." },
|
||||
"checkIn": {
|
||||
"rewardCoins": 1,
|
||||
"checkedInToday": false,
|
||||
"lastCheckInDate": "",
|
||||
"lastCheckInAt": "",
|
||||
"today": "2026-03-14"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> `user` 还会包含 `lastVisitAt`、`lastVisitDate`、`checkInDays`、`checkInStreak`、`visitDays`、`visitStreak` 等统计字段。
|
||||
|
||||
> 说明：密码不会返回。
|
||||
|
||||
### 每日签到
|
||||
`POST /api/auth/check-in`
|
||||
|
||||
请求头：
|
||||
`Authorization: Bearer <jwt-token>`
|
||||
|
||||
响应：
|
||||
```json
|
||||
{
|
||||
"checkedIn": true,
|
||||
"alreadyCheckedIn": false,
|
||||
"rewardCoins": 1,
|
||||
"awardedCoins": 1,
|
||||
"message": "签到成功",
|
||||
"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", "...": "..." }
|
||||
}
|
||||
```
|
||||
|
||||
## 用户广场
|
||||
|
||||
### 获取用户公开主页
|
||||
`GET /api/public/users/{account}`
|
||||
|
||||
说明：
|
||||
- 仅支持账户名 `account`，不支持昵称查询。
|
||||
- 适合第三方应用展示用户公开资料。
|
||||
|
||||
响应：
|
||||
```json
|
||||
{
|
||||
"user": {
|
||||
"account": "demo",
|
||||
"username": "示例用户",
|
||||
"level": 3,
|
||||
"sproutCoins": 10,
|
||||
"avatarUrl": "https://example.com/avatar.png",
|
||||
"bio": "### 简介"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 注册账号（发送邮箱验证码）
|
||||
`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` 中；如果文件不存在，后端启动时会自动生成并写入该文件。
|
||||
请求时可使用以下任一方式携带：
|
||||
- Query：`?token=<admin-token>`
|
||||
- Header：`X-Admin-Token: <admin-token>`
|
||||
|
||||
### 签到奖励设置
|
||||
`GET /api/admin/check-in/config`
|
||||
|
||||
`PUT /api/admin/check-in/config`
|
||||
|
||||
请求：
|
||||
```json
|
||||
{
|
||||
"rewardCoins": 1
|
||||
}
|
||||
```
|
||||
- Header：`Authorization: Bearer <admin-token>`
|
||||
|
||||
### 获取用户列表
|
||||
`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>'
|
||||
```
|
||||
Reference in New Issue
Block a user