save code

docs/游戏策划案.md

@@ -1,8 +1,8 @@
 # 《听仙》— 纯听觉仙侠MUD游戏策划案
 
-> 版本：v1.1（修订版）  
-> 日期：2026-05-21  
-> 状态：修订策划（解决交互冲突、MVP收窄、技术架构前置、音频队列收敛）
+> 版本：v1.2（修订版）
+> 日期：2026-05-21
+> 状态：修订策划（解决交互冲突、属性体系一致性、MVP收窄、技术架构前置、音频队列收敛）
 
 ---
 
@@ -156,11 +156,23 @@
          遇敌/切磋  │下滑=菜单   双击NPC=对话
               │     ┌────▼─────┐     │
          ┌────▼───┐ │  菜单态   │ ┌──▼───┐
-         │ 战斗态  │ └──────────┘ │对话态 │
-         └────────┘               └──────┘
+         │ 战斗态  │ └────┬─────┘ │对话态 │
+         └────────┘      │        └──┬───┘
+                         │           │选择交易
+              ┌──────────┼─────┐     ▼
+              ▼          ▼     ▼  ┌────────┐
+          ┌───────┐ ┌────────┐ │  │ 商店态 │
+          │背包态 │ │突破流程│ │  └────────┘
+          └───────┘ └────────┘ │
+                               ▼
+                           ┌────────┐
+                           │ 交易态 │
+                           └────────┘
 ```
 
 > **设计决策**：探索态中，**单击**始终是"查看当前状态"（不切换状态），**下滑**进入菜单。这确保单击在所有状态下含义一致——"告诉我现在的情况"，不产生歧义。
+>
+> **状态边界**：背包态、商店态、交易态、突破流程都是功能子流程，不作为核心主状态。它们使用相同的列表/确认类手势规则，进入和退出统一由 3.4 节定义。
 
 ### 3.3 各状态下的手势映射
 
@@ -209,12 +221,13 @@
 
 菜单项列表：
 1. 角色信息（属性、境界、经验）
-2. 背包（物品管理）
-3. 功法（已学技能）
-4. 装备（穿戴管理）
-5. 任务（当前任务列表）
-6. 社交（好友、门派、附近玩家）
-7. 系统（设置、退出）
+2. 修炼/突破（打坐收益、突破条件、开始突破）
+3. 背包（物品管理）
+4. 功法（已学技能）
+5. 装备（穿戴管理）
+6. 任务（当前任务列表）
+7. 社交（好友、门派、附近玩家）
+8. 系统（设置、退出）
 
 #### 对话态
 
@@ -242,6 +255,19 @@
 | 单击 | 查看物品详细信息 | "回灵丹：恢复50点灵力。品质：普通。描述：以灵草炼制的入门丹药。" |
 | 双击 | 使用/装备当前物品 | "你服下回灵丹。灵力恢复50点，当前灵力：115/200。" |
 
+#### 突破流程（菜单态子流程）
+
+玩家从菜单态进入"修炼/突破"后，若满足突破条件，会进入突破流程。
+
+| 手势 | 功能 | 语音反馈示例 |
+|------|------|------------|
+| 上滑 | 上一个辅助选项/材料说明 | "不使用突破丹" |
+| 下滑 | 下一个辅助选项/材料说明 | "使用突破丹，成功率提高10%" |
+| 左滑 | 取消突破，返回菜单态 | "已取消突破。" |
+| 右滑 | 重听当前阶段提示 | （重播当前突破引导语） |
+| 单击 | 查看当前突破状态/进度 | "正在凝聚灵气，进度60%，请等待下一次干扰提示。" |
+| 双击 | 开始突破 / 化解干扰 / 确认结果 | "你凝神静气，开始冲击瓶颈。" |
+
 ### 3.4 状态切换规则
 
 | 触发条件 | 从 | 到 | 音效提示 |
@@ -253,6 +279,13 @@
 | 遭遇敌人 | 探索态 | 战斗态 | 战斗警戒音效（剑鸣+鼓点） |
 | 战斗结束 | 战斗态 | 探索态 | 胜利/失败音效 |
 | 菜单进入背包 | 菜单态 | 背包态 | 背包打开音效 |
+| 背包中左滑返回 | 背包态 | 菜单态 | 返回音效 |
+| 菜单进入修炼/突破且满足条件 | 菜单态 | 突破流程 | 修炼氛围音 + 突破提示 |
+| 突破完成/取消 | 突破流程 | 菜单态 | 成功/失败/取消提示音 |
+| 对话中选择"交易" | 对话态 | 商店态 | 商店打开音效 |
+| 商店中左滑返回 | 商店态 | 对话态 | 商店关闭音效 |
+| 玩家互动选择"交易"且对方接受 | 探索态 | 交易态 | 交易打开音效 |
+| 交易完成/任意一方取消 | 交易态 | 探索态 | 交易完成/取消提示音 |
 
 ### 3.5 操作容错机制
 
@@ -320,13 +353,18 @@
 
 #### 突破机制
 - 每个大境界突破需要满足条件（经验值+特殊物品/事件）
-- 突破是一个互动音频事件（进入**突破态**）：
+- 突破入口在菜单"修炼/突破"中；条件满足时，系统播报"你已触及瓶颈，可尝试突破"
+- 突破是一个互动音频事件（进入**突破流程**，复用菜单态子流程，不新增主状态）：
   - 播放修炼氛围音
   - 语音引导玩家"凝神静气，双击开始突破"（**双击**确认开始）
   - 单击可查看当前突破进度/状态（保持单击统一语义）
   - 突破过程中随机出现干扰（需要在音效提示后及时**双击**化解）
   - 成功/失败有不同的音频叙事
   - 失败不掉级，但需等待冷却时间后重试
+- 突破冷却：
+  - 普通大境界突破失败：现实时间 30 分钟后可重试
+  - 天劫/终极试炼类突破失败：现实时间 60 分钟后可重试
+  - 服务端记录 `breakthrough_cooldown_until`，上线时语音提示剩余冷却
 
 ### 4.4 功法与技能体系
 
@@ -371,6 +409,8 @@
   - "你打坐修炼了3小时42分，获得经验1860点。当前等级：练气四层。"
 - 离线修炼收益 = 在线修炼收益 × 0.5（鼓励在线但不惩罚离线）
 - 离线修炼有上限（最多8小时有效），超出部分不计算
+- 离线期间可以自动提升同一大境界内的小层级；若经验达到需要主动突破的大境界门槛，角色停留在当前境界上限并记录 `pending_exp`
+- 下次上线时播报："你已触及筑基瓶颈，积累的灵气等待突破。请在菜单中选择修炼/突破。"
 
 ---
 
@@ -394,6 +434,7 @@
   items: [...],                      // 地面物品
   events: [...],                     // 可触发事件
   pvp_allowed: false,                // 是否允许PvP
+  safe_zone: false,                   // 是否为安全区
   level_range: [1, 10],              // 推荐等级范围
 }
 ```
