base/docs/api-reference.md

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