Mavis
梳理
同福客栈 · 新手流程现状梳理

当前新手流程 · v2 落地现状 对照方案 v1 · 找出已实现 / 字面落地但体验未打磨 / 完全没动

P0+P1+P2+P3 全部落地：剧情错触发、主操作台 11→4+7、揭幕仪式、4 步引导。 本文档对照方案 v1 逐节点梳理"实际跑起来时玩家会看到什么"， 标记 8 处字面落地但仍需打磨的细节，输出 P4+ 建议清单。

✅ 已落地 13 项 ⚠️ 待打磨 8 项 📋 待排期 4 项 🚧 完全未动 2 项
P0 剧情前置
12
事件加 requiredStaff · selection.ts 硬性短路 · tsc 零新错
P1 Tab 解锁
11→4+7
核心 4 + 收纳 7 · tabUnlockConfig 中心化 · hover 进度提示
P2 揭幕仪式
13
5 角色 + 8 Tab 档案 · ConfettiBurst 礼花 · 全屏卷轴大卡
P3 引导气泡
4 步
自动推进 · 可收起 · 跳过即存档 · 但和揭幕仪式并发未做协调
01

当前流程：玩家实际看到的节奏 CURRENT FLOW · DAY 1 → DAY 360 时间轴

新手期时间轴 覆盖开服第一年的关键节点

已落地 OK 字面落地，待打磨 待排期 / 有 bug 完全未动
DAY 1
开张适应期

玩家第一次进入主操作台

  • 🎓 引导 右下角 OnboardingCoach 弹出「第 1 步：掌柜的第一件事 · 佟湘玉」，指路「账本」Tab。
  • 🎉 揭幕 预警 Tab 因为 always 条件，会被 useUnveilDetector 检测为"刚解锁" → 弹出"预警中枢上线"揭幕。⚠️ 见问题 #1
  • ✓ 主操作台显示 核心 4 Tab（账本/门客/后厨/行囊） + 7 个收纳 Tab（5 个🔒）
  • ✓ 默认剧情：佟湘玉+李大嘴在场，mainline-business.ts 5 个事件无 requiredStaff 限制，全部可触发。
  • ✓ 玩家点开「账本」Tab → setHasOpenedLedger(true) → 引导自动跳到第 2 步。
DAY 4
首次掉落

行囊 Tab 首次满足 dayMin=4 条件

  • 🎉 揭幕 行囊启用揭幕 弹出：「第一次掉落的物件已收入行囊 —— 同福客栈开始有点家当了。」+ 礼花
  • ✓ ConsoleTabsBar 上「行囊」从灰 → 朱砂亮起，🔒 角标消失。
  • ⚠️ Tab 解锁瞬间的脉冲高亮还没做 —— 玩家可能错过新 Tab。见问题 #2
DAY 8±
研发 2 道菜

菜谱 Tab 满足 requiredUnlockedDishes≥2

  • 🎉 揭幕 菜谱启用揭幕：「研习出两道拿手菜 —— 大嘴的灶台不再只会煮面。」
  • ✓ 菜谱 Tab 解锁。
DAY 35±
招 🍳 李大嘴

李大嘴（默认 unlocked，剧情上门）

  • 👻 元老 李大嘴 开局就是 unlocked=true，所以不会触发"招贤纳士"揭幕（检测只针对 unlocked 从 false→true）。
  • ✓ 后院 Tab 满足 requiredStaff: ['li'] → 后院启用揭幕 弹出。
  • ✓ 角色线 dazui_supply_shortage / duan_zhi_visit 现在会被正确选中（之前可能因为权重不够被埋没）。
DAY 70±
招 🥊 郭芙蓉

