Stream reader results and navigate with cursors [skip ci]

This commit is contained in:
2026-11-07 17:27:31 +08:00
parent b5b1994993
commit ae4a505d70
10 changed files with 149 additions and 46 deletions
+18 -6
View File
@@ -1,6 +1,6 @@
# 论文只读 HTTP 接口
状态:既有论文库已完成 PostgreSQL 迁移与独立验收。此前 SQLite 实现方案已撤回,未部署;Foundry Core 的 codex/research-api 分支正在按实际 PostgreSQL schema 联调。本任务包括后端实现与联调,不把接口开发留给用户。
状态:既有论文库已完成 PostgreSQL 迁移与独立验收。此前 SQLite 实现方案已撤回,未部署;Foundry Core 的初版论文 API 已合并 main;本轮优化改用游标契约。本任务包括后端实现与联调,不把接口开发留给用户。
## 地址与配置
@@ -14,13 +14,16 @@ PAPER_API_ORIGIN=https://api.foundry.entroia.com/projects/thesisly/research/
## 列表
GET {PAPER_API_ORIGIN}/papers?q=&searchIn=text&topic=&sort=recent&page=1&pageSize=8
GET {PAPER_API_ORIGIN}/papers?q=&searchIn=text&topic=&sort=recent&cursor=&pageSize=8
- q:最多200个Unicode字符、20个词。searchIn=text时检索标题/摘要,searchIn=author时检索显示作者名。不会把用户输入作为任意SQL或FTS操作符。
- topic:精确arxiv:category值。
- sort:recent是稳定论文ID降序,即收录顺序,**不是发表日期排序**;title使用现有title_key索引。
- page:1–1000;pageSize:1–50,前端当前为8。前端与此上限一致;结果超过8,000条时明确提示缩小搜索或领域范围,不生成不可访问的下一页链接。超出实际末页的页面地址会跳转至当前条件下的末页。
- 返回{items:Paper[],total,topics,page,pageSize},同一只读事务内计数及取页;无效、重复、未知参数返回400。
- pageSize:1–50,前端当前为8。每次取9个位置,显示8篇,以额外一条判断是否有下一页。
- cursor:首屏省略;后续原样使用返回的 nextCursor / previousCursor。游标绑定关键词、范围、领域、排序和每页大小;修改筛选必须清除游标。空字符串表示没有该方向的下一页。
- 返回 `{items:Paper[],nextCursor:string,previousCursor:string,topics:string[],pageSize:number}`。不再返回 total/page,也不接受旧 page 参数;前后端需协调切换。列表不执行全库或搜索精确计数,不依赖总页数或8,000条浏览上限。
- recent 使用 ID 降序;title 使用存储的 title_key、ID 升序以区分同标题记录。每次请求是一个只读快照,跨页期间新增/删除/修改记录可能改变结果,不承诺整个浏览过程冻结语料库。
- 无效、重复、未知参数返回400;游标不是账户凭据。手工修改或跨筛选复用游标需要清除筛选重新浏览。
## 论文
@@ -32,7 +35,9 @@ source_records按paper_id关联;作者兼容[family,given,suffix]数组与字
已核对实际 PostgreSQL schema、编码标记和索引,并在服务器创建专用 SELECT 账号及受保护连接配置。已通过 SSH 回环隧道验证真实全库首页和详情(桌面/手机无页面异常和横向溢出),非常宽泛查询可能超出8秒预算;临时 Core 不是正式部署。不部署 SQLite sidecar,不复制整库,不从浏览器持有数据库连接串。
最多两个并行查询、8秒查询预算;繁忙返回429,超时/存储异常明确报错。已补建作者和领域索引,并局部关闭 JIT、调整过滤取页顺序。实测作者搜索146条、cs.AR领域9457条、CartoonGAN搜索3条、多词全文检索8653条均返回200;非常宽泛的检索仍可能超出8秒预算,这是当前已知的性能限制。语料库是共享公开数据;账户与未来私有收藏仍须按项目隔离。
默认排序的纯领域查询直接沿现有领域/论文索引取页;全文查询先在游标附近512的 ID 区间找一页,有少量匹配但不足一页时扩展一次到4096,仍不足9个位置才丢弃局部候选、执行完整索引检索,保证不截断较旧或稀疏结果。标题排序仍使用完整候选检索,宽泛条件仍可能超时。
最多两个并行查询、8秒查询预算;繁忙返回429,超时/存储异常明确报错。已补建作者和领域索引,并局部关闭 JIT、调整过滤取页顺序。初版计数接口曾验证作者、领域和多词全文检索;非常宽泛的检索仍可能超出8秒预算,这是当前已知的性能限制。语料库是共享公开数据;账户与未来私有收藏仍须按项目隔离。
## 联调前置
@@ -46,4 +51,11 @@ source_records按paper_id关联;作者兼容[family,given,suffix]数组与字
## 查询失败后的恢复
列表将超时、繁忙、无效条件和服务不可用作为可恢复状态:保留关键词/搜索范围/领域,不显示未知总数和分页,不把错误显示成0条结果,也不退回样本。用户可直接修改关键词或重试。真实库已验证graph超时后修改为CartoonGAN恢复3条;隔离浏览器和匿名HTTP传输用例覆盖了错误分类、表单保留及异常响应处理。
列表将超时、繁忙、无效条件和服务不可用作为可恢复状态:保留关键词/搜索范围/领域,不显示总数或可用分页,不把错误显示成0条结果,也不退回样本。用户可直接修改关键词或重试。真实库已验证graph超时后修改为CartoonGAN恢复3条;隔离浏览器和匿名HTTP传输用例覆盖了错误分类、表单保留及异常响应处理。
## 页面请求与后续优化
首页标题、搜索和排序先渲染,论文结果与领域列表通过 Suspense 后续载入,并复用同一个列表请求。搜索/排序使用 Next Form 站内导航,保留根布局和登录状态;列表中的领域、文章和分页链接关闭自动预取,限制链接预取带来的后台请求;本轮未执行生产 build,未测量生产预取收益。查询仍有明确的等待、失败、空结果三种状态。
下一阶段应分别测量:登录回调到可操作页面的耗时、窗口焦点触发的会话检查频率、文章 metadata 与正文的重复读取。可采用会话请求合并/焦点检查冷却、请求内文章读取去重,以及公开列表的短时有界缓存;账户校验和权限不复用公开缓存。总量若有产品需要,独立后台统计并标注统计时间,不进入阅读和搜索的关键路径。优先实测这些站内改动,不调整 Traefik。