# 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` 中同步更新