# 中学物理实验仿真平台 · 平台外壳 v4.0

> 当前位置：`42实验/_平台/`
> 定位：**可迁移的平台外壳**——把一个个独立实验（如「探究平抛运动的特点」）挂到统一的
> 教材目录、账号体系、实验记录与账户中心下，并支持**初中 / 高中双学段**。
> 平台零依赖、`file://` 双击即用，**不改动任何实验本体**。
> v4.0 新增：详情页底部改为**「继续上次实验 / 新建实验」两个主按钮**，继续时弹**多存档列表**
> （读实验端写在 `localStorage` 的 `pp_sessions_<用户名>_exp6`）；新增**课本 Word → 教材图集**
> 零依赖工具 `tools/docx2imgs.js`；去掉页面上的脚手架说明文字；修复教材参考页签的重叠问题。

---

## 一、文件清单

| 文件 | 作用 | 运行时依赖 |
| --- | --- | --- |
| `index.html` | 平台首页：顶栏（Logo / 学段切换 / 学科 / 搜索 / 登录）、左侧目录树、主区、右侧「服务 + 我的」、登录弹窗、账户中心抽屉、**实验详情弹层 + 存档列表弹层 + 图片放大层**、隐藏的 `#diag` | 无 |
| `platform.css` | 视觉系统 v4（**蓝白明亮风**）：设计令牌、三栏布局、渐变主卡、实验卡片、弹窗、抽屉、**详情页 / 存档列表 / 流程步骤条 / 效果图网格 / lightbox**、表格、动画、自适应、打印 | 无 |
| `platform.js` | 学段数据模型与切换、清单加载与兜底、目录树 / 卡片渲染、服务探测、**登录与账户中心**、**实验详情页（多存档读取 / 删除 / 继续 + 教材图集读取与打印 + 重叠体检）**、实验 / 后台入口 URL 拼参、内联 SVG Logo、自检 | 无 |
| `experiments.json` | **实验清单（迁移的唯一数据源）**：`stages[] → books → chapters → experiments`；实验可带 `detail` 字段（详情文案 / 效果图 / 流程 / 教材要点） | 无 |
| `教材/index.json` | **教材扫描件索引**：`{ "exp6": [ { "src":"exp6/p1.png", "title":"教材第 1 页", "note":"来自 课本.docx" } ] }` | 无 |
| `教材/index.js` | `index.json` 的 **JSONP 镜像**（`window.__PP_TEXTBOOK_INDEX__`）：`file://` 下 `fetch` 被拦时平台改读这个脚本，离线也能看图集（由 `docx2imgs.js` 自动生成） | 无 |
| `教材/exp6/` | 教材扫描件存放目录（`p1.png`、`p2.png` … 由 `docx2imgs.js` 生成，也可手工放 PNG/JPG） | 无 |
| `tools/docx2imgs.js` | 开发期工具（**零依赖**，只用 `fs`/`path`/`zlib`）：课本 `.docx` → `教材/<expId>/p1.png…`，并自动更新 `教材/index.json` + `index.js` | 仅 Node |
| `tools/sync-fallback.js` | 开发期工具：把 `experiments.json` 同步进 `platform.js` 的兜底数据 | 仅 Node（非运行时） |
| `tools/screenshot.js` | 开发期工具：无头 Edge + CDP（Node 自带 WebSocket，零 npm）批量出验收截图并回收 `#diag` / JS 报错；`--user-data-dir` 放 `%TEMP%` 且跑完即删 | 仅 Node + Edge（非运行时） |
| `tools/verify.js` | 开发期工具：v4 验收（本地静态服务 + CDP）——6 张截图 + `#diag` + **`getBoundingClientRect` 重叠体检** + 存档删除流程 + JS 报错回收；0 报错 / 0 重叠才返回 0 | 仅 Node + Edge（非运行时） |
| `README.md` | 本文档：学段 / 登录 / 账户中心 / **详情页与多存档 / 教材图集** / URL 传参约定 / 迁移 / 验收 | 无 |
| `预览截图/v3_*.png` | v3 验收截图（6 张，见第七节） | 无 |
| `预览截图/v4_*.png` | v3.1 详情页验收截图（6 张 + 1 张卡片双按钮） | 无 |
| `预览截图/v5_*.png` | v4 验收截图（6 张：两按钮 / 存档列表 / 教材参考 / 教材图集 / 首页 / 800px） | 无 |
| `预览截图/v5-shots.json` | v4 验收脚本回收的自检结果（`#diag` 全量 + 每张截图的重叠体检 / JS 报错数 + 存档删除流程） | 无 |

平台运行时**不引用任何 npm 包、CDN、外部字体或图标**；Logo 是 `platform.js` 里的手写内联 SVG。

---

## 二、快速开始

1. **双击 `_平台/index.html`**：直接以 `file://` 打开即可看到完整目录树与卡片。
   （`file://` 下 `fetch('experiments.json')` 被浏览器拦截，平台自动改用 `platform.js`
   内置的同一份兜底数据，界面与联网时完全一致。）
2. **推荐方式**：在 `42实验/` 目录起一个静态服务：

   ```bat
   cd /d "42实验"
   python -m http.server 8080
   ```

   访问 `http://localhost:8080/_平台/index.html`（也可用 VS Code Live Server 等；
   平台自身不需要安装任何依赖）。
3. **平台服务（8848）**：负责登录、实验记录与教师后台。未启动时：
   - 目录浏览、实验入口、游客体验**全部可用**；
   - 账户中心历史为空并提示「启动平台服务后可查看」；
   - 修改密码按钮置灰，右上角登录会提示「登录失败：网络不可达」。

> 启动服务：在实验 6 的 `仿真/` 目录运行 `启动服务.bat`（或 `node server/server.js`）。

---

## 三、登录与账户中心（v2 新增）

### 3.1 平台直接登录

- 入口：首页右上角**「登录」**（未登录）或用户徽标菜单 →「账户中心」。
- 调用：`POST {serviceBase}/api/auth/login`，请求体 `{ username, password }`。
- 成功返回：`{ ok, token, user:{ id, username, name, role, roleLabel, cls, classes } }`。
- **平台登录态**存在 `sessionStorage`：
  - `pp_platform_token`：平台自身使用（键名固定，验收项之一）；
  - `pp_token`：**写给实验页**（实验内 `cloud.js` 已按此键读取令牌）。
- 登录后右上角显示：**首字头像 + 姓名 + 角色徽标**，下拉菜单含
  「账户中心 / 进入实验 / 退出登录」。
- 刷新页面会用 `GET /api/auth/me` 静默续期；401 则自动清除登录态。
- 退出：`POST /api/auth/logout`，随后清除上述两个键。

### 3.2 三种角色

| 角色 | `role` | 徽标 | 账户中心可见内容 |
| --- | --- | --- | --- |
| 管理员 | `admin` | 管理员（金色） | 全平台记录（按后端过滤）+ 头部「打开管理后台」按钮 |
| 教师 | `teacher` | 教师（绿色） | 所负责班级的记录 + 学生姓名 / 班级列 |
| 学生 | `student` | 学生（蓝色） | 仅自己的记录 |

默认账号（v4 起管理员改为 `yxb`）：`yxb/yxb050608`、`teacher1/123456`、`teacher2/123456`、
`student01~12/123456`。老库（只有 `admin` 的 `users.json`）启动时会**自动补建 `yxb`**，
原 `admin` 账号保留、密码不变，仍可登录。

### 3.3 账户中心（居中抽屉）

