01 / OVERVIEW

项目概述

RedCircuit · 红石回路是一款融合电路图、Minecraft 像素方块与红石逻辑的桌面客户端游戏，配备完整货币经济与用户体系。

RedCircuit 将电路图工程的严谨性、像素方块的视觉表现力与Minecraft 红石逻辑的创造性玩法结合为一款原生桌面客户端游戏。玩家在 PCB 风格的网格画布上放置元器件、搭建信号回路、解谜闯关、自动化生产，或在多人模式中与他人对战协作。游戏内置红石币与金币双货币体系，支持用户注册登录、等级成长与成就解锁。

核心价值主张

关键指标目标

02 / ARCHITECTURE

技术架构

客户端-服务端分离架构，桌面客户端负责渲染与本地仿真，服务端负责账户、经济、联机与内容分发。

2.1 客户端架构

客户端基于 Unity 2024 LTS (C#) 构建，采用 2D 瓦片网格渲染器配合自定义红石信号辉光着色器。UI 层使用 Unity UI Toolkit (UXML/USS) 处理数据密集型界面（商店、背包、排行榜），编辑器画布使用 IMGUI 实现高性能即时绘制。电路仿真引擎为自定义基于 ECS 的信号传播系统，本地存储采用 SQLite 存档、蓝图与设置。

2.2 服务端架构

服务端采用 Go (Gin 框架) 构建 REST API 与 WebSocket 网关，按业务域拆分为五个微服务。主数据库使用 PostgreSQL 存储用户与交易数据，Redis 承担会话缓存、匹配队列与排行榜。文件存储使用 MinIO/S3 存放蓝图与回放，RabbitMQ 处理异步任务（经济结算、成就检查）。

2.3 网络协议

2.4 系统架构图

分层职责总览

03 / TECH STACK

技术栈选型

各技术领域的选型方案、版本、选型理由与替代方案对照。

04 / DATABASE

数据库设计

核心实体表结构定义，字段类型、约束与说明。

users · 用户表

circuits · 电路表

blueprints · 蓝图表

transactions · 交易流水表

puzzle_levels · 解谜关卡表

multiplayer_matches · 多人对局表

achievements · 成就表

05 / API DESIGN

API设计

REST API 端点清单，涵盖认证、用户、电路、蓝图、商店、解谜、多人与排行榜。

06 / SIMULATION

信号仿真引擎

基于 ECS 的红石信号传播系统，完整还原强度衰减、延迟、BUD 更新等机制。

仿真流程

仿真引擎每个 Tick 执行以下步骤：收集电源、重置信号网格、按强度优先级 BFS 传播、应用元件规则、处理延迟队列、更新输出元件、发射渲染事件。

信号更新优先级

信号属性

特殊规则

仿真循环伪代码

// Redstone Signal Simulation Loop (ECS-based)
function simulateTick(world):
    // 1. Collect all power sources
    powerSources = query(world, PowerSourceComponent)

    // 2. Reset signal grid
    for each cell in grid:
        cell.signal = 0
        cell.updated = false

    // 3. BFS propagation from sources (priority queue by strength)
    queue = PriorityQueue(descending by strength)
    for source in powerSources:
        if source.active:
            queue.push(source.cell, source.strength)

    // 4. Propagate signals
    while queue not empty:
        (cell, strength) = queue.pop()
        if cell.signal >= strength: continue   // already stronger
        cell.signal = strength
        cell.updated = true

        // Apply component-specific rules
        switch cell.component.type:
            case WIRE:    propagateToNeighbors(cell, strength - 1)
            case TORCH:   invertAndPropagate(cell, MAX_STRENGTH)
            case REPEATER:
                if cell.locked: break
                scheduleDelay(cell, strength, 1 tick)
            case COMPARATOR:
                output = compare(cell, strength)
                propagateForward(cell, output)
            case PISTON:  triggerPiston(cell, strength > 0)

        // BUD (Block Update Detector) check
        if cell.component.budSensitive:
            notifyObservers(cell)

    // 5. Resolve scheduled delays (repeaters, etc.)
    processDelayedQueue(world)

    // 6. Update outputs (lamps, pistons, doors)
    updateOutputComponents(world)

    // 7. Emit update events to render system
    emitRenderUpdates(world)

07 / COMPONENTS

元器件规格手册

全部分类元件的编号、成本、信号强度与特殊属性规格，共 8 大类 80 种元件。

7.1 电源类 POWER

7.2 传输类 WIRE

信号衰减示意

7.3 开关/控制类 SWITCH

7.4 输出类 OUTPUT

7.5 逻辑门类 LOGIC

逻辑门组合规则

7.6 特殊元件类 SPECIAL

7.7 模拟元件类 ANALOG

真实模拟电子元件，引入连续信号与线性电路概念，支持更贴近现实电路的设计体验。需在 Lv.15 解锁。

运算放大器工作模式

三极管组合应用

7.8 功率器件类 POWER DEVICE

高功率半导体器件，用于大电流驱动与功率控制场景。需在 Lv.20 解锁。适合自动化生产线和大型机械驱动。

555 定时器工作模式（X-10）

08 / GAME MODES

游戏模式规则

四大游戏模式的规则、限制与奖励机制定义。

8.1 自由搭建模式 Creative

8.2 解谜关卡模式 Puzzle

解谜模式提供 6 种关卡类型，通过 3 星评级衡量通关质量，每章节难度递增，共 6 章 240 关。

三星评级系统

限制规则

章节分布 (共 240 关)

8.3 自动化生产模式 Automation

玩家搭建生产线，将原料加工为成品出售赚取红石币。生产链从采集到精炼逐级加工。

8.4 多人对战/协作模式 Multiplayer

匹配与赛季规则

09 / ECONOMY

货币与经济系统

双货币体系设计，红石币为软货币贯穿玩法循环，金币为硬货币用于增值消费。

9.1 货币类型

9.2 产出与消耗平衡

9.3 充值档位

10 / USER SYSTEM

用户系统

注册登录、账号安全、新手引导、等级解锁与成就系统。

10.1 注册登录

新手引导流程

10.2 等级与解锁

10.3 成就系统

11 / MILESTONES

开发里程碑

从原型到运营的五阶段开发计划与交付物定义。

12 / DEPLOYMENT

部署与运维

服务端容器化部署、客户端分发、CI/CD 流水线与监控体系。

13 / RISKS

风险评估

技术、市场、运营与安全维度的风险识别与缓解措施。

15 / SPRINT PLAN

Sprint 分解与排期

以 2 周为一个 Sprint，从 M1 到 M9 共 18 个 Sprint，每个 Sprint 明确交付物和验收标准。

Phase 1 原型期 (M1-M2, Sprint 1-4)

Phase 2 Alpha (M3-M5, Sprint 5-10)

Phase 3 Beta (M6-M8, Sprint 11-16)

Phase 4 发布 (M9, Sprint 17-18)

16 / TEAM

团队组织与职责

按阶段递进的团队配置，明确角色、职责与协作流程。

团队配置阶段表

角色职责矩阵

协作流程

17 / CLIENT MODULES

客户端模块详设

Unity 客户端的模块拆分、核心脚本职责与数据流设计。

17.1 模块总览

17.2 仿真引擎核心数据结构

17.3 渲染性能策略

17.4 电路数据 JSON 格式

{
  "version": "1.0",
  "canvasSize": { "width": 128, "height": 128 },
  "components": [
    {
      "id": "comp_001",
      "type": "REDSTONE_TORCH",
      "x": 10, "y": 20,
      "rotation": 0,
      "properties": {}
    },
    {
      "id": "comp_002",
      "type": "REDSTONE_DUST",
      "x": 11, "y": 20,
      "rotation": 0,
      "properties": {}
    },
    {
      "id": "comp_003",
      "type": "AND_GATE",
      "x": 15, "y": 20,
      "rotation": 0,
      "properties": { "inputCount": 2 }
    },
    {
      "id": "comp_004",
      "type": "RESISTOR",
      "x": 12, "y": 20,
      "rotation": 0,
      "properties": { "resistance": 5 }
    }
  ],
  "wires": [
    { "from": "comp_001", "to": "comp_002" },
    { "from": "comp_002", "to": "comp_004" },
    { "from": "comp_004", "to": "comp_003", "inputIndex": 0 }
  ],
  "metadata": {
    "author": "CircuitMaster",
    "createdAt": "2026-08-07T12:00:00Z",
    "cost": 280,
    "componentCount": 4,
    "wireCount": 3
  }
}

18 / SERVER SERVICES

服务端微服务详设

5 个微服务的职责边界、核心接口、数据归属与通信协议。

18.1 微服务总览

18.2 auth-service 核心接口

18.3 economy-service 交易事务

// 购买流程伪代码 - 保证原子性和一致性
func PurchaseItem(userID string, itemID string) error {
    // 1. 开启数据库事务
    tx := db.Begin()
    
    // 2. 查询商品价格 (行锁)
    var item ShopItem
    tx.Clauses(clause.Locking{Strength: "UPDATE"}).
       First(&item, itemID)
    
    // 3. 查询用户余额 (行锁)
    var balance UserBalance
    tx.Clauses(clause.Locking{Strength: "UPDATE"}).
       First(&balance, "user_id = ?", userID)
    
    // 4. 校验余额
    if balance.RedstoneCoins < item.Price {
        tx.Rollback()
        return ErrInsufficientBalance
    }
    
    // 5. 扣减余额
    balance.RedstoneCoins -= item.Price
    tx.Save(&balance)
    
    // 6. 写入交易流水
    tx.Create(&Transaction{
        UserID:      userID,
        Type:        "purchase",
        Item:        item.Name,
        Amount:      -item.Price,
        Currency:    "redstone",
        BalanceAfter: balance.RedstoneCoins,
    })
    
    // 7. 发放商品 (调用对应服务)
    if item.Type == "component_pack" {
        // 发放元件包到用户库存
    } else if item.Type == "blueprint" {
        // 标记蓝图为已购买
    }
    
    // 8. 提交事务
    return tx.Commit().Error
}

18.4 数据库索引策略

18.5 / RELAY SERVER

联机服务器中转站开发

独立于业务微服务的联机中转网关，负责 P2P 打洞辅助、房间管理、实时消息路由与断线重连。

架构定位

连接拓扑

┌──────────┐         ┌──────────────┐         ┌──────────┐
│ Player A │◄───────►│  Relay Server │◄───────►│ Player B │
│ (Client) │  WSS    │  (Go + WS)   │  WSS    │ (Client) │
└──────────┘         └──────┬───────┘         └──────────┘
                            │
                     ┌──────┴───────┐
                     │  Room Manager │
                     │  (内存状态机) │
                     └──────┬───────┘
                            │
              ┌─────────────┼─────────────┐
              │             │             │
        ┌─────▼─────┐ ┌────▼────┐ ┌─────▼─────┐
        │  STUN/TURN │ │  Redis  │ │  Kafka   │
        │  (UDP)     │ │ (状态)  │ │ (事件)   │
        └───────────┘ └─────────┘ └───────────┘

连接模式优先级：
  1. P2P 直连 (STUN 打洞成功)  -> relay 仅做信令交换
  2. TURN 中继 (打洞失败)      -> relay 转发所有游戏数据
  3. WebSocket 中转 (兜底)     -> relay 中心化转发

消息协议定义 (Protobuf)

syntax = "proto3";
package relay;

// 客户端 -> Relay 消息
message ClientMessage {
  string msg_id     = 1;  // 消息唯一 ID (UUID)
  int32  msg_type   = 2;  // 消息类型枚举
  string room_id    = 3;  // 目标房间
  string user_id    = 4;  // 发送者
  bytes  payload    = 5;  // 业务载荷 (电路 delta / 聊天 / 状态)
  int64  timestamp  = 6;  // 客户端时间戳 (ms)
}

// Relay -> 客户端消息
message ServerMessage {
  string msg_id     = 1;
  int32  msg_type   = 2;
  string from_user  = 3;  // 消息来源用户
  bytes  payload    = 4;
  int64  server_ts  = 5;  // 服务端时间戳
  int32  seq        = 6;  // 房间内序号 (用于排序)
}

// 消息类型枚举
enum MessageType {
  MSG_JOIN_ROOM      = 0;   // 加入房间
  MSG_LEAVE_ROOM     = 1;   // 离开房间
  MSG_CIRCUIT_DELTA  = 2;   // 电路增量同步
  MSG_CIRCUIT_FULL   = 3;   // 电路全量同步
  MSG_CHAT           = 4;   // 聊天消息
  MSG_PRESENCE       = 5;   // 在线状态
  MSG_CURSOR         = 6;   // 光标位置同步
  MSG_ACTION         = 7;   // 游戏操作 (放置/删除元件)
  MSG_GAME_STATE     = 8;   // 游戏状态变更 (开始/暂停/结束)
  MSG_RECONNECT      = 9;   // 断线重连
  MSG_HEARTBEAT      = 10;  // 心跳
  MSG_KICK           = 11;  // 踢出
  MSG_ERROR          = 12;  // 错误
}

房间状态机

  ┌─────────┐  create   ┌──────────┐  all ready  ┌─────────┐
  │ CREATED │─────────►│ WAITING   │────────────►│ PLAYING  │
  └─────────┘          └────┬─────┘             └────┬────┘
                            │ leave                  │ end
                     ┌──────▼──────┐          ┌──────▼──────┐
                     │  ABANDONED  │          │  FINISHED   │
                     └─────────────┘          └─────────────┘

  房间状态流转规则：
  - CREATED  -> WAITING:     创建者进入，等待其他玩家
  - WAITING  -> PLAYING:      所有玩家就绪，房主点击开始
  - WAITING  -> ABANDONED:    所有玩家离开
  - PLAYING  -> FINISHED:     游戏结束 (计时到/目标达成/房主终止)
  - PLAYING  -> WAITING:      回到等待 (仅协作模式)
  - 任意状态 -> ABANDONED:     超时无活动 30min

核心数据结构 (Go)

// Room 房间结构
type Room struct {
    ID           string              `json:"id"`
    Mode         GameMode            `json:"mode"`          // free_build/puzzle/multiplayer
    Status       RoomStatus          `json:"status"`        // created/waiting/playing/finished
    HostUserID   string              `json:"host_user_id"`
    MaxPlayers   int                 `json:"max_players"`
    Players      map[string]*Player  `json:"players"`       // userID -> Player
    CircuitData  []byte              `json:"circuit_data"`  // 当前电路快照 (全量)
    DeltaQueue   chan CircuitDelta   `json:"-"`             // 增量更新队列
    SeqCounter   int64               `json:"seq_counter"`   // 消息序号计数器
    CreatedAt    time.Time           `json:"created_at"`
    UpdatedAt    time.Time           `json:"updated_at"`
    mu           sync.RWMutex        `json:"-"`
}

// Player 玩家连接
type Player struct {
    UserID       string          `json:"user_id"`
    Username     string          `json:"username"`
    Conn         *websocket.Conn `json:"-"`               // WebSocket 连接
    IsReady      bool            `json:"is_ready"`
    Cursor       struct {
        X int `json:"x"`
        Y int `json:"y"`
    } `json:"cursor"`
    JoinedAt     time.Time       `json:"joined_at"`
    LastActive   time.Time       `json:"last_active"`
    SendQueue    chan []byte     `json:"-"`               // 发送队列 (异步写)
}

// CircuitDelta 电路增量更新
type CircuitDelta struct {
    PlayerID  string          `json:"player_id"`
    OpType    DeltaOpType     `json:"op_type"`            // place/delete/move/rotate/wire
    Component *ComponentData  `json:"component,omitempty"`
    Wire      *WireData       `json:"wire,omitempty"`
    Position  *Position       `json:"position,omitempty"`
    Tick      int64           `json:"tick"`
    Seq       int64           `json:"seq"`
}

// RelayServer 中转服务器
type RelayServer struct {
    Rooms      map[string]*Room        // roomID -> Room
    Players    map[string]*Player      // userID -> Player (全局索引)
    Register   chan *Player            // 注册通道
    Unregister chan *Player            // 注销通道
    Broadcast  chan *BroadcastMsg      // 广播通道
    Redis      *redis.Client           // Redis (持久化房间状态)
    Logger     *zap.Logger
    mu         sync.RWMutex
}

核心处理流程伪代码

// === WebSocket 连接处理 ===
func (s *RelayServer) HandleConnection(conn *websocket.Conn, userID string, roomID string) {
    player := &Player{
        UserID:   userID,
        Conn:     conn,
        SendQueue: make(chan []byte, 256),
        JoinedAt: time.Now(),
    }
    
    // 1. 注册玩家
    s.Register <- player
    
    // 2. 加入房间
    room := s.GetOrCreateRoom(roomID)
    room.AddPlayer(player)
    
    // 3. 通知房间内其他玩家
    room.BroadcastExcept(userID, MSG_PRESENCE, &PresencePayload{
        UserID: userID, Status: "joined"
    })
    
    // 4. 向新玩家发送当前电路全量快照
    player.Send(MSG_CIRCUIT_FULL, room.CircuitData)
    
    // 5. 启动读写 goroutine
    go s.writePump(player)
    s.readPump(player, room)
}

// === 读取客户端消息 ===
func (s *RelayServer) readPump(player *Player, room *Room) {
    defer func() {
        s.Unregister <- player
        room.RemovePlayer(player.UserID)
        room.BroadcastExcept(player.UserID, MSG_PRESENCE, &PresencePayload{
            UserID: player.UserID, Status: "left"
        })
        player.Conn.Close()
    }()
    
    for {
        _, message, err := player.Conn.ReadMessage()
        if err != nil {
            break  // 连接断开
        }
        
        var msg ClientMessage
        proto.Unmarshal(message, &msg)
        
        switch msg.MsgType {
        case MSG_CIRCUIT_DELTA:
            // 应用增量到房间电路快照
            delta := parseDelta(msg.Payload)
            room.ApplyDelta(delta)
            // 广播给房间内其他玩家
            room.BroadcastExcept(msg.UserId, MSG_CIRCUIT_DELTA, msg.Payload)
            
        case MSG_CHAT:
            room.BroadcastAll(MSG_CHAT, msg.Payload)
            
        case MSG_CURSOR:
            room.BroadcastExcept(msg.UserId, MSG_CURSOR, msg.Payload)
            
        case MSG_ACTION:
            // 游戏操作需服务端校验 (多人对战模式)
            if room.Mode == GameModeMultiplayer {
                if !s.ValidateAction(room, msg) {
                    player.Send(MSG_ERROR, &ErrorPayload{Code: "invalid_action"})
                    continue
                }
            }
            room.BroadcastAll(MSG_ACTION, msg.Payload)
            
        case MSG_HEARTBEAT:
            player.LastActive = time.Now()
            player.Send(MSG_HEARTBEAT, &HeartbeatPayload{ServerTs: time.Now().UnixMilli()})
        }
    }
}

// === 断线重连 ===
func (s *RelayServer) HandleReconnect(userID string, roomID string, conn *websocket.Conn) {
    room, ok := s.Rooms[roomID]
    if !ok {
        // 房间已不存在
        conn.WriteMessage(MSG_ERROR, encodeError("room_not_found"))
        return
    }
    
    player, ok := room.Players[userID]
    if ok {
        // 旧连接还存在，关闭旧连接
        oldConn := player.Conn
        player.Conn = conn
        close(player.SendQueue)
        player.SendQueue = make(chan []byte, 256)
        oldConn.Close()
    } else {
        // 玩家已被清理，重新加入
        player = &Player{
            UserID: userID, Conn: conn,
            SendQueue: make(chan []byte, 256),
        }
        room.AddPlayer(player)
    }
    
    // 发送重连成功 + 当前全量快照 + 最近 50 条消息
    player.Send(MSG_RECONNECT, &ReconnectPayload{
        Success:    true,
        CircuitSnapshot: room.CircuitData,
        RecentMsgs: room.GetRecentMessages(50),
        Players:    room.GetPlayerList(),
    })
    
    go s.writePump(player)
    go s.readPump(player, room)
}

// === 房间广播 ===
func (r *Room) BroadcastExcept(userID string, msgType MessageType, payload []byte) {
    r.mu.RLock()
    defer r.mu.RUnlock()
    
    r.SeqCounter++
    msg := &ServerMessage{
        MsgType:   int32(msgType),
        Payload:   payload,
        ServerTs:  time.Now().UnixMilli(),
        Seq:       r.SeqCounter,
    }
    data, _ := proto.Marshal(msg)
    
    for _, player := range r.Players {
        if player.UserID == userID {
            continue
        }
        select {
        case player.SendQueue <- data:
        default:
            // 队列满，关闭连接
            close(player.SendQueue)
            delete(r.Players, player.UserID)
        }
    }
}

P2P 打洞与 TURN 中继

断线重连策略

水平扩展方案

监控指标

开发任务分解

19 / TESTING

测试与质量保障

四层测试体系：单元测试、集成测试、性能测试、E2E 测试，覆盖客户端与服务端。

19.1 测试分层

19.2 仿真引擎单元测试用例

19.3 性能指标与压测目标

19.4 Bug 分级与响应 SLA

20 / PERFORMANCE

性能优化方案

客户端、服务端、网络三个维度的具体优化措施与实施节点。

20.1 客户端优化

20.2 服务端优化

20.3 网络优化

21 / SECURITY

安全实施方案

认证安全、数据安全、反作弊、基础设施安全四层防护体系。

21.1 认证与授权

21.2 数据安全

21.3 反作弊系统

22 / CI/CD

CI/CD 流水线

从代码提交到生产部署的自动化流水线配置。

22.1 流水线阶段

22.2 环境配置

22.3 发布与回滚

23 / BUDGET

预算与成本估算

9 个月开发期 + 首年运营期的成本估算（人民币）。

23.1 人力成本

23.2 基础设施成本（月度）

23.3 其他成本

23.4 总预算汇总

24 / ROLLOUT

上线发布策略

分阶段灰度发布、数据监控、应急预案与运营节奏。

24.1 灰度发布计划

24.2 发布日监控清单

24.3 应急预案

24.4 首年运营节奏

25 / APPENDIX

附录

元件成本速查表与常见电路设计模式参考。

A. 元件成本速查表

全部元件按成本升序排列，便于快速查阅预算规划。共 80 种元件。

B. 常见电路设计模式