# 开发指南

## 技术栈

| 层 | 技术 |
|---|---|
| 后端 | Rust (tokio async) |
| 前端 | Vue 3 + Vite + TypeScript |
| 终端 | xterm.js |
| 通信 | WebSocket + HTTPS |
| 加密 | TLS 1.3, AES-256-GCM, ECDHE-X25519 |
| 数据库 | SQLite |

---

## Rust crate 结构

```text
crates/
├── rex-common        通用类型、错误定义、CLI、supervisor、版本、更新状态
├── rex-ssh           SSH/SFTP 协议实现
├── rex-mysql         MySQL 协议实现
├── rex-postgresql    PostgreSQL 协议实现
├── rex-redis         Redis 协议实现
├── rex-sqlite        SQLite 协议实现
├── rex-s3            S3/MinIO 协议实现
├── rex-transfer      文件传输引擎
├── rex-hub           Hub 二进制入口（整合所有 crate + 前端静态资源）
└── rex-agent         Agent 二进制入口（整合所有 crate）
```

### Hub 与 Agent 区别

```text
rex-hub   = 所有 crate + 前端静态资源（embedded）
rex-agent = 所有 crate（无前端）
```

---

## 前端工程结构

```text
packages/
└── rex-console-web/
    ├── package.json
    ├── index.html
    ├── src/
    │   ├── main.ts
    │   ├── App.vue
    │   ├── router.ts
    │   ├── api/
    │   ├── stores/
    │   ├── components/
    │   ├── layouts/
    │   ├── pages/
    │   ├── styles/
    │   └── i18n/
    ├── public/
    └── vite.config.ts
```

### 功能域组织

```text
packages/rex-console-web/src/
├── pages/          只做路由入口
├── features/       按功能域组织组件
│   ├── terminal/
│   ├── sql/
│   ├── files/
│   ├── agents/
│   ├── settings/
│   └── workspace/
├── components/     跨功能通用组件
├── api/            按接口域拆分
├── composables/    组合式函数
├── layouts/        布局组件
├── styles/         主题和全局样式
└── i18n/           国际化
```

---

## 里程碑总览

项目从 M0 到 M76，已完成 2.0 重设计：

| 里程碑 | 标题 | 状态 |
|--------|------|------|
| M0 | 项目骨架重建 | ✅ |
| M1 | 设计系统与组件库 | ✅ |
| M2 | 工作空间外壳 | ✅ |
| M3 | SSH 终端 | ✅ |
| M4 | 数据库控制台 | ✅ |
| M5 | Redis 控制台 | ✅ |
| M6 | 文件管理（SFTP+S3） | ✅ |
| M7 | 管理模块 + 打磨收尾 | ✅ |
| ... | ... | ✅ |
| M76 | Bug Fix | ✅ |

---

## 常用命令

### 环境工具

由 `.mise.toml` 管理：

```bash
mise install
```

### Rust 命令

```bash
# 格式检查
cargo fmt --check

# 代码检查
cargo clippy --workspace --all-targets

# 运行测试
cargo test --workspace
```

### 前端命令

```bash
# 进入前端目录
cd packages/rex-console-web

# 开发服务器
bun run dev

# 构建
bun run build

# 类型检查
bun run type-check

# lint
bun run lint
```

---

## Rust 依赖规则

依赖声明在根 `Cargo.toml`，crate 内使用 `workspace = true`：

```toml
# 根 Cargo.toml
[workspace.dependencies]
serde = { version = "1", features = ["derive"] }
tokio = { version = "1", features = ["full"] }
anyhow = "1"
```

```toml
# crates/rex-hub/Cargo.toml
[dependencies]
serde = { workspace = true }
tokio = { workspace = true }
anyhow = { workspace = true }
```

子 crate 不重复声明版本。

---

## 提交约定

按功能拆分提交，每个 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'
```