# 项目设计审查与优化建议 本文档汇总对当前项目的系统设计、流程设计和代码结构的审查结论。重点不在局部代码风格，而在后续稳定运行、失败恢复、数据一致性、可维护性和扩展性。 ## 总体评价 项目当前结构整体清晰：FastAPI 路由层较薄，主要业务放在 `app/services/`；抓取、总结、搜索、个人数据、管理后台等能力已有模块化拆分；SQLite + FTS5 对本地个人论文导览站是合理选择。 主要风险集中在以下几类： - 长任务生命周期没有统一抽象。 - Pipeline 不是显式状态机，阶段结果难以恢复和追踪。 - 数据库、文件系统、FTS5、ChromaDB 之间存在多处手工同步。 - Web、CLI、Scheduler 三个入口的业务策略存在分叉风险。 - 失败恢复和可观测性不足。 - 部分同步阻塞任务混入 async Web 流程。 ## 高优先级问题 ### 1. 缺少统一的任务系统 当前有三套入口都能触发重任务： - Web 管理后台：`/admin/trigger-pipeline`、`/admin/summarize` - APScheduler：每日自动 pipeline - CLI：`app.cli crawl/summarize` 它们共享部分 service，但没有统一的“任务创建、排队、运行、重试、取消、状态查询、失败恢复”模型。 影响： - Web 请求会长时间挂住。 - CLI、Web、Scheduler 的行为可能逐渐分叉。 - 任务卡死后只能看到粗粒度的 running lock。 - 前端难以展示阶段进度。 - 后续增加重跑、取消、恢复、并发限制会越来越复杂。 建议： 引入统一 Job 模型： ```text 入口层 -> 创建 Job -> Worker 执行 Job -> JobEvent 记录进度 -> 页面/API 查询状态 ``` 建议任务类型： - `crawl_daily` - `summarize_one` - `summarize_batch` - `pipeline_daily` - `refresh_upvotes` - `delete_range` - `reindex_fts` - `reindex_chroma` - `extract_images` 建议表结构方向： - `jobs`: 任务主记录，包含 `id/type/status/owner/created_at/started_at/completed_at/error` - `job_events`: 阶段事件，包含 `job_id/stage/status/message/payload_json/created_at` - `paper_processing_runs`: 单篇论文处理记录，适合跟踪总结、图片提取、索引状态 ### 2. Pipeline 不是显式状态机 当前 pipeline 基本是线性函数： ```text crawl -> summarize -> cleanup ``` 阶段输出没有被建模成可查询、可重放、可补偿的状态。 影响： - crawl 成功但 summarize 部分失败时，整体状态表达不够精确。 - cleanup 失败是否影响 pipeline 成败语义不清。 - “今天无数据回退昨天”是隐式逻辑，不是可配置策略。 - 图片提取、ChromaDB 索引失败被吞掉，用户无法知道哪些增强能力缺失。 建议： 将 pipeline 改为显式阶段状态： ```text created -> crawling -> crawled -> summarizing -> summarized | summarized_partial -> postprocessing -> completed | failed | cancelled ``` 每个阶段记录： - 输入参数 - 输出统计 - 错误类型 - 错误摘要 - 开始/结束时间 - 是否可重试 这样可以支持只重跑失败阶段，例如只重跑 ChromaDB 索引、只重跑图片提取、只重跑失败论文总结。 ### 3. 数据生命周期没有清晰分层 项目中至少有四类数据： - 主数据：`papers`、`authors`、`tags`、`summaries`、用户笔记/收藏/阅读状态 - 派生索引：FTS5、ChromaDB - 长期资产：`data/papers/{arxiv_id}` 下的 summary、raw output、images - 临时资产：`data/tmp/{arxiv_id}` 下的 PDF、源码、中间文件 现在这些数据由不同流程手动维护。删除、总结、重建索引、清理临时目录都分散在不同模块中。 影响： - DB 与文件系统可能不一致。 - DB 与 FTS5/ChromaDB 可能不一致。 - 删除流程中一部分资源删除成功、一部分失败时难以恢复。 - 很难判断某篇论文是否“完整可用”。 建议： 明确数据权威源： - DB 是权威源。 - FTS5、ChromaDB、summary.json、raw_output.txt、images 都应视为可重建派生物。 - 删除主数据优先保证 DB 状态正确，派生物清理可以异步补偿。 - 提供派生数据重建任务。 建议增加命令或任务： ```text rebuild-derived --fts rebuild-derived --chroma rebuild-derived --files rebuild-derived --images ``` ### 4. 数据库与文件系统存在双写一致性风险 总结持久化流程会写文件、写 DB、更新状态、提取图片、写 ChromaDB。任一步失败都可能留下不一致状态。 典型风险： - 文件已写入，但 DB 未提交。 - DB 标记 done，但 summary.json 缺失。 - DB done，但图片未提取或 ChromaDB 未索引。 - 重新总结时旧图片或旧 figures 残留。 建议： - 将结构化总结以 DB 为准，JSON 文件作为导出/缓存。 - 文件写入使用临时文件加原子 rename。 - DB 中记录派生物状态，例如： - `summary_persisted_at` - `fts_indexed_at` - `chroma_indexed_at` - `images_extracted_at` - `derived_error` - 提供一致性检查任务，扫描 DB 与文件/索引差异并修复。 ### 5. 失败恢复设计偏弱 当前失败主要依赖： - `summary_status.status` - `retry_count` - `task_locks` - `crawl_logs` 但对以下情况支持不足： - 进程崩溃后 `processing` 永久残留。 - `task_locks` 中 running lock 永久残留。 - 任务执行到一半，部分文件或索引已经写入。 - 某些后处理失败但主任务显示成功。 建议： - `task_locks` 增加 `heartbeat_at` 或 `expires_at`。 - 应用启动时扫描 stale running task，标记为 `failed/stale`。 - `summary_status` 增加更细阶段字段，例如： - `downloading_pdf` - `generating` - `validating` - `persisting` - `extracting_images` - `indexing` - 区分主流程失败和派生增强失败。 ### 6. 长任务直接跑在 Web 请求里 管理端触发 pipeline、批量总结、刷新 upvotes、删除数据时，会在请求生命周期内直接执行重任务。 影响： - HTTP 请求容易超时。 - 用户关闭页面后任务状态不清晰。 - Web 进程被重任务占用。 - 后续很难做取消、进度展示和失败恢复。 建议： - Web 只创建 job 并返回 `task_id`。 - 后台 worker 执行任务。 - 管理页面轮询 `/admin/jobs/{id}` 或使用 SSE 展示进度。 ## 中优先级问题 ### 7. FTS5 索引手工维护，容易漂移 `papers_fts` 是独立虚拟表。插入论文、更新总结、删除论文时手动同步。 影响： - 已有论文的 title、abstract、authors、tags 更新时可能不同步。 - AI 标签新增后，如果没有统一重建，搜索结果可能缺字段。 - 删除或回滚失败后索引可能残留。 建议： - 封装统一的 `reindex_paper(db, paper_id)`。 - 所有修改论文、标签、总结的路径最后调用它。 - 提供全量 `reindex_fts` 任务。 - 或用 SQLite trigger 维护基础字段，但总结字段仍建议通过统一函数更新。 ### 8. ChromaDB 索引缺少系统级一致性策略 ChromaDB 当前是可选增强能力，索引失败会被日志吞掉，不影响总结主流程。 影响： - 语义搜索可用性不透明。 - 某些论文 DB done，但未进入 ChromaDB。 - 删除或重建时可能出现残留索引。 建议： - 将 ChromaDB 明确视为派生索引。 - DB 中记录 `chroma_indexed_at` 和 `chroma_error`。 - 提供 `reindex_chroma` 任务。 - 搜索页或管理后台展示语义索引健康状态。 ### 9. 同步阻塞操作混入 async 主流程 部分 async 函数内部调用同步阻塞操作，例如 PDF 下载使用 `requests`，图片提取和 PDF 解析也都是同步重任务。 影响： - FastAPI event loop 可能被阻塞。 - 多篇并发总结时吞吐不可控。 - Web 服务响应受后台任务影响。 建议： - 最佳方案：重任务移到 worker 进程。 - 过渡方案：对同步阻塞段使用 `asyncio.to_thread()`。 - PDF 下载统一使用 `httpx.AsyncClient` 或明确放入同步 worker。 ### 10. 调度策略和业务流程耦合 Scheduler 固定每日 pipeline 加 30 分钟 upvote refresh；pipeline 内部固定“今天无数据回退昨天”。 影响： - 策略不易测试和调整。 - CLI、Web、Scheduler 可能各自实现不同 fallback。 - 后续支持日期范围、补抓、只总结新增论文会变复杂。 建议将策略配置化： - `crawl_target_policy`: `today` / `today_then_yesterday` / `date_range` - `summarize_scope`: `new_only` / `pending_and_failed` / `date_range` - `cleanup_policy`: `after_success` / `always` / `manual` - `upvote_refresh_window_days` - `pipeline_on_partial_failure`: `continue` / `stop` ### 11. 内嵌 APScheduler 对部署形态敏感 当前调度器嵌入 Web 进程，且多 worker 时只是打印警告。 影响： - 多 worker、多进程、reload 模式下可能重复或漏跑任务。 - Web 进程重启会影响调度可靠性。 - 调度状态和任务执行状态耦合。 建议： - 本地单机可以保留内嵌调度器。 - 长期运行建议拆为独立 scheduler 进程。 - scheduler 只负责创建 job，不直接执行重任务。 - Web 管理后台只展示 scheduler/job 状态。 ### 12. 运行时迁移能力不足 当前 `_migrate()` 只支持补列。 影响： - 无法可靠处理索引、约束、字段改名、数据回填。 - 数据库结构演进不可追踪。 - 生产或长期本地数据升级风险高。 建议： - 引入 Alembic。 - 将 FTS5、索引、部分约束和数据回填纳入迁移脚本。 - 启动时不要静默做复杂迁移，改为显式执行迁移命令。 ## 低到中优先级问题 ### 13. 配置校验不足 当前配置字段主要是裸类型，缺少合法值和组合校验。 风险示例： - `SUMMARY_BACKEND` 填错。 - `SUMMARY_PDF_MODE` 填错。 - `SCHEDULE_MINUTE + 30` 超过 59。 - `APP_WORKERS > 1` 且 `SCHEDULER_ENABLED=true`。 - `CHROMA_ENABLED=true` 但 embedding 配置缺失。 建议： - 使用 Pydantic validator 校验枚举值和组合条件。 - 对危险组合启动时报错，而不是只 warning。 ### 14. 私有函数跨模块调用说明模块边界不稳定 例如 `summarizer.py` 调用 `_generate_with_retry`、`_persist_summary` 等下划线函数。 影响： - 模块公开边界不清晰。 - 后续重构容易误伤。 - 测试和替换后端不方便。 建议： - 为 summary 生成、持久化、后处理定义明确公开 API。 - 下划线函数保留为模块内部实现细节。 - 引入更明确的 service 类或函数边界，例如： - `SummaryGenerator.generate()` - `SummaryRepository.save()` - `DerivedAssetBuilder.extract_images()` ### 15. 外部依赖缺少统一 adapter 项目依赖多个外部系统： - HuggingFace API - arXiv PDF/source 下载 - `pi` CLI - `claude` CLI - Embedding API - ChromaDB - ONNX layout detector 建议： - 为每类外部依赖定义 adapter。 - 统一 timeout、retry、error classification、metrics。 - 测试中替换 adapter，而不是 patch 深层函数。 ### 16. 删除流程事务边界不理想 删除流程中同时删除 FTS5、ChromaDB、本地文件、临时文件、ORM 数据。 影响： - 文件删除成功后 DB rollback，会造成数据仍在但文件丢失。 - DB 删除成功后 ChromaDB 删除失败，会造成残留索引。 - 单篇失败时 rollback 可能影响之前 flush 的状态，逻辑不直观。 建议： - 删除主数据与删除派生物分两阶段。 - DB 删除成功后创建派生清理 job。 - 派生物清理失败可重试，不影响主数据一致性。 ## 建议目标架构 如果项目定位是个人本地工具，可以采用轻量目标架构： ```text FastAPI Web - 页面和 API - 管理后台 - 创建 job - 查询 job 状态 Scheduler - 按策略创建 job - 不直接跑重任务 Worker - crawl - summarize - PDF download - image extraction - FTS/Chroma reindex - cleanup/delete Storage/Repository - DB 权威数据 - 文件资产管理 - 派生索引重建 - 一致性检查 ``` 如果暂时不想引入独立 worker，也可以先在单进程内实现 Job 表和后台任务执行器。这样至少能统一任务状态和恢复机制。 ## 推荐实施顺序 ### 第一阶段：先解决任务与状态 目标：降低长任务不可控风险。 - 新增 `jobs` 和 `job_events` 表。 - Web 管理动作改为创建 job 并返回 task_id。 - Scheduler 改为创建 job。 - CLI 复用同一套 job runner。 - 加 stale running job 恢复逻辑。 ### 第二阶段：统一派生数据管理 目标：降低 DB、文件、FTS、Chroma 不一致风险。 - 明确 DB 为权威源。 - 封装 `reindex_paper()`。 - 增加 `reindex_fts`、`reindex_chroma` 任务。 - 增加派生数据状态字段或健康检查。 - 删除流程改为 DB 主删除 + 派生清理 job。 ### 第三阶段：改造 pipeline 为状态机 目标：让任务可恢复、可补偿、可观测。 - 拆分 pipeline stages。 - 每个 stage 记录输入/输出/错误/耗时。 - 支持从失败阶段重跑。 - 将 fallback 策略配置化。 ### 第四阶段：提升运行可靠性 目标：长期运行更稳。 - 引入 Alembic。 - 配置加 validator。 - 同步阻塞操作移出 Web event loop。 - 外部依赖 adapter 化。 - 管理后台展示任务、派生索引、失败类型、耗时统计。 ## 最小可行改造方案 如果只做最小但收益最大的改动，建议优先做这三项： 1. 增加统一 Job 表和 job runner。 2. DB 作为权威源，FTS/Chroma/文件全部按派生物处理。 3. 增加 stale task 恢复和派生数据重建命令。 这三项能显著降低后续复杂度，也不会强迫项目马上拆成多个服务。