mini-zmc/docs/ONE_WEEK_MVP_PLAN.md

藏猫猫计划：一周 MVP 设计与实施规划书

版本：1.0
周期：7 天
目标形态：微信小程序可演示 MVP
规划日期：2026-07-27

1. 项目目标

在一周内交付一个能够在微信开发者工具和真机上稳定运行的小程序，让一名用户无需后端、无需真实好友在线，即可完整体验：

创建/加入房间 → 候场 → 身份分配 → 准备倒计时
→ 正式追逃 → 技能/线索/口令抓捕 → 自动结算 → 再来一局

本周期的核心不是上线真实多人服务，而是完成一个流程闭环、规则清楚、状态可靠、适合演示和用户访谈的产品版本，为下一阶段熟人多人内测提供依据。

1.1 成功标准

• 新用户能在 2 分钟内创建或加入一局游戏。
• 单人在模拟玩家辅助下可以走完全部游戏流程。
• 经典模式和感染模式均能正确完成身份、抓捕与结算。
• 页面刷新、前后台切换后，当前房间和游戏状态可以恢复。
• 关键错误有明确提示，不出现无法继续操作的死路。
• 安全规则在创建、候场和游戏过程中均有可见入口。
• 核心流程通过开发者工具和至少 1 台真机验证。

2. 本周范围

2.1 必须交付（P0）

1. 首页

   • 创建游戏、加入房间、安全规则入口。
   • 继续上一场未完成游戏。

2. 创建游戏

   • 房间名称、游戏模式、时长、准备时间、人数、寻找者数量、线索间隔、场地半径和技能开关。
   • 基础参数校验和安全承诺。

3. 加入与候场

   • 六位房间码和演示房间。
   • 昵称确认、房间预览、模拟玩家补充。
   • 玩家准备、房主开局、规则摘要和邀请入口。

4. 游戏主流程

   • 准备阶段与正式游戏阶段。
   • 寻找者/躲藏者差异化界面。
   • 周期性模糊线索、雷达、静默和四位抓捕口令。
   • 经典模式淘汰和感染模式转化。
   • 超时或全部抓捕后的自动结算。

5. 结算与复玩

   • 获胜阵营、玩家表现、抓捕数和参与结果。
   • 按原规则再来一局、返回首页和分享入口。

6. 稳定性与体验

   • 本地数据异常时的兜底处理。
   • 防止重复开局、重复结算和重复抓捕。
   • 页面卸载时清理计时器。
   • 空状态、按钮禁用态和错误提示。

2.2 尽量完成（P1）

• 游戏暂停与继续。
• 房主提前结束游戏。
• 模拟玩家自动产生少量抓捕或事件，使躲藏者视角也能完成演示。
• 技能冷却或剩余次数展示。
• 结算称号根据实际数据生成。
• 简单的游戏历史记录。

2.3 本周不做

• 微信正式登录和账号体系。
• 多设备实时房间同步、WebSocket 和断线重连。
• 真实地图选区、定位上报和地理围栏。
• 服务端动态口令、距离验证及完整防作弊。
• 附近陌生人组局、聊天、商城、积分和排行榜。
• 运营后台、举报审核和复杂未成年人体系。
• 正式发布所需的完整隐私合规与安全备案工作。

上述能力不能用前端模拟结果包装为真实能力。界面中涉及位置和防作弊的内容应明确标注为原型演示。

3. 用户与业务设计

3.1 核心用户

• 房主：配置规则、组织玩家、开始和结束游戏。
• 普通玩家：加入房间、准备、获得身份并参与游戏。
• 演示用户：单人使用模拟队友验证全部流程。

3.2 核心状态机

房间状态：

waiting → preparing → playing → paused（可选） → finished

玩家状态：

idle ↔ ready
ready → hiding / seeking
hiding → caught（经典模式）
hiding → seeking（感染模式）

必须遵守的状态规则：

• 只有 waiting 状态允许加入和切换准备。
• 至少 4 名玩家且寻找者少于总人数时才允许开局。
• 只有 preparing 可以进入 playing。
• 只有 playing 可以使用技能和提交抓捕。
• finished 后不再接受任何游戏操作。
• 重开时清空角色、抓捕、技能和计时数据，但保留房间设置与玩家。

3.3 胜负规则