@@ -434,6 +475,16 @@
 | 镇北郊外 | 风声、草虫鸣叫 | 巡逻卫兵（偶尔） | 野外入口、低级怪物 |
 | 镇南码头 | 水波拍岸、渔船吱呀 | 船夫老周 | 传送至其他区域 |
 
+#### 安全区规则
+
+安全区是全局房间属性，不只限于客栈二楼。
+
+- 进入安全区时播放轻柔结界音，并播报"你进入了安全区"
+- 离开安全区时播放结界淡出音，并播报"你离开了安全区"
+- 安全区内禁止发起自由 PvP、怪物不会主动刷新，正在被追击的战斗不能通过进入安全区强制脱战
+- 安全区内允许打坐修炼、交易、整理背包、社交聊天
+- 房间配置以 `safe_zone: true` 标记；若 `safe_zone: true`，默认 `pvp_allowed: false`
+
 #### 主要区域概览
 
 | 区域 | 等级 | 房间数（MVP） | 核心声景 |
@@ -473,14 +524,17 @@
 7. 当前天气/时辰
 ```
 
-#### 切换出口的播报
+#### 切换焦点的播报
+
+左滑/右滑在当前房间的所有可交互对象间循环切换，包括出口、NPC、地面物品和附近玩家。只有当前焦点是出口时，上滑才会移动；当前焦点不是出口时，上滑播放"当前焦点不可移动"的无效提示。
 
-左滑/右滑在可用出口间循环切换：
 ```
 右滑 → "北面——登山石阶"
