6.5 KiB
萌芽账户认证中心 API 文档
接入地址：
- 统一登录前端：
https://auth.shumengya.top - 后端 API：
https://auth.api.shumengya.top - 本地开发 API：
http://<host>:8080
对外接入建议：
- 第三方应用按钮跳转到统一登录前端。
- 登录成功后回跳到业务站点。
- 业务站点使用回跳带回的
token调用后端 API。
示例按钮：
<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
请求：
{
"account": "demo",
"password": "demo123"
}
响应：
{
"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
请求：
{
"token": "jwt-token"
}
响应：
{
"valid": true,
"user": { "account": "demo", "...": "..." }
}
获取当前用户信息
GET /api/auth/me
请求头：
Authorization: Bearer <jwt-token>
响应：
{
"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>
响应：
{
"checkedIn": true,
"alreadyCheckedIn": false,
"rewardCoins": 1,
"awardedCoins": 1,
"message": "签到成功",
"user": { "account": "demo", "...": "..." }
}
更新当前用户资料
PUT /api/auth/profile
请求头：
Authorization: Bearer <jwt-token>
请求（字段可选）：
{
"password": "newpass",
"username": "新昵称",
"phone": "13800000000",
"avatarUrl": "https://example.com/avatar.png",
"bio": "### 新简介"
}
响应：
{
"user": { "account": "demo", "...": "..." }
}
用户广场
获取用户公开主页
GET /api/public/users/{account}
说明：
- 仅支持账户名
account，不支持昵称查询。 - 适合第三方应用展示用户公开资料。
响应：
{
"user": {
"account": "demo",
"username": "示例用户",
"level": 3,
"sproutCoins": 10,
"avatarUrl": "https://example.com/avatar.png",
"bio": "### 简介"
}
}
注册账号（发送邮箱验证码）
POST /api/auth/register
请求：
{
"account": "demo",
"password": "demo123",
"username": "示例用户",
"email": "demo@example.com"
}
响应：
{
"sent": true,
"expiresAt": "2026-03-14T12:10:00Z"
}
验证邮箱并完成注册
POST /api/auth/verify-email
请求：
{
"account": "demo",
"code": "123456"
}
响应：
{
"created": true,
"user": { "account": "demo", "...": "..." }
}
忘记密码（发送重置验证码）
POST /api/auth/forgot-password
请求：
{
"account": "demo",
"email": "demo@example.com"
}
响应：
{
"sent": true,
"expiresAt": "2026-03-14T12:10:00Z"
}
重置密码
POST /api/auth/reset-password
请求：
{
"account": "demo",
"code": "123456",
"newPassword": "newpass"
}
响应：
{ "reset": true }
申请添加辅助邮箱（发送验证码）
POST /api/auth/secondary-email/request
请求头：
Authorization: Bearer <jwt-token>
请求：
{
"email": "demo2@example.com"
}
响应：
{
"sent": true,
"expiresAt": "2026-03-14T12:10:00Z"
}
验证辅助邮箱
POST /api/auth/secondary-email/verify
请求头：
Authorization: Bearer <jwt-token>
请求：
{
"email": "demo2@example.com",
"code": "123456"
}
响应：
{
"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
请求：
{
"rewardCoins": 1
}
- Header：
Authorization: Bearer <admin-token>
获取用户列表
GET /api/admin/users
响应：
{
"total": 1,
"users": [{ "account": "demo", "...": "..." }]
}
新建用户
POST /api/admin/users
请求：
{
"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}
请求（字段可选）：
{
"password": "newpass",
"username": "新昵称",
"level": 1,
"secondaryEmails": ["demo2@example.com"],
"sproutCoins": 99
}
删除用户
DELETE /api/admin/users/{account}
响应：
{ "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
快速联调用示例
# 登录
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>'