后端接口对接参考：鉴权、响应结构与分页
平台所有前后端共用同一套 REST 接口。本文面向需要做系统集成、数据同步或自建报表的工程师，给出接口风格、登录鉴权、统一响应结构、分页约定、错误处理与 WebSocket 事件的实际规则。
Inkwell Engine 的 PC 端与移动端没有特殊的「内部通道」——它们消费的就是同一套公开的 REST 接口。因此第三方系统（ERP 对接、报表工具、自动化脚本）能拿到与官方前端完全一致的数据视角。
基础约定
- 所有接口挂在
/api/v1前缀下，例如GET /api/v1/users； - 请求与响应体均为 JSON；
- 生产部署通常经反向代理把
/api转发到后端服务（默认端口 3000），对接时直接使用站点域名即可，无需关心内部端口。
登录与鉴权
调用业务接口前先登录获取访问令牌：
POST /api/v1/auth/login两个安全规则需要特别注意：
- 敏感字段加密传输：登录的账号密码属于敏感字段，必须使用平台 RSA 公钥加密后放入
encryptedData字段提交，明文提交会被拒绝（返回ENCRYPTION_REQUIRED）。官方前端的加密逻辑在src/api/modules/crypto.ts，自研对接方可复用同一公钥。 - 令牌传递：登录成功后拿到访问令牌，后续请求在
Authorization头携带Bearer <token>。令牌不要拼进 URL，也不要落到日志里。
令牌无效或过期时，接口统一返回 401 与 UNAUTHORIZED 错误码，收到后应引导重新登录，而不是重试请求。
统一响应结构
所有接口返回统一的信封结构，success 字段是判断成败的第一依据：
{
"success": true,
"data": { },
"message": "ok",
"_meta": { "locale": "zh-cn" }
}失败时的信封携带稳定的错误码与可国际化的键：
{
"success": false,
"code": "UNAUTHORIZED",
"key": "令牌无效",
"message": "失败",
"_meta": { "locale": "zh-cn", "key": "令牌无效" }
}code是机器可判定的错误类别（如UNAUTHORIZED、ENCRYPTION_REQUIRED），写集成逻辑时请依据它分支，不要解析message文案；key与_meta服务于多语言展示，人工排障时再看。
分页约定
列表类接口接受 page（从 1 开始）与 pageSize 查询参数，分页信息放在返回数据的 meta 字段：
{
"success": true,
"data": {
"data": [ ],
"meta": { "page": 1, "pageSize": 20, "total": 0, "totalPages": 0 }
}
}不同接口对 pageSize 各有上限保护，超限时会被拒绝或自动钳制，以响应中的错误提示为准。批量拉取数据时请按 page 递增遍历到 totalPages 为止，不要并发猛打。
数据安全：脱敏与裁剪
标注为敏感的业务字段在响应层自动处理，这是平台内建行为，对接方无需也不应该尝试还原：
- 手机号、邮箱等 PII 字段按策略脱敏返回（例如手机号显示为
138****8888）； - 口令、密钥类字段被完全裁剪，响应中不会出现。
如果你的集成需要完整字段用于计算，应在自己的服务端以受控方式直连数据库只读副本，而不是试图绕过接口脱敏。
WebSocket 事件
实时通知（任务进度、模块错误、待办提醒）走 WebSocket，连接路径为 /websockets。客户端连接后先发送 authenticate 事件携带访问令牌并等待确认，再订阅业务房间。令牌失效时服务器会主动断开，客户端应重新登录后重连。
注意事项
- 幂等与重试：写操作（POST/PUT/DELETE）不建议盲目自动重试，先读回确认状态，避免重复建单。
- 速率与体量：接口面向管理界面粒度设计，单次查询条数与并发请求数都应保持克制；大规模数据同步优先考虑错峰增量。
- 版本兼容：路径中的
v1是接口契约版本。字段级的新增通常是兼容的，但依赖字段删除前的废弃通知不可靠——集成侧应对未知字段与缺失字段保持宽容。 - 排障顺序：先看
success与code，再看 HTTP 状态码；AI 生成模块的运行时错误同时会进入平台的模块错误台账，可在 AI Studio 中查到聚合信息。