user-system/docs/API.md

API Contract

更新时间：2026-04-01

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

1. 基本约定

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

{
  "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 列表接口

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

4.2 登录成功

{
  "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 是否可用取决于配置是否填写真实凭据