62 lines
6.4 KiB
Markdown
62 lines
6.4 KiB
Markdown
# 论文只读 HTTP 接口
|
||
|
||
状态：既有论文库已完成 PostgreSQL 迁移与独立验收。此前 SQLite 实现方案已撤回，未部署；Foundry Core 的初版论文 API 已合并 main；本轮优化改用游标契约。本任务包括后端实现与联调，不把接口开发留给用户。
|
||
|
||
## 地址与配置
|
||
|
||
实际契约：GET /projects/{project}/research/papers 和 GET /projects/{project}/research/papers/{id}。上线后前端配置：
|
||
|
||
```dotenv
|
||
PAPER_API_ORIGIN=https://api.foundry.entroia.com/projects/thesisly/research/
|
||
```
|
||
|
||
未配置时显式显示20条真实数据库样本；配置后只请求远程接口，错误不会退回样本。前端不携带数据库或服务账户凭据。
|
||
|
||
## 列表
|
||
|
||
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索引。
|
||
- 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；游标不是账户凭据。手工修改或跨筛选复用游标需要清除筛选重新浏览。
|
||
|
||
## 论文
|
||
|
||
Paper包含id、title、abstract（可空）、authors字符串数组、publishedAt（保留来源格式，可空）、topics、sources（label/url/externalId），以及publications（venue/year/track/status/evidenceUrl）。可选doi、journal、comments。
|
||
|
||
source_records按paper_id关联；作者兼容[family,given,suffix]数组与字符串；真实 arXiv 的第四段机构名不拼入姓名。会议记录通过submissions→editions→venues，状态取最新决定观察；没有决定时保持unknown，不推断拒稿。不虚构代码库、数据集、引用量、热门或AI结论。详情不存在返回404。
|
||
|
||
## 读取边界
|
||
|
||
已核对实际 PostgreSQL schema、编码标记和索引，并在服务器创建专用 SELECT 账号及受保护连接配置。已通过 SSH 回环隧道验证真实全库首页和详情（桌面/手机无页面异常和横向溢出），非常宽泛查询可能超出8秒预算；临时 Core 不是正式部署。不部署 SQLite sidecar，不复制整库，不从浏览器持有数据库连接串。
|
||
|
||
默认排序的纯领域查询直接沿现有领域/论文索引取页；全文查询先在游标附近512的 ID 区间找一页，有少量匹配但不足一页时扩展一次到4096，仍不足9个位置才丢弃局部候选、执行完整索引检索，保证不截断较旧或稀疏结果。标题排序仍使用完整候选检索，宽泛条件仍可能超时。
|
||
|
||
最多两个并行查询、8秒查询预算；繁忙返回429，超时/存储异常明确报错。已补建作者和领域索引，并局部关闭 JIT、调整过滤取页顺序。初版计数接口曾验证作者、领域和多词全文检索；非常宽泛的检索仍可能超出8秒预算，这是当前已知的性能限制。语料库是共享公开数据；账户与未来私有收藏仍须按项目隔离。
|
||
|
||
## 联调前置
|
||
|
||
- 当前阶段不触发 CI、不推送启动流水线，也不部署；手动验证在已确认 ECS 的独立临时目录执行。后续主线合并仍需用户手动操作。
|
||
- 保留FOUNDRY_PROJECTS旧条目，追加thesisly→http://localhost:17322/auth/callback。
|
||
- 用户已确认新增 FOUNDRY_PROJECTS；无需添加 FOUNDRY_RESEARCH_DATABASE。PostgreSQL 后端连接仅放服务器受保护的 research.env，不放 Gitea Variables 或前端配置。
|
||
- 本地忽略文件 PAPER_API_ORIGIN 现指向 127.0.0.1:17325/projects/thesisly/research/，通过 SSH 连接 ECS 临时 Core。隧道和临时服务停止时应显式报错，不退回样本。
|
||
- 前端仓库为Zayden-Jung/Thesisly，不配置CI/CD；本地build按用户最新要求暂不执行。
|
||
- 正式 Core 已仅重载项目配置，Thesisly 匿名 auth/me 当前返回401，原有项目保留；论文 API 新代码仍未发布正式后端。Google/Slack真实授权和用户侧刷新、新标签保持、退出均已确认；邮件实际投递和验证未实测。302与fixture测试不代表邮件真实投递成功。
|
||
|
||
|
||
## 查询失败后的恢复
|
||
|
||
列表将超时、繁忙、无效条件和服务不可用作为可恢复状态：保留关键词/搜索范围/领域，不显示总数或可用分页，不把错误显示成0条结果，也不退回样本。用户可直接修改关键词或重试。真实库已验证graph超时后修改为CartoonGAN恢复3条；隔离浏览器和匿名HTTP传输用例覆盖了错误分类、表单保留及异常响应处理。
|
||
|
||
|
||
## 页面请求与后续优化
|
||
|
||
首页标题、搜索和排序先渲染，论文结果与领域列表通过 Suspense 后续载入，并复用同一个列表请求。搜索/排序使用 Next Form 站内导航，保留根布局和登录状态；列表中的领域、文章和分页链接关闭自动预取，限制链接预取带来的后台请求；本轮未执行生产 build，未测量生产预取收益。查询仍有明确的等待、失败、空结果三种状态。
|
||
|
||
下一阶段应分别测量：登录回调到可操作页面的耗时、窗口焦点触发的会话检查频率、文章 metadata 与正文的重复读取。可采用会话请求合并/焦点检查冷却、请求内文章读取去重，以及公开列表的短时有界缓存；账户校验和权限不复用公开缓存。总量若有产品需要，独立后台统计并标注统计时间，不进入阅读和搜索的关键路径。优先实测这些站内改动，不调整 Traefik。
|