-右滑 → "南面——下山土路"  
-右滑 → "北面——登山石阶"（循环）
-上滑 → 沿当前选中方向移动
+右滑 → "张道长"
+右滑 → "地上的破旧储物袋"
+右滑 → "南面——下山土路"
+双击 → 与当前焦点互动
+上滑 → 若当前焦点为出口，则沿该出口移动
 ```
 
 ### 5.4 随机事件系统
@@ -509,7 +563,7 @@
 ├──────────┬──────────┬──────────┬─────────────┤
 │ BGM 层   │ 氛围层    │ 音效层    │ 语音层      │
 │ (循环)    │ (循环)    │ (单次)    │ (队列)      │
-│ 音量:30% │ 音量:40%  │ 音量:80% │ 音量:100%   │
+│ 音量:40% │ 音量:40%  │ 音量:80% │ 音量:100%   │
 ├──────────┼──────────┼──────────┼─────────────┤
 │区域BGM   │环境声     │操作反馈   │NPC对白      │
 │战斗BGM   │天气声     │战斗音效   │系统播报     │
@@ -518,7 +572,7 @@
 ```
 
 #### 层级规则
-- **BGM层**：每个区域/状态一首BGM，进出时交叉淡入淡出（2秒）
+- **BGM层**：每个区域/状态一首BGM，进出时交叉淡入淡出（2秒）；语音播报时自动压低到 20%，播报结束后恢复
 - **氛围层**：环境声循环播放，可叠加天气音效
 - **音效层**：即时触发，可并行播放最多3个音效
 - **语音层**：**优先级队列**播放，具体规则见下方"音频播报状态机"
@@ -607,7 +661,7 @@
   - "造成" (通用连接)  
   - "{damage}" (数字，预生成常用数字0-9999)
   - "点" (通用)
-  - "{type}" (伤害类型：物理/火焰/冰霜/雷电/毒)
+  - "{type}" (伤害类型：物理/金/木/水/火/土/毒；毒用于持续伤害或特殊直接伤害)
   - "伤害" (通用后缀)
 
 拼接规则：
@@ -628,7 +682,7 @@
 | 怪物名称 | ~80 个 | VoxCPM2 |
 | NPC名称 | ~30 个 | VoxCPM2 |
 | 房间描述 | ~150 段 | VoxCPM2 |
-| NPC对话 | ~500 段 | VoxCPM2（不同NPC用不同参考音色） |
+| NPC对话 | ~1500 段 | VoxCPM2（v1.0总量，不同NPC用不同参考音色） |
 | 系统提示语 | ~100 段 | VoxCPM2 |
 | 主线剧情旁白 | ~200 段 | VoxCPM2 |
 
@@ -817,13 +871,18 @@
 
 | 攻\守 | 金 | 木 | 水 | 火 | 土 |
 |-------|----|----|----|----|-----|
-| 金 | 1.0 | 1.3 | 0.7 | 1.0 | 1.0 |
-| 木 | 0.7 | 1.0 | 1.0 | 0.7 | 1.3 |
-| 水 | 1.3 | 1.0 | 1.0 | 1.3 | 0.7 |
-| 火 | 1.0 | 1.3 | 0.7 | 1.0 | 1.0 |
+| 金 | 1.0 | 1.3 | 1.0 | 0.7 | 1.0 |
+| 木 | 0.7 | 1.0 | 1.0 | 1.0 | 1.3 |
+| 水 | 1.0 | 1.0 | 1.0 | 1.3 | 0.7 |
+| 火 | 1.3 | 1.0 | 0.7 | 1.0 | 1.0 |
 | 土 | 1.0 | 0.7 | 1.3 | 1.0 | 1.0 |
 
