# 《我要当岛主》0.1 第六步 · 本地存档 — 实现与验证报告

- 日期：2026-10-09
- 项目目录：`/vol1/ai/projects/wyszz-new/wechat-game-0.1-ds/`
- 本步范围：**只做第六步「本地存档」，完成后立即停止，未进入第七步离线收益**
- 运行时：微信小游戏运行时（`wx.createCanvas()`，无 DOM/CSS/WebView）+ 浏览器版本，两者共用同一套核心
- 引擎：three.js r186（`three@0.186.1`），未降级
- 存档：**只用本地存储**（浏览器 `localStorage` / 微信 `wx.setStorageSync`），**无后端、无云同步、无账号系统、无跨设备同步**

---

## 1. 结论速览

| 验证项 | 结果 |
| --- | --- |
| TypeScript 类型检查 `tsc --noEmit` | **通过（0 错误）** |
| 核心自动测试 `npm test` | **75/75 通过**（第三步 9 + 第四步 12 + 第五步 22 + 第六步 32） |
| 浏览器生产构建 | **通过**（`dist/browser/app.js` 574051 B） |
| 微信小游戏生产构建 | **通过**（`dist/game/bundle.js` 580573 B，`adapter.js` 9182 B） |
| 浏览器端到端测试（无头 Chromium，含读档/写档） | **107/107 通过** |
| 微信开发者工具游客模拟器 | **通过**（真实点击 25 次；跨进程重启恢复存档；离线 7.1 分钟零收益） |
| 沙箱日志逐条回放（第六步，29 项） | **29/29 通过** |
| 第五步回放器回归（第五步日志，21 项） | **21/21 通过** |
| 第三步/第四步/第五步核心规则是否被重写 | **没有**（`economy.ts` / `visit.ts` / `upgrade.ts` / `input.ts` 本步**逐字节未改**） |
| 游戏代码运行时错误 | **0** |
| 公网预览 `https://mayor3d.hynixing.cn/` | **HTTP 200**（未改动任何公网基础设施） |
| 真机验证 | **未验证 —— AppID 审核中** |
| 第七步离线收益 | **未进入，当前未实现** |

> **一句话结论：本地存档已实现，离线收益属于第七步，当前未实现。**

---

## 2. 修改文件清单

### 2.1 新增

| 文件 | 作用 |
| --- | --- |
| `src/core/save.ts` | 第六步本地存档的**唯一实现**：命名空间、schemaVersion、字段表、字段校验规则、序列化、严格解析、读档结论、写档结论。**纯模块，不引用任何存储 API** |
| `src/platform/storage-browser.ts` | 浏览器存储适配器（只包 `window.localStorage`，388 B 构建产物，**不含任何 schema / 序列化 / 常量**） |
| `src/platform/storage-wx.ts` | 微信小游戏存储适配器（只包 `wx.getStorageSync` / `setStorageSync` / `removeStorageSync`，428 B，**不含任何 schema**） |
| `tests/save.test.mjs` | 第六步核心自动测试 **32 项**（含任务书要求的 15 项必测） |
| `tools/analyze-vm-log-step6.mjs` | 沙箱日志逐条回放器（29 项：存档 + 离线收益 + 第三/四/五步回归） |
| `docs/报告-0.1第六步-本地存档.md` | 本报告 |

### 2.2 修改

| 文件 | 改动 |
| --- | --- |
| `src/browser/main.ts` | 接入 `loadSave` / `persistSave`；启动读档、寻访后写档、升级成功/失败后写档、15 秒节流写档、`visibilitychange`(hidden) / `pagehide` / `beforeunload` 先结算再写档；HUD 与页面新增存档状态行；`window.__wyszz` 调试钩子扩展（`readSaveRaw` / `writeSaveRaw` / `clearSaveRaw` / `forceSave` / 存档快照字段） |
| `src/game/main.ts` | 同上（`wx.getStorageSync`/`setStorageSync` 适配器、`installLifecycleHooks({ onHide })` 先结算再写档）；HUD 第 10 行改为存档状态行，原第 9/10 行合并，**HUD 仍为 10 行 / 512×400** |
| `src/platform/runtime.ts` | `installLifecycleHooks(hooks: { onHide?: () => void })`：`onHide` 在 `stopLoop('hidden')` **之前**于 try/catch 内执行 |
| `build.mjs` | `buildCore()` 入口增加 `src/core/save.ts`；新增 `buildPlatform()` 目标；`TARGETS` 增加 `platform`；小游戏项目名 `wyszz-0.1-step6` |
| `public/index.html` | 新增存档状态区（`#saveStatus` / `#saveDetail`） |
| `package.json` | 描述改为第六步；新增 `build:platform` / `verify:browser` / `analyze:vm:step6`；`test` 脚本纳入 `tests/save.test.mjs` |
| `tests/economy.test.mjs` | 第 7 项断言细化：仍禁止两个入口**自行实现结算**（不得写 `carryNumerator` / `lastSettleTsMs`、不得运算 `carryNumerator`），但允许入口把 `state.carryNumerator` **只读**透出到调试快照（第六步诊断需要） |
| `tools/verify-browser.mjs` | 新增 `reload()` / `readSaveRaw()` / `writeSaveRaw()` / `suppressWrites()` / `freshGame()` 辅助；B4 由「刷新归零」改为「刷新恢复」；新增 C0 确定性起点；**新增 D1–D11 共 40 项存档检查** |
| `win/deploy_into_open.ps1` / `win/restart_devtools_gpu.ps1` | 部署标识改 step6；重启脚本增加沙箱日志清理（**只删 `stage-err.log` / `run.log`，不碰模拟器 Storage**，所以重启等价于真实的「关掉游戏再打开」） |
| `README.md` | 进度改为第六步；新增存档 schema 字段表、浏览器/微信存储 API 差异表、第六步关键规则 21–28 |

