fmq/AstroResearch
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
AstroResearch/docs/architecture/core-modules.md
Asfmq 5db4cc5998 refactor: 全栈架构重构与质量硬化——API 错误统一、工具域重组、安全加固、前端组件化 
后端核心变更:
  - 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 (文献信息渲染)
2026-06-25 23:45:37 +08:00

61 lines
6.0 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# AstroResearch Architecture / 架构设计
AstroResearch 是一个集成了天文学文献检索、多通道下载（含防爬绕过与手动上传）、下载错误诊断、结构化解析、中英学术对比翻译、引文星系图谱以及馆藏健康度诊断的天文科研辅助系统。
## 3. 核心模块说明
### 3.1 API 层 (`src/api/`)
| 模块文件 | 职责 |
|:---|:---|
| **[mod.rs](../src/api/mod.rs)** | 定义全局共享状态 `AppState`（含 `active_bibcode` 追踪）和统一文献格式 `StandardPaper`（含 `pdf_error` / `html_error` 诊断字段），通过 `pub mod handlers` 保持向后兼容命名空间。 |
| **[helpers.rs](../src/api/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](../src/api/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](../src/api/notes.rs)** | 笔记 CRUD 处理器：创建 (`create_note`)、查询 (`get_notes`)、删除 (`delete_note`)。 |
| **[sync.rs](../src/api/sync.rs)** | 批量同步控制处理器：元数据同步启动/状态/计数、资源同步启动/停止/状态、检索条件管理。 |
### 3.2 服务层 (`src/services/`)
| 模块文件 | 职责 |
|:---|:---|
| **[batch/mod.rs](../src/services/batch/mod.rs)** | 批量同步引擎公共导出模块。 |
| **[batch/meta.rs](../src/services/batch/meta.rs)** | 元数据大批量采集引擎 (`MetaSync`)：分页检索 ADS/arXiv 并增量入库。 |
| **[batch/asset.rs](../src/services/batch/asset.rs)** | 物理资源批量处理引擎 (`AssetSync`)：后台异步执行下载/解析/翻译流水线，记录 `download_failed` / `parse_failed` 计数，保留最新 100 条日志。 |
| **[download.rs](../src/services/download.rs)** | 多通道下载器：浏览器头伪装与请求延迟控制、ADS Link Gateway 重定向追踪与 `validate.perfdrive.com` 防护解码绕过、官方 `arxiv.org/html` 优先及 `ar5iv` 兜底、**下载失败时以 `error:` 前缀记录诊断信息至数据库**。 |
| **[parser.rs](../src/services/parser.rs)** | HTML 语法树向 GFM Markdown 逆向转换，使用占位符保护 LaTeX 公式；统一图表链接；集成 MinerU PDF 解析。 |
| **[translation.rs](../src/services/translation.rs)** | 基于本地天文双语词典的 Trie 树最长匹配分词，注入 Glossary 系统提示词让 LLM 实现学术级精细翻译。 |
| **[query_parser.rs](../src/services/query_parser.rs)** | 高级检索语法解析器，将前端组合条件（AND/OR/NOT + 字段限定）转换为 ADS API 查询语法。 |
| **[logging.rs](../src/services/logging.rs)** | 全局日志记录系统，基于 `tracing-subscriber` 实现控制台美化日志输出与基于时间的每日滚动日志文件写出，使用上海时区 (+08:00) 格式化时间。 |
### 3.3 客户端层 (`src/clients/`)
| 模块文件 | 职责 |
|:---|:---|
| **[ads.rs](../src/clients/ads.rs)** | NASA ADS API 客户端：文献检索、元数据获取、BibTeX 导出。 |
| **[arxiv.rs](../src/clients/arxiv.rs)** | arXiv Atom XML API 客户端：解析 XML Feed 提取文献元数据。 |
| **[qiniu.rs](../src/clients/qiniu.rs)** | 七牛云对象存储客户端：PDF 插图上传与 CDN 外链生成。 |
### 3.4 独立工具 (`src/bin/`)
| 文件 | 职责 |
|:---|:---|
| **[health_check.rs](../src/bin/health_check.rs)** | 馆藏健康度诊断与修复工具：检测损坏文件、丢失文件、`error:` 报错记录和孤立 Markdown；`--fix` 模式自动清理并重置数据库状态。 |
### 3.5 前端核心组件 (`dashboard/src/`)
| 目录/组件文件 | 职责 |
|:---|:---|
| **[App.tsx](../dashboard/src/App.tsx)** | 全局骨架与胶水层：鉴权外壳、Tab 持久化、挂载全局弹窗，调度各页面跨组件跳转逻辑。 |
| **[pages/SearchPanel.tsx](../dashboard/src/pages/SearchPanel.tsx)** | 统一跨源检索页面：支持高级检索构造、分页排序以及下载错误状态提示与文献类型徽章显示。 |
| **[pages/LibraryPanel.tsx](../dashboard/src/pages/LibraryPanel.tsx)** | 馆藏管理页面：展现本地馆藏列表、最近阅读、同步状态、支持下载失败和“无资源”状态筛选。 |
| **[pages/ReaderPanel.tsx](../dashboard/src/pages/ReaderPanel.tsx)** | 对照阅读器视图：以 children 组合形式装配 `BilingualViewer` 与 `ReaderNotesSidebar`。 |
| **[pages/CitationPanel.tsx](../dashboard/src/pages/CitationPanel.tsx)** | 引文星系图谱视图：装配自研 Canvas 引文拓扑力导图。 |
| **[pages/SyncPanel.tsx](../dashboard/src/pages/SyncPanel.tsx)** | 批量同步控制页面：装配元数据同步面板、流水线批量任务日志流虚拟终端。 |
| **[pages/ResearchAgentPanel.tsx](../dashboard/src/pages/ResearchAgentPanel.tsx)** | 智能科研助理页面：装配 SSE 研讨消息列表、多模式选择、思维链展示与会话侧栏。 |
| **[components/](../dashboard/src/components/)** | 通用与业务子组件：如 Canvas 引擎 ([CitationGalaxyCanvas.tsx](../dashboard/src/components/CitationGalaxyCanvas.tsx))、下拉选择 ([CustomSelect.tsx](../dashboard/src/components/CustomSelect.tsx))、学术助手侧栏、智能体对话等。 |
| **[hooks/](../dashboard/src/hooks/)** | 全局与特定页面业务逻辑状态 Hook 库（如 `useLibrary`, `useSearch`, `useReaderState`, `useSyncState`, `useResearchAgent` 等），实现数据逻辑与 UI 渲染彻底解耦。 |
| **[types/index.ts](../dashboard/src/types/index.ts)** | 全局 TypeScript 静态类型定义中心。 |
---
Reference in New Issue View Git Blame Copy Permalink