echo-nexus/docs/03-技术架构.md

技术架构设计

一、技术栈

层	技术	说明
框架	Next.js 16 (App Router)	既有栈，SSR + API 一体
语言	TypeScript 5	全量类型
样式	Tailwind CSS 4 + shadcn/ui	既有 UI 组件库
渲染	HTML5 Canvas 2D	星空/粒子/晶体/解码阵列
客户端状态	Zustand + persist	游戏状态 + localStorage 持久化
服务端状态	TanStack Query（按需）	存档同步、统计
后端	Next.js API Routes	存档同步、全局统计
数据库	Prisma + SQLite	存档、统计（v0.4+）
实时	socket.io mini-service	全局「星潮」事件（v0.3+）

二、目录结构

src/
  app/
    page.tsx              # 游戏主入口（唯一用户可见路由）
    layout.tsx
    api/
      save/route.ts       # 存档同步（v0.4+）
      stats/route.ts      # 全局统计
  components/
    game/                 # 游戏专属组件
      StarfieldCanvas.tsx # 星空背景
      CrystalCluster.tsx  # 晶体集群
      DecodeArray.tsx     # 解码共振阵列 ⭐
      ResourceBar.tsx     # 顶栏资源
      MiningPanel.tsx
      TechTree.tsx
      Codex.tsx           # 记忆图谱
      PrestigeDialog.tsx
    ui/                   # shadcn/ui 既有
  lib/
    game/                 # 游戏逻辑（纯函数，可测）
      config.ts           # 数值配置
      types.ts            # 类型
      engine.ts           # 核心 tick 引擎
      decode.ts           # 解码谜题逻辑
      tech.ts             # 技术树
      codex.ts            # 叙事数据
      prestige.ts         # 飞升
    db.ts                 # Prisma
  store/
    gameStore.ts          # Zustand 游戏状态
  hooks/
    useGameLoop.ts        # 主循环
    use-toast.ts          # 既有

三、状态模型（Zustand）

interface GameState {
  // 资源
  crystals: number;           // 记忆晶体（主货币）
  insights: number;           // 技术洞见
  fragments: Record<FragmentId, boolean>; // 已获碎片
  contact: number;            // 接触进度 0-100
  
  // 产能
  crystalsPerSec: number;     // 由技术树计算
  pulsePower: number;         // 主动脉冲产出
  
  // 技术
  tech: Record<TechId, number>; // 各技术等级
  
  // 飞升
  ascensions: number;
  blueprints: string[];       // 保留的蓝图
  
  // 解码
  currentCrystal: Crystal | null;
  
  // 元
  lastTick: number;
  prestige: PrestigeBonus;
}

四、核心循环引擎

• 客户端 setInterval 每 100ms tick 一次。
• 每次 tick：crystals += crystalsPerSec * dt。
• 离线收益：加载时计算 now - lastTick，按 50% 效率补发（上限 8h）。
• 状态自动持久化到 localStorage（Zustand persist，节流 1s）。

五、解码谜题实现

• 阵列 = 节点图（邻接表），每节点有 resonance 值。
• 共振规则：玩家依序点击节点，相邻点击须满足 resonance 差值 ≤ 阈值，且最终形成闭合回路。
• 步数限制：规模 3×3=9 节点 / 4×4=16 / 5×5=25，步数上限分别为 6/10/15。
• 成功 → 结算奖励 + 动画；失败 → 晶体不损耗，可重试。

六、Canvas 渲染策略

• 单一全屏 Canvas 作为背景层（星空 + 星尘 + 远景星云）。
• 晶体集群与解码阵列用独立 Canvas 或 SVG叠加，便于交互。
• requestAnimationFrame 驱动，设备像素比适配，低性能设备降帧。

七、可扩展性

• 数值配置集中在 config.ts，便于平衡调整与工单需求响应。
• 叙事数据集中在 codex.ts，新增碎片只需追加数据。
• 技术树/解码规则/探险地图均数据驱动，支持后续模块化扩展。