### 2.3 明确未改动（本步一个字节都没碰）

- `src/core/economy.ts`（第三步时间收益）
- `src/core/visit.ts`（第四步寻访奖励）
- `src/core/upgrade.ts`（第五步升级费用与等级）
- `src/core/input.ts`（手势门）
- `src/scene/world.ts` / `camera.ts` / `pick.ts`、`src/shared/hud.ts`
- `tests/economy.test.mjs`（除第 7 项断言的措辞细化，见 §10.3）、`tests/visit.test.mjs`、`tests/upgrade.test.mjs`

> **`economy.ts` / `visit.ts` / `upgrade.ts` / `input.ts` 的核心规则没有被重写**，第六步只是**读写**它们产出的状态。

---

## 3. 存档 schemaVersion 与完整字段表

- **命名空间（固定）**：`wyszz-0.1-ds-save`
- **`schemaVersion` = 1**
- **形态**：**单个完整 JSON 信封**，只占一个 key；键顺序固定为 `schemaVersion` 后接 11 个字段
  （顺序固定 ⇒ 同样的状态写出**逐字节相同**的 JSON，见 §7.4）

| # | 字段 | 类型 | 取值约束 | 对应 0.1 已实现状态 |
| --- | --- | --- | --- | --- |
| 0 | `schemaVersion` | int | 必须 `= 1` | 存档格式版本 |
| 1 | `level` | int | `1 ≤ level ≤ 10000` | 市政厅等级（第三步/第五步） |
| 2 | `coinsMilli` | int | `0 ≤ x ≤ Number.MAX_SAFE_INTEGER` | 整数毫币余额（1 金币 = 1000 毫币） |
| 3 | `carryNumerator` | int | `0 ≤ x ≤ 59999` | 结算分子余数（不丢小数收益的关键） |
| 4 | `lastSettleTsMs` | int | `0 ≤ x ≤ Number.MAX_SAFE_INTEGER` | 最近结算时刻（**读档时被丢弃**） |
| 5 | `settleCount` | int | `≥ 0` | 已结算次数 |
| 6 | `lastGainMilli` | int | `≥ 0` | 上一次结算收益（毫币） |
| 7 | `totalGainMilli` | int | `≥ 0` | 时间收益累计（毫币） |
| 8 | `lifetimeReputation` | int | `≥ 0` | 累计声望（只增） |
| 9 | `spendableReputation` | int | `≥ 0` | 可用声望 |
| 10 | `visitCount` | int | `≥ 0` | 寻访次数 |
| 11 | `visitCoinsMilli` | int | `≥ 0` | 寻访累计金币（毫币） |

**任务书点名的 8 个必需字段全部在表内**：
`level` / `coinsMilli` / `carryNumerator` / `last_settle_ts_ms`（存档内为 `lastSettleTsMs`）/
`lifetimeReputation` / `spendableReputation` / `visitCount` / `visitCoinsMilli`。

**第 5~7 个字段（`settleCount` / `lastGainMilli` / `totalGainMilli`）属于 0.1 已实现状态**，
是第三步结算核心的一部分，所以**显式列入存档字段表并落盘，不依赖运行时默认值**。

**不保存**：临时 UI 状态、飘字（toast）、相机拖拽状态（yaw/pitch）、调试状态。
信封里一旦出现**任何多余字段**（如 `yaw` / `toast` / `camera`）⇒ **整档判损坏**（见 §7.2）。

**核心指纹**（两端必须一致，启动日志打印并与自算值比对）：

```
wyszz-core-save-v1:v=1:fields=11:carry=0..59999:ns=wyszz-0.1-ds-save
```

---

## 4. 浏览器与微信存储 API 的差异（只允许存储 API 不同）

| | 浏览器 | 微信小游戏 |
| --- | --- | --- |
| 适配器文件 | `src/platform/storage-browser.ts`（388 B） | `src/platform/storage-wx.ts`（428 B） |
| 读 | `window.localStorage.getItem(key)` | `wx.getStorageSync(key)` |
| 写 | `window.localStorage.setItem(key, text)` | `wx.setStorageSync(key, text)` |
| 删 | `window.localStorage.removeItem(key)` | `wx.removeStorageSync(key)` |
| 空值语义 | 缺失返回 `null` | 缺失返回 `''`，适配器统一映射成 `null` |
| 失败语义 | `setItem` 抛异常（如配额） | `setStorageSync` 抛异常 |
| schema / 序列化 / 校验 / 常量 | **无 —— 全部来自 `src/core/save.ts`** | **无 —— 同上** |

