docs: project docs, scripts, deployment configs, and evidence

2026-04-02 11:22:17 +08:00
parent 4718980ab5
commit bbeeb63dfa
396 changed files with 165018 additions and 0 deletions
--- a/docs/API.md
+++ b/docs/API.md
@@ -0,0 +1,232 @@
+# 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 是否可用取决于配置是否填写真实凭据