№ · UI 重构 CH.06.26
主页 · ✨ UI 重构 · 首页 3.0 精修代码总结 v1

首页 3.0 精修代码总结 v1

📅 2026-06-26 · 📦 18.0 KB · ✨ UI 重构 · 📝 MD 文档 🏷️ Buff🏷️ 规范🏷️ 设计

立 项 时 间：2026-06-26 文档状态：代码现状总结（精修方案的前置文档） 适 用 范 围：Web 横版首页（≥1024px 视口） 阅 读 对 象：开发者 + 设计者

0. 一句话总结

首页由 1 个 4402 行的 App.tsx（编排）+ 6 个桌面组件（壳/顶/侧/中/右/挂）+ 6 个账本子组件（截图里的"经营总览台账"模块）组成。 视觉规范已经成型（古风国风 + 拟物化印章 + 宣纸 + 木质），问题在尺寸/对齐/密度的不一致。

1. 组件树与文件清单

src/
├── App.tsx                                      [4402 行] 编排 + 状态 + 业务
├── index.css                                    [301 行]  全局样式 + 工具类 + 动画
│
├── components/
│   ├── DesktopWorkspacePanel.tsx                [224 行]  桌面横版根容器
│   │   ├── AppHeaderBar.tsx                     [168 行]  顶部状态栏
│   │   ├── StoryTrackingCard.tsx                [62 行]   剧情追踪条
│   │   ├── DesktopSidebar.tsx                   [94 行]   左侧 6 木牌
│   │   ├── MainHallPanel.tsx                    [183 行]  中间大堂主面板
│   │   │   ├── SystemStatusPanel.tsx            [356 行]  4 子卡（账号/周目/Buff/客栈）
│   │   │   └── InnCourt.tsx                     [809 行]  大堂场景（技术债重点）
│   │   ├── DesktopConsolePanel.tsx              [394 行]  右侧控制台壳
│   │   │   ├── ConsoleTabsBar.tsx               [67 行]   10 Tab 网格
│   │   │   ├── LedgerSummaryTab.tsx             [329 行]  账本 tab = "经营总览台账"
│   │   │   │   ├── LedgerHeader.tsx             [63 行]   标题 + 综合稳健度大印章
│   │   │   │   ├── MetricGrid.tsx               [344 行]  7 指标卡（含截图里 4 核心）
│   │   │   │   ├── HumanContentCard.tsx         [212 行]  人手与内容
│   │   │   │   ├── FailureRisksCard.tsx                   失败预警
│   │   │   │   ├── FailureRecordsCard.tsx                 败局记录
│   │   │   │   ├── SuggestionsCard.tsx                    掌柜建议
│   │   │   │   ├── tokens.ts                             7 个 metric tone 定义
│   │   │   │   └── types.ts                              ledger 子类型
│   │   │   ├── StaffTabs / RecipeTab / BackyardTab / KitchenTab / AdventureTab / BaggageTab / FacilitiesTab
│   │   │   ├── AuctionPanel (auction/AuctionPanel.tsx)    官府竞标（737 行）
│   │   │   └── PeerLobby                                  联机同盟
│   │   └── JianghuBriefboard.tsx                [417 行]  右挂悬浮信笺
│   │                                                （技术债重点）

统计：

  • 桌面首页直接相关：12 个组件
  • 总行数：~5,000 行
  • 已知技术债：App.tsx 4402 行 / InnCourt 809 行 / JianghuBriefboard 417 行

2. 关键样式系统（index.css + 散落）

2.1 全局工具类

| 类名 | 用途 | 实现 | | --- | --- | --- | | .tongfu-parchment | 宣纸主卡 | bg #faf3e8 + 4px double 边 + 24px inset 阴影 | | .tongfu-parchment-light | 浅宣纸 | bg #fcf8f2 + 2px 金边 + 8px inset | | .tongfu-crest | 朱红小印 | 旋转 -3° + bg 朱砂透明 + 1px 阴影 | | .tongfu-seal | 朱砂实心印章 | bg #b71c1c + 1px 阴影 + 2px 圆角 | | .tongfu-button-wooden | 木质按钮 | 135deg 木渐变 + 2px 金边 + hover 上扬 | | .tongfu-title | 毛笔字标题 | font-brush + 2px 阴影 | | .tongfu-bubbles | 气泡动画 | @keyframes tongfu-bubble-in/out |