玩家招募郭芙蓉（unlocked=false→true）

  • 🎉 揭幕 「郭 芙 蓉 · 排山倒海」全屏大卡 + 礼花 + "接纳招募 →"。
  • 🎉 揭幕 设施 Tab 解锁 → 「设 施 启 用」揭幕弹出（两个会排队展示）。
  • ✓ 关键剧情线 day_guo_front_door / martial_match_guo_guard 现在能正确触发（之前会穿帮）。
  • ⚠️ 两个揭幕同时触发，但 useUnveilDetector 的 setTimeout(50ms) 间隔很短，玩家体验上像"快速连弹"。见问题 #3
DAY 90±
初遇挑战期

首次剧情事件触发

  • ✓ setHasTriggeredEvent(true) → 引导跳到第 4 步。
  • 🎓 引导 第 4 步：街头说书「客栈开到第三天，江湖的客人就会自动上门」→ day ≥ 3 + hasTriggeredEvent → 引导完成，1.2s 后自动消失。
  • ✓ setOnboardingDismissed(true) → 写 localStorage，二次进游戏不再触发。
  • ⚠️ 如果玩家没完成第 4 步就退游戏，下次进游戏会从头开始 —— 没有持久化引导进度。见问题 #4
DAY 140±
招 🥋 白展堂

玩家招募白展堂（关键节点）

  • 🎉 揭幕 「白 展 堂 · 盗圣」全屏大卡。
  • 🎉 揭幕 闯荡 Tab 解锁 → 「闯 荡 启 用」揭幕。
  • ✓ 关键剧情线激活：bai_secret_old_friend / martial_match_bai_old_debt / night_rooftop_steps 现在能被正确选中。
  • ✓ 之前会穿帮的"白展堂守擂"等擂台赛事件，现在不会在白展堂未招募时触发了。
DAY 200±
招 🎓 吕轻侯

玩家招募吕秀才

  • 🎉 揭幕 「吕 轻 侯 · 子曾经曰过」全屏大卡。
  • ✓ ling_tengyun_case / martial_match_xiucai_words 角色线解锁。
DAY 270
官府竞标

dayMin=270 触发 · 竞拍 Tab 解锁

  • 🎉 揭幕 「同 福 竞 标 启 用 · 衙门红印落下」揭幕弹出。
  • ✓ AuctionTab 主操作台接入，玩家开始经历"客栈停业参拍"模式（沿用方案文档里描述的衙门重地 UI）。
DAY 360
岁末收束

声望 ≥ 500 · 联机 Tab 解锁

  • 🎉 揭幕 「联 机 启 用 · 同福的名号传开了」揭幕弹出。
  • ✓ PeerLobby 接入主操作台。
  • 🚧 year1Plan 12 月关键节点没接入 onboarding —— 12 月的"年终大戏"目前没有揭幕仪式（方案 v1 设计了但 P2 没实现 event_unveil 触发）。见问题 #5
02

五条核心流程线 · 全链路梳理 FIVE LINES · 启动 → 招募 → 解锁 → 剧情保护 → 存档持久化

① 启动主线 · OnboardingCoach 4 步

1
👩‍💼
佟湘玉
账本 Tab 打开
→ hasOpenedLedger
2
🍳
李大嘴
门客 Tab 招募
→ unlockedStaffCount ≥ 3
3
🪧
门廊小二
解锁 ≥ 5 个 Tab
→ unlockedTabsCount
4
📣
街头说书
首次剧情 + day ≥ 3
→ hasTriggeredEvent
✓
🎓
引导完成
写 localStorage
永久不再骚扰

② 招募线 · CinematicUnveilModal

触发链路：staff[id].unlocked: false → true → useUnveilDetector 检测 → queueRef.push → 弹窗。

StaffId角色档案触发时机状态
tong佟湘玉👩‍💼 离线+2%/级默认 unlocked，不触发揭幕元老
li李大嘴🍳 菜品+5/级默认 unlocked，不触发揭幕元老
guo郭芙蓉🥊 排山倒海玩家花 200 铜钱招募触发
bai白展堂🥋 盗圣巡堂玩家花 150 铜钱招募触发
lu吕轻侯🎓 子曰账法玩家花 350 铜钱招募触发
关键：招募 = StaffTabs 的"账册登记 → 招募"按钮（App.tsx ~line 2810）。目前只在 unlocked 从 false→true 时触发，没有"升级到某 level"也触发的逻辑（方案 v1 里讨论过——保留给后续打磨）。