两个适配器都只实现同一个接口：

```ts
interface SaveStorage { read(key: string): string | null; write(key: string, value: string): void; remove(key: string): void }
```

**因此同一份状态在两个平台上写出的存档逐字节相同。**
核心测试第 12 项同时注入 `globalThis.window.localStorage` 与 `globalThis.wx`，
断言两个适配器对同一状态产出的 JSON **完全相同**（byte-identical）。

---

## 5. 新用户初始化证据

- **核心测试**：第 1 项「新用户初始化」——空存储 ⇒ `kind='new-game'`、`level=1`、`coinsMilli=0`、
  两个声望与寻访计数全 0、`carryNumerator=0`、`sessionBaseMs=nowMs`。
- **浏览器端到端**：

```
PASS | D1 没有存档时显示「新游戏」 | kind=new-game status=新游戏
PASS | D1 新游戏回到默认初始状态（Lv1 / 0 金币 / 0 声望 / 0 寻访） | Lv1 coins=0 life=0
PASS | D1 新游戏的结算基线 = 打开时刻 | baseline=1791554046011 now=1791554046747
PASS | D1 界面显示存档状态与命名空间 | saveStatus=新游戏 detail=存档 wyszz-0.1-ds-save v1 · 写入 0 次 · 失败 0 次
PASS | C0 清档后重新打开确实是新游戏（Lv1 / 0 金币） | kind=new-game Lv1 coinsMilli=500
```

- **微信模拟器**：首次部署后的启动日志为 `save load new-game 新游戏`（见 §9 的首次运行记录）。

---

## 6. 成功读档证据

### 6.1 浏览器（无头 Chromium）

```
PASS | D2 寻访奖励后自动写档（寻访后 saveWrites 增加） | writes=4 bytes=245
PASS | D2 重新打开显示「已恢复本地进度」 | kind=restored status=已恢复本地进度
PASS | D2 读档后金币不少于存档（寻访奖励没丢），且没有虚增 | save=12172 loaded=12243 差=71
PASS | D2 读档后两种声望与存档一致（读档不增加也不减少声望） | life 4->4 spend 4->4
PASS | D2 读档建立了新的结算基线（不是存档里的旧时间戳） | saved=1791554047047 new=1791554047544
PASS | D3 升级成功后再写档（等级已提升） | Lv1 -> Lv2 成功=1
PASS | D3 读档后等级与存档一致 | save Lv2 loaded Lv2
PASS | D3 读档后速率与等级匹配（Lv2 = 12 金币/分钟） | Lv2 rate=12
PASS | D3 读档后扣费后的余额与存档一致 | save=22582 loaded=22631
PASS | D3 读档后升级次数与费用同步显示（C(2)=25 金币） | C=25 text=Lv2→Lv3：25 金币（25000 毫币）
PASS | D4 carryNumerator 保存后跨重新打开不丢失 | carry=43210 pending=345
PASS | D4 毫币余额精确恢复（12345 毫币 = 12 金币 + 345/1000） | coinsMilli=12345 coins=12
```

> D2/D3 的余额差（71 / 49 毫币）是**重新打开前那几秒的在线收益**（页面隐藏时按规则先结算再写档），
> 不是离线收益，也不是重复发奖：声望与寻访计数**逐位相等**，且差值 < 1 金币。

### 6.2 微信开发者工具游客模拟器（真实点击 + 跨进程重启）

**运行 1**（首次部署，模拟器 Storage 为空 ⇒ 新游戏），随后真实点击 12 次居民、2 次升级按钮：

```
tap#1  at=(197,387) travel=0 held=41ms -> raycast
pick#1 tap=(197,387) ndc=(0.008,0.083) HIT 居民 dist=48.48
visit#1 tag=居民 +3 coins(=3000 milli) +1 lifetime +1 spendable | lifetime=1 spendable=1 | coins=85 coins+306/1000 | last_settle_ts_ms=1791553686704->1791553686704 (must be equal)
save write 存档已写入 wyszz-0.1-ds-save bytes=247 | Lv1 金币=85306毫币 carry=50000 lifetime=1 spendable=1 寻访=1
...
visit#12 ... lifetime=12 spendable=12 | coins=124 coins+548/1000
tap#13 at=(195,667) -> 升级按钮
升级#1 source=button tag=市政厅 Lv1->Lv2 花费=20 金币(=20000 毫币) | 余额=105 金币+130/1000 | rate=10->12/min | lifetime=12->12 spendable=12->12 (must be equal)
save write 存档已写入 wyszz-0.1-ds-save bytes=253 | Lv2 金币=105130毫币 carry=10000 lifetime=12 spendable=12 寻访=12
tap#14 at=(195,667) -> 升级按钮
升级#2 source=button tag=市政厅 Lv2->Lv3 花费=25 金币(=25000 毫币) | 余额=80 金币+592/1000 | rate=12->14/min | lifetime=12->12 spendable=12->12 (must be equal)
save write 存档已写入 wyszz-0.1-ds-save bytes=253 | Lv3 金币=80592毫币 carry=10000 lifetime=12 spendable=12 寻访=12
```

