接口约定

管理 API 使用 /api/v1 前缀。应用通过 sdk.Route 注册相对路径并声明权限。精确接口合同以同版本核心源码中的 docs/API.md 为准。

认证

受保护接口携带访问令牌：

Authorization: Bearer <token>

接口	作用
POST /api/v1/auth/login	通过邮箱与密码登录
POST /api/v1/auth/refresh	用原访问令牌刷新
POST /api/v1/auth/logout	注销当前访问令牌
GET /api/v1/auth/profile	获取当前用户、角色与权限

当前机制不签发独立 refresh token。原访问令牌在刷新窗口内可用于刷新；前端核心运行时处理令牌过期与重新登录流程。

统一 JSON 响应

{
  "code": 0,
  "message": "ok",
  "data": {}
}

code: 0 表示成功，错误响应省略 data。结合 HTTP 状态与业务码判断结果。文件内容的二进制成功响应、Agent SSE 等专用协议不套用普通 JSON 处理方式。

分页

标准列表使用 page 与 pageSize，返回 list、total、page、pageSize。例如：

GET /api/v1/products?page=1&pageSize=10

特定候选项接口可能使用 has_more 且不暴露总数，按该接口合同处理，不假定所有响应都有 total。

常见错误码

code	含义	常见 HTTP 状态
1000	参数校验或业务规则失败	400 / 422
1001	登录凭证无效	401
1002	未登录或令牌无效	401
1003	令牌过期	401
1004	权限不足	403
1101	审批对象版本冲突	409
1102	审批请求键用于不同操作或参数	409
1404	文件不存在或不可见	404
1412	文件逻辑容量不足	409
5000	服务内部错误	500
5001	扩展当前不可用	503
5002	文件内容或存储暂不可用	503
5003	审批能力或执行依赖不可用	503

只有令牌过期的 401 + 1003 进入刷新判断，其他 401 需要重新登录。业务错误提示可展示给用户，程序分支依赖稳定错误码，不匹配中文文案。