feat: initial project structure

- 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
2026-06-05 21:56:40 +08:00
commit f1be24ab83
26 changed files with 2557 additions and 0 deletions
@@ -0,0 +1,224 @@
+# 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` 计算。