《同福客栈挂机游戏》游戏内按钮总览 v1 · 活跃设计

文档状态:v1 梳理稿(草稿,等 P1 拍板) 梳理日期:2026-07-14 范围:游戏内主页(已进游戏的桌面/竖屏模式)可见按钮的归属清单 + 实装状态 不在范围:启动页(v1.3 已发 → 见启动页v1.3按钮需求-v1.md);游戏内页面的非按钮交互(桌位点击、拖拽等) 关系:本文是 v1.3 启动页按钮文档的游戏内姊妹篇,不重复启动页内容 截图来源:P1 2026-07-14 上传两张(七侠镇新掌柜 弹窗 × 2 Tab:总览 / 账号)

0. 重要前置:实装 vs 设计稿

| 类别 | 来源 | 数量 | 状态 | |:--|:--|:-:|:-:| | A. 已实装 | 当前代码(AppHeaderBar.tsx / DesktopSidebar.tsx / SystemHubPanel.tsx / StoryTrackingCard.tsx) | 约 28 个 | ✅ 通 / 🟡 准通 | | B. 设计稿新增未实装 | P1 上传截图右上角 header 5 个按钮(代码里没找到) | 5 个 | 📐 设计稿待 P1 拍板 | | C. 启动页已发 | v1.3 启动页按钮(Header 排行榜/百科/新闻/下载/登录/支持我们 + Footer 微信群/法律/语言/画质/全屏) | 18 个 | v1.3 拍板中 → 启动页v1.3按钮需求-v1.md |

A + B = 本文档范围。C 链接过去不重复。

1. 总览图(脑图)

┌──────────────────────────────────────────────────────────────────┐
│ 顶部 AppHeaderBar (AppHeaderBar.tsx)                              │
│ ├─ 资源区(只读):账存铜钱 · 镇中声望 · 时辰 · 联机系统             │
│ └─ 按钮区:说明 · 路线 · 门厅 · 开声/静音 · 财神 · 终局测(DEV)     │
│   └─ 截图显示另有 5 个(布告·解锁/读中学习/规划/客栈·管家/终点测验)│
│     **代码里没有,需 P1 拍板**                                     │
├──────────────────────────────────────────────────────────────────┤
│ 庙前目标卡 StoryTrackingCard (StoryTrackingCard.tsx)               │
│ ├─ 进度条(只读)                                                   │
│ ├─ Year1 规划/收口 标签(只读)                                     │
│ └─ 「打开终局解释层」/「回看江湖简报」 跳转按钮 → 飞檐传书/终局    │
├────────┬─────────────────────────────────────────────────────────┤
│ 左侧栏 │ 中央工作区                                                │
│ Desktop│                                                           │
│ Sidebar│ ┌────────────┬─────────────┐                             │
│ (6 图) │ │ 冒险区(背景,只读)│ 弹窗:七侠镇新掌柜         │      │
│        │ │ InnCourt  8桌 │ SystemHubPanel (本轮主角)        │   │
│        │ └────────────┴─────────────┘                             │
├────────┴─────────────────────────────────────────────────────────┤
│ 飞檐传书 JianghuBriefboard / JianghuBriefingPanel (右抽屉,只读)  │
└──────────────────────────────────────────────────────────────────┘

2. 顶部 header 区(`AppHeaderBar.tsx` · 195 行)

2.1 资源显示(只读,非按钮)

2.2 按钮区(已实装)

| # | 玩家文案 | 代码 id | handler | 目标 | 状态 | 备注 | |:-:|:--|:--|:--|:--|:-:|:--| | H1 | 终局测 | dev-hard-shutdown-btn | onDeveloperHardShutdown | 强制触发 hard-shutdown 终局 | ✅ DEV only | 只在 import.meta.env.DEV 下渲染;截图里没看到,被折叠 | | H2 | 说明 | doc-manual-btn | onOpenManual | 打开「同福宝典」modal | ✅ 通 | 截图 line 132 | | H3 | 路线 | development-roadmap-btn | onOpenRoadmap | 打开开发路线页 | ✅ 通 | 截图 line 142 | | H4 | 门厅 | system-hub-btn | onOpenSystemHubHome | 打开「七侠镇新掌柜」弹窗 | ✅ 通 | 截图 line 152 — 本轮主角 | | H5 | 开声 / 静音 | volume-toggle-btn | onToggleMute | 切换市井音效 | ✅ 通 | 截图 line 174,文案随 isMuted 切换 | | H6 | 财神 | cheat-coins-btn | onDeveloperCheat | 开发调试:秒赠 5000 铜 | ✅ 通 | 截图 line 186 |

2.3 设计稿新增未实装(待 P1 拍板)

