主厅总览页精简方案 v1.0 · 活跃设计

保留 4 个固定布局 + 同福大堂，去掉人物关系图 · 设计 → 代码施工蓝图

触发：用户拍板主厅总览页布局清单 — 只要"左边按钮 / 上边按钮 / banner 上面初入江湖 / 飞鸽传书 / 同福大堂面貌"5 个固定布局，不要人物关系图目标：明确保留 vs 去掉的清单；明确实施步骤（哪些已经满足、哪些需要新增/精简）工期：1-2 个工作日（多数组件已就位，主要工作是确认 + 微调）

0. 元信息

| 项 | 内容 | | :--- | :--- | | 文档版本 | v1.0 / 2026-07-07 | | 配套文档 | AGENTS.md / DesktopWorkspacePanel.tsx / MainHallPanel.tsx / DesktopSidebar.tsx / AppHeaderBar.tsx / JianghuBriefboard.tsx | | 范围（做） | 确认保留 5 个固定布局；按需新增 1-2 个 dashboard 卡片（客栈状态 / 经营总览 / 伙计状态）；保证人物关系图不出现 | | 范围（不做） | 不实现人物关系图（含 7 侠关系网 + 羁绊可视化）；不重写 DesktopWorkspacePanel 编排层；不动 InnCourt 8 桌散落大堂布局；不动 sidebar / top nav / 飞鸽传书现有功能 | | 完成标准 | npm run lint 无新增错误；npm run build 通过；游戏启动后能直观看到保留的 5 个固定布局；任何"人物关系图"形态不出现 |

核心原则：

严格按 AGENTS.md 三层架构（数据层 / 逻辑层 / UI 层）
复用现有组件优先（SystemStatusPanel / InnCourt / JianghuBriefboard / DesktopSidebar / AppHeaderBar / StoryTrackingCard）
每个 T = 1 个 commit / 1 个 PR，可回滚

1. 用户需求清单（拍板）

✅ 保留（5 个固定布局）

| # | 元素 | 当前实现 | 状态 | | :-: | :--- | :--- | :---: | | 1 | 左边按钮 | src/components/DesktopSidebar.tsx（6 个图标：总览 / 订单 / 账目 / 事件 / 伙计 / 设置） | ✅ 已就位 | | 2 | 上边按钮 | src/components/AppHeaderBar.tsx（同福客栈 logo + 开始经营 / 排行榜 / 百科 / 新闻公告 / 下载 / 登录注册 + 状态显示） | ✅ 已就位 | | 3 | banner 上面「初入江湖」 | src/components/StoryTrackingCard.tsx（庙前目标卡，初始显示「初入江湖：经营同福客栈 10 日」） | ✅ 已就位 | | 4 | 飞鸽传书 | src/components/desktop/JianghuBriefboard.tsx（固定悬浮右抽屉） | ✅ 已就位 | | 5 | 同福大堂面貌 | src/components/MainHallPanel.tsx line 89-116（大合照 banner）+ src/components/InnCourt.tsx（8 桌散落大堂） | ✅ 已就位 |

❌ 划走（明确不做）

| # | 反需求 | 原因 | | :-: | :--- | :--- | | 1 | 人物关系图（7 侠关系网 / 羁绊可视化 / 关系线） | 用户拍板不要；当前代码也没有实现，无需删除 | | 2 | 人物关系图相关的 dashboard 卡片（含 7 侠头像 + 关系线 + 姻缘 / 姑嫂 / 亲家 / 姑爷 / 闺蜜等标签） | 同上 | | 3 | 任何形式的"羁绊可视化大图" / "家庭关系树" / "江湖人物网络" | 同上 | | 4 | 重写 DesktopWorkspacePanel / MainHallPanel / App.tsx 编排层 | 5 日反需求清单 § 5.2 / AGENTS.md § 7（不重写 App.tsx） | | 5 | InnCourt 大堂 8 桌散落布局改成"人物关系图"等其他形态 | 用户拍板保留同福大堂面貌 |