居中抽屉面板（宽 `min(1000px, 100%)`、最高 `90vh`，窄屏自动收边；打开时缩放 + 淡入），
顶部是头像 / 姓名 / 角色徽标 / 班级，下方三个 Tab：

1. **实验历史**：表格 `时间 / 实验名 / 方案 / 数据点 / v₀ / 得分 / 等级 / 操作`
   - 数据：`GET /api/records`（Bearer，后端按角色过滤）；
   - **查看报告**：`GET /api/records/:id` → 取 `reportHTML` → 用 `<iframe srcdoc>` 渲染
     （`sandbox=""`，只渲染不执行脚本；若后端未返回完整 HTML 会自动补一层浅色排版样式）；
   - **继续**：按该记录所在实验打开，自动带 `?resume=1`；
   - 状态：加载中 / 空（无记录）/ 离线 / 错误（HTTP 状态与原因）四种提示。
2. **我的账号**：账号信息（姓名 / 账号 / 角色 / 班级 / 登录状态）+ 修改密码表单
   （旧密码 + 新密码 + 确认，`POST /api/auth/password`，新密码 ≥ 6 位、两次一致、不同于旧密码）
   + 退出登录。**服务离线时表单置灰并给出原因。**
3. **快捷进入**：
   - **继续上次实验**：取最近一条记录所在实验 → `?token=…&auto=1&resume=1`；
   - **新建实验**：首个已上线实验 → `?token=…&auto=1&fresh=1`；
   - 下方实时展示「将打开的地址」（令牌中间以 `…` 省略，便于阅读）。

首页主区同样有**「继续上次实验 / 新建实验」两张主卡**，逻辑与 Tab3 完全一致。

### 3.4 不存在后端时

| 场景 | 行为 |
| --- | --- |
| 服务未启动 | 顶栏与右栏显示「未连接」；登录失败给出「网络不可达」；历史为空并提示「启动平台服务后可查看实验历史」；改密置灰 |
| 记录接口报错 | 历史区显示错误原因（含 HTTP 状态码），页面其余部分不受影响 |
| 令牌过期 | 静默清除登录态并回到未登录视图 |

### 3.5 学段切换（v3）

- 顶部「初中 / 高中」分段切换（`#stage-switch`），也可用 `?stage=junior` / `#stage/senior` 直接进入；
  上次选择记在 `sessionStorage.pp_platform_stage`，默认进入**高中**。
- 切换后**目录树、实验卡片、概览统计、主卡与右栏文案、页脚数据源全部随之切换**；
  搜索关键词会被清空（避免把「搜索无结果」误读成「该学段没有实验」）。
- 当前清单：**高中 21 个实验**（6 册 / 17 章，已上线 1）；**初中 20 个实验骨架**
  （人教八上 / 八下 / 九全一册，3 册 / 14 章，全部 `todo`，等实验页上线后把 `status` 改 `ready` 并填 `path` 即可）。
- 初中没有已上线实验时：主卡按钮置灰并给出说明，卡片显示「待上线」，`#diag` 中
  `readyCardClickable / readyTargetLooksValid` 自动视为通过（`stageCountsMatch` 仍严格校验）。

---

## 四、实验入口传参约定（**实验页需要实现的约定**）

平台在打开实验时统一拼接以下查询参数（见 `platform.js → buildExperimentURL()` / `buildDetailURL()`）：

| 参数 | 含义 | 平台何时拼接 |
| --- | --- | --- |
| `token=<登录令牌>` | 直接携带平台令牌 | 已登录时（卡片「直接进入」、详情页两个按钮、菜单「进入实验」、历史「继续」） |
| `auto=1` | 有令牌时**跳过实验登录页**、自动进入 | 与 `token` 同时出现（详情页入口即使未登录也保留，见下） |
| `from=platform` | **标明来自平台详情页**，实验页可据此做埋点 / 返回入口 / 差异化引导 | 详情页两个按钮 |
| `resume=1` | **继续上次实验**：载入该实验最近一次会话 / 记录 | 详情页「继续上次实验」、「历史记录-继续」 |
| `session=<存档 id>` | **恢复指定存档**（`localStorage` 里的 `id` 字段） | 详情页「继续上次实验」→ 存档列表里选中一条（v4 新增） |
| `fresh=1` | **新建实验**：全新会话，不载入历史数据 | 详情页「新建实验」、「全新开始」 |

完整形态示例（`file://` 与 `http://` 均可）：

```
# 卡片「直接进入」/ 菜单进入（老行为，不带 from）
…/6.探究平抛运动的特点/仿真/index.html?token=4f8c…&auto=1

# 详情页「新建实验」（v4 约定）
…/6.探究平抛运动的特点/仿真/index.html?token=4f8c…&auto=1&from=platform&fresh=1
# 详情页「继续上次实验」→ 存档列表选中某条存档（v4 约定）
…/6.探究平抛运动的特点/仿真/index.html?token=4f8c…&auto=1&from=platform&resume=1&session=s_1700000000000
# 兼容：只给 resume=1（实验页自己取该端最近一条存档）
…/6.探究平抛运动的特点/仿真/index.html?token=4f8c…&auto=1&from=platform&resume=1

# 游客走卡片「直接进入」：无参数
…/6.探究平抛运动的特点/仿真/index.html
```

> 详情页的 URL 由 `buildDetailURL(exp, mode, sessionId)` 生成：**始终带 `auto=1&from=platform`**，
> 已登录再加 `token`；`resume` 时若有选中存档再加 `session`。
> 未登录时「继续上次实验」置灰（提示「暂无存档，可新建实验」），「新建实验」会先弹登录框，
> 登录成功后自动接着进入。

### 实验页侧需要做的事

平台已经做了两件事，实验页只需读取：

1. **尽力写入** `sessionStorage.pp_token`（同源 / 同 `file` 源时生效）；
2. 在 URL 上拼接 `token` / `auto` / `resume` / `fresh`。

实验内 `js/cloud.js` 已用 `sessionStorage.getItem('pp_token')`，因此**同源场景无需改动**。
跨源（平台 `http://` ↔ 实验 `file://`）时 `sessionStorage` 不共享，需在实验启动时按 URL 参数落库：

```js
// 建议放在实验页面启动处（cloud.js 之后、app.boot() 之前）
(function () {
  var q = new URLSearchParams(location.search);
  var token = q.get('token');
  if (token) sessionStorage.setItem('pp_token', token);   // 与平台同一键名
  if (q.get('auto') === '1' && token) {
    /* 跳过实验内登录页，直接以该令牌进入端内；失败则退回登录页 */
  }
  if (q.get('resume') === '1') {
    /* 继续：载入该实验最近一次会话 / 记录 */
  }
  if (q.get('fresh') === '1') {
    /* 新建：清空临时会话，从零开始（提交时生成新记录） */
  }
})();
```

> 未登录时点「进入实验」会弹确认框：「登录后可记录成绩」→「去登录 / 以游客身份进入」，
> 游客进入**不带任何参数**，成绩不会入库。

### 后台管理入口（同样带 token）

账户中心头部的「打开管理后台 ↗」（仅管理员可见）由 `platform.js → buildAdminConsoleURL()` 生成，
与实验入口同一套约定：

```
http://localhost:8848/后台管理.html?token=<token>&auto=1
```

未登录时不带参数。后台页面按与实验页相同的方式读取 `token` / `auto`。