| # | 玩家文案(截图所见) | 推测归属 | 状态 | 阻塞 | |:-:|:--|:--|:-:|:--| | H7 | 布告·解锁 | 公告/事件目录相关 | 📐 设计稿 | 需 P1 拍板:接哪个 modal?走公告系统? | | H8 | 读中学习 | 教程/经营指南 | 📐 设计稿 | 需 P1 拍板:跟「同福宝典」(onOpenManual)是合并还是分流? | | H9 | 规划 | Year1 计划/Roadmap | 📐 设计稿 | 需 P1 拍板:跟「路线」(onOpenRoadmap)是合并还是分流? | | H10 | 客栈·管家 | 客栈状态详情 | 📐 设计稿 | 需 P1 拍板:接 InnStatusPanel 深入口还是新建? | | H11 | 终点测验 | 终局/通关检验 | 📐 设计稿 | 需 P1 拍板:跟「终局测」(onDeveloperHardShutdown)是合并还是分流?——后者是 DEV only,前者是玩家可见 |

⚠️ 判断:截图 P1 未明示这 5 个按钮是「下版设计」还是「实装现状」。我搜了 布告 / 读中 / 客栈·管家 / 规划 / 终点测验 等字串,在 *.tsx / *.ts 里都搜不到——所以默认按"设计稿新增"处理。P1 拍板后这 5 行会变成「✅ 已实装」或「🗑 砍」。

3. 左侧导航(`DesktopSidebar.tsx` · 104 行)

⚠️ Read 工具被反爬拒了,我用 grep 确认的按钮结构。下面是搜索结果整理,未读全文,若需逐字 review 再走 Read。

| # | 图标 | 玩家文案 | handler | 目标 | 状态 | 备注 | |:-:|:--|:--|:--|:--|:-:|:--| | S1 | (头像) | 账号 | onOpenAccountHub | 打开账号体系弹窗 | ✅ 通 | line 33-40 | | S2 | (CircleUser) | 门厅 | onOpenSystemHubHome | 打开「七侠镇新掌柜」弹窗 | ✅ 通 | line 42-49,= H4 同一目标 | | S3 | (Book) | 简报 | onOpenBriefing | 打开「江湖简报」抽屉/modal | ✅ 通 | line 51-58 | | S4 | (List) | 事件目录 | onOpenEventDirectory | 打开「事件目录」modal | ✅ 通 | line 60-67 | | S5 | (卷轴) | 说明 | onOpenManual | 打开「同福宝典」| ✅ 通 | line 75-82,= H2 同一目标 | | S6 | (路线) | 路线 | onOpenRoadmap | 打开开发路线 | ✅ 通 | line 84-91,= H3 同一目标 | | S7 | (音量) | 开声/静音 | onToggleMute | 切换音效 | ✅ 通 | line 93-104,= H5 同一目标 |

重复入口分析:门厅 / 说明 / 路线 / 开声 在 header 和 sidebar 都有,这是有意冗余(玩家可从两条路到达)。v1.3 拍板保留还是未来去重?——本文不拍板,留给 P1。

4. 庙前目标卡(`StoryTrackingCard.tsx` · 545 行)

DesktopWorkspacePanel.tsx line 178 渲染(<StoryTrackingCard storyTracking={storyTracking} />)

| # | 玩家文案 | 位置 | handler | 目标 | 状态 | 备注 | |:-:|:--|:--|:--|:--|:-:|:--| | T1 | 「打开终局解释层」 | 进度条右侧(line 499-503) | TasklineFailureJumpButton + target='endgame' | 跳到终局/失败解释层 | ✅ 通 | 当 bridge.trackingJumpTarget === 'endgame' 时显示 | | T2 | 「回看江湖简报」 | 同上 | 同上,target='briefing' | 跳到江湖简报 | ✅ 通 | 当 trackingJumpTarget === 'briefing' 时显示 | | T3 | (chip) Year1 规划 / Year1 收口 | line 511-512 | — | 标签(只读) | ✅ 通 | 根据 isYear1CloseoutResolved 切换文案 |

Y1 计划展开字段(line 514-537,只读,不渲染为按钮):

phaseLine(开家适应期 / 开中教学 / 基础经营闭环)

checklistStage.label + passSignal(通关信号)

第 360 天 / 跨年之夜(收口时)

5. 弹窗「七侠镇新掌柜」(`SystemHubPanel.tsx` · 486 行)

AppHeaderBar 的「门厅」/DesktopSidebar 的「门厅」/「账号」图标都打开这个弹窗。

5.1 弹窗头部(line 387-450)

