# DCTS 开发者与参与贡献指南 (Contributing Guide)

> 感谢关注并参与 DCTS (Distributed Computing TLUSTY/SYNSPEC) 的开发！本文档为开发者提供本地环境配置、代码库结构说明及测试规范。

---

## 1. 本地开发环境准备

### 必备依赖
- **Rust 工具链**：1.75+ (推荐使用 `rustup` 安装)
- **C/Fortran 编译器**（计算节点模拟调试需 `gfortran` 或预编译好的二进制）
- **SQLite 3**开发库（嵌入在 Rust dependencies 中，无需额外安装系统库）

### 克隆与编译
```bash
cd dcts
cargo check --workspace --all-targets
cargo build
```

---

## 2. 代码库结构 (Workspace Layout)

```
dcts/
├── Cargo.toml               # Workspace 根配置
├── config.yaml              # 示例网格配置文件
├── crates/
│   ├── common/              # [Library] 物理计算引擎、子进程管理、收敛检测与模板
│   ├── server/              # [Binary] Axum HTTP REST 服务端与 Scheduler
│   ├── node/                # [Binary] Worker 节点 Daemon 与任务抢占回路
│   └── mq/                  # [Library] SQLite 事务型分布式任务队列
├── tools/
│   └── sync_seeds/          # [Binary] 离线/增量种子同步 CLI 工具
└── docs/                    # 分主题架构与规格技术文档
```

---

## 3. 测试与规范 (Testing & Guidelines)

### 3.1 运行单元测试与集成测试
```bash
# 运行 Workspace 内所有单元测试
cargo test --workspace

# 针对核心物理解析模块独立测试
cargo test -p common
```

### 3.2 代码风格与 Linting
提交 PR 前请确保以下命令无 error 和 warning：
```bash
# 代码格式化
cargo fmt --all -- --check

# Rust 官方 Linter 静态检查
cargo clippy --workspace --all-targets -- -D warnings
```

---

## 4. 提交 Code Review 规范

1. **分支策略**：从 `main` 切出特性分支，推荐命名如 `feature/seed-optimizer` 或 `fix/stale-node-leak`。
2. **Commit Message 规范**：格式推荐使用 `module: succinct explanation`，如：
   - `common: add tolerance factor check for seed finder`
   - `server: fix sqlite connection pool leak under heavy load`
3. **保持文档更新**：若修改了 API 接口定义或数据库 Schema，请同步更新 `docs/api_reference.md` 与 `docs/database.md`。