> **拼接位置**：实验入口 = `platform.js` 的 `buildExperimentURL()`；后台入口 = `buildAdminConsoleURL()`。
> 两者都以 `S.token`（= `sessionStorage.pp_platform_token`）为令牌来源，`S.token` 在登录 / 续期 /
> 退出时同步维护，令牌也会同时写入 `sessionStorage.pp_token` 供实验页读取。

---

## 四·五、实验详情页（v3.1 起 · v4 改为两个主按钮 + 多存档）

点实验卡片（非按钮区）或卡片上的「查看详情」→ 打开**全屏详情弹层**，先看介绍、效果图、流程与
教材参考，再由底部固定操作条决定是否进入实验。卡片右侧按钮变成两个：

| 按钮 | 行为 | 说明 |
| --- | --- | --- |
| 查看详情 | 打开详情弹层（等同点卡片空白处） | 默认入口，`todo` 实验也可查看 |
| 直接进入 → | 老路径，直接新标签页打开实验 | 保留给熟悉的老师，`todo` 实验显示「开发中」禁用 |

### 4.5.1 四个 Tab

| Tab | 内容 | 数据来源 |
| --- | --- | --- |
| 概览 | 实验名 / 章节 / 时长 / 难度 / 标签 + 3~5 句介绍 + 「为什么做这个实验」2 条 + 「你会得到什么」2 条 | `detail.intro / why / gain / difficulty` |
| 效果图 | 3~6 张**真实仿真截图**，3 列网格；点击放大（lightbox：`←/→` 翻页、`Esc` 关闭、「打开原图 ↗」） | `detail.figures[]` |
| 流程 | 横向步骤条（9 步），每步标注「动手实验 / 白板讲解」，并给出 3 个实验方案 | `detail.flow[]` / `detail.steps[]` |
| 教材参考 | 上半：教材要点卡 6~8 条（每条带「教材第 X 页」页码占位）；下半：教材原文 / 扫描件图集，含「打印教材页」 | `detail.textbook.points[]` + `教材/index.json` |

底部固定操作条（v4）：**继续上次实验 / 新建实验**（左侧一句短提示，右端「关闭」）。

- **继续上次实验**：有存档时可点 → 弹**存档列表**；没有存档时置灰，提示「暂无存档，可新建实验」；
  未登录同样置灰。进入 URL 形如 `…&from=platform&resume=1&session=<id>`。
- **新建实验**：`…&from=platform&fresh=1`；未登录先弹登录框。
- 未上线（`todo`）实验两个按钮都禁用。

### 4.5.2 存档列表（v4 新增）

数据来源：实验端 `js/session.js` 写在 `localStorage` 的多存档，键名

```
pp_sessions_<当前登录用户名>_<实验 id>      例：pp_sessions_student01_exp6
值：[{ id, name, mode:"teacher|student", savedAt(ms), step, phase, scene, params, payload }]
```

列表每条显示：**名称 / 角色（教师端 · 学生端）/ 保存时间 / 进度（第 N 步 或 第 N 环节）/ 状态**，
按保存时间倒序；操作：

- 点一行 = 选中（`继续 →` 才可用），再点一次或双击 = 直接进入；
- 「删除」= 确认后从 `localStorage` 移除并刷新列表（全部删完自动关闭弹层并提示「暂无存档，可新建实验」）；
- `Esc` 关闭；键盘 `↑/↓` 换行、`Enter` 选中/进入、`Delete` 删除。

平台只**读 + 删**存档，不写实验进度；同一浏览器、同一账号在实验端保存后，回到平台即可看到。
`#diag` 里可查 `detail.archive`（`key` / `count` / `rows` / `modalOpenable` / `emptyTip`）。

### 4.5.3 `detail` 字段（写在 `experiments.json` 的实验对象里）

```json
{
  "id": "exp6",
  "name": "探究平抛运动的特点",
  "detail": {
    "difficulty": "中等",
    "intro": "3~5 句：是什么 / 研究什么 / 结论指向",
    "why": ["为什么做这个实验（2 条）", "……"],
    "gain": ["你会得到什么（2 条）", "……"],
    "figures": [
      { "src": "../高中21/6.探究平抛运动的特点/仿真/预览截图/02_场景①挡板描迹.png",
        "title": "方案二·挡板描迹", "note": "一句话说明这张图在演示什么" }
    ],
    "flow": [
      { "name": "导入", "kind": "board", "desc": "白板讲解：从情境切入" },
      { "name": "频闪", "kind": "do",    "desc": "动手实验：等时间隔拍位置点" }
    ],
    "steps": [
      { "name": "频闪照相法", "tag": "方案一", "desc": "方案说明" }
    ],
    "textbook": {
      "ref": "exp6",
      "book": "人教版《物理》必修第二册 · 第五章 抛体运动 · 第3节",
      "points": [
        { "title": "平抛运动的定义", "text": "要点正文", "page": "10" }
      ]
    }
  }
}
```

- `figures[].src`：**相对 `_平台/index.html` 的路径**（可以指向别的实验目录，如 `../高中21/…`）；
- `flow[].kind`：`"do"` = 动手实验（青绿），`"board"` = 白板讲解（蓝色）；
- `steps[]`：3 个实验方案（也兼容写成 `plans[]`）；
- `textbook.ref`：对应 `教材/index.json` 里的键，默认等于实验 `id`；
- `page`：页码**占位**，按你手上的教材版本填写即可（界面显示为「教材第 10 页」，鼠标悬停有提示）。

> 没有写 `detail` 的实验不会报错：平台用**通用占位**（genericDetail）渲染——一段说明 + 2 条 why / gain +
> 4 步通用流程 + 空的效果图 / 方案区，并在概览里提示「按 README 补写 detail」。因此 41 个实验都能点开详情。

### 4.5.4 教材扫描件怎么用（教师操作）

> **推荐**：直接用下面的「把课本 Word 转成图集」工具，一条命令完成「导出图片 + 登记索引」。

#### 把课本 Word 转成图集（3 步）

1. **准备文件**：用 Word 把相关课本页整理成一个 `.docx`（图片可以是扫描页截图，也可以是 Word 的
   「插入 → 图片」），保存为 `课本.docx`。**注意**只支持 `.docx`；`.doc` 请先另存为 `.docx`。
2. **运行工具**（在 `_平台` 目录，Node 18+ 即可，**不需要 npm install**）：

   ```bat
   cd /d "42实验/_平台"
   node tools/docx2imgs.js "D:\课本\必修二第五章.docx" exp6
   ```

   第二个参数是实验 id（省略时按文件名推断：文件名含 `exp6`，或形如 `6.xxx.docx` → `exp6`）。
   工具只解压 `word/media/` 下的 `png/jpg/jpeg`，**按它们在文档里出现的顺序**输出为
   `教材/exp6/p1.png`、`p2.png` …（JPEG 输出 `p1.jpg`），并自动：
   - 写入 / 更新 `教材/index.json` 的 `exp6` 条目（`src` 相对 `教材/`，`title` 用「教材第 N 页」占位，
     `note` 记录来源文件）；
   - 同步生成 `教材/index.js`（JSONP 镜像，`file://` 双击打开也能读到图集）；
   - 清掉上一次生成的多余 `p*.png/jpg`，避免旧页残留。
3. **看效果**：刷新 `_平台/index.html` → 任一实验「查看详情」→ **教材参考** → 下半部分是图集
   （3 列，点击放大 / 可「打开原图 ↗」）；`#diag` 里 `detail.textbookIndex.rendered` 是渲染张数。

工具输出示例：

