v0.9 工单修复部署

2026-06-24 00:41:29 +00:00
commit 73720d8306
279 changed files with 39708 additions and 0 deletions
@@ -0,0 +1,109 @@
+# 技术架构设计
+
+## 一、技术栈
+
+| 层 | 技术 | 说明 |
+|---|---|---|
+| 框架 | 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`，新增碎片只需追加数据。
+- 技术树/解码规则/探险地图均数据驱动，支持后续模块化扩展。