50 lines
4.5 KiB
Markdown
50 lines
4.5 KiB
Markdown
# 论文只读 HTTP 接口
|
||
|
||
状态：既有论文库已完成 PostgreSQL 迁移与独立验收。此前 SQLite 实现方案已撤回，未部署；Foundry Core 的 codex/research-api 分支正在按实际 PostgreSQL schema 联调。本任务包括后端实现与联调，不把接口开发留给用户。
|
||
|
||
## 地址与配置
|
||
|
||
实际契约：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&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传输用例覆盖了错误分类、表单保留及异常响应处理。
|