**运行 2**（DevTools 进程被强制结束 → 重新启动，即真实的「关掉游戏再打开」）：

```
# stage-c island  boot 2026-10-09 21:59:14.742
save core wyszz-core-save-v1 fingerprint=wyszz-core-save-v1:v=1:fields=11:carry=0..59999:ns=wyszz-0.1-ds-save (expect wyszz-core-save-v1:v=1:fields=11:carry=0..59999:ns=wyszz-0.1-ds-save)
save namespace=wyszz-0.1-ds-save schemaVersion=1 fields=11 storageApi=wx.getStorageSync/setStorageSync
save load restored 已恢复本地进度 | Lv3 金币=127+44/1000 carry=10000 lifetime=12 spendable=12 寻访=12 寻访毫币=36000 | 新基线 last_settle_ts_ms=1791554355183（存档里的 1791553929034 已被丢弃，不追溯离线收益）
econ boot last_settle_ts_ms=1791554355183 coins=127 rate=14/min autoSettleMs=1000
```

模拟器界面实拍（`evidence/screenshot-step6-restored.png`）同时显示
`0.1 第六步 · 本地存档 · three r186`、`存档 已恢复本地进度 · 已恢复 · 写入 52 次 失败 0 次`、
`金币 106 · 14 金币/分钟（Lv3）`、`声望 lifetime 12 · spendable 12`、`已升级 2 次（失败 0）`。

**运行 2 继续真实点击 11 次**（结算按钮 / 市政厅 / 居民 ×2 / 道路 / 浮空岛 / 树木 / 升级按钮 ×4）：

```
tap#1  at=(195,769) -> 结算按钮
tap#2  at=(184,290) travel=0 held=53ms -> raycast
pick#1 tap=(184,290) ndc=(-0.059,0.312) HIT 市政厅 dist=50.56
升级#1 source=cityhall tag=市政厅 Lv3->Lv4 花费=30 金币(=30000 毫币) | 余额=144 金币+651/1000 | rate=14->16/min | lifetime=12->12 spendable=12->12 (must be equal)
save write 存档已写入 wyszz-0.1-ds-save bytes=254 | Lv4 金币=144651毫币 carry=24000 lifetime=12 spendable=12 寻访=12 | last_settle_ts_ms=1791554559214
tap#3  at=(197,387) -> HIT 居民  => visit#1 +3 coins +1 lifetime +1 spendable  => save write Lv4 金币=148283毫币 lifetime=13 spendable=13 寻访=13
tap#4  at=(197,387) -> HIT 居民  => visit#2 +3 coins +1 lifetime +1 spendable  => save write Lv4 金币=151910毫币 lifetime=14 spendable=14 寻访=14
tap#5  at=(313,462) -> HIT 道路     （负样本，不发奖）
tap#6  at=(239,543) -> HIT 浮空岛   （负样本，不发奖）
tap#7  at=(325,420) -> HIT 树木     （负样本，不发奖）
tap#8  at=(195,667) -> 升级按钮 => 升级#2 Lv4->Lv5 花费=37 => save write Lv5 金币=117423毫币
tap#9  at=(195,667) -> 升级按钮 => 升级#3 Lv5->Lv6 花费=45 => save write Lv6 金币=73124毫币
tap#10 at=(195,667) -> 升级按钮 => 升级#4 Lv6->Lv7 花费=55 => save write Lv7 金币=18900毫币
tap#11 at=(195,667) -> 升级按钮 => 升级失败（insufficient-coins）source=button Lv7 保持 | 需要=66 金币(=66000 毫币) 还差=47 金币 | 余额=19 金币+757/1000
                                     => save write Lv7 金币=19757毫币 lifetime=14 spendable=14 寻访=14
```

**「状态改变后保存」在模拟器日志里逐条可见**：每一次 `visit#` / `升级#` / `升级失败` 的**下一行**
就是 `save write`，且写入的 `Lv` / `金币` / `carry` / `lifetime` / `spendable` / `寻访`
与事件后的内存状态**完全一致**（回放器 S8 / S9 逐条校验，见 §10.2）。

---

## 7. 损坏存档、schemaVersion 不支持、写档失败证据

### 7.1 损坏存档 ⇒ 回退新游戏、不崩溃、不伪造奖励

浏览器端到端用 6 个损坏样本逐个「写入 → 屏蔽回写 → 重新打开」：

