FIRST

2026-08-07 23:39:47 +08:00
parent f2105bf14c
commit 9500c4c80a
52 changed files with 3801 additions and 0 deletions
@@ -0,0 +1,206 @@
+# 初始化 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  # 确认无敏感文件
+   ```