BOOK INDEX API REFERENCE

从资料入库，
到可追溯检索。

按业务找接口，按步骤完成联调。这里说明每个接口的用途、调用前提、参数含义与响应结构，而不只是列出 URL。

— 个接口操作7 个业务模块正在核对运行契约…

先看调用顺序

EPUB 图书主流程

01上传原书原始 EPUB 字节 → resourceId 02等待解析轮询唯一解析 → READY / FAILED 03检查与复核查看问题 → 确认 → 索引对账 04上架与检索满足门禁 → ONLINE → 引用阅读

HTTP 200 不代表异步解析完成。每份图书只有一份解析结果；重解析覆盖旧结果，旧句子引用失效。研究文献走独立导入接口，不走 EPUB 解析链路。

连接与公共约定

先配置，再复制示例

示例中的 API Base URL

默认使用当前文档主机的 8000 端口；只改变示例代码，不会发起业务请求。地址不含 /api/v1，也不是当前文档站地址。

文档可访问 ≠ 业务 API 已开放

当前 Nginx 只公开文档和只读 OpenAPI；业务 API 仍监听服务器回环 127.0.0.1:8000。待服务器端口开放后，可按本页的 http://公网IP:8000 直接联调，无需 SSH 隧道。admin 前缀不是鉴权，不要直接公开写接口。

如何配置 API 地址、公网端口和前端代理？

接口开放前，开发联调可临时通过获准的 SSH 隧道访问服务器回环地址；接口开放后直接使用上方 API Base URL，不需要隧道。服务器侧需要同时放通云安全组和主机监听，当前容器仍只绑定 127.0.0.1:8000，仅开放云端口不会自动生效。

前端配置建议：本地开发把 /api 代理到 http://公网IP:8000；生产前端优先使用同站反向代理并配置 HTTPS。进入用户浏览器的跨域来源必须加入后端 CORS_ORIGINS，不要在浏览器关闭安全校验；HTTP 文档站请求 HTTPS API 或反向时都可能被浏览器拦截。

JSON 信封、业务状态与错误处理

JSON 成功响应固定为 code / message / data / requestId。成功 code 为 0，requestId 与响应头 X-Request-ID 对应。二进制文件直接返回字节，不包 JSON。

{
  "code": 0,
  "message": "ok",
  "data": { "total": 0, "items": [] },
  "requestId": "示例追踪标识"
}

同时检查 HTTP 状态和 code。请求参数大小写有意义：查询常用 resourceId / pageSize，路径模板及部分响应使用 snake_case，按下方实际名称调用。

400 / 413 / 415 文件内容、体积或媒体类型不合法
404 记录/文件不存在，或引用已经失效
409 状态冲突、尚未复核、任务运行中或索引不一致
422 UUID、枚举、长度、分页或业务参数校验失败
503 依赖故障或数据/文件一致性异常；不要当作零命中

自动参数错误通常 code=10422，显式业务拒绝为 30000+HTTP 状态，未处理依赖错误为 10503。实际错误体采用统一信封，不是 OpenAPI 自动生成的 HTTPValidationError 结构。Nginx 拒绝访问的响应不采用应用信封。

状态、分页与覆盖更新要注意什么？

图书资源 status 与解析 status 是两个状态域：资源常见 PROCESSING / REVIEW / ONLINE / FAILED；解析为 QUEUED / PROCESSING / READY / FAILED。上传后通过 GET /api/v1/admin/parses?resourceId=… 轮询，建议客户端约 2 秒一次、设置超时并允许用户恢复，不能无限轮询。

page 从 1 开始；多数接口 pageSize 默认 20，文献默认 10，上限 100。具体限制看接口参数表。total 的单位随接口不同：图书列表是书，块级全文是块，文献列表是篇，不要混用。

上架前需要解析就绪、质检通过、问题已复核且索引一致。ACKNOWLEDGE 不能豁免硬错误。ONLINE 资料先下架才能重解析；重解析保留原 EPUB 与人工书目修订，不保留旧句引用或历史候选。

接口参考

正在加载…

/

正在读取当前部署的接口契约…

从资料入库，到可追溯检索。

先看调用顺序

连接与公共约定

接口参考

从资料入库，
到可追溯检索。