Thesisly/docs/paper-api.md

论文只读 HTTP 接口

状态：既有论文库已完成 PostgreSQL 迁移与独立验收。此前 SQLite 实现方案已撤回，未部署；Foundry Core 的 codex/research-api 分支正在按实际 PostgreSQL schema 联调。本任务包括后端实现与联调，不把接口开发留给用户。

地址与配置

实际契约：GET /projects/{project}/research/papers 和 GET /projects/{project}/research/papers/{id}。上线后前端配置：

PAPER_API_ORIGIN=https://api.foundry.entroia.com/projects/thesisly/research/

未配置时显式显示20条真实数据库样本；配置后只请求远程接口，错误不会退回样本。前端不携带数据库或服务账户凭据。

列表

GET {PAPER_API_ORIGIN}/papers?q=&searchIn=text&topic=&sort=recent&page=1&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。

论文

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 回环隧道验证真实全库首页和详情（桌面/手机无页面异常和横向溢出），查询性能仍在调整；临时 Core 不是正式部署。不部署 SQLite sidecar，不复制整库，不从浏览器持有数据库连接串。

最多两个并行查询、8秒查询预算；繁忙返回429，超时/存储异常明确报错。已补建作者和领域索引，并局部关闭 JIT、调整过滤取页顺序。实测作者搜索146条、cs.AR领域9457条、CartoonGAN搜索3条、多词全文检索8653条均返回200；非常宽泛的检索仍可能超出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传输用例覆盖了错误分类、表单保留及异常响应处理。