```
PASS | D5 损坏 JSON 安全回退默认状态、显示「本地存档无法读取，已使用新游戏」、不崩溃 | {"schemaVersion":1,"level":1, -> bad-json
PASS | D5 损坏存档不伪造任何奖励（等级/金币/声望/寻访全部归零） | 最后一次={"schemaVersion":1,"level":1, -> bad-json
PASS | D5 损坏存档提示文案在界面上可见 | saveStatus=本地存档无法读取，已使用新游戏
```

覆盖的损坏类型（核心测试第 8–11 项 + D5/D6 共 30+ 个样本）：
JSON 语法损坏、截断、`null`、数组、字符串、字段缺失、多余字段（`yaw`/`toast`/`camera`）、
类型错误（字符串/布尔/对象/数组/null）、`NaN`/`Infinity`（含 `1e999` 这种**合法 JSON 但解析成 Infinity**）、
非整数（`1.5`）、负数、越界（`level=0`、`level=10001`、`carryNumerator=60000`、
超过 `MAX_SAFE_INTEGER`）。

每一次都断言：`kind='corrupt'`、界面文案 = 「本地存档无法读取，已使用新游戏」、
内存状态**全部归零**（`Lv1` / `0 金币` / `0 声望` / `0 寻访`）、**没有伪造任何奖励**、进程不崩溃。

### 7.2 schemaVersion 不支持 ⇒ 回退

```
PASS | D6 schemaVersion 不支持时安全回退默认状态（0/2/3/99/1.5/字符串/null） | ver=null -> bad-type
```

核心测试第 9 项对 `0 / 2 / 3 / 99 / 1.5 / '1' / null / 缺失` 全部断言 `reason='unsupported-version'`
或类型错误、`kind='corrupt'`、状态归零。

### 7.3 写档失败 ⇒ 不崩溃、保留内存状态、记录明确错误、可恢复

浏览器端到端把 `window.localStorage.setItem` 换成抛 `quota exceeded` 的实现：

```
PASS | D8 写档失败时显示「本地保存失败」 | saveStatus=本地保存失败 errors=0->1
PASS | D8 写档失败不崩溃：内存状态照常更新（寻访奖励仍然发放） | life 3->4 coinsMilli 500->3666
PASS | D8 写档失败后结算循环仍在跑（settleCount 继续增长，游戏没卡死）
PASS | D8 写档失败时错误详情被记录（不是静默吞掉） | lastSaveError="Error: quota exceeded (simulated)"
PASS | D8 存储恢复后可以正常写档（游戏没有卡死） | ok=true bytes=245
PASS | D8 恢复写档后状态回到正常提示 | saveStatus=已恢复本地进度
```

> 注意：`saveStatus` 在**下一次写档成功**后会自动回到读档结论（写档成功即健康状态），
> 这是本步实测发现并修掉的一个显示层缺陷（见 §11.2 T6）。

### 7.4 单个完整 JSON 信封

```
PASS | D10 存档只占一个 key（单个完整信封，不拆多个互不一致的 key） | keys=["wyszz-0.1-ds-save"]
PASS | D10 信封含 schemaVersion + 11 个状态字段，8 个必需字段齐全 | n=12 v=1 has=true
PASS | D10 信封里没有任何临时 UI / 飘字 / 相机 / 调试字段 | ui=[]
PASS | D10 信封能被 JSON.parse 且字段值都是非负安全整数 | 所有字段都是非负安全整数，level>=1，carryNumerator<=59999
PASS | D11 重复写档写出的内容逐字节一致（纯写入，不发奖） | coinsMilli 3833/3833
PASS | D11 连续两次重新打开得到完全相同的状态（读档不重复发奖） | coinsMilli 3833 vs 3833 life 4 vs 4
PASS | D11 读档后状态与写档内容毫币级一致（没有凭空增加） | saved=3833 loaded=3833
```

---

## 8. 不发放离线收益的证据（本步最关键的一条）

### 8.1 微信模拟器：真实关闭 7.1 分钟后重开，零离线收益

| 项 | 值 |
| --- | --- |
| 存档里的 `last_settle_ts_ms` | `1791553929034`（本地 21:52:09） |
| 重新打开时的新基线 | `1791554355183`（本地 21:59:15） |
| **离线间隔** | **426.1 秒 = 7.10 分钟** |
| 读档恢复的余额 | **127044 毫币**（= 127 金币 + 44/1000） |
| 若按 Lv3 速率（14 金币/分钟）结算这段离线 | **本应 +99434 毫币 ≈ +99 金币** |
| 实际 | **+0** |
| 存档里的旧时间戳 | **被明确丢弃**（日志原文：`（存档里的 1791553929034 已被丢弃，不追溯离线收益）`） |

**决定性的日志内精确等式**（回放器 S6 校验）：
读档余额 = `127044` 毫币；读档后过了 **1024 ms 在线时间**，第一条 `save write` 的余额 = `127283` 毫币。
用共享核心 `settle()` 复算同一段在线时间，期望值 **正好是 127283**（`127044 + 239`）。

> 也就是说：读档后的余额**恰好**是存档余额，之后**只按在线毫秒**增长。
> 如果离线间隔被结算过，第一条写档的余额会多出约 99434 毫币 —— 实际没有。

