feat: 手动上传绕防爬、下载错误诊断与健康检查工具；模块化重构 API 与批量同步

后端：
  - 将 handlers.rs (1338行) 拆分为 helpers/papers/notes/sync 四模块
  - 将 batch_sync.rs 拆分为 batch/{mod,meta,asset} 三模块
  - 新增 POST /api/upload 多部件文件上传接口
  - 新增 POST /api/no_resource 标记文献"无全文资源"
  - 新增 GET/POST /api/active_bibcode 追踪活跃文献
  - StandardPaper 结构体扩展 pdf_error / html_error 错误诊断字段
  - download.rs 记录下载失败详情至数据库
  - 新增 health_check 二进制工具，支持只读扫描与 --fix 自动修复
  - 移除 scratch/ 目录、recovered_handlers.rs 及调试日志

  前端：
  - 新建 CustomSelect 可复用组件，替换全部原生 select
  - LibraryPanel：同步按钮反馈动画、下载失败/无资源状态筛选与计数、
    文献类型筛选、状态优先排序、搜索一键清空
  - 详情弹窗：错误诊断展示、手动 PDF/HTML 上传区、无资源标记/恢复
  - SearchPanel：扩展文献类型徽章、下载失败状态提示
  - SyncPanel：同步启动乐观 UI 更新、日志容器内自动滚动
  - Tab 状态 localStorage 持久化、弹窗 z-index 修复

docs/deployment.md

@@ -32,6 +32,13 @@ cargo build --release
 ```
 编译产物位于 `target/release/astroresearch`。
 
+### 步骤 3（可选）：编译健康检查工具
+如需在目标服务器上运行馆藏健康度诊断与修复：
+```bash
+cargo build --release --bin health_check
+```
+编译产物位于 `target/release/health_check`。
+
 ---
 
 ## 3. 服务部署与启动 (Running in Production)
@@ -44,3 +51,39 @@ cargo build --release
    ./astroresearch
    ```
 5. 进程将默认在后台启动并监听 `http://localhost:8000` 端口。你可以通过 Nginx 将此端口反向代理到公网 80/443 端口。
+
+---
+
+## 4. 环境变量配置 (Environment Variables)
+
+| 变量名 | 必需 | 默认值 | 说明 |
+|:---|:---|:---|:---|
+| `DATABASE_URL` | 否 | `sqlite://library/astro_research.db` | SQLite 数据库连接 URL |
+| `ADS_API_KEY` | 是 | - | NASA ADS API 访问 Token |
+| `LLM_API_KEY` | 是 | - | 大语言模型 API Key |
+| `LLM_API_BASE` | 否 | `https://api.openai.com/v1` | 大语言模型 API 基础地址 |
+| `LLM_MODEL` | 否 | `gpt-4o-mini` | 翻译大模型名称 |
+| `QINIU_AK` | 否 | - | 七牛云 Access Key |
+| `QINIU_SK` | 否 | - | 七牛云 Secret Key |
+| `QINIU_BUCKET` | 否 | - | 七牛云存储空间名 |
+| `QINIU_DOMAIN` | 否 | - | 七牛云外链 CDN 域名 |
+| `MINERU_API_URL` | 否 | - | MinerU PDF 解析远程 API 地址 |
+| `MINERU_API_KEY` | 否 | - | MinerU API Token |
+| `LIBRARY_DIR` | 否 | `./library` | 本地文献馆藏根目录 |
+| `PORT` | 否 | `8000` | 后端服务监听端口 |
+
+---
+
+## 5. 健康检查与维护 (Health Check)
+
+部署后可定期运行健康检查工具排查馆藏一致性问题：
+
+```bash
+# 只读扫描（不修改任何数据）
+./health_check
+
+# 自动修复（清理损坏文件、重置无效路径）
+./health_check -- --fix
+```
+
+详见 [排障指南 §4.2](troubleshooting.md#42-馆藏文献健康度检查工具-health_check)。