feat(M5): 前端完善 + 部署 — Vue3 全量页面、仪表盘统计与我的审计接口、systemd/sudoers/迁移脚本、部署文档

docs/API.md

@@ -0,0 +1,85 @@
+# API 文档（RESTful v1）
+
+统一前缀 `/api/v1`；会话基于 cookie（HttpOnly/Secure/SameSite，`withCredentials`）。
+成功响应 `{"data": ...}`；失败响应 `{"error": "..."}`，HTTP 状态码语义化
+（400 参数/401 未登录/403 无权限/404 不存在/409 冲突/429 限速/500 内部）。
+
+权限：`-` 公开，`admin` 管理员会话，`user` 外部用户会话。
+
+## 认证 /auth
+
+| 方法 | 路径 | 说明 | 权限 |
+|---|---|---|---|
+| GET | `/auth/captcha` | 图形验证码 `{captcha_id, image}`（base64 PNG data URI） | - |
+| POST | `/auth/otp/send` | 外部用户：用户名+图形验证码 → 发 OTP 邮件（60s 冷却）。body: `{username, captcha_id, captcha_code}` | - |
+| POST | `/auth/otp/login` | `{username, code}` → 建 cookie 会话 | - |
+| POST | `/auth/admin/login` | `{username, password}` → 建 cookie 会话 | - |
+| POST | `/auth/admin/forgot` | `{username}` → 发密码重置邮件（不存在也返回成功，防枚举） | - |
+| POST | `/auth/admin/reset` | `{token, new_password}` → 重置密码 | - |
+| POST | `/auth/logout` | 登出（删会话 + 清 cookie） | admin/user |
+| GET | `/auth/me` | 当前主体 `{user_type, id, username, email}` | admin/user |
+
+## 用户 /users（admin）
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/users?page=&page_size=&status=&supervisor=` | 列表（分页 `{total, items}`） |
+| POST | `/users` | 创建。body: `{username(不含ext_), email, supervisor, purpose, ttl_days(0=默认)}` → `{id, username, status, expire_at}` |
+| GET | `/users/:id` | 详情 |
+| PATCH | `/users/:id` | 更新（可空字段省略）。body: `{email?, supervisor?, purpose?}` |
+| POST | `/users/:id/disable` | 禁用（清空 authorized_keys，SSH 立即失效） |
+| POST | `/users/:id/enable` | 启用（按 DB 密钥恢复） |
+| POST | `/users/:id/extend` | 延期。body: `{days(0=默认)}` → `{expire_at}`；已过期在回收期内可恢复 |
+| DELETE | `/users/:id` | 删除并回收（系统账号+家目录+密钥，保留审计） |
+| GET | `/users/:id/keys` | 用户密钥列表 |
+
+## 我的 /me（user）
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/me/keys` | 我的密钥列表 |
+| POST | `/me/keys` | 上传公钥 `{name, public_key}`（格式/重复校验 + 同步 authorized_keys） |
+| PATCH | `/me/keys/:id` | 重命名 `{name}` |
+| DELETE | `/me/keys/:id` | 吊销（立即失效） |
+| GET | `/me/audit?page=&page_size=` | 我的审计痕迹（本人为操作者或对象） |
+
+## 申请审批 /approvals
+
+| 方法 | 路径 | 说明 | 权限 |
+|---|---|---|---|
+| POST | `/approvals` | 提交申请 `{username, email, supervisor, purpose}`（不含 ext_） | - |
+| GET | `/approvals?status=` | 列表（pending/approved/rejected） | admin |
+| POST | `/approvals/:id/review` | 审批 `{approve: bool, reason}`（拒绝必填理由） | admin |
+
+## 审计 /audit（admin）
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/audit?page=&page_size=&actor=&action=&resource_type=&resource_id=&since=&until=` | 查询（since/until 为 RFC3339） |
+| GET | `/audit/export?since=&until=` | CSV 导出（UTF-8 BOM，`Content-Disposition` 下载） |
+
+## 系统设置 /settings（admin）
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/settings` | 全部设置项 `{items: [{key, value, overridden}]}`（config 默认 + settings 覆盖） |
+| PUT | `/settings` | 更新 `{key, value}`（白名单 key：`policy.default_ttl` / `policy.recycle_period` / `policy.audit_retention`，值为时长） |
+
+## 仪表盘 /admin（admin）
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/admin/stats` | `{total, active, disabled, expired, expiring_soon[], pending_approvals}`（近 30 天待过期） |
+
+## 其他
+
+| 方法 | 路径 | 说明 | 权限 |
+|---|---|---|---|
+| GET | `/healthz` | 健康检查 `{status, version, uptime, go, timestamp}` | - |
+
+## 审计动作一览
+
+`auth.admin_login`、`auth.otp_send`、`auth.otp_login`、`auth.logout`、
+`user.create/update/disable/enable/extend/delete`、`key.create/rename/revoke`、
+`approval.submit/review`、`lifecycle.expire`（到期锁定）、`lifecycle.recycle`（回收删除）。
+`detail` 为 JSON 字符串；`result` ∈ `success|failed`。