From 5eb303c3890aa66b54edb39e1464725994295f29 Mon Sep 17 00:00:00 2001
From: Super_Z <1401203083@qq.com>
Date: Tue, 23 Jun 2026 12:46:35 +0000
Subject: [PATCH] =?UTF-8?q?fix(decode):=20=E4=BF=AE=E5=A4=8D=E8=A7=A3?=
 =?UTF-8?q?=E7=A0=81=E8=B0=9C=E9=A2=98=E5=A4=A7=E9=87=8F=E6=97=A0=E8=A7=A3?=
 =?UTF-8?q?=E9=97=AE=E9=A2=98=20(v0.1.1)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

核心问题: generatePuzzle 随机填色未保证有解, 导致大量死局

修复:
- 路径构造法生成器: 主动构造一条保证可解的路径, 100%可解率
- isSolvable DFS精确判定: 检测此路不通, 提示撤销
- undoStep 撤销功能: 走错单步回退, 无需整局重排
- 卡死提示横幅: 局面无解时醒目提示+快捷撤销
- canStartFrom 可行起点高亮: 选起点阶段标记可行/死起点
- 旧存档兼容: init时清理不可解的遗留谜题

验证: 3000/3000可解, agent-browser T1/T2端到端通过
---
 docs/04-解码系统修复-v0.1.1.md | 57 ++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 docs/04-解码系统修复-v0.1.1.md

diff --git a/docs/04-解码系统修复-v0.1.1.md b/docs/04-解码系统修复-v0.1.1.md
new file mode 100644
index 000000000..938e59beb
--- /dev/null
+++ b/docs/04-解码系统修复-v0.1.1.md
@@ -0,0 +1,57 @@
+# 解码系统修复说明 (v0.1.1)
+
+## 问题
+用户反馈「解码大量的无法通过」。经分析，根因是 `generatePuzzle` **没有保证生成的局面有解**：随机填色后可能根本不存在一条满足「按目标顺序、四邻接、不重复」的路径，导致大量死局。
+
+## 修复方案
+
+### 1. 路径构造法生成器（核心修复）
+重写 `generatePuzzle`，采用**路径构造法**：
+1. 先随机生成目标序列 target。
+2. 在网格上**主动构造一条合法路径**：随机起点，每步走向一个未使用的四邻接节点，长度 = target.length。
+3. 把路径上第 i 个节点颜色**强制设为 target[i]**。
+4. 其余非路径节点随机填色（60% 偏向目标色，提升多解性）。
+
+这样**至少存在一条解**（即构造的路径），玩家不会遇到「怎么都过不了」的死局。
+
+### 2. 精确可解性检测 `isSolvable`
+新增 DFS 函数，从当前路径末端出发，精确判断是否存在一条按 target 剩余顺序、四邻接、不重复的完成路径。用于：
+- 玩家点击后检测「此路不通」，提示撤销。
+- `isStuck` 复用此判定。
+
+### 3. 撤销功能 `undoStep`
+新增 store action，支持单步回退（恢复节点 used 状态）。走错时无需整个重排。
+
+### 4. 卡死提示横幅
+当局面不可解时，顶部显示「谐振受阻，此路已无解」横幅 + 快捷撤销按钮。
+
+### 5. 可行起点高亮（体验增强）
+选起点阶段，用 `canStartFrom` 检测每个目标色节点「选了之后是否仍可解」：
+- **可行起点**：强光圈 + 2px 边框 + 快脉冲，引导玩家。
+- **死起点**：淡化(opacity 0.5)，避免玩家踩坑。
+
+### 6. 旧存档兼容
+`init` 时检测存档中的活跃谜题，若不可解（旧算法生成）则自动放回晶体队列，避免老玩家卡死。
+
+## 验证结果
+
+### 算法验证（1000 次/档位）
+- Tier 1: 1000/1000 可解 (100.0%)
+- Tier 2: 1000/1000 可解 (100.0%)
+- Tier 3: 1000/1000 可解 (100.0%)
+- 总计: 3000/3000 (100.00%)
+
+### 模拟游玩（带可解性筛选的贪心玩家）
+- 500 局: 100% 解出，平均撤销 0 次
+
+### agent-browser 端到端验证
+- T1 (3×3): 通过 ✓
+- T2 (4×4): 通过 ✓
+- 死路检测: 触发「谐振受阻」横幅 ✓
+- 撤销: 单步回退正常 ✓
+- 可行起点高亮: 准确标记（4 个玫色节点中仅 1 个为可行起点，与手算一致）✓
+
+## 影响文件
+- `src/lib/game/decode.ts` — 重写生成器 + 新增 isSolvable/canStartFrom
+- `src/store/gameStore.ts` — clickNode 可解性检测 + undoStep + init 兼容
+- `src/components/game/DecodeArray.tsx` — 撤销按钮 + 卡死横幅 + 可行起点高亮