| # | 玩家文案 | 位置 | handler | 目标 | 状态 | |:-:|:--|:--|:--|:--|:-:| | P1 | 头像 + 账号名 + 传承点 | line 389-405 | onOpenAccount | 切到「账号」Tab | ✅ 通 | | P2 | 简报 | line 408-411 | onOpenBriefing | 打开「江湖简报」 | ✅ 通 | | P3 | 事件目录 | line 412-415 | onOpenEventDirectory | 打开「事件目录」 | ✅ 通 | | P4 | 关闭门厅 | line 417-419 | onClose | 关闭弹窗 | ✅ 通 | | P5 | 6 个 Tab:总览 / 账号 / 周目 / Buff / 客栈 / 终局 | line 424-449 | 按 view.key 路由 | 切 Tab | ✅ 通 |

5.2 Tab 切换矩阵

| Tab | key | 渲染组件 | line | 数据源 | |:--|:--|:--|:-:|:--| | 总览 | home | 内联 JSX(账号与周目 + Year1 + 任务线失败 + Buff/客栈/终局快捷入口) | 266-381 | account / latestSlot / year1Plan / taskLineFailureSummary / buffSummary / innStatus / endgameEntries | | 账号 | account | <AccountPanel profileState={...} /> | 214-219 | profileState | | 周目 | playthrough | <PlaythroughPanel ... onOpenSnapshotBrowser={...} /> | 220-225 | playthroughVault | | Buff | buff | <BuffPanel buffSummary={...} /> | 226-231 | buffSummary | | 客栈 | inn | <InnStatusPanel ... onOpenAction={...} /> | 232-249 | innStatus | | 终局 | endgame | <EndgamePanel ... /> | 250-264 | endgameEntries / recentSafe / failureRecordsCount |

6 Tab 的点击是直接切本弹窗内 view(line 428-434),不打开新 modal。

5.3 总览 Tab 内的可点击项(line 266-381)

| # | 玩家文案 | 位置 | handler | 目标 | 状态 | 备注 | |:-:|:--|:--|:--|:--|:-:|:--| | H1 | (账号名按钮) | line 274 | 顶部 onOpenAccount 复用 | 切到「账号」Tab | ✅ 通 | "未登录账房"时点击接入账号档 | | H2 | 「打开账号页」 | line 290 | onOpenAccount | 切到「账号」Tab | ✅ 通 | | | H3 | 「打开周目页」 | line 291 | onOpenPlaythrough | 切到「周目」Tab | ✅ 通 | | | H4 | (Year1 阶段卡) | line 298-322 | — | 只读 | ✅ 通 | 显示 phaseLine + attributeLine + itemLine + checklistLine | | H5 | (任务线失败运行态) | line 324-341 | — | 只读 | ✅ 通 | 显示 taskLineId / stageLabel / triggerDay / mainchainLine | | H6 | 「Buff 总览」 | line 345-351 | onOpenBuff | 切到「Buff」Tab | ✅ 通 | 右侧 ChevronRight 箭头 | | H7 | 「客栈状态」 | line 352-358 | onOpenInn | 切到「客栈」Tab | ✅ 通 | 显示 gameStageLabel · healthScore/100 | | H8 | 「终局深入口」 | line 359-365 | onOpenEndgame | 切到「终局」Tab | ✅ 通 | 显示最新终局快照 title | | H9 | 「江湖简报」 | line 370-373 | onOpenBriefing | 打开「江湖简报」 | ✅ 通 | 底部 2 列布局 | | H10 | 「事件目录」 | line 374-377 | onOpenEventDirectory | 打开「事件目录」 | ✅ 通 | 底部 2 列布局 |

5.4 各子 Tab 详情

5.4.1 账号 Tab → `<AccountPanel>` · 本轮截图重点

数据:profileState: GlobalProfileLoadResult · 包含 profile.accountName / legacyPoints / unlocks / … + source(local/云)
显示字段:
- 账号名(line 274)
- source · 传承点 (line 277)
- 账号卡 line 271-279(图 1 中「七侠镇新掌柜」+「storage · 传承点 0」)
- 周目摘要卡 line 280-288(图 1 中「周目摘要」+「糖:1 · active」)
- ID: profile_xxxx(由 AccountPanel 内部渲染,玩家文案示例)
- 创建于 2026/06/23 / 最近 2026/07/14 17:08(由 AccountPanel 内部渲染)
- 生前统计:周目完成 / 周目失败 / 已解锁周数(由 AccountPanel 内部渲染)
- 「只读入口」说明:当前只显示 GlobalProfile 资料,账号切换/重置入门管家未提供(line 280-288 下方)
按钮:这个 Tab 内 0 按钮 — 全只读;切其他 Tab 走 P1(头像/顶部按钮)

图 1 看到的账号资料卡就是这个 Tab 渲染的(AccountPanel)。截图上的「只读入口」段是 P1 显式标注的「不实装」说明。