2.2 色值（散落在组件里，未完全集中）

| 用途 | 色值 | 出处 | | --- | --- | --- | | body 背景 | #221208 / 渐变到 #150904 | index.css | | 木深色 | #5d4037 / #4e342e / #3e2723 | 多处 | | 木浅色 | #8d6e63 / #a1887f | 多处 | | 木最浅 | #d7ccc8 | 多处 | | 宣纸 | #fbf7f0 / #fdfbf7 / #faf3e8 / #fffaf2 / #fcf8f2 / #f7f2ea | 多处 | | 朱砂 | #b71c1c / #801010 / #a83232 / #7a2e20 / #8b1a1a / #6e1313 | 多处 | | 灯火 | #c5a059 / #8d4f12 / #b71c1c | 多处 | | 竹青 | #1b5e20 / #3d7a4a / #4a8a52 | 多处 | | 暮红 | #8b3a2e | 散落 | | 蓝灰 | #465969 | 散落 | | 黛绿 | #1f5430 | 散落 |

⚠️ 色值命名混乱：同一个"宣纸"有 5+ 种 hex，同一个"朱砂"有 5+ 种 hex。3.0 精修可考虑统一为 1 个 token 表。

2.3 字号阶梯（散落）

实际使用的字号（从代码 + 截图综合）：

  • text-[7px] / text-[8px] / text-[9px] / text-[10px] / text-[11px] / text-[12px] / text-[13px] / text-[14px] / text-[15px] / text-[16px] / text-[18px] / text-[22px] / text-[24px] / text-[26px]

⚠️ 字号阶梯混乱：14 个不同值。3.0 精修建议归并为 8-9 档。

2.4 圆角

  • rounded-lg (8px) / rounded-xl (12px) / rounded-2xl (16px) / rounded-3xl (24px)
  • 自定义 rounded-[10px] / rounded-[11px] / rounded-[12px]
  • rounded-full (9999px) 胶囊

2.5 字体

index.css 第 4-8 行定义：

--font-sans: "Inter", "system-ui", sans-serif;
--font-serif: "Noto Serif SC", "Playfair Display", Georgia, serif;
--font-brush: "ZCOOL KuaiLe", "Noto Serif SC", serif;

引用方式：font-serif / font-brush / font-metric(自定义) / tabular-nums (Tailwind)

3. 桌面布局断点与栅格

3.1 视口断点

| 视口 | 行为 | | --- | --- | | < 1024px | PortraitWorkspacePanel（竖版） | | ≥ 1024px | DesktopWorkspacePanel（横版） | | ≥ 1680px | 容器 max-w-[1680px] 生效 |

3.2 横版栅格（DesktopWorkspacePanel.tsx 第 130-184 行）

┌─────────────────────────────────────────────────────────────────┐
│  AppHeaderBar                                                   │
├─────────────────────────────────────────────────────────────────┤
│  StoryTrackingCard                                              │
├────────────┬────────────────────────────────┬──────────────────┤
│            │                                │                  │
│ Desktop    │  MainHallPanel                  │  Desktop         │
│ Sidebar    │  ├─ 大堂图                      │  ConsolePanel    │
│ 72px       │  ├─ SystemStatusPanel (4子卡)   │  (children)      │
│            │  └─ InnCourt                    │                  │
│ 6 木牌     │                                 │  ├─ 10 Tab       │
│            │                                │  └─ 内容区       │
│            │                                │                  │
└────────────┴────────────────────────────────┴──────────────────┘
                                                          (右挂)
                                                JianghuBriefboard
                                                (280-300px)

栅格定义：

className="grid flex-1 grid-cols-1 gap-4 min-w-0 
           lg:grid-cols-[minmax(420px,1.4fr)_minmax(760px,1fr)]"

