4.6 KiB
4.6 KiB
萌芽账户认证中心 API 文档
基础地址：http://<host>:8080
认证与统一登录
登录获取统一令牌
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", "...": "..." }
}
说明：密码不会返回。
更新当前用户资料
PUT /api/auth/profile
请求头：
Authorization: Bearer <jwt-token>
请求（字段可选）：
{
"password": "newpass",
"username": "新昵称",
"phone": "13800000000",
"avatarUrl": "https://example.com/avatar.png",
"bio": "### 新简介"
}
响应：
{
"user": { "account": "demo", "...": "..." }
}
注册账号（发送邮箱验证码）
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> - 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>'