01 / OVERVIEW

## 项目概述

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

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

核心定位

目标平台
Windows / macOS 桌面客户端
发行渠道
官网独立安装包 + 自动更新
目标受众
红石工程师 / 电路爱好者 / 解谜玩家
商业模式
免费游玩 + 内购 + 创意工坊分成

### 核心价值主张

维度 | 价值主张 | 差异化优势
--- | --- | ---
玩法深度 | 完整还原红石信号强度、衰减、延迟与 BUD 更新机制 | 市面同类产品多简化逻辑，本作保留硬核仿真
视觉风格 | PCB 电路板 × 像素方块混搭美学 | 区别于纯像素或纯电路模拟器
内容体量 | 80 种元器件、240 个解谜关卡、4 大模式 | 单机+联机兼顾，内容耐玩度高
经济闭环 | 红石币产出消耗平衡 + 金币充值 + 创意工坊交易 | UGC 生态自循环，降低内容更新成本
社交竞技 | 多人对战排位赛季 + 协作建造 + 蓝图分享 | 红石领域稀缺的竞技化设计

### 关键指标目标

指标 | 上线首月目标 | 稳定期目标 (M12) | 说明
--- | --- | --- | ---
DAU | 15,000 | 60,000 | 日活跃用户
MAU | 80,000 | 300,000 | 月活跃用户
次日留存 | 42% | 50% | 新手引导优化后提升
七日留存 | 22% | 30% | 关卡内容驱动
付费率 | 3.5% | 6% | 金币充值 + 创意工坊
ARPPU | ¥28 | ¥45 | 每付费用户平均收益
蓝图上传量 | 2,000 | 20,000/月 | UGC 生态健康度

02 / ARCHITECTURE

## 技术架构

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

### 2.1 客户端架构

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

