Asfmq
5db4cc5998
后端核心变更: - API 层: 新增 AppError 枚举统一错误类型，替代散落的 (StatusCode, String) - Agent 工具域: 重组为 astro/system/ 和 astro/research/ 两级域，新增 ProcessPaperTool 流水线工具 - 安全: 新增 SSRF 双层防护 (同步字符串级 + 异步 DNS 解析级)，覆盖 IPv4/IPv6 私网段 - 弱密码检测: 扩展弱密码列表并增加最小长度检查 - LLM 客户端: 新增 ChatCompleter/Embedder trait，支持依赖注入与批量向量化 embed_batch - 批量处理: AssetBatch 从串行改为 Semaphore 并发池 (BATCH_CONCURRENCY=3) - 分块器: 重写为三阶段结构化管线 (章节解析→短节合并→带标题路径子块) - RAG: embedding 计算移出事务，RetrievalResult 新增 headings/section_index 字段 - 检索: ADS/arXiv 并行检索 (tokio::join!)，去重改用 HashSet，本地库回填批量 IN 查询 - 天体查询: Sesame API 升级到 v4，新增视差误差/自行/视向速度/多波段测光字段 - 迁移: 14 个增量文件合并为单一 init.sql，支持 sqlx::migrate! 内存库集成测试 - 测试: circuit_breaker/hooks/task_board/session/memory/streaming_executor 新增修正 15+ 测试 前端架构重构: - 目录重组: features/ → pages/ + components/ + hooks/ 三层分离 - App.tsx 从 1181 行压缩至 ~174 行 (逻辑抽入 9 个自定义 Hook) - Agent 面板拆分为 AgentSessionSidebar/AgentMessageList/AgentInputArea 子组件 - 新增 GlobalDialog/PaperDetailModal/UncachedPaperModal 通用对话框组件 - 工具函数抽取: celestial.ts (天体坐标格式), paper.tsx (文献信息渲染)
6.0 KiB
6.0 KiB
AstroResearch Architecture / 架构设计
AstroResearch 是一个集成了天文学文献检索、多通道下载（含防爬绕过与手动上传）、下载错误诊断、结构化解析、中英学术对比翻译、引文星系图谱以及馆藏健康度诊断的天文科研辅助系统。
3. 核心模块说明
3.1 API 层 (src/api/)
| 模块文件 | 职责 |
|---|---|
| mod.rs | 定义全局共享状态 AppState（含 active_bibcode 追踪）和统一文献格式 StandardPaper（含 pdf_error / html_error 诊断字段），通过 pub mod handlers 保持向后兼容命名空间。 |
| helpers.rs | 共享工具函数：convert_ads_doc_to_standard、convert_arxiv_to_standard、save_paper_to_db、get_paper_from_db、check_paper_paths_in_db。负责数据库 CRUD 和 error: 前缀诊断信息的读取与解析。 |
| papers.rs | 文献相关核心处理器：统一检索 (search_papers)、下载 (download_paper)、手动上传 (upload_paper_file)、无资源标记 (mark_no_resource)、解析 (parse_paper)、翻译 (translate_paper)、引文拓扑 (get_citation_network)、文献详情 (get_paper_detail)、馆藏列表 (get_library)、BibTeX 导出 (export_citations)、活跃文献追踪 (get/set_active_bibcode)。 |
| notes.rs | 笔记 CRUD 处理器：创建 (create_note)、查询 (get_notes)、删除 (delete_note)。 |
| sync.rs | 批量同步控制处理器：元数据同步启动/状态/计数、资源同步启动/停止/状态、检索条件管理。 |
3.2 服务层 (src/services/)
| 模块文件 | 职责 |
|---|---|
| batch/mod.rs | 批量同步引擎公共导出模块。 |
| batch/meta.rs | 元数据大批量采集引擎 (MetaSync)：分页检索 ADS/arXiv 并增量入库。 |
| batch/asset.rs | 物理资源批量处理引擎 (AssetSync)：后台异步执行下载/解析/翻译流水线，记录 download_failed / parse_failed 计数，保留最新 100 条日志。 |
| download.rs | 多通道下载器：浏览器头伪装与请求延迟控制、ADS Link Gateway 重定向追踪与 validate.perfdrive.com 防护解码绕过、官方 arxiv.org/html 优先及 ar5iv 兜底、下载失败时以 error: 前缀记录诊断信息至数据库。 |
| parser.rs | HTML 语法树向 GFM Markdown 逆向转换，使用占位符保护 LaTeX 公式；统一图表链接；集成 MinerU PDF 解析。 |
| translation.rs | 基于本地天文双语词典的 Trie 树最长匹配分词，注入 Glossary 系统提示词让 LLM 实现学术级精细翻译。 |
| query_parser.rs | 高级检索语法解析器，将前端组合条件（AND/OR/NOT + 字段限定）转换为 ADS API 查询语法。 |
| logging.rs | 全局日志记录系统，基于 tracing-subscriber 实现控制台美化日志输出与基于时间的每日滚动日志文件写出，使用上海时区 (+08:00) 格式化时间。 |
3.3 客户端层 (src/clients/)
| 模块文件 | 职责 |
|---|---|
| ads.rs | NASA ADS API 客户端：文献检索、元数据获取、BibTeX 导出。 |
| arxiv.rs | arXiv Atom XML API 客户端：解析 XML Feed 提取文献元数据。 |
| qiniu.rs | 七牛云对象存储客户端：PDF 插图上传与 CDN 外链生成。 |
3.4 独立工具 (src/bin/)
| 文件 | 职责 |
|---|---|
| health_check.rs | 馆藏健康度诊断与修复工具：检测损坏文件、丢失文件、error: 报错记录和孤立 Markdown；--fix 模式自动清理并重置数据库状态。 |
3.5 前端核心组件 (dashboard/src/)
| 目录/组件文件 | 职责 |
|---|---|
| App.tsx | 全局骨架与胶水层：鉴权外壳、Tab 持久化、挂载全局弹窗，调度各页面跨组件跳转逻辑。 |
| pages/SearchPanel.tsx | 统一跨源检索页面：支持高级检索构造、分页排序以及下载错误状态提示与文献类型徽章显示。 |
| pages/LibraryPanel.tsx | 馆藏管理页面：展现本地馆藏列表、最近阅读、同步状态、支持下载失败和“无资源”状态筛选。 |
| pages/ReaderPanel.tsx | 对照阅读器视图：以 children 组合形式装配 BilingualViewer 与 ReaderNotesSidebar。 |
| pages/CitationPanel.tsx | 引文星系图谱视图：装配自研 Canvas 引文拓扑力导图。 |
| pages/SyncPanel.tsx | 批量同步控制页面：装配元数据同步面板、流水线批量任务日志流虚拟终端。 |
| pages/ResearchAgentPanel.tsx | 智能科研助理页面：装配 SSE 研讨消息列表、多模式选择、思维链展示与会话侧栏。 |
| components/ | 通用与业务子组件：如 Canvas 引擎 (CitationGalaxyCanvas.tsx)、下拉选择 (CustomSelect.tsx)、学术助手侧栏、智能体对话等。 |
| hooks/ | 全局与特定页面业务逻辑状态 Hook 库（如 useLibrary, useSearch, useReaderState, useSyncState, useResearchAgent 等），实现数据逻辑与 UI 渲染彻底解耦。 |
| types/index.ts | 全局 TypeScript 静态类型定义中心。 |