daily-paper/docs/api-and-ui.md

API 路由与页面设计

本文档定义页面路由、JSON API、管理接口、用户流程和验收标准。

---

1. 页面路由

方法	路径	说明
GET	/	重定向到 /day/{today}
GET	/day/{date}	指定日期论文列表
GET	/paper/{arxiv_id}	论文详情
GET	/search	搜索页和搜索结果
GET	/reading-list	收藏和阅读列表
GET	/admin/logs	管理日志页，需要 token
GET	/rss.xml	RSS Feed

后续增强：

• /trends
• /compare?ids=id1,id2
• /similar/{arxiv_id}

---

2. 数据 API

方法	路径	说明
GET	/api/papers?date=&tag=&q=	论文列表
GET	/api/paper/{arxiv_id}	单篇论文详情
GET	/api/dates	有数据的日期列表
GET	/api/tags	标签及计数
GET	/api/stats	统计信息
GET	/api/search?q=&tag=	FTS5 搜索

---

3. 用户数据 API

方法	路径	说明
POST	/api/bookmark/{arxiv_id}	收藏/取消收藏
POST	/api/reading-status/{arxiv_id}	更新阅读状态
GET	/api/note/{arxiv_id}	获取笔记
POST	/api/note/{arxiv_id}	保存笔记

请求和响应使用 JSON。无账号体系，数据写入本地 SQLite。

安全边界：

• 默认 APP_HOST=127.0.0.1 时，用户数据 API 只服务本机访问。
• 如果绑定到非本地地址，用户数据写接口需要启用 same-origin 检查或 token。

---

4. 管理接口

所有管理接口都需要：

Authorization: Bearer <ADMIN_TOKEN>

方法	路径	说明
POST	/admin/crawl	手动抓取指定日期，默认今天
POST	/admin/summarize/{arxiv_id}	手动总结或重跑单篇
POST	/admin/summarize	批量总结 pending 论文
POST	/admin/cleanup	清理临时文件
POST	/admin/delete	删除指定日期范围内的数据
GET	/admin/logs	查看任务日志

/admin/delete 请求体

{
  "date_start": "2026-06-01",
  "date_end": "2026-06-05",
  "include_notes": true,
  "confirm": "DELETE"
}

confirm 必须为 DELETE，否则拒绝执行。

---

5. 页面状态

首页 / 日期页

每张论文卡片展示：

• 中文标题；没有总结时展示英文标题。
• 一句话摘要；没有总结时展示英文 abstract 截断。
• 标签、作者、upvotes、难度。
• 总结状态：未总结、总结中、失败、已完成。
• 收藏按钮、阅读状态入口、详情链接。

详情页

详情页按状态降级：

状态	展示
无总结	英文标题、作者、摘要、HF/arXiv 链接、手动总结按钮
processing	元数据 + “正在生成总结”
failed	元数据 + 错误类型 + 手动重跑按钮
done/normal	完整中文结构化解读
done/degraded	展示已有内容，缺失模块标注不完整
done/low	顶部质量提示 + 已有内容

详情模块：

• 一句话摘要
• 预置知识
• 研究动机
• 核心方法
• 实验结果
• 局限和改进方向
• 原文链接
• 收藏、阅读状态、个人笔记

搜索页

MVP 只提供关键词搜索：

• 搜索框。
• 标签筛选。
• 结果按相关性和日期排序。
• 命中片段高亮。

语义搜索作为后续增强，UI 上先不展示模式切换。

阅读列表

筛选项：

• 全部收藏。
• 未读。
• 已读摘要。
• 已读原文。
• 有笔记。
• 标签。

---

6. 用户流程

访问 /
  -> /day/{today}
  -> 浏览论文卡片
  -> 点击论文进入 /paper/{arxiv_id}
  -> 收藏 / 修改阅读状态 / 写笔记
  -> 搜索 /search?q=...
  -> 阅读列表 /reading-list

管理员流程：

POST /admin/crawl
  -> 抓取论文并入库
  -> POST /admin/summarize
  -> 生成总结
  -> POST /admin/cleanup
  -> 查看 /admin/logs

删除流程：

POST /admin/delete
  -> 校验 token 和 confirm
  -> 删除日期范围内论文、索引、用户数据、本地文件
  -> 写入删除记录和日志

---

7. MVP 验收标准

抓取

• 指定日期能抓取 HF Daily Papers 前 N 篇。
• 同一天重复抓取不会重复插入。
• 空日期返回成功状态和 0 篇日志。
• 网络失败有 timeout、重试和错误日志。

总结

• 单篇总结失败不会影响其他论文。
• 必填字段缺失时自动重试一次。
• 重试失败后标记 permanent_failure。
• 总结成功后页面、FTS 索引和 summary.json 同步更新。
• 成功或失败后都会清理 PDF/源码临时文件。

页面

• 首页能显示未总结、总结中、失败、完成状态。
• 详情页无总结时仍可阅读英文元数据。
• degraded/low 总结有清晰提示。
• 移动端不出现主要内容横向溢出。

搜索

• 能搜索标题、摘要、作者、标签、中文总结。
• 删除论文后搜索结果不再出现该论文。

管理

• 无 token 不能调用管理接口。
• token 错误返回 401。
• 删除接口没有 confirm=DELETE 时拒绝执行。
• 删除指定日期范围后，页面、搜索索引、用户数据和本地文件保持一致。

调度

• 单 worker 下每日任务只执行一次。
• 多 worker 或非本地 host 配置存在风险时，应用启动给出明确告警或拒绝启动。
• / 的 today 和每日调度日期都按 APP_TIMEZONE 计算。