⚠️ 关键洞察：当前代码本来就没有「人物关系图」！用户给的参考图是设计稿灵感，不是当前代码状态。本切片的核心工作是确认当前代码已满足用户需求，只新增用户截图里其他合理的 dashboard 卡片（客栈状态 / 经营总览 / 伙计状态），绝不碰人物关系图。

2. 现状 vs 用户需求对照

2.1 现有 DesktopWorkspacePanel 顶层结构

┌──────────────────────────────────────────────────┐
│  AppHeaderBar (顶部 nav)                          │  ← ① 上边按钮 ✅
├──────────────────────────────────────────────────┤
│  StoryTrackingCard (庙前目标 · 「初入江湖」)     │  ← ③ banner 上面「初入江湖」 ✅
├──────────────────────────────────────────────────┤
│ ┌────┐ ┌──────────────────┐ ┌──────────────┐   │
│ │    │ │ MainHallPanel    │ │ children     │   │
│ │Side│ │ ├ 同福大堂 banner │ │ (控制台)     │   │
│ │bar │ │ ├ SystemStatusPanel│ │             │   │
│ │ 6  │ │ ├ InnCourt 大堂  │ │             │   │
│ │图标│ │ └ 江湖消息 LOG   │ │             │   │
│ │    │ │                  │ │             │   │
│ └────┘ └──────────────────┘ └──────────────┘   │
│           ④ ①                                  │
├──────────────────────────────────────────────────┤
│  footer                                          │
│  + JianghuBriefboard (飞鸽传书) — fixed 右抽屉   │  ← ④ 飞鸽传书 ✅
└──────────────────────────────────────────────────┘

对照用户需求：

✅ ① 上边按钮（AppHeaderBar）— 已有
✅ ② 左边按钮（DesktopSidebar）— 已有
✅ ③ banner 上面「初入江湖」（StoryTrackingCard）— 已有
✅ ④ 飞鸽传书（JianghuBriefboard）— 已有
✅ ⑤ 同福大堂 banner + InnCourt 大堂（MainHallPanel）— 已有

缺口：用户截图里的 客栈状态 / 经营总览 / 伙计状态 三个 dashboard 卡片目前没有（SystemStatusPanel 不是这个语义）。本切片 T2 阶段按需新增。

2.2 关键代码定位

| 元素 | 文件 | 行 | 备注 | | :--- | :--- | :---: | :--- | | 顶层布局 | src/components/DesktopWorkspacePanel.tsx | 130-262 | 264 行总长，编排层 | | 左边按钮 | src/components/DesktopSidebar.tsx | 全文件 | 6 图标 + 系统按钮 | | 上边按钮 | src/components/AppHeaderBar.tsx | 全文件 | logo + nav + 状态 | | 庙前目标 | src/components/StoryTrackingCard.tsx | 全文件 | 顶部 sticky 卡 | | 同福大堂 banner | src/components/MainHallPanel.tsx | 89-116 | h-56 sm:h-64 + 大合照 | | 同福大堂 InnCourt | src/components/InnCourt.tsx | 全文件 | 8 桌散落大堂背景 | | 飞鸽传书 | src/components/desktop/JianghuBriefboard.tsx | 全文件 | fixed 右抽屉 |

3. 实施切片

T1. 现状确认 + 反需求卡片审查（半天）

目标：跑一遍当前代码，确认 5 个保留元素全部就位、人物关系图确实不存在。

执行：

npm run dev 启动游戏，进桌面模式
截图桌面模式主厅布局
对照用户截图（参考设计稿）写差异表
检查 StoryTrackingCard 是否显示「初入江湖」
检查 JianghuBriefboard 是否在右抽屉
检查 MainHallPanel 是否渲染同福大堂 banner + InnCourt
grep 确认「人物关系图 / 羁绊可视化 / 关系网」等关键词在生产代码里都不渲染

新增/改动：无（纯确认）

验收：