5.4.2 周目 Tab → `<PlaythroughPanel>`

显示 playthroughVault.slots 列表(每个槽位一行:slotId / status / updatedAt)
入口:onOpenSnapshotBrowser → 打开「存档快照浏览器」
本轮未截图,需要时再单独梳理

5.4.3 Buff Tab → `<BuffPanel>`

显示 buffSummary.activeBuffs(激活 Buff 列表)
只读

5.4.4 客栈 Tab → `<InnStatusPanel>`

显示 innStatus.gameStageLabel + healthScore
按钮:
- onOpenDimensionDetail → 打开维度详情(同 onOpenInn,line 238)
- onOpenAction(actionId) → 根据 actionId 分发:
  - review_failure_pressure → onOpenEndgame()(line 240-242)
  - 其他 → onOpenInn()(line 244-245)

5.4.5 终局 Tab → `<EndgamePanel>`

显示 endgameEntries 列表 + recentSafe + failureRecordsCount
按钮:
- onOpenSnapshotBrowser → 打开「存档快照浏览器」(同周目 Tab)
- onReplayEndgame → 重玩终局(由 props 传)
- onRestoreSafe → 恢复到 recentSafe

6. 同源压力/跳转接线(两 Tab 都显示 · line 458-478)

这块不是按钮,是数据展示(只读)。但 v1.2 视觉稿里它长得像 chip,所以单列一节免得混淆。

⚠️ 审稿提示:第 5 行「主链」字段按当前代码是直接拼接 pressureSourceTags / failureSeedTags / briefingRefs 进 buildMainchainLine,未做玩家文案收束。这违反了 AGENTS.md §4 「玩家文案 vs 开发者字段」—— bridgeRefs / Tags / Source / Seed 都是开发者字段。建议未来加玩家文案层(bridge.playerLine),但不阻塞本文档。

7. 底层 handler 总览(用于代码联调)

把所有 handler 集中列出来,方便 P1 拍板时一眼看到全貌。

8. 状态汇总(速查表)

8.1 按位置

| 区域 | 按钮数 | 已通 | 占位/无 | 设计稿新增 | |:--|:-:|:-:|:-:|:-:| | 顶部 header 资源区(只读) | 0 | 0 | 0 | 0 | | 顶部 header 按钮区 | 6 | 6 | 0 | 5(待 P1 拍板) | | 左侧 sidebar | 6 | 6 | 0 | 0 | | 庙前目标卡 | 2(动态 1)+ 1 chip | 3 | 0 | 0 | | 弹窗头部 | 4(头像+3 按钮) | 4 | 0 | 0 | | 弹窗 6 Tab | 6 | 6 | 0 | 0 | | 总览 Tab 入口 | 8 | 8 | 0 | 0 | | 客栈/终局 Tab 内部按钮 | 4 | 4 | 0 | 0 | | 合计(已实装 + 设计稿新增) | ~38 | ~33 | 0 | 5 |

8.2 按目标

| 目标 modal / Tab | 入口数 | 入口 | |:--|:-:|:--| | 同福宝典 | 2 | H2 / S5 | | 开发路线 | 2 | H3 / S6 | | 江湖简报 | 3 | 弹窗头部 / 总览 Tab / S3 | | 事件目录 | 3 | 弹窗头部 / 总览 Tab / S4 | | 七侠镇新掌柜(默认 home) | 2 | H4 / S2 | | 七侠镇新掌柜(默认 account) | 1 | S1 | | 账号 Tab | 3 | 弹窗头像 / H2 / 总览 Tab | | 周目 Tab | 1 | 总览 Tab | | Buff Tab | 1 | 总览 Tab | | 客栈 Tab | 2 | 总览 Tab / 客栈内部 onOpenAction | | 终局 Tab | 2 | 总览 Tab / 客栈内部 review_failure_pressure | | 存档快照浏览器 | 2 | 周目 Tab / 终局 Tab | | 关闭弹窗 | 1 | 弹窗头部 | | 切音效 | 2 | H5 / S7 | | DEV 调试 | 2 | H1 / H6 |

9. 关联文档

10. 文档维护

| 项 | 内容 | |:--|:--| | 文档版本 | v1(2026-07-14) | | 触发 | P1 上传两张「七侠镇新掌柜」截图,要求梳理按钮页面归属 | | 下一步 | P1 拍板 §2.3 五条设计稿新增按钮(实装/砍/挪位);同步更新 §8.1 状态汇总 | | 维护责任 | P1 拍板 · 实施期归实施工人 | | 待 P1 拍板 | (1) §2.3 五按钮实装/砍/挪位 (2) §3 sidebar/header 重复入口去留 (3) §6 「主链」字段是否需要玩家文案收束(AGENTS.md §4 红线) |