Rain-Bus
f1be24ab83
- Add FastAPI app with paper browsing UI and REST API - Add crawler service and database models - Add scripts for DB init and manual crawl - Add docs (api-and-ui, data-model, services) - Add requirements and project config
225 lines
5.4 KiB
Markdown
225 lines
5.4 KiB
Markdown
# 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. 管理接口
|
|
|
|
所有管理接口都需要：
|
|
|
|
```text
|
|
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` 请求体
|
|
|
|
```json
|
|
{
|
|
"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. 用户流程
|
|
|
|
```text
|
|
访问 /
|
|
-> /day/{today}
|
|
-> 浏览论文卡片
|
|
-> 点击论文进入 /paper/{arxiv_id}
|
|
-> 收藏 / 修改阅读状态 / 写笔记
|
|
-> 搜索 /search?q=...
|
|
-> 阅读列表 /reading-list
|
|
```
|
|
|
|
管理员流程：
|
|
|
|
```text
|
|
POST /admin/crawl
|
|
-> 抓取论文并入库
|
|
-> POST /admin/summarize
|
|
-> 生成总结
|
|
-> POST /admin/cleanup
|
|
-> 查看 /admin/logs
|
|
```
|
|
|
|
删除流程：
|
|
|
|
```text
|
|
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` 计算。
|