npm run lint 通过（无改动）
截图存档 docs/design/active/screenshots/mainHall现状-v1.png
反需求清单（本文档 § 1.❌）全部确认

T2. 新增 dashboard 卡片（可选 · 1 天）

目标：如果 T1 确认用户截图里的「客栈状态 / 经营总览 / 伙计状态」三个 dashboard 卡片值得做，新建三个轻量组件挂到 MainHallPanel。

新建文件（按三层架构）：

src/components/dashboard/InnStatusCard.tsx —— 客栈状态（黄金 / 声望 / 伙计总数 / 客栈等级 + 满意度 / 清洁度进度条）
src/components/dashboard/BusinessOverviewCard.tsx —— 经营总览（黄金收入 / 营业支出 / 净利润 / 食材储备 / 客商入住率 / 江湖声望）
src/components/dashboard/StaffStatusCard.tsx —— 伙计状态（每人一行：头像 + 名字 + 状态条 + 状态标签）

三层架构守则：

数据层（如需新增 type / 常量）→ src/data/dashboard/types.ts

逻辑层（如需派生计算）→ src/utils/dashboard/statusLogic.ts

UI 层 → 上述 3 个 .tsx 组件

改动文件：

src/components/MainHallPanel.tsx —— 在同福大堂 banner 下方插入 3 个卡片（按用户截图布局：客栈状态左、伙计状态右、经营总览中间）

3 个卡片的视觉规范（参考用户截图）：

客栈状态：6 数字卡（grid-cols-4）+ 2 进度条（满意度/清洁度）
经营总览：6 统计卡（grid-cols-3）
伙计状态：每人一行紧凑列表（avatar + name + 状态条 + chip）
配色：朱砂红 + 琥珀金 + 翠绿 + 浅米色，跟现有 SystemStatusPanel / StaffTabs 调性一致
拟物化：复用 TongfuPaper / TongfuSeal / TongfuInkDot

验收：

3 个 .tsx 组件独立可复用
不引入新 tsc 错误
不破坏现有 MainHallPanel / InnCourt 渲染
视觉对照用户截图（differences 标注）

T3. 视觉对照 + 回归测试（半天）

目标：跑通 5 个保留元素 + 3 个 dashboard 卡片（如果 T2 做了），确认人物关系图不出现。

新增文件：

docs/design/active/主厅总览页精简方案-v1-checklist.md

checklist 内容：

# 主厅总览页精简方案回归 Checklist v1.0

## A. 代码质量
- [ ] `npm run lint` 通过（tsc --noEmit 无新增错误；保持现有 66+ 旧错误不变）
- [ ] `npm run build` 通过
- [ ] 无新增 `any` 类型

## B. 5 个保留元素（用户拍板）
- [ ] ① 左边按钮 = DesktopSidebar 6 图标全可见 + 可点击
- [ ] ② 上边按钮 = AppHeaderBar nav + 状态显示全可见
- [ ] ③ banner 上面「初入江湖」 = StoryTrackingCard 显示庙前目标
- [ ] ④ 飞鸽传书 = JianghuBriefboard 在右抽屉，可展开/收起
- [ ] ⑤ 同福大堂 = MainHallPanel banner + InnCourt 8 桌散落

## C. 反需求（用户拍板不做）
- [ ] ❌ 人物关系图（7 侠关系网）不出现
- [ ] ❌ 羁绊可视化大图不出现
- [ ] ❌ 家庭关系树不出现
- [ ] ❌ 江湖人物网络图不出现
- [ ] grep 确认生产代码里没有 "人物关系图 / 关系网 / 姻缘 / 姑嫂 / 亲家 / 姑爷 / 闺蜜" 等关系网渲染