-克制伤害 ×1.3，被克制伤害 ×0.7。
+五行相克：金克木、木克土、土克水、水克火、火克金。克制伤害 ×1.3，被克制伤害 ×0.7。
+
+毒不属于五行灵根属性，默认不参与五行克制矩阵：
+- 毒作为状态效果时，按中毒、腐蚀等持续伤害规则结算，属性克制系数固定为 1.0
+- 毒作为直接伤害时，仍播报为"毒伤害"，但属性克制系数固定为 1.0；平衡主要通过命中率、持续回合、可驱散性控制
+- 若技能同时带有五行属性和毒效果（如"木系毒藤"），直接命中部分按木属性计算，后续中毒部分按毒规则计算
 
 ### 7.4 PvE 怪物设计
 
@@ -847,7 +906,7 @@
 | 青云山外围 | 凶·山魈 | 8-10 | 木 | 诡异笑声 |
 | 落星平原 | 盗匪 | 5-10 | 金 | 刀剑碰撞 |
 | 落星平原 | 妖狐 | 8-12 | 火 | 妖媚笑声+火焰 |
-| 幽冥沼泽 | 沼泽毒蛙 | 15-18 | 水/毒 | 粘腻跳跃+毒液 |
+| 幽冥沼泽 | 沼泽毒蛙 | 15-18 | 水（附带中毒） | 粘腻跳跃+毒液 |
 | 赤炎荒原 | 赤焰蟒 | 15-20 | 火 | 火焰吐息 |
 
 ### 7.5 PvP 对战规则
@@ -928,7 +987,9 @@
 | Boss大招 | 独特前摇音效（如龙吟） + 语音预警 | 双击使用闪避身法 |
 | Boss进入暴走 | BGM节奏加快 + 语音"它进入了狂暴状态！" | 提高输出/拉开距离 |
 | Boss可打断 | 特殊音效（咳嗽/喘息） + 语音"它露出了破绽！" | 立即双击使用控制技能 |
-| 场地危险 | 警告音效 + 语音"地面开始龟裂！" | 上滑选择闪避 |
+| 场地危险 | 警告音效 + 语音"地面开始龟裂！" | 切换到闪避身法后双击使用 |
+
+> Boss战仍使用战斗态手势：上/下滑切换技能，左/右滑切换目标，双击确认。Boss机制只改变推荐应对技能，不新增独立手势。
 
 ### 8.4 组队副本的语音协调
 
@@ -1071,13 +1132,15 @@ NPC: 张道长
 
 #### 装备品质
 
-| 品质 | 颜色概念 | 音频标识 | 属性加成 |
+| 品质 | 播报短语 | 音频标识 | 属性加成 |
 |------|---------|---------|---------|
-| 凡品 | 白 | 无特殊音效 | 基础属性 |
-| 灵器 | 绿 | 获得时有轻微灵光音 | +10-20% |
-| 宝器 | 蓝 | 获得时有明显灵光音 | +20-40% |
-| 仙器 | 紫 | 获得时有华丽仙乐 | +40-70% |
-| 太古神器 | 金 | 获得时有震撼天地音效 | +70-100%+特殊效果 |
+| 凡品 | "凡品" | 无特殊音效 | 基础属性 |
+| 灵器 | "灵器" | 获得时有轻微灵光音 | +10-20% |
+| 宝器 | "宝器" | 获得时有明显灵光音 | +20-40% |
+| 仙器 | "仙器" | 获得时有华丽仙乐 | +40-70% |
+| 太古神器 | "太古神器" | 获得时有震撼天地音效 | +70-100%+特殊效果 |
+
+> 品质不依赖颜色表达。若未来提供低视觉辅助界面，颜色只作为额外视觉提示，不作为核心信息载体。
 
 #### 消耗品
 
@@ -1089,6 +1152,14 @@ NPC: 张道长
 | 传送符 | 传送至指定城镇 | 商店 |
 | 隐身符 | 短时间隐身（PvP逃跑用） | 商店/任务 |
 
+#### 传送符使用规则
+
+- 可传送目的地：玩家已到访并解锁的城镇传送点、门派山门、公共安全区
+- 不可使用场景：战斗中、Boss房间、未结算副本、自由 PvP 追击状态、剧情强制场景
+- 使用流程：在背包选中传送符 → 双击使用 → 上/下滑选择目的地 → 单击确认目的地详情 → 双击开始施法
+- 施法时间：现实 5 秒，期间播放符箓燃烧音；受到攻击、移动或左滑取消会打断施法，传送符不消耗
+- 成功后播放空间撕裂音，进入目标房间并按 5.3 的房间播报顺序播报
+
 #### 材料
 
 用于炼丹、炼器的基础材料，按品级分为1-5星。
