SproutGate/sproutgate-backend/API_DOCS.md

# 萌芽账户认证中心 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` 中；如果文件不存在，后端启动时会自动生成并写入该文件。
请求时可使用以下任一方式携带：
- Query：`?token=<admin-token>`
- Header：`X-Admin-Token: <admin-token>`
- 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>'
```