MRCC/.trae/documents/initialize-mrcc-project.md

初始化 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 为例）：

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# 脚本模式（空骨架）：

using UnityEngine;

namespace RedCircuit.Grid
{
    /// <summary>网格画布渲染器，负责 PCB 风格网格绘制与视口裁剪。</summary>
    public class GridCanvas : MonoBehaviour
    {
    }
}

Assembly Definition (asmdef) 模式：

{
    "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 后端编译:

   cd server; go mod tidy; go build ./cmd/...
   

2. 各服务启动 + 健康检查:

   go run ./cmd/auth-service &
   curl http://localhost:8081/health  # 期望 {"code":0,"message":"ok"}
   # 对 8082-8086 重复
   

3. relay-server WebSocket:

   # 连接 ws://localhost:8086/ws 应成功升级
   

4. Unity 客户端:
   • 用 Unity Hub 打开 client/ 文件夹
   • 无编译错误，8 个 asmdef 程序集均编译通过
5. Git 提交:

   git add -A; git status  # 确认无敏感文件