# 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 根配置
├── crates/
│   ├── common/              # [Library] 物理计算引擎、子进程管理、收敛检测、种子匹配与归档白名单
│   ├── server/              # [Binary] Axum HTTP REST 服务端与 Scheduler
│   ├── node/                # [Binary] Worker 节点 Daemon 与任务抢占回路
│   └── mq/                  # [Library] SQLite 事务型分布式任务队列
├── dashboard/               # [Web] ESM 模块化运维看板（Vite）
├── workflows/sdB_cno.yaml   # 示例网格工作流配置
├── scripts/                 # 结果拉取等运维脚本
└── 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 规范**：遵循 Conventional Commits，格式为 `<type>(<scope>): <description>`，如：
   - `feat(common): 有向 CNO 距离种子匹配`
   - `fix(server): 修复调度竞态与僵尸任务自愈`
   - `type` ∈ `feat` / `fix` / `refactor` / `docs` / `test` / `chore` / `perf` / `ci`；`scope` 常用 `common` / `server` / `node` / `mq` / `dashboard` / `all`。
3. **保持文档更新**：若修改了 API 接口定义或数据库 Schema，请同步更新 `docs/api.md`、`docs/database.md`，以及物理/调度设计文档（`docs/design.md`、`docs/task_engine_decoupling_design.md`）。