@@ -1105,8 +1176,20 @@ NPC: 张道长
 - 流程：
   1. 发起方：选中对方 → 双击 → 选择"交易"
   2. 接收方收到语音："[玩家A]向你发起交易请求。双击接受。"
-  3. 交易界面：双方各放入物品 → 确认
-  4. 双方双击确认后交易完成
+  3. 双方进入交易态，各自从背包中放入物品或灵石
+  4. 双方双击锁定后，系统播报交易摘要
+  5. 双方再次双击最终确认后交易完成；任意一方左滑取消则交易关闭
+
+交易态操作：
+
+| 手势 | 功能 | 语音反馈示例 |
+|------|------|------------|
+| 上滑 | 上一个可交易物品/金额选项 | "回灵丹×3" |
+| 下滑 | 下一个可交易物品/金额选项 | "灵石100枚" |
+| 左滑 | 取消交易/返回上一级 | "交易已取消。" |
+| 右滑 | 切换区域：我的物品 / 对方物品 / 确认区 | "对方已放入：铁剑，凡品。" |
+| 单击 | 查看当前物品或交易摘要 | "你将给出回灵丹×3，对方将给出灵石60枚。" |
+| 双击 | 放入/移除当前物品；在确认区锁定或最终确认 | "已放入回灵丹×1。" |
 
 ### 10.4 背包管理的音频方案
 
@@ -1335,19 +1418,25 @@ NPC: 张道长
 
 ### 13.3 服务端技术栈
 
-| 模块 | 技术建议 | 说明 |
+| 模块 | 技术选型 | 说明 |
 |------|---------|------|
-| 游戏服务器 | Node.js / Go | WebSocket服务 + 游戏逻辑 |
-| 数据库 | PostgreSQL / MongoDB | 玩家数据、世界状态 |
+| 游戏服务器 | Node.js + TypeScript | WebSocket服务 + 游戏逻辑，便于与H5前端共享协议类型 |
+| 数据库 | PostgreSQL | 玩家数据、交易、任务进度等强一致持久化数据 |
 | 缓存 | Redis | 在线状态、会话、排行榜 |
 | 音频资源 | 静态文件服务 / CDN | 预生成音频文件托管 |
 | TTS服务 | VoxCPM2 REST API | 动态语音生成 |
-| 任务队列 | Redis Queue | TTS生成任务排队 |
+| 任务队列 | BullMQ（Redis） | TTS生成任务排队、重试、失败追踪 |
 
 ### 13.4 通信协议设计
 
 客户端和服务器之间通过 WebSocket 传输 JSON 消息：
 
+#### 通用协议规则
+
+- 所有会改变服务器状态的客户端消息必须携带 `request_id`，服务端响应中原样返回，便于重试去重
+- 服务端下发的关键事件携带递增 `event_id`，客户端断线重连后可用 `last_event_id` 请求补发
+- 以下示例为业务字段示意，省略了 `request_id`、`event_id`、`session_id` 等通用字段
+
 #### 客户端 → 服务器
 
 ```json
@@ -1409,6 +1498,36 @@ NPC: 张道长
 }
 ```
 
+#### 错误响应与重连
+
+```json
+// 错误响应
+{
+  "type": "error",
+  "request_id": "req_20260521_0001",
+  "code": "INVALID_STATE",
+  "message_audio": "err_state_changed.mp3",
+  "fallback_text": "状态已变化，请重新确认。",
+  "recoverable": true
+}
+
+// 心跳
+{"type": "ping", "client_time": 1779368400000}
+{"type": "pong", "server_time": 1779368400120}
+
+// 断线恢复
+{
+  "type": "resume",
+  "resume_token": "token_xxx",
+  "last_event_id": 1288
+}
+```
+
+- 客户端每 20 秒发送一次 `ping`；连续 3 次未收到 `pong` 视为断线
+- 断线后按 1s / 3s / 5s / 10s / 30s 退避重连，最多保持 5 分钟会话
+- 重连成功后，服务端根据 `last_event_id` 补发关键事件；过期则返回完整房间状态和角色状态
+- 对于不可恢复错误（如账号被顶号、版本过低），服务端下发 `recoverable: false` 并引导回登录态
+
 ### 13.5 音频资源管理
 
 #### 资源分级加载策略
