# Base API 接口文档

> 基础路径: `/api/v1` | 认证方式: `Authorization: Bearer <token>`

## 权限说明

| 级别 | 标记 | 说明 |
|------|------|------|
| 公开 | - | 无需登录 |
| 登录 | Auth | 需要有效 JWT |
| 授权 | Authz | 需要登录 + Casbin 角色权限 |

角色层级: `super_admin` > `admin` > `user` > `guest`

---

## 1. 认证 (Auth)

| 方法 | 路径 | 描述 | 权限 |
|------|------|------|------|
| POST | `/register` | 用户注册 | 公开 |
| POST | `/login` | 用户登录 | 公开 |
| POST | `/refresh` | 刷新 Token | 公开 |

## 2. 用户管理 (User)

| 方法 | 路径 | 描述 | 权限 |
|------|------|------|------|
| POST | `/user` | 创建用户 | Authz (admin) |
| GET | `/users` | 获取用户列表 | Authz (admin) |
| GET | `/user/:id` | 获取用户详情 | Authz (admin) |
| PUT | `/user/:id` | 更新用户信息 | Authz (admin) |
| DELETE | `/user/:id` | 删除用户 | Authz (super_admin) |

## 3. 个人中心 (Profile)

| 方法 | 路径 | 描述 | 权限 |
|------|------|------|------|
| GET | `/profile/me` | 获取个人信息 | Authz (user) |
| PUT | `/profile/me` | 更新个人资料 | Authz (user) |
| POST | `/profile/password` | 修改密码 | Authz (user) |
| GET | `/profile/orgs` | 获取我的机构列表 | Authz (user) |
| PUT | `/profile/current-org` | 切换当前机构 | Authz (user) |

## 4. 仪表盘 (Dashboard)

| 方法 | 路径 | 描述 | 权限 |
|------|------|------|------|
| GET | `/dashboard/stats` | 获取仪表盘统计数据 | Authz (guest) |
| GET | `/dashboard/activities` | 获取最近活动列表 | Authz (guest) |

## 5. 文件管理 (File)

| 方法 | 路径 | 描述 | 权限 |
|------|------|------|------|
| POST | `/file/upload` | 上传文件 (multipart/form-data) | Authz (user) |
| GET | `/files` | 获取文件列表 | Authz (user) |
| GET | `/file/:id` | 获取文件详情 | Authz (user) |
| GET | `/file/:id/url` | 获取文件访问 URL | Authz (user) |
| PUT | `/file/:id` | 更新文件信息 | Authz (user) |
| DELETE | `/file/:id` | 删除文件 | Authz (user) |

## 6. 菜单管理 (Menu)

| 方法 | 路径 | 描述 | 权限 |
|------|------|------|------|
| GET | `/menus/current` | 获取当前用户可见菜单 | Auth |
| GET | `/menus` | 获取全部菜单列表 | Authz (admin) |
| POST | `/menu` | 创建菜单 | Authz (admin) |
| PUT | `/menu/:id` | 更新菜单 | Authz (admin) |
| DELETE | `/menu/:id` | 删除菜单 | Authz (admin) |
| PUT | `/menus/sort` | 批量排序菜单 | Authz (super_admin) |

## 7. 角色管理 (Role)

| 方法 | 路径 | 描述 | 权限 |
|------|------|------|------|
| GET | `/roles` | 获取角色列表 | Authz (admin) |
| POST | `/role` | 创建角色 | Authz (admin) |
| PUT | `/role/:id` | 更新角色 | Authz (admin) |
| DELETE | `/role/:id` | 删除角色 | Authz (admin) |
| GET | `/role/:id/menus` | 获取角色菜单 | Authz (admin) |
| PUT | `/role/:id/menus` | 设置角色菜单 | Authz (admin) |

## 8. 机构管理 (Organization)

| 方法 | 路径 | 描述 | 权限 |
|------|------|------|------|
| GET | `/organizations` | 获取机构列表 | Authz (admin) |
| POST | `/organization` | 创建机构 | Authz (admin) |
| PUT | `/organization/:id` | 更新机构 | Authz (admin) |
| DELETE | `/organization/:id` | 删除机构 | Authz (admin) |
| GET | `/organization/:id/members` | 获取机构成员 | Authz (admin) |
| POST | `/organization/:id/member` | 添加机构成员 | Authz (admin) |
| PUT | `/organization/:id/member/:userId` | 更新成员角色 | Authz (admin) |
| DELETE | `/organization/:id/member/:userId` | 移除机构成员 | Authz (admin) |

## 9. AI 对话 (AI Chat)

| 方法 | 路径 | 描述 | 权限 |
|------|------|------|------|
| POST | `/ai/chat/completions` | AI 对话补全 (支持 SSE 流式) | Auth |
| GET | `/ai/conversations` | 获取对话列表 | Auth |
| POST | `/ai/conversation` | 创建对话 | Auth |
| GET | `/ai/conversation/:id` | 获取对话详情 | Auth |
| PUT | `/ai/conversation/:id` | 更新对话标题 | Auth |
| DELETE | `/ai/conversation/:id` | 删除对话 | Auth |
| GET | `/ai/models` | 获取可用模型列表 | Auth |
| GET | `/ai/quota/me` | 获取我的配额 | Auth |
| GET | `/ai/quota/records` | 获取我的用量记录 | Auth |
| GET | `/ai/usage/export` | 导出用量记录 CSV | Auth |

## 10. AI 密钥 (AI Keys - 用户)

| 方法 | 路径 | 描述 | 权限 |
|------|------|------|------|
| GET | `/ai/keys` | 获取我的 API Key 列表 | Auth |
| POST | `/ai/key` | 添加 API Key | Auth |
| PUT | `/ai/key/:id` | 更新 API Key | Auth |
| DELETE | `/ai/key/:id` | 删除 API Key | Auth |

## 11. AI 管理 (AI Admin)

| 方法 | 路径 | 描述 | 权限 |
|------|------|------|------|
| GET | `/ai/providers` | 获取 AI 平台列表 | Authz (admin) |
| POST | `/ai/provider` | 创建 AI 平台 | Authz (admin) |
| PUT | `/ai/provider/:id` | 更新 AI 平台 | Authz (admin) |
| DELETE | `/ai/provider/:id` | 删除 AI 平台 | Authz (admin) |
| POST | `/ai/model` | 创建 AI 模型 | Authz (admin) |
| PUT | `/ai/model/:id` | 更新 AI 模型 | Authz (admin) |
| DELETE | `/ai/model/:id` | 删除 AI 模型 | Authz (admin) |
| GET | `/ai/quotas` | 获取用户额度列表 | Authz (admin) |
| POST | `/ai/quota/recharge` | 充值用户额度 | Authz (admin) |
| GET | `/ai/stats` | 获取 AI 使用统计 | Authz (admin) |
| GET | `/ai/system-keys` | 获取系统密钥列表 | Authz (admin) |
| POST | `/ai/system-key` | 创建系统密钥 | Authz (admin) |
| PUT | `/ai/system-key/:id` | 更新系统密钥 | Authz (admin) |
| DELETE | `/ai/system-key/:id` | 删除系统密钥 | Authz (admin) |

---

**共 64 个接口** | 公开 3 · 登录用户 14 · 管理员授权 47