# meta-unit-core 开发指南

[English](GUIDE.md)

本指南将引导你设置 `meta-unit-core` 的开发环境，我们推荐使用 Dev Containers 以确保环境的一致性，并涵盖必要的 Rust 工具链。

---

## 1. 前提条件

在开始之前，请确保你的系统已安装以下软件：

* **Docker Desktop (或 Docker Engine)：** 运行 Dev Containers 所必需。
    * [下载 Docker Desktop](https://www.docker.com/products/docker-desktop)
* **JetBrains Gateway (用于 RustRover)：** 推荐用于远程开发的 IDE。
    * [下载 JetBrains Gateway](https://www.jetbrains.com/remote-development/gateway/)
    * 或者，你也可以使用安装了 Dev Containers 扩展的 VS Code。

---

## 2. 设置开发环境（推荐：Dev Containers）

我们使用 Dev Containers 为所有贡献者提供一致且隔离的开发环境。

1.  **克隆仓库：**
    ```bash
    git clone https://nest.doylee.cn/dao-os/meta-unit-core.git
    cd meta-unit-core
    ```

2.  **使用 JetBrains Gateway 打开：**
    * 启动 **JetBrains Gateway**。
    * 选择 **"Dev Containers"** 选项卡。
    * 点击 **"Connect to Dev Container"** 或类似选项。
    * 导航并选择 `meta-unit-core` 项目目录（你克隆仓库的位置）。JetBrains Gateway 将自动检测到 `.devcontainer/devcontainer.json` 文件。
    * 按照提示连接。Gateway 将构建容器（如果是首次连接），并打开连接到远程环境的 RustRover。

3.  **容器内的初始设置：**
    首次连接时，`.devcontainer/devcontainer.json` 中定义的 `postCreateCommand` (`cargo update && cargo check`) 将自动运行。这将获取所有 Rust 依赖项并执行初步的健全性检查。

    如果你不使用 Dev Containers，你需要手动确保以下工具已安装：
    * **Rust 工具链：** 从 [rustup.rs](https://rustup.rs/) 安装 `rustup`。
    * **WASM 目标：** 添加 WASM 目标：`rustup target add wasm32-unknown-unknown`
    * **Cargo 子命令：** 安装有用的子命令，如 `cargo-watch`、`cargo-edit`、`cargo-tarpaulin`（用于覆盖率）、`mdbook`（用于文档）。
    * **Protobuf 工具：** 如果你直接处理 `.proto` 文件（而非通过 `meta-unit-proto` 项目的构建过程），则需要 `protoc` 编译器和 `protoc-gen-prost`（用于 Rust 代码生成）。

---

## 3. 构建项目

进入 Dev Container 后，你可以构建项目：

```bash
cargo build
```

以发布模式（优化性能）构建：

```bash
cargo build --release
```

---

## 4. 运行测试

我们优先采用测试驱动开发 (TDD)。运行所有测试：

```bash
cargo test
```

运行特定测试：

```bash
cargo test <测试名称或正则表达式>
```

---

## 5. 格式化和代码检查

在提交代码之前，请确保它符合我们的代码风格并通过了代码检查：

```bash
cargo fmt --all -- --check # 检查格式而不应用更改
cargo fmt --all           # 应用格式更改

cargo clippy --all-targets --all-features -- -D warnings # 运行 linter，将所有警告视为错误
```

---

## 6. 贡献工作流（基于主干开发）

我们遵循**基于主干开发 (Trunk-Based Development - TBD)** 的工作流：

1.  **拉取最新主干代码：** 始终从 `main` 分支拉取最新更改。
    ```bash
    git pull origin main
    ```
2.  **创建短生命周期的特性分支：** 为了你的本地开发，创建一个新分支。这个分支应该很快合并回 `main`。
    ```bash
    git checkout -b my-feature-branch
    ```
3.  **开发与测试 (TDD)：** 进行小而原子性的提交。先编写测试，然后编写代码使其通过。
4.  **推送并创建拉取请求 (PR)：** 推送你的分支并在 Gitea 上向 `main` 分支发起拉取请求。
    ```bash
    git push origin my-feature-branch
    ```
5.  **快速审查与合并：** 你的 PR 将被快速审查。一旦通过批准且 CI 通过，它将被合并到 `main`。
6.  **使用特性开关：** 对于较大或未完成的特性，直接提交到 `main`，但用 [特性开关 (feature flags)](https://docs.rs/feature-flags/latest/feature_flags/) 包裹新代码。这确保 `main` 始终保持可发布状态。

---

## 7. 故障排除

* **容器构建失败：** 检查 `meta-unit-core/.devcontainer/Dockerfile` 和 `docker-compose.yml` 是否有语法错误。确保 Docker Desktop 正在运行并有足够的资源。
* **"No such file or directory" for `Dockerfile`：** 仔细检查 `Dockerfile`、`docker-compose.yml` 和 `devcontainer.json` 是否都在 `meta-unit-core/.devcontainer/` 目录下，并确保 `docker-compose.yml` 的 `build` 上下文设置正确（`context: .` 和 `dockerfile: Dockerfile`）。
* **容器内权限错误：** 确保容器内部运行的用户（如果不是 root）对挂载的 `/app` 目录具有适当的权限。你可能需要调整宿主机上该目录的所有权/权限。
* **`cargo build` 慢：** 确保 Docker Desktop 分配了足够的 CPU 和内存。可以考虑使用 `sccache` 加速构建。

---