```
========================================
  课本 Word → 教材图集  完成
========================================
  源文件      D:\课本\必修二第五章.docx
  提取张数    3 张（png/jpg）
  输出目录    …\_平台\教材\exp6
  命名        p1.png … p3.png（按文档中出现顺序）
  index.json  已写入 exp6（3 条）  → …\_平台\教材\index.json
  index.js    JSONP 镜像已同步（离线双击 index.html 也能读）
```

失败时会给出中文原因与下一步建议（文件不存在 / `.doc` 旧格式 / 不是 zip / `word/media/` 无图片 /
`index.json` 不是合法 JSON 等）。

#### 手工登记（不用工具时）

1. 把扫描件（`png` / `jpg`，建议按页命名）放进 `_平台/教材/<实验id>/`，例如：

   ```
   _平台/教材/exp6/p10.png
   _平台/教材/exp6/p11.png
   ```

2. 在 `_平台/教材/index.json` 里登记（`src` **相对 `教材/` 目录**）：

   ```json
   {
     "exp6": [
       { "src": "exp6/p10.png", "title": "第五章 P10", "note": "平抛运动" },
       { "src": "exp6/p11.png", "title": "第五章 P11", "note": "频闪法 / 描迹法" }
     ]
   }
   ```

3. 刷新页面 → 详情页「教材参考」下半部分出现图集（3 列），点击图片可放大、可「打开原图 ↗」；
   点「打印教材页」只打印**教材要点卡 + 图集**（打印对话框里可选「另存为 PDF」）。

**空图集时**显示空态卡：「暂无教材扫描件」+ 一条命令提示
`node tools/docx2imgs.js 课本.docx exp6`；`继续上次实验`等按钮不受影响。

> `file://` 下浏览器会拦截 `fetch('教材/index.json')`，平台会自动改读 `教材/index.js`
> （JSONP 镜像，由 `docx2imgs.js` 生成），因此**双击 index.html 也能看到图集**；
> 两个文件都没有时按空图集显示，页面不报错。用静态服务打开同样可以（读 `index.json`）。

### 4.5.5 改详情文案（3 步）

1. 在 `experiments.json` 里找到实验对象，补 / 改 `detail.intro / why / gain / figures / flow / steps / textbook`；
2. 跑一次兜底数据同步（否则 `file://` 下还是旧文案）：

   ```bat
   cd /d "42实验/_平台"
   node tools/sync-fallback.js
   ```

3. 刷新 `index.html`：点卡片 → 详情页 → 逐 Tab 检查；`#diag` 里看 `detail.*`（见 7.7）。

> 只改文案时也可以直接开静态服务，此时读的是 `experiments.json` 本身，改完刷新即可（同步步骤仍然建议做）。
> 文案里可以写 `v₀`、`½gt²`、`Δy` 这类 Unicode 上下标，**不要写 LaTeX / Markdown 标记**。

### 4.5.6 深链接（自检 / 截图用）

```
index.html?detail=exp6                      打开详情（概览）
index.html?detail=exp6&detailtab=figures    打开效果图 Tab
index.html?detail=exp6&detailtab=textbook   打开教材参考 Tab
index.html#detail/exp6/flow                 同上（hash 形式，可带第 4 段开 lightbox）
index.html#detail/exp6/figures/1            效果图 Tab + 直接放大第 2 张
index.html?detail=exp6#detailselftest       只跑一次详情页自检（结果写 diag.detailCheck）
```

开发钩子（**仅 `file://` 或 localhost 生效**）：

| 参数 | 作用 |
| --- | --- |
| `?mockuser=admin\|teacher1\|student01` | 注入**无令牌**的模拟用户，用于离线验收账户中心 / 详情页按钮态 |
| `?mockrecord=1` | 塞一条模拟实验记录 |
| `?mocksessions=1` | 给当前 mock 用户写 3 条 `pp_sessions_<user>_exp6` 存档（学生端 / 教师端各若干），复现「继续上次实验」与存档列表 |
| `?mocksessions=clear` | 清掉这些模拟存档 |
| `?still=1` | 关闭卡片入场动画（截图用） |
| `?hover=exp6` | 让某张卡片停在 hover 态（截图用） |

---

## 五、迁移指南：新增一个实验

> **只需要动数据，不需要改平台代码。**
> v3 起数据在 `experiments.json → stages[]` 下：高中实验加到 `stages[1].books`（`senior`），
> 初中实验加到 `stages[0].books`（`junior`）；学段内的结构仍是「册次 → 章节 → 实验」。

### 第 1 处：放入实验目录

```
42实验/高中21/7.探究向心力大小与半径、角速度、质量的关系/仿真/index.html
```

### 第 2 处：在 `experiments.json` 对应学段中登记

```json
{
  "id": "exp7",
  "no": 7,
  "name": "探究向心力大小与半径、角速度、质量的关系",
  "status": "ready",
  "path": "../高中21/7.探究向心力大小与半径、角速度、质量的关系/仿真/index.html",
  "thumb": "",
  "tags": ["力学", "圆周运动"],
  "minutes": 45,
  "detail": { "intro": "…", "why": ["…"], "gain": ["…"], "figures": [], "flow": [], "steps": [] }
}
```

- `status`：`"ready"`（可进入，卡片出现「直接进入」）/ `"todo"`（卡片显示「待上线」且「直接进入」禁用）。
- `path`：**相对 `_平台/index.html` 的路径**；`todo` 留空字符串。
- `thumb`：可选缩略图（卡片统一使用 SVG 实验徽标 / 首字色块，此字段仅为兼容保留）。
- `id` 在**同一学段内**唯一，建议高中 `exp<序号>`、初中 `j<序号>`；`no` 用于卡片排序与序号徽章。
- `detail`：**可选**。不写也能点开详情（通用占位）；要正式文案 / 效果图 / 教材要点就按 4.5.2 补写。

### 第 3 处：同步内置兜底数据（**最容易漏**）

```bat
cd /d "42实验/_平台"
node tools/sync-fallback.js
```

> `file://` 下不能 `fetch` 本地 JSON，平台会用 `platform.js` 里的兜底副本。
> 不同步会出现「页面是新的、数据是旧的」。同步后自检项 `fallbackSynced` 为 `true`。

### 第 4 处：验收

先跑 JSON 校验（第六节 1），再双击 `index.html` 看目录树与卡片，最后看 `#diag`。

新增**章节 / 册次**：往对应学段的 `chapters` / `books` 数组里加对象，平台代码不变。
新增**学段**：在 `stages[]` 中加一个 `{ id, name, subject, curriculum, term, books[] }` 对象即可，
顶部切换按钮会自动多出一个（按钮总量 2 个是当前 UI 的排版前提，扩到 3 个建议同时收窄 `.stage-btn` 内边距）。

---

## 六、视觉规范（v3.1 · 蓝白明亮）

面向中学课堂：浅蓝白底 + 纯白卡片 + 单一蓝色强调；辅助青绿只用于「已上线 / 成功」。

