mengyastore/sproutgate-API_DOCS.md

# 萌芽账户认证中心 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>'
```