接口文档

接口概述

后端基于 FastAPI 提供一套 RESTful JSON 接口，按业务域进行划分

模块前缀	业务域	说明
/system	系统管理	认证、用户、角色、部门、菜单、字典、权限、日志、邮件、短信、OAuth2、站内信等
/infra	基础设施	参数配置、文件、定时任务、Redis/服务器监控、在线用户、健康检查、WebSocket
/bpm	工作流	流程模型、流程定义、流程实例、审批任务、用户组、表单、分类、评论等
/ai	AI 能力	对话、知识库、文档/分段、模型管理、API Key、聊天角色、工具、写作等

所有接口默认返回 application/json（文件下载/上传接口除外），请求体与响应体中的字段统一使用小驼峰命名（snake_case 会自动转换）。

---

接口文档的查看

项目内置 OpenAPI 文档，开发环境默认开启。但生产环境默认关闭（DOCS_URL、REDOC_URL 为空）以避免接口结构泄露。在开发环境 backend\env\.env.dev 配置中已开启：

DOCS_URL = "/docs"      # Swagger UI
REDOC_URL = "/redoc"    # ReDoc

启动后端，浏览器访问：http://localhost:8000/api/v1/docs

• Swagger UI：http://<host>:<port>/docs
• ReDoc：http://<host>:<port>/redoc
• OpenAPI Schema：http://<host>:<port>/openapi.json（仅当 DOCS_URL 或 REDOC_URL 非空时可用）

各大模块路由前缀一览：

模块	路由前缀
系统管理	/system
基础设施	/infra
工作流	/bpm
AI	/ai

---

接口认证与鉴权

获取令牌

除登录、注册、验证码、健康检查等少数公开接口外，其余接口均需要携带有效的访问令牌（Access Token）。

• 启动后端后，浏览器访问：http://localhost:8000/api/v1/docs
• 点击右上方 Authorize 按钮，输入 admin / admin123

获取令牌原理

发送 POST 请求

POST /system/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "your_password",
  "captchaVerification": ""   // 开启验证码时必填，格式 key___code
}

成功响应返回：

{
  "code": 0,
  "msg": "登录成功",
  "data": {
    "accessToken": "eyJhbGciOi...",
    "refreshToken": "eyJhbGciOi...",
    "expiresIn": 43200,
    "tokenType": "Bearer"
  },
  "statusCode": 200,
  "success": true
}

在请求中携带令牌

后续请求在 HTTP 头中携带 Bearer Token：

Authorization: Bearer <access_token>

服务端会从 Authorization 头解析 Bearer 前缀后的令牌（见 framework/web/middleware.py 的 _strip_bearer）。

令牌刷新与过期

• Access Token 默认有效期 ACCESS_TOKEN_EXPIRE_SECONDS = 43200（12 小时）。
• 开启 TOKEN_SLIDING_EXPIRE=true 时支持滑动过期：用户持续操作会自动续期。
• 令牌过期后，使用 Refresh Token 续期：

POST /system/auth/refresh-token?refreshToken=<refresh_token>

• 退出登录：

POST /system/auth/logout
Authorization: Bearer <access_token>

---

统一请求与响应格式

统一响应结构

所有 JSON 接口统一返回如下结构：ResponseSchema

{
  "code": 0,            // 业务状态码（0 表示成功，非 0 见状态码表）
  "msg": "成功",         // 提示信息
  "data": {},           // 业务数据（可为对象/数组/分页对象，也可能为 null）
  "statusCode": 200,    // HTTP 状态码
  "success": true       // 是否成功
}

• code 与 statusCode 的区别：code 是业务状态码；statusCode 是 HTTP 状态码。
• 响应体字段经过小驼峰转换（snake_case → camelCase），日期时间统一格式为 YYYY-MM-DD HH:MM:SS。

分页响应

列表类接口（通常为 .../page）使用分页结构：PageResultSchema

{
  "code": 0,
  "data": {
    "pageNo": 1,
    "pageSize": 10,
    "total": 57,
    "hasNext": true,
    "items": [ { } ]
  },
  "statusCode": 200,
  "success": true
}

分页请求参数一般通过 Query 传递：pageNo（页码，默认 1）、pageSize（每页条数，默认 10），以及 orderBy（排序字段，可选）。

文件上传 / 下载

• 上传：使用 multipart/form-data，文件字段为 file，部分接口附带 updateSupport 等表单字段。
• 下载（导出 / 模板）：返回 application/octet-stream 或具体类型（如 Excel 的 application/vnd.openxmlformats-officedocument.spreadsheetml.sheet），并通过 Content-Disposition 头携带文件名。前端需读取响应二进制流。

---

业务状态码说明

响应中的 code 字段取值参考 framework/web/status_code.py 的 RET 枚举：

code	含义	类别
0	成功	成功
1	请求错误（通用）	错误
200	操作成功	成功
400	参数错误	HTTP
401	未授权（未登录 / 令牌无效）	HTTP
403	访问受限（无权限）	HTTP
404	资源不存在	HTTP
422	请求参数验证错误	HTTP
429	请求过于频繁	HTTP
500	服务器内部错误	服务器
4003	数据已存在	业务
4004	数据错误	业务
4103	参数错误	业务
4503	访问频率超限	限流
4504	无效令牌	Token
4505	令牌过期	Token
4506	无效凭证	认证
4512	权限错误	权限

业务错误码区间约定：0~200 成功；400~600 HTTP 标准错误；4000+ 自定义业务错误。

---