| 令牌 | 值 |
| --- | --- |
| 背景 | `#f5f8ff` 渐变（`#f8fbff → #f3f7ff → #eef4ff`）+ 两处柔光 + 极淡点阵 |
| 卡片 | 纯白 `#fff`，`1px #e6ecf8` 描边，圆角 18~22px，阴影 `0 6px 20px rgba(47,107,255,.08)` |
| 主色 | `#2f6bff`（hover / 渐变用 `#2459e0`~`#4d8bff`），浅底色 `#eef4ff` |
| 辅助色 | `#12b7a8`（已上线 / 成功），只用于状态点、状态 Pill、统计数字 |
| 文字 | `#0f1b33` / `#5b6b85` / 弱化 `#8494ac` |
| 字号 | 正文与所有辅助文字 **≥13px**，行高 1.6~1.8；卡片标题 15.5px，页标题 `clamp(21px, 2.1vw, 27px)` |
| 渐变主卡 | 蓝→青 `linear-gradient(135deg,#2f6bff,#3d8bff,#12b7a8)`，白色文字 + 白色按钮 |
| 卡片信息 | 序号徽章（`06`）+ 实验 Logo / 首字色块 + 状态 Pill + 名称 + 册次·章节 + 标签 + 两个按钮（查看详情 / 直接进入）；2 列网格 |
| 详情弹层 | 宽 1240px / 最高 94vh 圆角 24px；遮罩加深到 `rgba(15,27,51,.52)` + 4px 模糊；头部 Logo + 名称 + 6 个信息 chip；底部固定操作条（`#fff→#fbfdff` 渐变 + 1px 上描边） |
| 流程步骤条 | 9 列等宽卡片，顶部 3px 色条：**动手实验=青绿 `#12b7a8`**、**白板讲解=蓝 `#2f6bff`**；步骤间箭头用旋转 45° 的双边线；窄屏横向滚动 |
| 教材参考 | 要点卡 2 列（页码 chip 浅蓝）；扫描件图集 3 列（`object-fit: contain`）；空态为虚线框 + 手绘 SVG + 一行命令提示 |
| 存档列表 | 弹层 620px；每行「圆形单选点 + 名称 + 角色/时间/进度/状态标签 + 删除」；选中行蓝色描边 + 光晕 |

### 动效（克制，可一键关闭）

| 交互 | 规格 |
| --- | --- |
| 页面进入 | 卡片 stagger 淡入上移：每张延迟 70ms（60~80ms 区间），封顶 240ms，单卡 340ms → 整段 < 600ms |
| 卡片 hover | 上浮 2px + 阴影加深 + 边框提亮，`0.18s cubic-bezier(.2,.8,.3,1)` |
| 目录展开 / 收起 | `grid-template-rows: 0fr → 1fr`，`0.25s` 高度过渡（只切 class、不重建 DOM） |
| 弹窗 / 抽屉 | `scale(.96) → 1` + 淡入，0.2~0.24s |
| 按钮 / 输入 focus | 蓝色光晕 `0 0 0 3px rgba(47,107,255,.16~.24)` |
| 减少动效 | `@media (prefers-reduced-motion: reduce)` 下全部动画与过渡关闭 |

### Logo（手写内联 SVG，可复用）

```js
PP.Platform.logoSVG(26)          // 平台：原子轨道 + 原子核 + 平抛轨迹小弧（白色系）
PP.Platform.expLogoSVG('exp6')   // 实验：坐标轴 + 抛物线 + 带拖尾的小球（蓝色系）
PP.Logos.platform / PP.Logos.experiment   // 同一函数的别名
```

平台 Logo 放在蓝色渐变圆角底块上（顶栏 / 登录弹窗）；实验卡片有仿真入口时用 `expLogoSVG`，
没有时用**实验名首字色块**（按 id 稳定取 6 种渐变之一），两者同一几何语言。

---

## 七、验收

### 1) JSON 合法性

```bat
cd /d "42实验\_平台"
set NODE=C:\Users\13591\.dsh\dsh-runtimes\dsh-primary-runtime\dependencies\node\bin\node.exe
%NODE% -e "JSON.parse(require('fs').readFileSync('experiments.json','utf8'));console.log('experiments.json OK')"
%NODE% -e "JSON.parse(require('fs').readFileSync('教材/index.json','utf8'));console.log('教材/index.json OK')"
```

> 一条命令同时校验两份（v3.1 起 `教材/index.json` 也是平台读取的 JSON）：

```bat
%NODE% -e "const fs=require('fs');['experiments.json','教材/index.json'].forEach(f=>{JSON.parse(fs.readFileSync(f,'utf8'));console.log(f+' OK')})"
```

### 2) 页面自检（隐藏 `#diag` 输出 JSON）

```powershell
$edge = "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe"
$page = "file:///C:/Users/13591/Desktop/2026大创/dsh/42实验/_平台/index.html"
$prof = Join-Path $env:TEMP ("pp-edge-" + [guid]::NewGuid().ToString('N').Substring(0,8))
& $edge --headless=new --disable-gpu --user-data-dir="$prof" --virtual-time-budget=8000 `
    --dump-dom $page | Out-File -Encoding utf8 "$env:TEMP\dom.html"
Remove-Item -Recurse -Force $prof      # 测完即删
```

从 `dom.html` 里读 `<pre id="diag">` 的 JSON。常用字段：

| 字段 | 期望 |
| --- | --- |
| `ok` | `true`（两个学段都应通过） |
| `checks.noJsError` | `true`（`errors: []`，即 0 个 JS 报错） |
| `checks.treeRendered` | `true`（当前学段：高中 6 册 / 17 章 / 21 实验；初中 3 册 / 14 章 / 20 实验） |
| `checks.cardsMatchTotal` | `true`（卡片数 = 当前学段实验数） |
| `checks.stageSwitchable` / `stageActiveMatchesData` / `stageCountsMatch` | 三项均 `true`（学段数据与渲染一致） |
| `checks.readyCardClickable` | 高中 `true`（exp6「直接进入」是可点链接且 href 与规则一致）；初中无已上线实验时自动视为通过 |
| `checks.todoCardsDisabled` | `true`（待上线卡片没有可用的「直接进入」） |
| `checks.loginModalExists` / `checks.accountCenterExists` | `true` |
| `checks.detailLayerExists` / `detailTabsSwitchable` | `true`（详情弹层与四个 Tab 都在、且可切换） |
| `checks.detailFiguresAtLeast4` | `true`（exp6 效果图 **6 张** ≥ 4） |
| `checks.detailFlowNineSteps` | `true`（流程 **9 步**） |
| `checks.detailTextbookState` | `true`（图集有图，或空态文案存在） |
| `checks.detailURLParams` | `true`（两个按钮 URL 分别含 `resume=1` / `fresh=1`，且都含 `auto=1&from=platform`） |
| `checks.detailCardActions` | `true`（卡片有「查看详情」+「直接进入」，且整卡可点） |
| `checks.detailTwoButtons` / `detailNoEnterButton` | `true`（v4：底部**只有**「继续上次实验 / 新建实验」，且旧的「进入实验」按钮已移除） |
| `checks.archiveListUsable` / `archiveEmptyTip` | `true`（有存档时弹层能打开且行数 = 存档数；无存档时提示「暂无存档，可新建实验」） |
| `checks.detailNoOverlap` | `true`（v4：四个 Tab 用 `getBoundingClientRect` 两两比过，0 处重叠；见 7.8） |
| `detail.tabs[]` / `detail.figures` / `detail.flowSteps` / `detail.textbookEmpty` | 详情页自检明细（见 7.7） |
| `ui.cards` | 高中 **21** / 初中 **20** |
| `ui.stageId` | `senior` / `junior` |
| `stage.id` / `stage.curriculum` | 当前学段（如 `senior` / `人教版（2019）`） |
| `stages[]` | 两学段各自计数：`junior 20`、`senior 21`（含 ready / books / chapters） |
| `dataSource` | `file://` 默认 `fallback`；加 `--allow-file-access-from-files` 或 HTTP 下为 `json` |
| `stats` | 当前学段明细，如高中 `books:6 / chapters:17 / total:21 / ready:1 / todo:20` |

