# AstroResearch Contributing Guide / 参与贡献

我们欢迎社区共同参与 AstroResearch 的开发与优化。

环境搭建和项目结构详见 **[开发指南](development.md)**。

---

## 1. 项目结构约定 (Project Structure Conventions)

---

## 2. 编码规范 (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` 接口。

---

## 3. 测试与验证 (Testing)

### 运行后端单元测试
系统为各个下载、解析、词典分词、接口提取等模块设计了健全的测试。运行测试命令：
```bash
cargo test
```

### 运行前端校验
```bash
cd dashboard
npm run build   # 运行 TypeScript 类型检查及 Vite 打包编译
```
确保无编译 Error 或 Warn 警告后方可提交 PR。

### 运行健康检查工具
提交前建议对本地馆藏运行健康检查，确保功能正常：
```bash
cargo run --bin health_check
```

---

## 4. 数据库迁移 (Database Migrations)

添加新的数据库字段或表时，需在 `migrations/` 目录下创建新的迁移脚本：
1. 文件命名格式：`YYYYMMDDHHMMSS_description.sql`
2. 迁移脚本会在 `cargo run` 启动时自动执行
3. 新增字段需同时在后端 `StandardPaper` 结构体和前端 `types.ts` 中同步更新