• 经典模式：全部躲藏者被抓，寻找者胜；倒计时结束仍有躲藏者，躲藏者胜。
• 感染模式：被抓者转为寻找者；最后一个躲藏者被转化后寻找者胜；倒计时结束仍有人存活则躲藏者胜。

4. 技术设计

4.1 本周架构

微信小程序页面 pages/*
        ↓
本地领域服务 services/game-service.js
        ↓
wx Storage（房间、玩家、事件、结果）

继续使用原生 JavaScript，不新增 npm 依赖，不在一周期限内引入后端。页面不得直接修改房间对象，所有业务状态变化统一经过游戏服务，以便后续替换为云函数或 HTTP API。

4.2 模块职责

• pages/*：页面展示、用户输入、导航和生命周期管理。
• services/game-service.js：房间状态机、角色分配、技能、抓捕、结算和持久化。
• utils/constants.js：模式、默认规则、演示数据和枚举。
• utils/format.js：倒计时、时间和通用数据处理。
• wx Storage：保存当前版本的房间快照和当前房间索引。

4.3 本周重点改造

1. 将所有操作增加房间状态和角色权限校验。
2. 为房间增加数据版本或 schema 版本，避免旧缓存导致页面崩溃。
3. 让线索间隔使用创建时配置；演示加速通过独立配置控制。
4. 将技能使用次数保存到房间玩家数据，而不是只存在页面内存。
5. 抓捕时明确目标，或在演示模式中明确提示“当前模拟目标”。
6. 将动态口令绑定目标和时间窗口，至少在本地实现定时变化与重复使用限制。
7. 统一使用 phaseEndsAt 计算倒计时，恢复页面时不重新开始计时。
8. 结算形成稳定快照，防止当前时间变化造成排名变化。
9. 限制事件数量，并区分全员、寻找者和个人可见事件。
10. 为不存在、损坏或已经结束的房间提供恢复路径。

4.4 为后端演进预留的接口

页面层保持以下语义接口：

• createRoom(payload)
• getRoom(code)
• joinRoom(code, player)
• toggleReady(code, playerId)
• startGame(code)
• useSkill(code, skill)
• capture(code, credential)
• pauseGame(code) / resumeGame(code)
• finishGame(code, reason)
• resetRoom(code)

下一阶段可将接口内部替换为云函数或网络请求，而无需重写页面流程。

5. 一周实施排期

第 1 天：范围冻结与主流程体检

状态：已完成（2026-07-27）

• 冻结 P0 范围和验收清单。
• 按现有代码和模拟运行完整走查创建、加入、候场、开局、技能、抓捕、结算与复玩流程。
• 记录创建、加入、开局、技能、抓捕、结算和复玩的缺陷。
• 梳理房间与玩家状态字段，补充缺省值和兼容策略。
• 建立本地游戏服务基线测试。
• 产出缺陷清单、状态模型和可稳定启动的基线版本。

第 1 天实施结果：

• 房间数据初始新增 schemaVersion；第 4 天因技能和口令状态扩展已升级为 schemaVersion: 2。
• 启动时自动补齐旧缓存中的房间设置、玩家字段、事件字段和时间字段。
• 非对象顶层缓存、无效房间和非法房间码会被安全忽略或清理。
• 缺失或非法的房间/玩家状态会回退到有效状态，避免页面直接崩溃。
• 事件历史统一限制为最近 20 条。
• 新增本地服务回归测试，覆盖旧数据迁移、损坏缓存、完整游戏流程和复玩重置。

主流程体检缺陷清单：

编号	优先级	模块	问题	计划处理
D1-01	P0	创建/开局	创建时可能出现寻找者数量不小于人数上限	已完成（第 2 天）
D1-02	P0	候场	普通房间开局未校验房主权限和全员准备状态	已完成（第 2 天）
D1-03	P0	状态机	重复开局、重复结束等状态迁移保护不足	已完成（第 3 天）
D1-04	P0	计时	线索固定为 15 秒，未使用房间配置	已完成（第 3 天）
D1-05	P0	技能	技能使用状态只在页面内存中，重新进入后可重复使用	已完成（第 4 天）
D1-06	P0	抓捕	口令不随时间变化，且无法选择明确目标	已完成（第 4 天）
D1-07	P0	抓捕	抓捕发起者角色校验不足	已完成（第 4 天）
D1-08	P1	结算	同分排名使用当前时间参与比较，结果可能变化	已完成（第 5 天）
D1-09	P1	安全	安全退出弹窗未真正更新玩家或房间状态	已完成（第 5 天）
D1-10	P1	演示	躲藏者视角缺少自动事件，单人演示难以自然结束	第 5 天（有余量时）

说明：微信开发者工具和真实设备上的视觉、震动、分享及前后台能力仍按第 6 天计划执行真机验收；第 1 天完成的是代码路径走查与本地服务模拟回归。

第 2 天：创建、加入与候场

状态：已完成（2026-07-27）

• 完善创建参数校验，处理寻找者数量与人数上限冲突。
• 完善无房间、房间已满、已开局、已取消和已结束提示。
• 修复准备状态、房主权限和开局条件。
• 确保分享参数和演示房间可进入。
• 扩充创建、加入与候场服务回归测试。
• 产出从首页到成功开局的稳定链路。

第 2 天实施结果：

• 创建房间由服务层统一校验名称、模式、游戏时间、准备时间、人数上限、寻找者数量、线索间隔和活动半径。
• 寻找者数量必须小于人数上限；页面切换人数上限时会自动调整冲突选项。
• 六位码格式错误、房间不存在、房间已满、游戏已开始、已结束或已取消分别显示明确提示。
• 只有房主可以开始普通房间；演示房间保留当前用户代操作能力。
• 开局前统一校验至少 4 人、寻找者少于当前玩家数以及所有玩家已准备。
• 游戏开始后禁止继续修改准备状态或重复开始。
• 通过分享卡片携带的 code 参数仍可直接预览并加入；演示房间加入者自动准备，保证单人演示链路可启动。

第 3 天：游戏状态机与计时

状态：已完成（2026-07-27）

• 加固 waiting → preparing → playing → finished 状态迁移。
• 统一阶段时间和页面恢复逻辑。
• 使用规则配置驱动正式线索间隔，同时保留独立的演示加速配置。
• 处理前后台切换、页面重复进入和重复结算。
• 扩充状态迁移及正式/演示计时回归测试。
• 产出可靠运行的准备阶段和正式游戏倒计时。

第 3 天实施结果：

• 开始、进入追逃、线索广播、技能使用和结束游戏均增加合法房间状态校验。
• 禁止重复开局、重复进入追逃阶段、非游戏阶段广播线索以及重复结算。
• 房间新增独立 runtime 配置；当前本地 MVP 明确启用演示加速，不再把加速数值散落在业务代码中。
• 关闭演示加速后，准备时长、游戏时长和线索间隔均严格使用创建房间时的分钟配置。
• 阶段切换以原定 phaseEndsAt 作为下一阶段开始时间；应用回到前台时可以补算真实经过时间，不会重新开始倒计时。
• 游戏页进入后台时停止本地轮询，回到前台立即恢复并校准状态，避免重复计时器。
• 演示模式保持准备分钟按秒压缩、正式游戏最长 180 秒、线索每 15 秒一次，便于单人快速走查。

第 4 天：身份、技能与抓捕

状态：已完成（2026-07-27）

• 验证不同人数和寻找者配置下的角色数量合法性。
• 完成经典/感染两种抓捕行为。
• 技能次数持久化，技能关闭时隐藏入口。
• 改造本地动态口令的目标绑定、时效与重复使用限制。
• 补充寻找者和躲藏者两种视角及权限走查。
• 扩充身份、技能、抓捕与模式分支回归测试。
• 产出可重复验证的核心玩法闭环。

第 4 天实施结果：

• 玩家新增持久化的 skillsUsed 和 silentPending；重新进入页面后仍能识别技能已使用，重开房间时统一清零。
• 本局关闭技能时不展示技能入口；开启技能时每名玩家每局只能使用一次对应身份技能。
• 寻找者只能使用雷达，仍在躲藏的玩家只能使用静默；被抓或状态异常的玩家不能使用技能。
• 寻找者抓捕前必须明确选择一名仍在躲藏的目标；躲藏者页面只显示属于自己的口令。
• 四位口令绑定房间、目标玩家和 30 秒时间窗，到期自动变化。
• 已使用口令保存在房间数据中并限制最近 50 条，不能重复提交。
• 抓捕接口校验发起者必须是 seeking 状态的寻找者，目标必须是 hiding 状态的躲藏者。
• 经典模式下目标转为 caught 并进入观战提示；感染模式下目标转为 seeker/seeking 并继续参与。
• 最后一名躲藏者被抓后仍自动结算为寻找者胜利。

第 5 天：结算、安全与异常流程

状态：已完成（2026-07-27）

• 固化胜负判断、排名和结果文案。
• 完善再来一局的数据重置。
• 补充暂停/继续、安全退出、提前结束及异常操作提示。
• 检查并收紧敏感信息在错误角色界面的展示。
• 扩充暂停、退出、权限、结算快照和重开回归测试。
• 产出可以收口的正常流程和主要异常流程。

第 5 天实施结果：

• 游戏结束时生成不可变 resultSnapshot，固定玩家排名、初始/最终身份、抓捕数、存活时间、实际用时和事件数量。
• 排名依次按抓捕数、存活时间、加入时间和玩家 ID 排序，不再依赖打开结果页时的当前时间。
• 感染模式战报可展示“躲藏者→寻找者”，避免只展示最终角色造成误解。
• 再来一局会清理阶段计时、暂停信息、口令使用记录、技能、抓捕、角色和结算快照，同时保留房间规则与玩家。
• 房主可以暂停和继续游戏；暂停期间游戏倒计时与下一次线索倒计时均冻结。
• 房主可以确认后提前结束并生成战报；非房主不能执行暂停、继续或提前结束。
• “安全退出”会实际把玩家标记为 quit、清除当前房间入口并记录安全事件；最后一名躲藏者退出时自动结算。
• “联系房主”在原型阶段明确提示使用约定的电话或微信，不伪造即时通讯能力。
• 静默事件不再公开具体使用者姓名；躲藏者仍只看到自己的口令，寻找者的演示口令入口仅在明确的演示加速模式展示。

第 6 天：体验打磨与真机测试

状态：功能实现与代码检查已完成（2026-07-27）；真机人工验收待连接设备执行

• 统一加载态、空状态、禁用态、Toast 和弹窗文案。
• 完成小屏、长昵称、人数上限和事件列表的代码侧适配。
• 增加页面 WXML 事件与 JS 方法绑定契约检查。
• 防止创建、加入、开局、抓捕和复玩重复提交。
• 形成震动、分享、剪贴板、前后台切换和本地缓存真机验收清单。
• 在微信开发者工具和真机执行清单（需要人工连接真实设备）。
• 代码侧未发现阻塞级与高优先级缺陷。
• 产出候选演示版本代码。

第 6 天实施结果：

• 加入页会在输入完整房间码后展示明确的不存在、已满、已开始、已结束或已取消状态，并只在允许加入时启用按钮。
• 创建、加入、开局、抓捕和复玩增加提交中状态，防止快速重复点击。
• 候场、游戏和战报页面在房间数据丢失时不再白屏，统一显示说明和返回首页入口。
• 游戏事件为空时展示空状态；已取消的当前房间不会继续出现在首页。
• 房间码复制成功后提供明确反馈。
• 候场玩家昵称和战报昵称增加单行省略，房间名允许安全换行；游戏头部增加小屏适配。
• 三个安全管理按钮重新布局，避免第三个按钮挤压。
• 新增页面绑定契约测试，自动检查 WXML 引用的事件处理函数是否在对应页面 JS 中存在。
• 新增独立真机验收清单 docs/DEVICE_TEST_CHECKLIST.md，覆盖双端屏幕、震动、分享、剪贴板、前后台、快速点击和安全权限。

限制说明：当前执行环境无法启动微信开发者工具或连接用户真机，因此不能把真机清单虚假标记为通过。完成清单后才可将第 6 天整体状态更新为“全部验收完成”。

第 7 天：回归、演示与交付

状态：代码与交付材料已完成（2026-07-27）；微信开发者工具及真机发布门禁待人工执行

• 按验收用例执行游戏服务、页面契约和发布就绪自动回归。
• 在模拟 Storage 中清理缓存并验证首次启动、演示数据补种和完整流程。
• 准备 5 分钟演示脚本和已知限制说明。
• 更新项目导入、自动检查和运行文档。
• 将 MVP 版本冻结为 0.1.0-mvp。
• 整理下一阶段多人化进入条件。
• 产出测试报告、演示说明、版本说明和后续清单。
• 在微信开发者工具完成最终编译并执行真机发布门禁（需要人工连接设备）。

第 7 天实施结果：

• 新增统一自动回归入口 node tests/run-all.js。
• 新增发布就绪检查，验证小程序页面注册、页面四件套文件、项目类型、版本号和交付文档完整性。
• 自动回归结果为游戏服务、页面事件契约、发布就绪检查全部通过。
• app.globalData.version 固定为 0.1.0-mvp，README 同步标注版本用途和安全边界。
• 新增 5 分钟演示脚本，覆盖定位说明、创建、候场、核心玩法、安全管理、结算和复玩。
• 新增测试报告，明确自动覆盖范围、未覆盖的微信运行时能力和发布判断。
• 新增版本说明，集中记录已交付能力、已知限制和下一阶段进入条件。
• 当前版本可用于单设备产品演示和用户访谈，不允许描述为可直接承载真实多人户外活动的生产版本。

自动回归结果：

game-service tests passed
page contract tests passed
release readiness tests passed
all automated checks passed

最终发布门禁：完成 docs/DEVICE_TEST_CHECKLIST.md 后，才可将第 6、7 天的设备验收项标记为完成，并决定是否交付真机演示。

6. 验收用例

6.1 主流程

1. 用户创建感染模式房间，模拟玩家补足至可开局人数。
2. 房主开始游戏，系统正确分配指定数量的寻找者。
3. 准备倒计时结束后自动进入正式追逃。
4. 寻找者使用雷达并通过有效口令完成抓捕。
5. 被抓躲藏者转化为寻找者，人数统计同步变化。
6. 最后一名躲藏者被抓后自动进入寻找者胜利结算。
7. 用户按原规则重开，所有本局数据正确清零。

6.2 分支流程

• 经典模式中被抓者保持被抓状态，不转为寻找者。
• 游戏超时且仍有存活者时，躲藏者获胜。
• 技能关闭时不能使用雷达或静默。
• 错误、过期或已使用口令不能完成抓捕。
• 非房主不能开始或提前结束普通房间。
• 不足 4 人、寻找者数量非法时不能开始。

6.3 恢复与异常

• 关闭并重新进入小程序后可以继续当前房间。
• 游戏页面退出再进入后倒计时基于原结束时间恢复。
• 房间数据不存在或损坏时返回首页并给出提示。
• 快速重复点击开始、抓捕和结束不会产生重复结果。
• 房间结束后不能继续使用技能或提交抓捕。

7. 质量要求

• P0 流程无阻塞级缺陷。
• 页面 JS 无未捕获异常，WXML 无明显渲染警告。
• 核心按钮在常见手机尺寸下可见且易于单手点击。
• 重要操作有文字反馈，关键阶段变化可配合震动。
• 本地房间事件限制数量，避免数据无限增长。
• 所有演示能力与真实能力边界清晰，不误导测试用户。

8. 人力与协作建议

按 1 名熟悉微信小程序的开发者估算，一周可完成本规划中的 P0；P1 仅在 P0 提前完成时进入。建议每天结束前进行一次 20～30 分钟的完整流程回归，不将全部测试集中到最后一天。

如果有第二名成员，优先分工如下：

• 开发者：状态机、页面逻辑、数据兼容和缺陷修复。
• 产品/测试：规则确认、真机用例、文案、安全流程和演示材料。

9. 风险与应对

风险	影响	应对方式
一周内加入真实多人同步	架构和联调工作不可控	本周固定使用本地模拟，下一阶段单独建设后端
原型时间压缩与正式规则混杂	测试结果失真	增加明确的演示加速配置，不直接改业务规则
页面直接依赖本地数据结构	后续迁移成本增加	状态变更统一收口到服务层
动态口令被误认为安全机制	产生错误安全预期	明确标注本地演示，正式版必须服务端校验
真机能力验证太晚	最后一天出现兼容问题	第 3 天开始至少每天一次真机回归
持续增加玩法	核心闭环无法按时稳定	P0 冻结，新增需求统一进入下一版本

10. 交付物

• 可导入微信开发者工具并正常编译的小程序源码。
• 可单人完成全流程的经典模式与感染模式。
• 演示房间和模拟玩家数据。
• 产品需求、技术设计和本实施规划书。
• 核心验收用例与测试结果。
• 已知限制和下一阶段多人化改造清单。

11. 下一阶段建议

一周 MVP 完成后，用 3～5 场用户访谈或现场模拟验证规则是否易懂、线索节奏是否合理、玩家是否频繁看手机以及安全提示是否有效。确认玩法成立后，再进入 2～4 周的熟人多人版建设，依次接入微信登录、云端房间、实时同步、服务端倒计时、定位与抓捕校验。