两学段一起验（PowerShell，结果写到 `$env:TEMP`）：

```powershell
$edge = "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe"
$page = "file:///C:/Users/13591/Desktop/2026大创/dsh/42实验/_平台/index.html"
$prof = Join-Path $env:TEMP ("pp-edge-" + [guid]::NewGuid().ToString('N').Substring(0,8))
foreach ($q in @("?stage=senior", "?stage=junior")) {
  $dom = Join-Path $env:TEMP "pp-dom.html"
  & $edge --headless=new --disable-gpu --user-data-dir="$prof" --virtual-time-budget=8000 `
      --dump-dom "$page$q" | Out-File -Encoding utf8 $dom
  # 取出 <pre id="diag"> 的 JSON：ok / ui.cards / stage.id / errors
}
Remove-Item -Recurse -Force $prof      # 测完即删
```

### 3) 功能自检（`#selftest`）

在 URL 末尾加 `#selftest`，页面会用真实接口依次验证并把结果写进 `diag.selftest`：

- `logins[]`：`admin` / `teacher1` / `student01` 三角色登录成功、`badgeText` 与角色一致
  （管理员 / 教师 / 学生）、`tokenStored: true`、各角色可见记录条数；
- `accountCenter`：抽屉已打开、三个 Tab 可切换、改密表单四个控件存在、
  管理员「打开管理后台」可见、历史表格行数、**报告 iframe 真实渲染成功**
  （`report.state = "ready"`、`length > 0`、`frameHasContent: true`）、
  改密表单本地校验（`passwordValidation.mismatchDetected / shortPasswordDetected`，
  只触发前端校验，不调用接口、不改任何账号）；
- `urls`：`tokenInURL / autoInURL / resumeInURL / freshInURL / pathsMatch`，
  以及**点击真实按钮**捕获到的 URL 与 `buildExperimentURL()` 是否一致（`buttonsMatchBuilder`）；
- `guestConfirm`：未登录点击实验卡片时弹出游客确认、且没有直接打开；
- `summary`：以上各项的布尔汇总；`ok` 为总体结论。

### 3.1) 学段切换自检（`#stageselftest`）

在 URL 末尾加 `#stageselftest`，页面会切到另一个学段、统计卡片数、再切回来，结果写进 `diag.stageSwitch`：

| 字段 | 期望 |
| --- | --- |
| `from.stage` / `to.stage` | `senior` → `junior`（或反向） |
| `from.cards` / `to.cards` | `21` → `20` |
| `changed` | `true`（切换后卡片数确实变化） |
| `restored` / `ok` | `true`（切回后恢复原卡片数，且无 JS 报错） |

### 4) 离线兜底自检（`#selftest-offline`）

```
index.html?service=http://127.0.0.1:1&mockuser=admin#selftest-offline
```

期望：`service.state = "offline"`、页面仍渲染 21 个节点 / 21 张卡片、
表单提交后提示「登录失败：网络不可达」且按钮恢复可用、
账户中心历史为空且包含「启动平台服务后可查看」、改密按钮 `disabled = true`、`errors: []`。

### 5) 验收截图（`预览截图/`）

| 文件 | 内容 | 生成方式（无头 Edge 1600×1000） |
| --- | --- | --- |
| `v3_01-home-senior.png` | 高中首页（三栏 + 目录树 + 渐变主卡 + 2 列卡片） | `index.html?still=1` |
| `v3_02-home-junior.png` | 初中首页（20 个实验骨架，全部「待上线」） | `index.html?stage=junior&still=1` |
| `v3_03-login-modal.png` | 登录弹窗（输入框 focus 蓝色光晕） | `index.html?still=1#login` |
| `v3_04-account-center.png` | 账户中心 · 实验历史（真实服务 2 条记录） | `index.html?autologin=admin:admin123&still=1#account` |
| `v3_05-mobile-800.png` | 800px 移动版（单列、内容优先、目录树限高滚动） | `--window-size=800,1000` + `?stage=junior&still=1` |
| `v3_06-card-hover.png` | 卡片 hover 态（`?hover=` 加 `is-hover` class 模拟，无头下无法真实悬停） | `index.html?still=1&hover=first` |

```powershell
$edge = "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe"
$page = "file:///C:/Users/13591/Desktop/2026大创/dsh/42实验/_平台/index.html"
$prof = Join-Path $env:TEMP ("pp-shot-" + [guid]::NewGuid().ToString('N').Substring(0,8))
& $edge --headless=new --disable-gpu --hide-scrollbars --force-device-scale-factor=1 `
    --window-size=1600,1000 --virtual-time-budget=9000 --user-data-dir="$prof" `
    --screenshot="预览截图\v3_01-home-senior.png" "$page?still=1"
Remove-Item -Recurse -Force $prof      # 测完即删
```

> ⚠️ 用 `--screenshot` 命令行这种方式时，**页面被程序化滚动后再截图会得到空白图**（Edge headless 特性）。
> v3.1 的 `tools/screenshot.js` 改走 **CDP**，滚动之后截图正常（`v4_04` 就是滚到图集处截的），
> 并且会自动等「详情弹层已打开 + 图片加载完」再按快门。

### 5.1) v3.1 详情页验收截图（**推荐用脚本一次跑完**）

```bat
cd /d "42实验\_平台"
set NODE=C:\Users\13591\.dsh\dsh-runtimes\dsh-primary-runtime\dependencies\node\bin\node.exe
%NODE% tools\screenshot.js
```

脚本会：起一个 `--user-data-dir` 在 `%TEMP%` 的无头 Edge → 依次打开下面 7 个状态截图 →
回收 `#diag` 与 console / 未捕获异常 → **关闭浏览器并删掉临时 profile** →
把自检汇总写到 `预览截图/v4-shots.json`，控制台打印 `ok / checks / detail / 每张的 JS 报错数`。

| 文件 | 内容 | 打开的地址 |
| --- | --- | --- |
| `v4_01-detail-overview.png` | 详情-概览（已登录 + 有存档） | `?still=1&mockuser=student01&mockrecord=1#detail/exp6/overview` |
| `v4_02-detail-figures-lightbox.png` | 详情-效果图 + **lightbox 打开态** | `?still=1&mockuser=student01&mockrecord=1#detail/exp6/figures/1` |
| `v4_03-detail-flow.png` | 详情-流程（9 步 + 3 方案） | `?still=1&mockuser=student01&mockrecord=1#detail/exp6/flow` |
| `v4_04-detail-textbook-empty.png` | 详情-教材参考（要点卡 + 图集**空态**） | `?still=1&mockuser=student01&mockrecord=1#detail/exp6/textbook` |
| `v4_05-detail-guest-buttons.png` | 未登录：三个按钮「登录后可进入」 | `?still=1#detail/exp6/overview` |
| `v4_06-detail-mobile-800.png` | 移动 800px 宽 | `--window-size=800,1000` 等价：`Emulation 800×1000` |
| `v4_07-card-actions.png` | 卡片双按钮（查看详情 / 直接进入） | `?still=1&mockuser=student01&mockrecord=1` |

单跑一张：`%NODE% tools\screenshot.js --only 04-textbook`

### 5.2) v4 验收截图 + 重叠体检（`tools/verify.js`，**推荐**）

