207 lines
7.8 KiB
Markdown
207 lines
7.8 KiB
Markdown
# 初始化 MRCC 项目
|
||
|
||
## Summary
|
||
|
||
将 MRCC (MineRedCircuitcraft) 从空目录初始化为完整的 monorepo 骨架，包含 Unity 客户端和 Go 后端（6 个服务），每个服务具备 `/health` 健康检查端点并可独立启动。对应开发文档 Sprint 1 的交付目标。
|
||
|
||
## Current State Analysis
|
||
|
||
| 项目 | 状态 |
|
||
|------|------|
|
||
| Git 仓库 | 已初始化，main 分支，remote: `dcp.itnet.buzz/Deaicup/MRCC` |
|
||
| 现有文件 | `README.md`、`完整开发文档.html` |
|
||
| Go | **未安装** |
|
||
| Docker | **未安装** |
|
||
| Unity CLI | 不在 PATH 中（可能已安装 Editor） |
|
||
|
||
开发文档定义的技术栈：
|
||
- 客户端: Unity 2024 LTS (C#)，8 个模块
|
||
- 后端: Go 1.22 + Gin，5 个业务微服务 + 1 个联机中转站
|
||
- 基础设施: PostgreSQL 16、Redis 7.2、MinIO、RabbitMQ 3.13
|
||
|
||
## Prerequisites
|
||
|
||
执行前需安装（可通过 dev-env-expert 辅助）：
|
||
1. **Go 1.22+** — 后端编译运行
|
||
2. **Docker Desktop** — 开发环境基础设施（PostgreSQL/Redis/MinIO/RabbitMQ）
|
||
3. **Unity 2024 LTS** — 客户端打开编辑
|
||
|
||
> 骨架代码可先创建，Go 安装后即可 `go run` 启动后端。
|
||
|
||
## Proposed Changes
|
||
|
||
### 1. 根目录文件 (4 files)
|
||
|
||
| 文件 | 内容 |
|
||
|------|------|
|
||
| `.gitignore` | Go + Unity + IDE 忽略规则合并 |
|
||
| `docker-compose.dev.yml` | PostgreSQL 16、Redis 7.2、MinIO、RabbitMQ 3.13 开发环境 |
|
||
| `Makefile` | 根目录快捷命令：`make dev`（启动基础设施）、`make build-all`、`make run-*` |
|
||
| `.github/workflows/ci.yml` | Go build + vet + test；PR 触发 |
|
||
|
||
### 2. Go 后端 (`server/`)
|
||
|
||
**Module path**: `mrcc`
|
||
|
||
```
|
||
server/
|
||
├── go.mod # module mrcc, go 1.22, deps: gin, gorilla/websocket
|
||
├── Makefile # build / run-* / tidy / lint / test
|
||
├── cmd/
|
||
│ ├── auth-service/main.go # :8081, /health
|
||
│ ├── economy-service/main.go # :8082, /health
|
||
│ ├── blueprint-service/main.go # :8083, /health
|
||
│ ├── match-service/main.go # :8084, /health
|
||
│ ├── social-service/main.go # :8085, /health
|
||
│ └── relay-server/main.go # :8086, /health + /ws WebSocket 骨架
|
||
├── internal/
|
||
│ ├── config/config.go # 环境变量加载，ServiceConfig 结构体
|
||
│ ├── logger/logger.go # slog 封装，统一日志格式
|
||
│ └── httpserver/server.go # Gin 实例工厂：CORS、Recovery、日志中间件、/health 注册
|
||
└── pkg/
|
||
└── response/response.go # 标准 JSON 响应 {code, message, data}
|
||
```
|
||
|
||
**每个业务微服务 main.go 模式**（以 auth-service 为例）：
|
||
```go
|
||
package main
|
||
|
||
import (
|
||
"log"
|
||
"mrcc/internal/config"
|
||
"mrcc/internal/httpserver"
|
||
)
|
||
|
||
func main() {
|
||
cfg := config.Load("auth-service", "8081")
|
||
srv := httpserver.New(cfg)
|
||
log.Printf("auth-service listening on :%s", cfg.Port)
|
||
if err := srv.Run(":" + cfg.Port); err != nil {
|
||
log.Fatal(err)
|
||
}
|
||
}
|
||
```
|
||
|
||
**relay-server 额外内容**：
|
||
- `/ws` WebSocket 升级端点（gorilla/websocket）
|
||
- `Room`、`Player` 结构体定义（对照文档 18.5 节）
|
||
- 连接注册/注销 channel 骨架（不实现完整逻辑）
|
||
|
||
**go.mod 依赖**（最小化）：
|
||
- `github.com/gin-gonic/gin v1.10.0`
|
||
- `github.com/gorilla/websocket v1.5.3`
|
||
|
||
### 3. Unity 客户端 (`client/`)
|
||
|
||
```
|
||
client/
|
||
├── Assets/
|
||
│ └── Scripts/
|
||
│ ├── RedCircuit.Grid/ # RedCircuit.Grid.asmdef
|
||
│ │ ├── GridCanvas.cs # 网格画布渲染
|
||
│ │ ├── ChunkManager.cs # 分块管理
|
||
│ │ └── TileRenderer.cs # 瓦片渲染
|
||
│ ├── RedCircuit.Simulation/ # RedCircuit.Simulation.asmdef
|
||
│ │ ├── SimulationLoop.cs # 仿真主循环
|
||
│ │ ├── SignalPropagator.cs # 信号传播
|
||
│ │ └── ComponentBehavior.cs # 元件行为基类
|
||
│ ├── RedCircuit.Components/ # RedCircuit.Components.asmdef
|
||
│ │ ├── ComponentRegistry.cs # 元件注册表
|
||
│ │ ├── PlacementController.cs # 放置控制器
|
||
│ │ └── ComponentData.cs # 元件数据定义
|
||
│ ├── RedCircuit.UI/ # RedCircuit.UI.asmdef
|
||
│ │ ├── EditorWindow.cs # 编辑器窗口
|
||
│ │ ├── ToolbarController.cs # 工具栏
|
||
│ │ ├── PalettePanel.cs # 元件面板
|
||
│ │ └── InspectorPanel.cs # 属性面板
|
||
│ ├── RedCircuit.Net/ # RedCircuit.Net.asmdef
|
||
│ │ ├── ApiClient.cs # REST 客户端
|
||
│ │ ├── WsClient.cs # WebSocket 客户端
|
||
│ │ └── SyncManager.cs # 同步管理
|
||
│ ├── RedCircuit.Save/ # RedCircuit.Save.asmdef
|
||
│ │ ├── SaveManager.cs # 存档管理
|
||
│ │ ├── LocalDatabase.cs # 本地 SQLite
|
||
│ │ └── CloudSync.cs # 云端同步
|
||
│ ├── RedCircuit.Audio/ # RedCircuit.Audio.asmdef
|
||
│ │ ├── AudioManager.cs # 音频管理
|
||
│ │ └── NotePlayer.cs # 音符播放
|
||
│ └── RedCircuit.Auth/ # RedCircuit.Auth.asmdef
|
||
│ ├── AuthManager.cs # 认证管理
|
||
│ ├── TokenStore.cs # Token 存储
|
||
│ └── OAuthClient.cs # OAuth 客户端
|
||
├── Packages/
|
||
│ └── manifest.json # Unity 2024 LTS 基础包
|
||
└── ProjectSettings/
|
||
└── ProjectVersion.txt # 2024.2.0f1
|
||
```
|
||
|
||
**每个 C# 脚本模式**（空骨架）：
|
||
```csharp
|
||
using UnityEngine;
|
||
|
||
namespace RedCircuit.Grid
|
||
{
|
||
/// <summary>网格画布渲染器，负责 PCB 风格网格绘制与视口裁剪。</summary>
|
||
public class GridCanvas : MonoBehaviour
|
||
{
|
||
}
|
||
}
|
||
```
|
||
|
||
**Assembly Definition (asmdef) 模式**：
|
||
```json
|
||
{
|
||
"name": "RedCircuit.Grid",
|
||
"rootNamespace": "RedCircuit.Grid",
|
||
"references": [],
|
||
"includePlatforms": [],
|
||
"excludePlatforms": [],
|
||
"allowUnsafeCode": false,
|
||
"autoReferenced": true,
|
||
"defineConstraints": []
|
||
}
|
||
```
|
||
|
||
### 4. 文件清单汇总
|
||
|
||
| 区域 | 文件数 |
|
||
|------|--------|
|
||
| 根目录 | 4 |
|
||
| server/ (Go) | 16 (go.mod, Makefile, 6×main.go, 4×internal, 1×pkg) |
|
||
| client/ (Unity) | 29 (8×asmdef, 24×cs, manifest.json, ProjectVersion.txt) |
|
||
| **合计** | **~49 files** |
|
||
|
||
## Assumptions & Decisions
|
||
|
||
1. **端口分配**: relay-server 使用 8086（文档中 8084 与 match-service 冲突，调整为 8086）
|
||
2. **Go module path**: 使用 `mrcc`（简单私有项目名，可后续改为 VCS URL）
|
||
3. **日志**: 使用标准库 `log/slog`，不引入 zap（最小化依赖）
|
||
4. **数据库连接**: 骨架阶段不连接实际数据库，docker-compose 仅供后续 Sprint 使用
|
||
5. **Unity 场景**: 不手动创建 .unity 场景文件（格式复杂且版本相关），用户在 Unity Editor 中新建
|
||
6. **.meta 文件**: 不创建 Unity .meta 文件，Unity Editor 首次打开自动生成
|
||
7. **CI**: 仅 Go 后端 CI（Unity CI 需要 Unity License，后续 Sprint 再加）
|
||
|
||
## Verification Steps
|
||
|
||
1. **Go 后端编译**:
|
||
```powershell
|
||
cd server; go mod tidy; go build ./cmd/...
|
||
```
|
||
2. **各服务启动 + 健康检查**:
|
||
```powershell
|
||
go run ./cmd/auth-service &
|
||
curl http://localhost:8081/health # 期望 {"code":0,"message":"ok"}
|
||
# 对 8082-8086 重复
|
||
```
|
||
3. **relay-server WebSocket**:
|
||
```powershell
|
||
# 连接 ws://localhost:8086/ws 应成功升级
|
||
```
|
||
4. **Unity 客户端**:
|
||
- 用 Unity Hub 打开 `client/` 文件夹
|
||
- 无编译错误，8 个 asmdef 程序集均编译通过
|
||
5. **Git 提交**:
|
||
```powershell
|
||
git add -A; git status # 确认无敏感文件
|
||
```
|