**关闭方式**：DevTools 进程按安装目录前缀精确匹配后被强制结束（`TARGETS=16` → `LEFT=0`，`CLOSED_AT=21:52:32`），
所以这**不是**「窗口最小化」，而是真正的进程消失后再打开。

### 8.2 浏览器：1 小时旧时间戳

```
PASS | D7 读档后金币没有被离线 1 小时结算（Lv1 本应 +600 金币） | coinsMilli=0（离线 1 小时 @10/min 本应是 60000）
PASS | D7 读档后结算基线 = 重新打开的时刻，不是旧的 last_settle_ts_ms | old=1791550461985 new=1791554062069 openAt=1791554061988
PASS | D7 离线期间的声望与寻访也没有被改写（原样恢复） | life=3 spend=3 visit=3
PASS | D7 重新打开后的在线时间照常结算（3 秒 ≈ 0~1 金币，绝不是 600） | coinsMilli=500（3 秒 @10/min ≈ 500 毫币）
```

### 8.3 核心测试

第 14 项：`lastSettleTsMs` 设为 1 小时前，`loadSave` 后 `sessionBaseMs === nowMs`，
`economy.lastSettleTsMs === nowMs`，金币**一分不加**。
第 22 项：读档后立刻 `settle(now)` 收益为 0；再过 1000 ms 收益恰好 166 毫币（不是 60000）。

### 8.4 关闭/隐藏前先结算当前在线时间

- 浏览器：`visibilitychange`(hidden) / `pagehide` / `beforeunload` → `settleAndSave(reason)` 先结算再写档。
  端到端 B4 证实：刷新后恢复的余额包含刷新前最后一段在线收益（`before=10 afterReload=11`），
  但**绝不包含**离线时段。
- 小游戏：`installLifecycleHooks({ onHide })` → `settleNow('hide')` → `persistSaveNow(true)` → 写日志
  `save onHide done`。`onHide` 在 `stopLoop('hidden')` **之前**执行（见 `src/platform/runtime.ts`）。

---

## 9. 第三/四/五步回归结果

| 回归项 | 方法 | 结果 |
| --- | --- | --- |
| 第三步时间收益 | 沙箱日志逐条回放（`analyze-vm-log-step6.mjs` V2）：238 条 `结算` 行全部能被共享核心复算一致 | **通过** |
| 第四步寻访 | V3/V4/V9：`visit#` 余额与声望一致、`last_settle_ts_ms` 前后相同、每次严格 +3000 毫币 | **通过** |
| 第四步负样本 | V6：`道路` / `浮空岛` / `树木` 都被真实射线命中但**都不发奖** | **通过** |
| 第四步手势门 | V7：`结算` 按钮点击**不**触发射线拾取 | **通过** |
| 第五步升级 | V10：4 次 `升级#`（含 `source=cityhall` 1 次）的等级/速率/余额/花费全部重放一致 | **通过** |
| 第五步金币不足 | V11：1 次 `升级失败（insufficient-coins）`，等级不变、一分不扣 | **通过** |
| 第五步市政厅分支 | V12：点市政厅走升级分支且**不**产生 `visit#` | **通过** |
| 第五步声望不变 | V13：升级全程不改动 `lifetime` / `spendable`，时间戳前后相同 | **通过** |
| 按钮热区 | V15：`settleY=[721,819]` / `upgradeY=[629,709]`，`overlap=false` | **通过** |
| 全程不变量 | V14：终态无负余额/负等级/NaN，`carryNumerator ∈ [0,59999]` | **通过** |
| 第五步回放器基线 | `analyze-vm-log-step5.mjs` 在第五步日志上 | **21/21 通过** |
| 核心文件是否被改写 | `economy.ts` / `visit.ts` / `upgrade.ts` / `input.ts` 本步**逐字节未改** | **通过** |

**沙箱日志回放（第六步）：29/29 通过**（`evidence/vm-log-analysis-step6.txt`）。
**第五步回放器在第五步日志上：21/21 通过**（`evidence/vm-log-analysis-step5.txt`）。

---

## 10. 自动化验证汇总

### 10.1 TypeScript 与核心测试

```
$ npx tsc --noEmit
（exit 0，0 错误）

$ npm test
core: economy.js=663 visit.js=545 upgrade.js=4708 save.js=9277 input.js=885
platform: storage-browser.js=388 storage-wx.js=428
scene: world.js=417 camera.js=1133 pick.js=925
browser: app.js=574051
game: bundle.js=580573 adapter.js=9182 total=589755
ℹ tests 75
ℹ pass 75
ℹ fail 0
```

第六步 `tests/save.test.mjs` 的 **32 项**覆盖任务书要求的 15 项必测：
新用户初始化、全字段往返、寻访后往返、升级后往返、`carryNumerator` 不丢失、
损坏 JSON 回退、`schemaVersion` 不支持回退、`NaN`/`Infinity`/负数/超范围拒绝、
重复读档不重复发奖、旧 `last_settle_ts_ms` 不产生离线金币、读档后新基线正确、
**两个适配器同构（byte-identical）**、第三/四/五步回归；
另有 2000 轮随机模糊测试与 200 轮逐字节稳定性测试。