```bat
cd /d "42实验\_平台"
set NODE=C:\Users\13591\.dsh\dsh-runtimes\dsh-primary-runtime\dependencies\node\bin\node.exe
%NODE% tools\verify.js
```

与 `screenshot.js` 的区别：**起一个临时静态服务**（`127.0.0.1:8899`，随机端口兜底）——
`教材/index.json` 走 `fetch`，`file://` 下会被拦；这样图集才有图。脚本会：

1. 逐个打开 6 个状态截图（`--user-data-dir` 放 `%TEMP%`，跑完即删）；
2. 每个状态回收 `#diag`、`console` / 未捕获异常、`PP.Platform.checkDetailOverlap()`；
3. 再跑一遍**存档删除流程**（`window.confirm` 打桩，不弹窗）；
4. 汇总写 `预览截图/v5-shots.json`；**任何 JS 报错 / 任何重叠 / `diag.ok=false` 都以退出码 1 失败**。

| 文件 | 内容 | 打开的地址（1600×900，⑥ 为 800×1000） |
| --- | --- | --- |
| `v5_01-detail-two-buttons.png` | ① 详情页底部两个主按钮（有 3 个存档 → 继续可用） | `?still=1&mockuser=student01&mocksessions=1#detail/exp6/overview` |
| `v5_02-archive-list.png` | ② 存档列表弹窗（名称 / 角色 / 时间 / 进度 / 状态 + 删除 / 继续） | 同上 + 点「继续上次实验」 |
| `v5_03-textbook-fixed.png` | ③ 教材参考（工具栏 + 8 条要点卡，标题与正文不重叠） | `…#detail/exp6/textbook` |
| `v5_04-textbook-gallery.png` | ④ 教材图集有图态（docx2imgs 导入的 3 张扫描页） | 同上 + 滚到图集 |
| `v5_05-home-no-scaffold.png` | ⑤ 首页去脚手架后 | `?still=1&mockuser=student01&mocksessions=1` |
| `v5_06-mobile-800.png` | ⑥ 800×1000 教材参考（页签栏 / 内容区不重叠） | `Emulation 800×1000` + 同上 |

### 6) 自动化 / 调试钩子（**仅 `file://` 或 localhost 生效**）

| 钩子 | 作用 |
| --- | --- |
| `?service=<url>` | 临时覆盖平台服务地址（如 `http://127.0.0.1:1` 验证离线） |
| `?autologin=user:pass` | 免交互登录，用于截图 / 自检（需 `%3A` 转义冒号） |
| `?mockuser=admin\|teacher1\|student01` | 注入**无令牌**的模拟用户，仅用于在服务离线时验证账户中心空态与置灰 |
| `?mockrecord=1` | v3.1：给模拟用户塞 1 条实验记录（不写任何存储） |
| `?mocksessions=1` | v4：给 mock 用户写 3 条 `pp_sessions_<user>_exp6` 存档（学生端 / 教师端），复现存档列表；`=clear` 清除 |
| `?stage=junior\|senior` | 启动时直接进入指定学段（默认高中） |
| `?hover=exp6\|first` | 截图用：给目标卡片加 `is-hover`，模拟 hover 态 |
| `?still=1` | 截图用：关闭入场 / 弹层动画，拿稳定终态 |
| `?detail=exp6` / `?detail=exp6&detailtab=flow\|figures\|textbook` | 启动时直接打开详情页并切到指定 Tab |
| `?detail=exp6&lightbox=1` | 打开详情页并直接放大第 2 张效果图 |
| `#login` | 打开登录弹窗 |
| `#account` / `#account/quick` / `#account/account` | 打开账户中心并切到指定 Tab |
| `#detail/exp6` / `#detail/exp6/flow` / `#detail/exp6/figures/1` | 详情页深链接（`#detail/<id>/<tab>/<图下标>`，下标从 0 开始） |
| `#detailselftest` | 只跑一次详情页自检（结果写 `diag.detailCheck`） |
| `#stage/junior` / `#stage/senior` | 切换学段（与顶部按钮同一条路径） |
| `#stageselftest` | 学段切换自检：切过去再切回，把前后卡片数写进 `diag.stageSwitch` |
| `#selftest` / `#selftest-offline` | 功能自检 / 离线兜底自检 |
| `#expand-all` / `#exp6` | 展开全部目录 / 定位实验卡片 |

> 这些钩子只影响页面 UI 与自检，不会写入服务端；`mockuser` / `mockrecord` 不产生令牌、不做任何鉴权请求。

### 7) 详情页自检（`#diag` 里的 `detail` / `checks.detail*`）

平台**每次启动都会静默跑一次详情自检**（不弹窗、不打扰用户），结果写在 `#diag` 的 `detail` 对象里：

| 字段 | 期望（exp6） |
| --- | --- |
| `detail.subject` | `exp6` |
| `detail.tabs[]` | 四项 `overview / figures / flow / textbook` 全部 `visible: true`、`tabActive: true` |
| `detail.tabsSwitchable` | `true` |
| `detail.figures` | **6**（≥4 即通过） |
| `detail.flowSteps` | **9**（`flowDo: 5` 动手实验 + `flowBoard: 4` 白板讲解） |
| `detail.textbookPoints` | **8** 条要点卡 |
| `detail.textbookFigures` / `detail.textbookEmpty` | 导入图集后为 **3** / `false`；未导入时 `0` / `true`（空态文案存在） |
| `detail.textbookEmptyText` | 空态时含「暂无教材扫描件」+ `node tools/docx2imgs.js 课本.docx exp6` 提示 |
| `detail.textbookIndex` | `state: "ready"`、`via: "json"`（http）或 `"js"`（`file://` 读 JSONP 镜像）、`figures / rendered` = 渲染张数 |
| `detail.urls.fresh / resume` | fresh 含 `auto=1&from=platform&fresh=1`；resume 含 `resume=1`，有存档时还含 `session=` |
| `detail.urlChecks` | `auto / resume / fresh / fromPlatform` 均为 `true`；有存档时 `session: true` |
| `detail.buttons` | v4：`twoButtons: true` + `resume{label,disabled,count,url}` + `fresh{label,disabled,url}` |
| `detail.archive` | `key`（`pp_sessions_<用户>_exp6`）/ `count` / `rows[]`（名称·角色·时间·进度·状态）/ `modalOpenable` / `emptyTip` |
| `detail.overlaps` | v4 重叠体检汇总：`viewport` / `ok` / `perTab[]`（每个 Tab 比对了多少对元素、几处重叠） |
| `detail.cardActions` | `detail: true` + `enter: true` + `cardClickable: true` |
| `detail.open` / `activeTab` / `lightbox` | 当前是否打开、当前 Tab、lightbox 状态（打开时才为 `true`） |
| `checks.detail*` | 以上各项的布尔汇总，全部参与 `diag.ok` |

### 7.1) 重叠体检（v4，`getBoundingClientRect`）

`checks.detailNoOverlap` 的算法（`platform.js → checkDetailOverlaps / measureDetailOverlaps`）：

1. 详情弹层关闭时，临时 `hidden=false + visibility:hidden` 让它完成布局（看不见、不闪）；
2. 逐个 Tab 收集 `头部 / 页签栏 / 内容区 / 小节标题 / 要点卡 / 标题 / 正文 / 空态卡 / 图集` 等
   元素（`OVERLAP_SELECTOR`），各自取 `getBoundingClientRect()`，并**按滚动容器裁剪**；
