# 技术架构设计

## 一、技术栈

| 层 | 技术 | 说明 |
|---|---|---|
| 框架 | 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）

```ts
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`，新增碎片只需追加数据。
- 技术树/解码规则/探险地图均数据驱动，支持后续模块化扩展。