# 11 · 交付报告（高模型前端重建契约包 v1）

- 日期：2026-10-10
- 交付物：**高模型前端重建契约包 v1**（`frontend-rebuild-contract-v1`）
- 本任务性质：**只做冻结与整理**，不重做视觉，不进入 0.2
- 本任务结束时状态：**已完成并停止**

---

## 11.1 一句话结论

已把《我要当岛主》0.1 第三～第八步已验收的**功能规则**冻结成一份与旧视觉实现
**完全隔离**的契约包：40+ 个文件全部是文档、类型声明、接口声明、工具脚本与 JSON 夹具，
**零图片、零旧源码、零旧路径、零凭据**；20 个场景 / 32 个变体 / 106 个事件步的黑盒夹具
用参考实现跑出 **32/32 通过**；契约类型与接口 `tsc --noEmit` **0 错误**。

---

## 11.2 契约包内容清单

| 类别 | 文件 | 说明 |
| --- | --- | --- |
| 交接说明 | `README.md` | 五分钟上手 + 验收清单 |
| 契约说明文档 | `docs/01-契约总览.md` | 范围、术语表、状态机全景、三条最易错顺序、精度原则 |
| | `docs/02-状态与字段清单.md` | 13 个持久字段的名称/类型/单位/范围/初始值/谁能改；派生量；17 条不变量；明确不持久化的东西；校验顺序表 |
| | `docs/03-公式与规则清单.md` | 时间收益公式（含 9 个验证向量）、寻访规则、升级规则、离线规则、边界行为总表 |
| | `docs/04-API契约.md` | 每个 API 的输入/输出/错误/不变量 + 完整流程调用顺序 |
| | `docs/05-事件序列格式.md` | 8 种平台无关事件、字段、可观测输出、事件→API 映射 |
| | `docs/06-v1到v2迁移规则.md` | 迁移规则、每条规则的理由、验证向量、不许做的事 |
| | `docs/07-黑盒夹具说明.md` | 20 个夹具清单、F11 的 13 个变体、用法、比对强度 |
| | `docs/08-依赖边界与技术约束.md` | 8 条依赖禁令 + 6 条技术约束 |
| | `docs/09-核心测试结果摘要.md` | 第三～八步实测数字、22 项微信模拟器判据、未验证部分 |
| | `docs/10-隔离声明.md` | 包含什么、绝不包含什么、怎么自检、功能等价定义 |
| | `docs/11-交付报告.md` | 本文件 |
| TypeScript 类型定义 | `types/game-state.d.ts` | 全部状态类型 + 常量声明 + 字段取值表（**无实现**） |
| 平台无关 API 接口 | `api/contract.d.ts` | 全部 API 签名 + 输入/输出/错误/不变量（**无实现**） |
| 实现骨架 | `api/skeleton.ts` | 签名齐全、函数体全是 `throw new Error('未实现')`（**无任何公式**） |
| JSON 黑盒测试夹具 | `fixtures/*.json`（21 个） | 20 个场景 + 索引；32 个变体；106 个事件步 |
| 工具 | `tools/driver.mjs` | 参考驱动：事件序列 → API 调用（唯一语义） |
| | `tools/scenarios.mjs` | 场景定义 |
| | `tools/gen-fixtures.mjs` | 夹具生成器（`--core` 传入实现，**不内置任何路径**） |
| | `tools/run-fixtures.mjs` | **新前端的验收工具**（`--impl` 传入自己的实现） |
| | `tools/check-isolation.mjs` | 隔离自检（A～E 五类规则） |
| 工程配置 | `tsconfig.json` | 契约类型检查配置 |
| SHA-256 清单 | `SHA256SUMS.txt` | 41 个文件的 SHA-256（不含自身） |

---

## 11.3 严格禁止放入的内容 —— 逐条核对

| 禁止项 | 结果 | 依据 |
| --- | --- | --- |
| 旧前端源码 | **0** | 自检规则 C（旧前端源码特征标识）0 命中 |
| 旧场景代码 | **0** | 自检规则 C 0 命中 |
| 旧 CSS | **0** | 文件类型白名单只允许 `.md/.ts/.mjs/.json/.txt`；无 `.css` |
| 旧截图 | **0** | 自检规则 A（视觉产物）0 命中 |
| DSH / 外部模型的视觉实现 | **0** | 自检规则 B/C 0 命中 |
| 旧目录路径 | **0** | 自检规则 B 0 命中；生成器/校验器都用参数传路径 |
| 「照着旧画面复刻」的描述 | **0** | 全文只描述「必须可读什么信息」，不描述构图 |
| 调试密钥 / 公网凭据 / 内部服务信息 | **0** | 自检规则 D 0 命中 |

