init:完善项目文档并设置开发环境

- 新增贡献指南、开发指南和README的中文版本 - 创建Dev Container配置文件，包括Dockerfile、docker-compose.yml和devcontainer.json - 初始化项目结构，创建必要的目录和文件 - 设置Rust开发环境，包括依赖和工具链
2025-06-05 13:59:19 +08:00
parent 8a2011f2d0
commit 00e8d4811c
31 changed files with 731 additions and 5 deletions
--- a/GUIDE-CN.md
+++ b/GUIDE-CN.md
@@ -0,0 +1,123 @@
+# 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` 加速构建。
+
+---