### 10.2 浏览器端到端（无头 Chromium，软件光栅化）

```
=== browser verification (step6): 107/107 passed ===
log -> evidence/browser-verify-step6.log
```

分三组：B1–B13（第三步/第四步，含 B4 已改为「刷新必须恢复存档且不发离线收益」）、
C0–C8（第五步升级）、**D1–D11（第六步存档，40 项）**。

### 10.3 微信开发者工具游客模拟器

```
=== vm log replay (step6): 29/29 passed ===
```

覆盖 S1–S14（存档标识/命名空间/读档/离线收益/字段校验/节流/写档失败/错误数）与
V1–V15（第三/四/五步回归）。

> **关于 `tests/economy.test.mjs` 第 7 项**：该断言原本要求两个入口源码里**完全不出现** `carryNumerator`。
> 第六步浏览器入口需要把 `state.carryNumerator` **只读**透出到调试快照（诊断用），
> 因此把断言细化为「**不得写** `carryNumerator` / `lastSettleTsMs`，**不得对 `carryNumerator` 做运算**」——
> 仍然禁止入口自行实现结算，只是不再禁止只读透出。**核心结算逻辑没有搬到入口。**

---

## 11. 游戏代码错误与工具自身错误（严格区分）

### 11.1 游戏代码运行时错误：**0**

- `evidence/vm-boot-step6.txt`（沙箱 `stage-err.log`）全文只有 3 行：

```
boot 2026-10-09T13:59:14.695Z
ADAPTER_OK
BUNDLE_OK
```

- 回放器 S14：`ERROR|TypeError|ReferenceError` 匹配行 = **0**
- 无 `BOOT_FAILED`，无未捕获异常，无 GL 初始化失败
- 浏览器端到端 107 项全绿，无页面异常

### 11.2 工具自身错误（不是游戏代码错误）

| # | 工具/方法错误 | 现象 | 处理 |
| --- | --- | --- | --- |
| T1 | `sed` 改日志输出路径没匹配 | `verify-browser.mjs` 的路径被拆成 `'evidence', 'browser-verify-step5.log'` 两段字符串，`sed` 按整段路径替换必然失败 | 改用 `edit` 精确替换；产物路径已核对为 `evidence/browser-verify-step6.log` |
| T2 | 解析脚本硬编码了输入文件 | `parse_log.py` 里写死了 `/tmp/rawlog1.txt`，导致「点了 12 次居民却读到 0 次寻访」的假象 | 改为按参数传入；重新解析后确认 12 次寻访全部命中 |
| T3 | 第六步测试方法错误（**不是游戏 bug**） | 「写入样本存档 → `Page.reload`」读不回样本：因为第六步**正确行为**就是页面隐藏前**先结算再写档**，`pagehide` 把内存状态覆盖回了存储 | 新增 `suppressWrites()`：只让**当前文档**的 `setItem` 变空操作，reload 后新文档拿回真实 `localStorage`，从而精确读到样本存档 |
| T4 | `delete window.localStorage` 破坏了全局绑定 | Chrome 里 `localStorage` 是 `window` 的**自有**访问器属性，`delete` 之后裸标识符 `localStorage` 变成 `ReferenceError` | 改为先保存 `Object.getOwnPropertyDescriptor(window,'localStorage')`，恢复时把描述符装回去 |
| T5 | 离线收益判据不能手算 | 手算 `floor(在线ms × 速率 / 60000)` 与核心差 1 毫币，因为 `carryNumerator` 也参与分子 | 改用共享核心 `settle()` 直接算期望值，**与游戏运行时同一份代码** |
| T6 | 写档恢复后状态提示不刷新（**游戏显示层缺陷，已修**） | `setItem` 恢复成功后 `saveStatus` 仍停在「本地保存失败」 | 写档成功时若此前是失败态，则把 `saveStatus` 重置为读档结论（浏览器与小游戏入口同改） |
| T7 | 回放器 `ratePerMinute` 传参错误 | 误传 `economy` 对象而非 `economy.level`，导致每次升级都判「速率不一致」 | 改为 `ratePerMinute(got.economy.level)` |
| T8 | 回放器正则分组下标错位 | `升级#` / `升级失败` 的时间戳是第 16/17、15/16 组，误用第 14/15 组 | 逐组核对后修正 |
| T9 | 回放器取错结果字段 | `applyUpgrade` 返回 `{ economy, visit, result }`，`settle` 返回 `{ state, result }`，误读顶层 `ok`/`gainMilli` | 统一改为读 `.result.*` |
| T10 | `read_gamelog.ps1` 输出需按 `R\| ` 切分 | 每个文件被 `Get-Content -Raw` 打成一行，`grep "^R\| "` 只能匹配首行 | 用 `re.split(r'^FILE ', raw, flags=re.M)` 切文件块，再剥掉 `R\| ` / `Response: ` 前缀 |

