refactor!: 模块化拆分 src 结构，新增批量同步服务、查询解析器及前端分页/高级检索功能

- src/ 按 clients/services/api 分层，Config 提升至 crate 根 - 新增 batch_sync.rs（双源并行收割）、query_parser.rs（多平台检索式转换） - build.rs 自动触发前端 npm install & build - SearchPanel 支持分页/排序/每页条数/高级检索构建器，前端加入搜索缓存 - 新增 SyncPanel 替换 SettingsPanel；新增 live_search 集成测试
2026-06-09 10:29:24 +08:00
parent 307a1c0cee
commit e13fa2ad40
27 changed files with 4115 additions and 207 deletions
@@ -51,14 +51,19 @@ export interface NoteRecord {
 - **Query Parameters**:
  - `q` (string, required): 检索关键词。
  - `source` (string, optional): 指定源，取值为 `all` | `ads` | `arxiv`，默认 `all`。
-  - `rows` (number, optional): 返回条数限制。
+  - `rows` (number, optional): 返回条数限制，默认 10。
+  - `start` (number, optional): 分页起始偏移量，默认 0。
+  - `sort` (string, optional): 排序字段，取值为 `relevance` | `date_desc` | `date_asc` | `citations_desc`，默认 `relevance`。
 - **Response Schema (`Vec<StandardPaper>`)**:
  - HTTP `200 OK`
 - **cURL 示例**:
  ```bash
  curl -G "http://localhost:8000/api/search" \
    --data-urlencode "q=Hertzsprung-Russell diagram" \
-    --data-urlencode "source=all"
+    --data-urlencode "source=all" \
+    --data-urlencode "start=0" \
+    --data-urlencode "rows=10" \
+    --data-urlencode "sort=citations_desc"
  ```

 #### 2.1.2 批量引文 BibTeX 导出
@@ -263,6 +268,117 @@ export interface NoteRecord {

 ---

+### 2.6 批量同步与文献处理模块 (Batch Sync & Processing)
+
+#### 2.6.1 预估元数据同步匹配总量
+- **Endpoint**: `GET /api/sync/meta/count`
+- **Description**: 向 ADS 或 arXiv 发送带 rows=0 的检索请求，快速获取该关键词匹配到的文献总量，而不拉取实际正文。
+- **Query Parameters**:
+  - `q` (string, required): 检索词。
+  - `source` (string, required): 数据源，支持 `all` | `ads` | `arxiv`。
+- **Response Schema**:
+  ```json
+  {
+    "total": 1285
+  }
+  ```
+- **cURL 示例**:
+  ```bash
+  curl -G "http://localhost:8000/api/sync/meta/count" \
+    --data-urlencode "q=hot subdwarf" \
+    --data-urlencode "source=all"
+  ```
+
+#### 2.6.2 启动后台元数据同步
+- **Endpoint**: `POST /api/sync/meta/run`
+- **Description**: 后台异步启动对指定关键词的文献元数据的大批量增量检索与同步入库。
+- **Request Body**:
+  ```json
+  {
+    "q": "hot subdwarf",
+    "source": "all",
+    "limit": 200
+  }
+  ```
+- **Response Schema**: Returns HTTP `200 OK` (plain text success message).
+- **cURL 示例**:
+  ```bash
+  curl -X POST "http://localhost:8000/api/sync/meta/run" \
+    -H "Content-Type: application/json" \
+    -d '{"q": "hot subdwarf", "source": "all", "limit": 200}'
+  ```
+
+#### 2.6.3 查询元数据同步运行状态与进度
+- **Endpoint**: `GET /api/sync/meta/status`
+- **Description**: 获取当前后台正在运行或最近一次运行的元数据同步任务的详细状态和进度百分比。
+- **Response Schema**:
+  ```json
+  {
+    "active": false,
+    "query": "hot subdwarf",
+    "source": "all",
+    "synced": 200,
+    "total": 200
+  }
+  ```
+- **cURL 示例**:
+  ```bash
+  curl "http://localhost:8000/api/sync/meta/status"
+  ```
+
+#### 2.6.4 启动后台文献资源批量下载/解析
+- **Endpoint**: `POST /api/sync/asset/run`
+- **Description**: 后台异步启动文献物理资源 (PDF/HTML) 的批量下载及结构化 Markdown 转换任务。
+- **Request Body**:
+  ```json
+  {
+    "action": "all",  // "all" (下载并解析) | "download" (仅下载) | "parse" (仅解析)
+    "scope": "undownloaded"  // "all" (全部) | "undownloaded" (仅未下载) | "unparsed" (仅未解析)
+  }
+  ```
+- **Response Schema**: Returns HTTP `200 OK` (plain text success message).
+- **cURL 示例**:
+  ```bash
+  curl -X POST "http://localhost:8000/api/sync/asset/run" \
+    -H "Content-Type: application/json" \
+    -d '{"action": "all", "scope": "undownloaded"}'
+  ```
+
+#### 2.6.5 停止正在运行的物理资源处理任务
+- **Endpoint**: `POST /api/sync/asset/stop`
+- **Description**: 中断并停止当前后台正在执行的批量下载与解析流水线任务。
+- **Response Schema**: Returns HTTP `200 OK` (plain text status message).
+- **cURL 示例**:
+  ```bash
+  curl -X POST "http://localhost:8000/api/sync/asset/stop"
+  ```
+
+#### 2.6.6 查询批量处理任务状态与日志
+- **Endpoint**: `GET /api/sync/asset/status`
+- **Description**: 获取当前后台批量下载与解析任务的状态、总匹配文献数、已下载数、已解析数、当前处理的 Bibcode，以及实时流转的终端日志（最多保留最新 1000 行）。
+- **Response Schema**:
+  ```json
+  {
+    "active": false,
+    "total": 12,
+    "downloaded": 12,
+    "parsed": 12,
+    "current_bibcode": "2020A&A...635A..38C",
+    "logs": [
+      "[INFO] 批量处理任务初始化成功",
+      "[INFO] 开始下载文献: 2020A&A...635A..38C...",
+      "[INFO] 文献 2020A&A...635A..38C 下载完成"
+    ],
+    "action": "all"
+  }
+  ```
+- **cURL 示例**:
+  ```bash
+  curl "http://localhost:8000/api/sync/asset/status"
+  ```
+
+---
+
 ## 3. 常见 HTTP 状态码与异常处理 (Error Codes)

 系统基于标准的 HTTP Status Codes 返回错误原因，响应的 Response Body 中通常为纯文本提示（String）：
@@ -16,11 +16,12 @@ graph TD

    subgraph Backend ["Rust Axum 后端 (Port 8000)"]
        Router[Axum 路由与中间件]
-        Handlers[业务处理器 handlers.rs]
-        Parser[解析器 parser.rs]
-        Downloader[下载器 download.rs]
-        Translator[翻译器 translation.rs]
-        Qiniu[七牛云客户端 qiniu.rs]
+        Handlers[业务处理器 api/handlers.rs]
+        Sync[同步器 services/batch_sync.rs]
+        Parser[解析器 services/parser.rs]
+        Downloader[下载器 services/download.rs]
+        Translator[翻译器 services/translation.rs]
+        Qiniu[七牛云客户端 clients/qiniu.rs]
        DB[("SQLite / astro_research.db")]
    end

@@ -37,9 +38,14 @@ graph TD
    Router --> Handlers
    
    Handlers -->|查询/保存元数据| DB
-    Handlers -->|文献下载| Downloader
-    Handlers -->|结构化清洗| Parser
-    Handlers -->|LLM学术翻译| Translator
+    Handlers -->|文献下载/解析/翻译| Handlers
+    Handlers -->|批量操作| Sync
+    
+    Sync -->|元数据同步| ADS
+    Sync -->|元数据同步| arXiv
+    Sync -->|批量文件下载| Downloader
+    Sync -->|批量正文解析| Parser
+    Sync -->|写库记录| DB
    
    Downloader -->|代理请求| ADS
    Downloader -->|直连或 ar5iv| arXiv
@@ -214,14 +220,18 @@ sequenceDiagram

 ## 3. 核心模块说明

- **[src/download.rs](../src/download.rs)**:
+- **[src/api/handlers.rs](../src/api/handlers.rs)**:
+  - 处理 Axum API 路由分发与业务逻辑，包括统一检索、笔记管理、划词高亮及翻译。
+- **[src/services/batch_sync.rs](../src/services/batch_sync.rs)**:
+  - 核心后台大批量文献元数据采集 (`MetaSync`) 与文献物理资源批量处理 (`AssetSync`) 的业务同步引擎。
+- **[src/services/download.rs](../src/services/download.rs)**:
  - 包含浏览器头伪装与请求延迟控制。
  - 处理 ADS Link Gateway 路由重定向追踪与 `validate.perfdrive.com` 防护解码绕过。
  - 实现官方 `arxiv.org/html` 优先及 `ar5iv` 兜底，自动去除版本号后缀。
- **[src/parser.rs](../src/parser.rs)**:
+- **[src/services/parser.rs](../src/services/parser.rs)**:
  - 实现 HTML 语法树向 GFM Markdown 的逆向转换，使用占位符保护机制防止 MathJax/LaTeX 公式被误解析。
  - 统一相对图表链接，并集成 MinerU PDF 解析。
- **[src/translation.rs](../src/translation.rs)**:
+- **[src/services/translation.rs](../src/services/translation.rs)**:
  - 利用本地千万字级别的天文学双语词典对原文进行分词匹配，注入系统提示词让 LLM 实现学术级精细翻译。
 - **[dashboard/src/components/CitationGalaxyCanvas.tsx](../dashboard/src/components/CitationGalaxyCanvas.tsx)**:
  - 基于原生 HTML5 Canvas 开发的轻量级、高性能力导向图星系物理引擎，用于文献引文网络拓扑结构的可视化渲染。