Asfmq
8cc2b74abc
后端：
- 将 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 修复
98 lines
4.1 KiB
Markdown
98 lines
4.1 KiB
Markdown
# AstroResearch Contributing Guide / 参与贡献
|
||
|
||
我们欢迎社区共同参与 AstroResearch 的开发与优化。以下是关于本地开发调试、代码规范和测试的说明。
|
||
|
||
---
|
||
|
||
## 1. 开发者本地环境搭建 (Developer Setup)
|
||
|
||
### 后端开发环境 (Rust)
|
||
1. 准备 Rust 工具链 (Edition 2021)。
|
||
2. 安装 SQLx CLI（可选，用于生成迁移文件）：
|
||
```bash
|
||
cargo install sqlx-cli --no-default-features --features sqlite
|
||
```
|
||
3. 启动开发模式下的 Rust 服务：
|
||
```bash
|
||
cargo run
|
||
```
|
||
|
||
### 前端开发环境 (React + TypeScript)
|
||
1. 进入 `dashboard` 目录，安装依赖：
|
||
```bash
|
||
cd dashboard
|
||
npm install
|
||
```
|
||
2. 启动开发服务器（支持 HMR 热更新及 API 请求代理转发）：
|
||
```bash
|
||
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)
|
||
|
||
### 运行后端单元测试
|
||
系统为各个下载、解析、词典分词、接口提取等模块设计了健全的测试。运行测试命令：
|
||
```bash
|
||
cargo test
|
||
```
|
||
|
||
### 运行前端校验
|
||
```bash
|
||
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` 中同步更新
|