### 11.3 游客模式授权错误：**1（不是游戏代码错误）**

- `-80002 webapi_getwxaasyncsecinfo:fail` —— 游客模式限制
- 控制台徽标 **❌2 ⚠️1 = 第三步基线**，本步**没有新增任何错误**

---

## 12. 真机未验证

- **AppID 仍在审核中**，因此：
  - **没有**真机预览、**没有**真机通过结论
  - **没有**二维码、**没有**伪造 AppID
  - 微信正式上传/发布**未验证**
- 已验证范围：**微信开发者工具游客模拟器**（`platform=devtools`、`lib=3.17.2`、`system=iOS 10.0.1`、
  `model=iPhone 12/13 (Pro)`、`dpr=3`、`win=390x844`）+ 无头 Chromium 浏览器版本。
- `wx.setStorageSync` / `wx.getStorageSync` 在游客模拟器里**实测可用**（写档 52+21 次、失败 0 次）。

---

## 13. 未进入第七步

**本地存档已实现，离线收益属于第七步，当前未实现。**

- 重新打开时**基线重置为当前 `now_ms`**，存档里的旧 `last_settle_ts_ms` 一律丢弃
- 关闭期间的时间**不会被结算成金币**（模拟器实测 7.1 分钟离线 → +0 毫币）
- 没有实现：离线时长计算、离线收益上限、离线收益弹窗/领取界面、离线收益补偿
- 没有实现：自动升级、x10/MAX/批量升级、岛屿扩张、云存档、账号系统、跨设备同步、
  助手、广告、后端、排行榜、真机预览、正式上传

---

## 14. 回滚方法

本项目**不是 git 仓库**，回滚靠源码包：

1. **完整回滚到第五步**：解压 `wyszz-0.1-step5-source-*.zip` 覆盖项目目录，然后
   ```
   rm -f src/core/save.ts src/platform/storage-browser.ts src/platform/storage-wx.ts \
         tests/save.test.mjs tools/analyze-vm-log-step6.mjs
   # 把 build.mjs 的 buildCore() entryPoints/names 去掉 save.ts、删除 buildPlatform()、
   # 把 package.json 的 test 脚本与 TARGETS 还原，然后
   npx tsc --noEmit && npm test && npm run build
   ```
2. **只回滚第六步新增文件**：删掉上表 6 个新增文件即可（第五步代码本身没被改写，
   但 `src/browser/main.ts` / `src/game/main.ts` / `build.mjs` / `package.json` / `public/index.html` 有改动，
   所以「只删新增文件」会留下悬空 import，必须同时还原这几个文件）。
3. **存档数据回滚**：浏览器控制台 `localStorage.removeItem('wyszz-0.1-ds-save')`；
   小游戏 `wx.removeStorageSync('wyszz-0.1-ds-save')`。
   存档损坏时的表现**已经是安全回退**（显示「本地存档无法读取，已使用新游戏」）。
4. 更早的回滚点：`wyszz-0.1-step4-source-*` / `wyszz-0.1-step3-source-*`。

---

## 15. 隔离声明：旧项目与其他实验目录未修改

本步**只写了** `/vol1/ai/projects/wyszz-new/wechat-game-0.1-ds/`（以及全局规则要求的
`/vol1/ai/vault/AI记忆库/` 记录、Windows 虚拟机里 `C:\projects\wyszz-wx-spike\` 下的模拟器槽位）。

**未读取、未修改、未删除**：

- `/vol1/ai/projects/little-town/`
- `/vol1/ai/projects/wyszz-new/3d-spike-ds/`、`/vol1/ai/projects/wyszz-new/wechat-spike-ds/`
- `/vol1/ai/projects/wyszz-new/app/`
- MIMO 对照目录、`3d-spike/`
- 公网预览基础设施：**未改动 Cloudflare / DNS / 现有服务配置 / systemd / NAS 权限 / 共享 / 路由 / 防火墙 / 公网 3D 服务**

`https://mayor3d.hynixing.cn/` 保持可访问（HTTP 200）。

---

## 16. 本步遗留与下一步

**遗留（不阻塞）**

1. 存档目前只保存 0.1 已实现状态；第七步若新增「离线收益」相关字段（如上次离线领取时间），
   需要把 `schemaVersion` 升到 2 并写迁移规则（当前 `parseSave` 对非 1 的版本一律判损坏回退，
   升级版本时必须同步改这一处）。
2. 写档节流固定 15 秒；如果后续出现「长时间后台再切回」的极端场景，可考虑在 `onShow` 时补一次强制写档。
3. 真机验证仍待 AppID 审核通过。

**下一步（用户未要求，本步不做）**

- 第七步：离线收益。需要明确离线时长上限、离线收益公式、领取界面，
  以及「离线收益与本地存档 `lastSettleTsMs` 的关系」——**本步已刻意把这条边界留干净**：
  读档一律重置基线，第七步只需在读取存档后、建立基线前插入离线收益计算即可。