3. 两两比较（跳过祖先-后代），交叠区域宽高都 ≥ 2px 才算「重叠」；
4. 结果写 `detail.overlaps.perTab[]`，`ok` 要求**四个 Tab 全部 0 处重叠**。

在浏览器控制台随时可以手动跑：

```js
PP.Platform.checkDetailOverlap()            // 四个 Tab 全量
PP.Platform.measureDetailOverlaps('textbook')  // 只量某个 Tab
```

v4 在 **1600×900 与 800×1000** 下都实测 0 重叠（见 `预览截图/v5-shots.json` 的 `overlapAll`）。

---

## 八、已知限制

- 平台只读实验目录，不修改 / 不复制实验文件；**实验页 / 后台页的 `?token/auto/resume/fresh` 读取逻辑需对方实现**
  （见第四节；实验 6 的 `cloud.js` 已支持 `sessionStorage.pp_token`，跨源场景需补 URL 参数读取）。
- **初中为骨架数据**：20 个实验全部 `status:"todo"`、`path:""`，等对应仿真页上线后改这两项即可；初中学段暂无已上线实验，
  因此主卡置灰、卡片显示「待上线」，账户中心的历史记录也只对应高中实验。
- 记录与「继续」目前只对应已上线实验（当前仅 `exp6`）；`record.meta.experiment` 与清单按名称匹配，
  匹配不到时回退到当前学段首个已上线实验。
- 学段切换只渲染当前学段的数据（`S.index` 也只含当前学段），因此跨学段的历史记录名会退化为记录里的实验名文本。
- `file://` 下 `sessionStorage` 在不同文件间不一定共享，因此令牌以 URL 参数为准（平台两路都做了）。
- 报告 `reportHTML` 按原样渲染在沙箱 iframe 中（不执行脚本）；若后端返回的是片段，平台会补一层浅色排版。
- 缩略图字段 `thumb` 不再使用（统一 SVG 徽标 / 首字色块），保留字段以兼容旧清单。
- 平台服务当前仍由实验 6 的 `server/` 提供；未来合并为统一学科服务时只改 `experiments.json → meta.serviceBase` 即可。
- 无头截图：旧的 `--screenshot` 命令行方式在程序化滚动后会得到空白图（Edge headless 特性）；
  v3.1 的 `tools/screenshot.js` 走 CDP，滚动后截图正常。
- **详情页 / 教材图集的限制**：
  - `file://` 下 `fetch('教材/index.json')` 被浏览器拦截 → 平台自动改读 `教材/index.js`
    （JSONP 镜像，由 `docx2imgs.js` 生成）；两个都没有时按空图集显示，页面不报错。
    用静态服务打开则直接读 `index.json`。
  - 详情内容全部来自 `experiments.json` 的 `detail` 字段；只改 JSON 时如果继续用 `file://` 打开，
    记得跑 `node tools/sync-fallback.js`，否则看到的是兜底副本里的旧文案。
  - **「继续上次实验」只读实验端写在 `localStorage` 的存档**（`pp_sessions_<用户名>_exp6`）：
    换了浏览器 / 清了站点数据 / 换了账号都看不到；平台不新建存档，也不改实验进度。
  - `?mockuser=` 模拟用户默认没有存档（需要时加 `?mocksessions=1`）。
  - 详情弹层不拦截浏览器返回键（无路由），要「返回」请用关闭按钮 / `Esc` / 遮罩。
- **`docx2imgs.js` 的限制**：只支持 `.docx`（zip），不支持 `.doc` / ZIP64；只取 `word/media/` 下的
  `png/jpg/jpeg`（EMF/WMF 矢量图、Word 里未插入的图片都取不到）；输出保留原图字节，**不做压缩或转格式**。

---

## 九、版本记录

| 版本 | 日期 | 说明 |
| --- | --- | --- |
| v4.0 | 2026-11-21 | **详情页两分流 + 多存档**：底部改为「继续上次实验 / 新建实验」两个主按钮（去掉单独的「进入实验」「重新开始」）；「继续上次实验」弹**存档列表**（读实验端 `localStorage` 的 `pp_sessions_<用户名>_exp6`，每条显示名称 / 角色 / 保存时间 / 进度「第 N 步 / 第 N 环节」/ 状态，可选中进入 `…&resume=1&session=<id>`、可确认删除，无存档置灰并提示「暂无存档，可新建实验」）；新增 `?mocksessions=1` 演示钩子。**课本 Word → 教材图集**：新增零依赖 `tools/docx2imgs.js`（手工解析 zip 中央目录 + `zlib.inflateRawSync`，按文档出现顺序导出 `教材/<expId>/pN.png`，自动更新 `教材/index.json` 与 JSONP 镜像 `教材/index.js`，`file://` 下也能看图集）。**UI**：修复教材参考页签的重叠（头部/页签栏/操作条不参与收缩、页签栏 z-index、小节标题换行、要点卡标题与正文间距），新增 `getBoundingClientRect` 重叠体检 `checks.detailNoOverlap`；去掉 hero 长说明 / 右侧面板长解释 / 登录弹窗演示账号多行提示 / 详情页「登记格式」示例（移到 README）/ 账户中心「将打开的地址」面板。新增 `tools/verify.js`（静态服务 + CDP + 6 张 v5 截图 + 重叠体检 + 存档删除流程） |
| v3.1 | 2026-11-21 | **实验详情页**：点卡片（非按钮区）/「查看详情」打开全屏详情弹层——概览（介绍 + 为什么做 + 你会得到什么）/ 效果图（6 张真实仿真截图 + lightbox ←/→/Esc）/ 流程（9 步横向步骤条，标注动手实验·白板讲解，+ 3 个方案）/ 教材参考（8 条要点卡含页码占位 + 教材扫描件图集，可打印/另存 PDF）；底部固定操作条「进入实验 / 继续上次实验 / 重新开始 / 关闭」，未登录显示「登录后可进入」；进入参数新增 `from=platform`（`buildDetailURL()`）；卡片按钮改为「查看详情 + 直接进入」；`experiments.json` 新增 `detail` 字段（exp6 完整、其余走通用占位）；新增 `教材/index.json` 模板与 `教材/exp6/`；`#diag` 新增 `detail` 与 6 项 `checks.detail*`；新增 `tools/screenshot.js`（CDP 零依赖出图 + 回收自检）；README 增加「教材扫描件怎么用 / 改详情文案」 |
| v3.0 | 2026-11-21 | 视觉改版（蓝白明亮风 / 渐变主卡 / 2 列实验卡片 / 毛玻璃顶栏 / 目录树高度过渡 / 克制动效与 `prefers-reduced-motion`）；**多学段**（顶部初中-高中切换，按 `stages[]` 渲染，初中 20 个实验骨架）；平台文案改为「中学物理实验仿真平台」；去脚手架说明文字、新增「我的」快捷入口与空态插画；实验 / 后台入口统一携带 `?token=…&auto=1`；自检新增 `stage/stages/stageSwitch` 与 `#stageselftest` |
| v2.0 | 2026-11-21 | 视觉重做（深色科技风 / 卡片 / 30% 留白 / 统一 18px 圆角）；平台内直接登录（三角色）；账户中心（实验历史 + iframe 报告 + 改密 + 快捷进入）；实验入口 `token/auto/resume/fresh` 传参；手写 SVG 双 Logo；离线兜底与 `#selftest` 自检 |
| v1.0 | 2026-11-21 | 平台外壳首版：6 册 / 17 章 / 21 实验骨架，三级目录、卡片、服务探测、兜底数据、`#diag` 自检 |