③ 解锁线 · tabUnlockConfig + ConsoleTabsBar

Tab解锁条件评估函数状态
账本alwayskind: 'always'核心
门客alwayskind: 'always'核心
后厨alwayskind: 'always'核心
行囊dayMin: 4ctx.day >= 4核心
菜谱≥ 2 道菜解锁ctx.unlockedDishesCount >= 2第 8 日±
后院招募李大嘴staff.li.unlocked元老即解锁
设施招募郭芙蓉staff.guo.unlockedDAY 70±
闯荡招募白展堂staff.bai.unlockedDAY 140±
预警alwayskind: 'always'DAY 1
竞拍dayMin: 270ctx.day >= 270DAY 270
联机reputation ≥ 500ctx.reputation >= 500中后期

④ 剧情保护线 · requiredStaff

修复方案：selectWeightedGameEvent 在权重计算前先调用 isStaffRequirementSatisfied(event, state.unlockedStaff)，硬性短路 → 权重 0.01。

// selection.ts · L196 起的权重循环
const weights = events.map((event) => {
  if (!isDayWindowAllowed(event, state.day)) return 0.01;
  // 🔒 新增：硬性短路
  if (!isStaffRequirementSatisfied(event, state.unlockedStaff)) return 0.01;
  ...
});

// App.tsx · 调用处
selectWeightedGameEvent({
  ...,
  unlockedStaff: getUnlockedStaffSet(current.staff),
});

已标注的 12 个事件：mainline-tournament × 4 + role-guo-lu × 1 + role-bai-tong × 1 + role-dazui × 2 + side-night-risk × 2 + side-official × 1 + storyline-bai-tong-pilot × 1。

⑤ 存档持久化 · 3 处 localStorage

localStorage Key用途写入时机状态
tongfu_unveil_dismissed_v1揭幕仪式的"已展示"key 集合玩家关闭任意揭幕弹窗已实现
tongfu_onboarding_dismissed_v1新手引导是否被跳过点"跳过"或完成第 4 步已实现
tongfu_onboarding_step_v1新手引导当前进度（stepIdx）—未实现
03

8 处字面落地但仍需打磨 POLISH · 这些是 P4+ 排期里最影响体验的

P1① DAY 1 预警 Tab "误触发"揭幕
src/utils/unveilTriggers.ts:207 · prevUnlockedTabsRef

prevUnlockedTabsRef 初始化是空 Set，DAY 1 启动时所有"已经满足条件"的 tab（包括预警 always）都被检测为"新解锁"，触发预警中枢揭幕。但预警从 DAY 1 就该常驻，不应该"揭幕"。

修法：初始化 prevUnlockedTabsRef 时跑一遍当前已解锁 tab；或者在 TAB_UNVEIL_PROFILES 里给 warning 加 skipAutoUnveil: true。
P1② Tab 解锁瞬间没有脉冲高亮
src/components/ConsoleTabsBar.tsx · RenderTabButton

ConsoleTabsBar 只在 hover 时显示锁住进度，Tab 从灰→朱砂亮起的瞬间没有额外脉冲动画。玩家可能完全没注意到新开了哪个 Tab。揭幕仪式会弹窗，但玩家关掉弹窗后，再去看 Tab 条，可能已经忘了刚才解锁的是哪个。

修法：维护一个 recentlyUnlockedTabs 集合，对刚解锁的 Tab 加 animate-pulse 类 3 秒；同时弹一个角落 toast"行囊 已解锁 →"。
P1③ 多个揭幕"快速连弹"无间隔
src/utils/unveilTriggers.ts:312-319 · dismiss