模块 | 技术方案 | 职责
--- | --- | ---
游戏引擎 | Unity 2024 LTS (C#) | 主循环、渲染、资源管理、跨平台打包
渲染层 | 2D Tile 网格渲染器 + 自定义辉光 Shader | 方块绘制、红石信号高亮、粒子效果
UI 框架 | Unity UI Toolkit (UXML/USS) | 商店、背包、排行榜等数据界面
编辑器画布 | IMGUI 即时模式 | 电路编辑画布高频重绘
仿真引擎 | 自定义 ECS 信号传播系统 | 红石信号强度、衰减、延迟、BUD 计算
本地存储 | SQLite | 存档、蓝图、设置、离线缓存
网络层 | Unity Netcode for GameObjects / Photon | 多人实时同步、房间管理
反作弊 | 客户端预测 + 服务端校验 | 多人模式经济与比赛结果验证

### 2.2 服务端架构

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

微服务 | 职责 | 主要依赖
--- | --- | ---
auth-service | 注册、登录、Token 签发与刷新、会话管理 | PostgreSQL、Redis
economy-service | 红石币/金币余额、交易流水、商店购买、充值核销 | PostgreSQL、RabbitMQ
blueprint-service | 蓝图上传、检索、购买、下载、评分、分类 | PostgreSQL、MinIO
match-service | 多人匹配、房间状态、对局结果、赛季排位 | Redis、RabbitMQ
social-service | 好友、聊天、公会、成就、动态 | PostgreSQL、Redis

### 2.3 网络协议

协议 | 数据格式 | 适用场景
--- | --- | ---
REST API | JSON | 用户认证、商店、蓝图 CRUD、排行榜查询
WebSocket | JSON 帧 | 多人实时同步、聊天、在线状态
二进制协议 | Protobuf | 电路编辑器实时协作（增量 Delta 同步）
消息队列 | AMQP (RabbitMQ) | 经济结算、成就检查等异步任务

### 2.4 系统架构图

桌面客户端 (Unity 2024 LTS)渲染 / 本地仿真 / 离线存档
HTTPS / WSS
API 网关 (Go / Gin)鉴权 / 路由 / 限流
gRPC / 内部调用
auth-service认证
economy-service经济
blueprint-service蓝图
match-service匹配
social-service社交
持久化 / 缓存 / 对象存储 / 异步
PostgreSQL用户 / 交易
Redis会话 / 排行
MinIO / S3蓝图 / 回放
RabbitMQ异步任务

### 分层职责总览

层级 | 技术 | 职责
--- | --- | ---
表现层 | Unity 2024 LTS + UI Toolkit | 渲染、交互、本地仿真展示
网关层 | Go / Gin + Nginx | 请求路由、JWT 鉴权、限流熔断
服务层 | 5 个 Go 微服务 | 业务逻辑处理、事务编排
存储层 | PostgreSQL + Redis + MinIO | 持久化、缓存、对象存储
消息层 | RabbitMQ | 异步解耦、事件驱动

03 / TECH STACK

## 技术栈选型

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

领域 | 技术选型 | 版本 | 选型理由 | 替代方案
--- | --- | --- | --- | ---
游戏引擎 | Unity | 2024 LTS | 生态成熟、跨平台打包、Asset Store 资源丰富、C# 开发效率高 | Godot 4.x
客户端语言 | C# | 12 | Unity 原生语言、强类型、性能优良 | GDScript (Godot)
UI 框架 | Unity UI Toolkit | 2.0 | 类 Web 的 UXML/USS 体系、适合数据密集界面 | UGUI、IMGUI
后端语言 | Go | 1.22 | 高并发、编译快、内存占用低、适合微服务 | Rust、Java
后端框架 | Gin | 1.10 | 轻量高性能、中间件生态完善 | Echo、Fiber
数据库 | PostgreSQL | 16 | 事务可靠、JSONB 支持、扩展性强 | MySQL、CockroachDB
缓存 | Redis | 7.2 | 低延迟、排行榜 ZSET、会话存储 | Valkey、Memcached
消息队列 | RabbitMQ | 3.13 | 可靠投递、路由灵活、异步任务解耦 | Kafka、NATS
文件存储 | MinIO / S3 | - | 兼容 S3 协议、可自托管或上云、成本低 | Ceph、阿里云 OSS
CI/CD | GitHub Actions | - | 与代码仓库集成、矩阵构建、自托管 Runner | GitLab CI、Jenkins
监控 | Prometheus + Grafana | 2.50 / 11 | 指标采集可视化、告警规则灵活 | Datadog、Zabbix
错误追踪 | Sentry | 24 | 客户端崩溃与服务端异常统一收集 | Bugsnag、Crashlytics
数据分析 | 自建埋点 + ClickHouse | 24 | 玩家行为分析、留存漏斗、低成本海量查询 | Mixpanel、Amplitude

04 / DATABASE

## 数据库设计

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

### users · 用户表

字段名 | 类型 | 约束 | 说明
--- | --- | --- | ---
id | BIGSERIAL | PK | 用户主键
username | VARCHAR(32) | UNIQUE NOT NULL | 用户名
email | VARCHAR(128) | UNIQUE NOT NULL | 邮箱
password_hash | VARCHAR(255) | NOT NULL | bcrypt 哈希
created_at | TIMESTAMPTZ | DEFAULT NOW() | 注册时间
level | INT | DEFAULT 1 | 玩家等级
exp | INT | DEFAULT 0 | 经验值
redstone_coins | BIGINT | DEFAULT 0 | 红石币余额
gold_coins | INT | DEFAULT 0 | 金币余额
avatar | VARCHAR(255) | NULL | 头像 URL
status | SMALLINT | DEFAULT 1 | 状态 1正常 0封禁

### circuits · 电路表

字段名 | 类型 | 约束 | 说明
--- | --- | --- | ---
id | BIGSERIAL | PK | 电路主键
user_id | BIGINT | FK -> users.id | 所属用户
name | VARCHAR(64) | NOT NULL | 电路名称
data_json | JSONB | NOT NULL | 元件布局与连线数据
grid_size | VARCHAR(16) | NOT NULL | 画布尺寸 如 64x64
cost | INT | DEFAULT 0 | 元件总成本
mode | VARCHAR(16) | NOT NULL | 模式 creative/puzzle/auto
created_at | TIMESTAMPTZ | DEFAULT NOW() | 创建时间
updated_at | TIMESTAMPTZ | DEFAULT NOW() | 更新时间
is_public | BOOLEAN | DEFAULT FALSE | 是否公开

### blueprints · 蓝图表

字段名 | 类型 | 约束 | 说明
--- | --- | --- | ---
id | BIGSERIAL | PK | 蓝图主键
circuit_id | BIGINT | FK -> circuits.id | 关联电路
author_id | BIGINT | FK -> users.id | 作者
title | VARCHAR(64) | NOT NULL | 蓝图标题
description | TEXT | NULL | 蓝图描述
price | INT | DEFAULT 0 | 售价（红石币）
download_count | INT | DEFAULT 0 | 下载数
rating | NUMERIC(3,2) | DEFAULT 0 | 评分 0-5
category | VARCHAR(32) | NOT NULL | 分类
created_at | TIMESTAMPTZ | DEFAULT NOW() | 发布时间

### transactions · 交易流水表

字段名 | 类型 | 约束 | 说明
--- | --- | --- | ---
id | BIGSERIAL | PK | 流水主键
user_id | BIGINT | FK -> users.id | 用户
type | VARCHAR(16) | NOT NULL | 类型 earn/spend/recharge
item | VARCHAR(64) | NOT NULL | 项目说明
amount | BIGINT | NOT NULL | 金额
currency | VARCHAR(8) | NOT NULL | 货币 redstone/gold
balance_after | BIGINT | NOT NULL | 交易后余额
created_at | TIMESTAMPTZ | DEFAULT NOW() | 交易时间

### puzzle_levels · 解谜关卡表

字段名 | 类型 | 约束 | 说明
--- | --- | --- | ---
id | BIGSERIAL | PK | 关卡主键
chapter | SMALLINT | NOT NULL | 章节 1-6
level_num | SMALLINT | NOT NULL | 关卡序号
title | VARCHAR(64) | NOT NULL | 关卡标题
description | TEXT | NULL | 关卡描述
target_json | JSONB | NOT NULL | 通关目标条件
constraints_json | JSONB | NOT NULL | 限制规则
star_cost | SMALLINT | NOT NULL | 成本星条件
star_delay | SMALLINT | NOT NULL | 延迟星条件
reward | INT | NOT NULL | 通关奖励红石币

### multiplayer_matches · 多人对局表

字段名 | 类型 | 约束 | 说明
--- | --- | --- | ---
id | BIGSERIAL | PK | 对局主键
mode | VARCHAR(16) | NOT NULL | 对战模式
status | VARCHAR(16) | NOT NULL | 状态 waiting/playing/ended
players_json | JSONB | NOT NULL | 玩家列表与分数
result_json | JSONB | NULL | 对局结果
started_at | TIMESTAMPTZ | NULL | 开始时间
ended_at | TIMESTAMPTZ | NULL | 结束时间

### achievements · 成就表

字段名 | 类型 | 约束 | 说明
--- | --- | --- | ---
id | BIGSERIAL | PK | 记录主键
user_id | BIGINT | FK -> users.id | 用户
achievement_id | VARCHAR(32) | NOT NULL | 成就标识
unlocked_at | TIMESTAMPTZ | DEFAULT NOW() | 解锁时间

05 / API DESIGN

## API设计

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

方法 | 路径 | 说明 | 鉴权
--- | --- | --- | ---
POST | /api/auth/register | 用户注册 | 否
POST | /api/auth/login | 用户登录 | 否
POST | /api/auth/logout | 退出登录 | 是
POST | /api/auth/refresh | 刷新 Token | 是
GET | /api/user/profile | 获取个人资料 | 是
GET | /api/user/balance | 查询货币余额 | 是
GET | /api/user/achievements | 查询成就列表 | 是
GET | /api/circuits | 获取电路列表 | 是
POST | /api/circuits | 新建电路存档 | 是
GET | /api/circuits/:id | 获取电路详情 | 是
PUT | /api/circuits/:id | 更新电路 | 是
DELETE | /api/circuits/:id | 删除电路 | 是
POST | /api/circuits/:id/share | 分享电路为蓝图 | 是
GET | /api/blueprints | 浏览蓝图列表 | 是
POST | /api/blueprints | 上传蓝图 | 是
POST | /api/blueprints/:id/buy | 购买蓝图 | 是
GET | /api/blueprints/:id/download | 下载蓝图文件 | 是
POST | /api/blueprints/:id/rate | 评分 | 是
GET | /api/shop/items | 商店商品列表 | 是
POST | /api/shop/buy | 购买商品 | 是
GET | /api/shop/history | 购买历史 | 是
GET | /api/puzzle/levels | 解谜关卡列表 | 是
POST | /api/puzzle/:id/submit | 提交关卡答案 | 是
GET | /api/puzzle/progress | 关卡进度 | 是
POST | /api/multiplayer/match | 发起匹配 | 是
POST | /api/multiplayer/join | 加入房间 | 是
POST | /api/multiplayer/result | 提交对局结果 | 是
GET | /api/leaderboard | 排行榜 | 是

06 / SIMULATION

## 信号仿真引擎

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

### 仿真流程

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

步骤 | 操作 | 说明
--- | --- | ---
1 | 收集电源 | 查询所有 PowerSourceComponent 且处于激活态的元件
2 | 重置网格 | 将所有格子信号归零、标记未更新
3 | 优先级入队 | 按信号强度降序将电源推入优先级队列
4 | BFS 传播 | 从队列取出格子，向邻居传播衰减后信号
5 | 元件规则 | 对火把/中继器/比较器等应用特殊逻辑
6 | 延迟处理 | 处理中继器等延迟元件的跨 Tick 输出
7 | 输出更新 | 更新灯、活塞、门等输出元件状态
8 | 渲染事件 | 向渲染系统发射变更差量，触发重绘

### 信号更新优先级

优先级 | 元件类型 | 更新顺序 | 说明
--- | --- | --- | ---
P0 | 电源类 | 最先计算 | 拉杆、按钮、压力板等直接设定信号源
P1 | 红石火把 | 电源之后 | 反相输出，依赖输入端状态
P2 | 比较器 | 火把之后 | 比较/减法模式，需两侧输入
P3 | 中继器 | 比较器之后 | 延迟输出，受锁定信号影响
P4 | 红石粉 | 主动元件之后 | 按强度衰减传播，BFS 遍历
P5 | 输出类 | 最后更新 | 灯、活塞、门读取最终信号

### 信号属性

属性 | 取值范围 | 说明
--- | --- | ---
type | redstone / analog | 红石数字信号或模拟比较信号
strength | 0 - 15 | 信号强度，15 为满强度
speed | 1 tick / 格 | 红石粉每格传播延迟 1 tick
direction | N / E / S / W / UP / DOWN | 信号传播方向，支持六向

### 特殊规则

规则 | 触发条件 | 行为
--- | --- | ---
火把反相 | 火把附着方块被激活 | 火把熄灭，停止输出信号（NOT 门）
中继器锁定 | 侧面输入信号 | 中继器锁定当前输出值，不再响应输入变化
比较器检测 | 后方容器有物品 | 输出与物品填充率成正比的模拟信号
活塞链 | 活塞推动含活塞的方块 | 按顺序级联推动，最多 12 格
BUD 更新 | 方块状态变化未直接触发 | 观察者检测邻接变更并发出脉冲

### 仿真循环伪代码

    // 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

编号 | 元件名 | 成本(红石币) | 信号强度 | 特殊属性
--- | --- | --- | --- | ---
P-01 | POWER 红石火把 | 50 | 15 | 反相输出，可被附着方块熄灭
P-02 | POWER 红石块 | 100 | 15 | 恒定满强度，不可关闭
P-03 | POWER 拉杆 | 30 | 15 | 手动开关，双稳态
P-04 | POWER 按钮 | 40 | 15 | 瞬时脉冲，自动复位
P-05 | POWER 压力板 | 35 | 15 | 实体踩踏触发，离开复位
P-06 | POWER 阳光探测器 | 90 | 0-15 | 输出随光照强度变化
P-07 | POWER 阳光探测器(夜) | 90 | 0-15 | 反向模式，夜间满强度
P-08 | POWER 探测铁轨 | 70 | 15 | 矿车经过时触发脉冲
P-09 | POWER 直流电源 | 40 | 0-15 | 可调稳压输出，输出强度旋钮 0-15 自由设定；适合精密电路调试供电
P-10 | POWER 电池组 | 85 | 15 | 便携式移动电源，信号强度 15 恒定；可被活塞推动实现移动供电电路；电量有限需充电

### 7.2 传输类 WIRE

编号 | 元件名 | 成本(红石币) | 信号强度 | 特殊属性
--- | --- | --- | --- | ---
W-01 | WIRE 红石粉 | 5 | 15->0 | 每格衰减 1，可爬升 1 格
W-02 | WIRE 红石中继器 | 80 | 15 | 恢复满强度，1-4 档延迟
W-03 | WIRE 红石比较器 | 120 | 0-15 | 比较/减法模式，可测容器
W-04 | WIRE 绝缘导线 | 15 | 15->0 | 不与交叉导线串扰，衰减同红石粉
W-05 | WIRE 信号桥 | 25 | 15 | 跨层传输信号，不衰减
W-06 | WIRE 铜导线 | 12 | 15->0 | 低电阻传输，每格仅衰减 0.5（每 2 格衰减 1）；成本高于红石粉但传输距离翻倍
W-07 | WIRE 跳线 | 18 | 15 | 跨格架空连接，可跨越 1 格间隙直接连通两个元件；不与下方交叉导线串扰

### 信号衰减示意

15 -> 14 -> 13 -> 12 -> 11 -> 10 -> 9 -> 8 -> 7 -> 6 -> 5 -> 4 -> 3 -> 2 -> 1 -> 0

红石粉每传播 1 格衰减 1 点强度，中继器可恢复至满强度 15。

### 7.3 开关/控制类 SWITCH

编号 | 元件名 | 成本(红石币) | 信号强度 | 特殊属性
--- | --- | --- | --- | ---
S-01 | SWITCH 按钮木质 | 40 | 15 | 脉冲持续 1.5s
S-02 | SWITCH 按钮石质 | 40 | 15 | 脉冲持续 1s
S-03 | SWITCH 拉杆 | 30 | 15 | 双稳态手动开关
S-04 | SWITCH 压力板木质 | 35 | 15 | 所有实体触发
S-05 | SWITCH 压力板铁质 | 50 | 15 | 仅玩家触发
S-06 | SWITCH 压力板金质 | 80 | 15 | 仅玩家触发，信号更长
S-07 | SWITCH 绊线钩 | 45 | 15 | 绊线被触碰时触发
S-08 | SWITCH 阳光探测器 | 90 | 0-15 | 光照强度模拟输出
S-09 | SWITCH 观察者 | 150 | 15 | 检测前方方块变更，BUD 脉冲
S-10 | SWITCH 标靶 | 60 | 0-15 | 箭矢命中精度决定强度
S-11 | SWITCH 拨动开关 | 25 | 15 | 机械双稳态拨动开关，手动切换开/关；比拉杆更紧凑，可密集排列组成 DIP 开关阵列
S-12 | SWITCH 继电器 | 120 | 15 | 电磁开关，线圈通电吸合触点；支持常开/常闭双触点输出，实现电路隔离与跨域信号传递

### 7.4 输出类 OUTPUT

编号 | 元件名 | 成本(红石币) | 信号强度 | 特殊属性
--- | --- | --- | --- | ---
O-01 | OUTPUT 红石灯 | 60 | >=1 | 接收信号即点亮
O-02 | OUTPUT 活塞 | 150 | >=1 | 推出方块，断电收回
O-03 | OUTPUT 粘性活塞 | 200 | >=1 | 推出并拉回方块
O-04 | OUTPUT 发射器 | 180 | >=1 | 脉冲触发发射物品
O-05 | OUTPUT 投掷器 | 120 | >=1 | 脉冲触发掉落物品
O-06 | OUTPUT 漏斗 | 100 | - | 信号锁定时停止传输
O-07 | OUTPUT 音符盒 | 70 | >=1 | 脉冲触发播放音符
O-08 | OUTPUT TNT | 300 | >=1 | 信号触发引爆
O-09 | OUTPUT 门(铁) | 80 | >=1 | 信号开启，铁门仅受信号控制
O-10 | OUTPUT 门(木) | 50 | >=1 | 信号开启，也可手动开关
O-11 | OUTPUT 活板门 | 60 | >=1 | 信号开启翻板
O-12 | OUTPUT 灯笼 | 55 | - | 常亮光源，不受信号控制
O-13 | OUTPUT LED | 15 | >=1 | 低功耗指示灯，多色可选（红/绿/蓝/黄）；信号强度决定亮度，体积仅 0.5 格
O-14 | OUTPUT 蜂鸣器 | 35 | >=1 | 信号触发鸣响，频率随信号强度变化；可串联实现旋律播放，替代音符盒的精密方案
O-15 | OUTPUT 数码管 | 90 | 0-15 | 7 段数码显示管，直接显示输入信号强度数值 0-15；可级联实现多位数字显示

### 7.5 逻辑门类 LOGIC

编号 | 元件名 | 成本(红石币) | 信号强度 | 特殊属性
--- | --- | --- | --- | ---
L-01 | LOGIC NOT | 150 | 15 | 输入反相，单输入门
L-02 | LOGIC AND | 200 | 15 | 双输入全高才输出
L-03 | LOGIC OR | 200 | 15 | 任一输入高即输出
L-04 | LOGIC NAND | 220 | 15 | AND 后取反
L-05 | LOGIC NOR | 220 | 15 | OR 后取反
L-06 | LOGIC XOR | 250 | 15 | 输入不同才输出
L-07 | LOGIC XNOR | 250 | 15 | 输入相同才输出
L-08 | LOGIC 中继器逻辑 | 100 | 15 | 延迟+缓冲，可级联
L-09 | LOGIC RS 锁存器 | 350 | 15 | 置位/复位双稳态存储
L-10 | LOGIC D 触发器 | 400 | 15 | 边沿触发数据锁存
L-11 | LOGIC 计数器 | 500 | 0-15 | 脉冲计数，溢出进位

### 逻辑门组合规则

组合 | 等效逻辑 | 说明
--- | --- | ---
NOT + NOT | 缓冲器 | 无逻辑变化，仅作延迟/隔离
AND + NOT | NAND | 通用门，可组合出任一逻辑
OR + NOT | NOR | 通用门，可组合出任一逻辑
NAND + NAND | AND | 双重否定还原与门
NOR + NOR | OR | 双重否定还原或门
RS 锁存器 x N | 寄存器 | 多 Bit 并行存储，构成数据总线

### 7.6 特殊元件类 SPECIAL

编号 | 元件名 | 成本(红石币) | 信号强度 | 特殊属性
--- | --- | --- | --- | ---
X-01 | SPECIAL 命令方块 | 1000 | - | 执行预设指令，仅创意/编辑模式
X-02 | SPECIAL 结构方块 | 800 | - | 保存/加载区域结构，蓝图核心
X-03 | SPECIAL 信号示波器 | 300 | 0-15 | 实时显示信号波形与延迟
X-04 | SPECIAL 信号延迟器 | 150 | 15 | 可调 1-16 tick 精确延迟
X-05 | SPECIAL 信号分配器 | 120 | 15 | 一入多出，不衰减分路
X-06 | SPECIAL 物品过滤器 | 250 | - | 按物品类型筛选传输路径
X-07 | SPECIAL 物品分类器 | 400 | - | 多通道自动分拣，自动化核心
X-08 | SPECIAL ADC 模数转换器 | 450 | 0-15 | 将模拟信号（连续强度）转为数字信号（二进制 4-bit 输出）；连接模拟电路与数字逻辑的桥梁
X-09 | SPECIAL DAC 数模转换器 | 450 | 0-15 | 将 4-bit 数字信号转为模拟信号强度 0-15 输出；用于驱动模拟负载或生成可变亮度
X-10 | SPECIAL 555 定时器 | 350 | 15 | 支持单稳态（定时器）、双稳态（锁存）、无稳态（方波振荡器）三种工作模式；外接电阻电容可调频率与占空比

### 7.7 模拟元件类 ANALOG

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

编号 | 元件名 | 成本(红石币) | 信号规则 | 特殊属性
--- | --- | --- | --- | ---
A-01 | ANALOG 电阻 | 20 | 衰减可调 | 串联在导线中，可调阻值 1-15，按比例衰减信号强度；用于限流保护和信号分压
A-02 | ANALOG 电容 | 60 | 充放电 | 存储信号能量，输入断开后延迟释放（容量可调 1-8 tick）；用于平滑脉冲、延时开关、去抖
A-03 | ANALOG 电感 | 70 | 磁能存储 | 阻碍电流突变，信号突变时产生反电动势；与电容组合可构建 LC 振荡、滤波器；延迟特性与电容互补
A-04 | ANALOG 二极管 | 45 | 单向导通 | 仅允许信号正向通过、反向截止；等效红石中继器但无延迟、无放大；防信号回流
A-05 | ANALOG 稳压管 | 55 | 钳位 | 反向击穿后将信号钳位在固定强度（可调 1-15）；用于稳压保护、电压基准源、限幅电路
A-06 | ANALOG NPN 三极管 | 180 | 电流控制 | 三端元件（C/B/E）；B 有信号时 C->E 导通，B 无信号时截止；可用作信号开关或放大器
A-07 | ANALOG PNP 三极管 | 180 | 电流控制 | 与 NPN 互补；B 无信号时 C->E 导通，B 有信号时截止；适合高边开关设计，与 NPN 组合可搭建推挽电路
A-08 | ANALOG 运算放大器 | 280 | 线性放大 | 高增益差分放大器，支持反相/同相/差分/积分/微分五种工作模式；外接电阻设定增益倍数；模拟计算核心
A-09 | ANALOG 光耦 | 160 | 光电隔离 | 输入端 LED 驱动光敏管输出，实现电气隔离传输；抗干扰、防地线环路；高压与低压电路安全桥接

#### 运算放大器工作模式

模式 | 接法 | 输出 | 典型用途
--- | --- | --- | ---
反相放大 | 输入接反相端，同相端接地，Rf/R1 设定增益 | Vout = -Vin * (Rf/R1) | 信号反相放大、加法器
同相放大 | 输入接同相端，反相端分压反馈 | Vout = Vin * (1 + Rf/R1) | 信号同相放大、缓冲器
差分放大 | 双端输入，差模放大共模抑制 | Vout = (V+ - V-) * Gain | 传感器信号放大、噪声抑制
积分器 | 反馈回路用电容替代电阻 | Vout = -1/RC * ∫Vin dt | 波形变换、斜坡发生器
比较器 | 开环工作，无反馈 | Vout = +Vcc if V+ > V- else -Vcc | 阈值检测、过零比较

#### 三极管组合应用

组合 | 结构 | 功能
--- | --- | ---
推挽输出 | NPN + PNP 对管，基极共连 | 双向驱动，可拉高也可拉低，替代活塞推拉逻辑
达林顿管 | 两级 NPN 级联 | 超高增益，极弱信号可驱动大负载
差分对 | 双 NPN 共发射极 | 比较两路信号差值，运放输入级的基础结构

### 7.8 功率器件类 POWER DEVICE

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

编号 | 元件名 | 成本(红石币) | 信号规则 | 特殊属性
--- | --- | --- | --- | ---
PD-01 | POWER_DEVICE 单向可控硅 SCR | 220 | 触发导通 | 门极脉冲触发后持续导通，直至电流降至零才关断；用于整流功率控制、过压保护；半控型器件
PD-02 | POWER_DEVICE 双向可控硅 TRIAC | 280 | 双向触发 | 双方向均可触发导通，等效两个 SCR 反并联；交流功率控制核心元件；调光、调速、温控
PD-03 | POWER_DEVICE IGBT | 420 | 电压驱动 | 结合 MOS 管高输入阻抗与三极管大电流能力；高压大电流开关核心；逆变器、电机驱动首选
PD-04 | POWER_DEVICE MOS 管 | 200 | 电压控制 | 电压驱动型场效应管，导通电阻极低；开关速度快，高频功率应用核心；可并联扩流
PD-05 | POWER_DEVICE 达林顿管 | 300 | 高增益驱动 | 两级三极管复合封装，电流增益达 1000+；微弱信号即可驱动大功率负载；步进电机/继电器阵列驱动
PD-06 | POWER_DEVICE 继电器模组 | 250 | 多路隔离 | 4 路独立继电器集成模组，每路常开+常闭双触点；可同时控制 4 路独立高功率负载；工业自动化标配

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

模式 | 接法 | 输出 | 典型用途
--- | --- | --- | ---
单稳态 | 触发端输入脉冲，外接 R+C 定时 | 固定宽度高电平脉冲 | 延时开关、脉冲展宽、防抖
双稳态 | 触发端置位，复位端清零 | 锁存当前状态 | RS 锁存器替代、记忆电路
无稳态 | 两电阻 + 电容构成振荡回路 | 连续方波信号 | 时钟发生器、PWM 调制、闪烁灯

08 / GAME MODES

## 游戏模式规则

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

### 8.1 自由搭建模式 Creative

规则项 | 设定 | 说明
--- | --- | ---
资源 | 无限 | 所有元件免费无限使用
成本 | 不计 | 不消耗红石币
画布尺寸 | 256x256 | 最大单电路画布
存档槽位 | 20 | 本地+云端各 20 个
仿真 | 实时 | 放置即仿真，可暂停单步
分享 | 允许 | 可发布为蓝图供他人下载
目标 | 无 | 纯创造，无强制目标

### 8.2 解谜关卡模式 Puzzle

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

关卡类型 | 玩法说明 | 示例目标
--- | --- | ---
信号路由 | 将信号从起点传至终点 | 点亮指定红石灯
逻辑运算 | 搭建满足真值表的逻辑电路 | 实现 XOR 门
时序控制 | 按顺序触发多个输出 | 三盏灯依次点亮
计数挑战 | 统计脉冲数并输出 | 计满 10 次触发
资源优化 | 在元件数限制内通关 | 不超过 15 个元件
延迟竞速 | 在延迟上限内完成 | 总延迟不超过 20 tick

### 三星评级系统

星级 | 条件 | 奖励
--- | --- | ---
一星 | 完成通关目标 | 基础红石币奖励
二星 | 成本不超过 star_cost 上限 | 1.5x 红石币 + 经验
三星 | 成本达标且延迟不超过 star_delay | 2x 红石币 + 成就进度

### 限制规则

限制类型 | 说明
--- | ---
元件禁用 | 部分关卡禁用高级元件（如命令方块、结构方块）
元件上限 | 限制可放置元件总数
画布缩放 | 缩小可用画布区域增加难度
预设锁定 | 部分元件位置固定不可移动

### 章节分布 (共 240 关)

章节 | 主题 | 关卡数 | 难度
--- | --- | --- | ---
第 1 章 | 基础电路入门 | 30 | 简单
第 2 章 | 逻辑门与运算 | 40 | 普通
第 3 章 | 时序与锁存 | 50 | 中等
第 4 章 | 复杂自动化 | 60 | 困难
第 5 章 | 高级电路设计 | 40 | 专家
第 6 章 | 极限挑战 | 20 | 大师
合计 | - | 240 | -

### 8.3 自动化生产模式 Automation

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

矿石采集 -> 粉碎机 -> 精炼炉 -> 合成台 -> 成品仓库 -> 出售获利

资源类型 | 采购价 | 用途
--- | --- | ---
原矿石 | 5 | 基础原料，粉碎后得矿粉
矿粉 | 12 | 精炼原料，可熔炼为锭
金属锭 | 30 | 合成元件壳体的核心材料
红石粉原料 | 8 | 提纯为可用红石粉
红石结晶 | 80 | 高级逻辑门核心材料
硅片 | 45 | 集成电路板基材
电路板 | 120 | 成品元件必备组件
能量核 | 200 | 特殊元件能源供给

效率公式：E = (成品数量 / 总耗时) x 100
成本回收：R = 成品售价 - (原料成本 + 元件磨损 + 电力消耗)
净利润：P = R x E x 运行时长

### 8.4 多人对战/协作模式 Multiplayer

对战模式 | 人数 | 规则
--- | --- | ---
电路竞速 | 2-4 | 最先完成指定电路搭建者获胜
信号攻防 | 2 | 一方搭建防御电路，另一方破解
资源争夺 | 2-4 | 争夺有限元件资源搭建最优电路
蓝图复刻 | 2-4 | 看图复原电路，最快最准者胜

协作模式 | 人数 | 规则
--- | --- | ---
联合建造 | 2-4 | 共同完成大型电路工程
分工流水线 | 2-4 | 各负责生产链一环，协同产出
解谜协作 | 2-4 | 合力攻克高难度解谜关卡

### 匹配与赛季规则

规则项 | 设定 | 说明
--- | --- | ---
匹配机制 | MMR 段位 | 基于隐藏分匹配相近水平玩家
匹配超时 | 60s | 超时后放宽段位范围
赛季周期 | 4 周 | 每月一个赛季，结算发放奖励
段位 | 7 级 | 青铜至宗师，每级 3 小段
赛季奖励 | 蓝图+金币 | 按最终段位发放限定蓝图与金币

09 / ECONOMY

## 货币与经济系统

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

### 9.1 货币类型

属性 | 红石币 (软货币) | 金币 (硬货币)
--- | --- | ---
获取方式 | 解谜通关、自动化生产、每日任务 | 人民币充值、赛季奖励、成就
主要用途 | 购买元件、解锁关卡、购买蓝图 | 购买稀有皮肤、加速、高级蓝图
可交易性 | 不可直接交易，仅通过蓝图间接流通 | 不可交易
上限 | 9,999,999 | 99,999
汇率参考 | 1000 红石币 ≈ ¥1 | 10 金币 = ¥1

### 9.2 产出与消耗平衡

产出渠道 | 日预估产出 | 说明
--- | --- | ---
解谜通关 | 800-1500 | 首次通关奖励高，重复递减
自动化生产 | 500-2000 | 取决于生产线效率与在线时长
每日任务 | 300 | 固定日任务奖励
蓝图销售分成 | 0-5000 | 他人购买作者蓝图，作者获 70%
多人对战奖励 | 100-600 | 按胜负与段位

消耗渠道 | 单次消耗 | 说明
--- | --- | ---
购买元件(单价) | 5-1000 | 按元件类型差异定价
解锁关卡章节 | 2000-8000 | 逐章递增
购买蓝图 | 0-3000 | 作者定价，平台抽成 30%
商店道具 | 100-500 | 消耗品与装饰品
自动化原料采购 | 5-200 | 生产链原料采购成本

### 9.3 充值档位

档位 | 价格 | 金币 | 额外赠送
--- | --- | --- | ---
新手包 | ¥6 | 60 | 首充双倍 + 新手元件包
标准包 | ¥30 | 300 | 30 金币 + 限定皮肤
超值包 | ¥68 | 680 | 120 金币 + 赛季通行证
豪华包 | ¥168 | 1680 | 400 金币 + 专属称号

10 / USER SYSTEM

## 用户系统

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

### 10.1 注册登录

规则项 | 要求 | 说明
--- | --- | ---
用户名 | 3-32 字符 | 字母数字下划线，唯一
邮箱 | 有效邮箱 | 用于找回密码与通知
密码 | 8-64 字符 | 需含大小写字母与数字，bcrypt 加密
第三方登录 | Google / GitHub / Discord | 支持 OAuth2 快捷登录
验证方式 | 邮箱验证码 | 注册与找回密码需验证

安全措施 | 说明
--- | ---
密码加密 | bcrypt 哈希存储，不存明文
JWT Token | 双 Token 机制，Access 短期 + Refresh 长期
异地登录检测 | 新设备登录需邮箱二次验证
登录频率限制 | 5 次失败锁定 15 分钟
数据传输加密 | 全站 HTTPS / WSS

### 新手引导流程

步骤 | 内容 | 奖励
--- | --- | ---
1 | 创建账号与角色 | 100 红石币
2 | 基础元件放置教学 | 150 红石币
3 | 完成首个教程关卡 | 200 红石币 + 经验
4 | 商店购买教学 | 拉杆元件 x5
5 | 分享首个电路 | 300 红石币 + 成就

### 10.2 等级与解锁

等级段 | 等级范围 | 经验要求 | 解锁内容
--- | --- | --- | ---
新手 | 1-10 | 0-5,000 | 基础元件、第 1-2 章、自由搭建
进阶 | 11-25 | 5,000-30,000 | 逻辑门元件、第 3-4 章、自动化
高级 | 26-50 | 30,000-120,000 | 特殊元件、第 5-6 章、多人模式
大师 | 51+ | 120,000+ | 全部解锁、蓝图上传、赛季排位

### 10.3 成就系统

成就 | 解锁条件 | 奖励
--- | --- | ---
初出茅庐 | 完成新手引导 | 300 红石币
电路学徒 | 通关 10 个解谜关卡 | 500 红石币 + 经验
逻辑大师 | 用逻辑门完成 50 个关卡 | 1000 红石币 + 称号
满星达人 | 累计获得 100 颗星 | 800 金币 + 限定皮肤
蓝图创作者 | 上传首个蓝图 | 200 红石币
人气作者 | 蓝图累计下载 1000 次 | 2000 红石币 + 称号
赛季冠军 | 达到宗师段位 | 5000 金币 + 限定蓝图

11 / MILESTONES

## 开发里程碑

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

阶段 | 时间 | 交付物 | 团队规模
--- | --- | --- | ---
Phase 1 原型期 | M1-M2 | 核心仿真引擎、基础编辑器、5 种元件原型 | 4 人
Phase 2 Alpha | M3-M5 | 全部 4 模式、经济系统、用户认证、前 3 章关卡 | 8 人
Phase 3 Beta | M6-M8 | 多人联机、蓝图工坊、商店、全 240 关、UI 打磨 | 12 人
Phase 4 发布 | M9 | 官网上线、监控告警、热修复管线、客服系统 | 12 人
Phase 5 运营 | M10+ | 赛季内容、限时活动、平衡性补丁、数据分析 | 10 人

12 / DEPLOYMENT

## 部署与运维

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

领域 | 方案 | 说明
--- | --- | ---
服务端部署 | Docker + Kubernetes | 容器化微服务，HPA 自动伸缩，滚动更新
客户端分发 | 官网安装包 + 自动更新服务 | 官网提供 Windows/macOS 安装包，内置增量更新客户端
CI/CD | GitHub Actions | 推送触发自动构建、单元测试、集成测试、部署
服务端监控 | Prometheus + Grafana | CPU/内存/QPS/延迟指标，告警规则推送到钉钉
错误追踪 | Sentry | 客户端崩溃报告与服务端异常堆栈统一收集
CDN | 蓝图文件 + 更新补丁 | 静态资源与增量更新包走 CDN 加速分发
日志收集 | ELK Stack | Elasticsearch + Logstash + Kibana 日志检索
备份策略 | 每日全量 + 实时 WAL | PostgreSQL 每日全量备份，WAL 实时归档

13 / RISKS

## 风险评估

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

风险项 | 类别 | 概率 | 影响 | 缓解措施
--- | --- | --- | --- | ---
大规模电路仿真性能瓶颈 | 技术 | 中 | 高 | ECS 优化、分块加载、LOD 降级、多线程
红石逻辑还原度不足 | 技术 | 低 | 高 | 对照 MC 原版行为单元测试，社区反馈迭代
多人同步延迟与一致性 | 技术 | 中 | 中 | 客户端预测+服务端权威，Delta 压缩同步
同类竞品挤压市场 | 市场 | 中 | 高 | 差异化双货币+UGC 生态，社区运营前置
玩家留存不及预期 | 市场 | 中 | 高 | 数据驱动关卡调优，限时活动促活
UGC 内容审核滞后 | 运营 | 中 | 中 | 机审+人审双通道，举报快速响应机制
服务器成本超预算 | 运营 | 低 | 中 | HPA 弹性伸缩，闲时缩容，预留缓存层
经济系统通胀失控 | 运营 | 中 | 高 | 产出消耗动态监控，定期平衡性补丁
账号盗号与黑产刷币 | 安全 | 中 | 高 | 异地登录验证、行为风控、交易限额
客户端被逆向破解 | 安全 | 低 | 中 | 代码混淆、关键逻辑服务端校验、反调试

15 / SPRINT PLAN

## Sprint 分解与排期

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

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

Sprint | 周期 | 交付物 | 验收标准
--- | --- | --- | ---
S1 | W1-2 | 项目骨架搭建：Unity 工程初始化、Go 项目骨架、CI 基础流水线、Git 仓库与代码规范 | Unity 可编译运行空场景；Go 服务可启动并返回 health check；CI 可自动构建
S2 | W3-4 | 网格画布渲染器 + 元件放置系统：16x16 网格、元件拖放放置、基础 8 种元件数据结构 | 可在画布上放置/删除/移动元件；网格坐标正确；元件数据 JSON 序列化通过
S3 | W5-6 | 信号仿真引擎 v1：红石粉信号传播、衰减计算、电源->导线->输出基本链路 | 红石火把->红石粉->红石灯 链路可点亮；信号强度衰减正确；1 tick = 0.1s 时序正确
S4 | W7-8 | 仿真引擎 v2 + 工具栏 UI：中继器/比较器/逻辑门仿真、保存/加载/运行/暂停按钮、成本计算 | 逻辑门输出正确（真值表验证）；电路可保存为 JSON 并重新加载；成本实时计算

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

Sprint | 周期 | 交付物 | 验收标准
--- | --- | --- | ---
S5 | W9-10 | 用户认证系统：注册/登录 API、JWT Token、SQLite 本地存档、PostgreSQL 用户表 | 注册->登录->获取Token->访问受保护接口 全链路通过；密码 bcrypt 加密；Token 过期自动刷新
S6 | W11-12 | 解谜关卡系统 v1：关卡数据结构、关卡加载器、前 30 关（第一章）、三星评级算法 | 30 关可游玩；输入/输出验证正确；三星评级按成本和延迟计算
S7 | W13-14 | 自由搭建模式 + 画布扩展至 128x128 + 全部 80 种元件数据填充 | 128x128 画布流畅运行(>30fps)；80 种元件均可放置和仿真；无限资源模式
S8 | W15-16 | 货币系统 + 商店 UI：红石币/金币数据库表、交易流水、商店 4 标签页、购买逻辑 | 解谜通关奖励红石币正确入账；商店购买扣费正确；交易流水可追溯
S9 | W17-18 | 自动化生产模式 v1：资源采集->传输->加工->出售 链路、效率计算、8 种资源 | 自动农场可运行产出资源；资源出售获得红石币；效率系数 0.5x-2.0x 正确
S10 | W19-20 | 解谜第二章 40 关 + 第三章前 25 关 + 成就系统 v1 + 等级系统 | 累计 95 关可游玩；等级升级正确解锁元件；7 个成就可触发

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

Sprint | 周期 | 交付物 | 验收标准
--- | --- | --- | ---
S11 | W21-22 | 多人联机核心：WebSocket 网关、客户端预测+服务端校验、实时画布同步 | 2 人同时编辑同一画布延迟 <200ms；冲突解决正确；断线重连恢复
S12 | W23-24 | 多人对战模式：电路竞速、成本竞速、匹配系统、积分排行 | 4 人匹配对局可完整进行；排行榜实时更新；积分增减正确
S13 | W25-26 | 蓝图工坊：蓝图上传/下载/评分/搜索、MinIO 文件存储、蓝图市场 UI | 蓝图可上传并下载复现；评分系统正常；搜索可按名称/作者/标签过滤
S14 | W27-28 | 解谜第三至第五章共 150 关 + 多人协作模式 + 信号攻防模式 | 累计 245 关可游玩；协作模式 4 人共建正常；信号攻防 2v2 可进行
S15 | W29-30 | 全 UI 打磨：动效系统、暗色/亮色主题、响应式适配、无障碍优化 | Lighthouse 评分 >85；动效 60fps；prefers-reduced-motion 生效；键盘可操作
S16 | W31-32 | 第五章剩余 + 第六章 20 关大师关 + 性能优化 + Bug 修复 + 封闭 Beta 测试 | 240 关全部可游玩；512x512 画布 >30fps；P0 Bug 清零；封闭 Beta 500 人测试

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

Sprint | 周期 | 交付物 | 验收标准
--- | --- | --- | ---
S17 | W33-34 | 开放 Beta + 压力测试 + 热修复管线 + 客服系统 + 数据分析埋点 | 5000 并发用户稳定；P0 Bug 24h 内修复；数据分析看板可查看 DAU/留存
S18 | W35-36 | 正式发布 + 监控告警 + 运营活动配置系统 + 赛季系统上线 | 正式环境运行稳定；告警 <5min 响应；第一赛季可正常运行；首周留存 >35%

16 / TEAM

## 团队组织与职责

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

### 团队配置阶段表

阶段 | 人数 | 角色构成 | 关键职责
--- | --- | --- | ---
Phase 1 | 4 | 技术主策 1 + 客户端 1 + 服务端 1 + 美术 1 | 核心引擎原型、美术风格验证
Phase 2 | 8 | + 客户端 2 + 服务端 1 + 策划 1 + QA 1 | 全模式开发、经济系统、认证系统
Phase 3 | 12 | + 客户端 1 + 服务端 1 + 美术 1 + QA 1 | 多人联机、蓝图工坊、全关卡、UI 打磨
Phase 4-5 | 10-12 | 稳定团队 + 运营 1 + 数据分析 1 | 发布运维、赛季内容、平衡性调优

### 角色职责矩阵

角色 | 核心职责 | 技术栈要求 | 产出物
--- | --- | --- | ---
技术主策 / Tech Lead | 架构决策、技术选型、代码审查、跨端协调 | Unity C# + Go + 系统设计 | 架构文档、技术方案、Code Review 记录
客户端工程师 x4 | Unity 渲染、UI Toolkit、仿真引擎客户端、网络层 | Unity 2024 LTS, C#, UI Toolkit | 客户端模块代码、性能报告
服务端工程师 x2 | Go 微服务、数据库设计、WebSocket 网关、反作弊 | Go, Gin, PostgreSQL, Redis | API 服务代码、数据库 Migration、接口文档
游戏策划 x1 | 关卡设计、数值平衡、经济系统调优、赛季规划 | Excel/Python 数据分析、关卡编辑器 | 关卡数据 JSON、数值表、策划案
UI/UX 美术 x2 | UI 设计、像素元件图标、特效、主题 | Figma, Aseprite, Unity Shader | UI 切图、图标素材、特效预设
QA 测试 x2 | 功能测试、自动化测试、性能测试、Bug 管理 | Python, Selenium, Unity Test Framework | 测试用例、Bug 报告、自动化脚本
运营 / 数据 x1 | 活动配置、数据分析、社区运营、赛季管理 | SQL, Tableau, 社区工具 | 运营报告、活动配置、数据看板

### 协作流程

流程 | 工具 | 规则
--- | --- | ---
代码管理 | Git + GitHub | main 分支保护；feature/* 分支开发；PR 至少 1 人 Review 后合并；Sprint 结束打 tag
任务管理 | GitHub Projects / Jira | Sprint Backlog 拆分至 2 人日以内；每日 Standup 15 分钟；Sprint Review + Retro
文档管理 | Notion / Confluence | API 文档 Swagger 自动生成；设计文档 PR 附带；会议纪要 24h 内归档
CI/CD | GitHub Actions | PR 触发自动构建+测试；main 分支自动部署 Staging；Tag 发布 Production
沟通 | 飞书 / Discord | 技术讨论频道；紧急问题电话优先；每周技术分享 1 小时
Bug 追踪 | GitHub Issues | P0 当日修复；P1 当 Sprint 修复；P2 排入 Backlog；Bug 复现步骤必填

17 / CLIENT MODULES

## 客户端模块详设

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

### 17.1 模块总览

模块 | 命名空间 | 职责 | 核心脚本
--- | --- | --- | ---
GridRenderer | RedCircuit.Grid | 网格画布渲染、视口裁剪、LOD | GridCanvas.cs, ChunkManager.cs, TileRenderer.cs
SimulationEngine | RedCircuit.Simulation | 信号传播、元件仿真、tick 循环 | SimulationLoop.cs, SignalPropagator.cs, ComponentBehavior.cs
ComponentSystem | RedCircuit.Components | 80 种元件数据定义、放置/删除/旋转 | ComponentRegistry.cs, PlacementController.cs, ComponentData.cs
UISystem | RedCircuit.UI | UI Toolkit 界面、工具栏、面板、弹窗 | EditorWindow.cs, ToolbarController.cs, PalettePanel.cs, InspectorPanel.cs
NetworkClient | RedCircuit.Net | REST 请求、WebSocket 连接、delta 同步 | ApiClient.cs, WsClient.cs, SyncManager.cs
SaveSystem | RedCircuit.Save | 本地 SQLite 存档、云端同步、蓝图导出 | SaveManager.cs, LocalDatabase.cs, CloudSync.cs
AudioSystem | RedCircuit.Audio | 音符盒/蜂鸣器音效、UI 音效、BGM | AudioManager.cs, NotePlayer.cs
AuthSystem | RedCircuit.Auth | 登录注册、Token 管理、第三方 OAuth | AuthManager.cs, TokenStore.cs, OAuthClient.cs

### 17.2 仿真引擎核心数据结构

类名 | 字段 | 说明
--- | --- | ---
GridCell | int x, y; Component component; int signalStrength; List<GridCell> neighbors | 网格单元，记录坐标、元件实例、当前信号强度、四邻连接
Component | ComponentType type; int rotation; Dictionary<string, int> properties; bool isPowered | 元件实例，类型、朝向、可调属性（阻值/延迟/模式等）、通电状态
SignalUpdate | GridCell target; int newStrength; int tick; SignalSource source | 信号更新事件，BFS 队列元素，记录目标格、新强度、tick 序号、来源
CircuitGraph | Dictionary<Vector2Int, GridCell> cells; Queue<SignalUpdate> updateQueue; HashSet<Vector2Int> dirtyCells | 电路图数据，全格字典 + 信号更新队列 + 脏标记集合
SimulationConfig | float tickDuration; int maxGridSize; bool enableShortCircuitDetection; bool stepMode | 仿真配置，tick 时长、最大画布、短路检测开关、步进模式

### 17.3 渲染性能策略

策略 | 实现方式 | 目标
--- | --- | ---
分块加载 | 画布按 16x16 分 Chunk，视口内 Chunk 才实例化 GameObject | 512x512 画布内存占用 <512MB
对象池 | 元件 GameObject 预生成 500 个池化，放置时取用而非 Instantiate | 消除 GC Spike，放置延迟 <16ms
GPU Instancing | 同类型元件使用 GPU Instancing 批量渲染 | 1000+ 元件同帧 Draw Call <50
信号轨迹 Shader | 红石信号轨迹用自定义 Shader 绘制，非逐格 GameObject | 信号动画 60fps，不随电路规模增长
LOD 降级 | 缩放 <50% 时元件图标降级为纯色方块，不渲染细节 | 全景浏览 512x512 保持 >30fps
仿真分帧 | 大电路仿真 BFS 分帧执行，每帧最多处理 2000 格更新 | 避免大电路导致主线程卡顿

### 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 微服务总览

服务 | 语言/框架 | 端口 | 数据库 | 核心职责
--- | --- | --- | --- | ---
auth-service | Go / Gin | 8081 | PostgreSQL(users) | 注册/登录/JWT/第三方OAuth/Token刷新
economy-service | Go / Gin | 8082 | PostgreSQL(transactions) + Redis(balance cache) | 货币余额/交易流水/商店购买/充值回调
blueprint-service | Go / Gin | 8083 | PostgreSQL(blueprints) + MinIO(files) | 蓝图CRUD/评分/搜索/下载/分类
match-service | Go + WebSocket | 8084 | Redis(matchmaking) + PostgreSQL(matches) | 匹配/房间管理/实时同步/对战结算
social-service | Go / Gin | 8085 | PostgreSQL(achievements) + Redis(leaderboard) | 成就/排行榜/好友/赛季/活动

### 18.2 auth-service 核心接口

接口 | 请求 | 响应 | 备注
--- | --- | --- | ---
POST /register | { username, email, password } | { userId, token, refreshToken } | 密码 bcrypt；发送验证邮件
POST /login | { username, password } | { userId, token, refreshToken, profile } | 5 次错误锁定 15min
POST /refresh | { refreshToken } | { token, refreshToken } | 旧 Token 黑名单
POST /oauth/callback | { provider, code } | { userId, token, refreshToken } | Google/GitHub/Discord
GET /profile | Header: Authorization | { userId, username, email, level, exp, balance } | 聚合 economy-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 数据库索引策略

表 | 索引 | 类型 | 查询场景
--- | --- | --- | ---
users | idx_users_username | UNIQUE B-Tree | 登录时按用户名查询
users | idx_users_email | UNIQUE B-Tree | 邮箱验证/找回密码
circuits | idx_circuits_user_id | B-Tree | 查询用户所有电路
circuits | idx_circuits_updated | B-Tree DESC | 按更新时间排序
blueprints | idx_bp_author | B-Tree | 作者蓝图列表
blueprints | idx_bp_category_rating | Composite B-Tree | 分类+评分排序
transactions | idx_tx_user_created | Composite B-Tree DESC | 用户交易历史分页
puzzle_levels | idx_puzzle_chapter_level | Composite B-Tree | 章节+关卡序号排序
multiplayer_matches | idx_match_status_started | Composite B-Tree | 按状态+时间查询对局

18.5 / RELAY SERVER

## 联机服务器中转站开发

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

### 架构定位

维度 | 说明
--- | ---
服务名称 | relay-server (Go 1.22 + gorilla/websocket)
端口 | TCP 8084 (WebSocket) / UDP 8086 (STUN/TURN)
部署形态 | 独立进程，不与 auth/economy 等业务服务混部；可水平扩展多节点 + 负载均衡
核心职责 | 房间生命周期管理 / WebSocket 长连接维护 / 消息路由转发 / P2P 打洞辅助 / TURN 中继兜底 / 断线重连状态恢复
不负责 | 用户认证(由 auth-service 签发 Token，relay 仅校验) / 货币结算 / 蓝图存储
设计目标 | 单节点支持 5000 并发 WebSocket 连接 / 200 个活跃房间 / 消息转发延迟 P99 <50ms

### 连接拓扑

    ┌──────────┐         ┌──────────────┐         ┌──────────┐
    │ 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 中继

阶段 | 行为 | 协议 | 超时
--- | --- | --- | ---
1. ICE 候选收集 | 客户端收集本地/反射/中继候选地址 | STUN (UDP) | 5s
2. 候选交换 | 通过 relay-server WebSocket 交换 SDP 和 ICE 候选 | WebSocket | 3s
3. 连接检查 | ICE 对每对候选地址进行连通性检查 | STUN Binding | 10s
4a. P2P 直连成功 | 后续游戏数据走 P2P 通道，relay 仅维持信令 | UDP (P2P) | -
4b. P2P 失败 -> TURN | 分配 TURN 中继地址，所有数据经 TURN 转发 | TURN (UDP) | -
4c. TURN 失败 -> WSS | 回退到 WebSocket 中心化转发 | WebSocket | -
5. 心跳保活 | P2P 模式每 15s 发 STUN Binding 保活；WSS 模式 30s 心跳 | STUN / WS | 60s 无响应断开

### 断线重连策略

断线时长 | 客户端行为 | 服务端行为 | 恢复方式
--- | --- | --- | ---
<5s | 自动重连，缓存消息 | 保留房间和玩家状态 | WebSocket 重连 + 增量同步
5-30s | 显示"重连中..."UI | 标记玩家为"暂离"，保留位置 | 重连 + 全量快照 + 最近 50 条消息
30s-3min | 重试退避 (1s/2s/4s/8s) | 保留房间，玩家标记"掉线" | 重连 + 全量快照
3-30min | 提示"连接超时" | 房间保留，玩家可手动重连 | 重新加入房间
>30min | - | 房间超时回收，玩家移除 | 需重新创建/加入房间

### 水平扩展方案

组件 | 方案 | 说明
--- | --- | ---
负载均衡 | L4 TCP 负载均衡 (HAProxy / Nginx stream) | WebSocket 长连接用最少连接策略；sticky session by userID
跨节点消息 | Redis Pub/Sub | 房间内玩家可能连在不同 relay 节点；消息先发 Redis channel，各节点订阅自己管理的房间
房间状态持久化 | Redis Hash (room:{id}) | 房间元数据 + 玩家列表持久化，节点故障后可恢复
电路快照存储 | Redis (热) + MinIO (冷) | 活跃房间电路快照存 Redis；房间结束后归档 MinIO
连接亲和性 | Consistent Hash by roomID | 同一房间的玩家尽量路由到同一 relay 节点，减少跨节点转发
优雅缩容 | drain 模式 | 节点标记 draining 后拒绝新连接，等现有连接自然结束或迁移

### 监控指标

指标 | Prometheus Metric | 告警阈值
--- | --- | ---
在线 WebSocket 连接数 | relay_connections_total | >4500 (单节点)
活跃房间数 | relay_rooms_active | >180
消息转发延迟 P99 | relay_msg_latency_seconds (histogram) | >50ms
消息丢失率 | relay_msg_drop_rate | >0.1%
P2P 打洞成功率 | relay_p2p_success_rate | <70%
TURN 中继流量 | relay_turn_bytes_total (counter) | 月预算阈值告警
断线重连成功率 | relay_reconnect_success_rate | <90%
goroutine 数量 | go_goroutines | >10000

### 开发任务分解

任务 | Sprint | 人日 | 依赖
--- | --- | --- | ---
WebSocket 连接管理 + 读写 goroutine + 心跳 | S11 | 3 | 无
房间状态机 + 玩家管理 + 广播机制 | S11 | 4 | WS 连接管理
Protobuf 消息协议定义 + 编解码 | S11 | 2 | 无
电路增量同步 (delta apply + broadcast) | S11 | 4 | 房间管理
断线重连 + 全量快照恢复 | S12 | 3 | 增量同步
STUN/TURN 服务集成 + ICE 候选交换 | S12 | 5 | WS 连接管理
Redis Pub/Sub 跨节点消息 | S12 | 3 | 房间管理
游戏操作服务端校验 (多人对战) | S12 | 3 | 增量同步
Prometheus 指标埋点 + Grafana 看板 | S12 | 2 | WS 连接管理
压力测试 (5000 连接 + 200 房间) | S16 | 3 | 全部功能完成
合计 | - | 32 | -

19 / TESTING

## 测试与质量保障

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

### 19.1 测试分层

层级 | 覆盖率目标 | 工具 | 运行频率 | 负责人
--- | --- | --- | --- | ---
单元测试 | >=80% | Unity Test Framework (客户端) / Go testing (服务端) | 每次 PR | 开发人员
集成测试 | 核心链路 100% | Go test + Docker Compose / Unity PlayMode | 每日 Nightly | QA + 开发
性能测试 | 关键指标达标 | Unity Profiler / k6 / wrk | 每 Sprint | QA
E2E 测试 | 主流程 100% | Unity PlayMode + API 自动化 | 每 Sprint | QA

### 19.2 仿真引擎单元测试用例

用例编号 | 测试场景 | 输入 | 预期输出
--- | --- | --- | ---
SIM-001 | 红石粉信号衰减 | 电源(15) + 15 格红石粉 | 第 15 格强度=1，第 16 格=0
SIM-002 | 中继器重置强度 | 衰减至 1 的信号经中继器 | 中继器输出强度=15
SIM-003 | AND 门真值表 | 4 种输入组合 (00/01/10/11) | 输出 0/0/0/1
SIM-004 | 红石火把反相 | 附着方块有信号 | 火把熄灭，无输出
SIM-005 | 中继器锁存 | 侧面输入信号时 | 输出冻结在当前状态
SIM-006 | 活塞推动链 | 13 个连续方块 | 推动失败（超过 12 个上限）
SIM-007 | 短路检测 | 两个电源直连同一导线 | 触发短路警告，仿真暂停
SIM-008 | 555 无稳态振荡 | R=10, C=4 | 输出方波，周期 = 0.693*(R1+R2)*C tick
SIM-009 | 运放反相放大 | Vin=5, Rf=10, R1=5 | Vout = -10
SIM-010 | ADC 4-bit 转换 | 模拟输入强度=13 | 数字输出 = 1101

### 19.3 性能指标与压测目标

场景 | 指标 | 目标值 | 工具
--- | --- | --- | ---
客户端 - 小型电路 (50 元件) | 仿真 FPS | >=60 fps | Unity Profiler
客户端 - 大型电路 (500 元件) | 仿真 FPS | >=30 fps | Unity Profiler
客户端 - 超大画布 (512x512) | 渲染 FPS | >=30 fps | Unity Profiler
客户端 - 内存占用 | 峰值内存 | <=1GB | Unity Memory Profiler
服务端 - 登录接口 | P99 延迟 | <=100ms | wrk
服务端 - 商店购买 | P99 延迟 | <=200ms | wrk
服务端 - 并发用户 | 最大并发 | >=5000 | k6
多人同步 - 画布编辑 | 端到端延迟 | <=200ms | 自定义压测脚本
多人同步 - 匹配等待 | 平均等待 | <=30s | 日志统计

### 19.4 Bug 分级与响应 SLA

级别 | 定义 | 响应时间 | 修复时限
--- | --- | --- | ---
P0 阻塞 | 崩溃/数据丢失/核心功能不可用/安全漏洞 | 30 分钟 | 24 小时内
P1 严重 | 核心功能异常/性能严重退化/支付错误 | 2 小时 | 当前 Sprint 内
P2 一般 | 非核心功能异常/UI 错位/文案错误 | 1 个工作日 | 下个 Sprint
P3 轻微 | 体验优化/建议类 | 3 个工作日 | Backlog 排期

20 / PERFORMANCE

## 性能优化方案

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

### 20.1 客户端优化

优化项 | 问题 | 方案 | 实施节点
--- | --- | --- | ---
ECS 仿真 | 大电路 GameObject 方式导致 GC Spike | 仿真数据迁移至 ECS (Entities 1.0)，元件数据用 IComponentData，信号传播用 IJobChunk | S4 仿真引擎重构
分块渲染 | 512x512 画布全量渲染卡顿 | 16x16 Chunk + 视口裁剪，仅渲染可见区域 + 1 格缓冲 | S2 画布开发时
信号轨迹 GPU 绘制 | 每格信号线逐个 GameObject 性能差 | ComputeBuffer + 自定义 Shader，全画布信号轨迹一次 DrawCall | S4 仿真引擎 v2
对象池 | 放置/删除元件频繁 Instantiate/Destroy | 预生成 500 个元件 GameObject 池，按需取用/归还 | S2 画布开发时
仿真分帧 | 大电路单 tick BFS 导致主线程阻塞 | BFS 分帧执行，每帧最多 2000 格更新，跨帧续传 | S4 仿真引擎 v2
LOD 降级 | 全景浏览时细节渲染浪费 GPU | 缩放 <50% 时元件降级为纯色方块，关闭信号动画 | S15 UI 打磨
纹理图集 | 80 种元件图标各自纹理导致 DrawCall 多 | 所有元件图标打包为 1024x1024 Atlas，单次 DrawCall | S7 元件填充时
异步加载 | 关卡数据/蓝图加载阻塞主线程 | JSON 反序列化放入 async Task，加载完成回调切换 | S6 关卡系统

### 20.2 服务端优化

优化项 | 问题 | 方案 | 实施节点
--- | --- | --- | ---
Redis 余额缓存 | 每次请求查 PostgreSQL 余额慢 | 余额写入 Redis Cache-Aside，写操作回写 DB + 失效缓存 | S8 货币系统
连接池 | 数据库频繁建连开销大 | pgxpool 连接池，最大 25 连接/服务，空闲 60s 回收 | S5 认证系统
排行榜 ZSET | 排行榜分页查询慢 | Redis Sorted Set 存储积分排名，ZREVRANGE 分页 | S12 多人对战
蓝图搜索 ES | PostgreSQL LIKE 搜索全表扫描 | 蓝图数据同步至 Elasticsearch，支持全文搜索+标签过滤 | S13 蓝图工坊
API 限流 | 恶意刷接口 | Nginx 层 rate_limit 100req/min/IP；关键接口令牌桶 10req/s/user | S5 认证系统
异步任务队列 | 成就检查/经济结算阻塞请求 | RabbitMQ 消费者异步处理，请求仅入队即返回 | S8 货币系统

### 20.3 网络优化

优化项 | 方案 | 效果
--- | --- | ---
Delta 同步 | 多人编辑仅同步变更的格子和元件，非全量画布 | 带宽减少 90%+
Protobuf 编码 | 实时同步消息用 Protobuf 替代 JSON | 消息体积减少 60%+
WebSocket 压缩 | 开启 permessage-deflate 压缩 | 带宽减少 50%+
客户端预测 | 元件放置/删除本地立即生效，服务端确认后修正 | 操作延迟感知 <50ms
断线重连 | WebSocket 断开 30s 内重连，恢复画布状态 | 用户体验连续

21 / SECURITY

## 安全实施方案

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

### 21.1 认证与授权

措施 | 实现方式 | 说明
--- | --- | ---
密码加密 | bcrypt cost=12 | 服务端加盐哈希，不可逆
JWT Token | RS256 签名，Access 15min + Refresh 7d | Access Token 无状态；Refresh Token Redis 黑名单
登录保护 | 5 次错误锁定 15min + IP 限流 | 防止暴力破解
异地登录验证 | 新设备/新IP 邮箱二次验证码 | 6 位数字验证码，5min 有效
OAuth 第三方 | Google/GitHub/Discord OAuth2 | 不存储第三方密码，仅存 provider+providerId
API 鉴权 | Bearer Token + RBAC 权限校验 | 每个接口声明所需角色，中间件统一校验

### 21.2 数据安全

措施 | 实现方式
--- | ---
传输加密 | 全站 HTTPS TLS 1.3；WebSocket over TLS (wss)
敏感数据加密 | 邮箱/手机号 AES-256-GCM 加密存储；密钥 KMS 管理
SQL 注入防护 | Go ORM 参数化查询，禁止字符串拼接 SQL
XSS 防护 | 蓝图描述/用户名等 UGC 内容 HTML 转义后存储
CSRF 防护 | SameSite=Strict Cookie + CSRF Token 双重防护
数据备份 | PostgreSQL 每日全量 + WAL 实时归档；7 日保留期
GDPR 合规 | 支持账号注销+数据导出；隐私政策明确告知数据用途

### 21.3 反作弊系统

场景 | 检测方式 | 处理措施
--- | --- | ---
解谜作弊 | 服务端校验电路数据合法性 + 输出验证 | 拒绝奖励，记录异常行为
货币刷取 | 产出频率监控 + 行为模式分析 | 异常产出冻结账户，人工审核
多人对战作弊 | 关键操作服务端权威校验 + 客户端预测修正 | 判定无效，扣除积分，封禁 7 天
蓝图抄袭 | 蓝图哈希比对 + 相似度算法 | 下架抄袭蓝图，警告作者
客户端修改 | 代码混淆 + 关键逻辑服务端校验 + 完整性校验 | 完整性校验失败拒绝登录
黑产刷币 | 交易频率监控 + IP 设备指纹 + 金额异常检测 | 冻结资产，IP 封禁，上报风控

22 / CI/CD

## CI/CD 流水线

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

### 22.1 流水线阶段

阶段 | 触发 | 任务 | 预计时长
--- | --- | --- | ---
Lint & Build | PR / Push | Go vet + golangci-lint；Unity Build；编译检查 | 3 min
Unit Test | PR / Push | Go test -race -cover；Unity EditMode + PlayMode Test | 5 min
Integration Test | Push to main | Docker Compose 启动全链路；API 集成测试 | 8 min
Build Artifacts | Push to main / Tag | Go 二进制编译；Unity 客户端打包(Win+Mac) | 15 min
Deploy Staging | Push to main | Docker 镜像推 Harbor；K8s 滚动更新 Staging | 5 min
Smoke Test | Deploy Staging 后 | 核心接口可用性检查；客户端启动测试 | 3 min
Deploy Production | Tag v* 手动触发 | 人工确认 -> K8s 滚动更新 Production | 5 min

### 22.2 环境配置

环境 | 用途 | 数据库 | 部署方式
--- | --- | --- | ---
Local | 开发调试 | SQLite + 本地 Redis | docker-compose dev
Staging | 集成测试 + QA 验收 | PostgreSQL(单机) + Redis(单机) | K8s staging namespace
Beta | 封闭/开放 Beta 测试 | PostgreSQL(主从) + Redis(哨兵) | K8s beta namespace (2 副本)
Production | 正式生产 | PostgreSQL(主从+读写分离) + Redis(集群) | K8s production namespace (3+ 副本 + HPA)

### 22.3 发布与回滚

操作 | 方式 | 预计耗时
--- | --- | ---
正常发布 | Git Tag -> CI 自动构建 -> K8s 滚动更新(零停机) | 15-20 min
热修复 | hotfix 分支 -> 快速 CI -> 直接部署 Production | 10-15 min
紧急回滚 | kubectl rollout undo deployment/xxx --to-revision=N | 2 min
数据库回滚 | Migration down 脚本 + WAL 恢复 | 15 min
客户端热更新 | 配置/数值/关卡 JSON 增量下发 | 即时
客户端全量更新 | 官网安装包替换 + 增量补丁 | 用户下次启动

23 / BUDGET

## 预算与成本估算

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

### 23.1 人力成本

阶段 | 人数 | 月数 | 人均月薪 | 小计
--- | --- | --- | --- | ---
Phase 1 (M1-2) | 4 | 2 | 25,000 | 200,000
Phase 2 (M3-5) | 8 | 3 | 25,000 | 600,000
Phase 3 (M6-8) | 12 | 3 | 25,000 | 900,000
Phase 4 (M9) | 12 | 1 | 25,000 | 300,000
开发期合计 | - | 9 | - | 2,000,000
首年运营 (M10-12) | 10 | 3 | 25,000 | 750,000
总计首年 | - | 12 | - | 2,750,000

### 23.2 基础设施成本（月度）

项目 | 规格 | 月费用 | 备注
--- | --- | --- | ---
应用服务器 | 8C16G x3 (K8s 节点) | 3,600 | 阿里云 ECS
数据库 | PostgreSQL 8C32G 主从 | 4,500 | RDS 高可用版
Redis | 4G 集群版 | 800 | 阿里云 Redis
对象存储 | MinIO/OSS 500GB | 500 | 蓝图文件+截图
CDN | 1TB/月 流量 | 500 | 更新包+静态资源
消息队列 | RabbitMQ 2C4G | 600 | 异步任务
Elasticsearch | 2C8G | 1,200 | 蓝图搜索
监控+日志 | Prometheus+Grafana+ELK | 1,500 | 自建+云服务混合
域名+SSL | redcircuit.game + 通配符证书 | 100 | 年费摊月
月度合计 | - | 13,300 | -
首年合计 | - | 159,600 | -

### 23.3 其他成本

项目 | 费用 | 说明
--- | --- | ---
Unity 订阅 | 0 | Unity Personal 免费版（年收入 <20万刀）；Pro 版 $204/月/座 (年收入超限后)
开发工具 | 20,000 | Figma Pro + JetBrains IDE + 其他工具年费
第三方服务 | 15,000 | 邮件服务/SMS 验证码/OAuth/API 网关
美术外包 | 80,000 | 部分元件图标/特效/UI 切图外包
QA 外包 | 30,000 | Beta 测试期间外包测试
营销推广 | 100,000 | 首发推广+B 站/KOL 合作
其他合计 | 245,000 | -

### 23.4 总预算汇总

类别 | 金额 | 占比
--- | --- | ---
人力成本 | 2,750,000 | 87%
基础设施 | 159,600 | 5%
其他成本 | 245,000 | 8%
总计首年预算 | 3,154,600 | 100%
建议预留缓冲 (15%) | 473,190 | -
建议总预算 | 3,627,790 | -

24 / ROLLOUT

## 上线发布策略

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

### 24.1 灰度发布计划

阶段 | 时间 | 用户量 | 目标 | 通过标准
--- | --- | --- | --- | ---
内测 Alpha | M5 结束 | 团队 20 人 | 核心功能验证 | P0 Bug 清零
封闭 Beta | M8 结束 | 500 人邀请制 | 全功能验证 + 压力测试 | P0/P1 清零；留存 >30%
开放 Beta | M9 W1-2 | 5,000 人公开注册 | 服务器压测 + 数据收集 | 5000 并发稳定；P0 清零
正式发布 | M9 W3 | 全网开放 | 商业化运营启动 | 首周 DAU >5,000；留存 >35%
推广期 | M10+ | 持续增长 | KOL 推广 + 社区运营 | MAU >50,000

### 24.2 发布日监控清单

监控项 | 工具 | 告警阈值 | 负责人
--- | --- | --- | ---
服务器 CPU | Prometheus | >80% 持续 5min | 服务端工程师
服务器内存 | Prometheus | >85% 持续 5min | 服务端工程师
API P99 延迟 | Grafana | >500ms | 服务端工程师
API 错误率 | Sentry | >1% | 服务端工程师
客户端崩溃率 | Sentry | >2% | 客户端工程师
WebSocket 连接数 | Grafana | >4000 | 服务端工程师
数据库慢查询 | pg_stat_statements | >1s | DBA / 服务端
登录成功率 | Grafana | <95% | QA
支付成功率 | Grafana | <98% | QA + 运营

### 24.3 应急预案

故障等级 | 触发条件 | 响应流程 | 恢复目标
--- | --- | --- | ---
S1 严重故障 | 全服不可用 / 数据丢失 / 支付异常 | 电话通知全员 -> 紧急 War Room -> 修复 -> 事后复盘 | 1 小时内恢复
S2 主要故障 | 核心功能不可用 / 性能严重退化 | 飞书告警 -> 值班工程师处理 -> 升级判断 | 4 小时内恢复
S3 一般故障 | 非核心功能异常 / 少数用户受影响 | 工单系统 -> 工作时间内处理 | 24 小时内恢复
回滚预案 | 新版本引入严重 Bug | kubectl rollout undo -> 数据库回滚 -> 客户端提示旧版 | 10 分钟内回滚完成

### 24.4 首年运营节奏

月份 | 运营重点 | 内容更新 | 活动
--- | --- | --- | ---
M9 发布月 | 稳定性保障 + 新手引导优化 | 240 关 + 80 元件首发 | 首发七日登录奖励
M10 | 数据驱动调优 + 社区建设 | 限时活动关卡 20 关 | 万圣节主题电路设计赛
M11 | 赛季 1 启动 + 蓝图生态 | 新增元件 5 种 + 赛季排行 | 赛季 1 排位赛 + 双倍红石币周末
M12 | 留存提升 + 平衡性补丁 | 大师关卡 +10 关 + 蓝图审核优化 | 圣诞/元旦限定皮肤 + 年度总结

25 / APPENDIX

## 附录

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

### A. 元件成本速查表

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

序号 | 编号 | 元件名 | 类别 | 成本(红石币)
--- | --- | --- | --- | ---
1 | W-01 | 红石粉 | WIRE | 5
2 | O-13 | LED | OUTPUT | 15
3 | W-04 | 绝缘导线 | WIRE | 15
4 | W-06 | 铜导线 | WIRE | 12
5 | A-01 | 电阻 | ANALOG | 20
6 | W-07 | 跳线 | WIRE | 18
7 | W-05 | 信号桥 | WIRE | 25
8 | S-11 | 拨动开关 | SWITCH | 25
9 | P-03 | 拉杆 | POWER | 30
10 | S-03 | 拉杆 | SWITCH | 30
11 | P-05 | 压力板 | POWER | 35
12 | S-04 | 压力板木质 | SWITCH | 35
13 | O-14 | 蜂鸣器 | OUTPUT | 35
14 | P-04 | 按钮 | POWER | 40
15 | S-01 | 按钮木质 | SWITCH | 40
16 | S-02 | 按钮石质 | SWITCH | 40
17 | P-09 | 直流电源 | POWER | 40
18 | A-04 | 二极管 | ANALOG | 45
19 | S-07 | 绊线钩 | SWITCH | 45
20 | P-01 | 红石火把 | POWER | 50
21 | S-05 | 压力板铁质 | SWITCH | 50
22 | O-10 | 门(木) | OUTPUT | 50
23 | A-05 | 稳压管 | ANALOG | 55
24 | O-12 | 灯笼 | OUTPUT | 55
25 | A-02 | 电容 | ANALOG | 60
26 | O-01 | 红石灯 | OUTPUT | 60
27 | O-11 | 活板门 | OUTPUT | 60
28 | S-10 | 标靶 | SWITCH | 60
29 | A-03 | 电感 | ANALOG | 70
30 | O-07 | 音符盒 | OUTPUT | 70
31 | P-08 | 探测铁轨 | POWER | 70
32 | P-10 | 电池组 | POWER | 85
33 | W-02 | 红石中继器 | WIRE | 80
34 | S-06 | 压力板金质 | SWITCH | 80
35 | O-09 | 门(铁) | OUTPUT | 80
36 | O-15 | 数码管 | OUTPUT | 90
37 | P-06 | 阳光探测器 | POWER | 90
38 | P-07 | 阳光探测器(夜) | POWER | 90
39 | S-08 | 阳光探测器 | SWITCH | 90
40 | P-02 | 红石块 | POWER | 100
41 | O-06 | 漏斗 | OUTPUT | 100
42 | L-08 | 中继器逻辑 | LOGIC | 100
43 | S-12 | 继电器 | SWITCH | 120
44 | W-03 | 红石比较器 | WIRE | 120
45 | O-05 | 投掷器 | OUTPUT | 120
46 | X-05 | 信号分配器 | SPECIAL | 120
47 | S-09 | 观察者 | SWITCH | 150
48 | O-02 | 活塞 | OUTPUT | 150
49 | L-01 | NOT | LOGIC | 150
50 | X-04 | 信号延迟器 | SPECIAL | 150
51 | A-09 | 光耦 | ANALOG | 160
52 | O-04 | 发射器 | OUTPUT | 180
53 | A-06 | NPN 三极管 | ANALOG | 180
54 | A-07 | PNP 三极管 | ANALOG | 180
55 | PD-04 | MOS 管 | POWER_DEVICE | 200
56 | O-03 | 粘性活塞 | OUTPUT | 200
57 | L-02 | AND | LOGIC | 200
58 | L-03 | OR | LOGIC | 200
59 | PD-01 | 单向可控硅 SCR | POWER_DEVICE | 220
60 | L-04 | NAND | LOGIC | 220
61 | L-05 | NOR | LOGIC | 220
62 | PD-06 | 继电器模组 | POWER_DEVICE | 250
63 | L-06 | XOR | LOGIC | 250
64 | L-07 | XNOR | LOGIC | 250
65 | X-06 | 物品过滤器 | SPECIAL | 250
66 | PD-02 | 双向可控硅 TRIAC | POWER_DEVICE | 280
67 | A-08 | 运算放大器 | ANALOG | 280
68 | PD-05 | 达林顿管 | POWER_DEVICE | 300
69 | O-08 | TNT | OUTPUT | 300
70 | X-03 | 信号示波器 | SPECIAL | 300
71 | X-10 | 555 定时器 | SPECIAL | 350
72 | L-09 | RS锁存器 | LOGIC | 350
73 | L-10 | D触发器 | LOGIC | 400
74 | X-07 | 物品分类器 | SPECIAL | 400
75 | PD-03 | IGBT | POWER_DEVICE | 420
76 | X-08 | ADC 模数转换器 | SPECIAL | 450
77 | X-09 | DAC 数模转换器 | SPECIAL | 450
78 | L-11 | 计数器 | LOGIC | 500
79 | X-02 | 结构方块 | SPECIAL | 800
80 | X-01 | 命令方块 | SPECIAL | 1000

### B. 常见电路设计模式

模式 | 核心元件 | 用途
--- | --- | ---
T 触发器 | RS 锁存器 + 边沿检测 | 按钮单次脉冲切换开关状态
时钟发生器 | 中继器环形振荡 | 产生周期性脉冲信号
脉冲缩短器 | 比较器 + 中继器 | 将长脉冲截断为单 tick 短脉冲
脉冲延长器 | 多级中继器链 | 延长脉冲持续时间
二进制计数器 | D 触发器级联 | 多 Bit 二进制计数与溢出进位
优先编码器 | OR 门阵列 + NOT | 多输入中输出最高优先级
边沿检测器 | 比较器 + 中继器 | 检测信号上升沿或下降沿
数据选择器 MUX | AND + OR + NOT | 按控制端选择多路输入之一输出