接口约定

管理 API 使用 /api/v1 前缀。应用通过 sdk.Route 注册相对路径并声明权限。0.13.0 的端点覆盖认证、统一授权（显式 Grants 与授权管理控制面）、用户与组织、字典参数、日志、通知、工作流、AI 模型与 Agent、数据交换以及业务附件等模块。精确接口合同以同版本核心源码中的 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`	获取当前用户、角色身份 code 与能力投影
`GET /api/v1/auth/menus`	获取当前用户可见的菜单树

令牌为 JWT，默认有效期 60 分钟（JWT_TTL），刷新窗口默认 14 天（JWT_REFRESH_TTL）。不签发独立 refresh token：原访问令牌即使已过期，只要未超过刷新窗口，仍可调用 refresh 换取新令牌；超过窗口返回 401 + code 1003，须重新登录。

JWT 携带签名保护的 auth_revision，普通鉴权与刷新都实时比对数据库当前版本；注销、改密、后台账号编辑、角色替换、禁用或删除等递增修订的操作会撤销该账号此前的全部会话，撤销状态在重启和多实例部署后仍然有效。手机号仅作为联系信息，不用于登录。

统一 JSON 响应

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

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

分页

标准列表使用 page 与 pageSize（默认 1 与 10，最大 100），返回 list、total、page、pageSize。例如：

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

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

常见错误码

code	含义	常见 HTTP 状态
`1000`	参数校验失败（也用于业务规则冲突，如删除保护、CAS 漂移）	`422 / 400`
`1001`	登录凭证无效（不区分账号或密码错误）	`401`
`1002`	未登录或令牌无效（含已注销/撤销令牌）	`401`
`1003`	令牌过期（含刷新窗口已过）	`401`
`1004`	权限不足（缺少所需权限或授权范围）	`403`
`1100`	审批定义无效（结构失败或发布校验不通过）	`422`
`1101`	审批草稿/任务/实例版本冲突	`409`
`1102`	同一审批 request_id 用于不同目标/动作/参数	`409`
`1103`	审批当前状态不允许该动作	`409`
`1104`	审批业务资源已变化或不满足绑定/意图约束	`409`
`1105`	审批引用不存在或当前不可见	`404`
`1106`	审批结构/值/查询预算超限	`422 / 413`
`1404`	文件不存在或不可见	`404`
`1409`	文件版本/幂等声明/引用/生命周期冲突	`409`
`1410`	上传任务已过期或取消	`410`
`1411`	文件被业务引用	`409`
`1412`	文件逻辑容量不足	`409`
`1413`	文件或总请求体超过限制	`413`
`1415`	文件类型不支持或内容不匹配	`415`
`1429`	上传并发或容量预留不足，可重试	`429`
`5000`	服务内部错误	`500`
`5001`	扩展当前不可用（稳定脱敏响应）	`503`
`5002`	文件内容或存储暂不可用	`503`
`5003`	审批能力或固定执行依赖当前不可用	`503`

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