**合计 42 个文件全部合规。**

### 一个值得说明的设计

`tools/check-isolation.mjs` 的**模式串是拼接出来的**（如 `'wechat-' + 'game-0.1-ds'`），
这样检查器**自身也不含被禁止的字面量** —— 否则它会把自己判成违规，
而且会把旧路径写进契约包。同理，`gen-fixtures.mjs` 与 `run-fixtures.mjs`
**不内置任何实现路径**，必须由 `--core` / `--impl` 显式传入。

---

## 11.4 必须验证的项目 —— 逐条结果

### ✅ 契约包内没有旧前端源码、截图和视觉产物

```
node tools/check-isolation.mjs --root .
文件总数：42
文件类型分布：.json×22  .md×11  .mjs×5  .ts×3  .txt×1
PASS | A 视觉产物：0 命中
PASS | B 旧目录/旧路径：0 命中
PASS | C 旧前端源码特征：0 命中
PASS | D 凭据/内部信息：0 命中
PASS | E 文件类型白名单：0 命中
=== 隔离自检：PASS（42 个文件全部合规）===
```

文件类型分布本身就说明问题：**只有文档、类型、工具、夹具、清单**，
连一个 `.png` / `.css` / `.html` 都没有。

### ✅ 原 0.1 项目目录未修改

| 目录 | 本任务期间被改动的文件数 |
| --- | --- |
| 0.1 正式开发目录 | **0** |
| 3D 预览工程目录 | **0** |
| 小游戏试验目录 | **0** |
| 应用目录 | **0** |
| 旧项目目录 | **0** |

判据：`find <dir> -newermt "<任务开始时刻>" -type f | wc -l` ⇒ 全部为 `0`。
并且「本任务开始后被动过的文件」全部落在契约包目录内，无一例外。

### ✅ 公网根路径、`/step6/`、`/step7/`、`/step8/` 未修改

| 页面 | HTTP | 字节 | sha256（前 16 位） | 与基线 |
| --- | --- | --- | --- | --- |
| 根路径 | 200 | 1337 | `fbad5a50982c1f36…` | **一致** |
| `/step6/` | 200 | 9048 | `266a5e5bb9dfb3e4…` | **一致** |
| `/step7/` | 200 | 13600 | `03139af1f1a844a7…` | **一致** |
| `/step8/` | 200 | 14797 | `8142457b9b558a37…` | **一致** |

本任务**未触碰**任何 DNS、CDN、隧道、反向代理、防火墙或系统服务配置。
未部署、未上传、未删除任何公网文件。

### ✅ 当前 0.1 八步仍保持可回滚

- 回滚目标目录存在且内容完整（`assets/`、`index.html`、`step6/`、`step7/`、`step8/`）。
- 一条命令回滚第八步：`rm -rf <3d 预览工程目录>/dist/step8` ⇒ `/step8/` 立即回到 404，
  其余三个页面完全不受影响。
- 本任务**没有**改动任何回滚相关文件。

### ✅ 不进入 0.2

- 契约包**不含** 0.2 的任何设计：岛屿扩张、种子生成、随机地形 / 场景、助手、广告、
  后端、排行榜、月度赛季、新的升级轨道。
- 契约包**不含**真机发布或正式提交审核的任何内容。
- 本任务结束后**停止**，不自动继续。

### ✅ 不开始高级模型前端实现

- 契约包里**没有任何渲染实现**：`find` 结果中除文档 / 类型 / 工具 / 夹具 / 清单外无其它文件。
- `api/skeleton.ts` 的函数体全部是 `throw new Error('未实现')`，**不含任何公式**。
- 本任务**未调用**任何高级模型来生成契约内容；契约是从已验收的功能核心中人工抽取并冻结的。
- 本任务**未创建**任何新前端工程、未写任何渲染代码、未做任何视觉改动。

---

## 11.5 契约包自身的验证