招郭芙蓉会同时触发 2 个揭幕（郭芙蓉 + 设施 Tab）。dismiss 用 setTimeout(50ms) 取下一个，玩家刚按"接纳招募 →"，下一个 0.05 秒后就弹出——体验像连弹。

修法：dismiss 加最短间隔 600ms；或攒到 3 个时合并为"卡片组"轮播；或干脆不允许 staff + tab 同帧触发，让 tab 的揭幕延后到 staff 关闭后 800ms。
P1④ Onboarding 引导进度不持久化
src/components/OnboardingCoach.tsx · stepIdx state

stepIdx 是组件本地 state，没写 localStorage。玩家做到第 2 步退游戏，下次进游戏会从头开始（虽然不会从 0 触发，因为 onboardingDismissed 还是 false，但会从第 1 步重新显示）。

修法：增加 tongfu_onboarding_step_v1 写 stepIdx；初始化时读。
P2⑤ event_unveil 类型完全未触发
src/utils/unveilTriggers.ts · 仅预留

CinematicUnveilModal 支持 kind: 'event_unveil'，但 useUnveilDetector 没接入任何大事件触发（如擂台赛开幕 / 旧账风波 / 年终大戏）。这些是方案 v1 设计的"重头戏揭幕"。

修法：在 tournament 系统的 setup 阶段、storyline-year 的关键节点 push event:xxx key 入队。
P2⑥ "更多"折叠抽屉未实现
src/components/ConsoleTabsBar.tsx

当前所有 11 个 Tab 仍然平铺，5 个🔒的收纳 Tab 也会占据 Tab 条空间。LayoutTab 类型预留了 'more'，但 ConsoleTabsBar 没渲染。

修法：收纳 Tab 在 isCore=false 时收进"更多 ▾"下拉菜单；下拉里再分组"已解锁 / 锁住中"。
P2⑦ year1Plan 没接入 onboarding
src/data/year1Plan.ts · 12 月阶段 + keyNodes

项目已有 YEAR1_PLAN_PHASES 12 月规划（keyNodes: 开业大吉/三日小结/招募吕秀才/食安风波/...），但 OnboardingCoach 没用它。引导只覆盖 4 步"操作型"，不覆盖"剧情型"（月 3 食安风波/月 6 擂台赛/月 9 官府竞标/月 12 岁末大戏）。

修法：OnboardingCoach 改成 N 步（12 步），按 year1Plan 的 keyNodes 推进；用 day 或触发事件判定进度。
P2⑧ ConfettiBurst 在 Modal 内坐标定位
src/components/ConfettiBurst.tsx · getBoundingClientRect

ConfettiBurst 内部用 getBoundingClientRect 计算 originX/originY。Modal 是 fixed inset-0 z-130，理论上 OK，但首次渲染时容器可能还没稳定，粒子可能从屏幕外飞。

修法：用 useLayoutEffect 替代 useEffect；在 onClose 后 50ms 内不要清空粒子。
04

建议打磨清单 P4+ P4+ ROADMAP · 优先级与工作量 · v3 更新（⑤ 已落地）

P 级 项 改什么 工作量 影响
P0 ① DAY 1 预警误触发 unveilTriggers.ts 初始化 prevUnlockedTabs 0.5 小时 消除一启动就弹的尴尬
P0 ② Tab 解锁脉冲 + 角落 toast ConsoleTabsBar + Toast 组件 1 小时 让玩家真看到新 Tab
P0 ③ 揭幕间隔拉到 800ms unveilTriggers.ts dismiss 0.5 小时 消除连弹
P1 ④ onboarding 进度持久化 OnboardingCoach + localStorage 0.5 小时 中途中断不丢进度
P1 ⑥ "更多"折叠抽屉 ConsoleTabsBar 2 小时 11→6 一行清爽
P1 ✅ ⑤ event_unveil 触发接入 已实现 EVENT_UNVEIL_PROFILES + enqueueEventUnveil；监听 tournament setup/final/cooldown + day≥330 岁末 + old_ledger_opening 已落地 擂台赛 / 旧账 / 岁末有仪式
P2 ⑦ year1Plan 12 步剧情引导 OnboardingCoach 改成 N 步 3 小时 覆盖到第 12 个月
P2 ⑧ ConfettiBurst 时序 useLayoutEffect + 延迟清空 0.5 小时 粒子更稳
P2 storyline-guo-lu-pilot 触发器 storyline 任务触发接入 unveil 1 小时 郭芙蓉入伙有专属揭幕
P3 角色升级揭幕（Lv 5 / Lv 10） unveilDetector 检测 level 跃迁 2 小时 养成的额外正反馈
P3 移动端 CoachMark 适配 OnboardingCoach 改 viewport < sm 时换位置 1 小时 移动玩家体验
P3 "跳过本步 / 跳过全部" 区分 OnboardingCoach 拆按钮 0.5 小时 更细颗粒度
05

