71 lines
6.3 KiB
Markdown
71 lines
6.3 KiB
Markdown
# R1 落地一致性审查报告（策划，R2 轮）
|
||
|
||
> **档案带（26 号之后）**：本文记录 R1 实现与当时设计的出入，工程裁定（haptics 文件名、voice 平铺回退、`_settings`）仍有效。**手势宪法、只靠震动做反馈、向导接线已由 00/26 号废止**，勿再当施工依据。
|
||
|
||
审查对象：`docs/web-engine-api.md`（R1 变更）、`docs/audio/round1-report.md`、
|
||
`web/index.html`（大厅新 UI）、`web/engine/{settings,haptics,audio}.js`、`web/server/server.js`。
|
||
对照基准：`docs/design/00-global-ux.md`（设计规范初稿）。
|
||
|
||
**总体结论：R1 落地质量高，核心语义全部符合设计。发现 6 处出入，均已裁定"以谁为准"；
|
||
00-global-ux.md 已按本报告完成修订（R2 修订版），后续各轮以修订版 00 文档为唯一基准。**
|
||
|
||
---
|
||
|
||
## 出入清单与裁定
|
||
|
||
### 1. 震动模块命名与震型表 —— 以实现为准
|
||
|
||
- 设计：`engine/vibrate.js`，常量 `VIB.CONFIRM/ERROR/...`（大写），9 种震型。
|
||
- 实现：`engine/haptics.js`，`HAPTIC_PATTERNS` 小写命名（`confirm/error/success/warning/swipe/heartbeat`），6 种预定义 + 自定义数组调用；数值微调（error=[60,40,60] vs 设计 [40,60,40]；warning=[30,50,30,50,30] vs [30,40,...]）。
|
||
- **裁定：以实现为准。** 数值差异在感知阈内。设计侧 PICKUP/HIT/BEAT/DANGER 四种语义震型引擎未预定义——**R3 起游戏层先用自定义数组（[15,40,15]/[80]/[8]/[20,50,30,50,40]），建议引擎 R3 补为预定义**（请开发排期）。
|
||
- 00 文档 §2 已修订。
|
||
|
||
### 2. gesture.js 内置基础震动 —— 以实现为准，设计规范随之修订
|
||
|
||
- 实现：滑动识别成功自动 `swipe`、tap/doubletap 自动 `confirm`（web-engine-api.md:222-224 已写明"游戏层不要重复调用，否则双重震动"）。
|
||
- 设计初稿要求游戏层对"滑动生效/确认"调 SWIPE_OK/CONFIRM——按实现会导致双重震动。
|
||
- **裁定：以实现为准。** 震动分工：手势识别反馈=引擎内置；语义事件（error/success/warning/PICKUP/HIT/BEAT/DANGER）=游戏层。00 文档 §2.3 已修订，01/02/04/05 各篇中"单击确认给 CONFIRM 震动""滑动给 SWIPE_OK"的表述按此映射理解，不逐一改文。
|
||
|
||
### 3. voice 资产回退逻辑 —— 以实现为准（比设计更优）
|
||
|
||
- 设计：`voice/<gender>/` 缺失时回退另一性别。
|
||
- 实现：`voice/<gender>/` → 回退**平铺** `voice/<id>`（web-engine-api.md:145-148），不做性别回退。
|
||
- **裁定：以实现为准。** 音频总监已保证两性别 id 集合一致（round1-report §1），性别回退无必要；平铺回退恰好解决 storyline 角色台词（单音色）的加载问题，设计更简洁。00 文档 §1.1 已修订。
|
||
- 附带确认：voice 缓存键带性别前缀（audio.js:239），运行时切换性别不会串缓存——处理正确。
|
||
|
||
### 4. 设置值格式与服务器同步形式 —— 以实现为准
|
||
|
||
- 设计：speed/bgm 字符串枚举（"normal"/"fast"/"veryfast"）；独立 `/api/settings` 端点。
|
||
- 实现：数值（1.0/1.35/1.7、1.0/0.3/0），`settings.js` 非法值逐项丢弃；设置走进度接口保留键 **`game='_settings'`**（index.html:288）。
|
||
- **裁定：以实现为准。** `_settings` 为全局保留键，任何游戏存档不得占用（00 §4.3 已写明）。数值格式更利于引擎直接乘算。
|
||
- speed 生效时机为"下一句起"（audio.js:343，创建 source 时读值）——可接受，文档已注明；正在播放的长句不变速不算问题（句子均 ≤25 字短句）。
|
||
|
||
### 5. 进度 API 形态与存档信封 —— 以实现为准
|
||
|
||
- 设计：`GET/PUT /api/progress/<game>` 路径段 + 统一信封 `{schema, game, updatedAt, data}`；token 存 `soundgame.token`。
|
||
- 实现：`GET /api/progress?game=xxx`、`PUT {game, data}`；data 自由格式（服务器不校验）；token 存 `soundgame.auth`（含 username）；大厅卡片约定读 **`data.summary`** 字符串。
|
||
- **裁定：以实现为准。** 游戏侧 `data` 内仍建议自放 `schema`/`updatedAt` 字段（便于迁移），`summary` 为**必须**（RPG 存档结构已按此定义，05-rpg-chapter1.md §6）。00 文档 §4 已修订。
|
||
|
||
### 6. 各游戏默认音色性别 —— 以实现为准（全局统一默认 female）
|
||
|
||
- 音频总监建议（round1-report §5.3）：按游戏默认原音色性别（storyline/escape=male，其余=female）。
|
||
- 实现：全局单一设置项，默认 female，不分游戏。
|
||
- **裁定：以实现为准。** 全局单项更符合"设置系统"的用户心智（用户选一次全合集生效）；各游戏原音色差异已由双性别资产覆盖，用户可自切。此条无需改动，仅记录在案。
|
||
|
||
## 需要转达的事项
|
||
|
||
1. **给引擎开发**：R3 请在 `haptics.js` 补 4 个预定义震型：`pickup=[15,40,15]`、`hit=[80]`、`beat=[8]`、`danger=[20,50,30,50,40]`（R3 节奏游戏与 R5 RPG 都要用；未补前游戏层传自定义数组，不阻塞）。
|
||
2. **给音频总监**：
|
||
- R3 录制依据 `docs/design/03-rhythm-voice-ids.md`（31 句 ×2 性别，rhythm 旁白 female=Vivian/male=Uncle_Fu 沿用 R1 分配；grade_*/restart 为重录覆盖）。
|
||
- R4 录制依据 `docs/design/05-rpg-ch1-voice-ids.md`（旁白 104×2 + NPC 16 平铺单音色；黑风寨主与村长同为 Uncle_Fu 不同 instruct，请优先试听这两条确认区分度，若混淆寨主改 Dylan 阴狠 instruct）。
|
||
- Mureka/SA3 需求：`docs/design/05-rpg-chapter1.md` §7（5 BGM + 35 sfx，含英文 prompt 草稿）与 03-rhythm-rebuild.md §8.4（3 首 BGM 重做 + 7 个乐器音）。
|
||
3. **给大厅/UI 开发**：设置变更后的试听句（00 §1.2）列为 R3 打磨项，非阻塞。
|
||
4. **资产清理**：平铺旧 voice 文件待 R2 各游戏切换验证完成后由音频侧清理（round1-report §5.4 已排）。
|
||
|
||
## 无出入确认项（抽查通过）
|
||
|
||
- 音频解锁流程、三层架构、onComplete 打断语义未变，设计文档依赖的契约完好。
|
||
- bgm=0 时 `_playBgm` 短路不加载——与设计"不是静音播放"一致。
|
||
- simon BGM 资产已删除（round1-report §5.2），与 02 文档一致；game.js 的 bgm 引用移除属 R2 开发任务。
|
||
- 服务器安全声明（局域网玩具级、PIN 明文）已在 web/server/README.md 显著标注，符合家庭内网定位，设计无异议。
|