# 贡献指南

## 开发流程

开发按里程碑（M0 → M9）顺序推进，每个里程碑串行执行以下 8 步：

```text
1. 写开发文档（创建里程碑文档）
2. 和设计核对
3. 开发（前后端一起）
4. simplify
5. code review
6. 测试（100% 覆盖率）
7. 和设计再确认
8. 提交 + 完成里程碑
```

---

## 1. 写开发文档

每个里程碑开始前，在 `docs/milestones/` 创建里程碑文档。

**里程碑文档必须包含：**

```markdown
# M{N}: {标题}

## Context
前序阶段完成了什么，本阶段在整体产品中的位置。

## 产品边界
本阶段做什么、不做什么。

## 子任务清单
| 子任务 | 内容 | 前端/后端 | 状态 |
|--------|------|-----------|------|
| N.1 | ... | 后端 | ⬜ |
| N.2 | ... | 前端 | ⬜ |

## 子任务详细设计
...

## 设计核对点
```

---

## 2. 和设计核对

对照 `docs/PRODUCT.md` 检查：

- 是否符合产品定位（单用户、自托管）
- 架构是否一致（单二进制 + supervisor + worker）
- 文件传输是否不经过浏览器
- 是否引入了不该有的概念（RBAC、多用户）

---

## 3. 开发原则

- 文档为先，不临时改方向
- 不做文档外的大功能
- 每个 commit 只包含一个完整子功能点
- 不做一次性大提交

---

## 4. Simplify

开发完成后精简代码：

- 是否有重复代码
- 是否有过度设计
- 是否提前实现了下一阶段能力
- 是否符合 Rust workspace / Vue 功能域结构
- 是否可以把大文件拆小

---

## 5. Code Review

审查维度：

- 正确性、安全性、架构一致性
- 测试覆盖、错误处理
- 配置和密钥处理
- 审计日志
- 与里程碑文档是否一致

---

## 6. 测试

### Rust 测试

```bash
cargo fmt --check
cargo clippy --workspace --all-targets
cargo test --workspace
```

### 前端测试

```bash
bun run type-check
bun run lint
bun run build
```

### 测试原则

- 所有公开函数和关键逻辑路径必须有测试
- Rust 测试代码依赖使用 `workspace = true`
- 单元测试放在模块内 `#[cfg(test)] mod tests`
- 前端测试只验证当前功能，不依赖外部服务

---

## 7. 和设计再确认

确保：
- 实现和里程碑文档一致
- 产品语义没变
- 用户可见行为没变

---

## 8. 提交

### 提交约定

按功能拆分提交，每个 commit 只包含一个子功能点：

```bash
# ✅ 好的
git commit -m 'feat: add agent heartbeat model'
git commit -m 'feat: add agent list api'

# ❌ 不好
git commit -m 'feat: add agent management'
```

### 提交前检查

- Rust 代码必须 `cargo fmt`
- 前端 `bun run type-check` 通过
- 前端 `bun run lint` 无 error

---

## 代码规范

### Rust

- 使用 `cargo fmt` 格式化
- 使用 `cargo clippy` 检查
- 依赖使用 `workspace = true`

### 前端

- TypeScript 严格模式
- ESLint 检查
- 按功能域组织组件

---

## 项目结构

```text
docs/
  PRODUCT.md              产品功能、架构决策
  DEVELOPMENT.md          开发索引
  architecture/           架构文档
  reference/              参考文档
  milestones/             里程碑文档

crates/
  rex-common/             通用类型、错误、配置解析
  rex-hub/                Hub 二进制
  rex-agent/              Agent 二进制
  rex-ssh/                SSH/SFTP 协议
  rex-mysql/              MySQL 协议
  rex-postgresql/         PostgreSQL 协议
  rex-redis/              Redis 协议
  rex-sqlite/             SQLite 协议
  rex-s3/                 S3/MinIO 协议
  rex-transfer/           文件传输引擎

packages/
  rex-console-web/        Vue 3 前端工程
```