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/contributing.md

@@ -30,21 +30,43 @@
 
 ---
 
-## 2. 编码规范 (Coding Style Guidelines)
+## 2. 项目结构约定 (Project Structure Conventions)
+
+### 后端模块化架构
+
+后端代码已从单文件架构重构为模块化架构：
+
+- **API 层** (`src/api/`)：按职责拆分为 `papers.rs`（文献相关）、`notes.rs`（笔记相关）、`sync.rs`（同步相关）、`helpers.rs`（共享工具），通过 `mod.rs` 统一暴露 `AppState`、`StandardPaper` 和向后兼容的 `handlers` 命名空间。
+- **服务层** (`src/services/`)：批量同步引擎从单文件 `batch_sync.rs` 拆分为 `batch/mod.rs` + `meta.rs` + `asset.rs`，同时通过 `pub mod batch_sync` 保持路径兼容。
+- **独立工具** (`src/bin/`)：`health_check.rs` 作为独立二进制程序，可直接运行。
+
+### 前端组件化架构
+
+- **可复用组件** (`components/`)：`CustomSelect` 替代所有原生 `<select>`，保持视觉一致性。
+- **功能模块** (`features/`)：按功能域划分（search、library、reader、citation、sync、settings）。
+- **类型定义** (`types.ts`)：集中管理所有接口类型，与后端 `StandardPaper` 结构体保持同步。
+
+---
+
+## 3. 编码规范 (Coding Style Guidelines)
 
 ### Rust 规范 (Backend)
 - 遵循 Rust 官方标准样式，提交前必须执行 `cargo fmt` 与 `cargo clippy`。
-- 注释和系统日志建议统一使用中文，便于开发者追踪 and 阅读。
+- 注释和系统日志建议统一使用中文，便于开发者追踪和阅读。
 - API handlers 中的异常信息请使用 `anyhow` 或 `thiserror` 进行结构化抛出。
+- **模块化原则**：API 层按职责拆分文件（papers / notes / sync / helpers），避免单文件过大（目标 <800 行）。
+- **错误诊断约定**：下载失败时使用 `error:` 前缀存入 `pdf_path` / `html_path`，便于前端和 `health_check` 工具解析。
 
 ### React & TypeScript 规范 (Frontend)
 - 严格遵循 `React 18/19` 函数式组件写法，使用 React Hooks 维护状态。
 - 为保证生产编译成功，务必开启类型安全限制（如在导入纯类型时显式使用 `import type { ... }`）。
 - CSS 层面使用 Tailwind CSS 统一的高对比度浅色纯中文控制台风格，所有布局、间距、颜色需遵循实边框、高对比度黑白字及高雅按钮样式（`.btn-console` 等），以保障学术沉浸与阅读的高保真性。
+- **下拉选择器统一使用 `CustomSelect` 组件**，不要使用原生 `<select>`。
+- **新增 API 字段**：后端 `StandardPaper` 新增字段时，必须同步更新 `dashboard/src/types.ts` 中的 `StandardPaper` 接口。
 
 ---
 
-## 3. 测试与验证 (Testing)
+## 4. 测试与验证 (Testing)
 
 ### 运行后端单元测试
 系统为各个下载、解析、词典分词、接口提取等模块设计了健全的测试。运行测试命令：
@@ -58,3 +80,18 @@ cd dashboard
 npm run build   # 运行 TypeScript 类型检查及 Vite 打包编译
 ```
 确保无编译 Error 或 Warn 警告后方可提交 PR。
+
+### 运行健康检查工具
+提交前建议对本地馆藏运行健康检查，确保功能正常：
+```bash
+cargo run --bin health_check
+```
+
+---
+
+## 5. 数据库迁移 (Database Migrations)
+
+添加新的数据库字段或表时，需在 `migrations/` 目录下创建新的迁移脚本：
+1. 文件命名格式：`YYYYMMDDHHMMSS_description.sql`
+2. 迁移脚本会在 `cargo run` 启动时自动执行
+3. 新增字段需同时在后端 `StandardPaper` 结构体和前端 `types.ts` 中同步更新