## D. 视觉对照（跟用户截图 v1.0 参考图对）
- [ ] sidebar 6 图标布局跟用户截图一致
- [ ] 顶部 nav + 状态显示布局跟用户截图一致
- [ ] 庙前目标卡显示「初入江湖」初始化文本
- [ ] 同福大堂 banner 显示大合照 + 「七侠齐聚」标题 + 「七侠齐聚大团圆，笑语欢声满同福。」描述
- [ ] InnCourt 8 桌散落大堂背景图正常
- [ ] 飞鸽传书右抽屉可见，6 类朱砂印章（传/闻/警/银/习/名）正确

## E. 功能完整性
- [ ] 桌面模式 → 进游戏 → 主厅布局 5 元素全可见
- [ ] 点击 sidebar 图标 → 弹出对应 modal
- [ ] 点击飞鸽传书 → 展开/收起切换
- [ ] 点击桌位 → onTableClick 触发 → 顾客入座正常
- [ ] 现有 InnCourt / StoryTrackingCard / JianghuBriefboard 功能不破坏

## F. 手动测试场景
1. 开新档 → 进游戏 → 看桌面模式主厅 → 5 元素全可见
2. 截图存档，跟用户参考图对比
3. 切换 sidebar 各 tab → 各 modal 弹出正常
4. 切换飞鸽传书 → 展开/收起
5. 玩 1 个周期（开档 → 进游戏 → 等 30 秒 → 看 InnCourt 顾客状态）

4. 验收清单（汇总）

每个 T 完成后：

npm run lint
npm run build
npm run dev   # 手动玩一遍：开档 → 进游戏 → 看主厅布局

T3 完成后跑完整 checklist（见 § 3 T3）。

5. 回滚方案

| T | 回滚方式 | 风险 | | :-: | :--- | :--- | | T1 | 无代码改动，无回滚 | — | | T2 | git revert T2-commit —— 删除 3 个 .tsx + MainHallPanel.tsx 改动 | 低（纯新增） | | T3 | 删除 checklist 文件 | 低 |

6. 与设计文档的对应

7. 后续 Phase 预告（不在本切片范围）

❌ 明确不在任何 Phase：人物关系图（7 侠关系网 / 羁绊可视化）。用户拍板不要，本文档 § 1 已划走。

8. 实施节奏建议

| 工作日 | 任务 | 备注 | | :---: | :--- | :--- | | 第 1 天上午 | T1 现状确认 + 反需求 grep + 截图存档 | 半天 | | 第 1 天下午 | T2 新增 dashboard 卡片（如需要） | 半天-1 天 | | 第 2 天 | T3 回归测试 + checklist | 半天 |

每天 commit 一次，PR 互相独立可 review。

附录 A. 用户原话存档（避免跑偏）

用户原话（2026-07-07）： "我只要左边按钮，上边按钮，banner上面初入江湖这个，然后飞鸽传书，这几个固定布局。人物关系图不要，依然保留我们的同福大堂面貌布局。"

用户确认（2026-07-07）： "对的，先落文档。"

翻译：

保留：左边按钮（DesktopSidebar）+ 上边按钮（AppHeaderBar）+ banner 上面「初入江湖」（StoryTrackingCard）+ 飞鸽传书（JianghuBriefboard）+ 同福大堂（MainHallPanel banner + InnCourt）
去掉：人物关系图（用户截图里的 7 侠关系网）—— 当前代码里本来就没有，但要确保后续不新增

附录 B. 不在本切片范围（明确划走）

❌ 人物关系图（7 侠关系网 / 姻缘 / 姑嫂 / 亲家 / 姑爷 / 闺蜜关系线）
❌ 羁绊可视化大图（含 7 侠头像 + 关系网）
❌ 家庭关系树
❌ 江湖人物网络图
❌ 重写 DesktopWorkspacePanel / MainHallPanel 编排层
❌ 改 InnCourt 8 桌散落大堂布局（用户拍板保留）
❌ 动 sidebar / top nav / 飞鸽传书现有功能
❌ 修 66+ tsc 旧错误（AGENTS.md §7）
❌ 动 portrait 头像素材（不动 .png / portraits.ts URL）

主厅总览页精简方案 v1.0 完。 等你拍板开 T1，还是先讨论切片本身？