@@ -1420,6 +1539,13 @@ NPC: 张道长
 | L2-内容 | NPC对话、房间描述 | 进入房间/触发对话时加载 | LRU缓存 |
 | L3-动态 | 动态生成的玩家名等 | 首次遇到时生成并缓存 | 永久缓存 |
 
+#### 音频加载失败降级
+
+- 单个音频资源加载失败时，客户端重试 2 次；仍失败则查找本地缓存
+- 若缓存不可用且消息含 `fallback_text`，使用浏览器 Web Speech API 或系统 TTS 播读文本
+- 若系统 TTS 也不可用，播放错误提示音并跳过该非关键音频；P0/P1 关键消息必须继续重试或请求服务端重新下发
+- 客户端上报 `audio_load_failed` 事件，包含资源ID、消息优先级、网络状态，便于后续补资源
+
 #### 音频格式
 
 | 用途 | 格式 | 码率 | 原因 |
@@ -1441,7 +1567,8 @@ characters
   id, player_id, name, origin, element,
   level, exp, realm,
   hp, max_hp, mp, max_mp,
-  str, int, agi, spi, luk,
+  root_bone, comprehension, spirit_power, divine_sense, fortune,
+  pending_exp, breakthrough_cooldown_until,
   current_room_id, current_state,
   money, guild_id
   
@@ -1574,7 +1701,8 @@ Redis:
 | **v0.3 内容原型** | 任务/对话系统 | 1个NPC+1条教学任务+物品/装备基础操作+菜单系统 | 能否通过音频完成"接任务→打怪→交任务"闭环 | +20个文件 |
 | **v0.4 联机原型** | 多人同步 | 登录+同房间玩家可见+房间聊天（文字转语音）+WebSocket | 多人状态同步+语音播报是否混乱 | +15个文件 |
 | **v0.5 内测MVP** | 内容量+游历修士 | 扩展至15-20个房间+主线第一章前半+3-5个游历修士+日常任务 | 首次完整体验测试、留存观察 | +150个文件 |
-| **v0.7 社交扩展** | PvP+组队+副本 | 切磋系统+组队副本+好友+新区域 | 多人玩法验证 | +200个文件 |
+| **v0.6 社交原型** | 社交与交易 | 好友+私聊+玩家交易+简单组队 | 纯音频社交与交易流程是否清晰 | +80个文件 |
+| **v0.7 副本/PvP扩展** | PvP+组队副本 | 切磋系统+组队副本+新区域 | 多人玩法验证 | +120个文件 |
 | **v1.0 正式版** | 完整内容 | 5大区域+主线前3章+门派+公会+完整经济系统 | 公开上线 | +1500个文件 |
 
 ---
@@ -1609,7 +1737,9 @@ Redis:
 | 菜单态 | 上一项 | 下一项 | 返回 | 展开子菜单 | 查看详情 | 确认 |
 | 对话态 | 上一选项 | 下一选项 | 结束对话 | 重听 | 当前选项 | 选择 |
 | 背包态 | 上一物品 | 下一物品 | 返回 | 操作菜单 | 物品详情 | 使用/装备 |
+| 突破流程 | 上一辅助选项 | 下一辅助选项 | 取消/返回 | 重听提示 | 查看突破状态 | 开始/化解/确认 |
 | 商店态 | 上一商品 | 下一商品 | 返回 | 切分类 | 商品详情 | 购买 |
+| 交易态 | 上一物品/金额 | 下一物品/金额 | 取消/返回 | 切换交易区域 | 查看摘要 | 放入/锁定/确认 |
 
 > **一致性规则**：单击在所有状态下 = "告诉我现在的情况"（只读，不改变状态）。双击在所有状态下 = "确认/执行当前操作"。左滑在列表类状态下 = "返回/退出"。