# 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` 计算。