Asfmq 8cc2b74abc 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 修复

2026-06-11 22:56:36 +08:00

4.1 KiB

Raw Blame History

AstroResearch Contributing Guide / 参与贡献

我们欢迎社区共同参与 AstroResearch 的开发与优化。以下是关于本地开发调试、代码规范和测试的说明。

1. 开发者本地环境搭建 (Developer Setup)

后端开发环境 (Rust)

准备 Rust 工具链 (Edition 2021)。

安装 SQLx CLI（可选，用于生成迁移文件）：

cargo install sqlx-cli --no-default-features --features sqlite

启动开发模式下的 Rust 服务：
```
cargo run
```

前端开发环境 (React + TypeScript)

进入 dashboard 目录，安装依赖：
```
cd dashboard
npm install
```
启动开发服务器（支持 HMR 热更新及 API 请求代理转发）：
```
npm run dev
```

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。
注释和系统日志建议统一使用中文，便于开发者追踪和阅读。
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 接口。

4. 测试与验证 (Testing)

运行后端单元测试

系统为各个下载、解析、词典分词、接口提取等模块设计了健全的测试。运行测试命令：

cargo test

运行前端校验

cd dashboard
npm run build   # 运行 TypeScript 类型检查及 Vite 打包编译

确保无编译 Error 或 Warn 警告后方可提交 PR。

运行健康检查工具

提交前建议对本地馆藏运行健康检查，确保功能正常：

cargo run --bin health_check

5. 数据库迁移 (Database Migrations)

添加新的数据库字段或表时，需在 migrations/ 目录下创建新的迁移脚本：

文件命名格式：YYYYMMDDHHMMSS_description.sql
迁移脚本会在 cargo run 启动时自动执行
新增字段需同时在后端 StandardPaper 结构体和前端 types.ts 中同步更新

4.1 KiB Raw Blame History Unescape Escape