[minmax(420px,1.4fr) _ minmax(760px,1fr)] 表示：

  • 左 MainHallPanel：最小 420px，弹性 1.4 份
  • 右 ConsolePanel：最小 760px，弹性 1 份

⚠️ 断点怪异：用 fr 单位 + minmax，但没考虑 sidebar + briefboard 宽度。在 1280-1440 视口下，ConsolePanel 容易挤压。

4. 各区块现状（基于代码 + 截图综合）

4.1 顶部状态栏（AppHeaderBar.tsx）

┌─[LOGO 块 12px 8px rounded-xl]─[掌柜信息]─[4 状态卡 min-w 不齐]─[5 按钮 32-36px 混]─┐

关键 className：

  • 外层：border-b-4 border-double border-[#8d6e63] bg-[#fbf7f0]/96
  • LOGO 块：bg-gradient-to-br from-[#8d6e63] to-[#5d4037] px-3 py-2 rounded-xl shadow-md border-2 border-[#4e342e]
  • 4 状态卡：flex-1 + 各 min-width（不一致）
  • 5 按钮：高度 32-36px，padding 不齐

关键问题：

  • 4 状态卡 min-width 不统一（截图里前 2 窄后 2 宽）
  • 5 按钮高度不齐
  • max-w 1680 太宽，1280-1440 视口下单行布局会挤

4.2 剧情追踪条（StoryTrackingCard.tsx）

┌─[剧情追踪] [dayLabel chip]─[title]─[下一步]─────────[进度% 180px]─┐

关键 className：

  • rounded-2xl border border-[#d7ccc8] bg-[#fffaf2]/95 px-3 py-2 shadow-sm
  • 进度条：h-2 rounded-full bg-[#efe7dd] + 内部渐变 #8d6e63 → #c5a059
  • 进度条宽：sm:w-[180px]（偏窄）

关键问题：

  • 整体 padding 偏小
  • 进度条偏窄

4.3 左侧导航（DesktopSidebar.tsx）

┌─[门厅] 56×56─┐
│[简报]         │ gap-4
│[事件]         │
│[---分隔---]   │
│[说明]         │
│[路线]         │
│[开声]         │
└────────────────┘

关键 className：

  • 侧栏：hidden md:flex w-[64px] lg:w-[72px]
  • 6 按钮：h-14 w-14 rounded-2xl border ... gap-1（56×56）
  • 中间分隔：my-1 w-8 border-b-2 border-dashed border-[#d7ccc8]
  • 字号：text-[10px] font-bold（偏小）

关键问题：

  • 6 按钮 56×56 偏小（标准 touch target ≥44px，56px 也行但视觉上单薄）
  • 中间虚线分隔突兀
  • 字号 10px 偏小

4.4 中间大堂（MainHallPanel.tsx）

┌─[标题 + 当前食客]─────────────────────────────────────┐
│                                                       │
│  [大堂图 16:9 h-32 sm:h-40 lg:h-44]                   │
│   + 角标 "同福开张" 渐变遮罩                          │
│                                                       │
├─[SystemStatusPanel: 4 子卡 2×4]─────────────────────┤
│  账号 / 周目 / Buff / 客栈                             │
│  (可展开)                                              │
├─[InnCourt] 大堂场景──────────────────────────────────┤
│  8 桌子 + 12 区域 + 贼/垃圾/浮字                     │
│                                                       │
└───────────────────────────────────────────────────────┘

关键 className：

  • 容器：tongfu-parchment p-3.5 sm:p-5
  • 大堂图：h-32 sm:h-40 lg:h-44（16:9 偏方），圆角 16px
  • SystemStatusPanel：紧凑模式 4 子卡（padding 1-1.5px，超小）

关键问题：

  • 大堂图比例 16:9 偏方
  • SystemStatusPanel 4 子卡 padding 极小（1-1.5px），内容挤
  • InnCourt 809 行（技术债，但本次不动）

4.5 右侧控制台（DesktopConsolePanel.tsx）

┌─[10 Tab 网格 grid-cols-2 sm:grid-cols-3]──────────────┐
│  账本 门客 菜谱                                       │
│  后院 后厨 闯荡                                       │
│  行囊 设施 官府竞标                                   │
│  联机同盟                                             │  ← 最后一行 1 个孤立
├─[LedgerSummaryTab 内容区]────────────────────────────┤
│  LedgerHeader: 标题 + 综合稳健度大印章                │
│  MetricGrid: 7 卡（4 核心 + 3 辅助）                  │
│  HumanContentCard: 人手与内容                         │
│  FailureRisksCard: 失败预警                          │
│  FailureRecordsCard: 败局记录                        │
│  SuggestionsCard: 掌柜建议                            │
└───────────────────────────────────────────────────────┘

关键 className：

  • 控制台壳：tongfu-parchment p-3.5 sm:p-5 shadow-[0_18px_36px_rgba(0,0,0,0.18)]
  • Tab：grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-3 gap-2
  • Tab 按钮：min-h-[46px] rounded-xl border ... text-[12px] sm:text-[13px]
  • 内容区：flex-1 overflow-y-auto lg:min-h-0 min-h-[420px] pr-1.5

关键问题：

  • 10 Tab 3 列布局，最后一行 1 个孤立
  • Tab min-h 46px 偏矮
  • 字号 12-13px 偏小

4.6 经营总览台账（ledger/*）

LedgerHeader.tsx — 标题 + 综合稳健度大印章

  • 标题：flex flex-wrap items-center gap-1.5 text-[14px] sm:text-[15px] font-black font-serif
  • 大印章：rounded-xl border px-3 py-2 + 22-26px 大字 + GuofengCornerBadge

MetricGrid.tsx — 7 指标卡（4 核心 + 3 辅助）

  • 网格：grid grid-cols-2 md:grid-cols-4 gap-3
  • Card：relative rounded-xl border p-3 + border-l-4 ${t.accent}
  • 数据：text-[14px] tabular-nums
  • 标题：text-[11px] font-black
  • 右上角 GuofengCornerBadge（朱红印章感标签）
  • 7 个 tone：amber/ochre/cinnabar/plum/cyan/jade/saffron

HumanContentCard.tsx — 人手与内容

  • 容器：rounded-2xl border border-[#d7ccc8] bg-white p-3
  • 6 个 Pill：grid grid-cols-2 sm:grid-cols-3 xl:grid-cols-6
  • 在岗伙计：grid grid-cols-2 sm:grid-cols-4 gap-x-3 gap-y-1.5

关键问题：

  • MetricGrid 4 核心卡 padding p-3（约 12px）偏小
  • 4 核心卡等宽，但视觉权重应区分（截图里"金"和"总"是 chip 颜色不同的）
  • LedgerHeader 综合稳健度大印章尺寸可以更大

4.7 江湖消息悬浮（JianghuBriefboard.tsx）

  • 固定 280-300px 宽
  • lg+ viewport 才显示
  • 倒序渲染 innLogs
  • 复杂样式：6 类单字朱砂印章 / 红线信笺 / 红木画轴 / 落款大印 / 气泡队列

已知问题：

  • 417 行（技术债）
  • fixed 定位在右侧 4px，与主内容抢空间

5. 关键尺寸 / 间距数据表

| 区块 | 关键尺寸 | | --- | --- | | 全局 max-w | 1680px（DesktopWorkspacePanel/AppHeaderBar 6 处都用） | | 顶部 LOGO 块 | 12px 8px（h-padding 8 / v-padding 8），高约 48-56px | | 顶部状态卡 padding | px-3 py-2（12/8）| | 顶部按钮高度 | 32-36px 混 | | 剧情追踪条 padding | px-3 py-2（12/8）| | 剧情追踪条进度条宽 | 180px | | 侧栏宽 | 64-72px | | 侧栏按钮 | 56×56，gap-4（16px）| | 侧栏字号 | 10px | | 大堂图 | h-32 sm:h-40 lg:h-44（128-176px）| | 大堂图圆角 | 16px | | SystemStatusPanel 4 子卡 | padding 1-1.5px（极小）| | 控制台壳 padding | p-3.5 sm:p-5（14/20）| | 控制台 Tab | min-h 46px，padding 10px，圆角 12px | | MetricGrid 4 卡 | padding p-3（12px），圆角 12px | | MetricGrid 网格 | grid-cols-2 md:grid-cols-4 gap-3 | | LedgerHeader 大印章 | 22-26px 数字 |

6. 已知问题清单（精修方向）

| # | 区块 | 问题 | 严重度 | | --- | --- | --- | --- | | 1 | 顶部 4 状态卡 | min-width 不一致（截图里前 2 窄后 2 宽） | 高 | | 2 | 顶部 5 按钮 | 高度不齐（32-36px 混） | 高 | | 3 | 顶部 max-w 1680 | 1280-1440 视口下留白多 / 挤压 | 中 | | 4 | 剧情追踪条 | padding 偏小，进度条 180px 偏窄 | 中 | | 5 | 左侧 6 木牌 | 56×56 偏小、字号 10px 偏小、中间虚线分隔突兀 | 中 | | 6 | 大堂图 | 16:9 偏方，圆角 16px 与其他不一致 | 中 | | 7 | SystemStatusPanel 4 子卡 | padding 极小（1-1.5px），内容挤 | 高 | | 8 | 控制台 10 Tab | 3 列布局最后一行孤立、min-h 46px 偏矮 | 中 | | 9 | MetricGrid 4 核心卡 | padding p-3 偏小 | 中 | | 10 | 控制台与 briefboard | 抢右侧 280-300px 空间，挤压 | 低 | | 11 | 色值命名 | 宣纸 5+ 种、朱砂 5+ 种 hex 散落 | 低 | | 12 | 字号阶梯 | 14 个不同值并存 | 低 |

技术债（非本次 3.0 精修范围）：

  • App.tsx 4402 行
  • InnCourt.tsx 809 行
  • JianghuBriefboard.tsx 417 行
  • 建议下一阶段单独立项"组件拆分重构"，本次不动

7. 资产现状

  • public/icons/tongfu/：16 个 SVG/PNG 图标
  • public/banners/：2 张横幅（tongfu-main-banner.png / tongfu-reunion.png）
  • public/portraits/：5 个角色立绘 + 1 个 tongfu-pack-02 目录
  • public/assets/avatars/：头像包
  • public/assets/ui/：UI 资产

所有资产齐全，本次 3.0 精修不动任何资产。

8. 3.0 精修约束

✅ 可动：

  • className 上的尺寸 / 间距 / 对齐 / 密度
  • 圆角 / 字号
  • 网格列数
  • padding / margin / gap
  • max-w 收紧

❌ 不动：

  • 色值 hex（保留所有现有颜色）
  • 字体 / 字号档位定义
  • 组件拆分（App.tsx、InnCourt、JianghuBriefboard 保持原样）
  • 任何新文件 / 新依赖 / 新图标
  • 任何业务逻辑 / 数据流

9. 验收基线

精修前应当保留的"基线"：

  • 所有 7 类古风工具类（tongfu-parchment / parchment-light / crest / seal / button-wooden / title / bubbles）继续生效
  • 所有 16 个 tongfu 图标继续可用
  • 所有 6 种 metric tone（amber/ochre/cinnabar/plum/cyan/jade/saffron）继续生效
  • 江湖消息悬浮信笺的"朱砂单字印章 / 红线信笺 / 红木画轴"特色保留
  • 经营总览台账的"朱砂印章 + 大字 + corner badge"特色保留
  • 剧情追踪条的"渐变进度条 + dayLabel chip"特色保留

精修后可以优化的"目标"：

  • 1280 / 1440 / 1680 三档视口都有合理表现
  • 4 状态卡 / 4 核心卡 / 6 侧栏木牌内部对齐统一
  • max-w 1680 → 1440（1280-1440 视口下体验提升）
  • 各区块 padding / 字号阶梯统一
  • 10 Tab 3 列最后一行不孤立