| 验证项 | 工具 | 结果 |
| --- | --- | --- |
| 隔离自检（A～E 五类） | `tools/check-isolation.mjs` | **PASS（42/42 文件合规）** |
| 契约类型 + 接口 + 骨架类型检查 | `tsc --noEmit -p tsconfig.json` | **0 错误** |
| 黑盒夹具自检（参考实现跑夹具） | `tools/run-fixtures.mjs` | **32/32 通过** |
| SHA-256 清单校验 | `sha256sum -c SHA256SUMS.txt` | **41/41 OK** |
| 夹具规模 | — | 20 场景 / 32 变体 / 106 事件步 |

### 夹具覆盖的场景

新游戏、10 次居民寻访、射线负样本、Lv1→Lv2 升级、金币不足升级、进入后台、
离线 1 小时、离线 1h/8h/24h/7d、重复返回前台、存档+刷新恢复、损坏存档（13 个变体）、
v1 存档迁移、时间倒退、carry 余数累积、离线 carry+等级速率、只读预演一致性、
**离线期间跳过在线结算（防重复发放的关键守卫）**、离线零时长、升级后速率交接、迁移后继续游玩。

---

## 11.6 交接说明（给接手的高级模型）

### 你唯一需要做的事

```bash
node tools/run-fixtures.mjs --impl <你的核心模块目录>
```

目标：**32/32 通过**。没通过之前不要开始调画面。

### 你的实现目录需要导出五个 ESM 模块

```
economy.js   createInitialState, settle, ratePerMinute, rateMilliPerMinute, coinsOf, pendingMilli, creditMilli
visit.js     createVisitState, applyResidentVisit, isResidentTag
upgrade.js   applyUpgrade, upgradeCostCoins, upgradeCostMilli, isCityhallTag
save.js      loadSave, persistSave, parseSave, encodeSave, toSaveRecord, clearSave, migrateV1ToV2, SAVE_NAMESPACE
offline.js   enterBackground, enterForeground, previewOffline, offlineDuration
```

导出名与语义以 `api/contract.d.ts` 为准；`api/skeleton.ts` 可直接复制开工。

### 三条最容易踩的坑

1. **升级前必须先按旧速率结算时间收益**，再检查金币、扣费、升级。
2. **进后台前必须先结算在线区间**，再把离线起点设为那一刻；否则漏发。
3. **离线期间必须跳过在线自动结算**，否则同一段时间被算两次 —— 重复发放。
   （夹具 `F17` 专门验这条。）

### 你可以自由发挥的部分

- 场景怎么搭、模型怎么建、配色怎么定、界面怎么排版 —— **全部由你决定**。
- 本包**不提供**任何视觉参考，也**不要求**与任何既有画面相似。
- 契约只管：**必须可读哪些信息**、**行为必须怎样**、**数据必须怎样**。

### 你必须遵守的边界

- 只调用契约 API；不复制第二套经济公式；不自行修改核心状态；不从 UI 直接写金币或声望。
- Three.js + TypeScript；浏览器与微信小游戏共用同一套行为接口。
- 真实 3D 射线拾取；支持鼠标、触摸、旋转、缩放。
- 不使用 DOM 作为游戏画面。
- 不把模拟器结果写成真机结果。

---

## 11.7 交付物

| 交付物 | 内容 |
| --- | --- |
| **契约说明文档** | `README.md` + `docs/01` ～ `docs/11`（共 12 份） |
| **TypeScript 类型定义** | `types/game-state.d.ts` |
| **平台无关 API 接口** | `api/contract.d.ts`（+ `api/skeleton.ts` 骨架） |
| **JSON 黑盒测试夹具** | `fixtures/`（21 个 JSON） |
| **字段和公式清单** | `docs/02`（字段）+ `docs/03`（公式） |
| **隔离声明** | `docs/10` |
| **SHA-256 清单** | `SHA256SUMS.txt` |
| **交接说明** | `README.md` + 本文件 §11.6 |
| **源码包** | 契约包整体压缩 |
| **证据包** | 验证日志 + 本报告 |

全部交付物已用真实下载链接登记（见最终答复）。

---

## 11.8 边界与后续

- 本任务**已停止**。不进入 0.2，不开始高级模型前端实现，不重做视觉。
- 契约包内容**已冻结**。若需修改数值 / 公式 / 顺序 / 不变量，必须同时更新
  `docs/02`、`docs/03`、`api/contract.d.ts`、`types/game-state.d.ts`，
  **重新生成全部夹具**，并提升 `contractVersion`。
- 唯一未完成的既有待办仍是**真机验证**（微信小游戏账号标识审核中），
  它与本契约包无关，也不因本任务而改变状态。