浏览器测试清单 BROWSER PRE-FLIGHT · 跑前必测

首次启动（清缓存）

  • ✅ 进游戏后 右下角 4 步引导气泡 立刻出现
  • ⚠️ "预警中枢上线"揭幕 错误弹出 → 已知 bug，详见问题 #1
  • ✅ 主操作台 核心 4 Tab（账本/门客/后厨/行囊）+ 5 个🔒收纳 Tab
  • ✅ Hover 锁住的「设施」Tab → 看到"招募 🥊 郭芙蓉 后开放"
  • ✅ 点账本 Tab → 引导第 1 步自动消失，第 2 步 900ms 后浮现
  • ✅ DAY 1 时不应该触发任何擂台赛 / 角色专属剧情（白展堂未招募）

DAY 4 / DAY 8 / DAY 35

  • ✅ DAY 4 行囊 Tab 满足条件 → "行囊启用"揭幕 弹出
  • ⚠️ 关闭后没有脉冲高亮提示 → 已知 bug，详见问题 #2
  • ✅ DAY 8 菜谱 Tab 解锁 → 揭幕弹出
  • ⚠️ 揭幕顺序：行囊 → 菜谱 两个连续 → 0.05 秒连弹 → 已知 bug，详见问题 #3
  • ✅ DAY 35 后院 Tab 解锁（默认 li 已 unlocked）

招郭芙蓉（关键场景）

  • ✅ 在门客 Tab 花 200 铜钱招郭芙蓉 → "郭 芙 蓉 · 排山倒海" 全屏大卡弹出
  • ⚠️ 关闭后 50ms → "设施启用"揭幕紧跟弹出 → 详见问题 #3
  • ✅ 设施 Tab 从 🔒 → 朱砂亮起
  • ✅ DAY 70+ day_guo_front_door / martial_match_guo_guard 现在能被触发（之前因为 unlocked=false 被屏蔽）
  • ✅ 关掉揭幕后，localStorage.tongfu_unveil_dismissed_v1 包含 "staff:guo" 和 "tab:facilities"

招白展堂（核心病灶修复验证）

  • ✅ 招白展堂 → "盗圣巡堂" 全屏大卡
  • ✅ 关闭后 → "闯荡启用"揭幕
  • ✅ 闯荡 Tab 从 🔒 → 朱砂亮起
  • ⭐ 关键验证：白展堂未招募时打开 console 检查 GameEvent pool
    • 不应能选中 martial_match_bai_old_debt / bai_secret_old_friend / night_rooftop_steps
    • 权重应该都是 0.01

重启游戏（持久化验证）

  • ✅ 已展示过的揭幕不会再弹
  • ✅ 已完成 4 步引导 → 不会再出现引导气泡
  • ⚠️ 引导做到一半退游戏 → 下次从头开始 → 详见问题 #4
  • ✅ 锁住的 Tab 状态保留（不会因为重启就突然亮）
同福客栈 · 新手流程 v2 落地现状梳理 · 2026-06-29 · Mavis 出品 · 对照方案 v1