user-system/docs/API.md

# API Contract

更新时间：2026-04-01

本文档只描述当前仓库里真实存在、且在 `cmd/server/main.go` 中实际接线的接口。

## 1. 基本约定

- 基础路径：`/api/v1`
- 认证方式：`Authorization: Bearer <access_token>`
- 当前实现不支持通过 query string 传递 token
- 统一响应：

```json
{
  "code": 0,
  "message": "success",
  "data": {}
}
```

- 基础设施接口不走统一响应：
  - `GET /health`
  - `GET /health/live`
  - `GET /health/ready`
  - `GET /metrics`
  - `GET /swagger/*any`

## 2. 当前公开接口

### 2.1 认证

- `POST /api/v1/auth/register`
  - 当请求体包含 `phone` 时，当前实现要求同时提供 `phone_code`
- `POST /api/v1/auth/bootstrap-admin`
- `POST /api/v1/auth/login`
- `POST /api/v1/auth/refresh`
- `GET /api/v1/auth/capabilities`
- `GET /api/v1/auth/activate`
- `POST /api/v1/auth/resend-activation`
- `POST /api/v1/auth/send-email-code`
- `POST /api/v1/auth/login/email-code`
- `POST /api/v1/auth/send-code`
- `POST /api/v1/auth/login/code`
- `GET /api/v1/auth/csrf-token`
- `GET /api/v1/auth/oauth/providers`
- `GET /api/v1/auth/oauth/:provider`
- `GET /api/v1/auth/oauth/:provider/callback`

说明：

- `/api/v1/auth/*` 当前会统一返回 `Cache-Control: no-store` 等防缓存头。

### 2.2 密码重置

- `POST /api/v1/auth/forgot-password`
- `GET /api/v1/auth/reset-password`
- `POST /api/v1/auth/reset-password`

### 2.3 验证码

- `GET /api/v1/auth/captcha`
- `GET /api/v1/auth/captcha/image`
- `POST /api/v1/auth/captcha/verify`

## 3. 当前受保护接口

### 3.1 认证与当前用户

- `POST /api/v1/auth/logout`
- `GET /api/v1/auth/userinfo`
- `GET /api/v1/auth/2fa/status`
- `GET /api/v1/auth/2fa/setup`
- `POST /api/v1/auth/2fa/enable`
- `POST /api/v1/auth/2fa/disable`
- `POST /api/v1/auth/2fa/verify`
- `GET /api/v1/users/me/social-accounts`
- `POST /api/v1/users/me/bind-social`
- `DELETE /api/v1/users/me/bind-social/:provider`

### 3.2 用户

- `GET /api/v1/users`
  - 当前要求管理员
  - 支持 `page`、`page_size`、`keyword`
  - 支持 `status=0|1|2|3`
  - 支持高级筛选：`role_ids`、`created_from`、`created_to`、`sort_by`、`sort_order`
- `GET /api/v1/users/:id`
  - 当前要求本人或管理员
- `PUT /api/v1/users/:id`
  - 当前要求本人或管理员
- `DELETE /api/v1/users/:id`
  - 当前要求权限 `user:delete`
- `PUT /api/v1/users/:id/password`
  - 当前只允许本人
- `PUT /api/v1/users/:id/status`
  - 当前要求权限 `user:manage`
- `GET /api/v1/users/:id/roles`
  - 当前要求本人或管理员
- `PUT /api/v1/users/:id/roles`
  - 当前要求权限 `user:manage`
- `POST /api/v1/users/:id/avatar`

### 3.3 角色与权限

以下接口全部要求管理员：

- `POST /api/v1/roles`
- `GET /api/v1/roles`
- `GET /api/v1/roles/:id`
- `PUT /api/v1/roles/:id`
- `DELETE /api/v1/roles/:id`
- `PUT /api/v1/roles/:id/status`
- `GET /api/v1/roles/:id/permissions`
- `PUT /api/v1/roles/:id/permissions`
- `POST /api/v1/permissions`
- `GET /api/v1/permissions`
- `GET /api/v1/permissions/tree`
- `GET /api/v1/permissions/:id`
- `PUT /api/v1/permissions/:id`
- `DELETE /api/v1/permissions/:id`
- `PUT /api/v1/permissions/:id/status`

### 3.4 设备

- `GET /api/v1/devices`
- `POST /api/v1/devices`
- `GET /api/v1/devices/:id`
- `PUT /api/v1/devices/:id`
- `DELETE /api/v1/devices/:id`
- `PUT /api/v1/devices/:id/status`
- `POST /api/v1/devices/:id/trust`
  - 设置设备信任状态，跳过2FA
  - 请求体: `{ "trust_duration": "30d" }` (可选，默认永久)
- `DELETE /api/v1/devices/:id/trust`
  - 取消设备信任状态
- `POST /api/v1/devices/by-device-id/:deviceId/trust`
  - 通过设备标识字符串设置信任状态
  - 请求体: `{ "trust_duration": "30d" }` (可选，默认永久)
- `GET /api/v1/devices/me/trusted`
  - 获取当前用户的信任设备列表
- `POST /api/v1/devices/me/logout-others`
  - 登出所有其他设备
  - 请求头: `X-Device-ID: <current_device_id>`
- `GET /api/v1/devices/users/:id`

### 3.5 日志

- `GET /api/v1/logs/login/me`
- `GET /api/v1/logs/operation/me`
- `GET /api/v1/logs/login`
  - 当前要求管理员
- `GET /api/v1/logs/operation`
  - 当前要求管理员

### 3.6 2FA / TOTP

- `GET /api/v1/auth/2fa/status`
- `GET /api/v1/auth/2fa/setup`
- `POST /api/v1/auth/2fa/enable`
- `POST /api/v1/auth/2fa/disable`
- `POST /api/v1/auth/2fa/verify`
  - 请求体: `{ "code": "123456", "device_id": "xxx" }` (device_id 可选)
  - 若设备已信任且未过期，跳过TOTP验证

### 3.7 Webhook

- `POST /api/v1/webhooks`
- `GET /api/v1/webhooks`
- `PUT /api/v1/webhooks/:id`
- `DELETE /api/v1/webhooks/:id`
- `GET /api/v1/webhooks/:id/deliveries`

### 3.8 管理员扩展接口

- `GET /api/v1/admin/users/export`
  - 支持 `format=csv|xlsx`
  - 支持 `fields=username,email,...`
  - 支持基础导出筛选：`keyword`、`status`
- `POST /api/v1/admin/users/import`
  - 当前支持上传 `.csv` 或 `.xlsx`
- `GET /api/v1/admin/users/import/template`
  - 支持 `format=csv|xlsx`
- `GET /api/v1/admin/stats/dashboard`
- `GET /api/v1/admin/stats/users`

## 4. 当前响应形态

### 4.1 列表接口

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [],
    "total": 0,
    "page": 1,
    "page_size": 20
  }
}
```

### 4.2 登录成功

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "access_token": "token",
    "refresh_token": "refresh-token",
    "expires_in": 7200,
    "user": {
      "id": 1,
      "username": "admin",
      "email": "admin@example.com",
      "phone": "",
      "nickname": "",
      "avatar": "",
      "status": 1
    }
  }
}
```

## 5. 运行时说明

- 当前主密码算法为 `Argon2id`
- 当前主 JWT 算法为 `RS256`
- 当前配置下短信验证码路由已挂载
- OAuth 路由始终存在，具体 provider 是否可用取决于配置是否填写真实凭据