同福客栈挂机游戏 - 素材使用审计报告 v1

整理时间:2026-07-02 15:00 +08:00 | 整理人:Mavis 性质:代码 vs 素材 对照表(诊断 + 落地摘要) 范围:src//*.{ts,tsx} x public//*.{png,svg,webp,jpg} 本轮变更:完成 6 背景 + 16 图标 + 20 头像 剪裁 + 落档 + 重命名

0. TL;DR

• 本轮剪裁 42 件,全部已就位
  • 6 背景 -> public/bg/scenes/(backlog P0-1..P0-6 1:1 对齐)
  • 16 图标 -> public/icons/tongfu/(替换原 16 个低清占位,透明背景)
  • 20 头像 -> public/assets/avatars/(替换原 20 个 webp 低清占位,正确命名)
• 代码 vs 素材引用情况
  • 图标:16 个全部被代码使用(19 个文件、267 处引用)
  • 头像:20 个全部被代码预留路径 + 6 个主角色被实际使用
  • 背景:0 处代码引用 - 落档后备,等接入
• 真正未被代码引用的占位素材:
  • public/icons/tongfu/attr/*.svg x 7
  • public/icons/tongfu/func/*.svg x 8
  • public/icons/tongfu/buff/*.svg x 60+
  • public/icons/tongfu/wulin/*.svg x 12
  • public/assets/ui/unpacked/atlas_{1,2,3}sprite*.png x 32
  • stitch 设计稿 + 大团圆/6人照 等 x 14
  • 早期裁切残留 x 8

1. 项目代码里"已用"的素材(实测)

1.1 16 个图标 - 全部已用(267 处引用,19 个文件)

中央注册表:src/components/tongfuIcons.tsx(L9-26)

16 个键:coin / reputationFan / broom / arrestToken / billScroll / foodBowl / abacus / ledgerBook / recruitSign / recipeScroll / backyardWell / kitchenWok / adventureBundle / baggageSack / facilityHammer / allianceFists

物理文件全部在 public/icons/tongfu/{name}.png(本轮全部升级高清)

主要使用方(共 20 个文件): App.tsx / BaggageTab.tsx / AdventureTab.tsx / ConsoleTabsBar.tsx / RandomEventPopup.tsx / KitchenTab.tsx / BackyardTab.tsx / RecipeTab.tsx / AppHeaderBar.tsx / InnCourt.tsx / StaffRegisterModal.tsx / DesktopSidebar.tsx / MainHallPanel.tsx / StaffTabs.tsx / TongfuSkillPanel.tsx / FacilitiesTab.tsx / PlaythroughPanel.tsx / PeerLobby.tsx / LedgerAuditModal.tsx / HelpManual.tsx

1.2 6 个主角色头像 - 全部已用

| 物理文件 | 代码引用 | 引用方 | | :-: | :-: | :--- | | public/portraits/tong.png | STAFF_PORTRAITS.tong | staffVisuals.ts -> StaffTabs.tsx L126 + StaffRegisterModal.tsx L205 | | public/portraits/li.png | STAFF_PORTRAITS.li | 同上 | | public/portraits/bai.png | STAFF_PORTRAITS.bai | 同上 | | public/portraits/guo.png | STAFF_PORTRAITS.guo | 同上 | | public/portraits/lu.png | STAFF_PORTRAITS.lu | 同上 | | public/portraits/mobei.png | portraitUrl: /portraits/mobei.png | gameData.ts L351 + data/customers/index.ts L19 |

这 6 个文件本轮未动(已存在的高清版本,沿用)。

1.3 20 个 NPC 头像 - 路径已预留(占位已升级)

• 代码路径:TONGFU_PORTRAIT_BASE = /assets/avatars(src/gameData.ts L316 + src/data/portraits.ts L6)
• 使用方:InnCourt.tsx L910 seated.portraitUrl - 客栈内顾客落座时显示头像
• 本轮动作:public/assets/avatars/01-20.webp 全部替换为高清 .png

1.4 2 个 Banner - 已用

• public/banners/tongfu-main-banner.png - MainHallPanel.tsx L101
• public/banners/tongfu-reunion.png - FacilitiesTab.tsx L364

2. 项目里未用 / 占位的素材(本轮剪裁无关,但要心里有数)

2.1 SVG icon library(public/icons/tongfu/{attr,func,buff,wulin}/) - 87 件,代码 0 引用

• attr/icon_attr_*.svg x 7(security / inventory / cashflow / staff / traffic / reputation / hygiene)- 这正是 backlog §2.2 P0 6+1 项
• func/icon_save_.svg + icon_event_.svg + icon_msg_*.svg + icon_heritage_point.svg x 8 - 这正是 backlog §2.3 P0 7 项
• buff/buff_*.svg x 60+(客栈状态 / 员工 / 夜防 / 社交 / 天气 / 官府 等)
• wulin/01-12-*.svg x 12(令牌/灯笼/算盘/铜钱/卷轴/酒坛/扇/刀/牌/包袱/葫芦/告示)

现状:这是项目的"远期 icon 库",没有任何 ts/tsx 文件 import 它们。两套体系是并行不悖的:

• 手绘 PNG 16 件 <- 当前线 <- 本轮已升级高清版
• SVG 库 87 件 <- 远期线 <- 暂未接入

2.2 UI 设计稿 + atlas(public/assets/ui/) - 53 件,代码 0 引用

• unpacked/atlas_{1,2,3}sprite*.png x 32 - 早期 sprite atlas 拆片
• stitch_*.png x 9 + banner.png + portrait_bg.png + 6人照.png + 大团圆.png - stitch 设计稿
• slices/_archive/*.png x 7 - 早期切图归档
• cropped/{ui-components,scenes,icons-portraits}/*.png + manifest.json - 早期裁切成果

2.3 4 个根目录大图(剧情插画.png / 白展堂与佟湘玉.png / 郭芙蓉跟吕秀才.png / 大团圆.png) - 未裁切

代码 0 引用,本轮也未动。属于"未来剧情插画"备料。

2.4 7 个剧情复合图(pic/剧情/剧情1-7.png) - 未裁切

代码 0 引用,未动。

2.5 9 宫格表情包(pic/佟湘玉9宫格表情包.png + 圆版.png) - 未裁切

代码 0 引用,未动。可用于客栈"掌柜/员工反应表情"- 但代码当前用 emoji 替代了这些头像。

3. 本轮剪裁 42 件 x 代码对接表

3.1 6 个背景(全部已对接 backlog P0,代码暂未引用)

| 落档 | backlog 对应 | 状态 | | :-: | :-: | :--- | | public/bg/scenes/account_empty.png | P0-1 bg_account_empty | 落档,代码未接 | | public/bg/scenes/save_empty.png | P0-2 bg_save_empty | 落档,代码未接 | | public/bg/scenes/status_danger.png | P0-3 illu_status_danger | 落档,代码未接 | | public/bg/scenes/status_good.png | P0-4 illu_status_good | 落档,代码未接 | | public/bg/scenes/gameover_pressure.png | P0-5 bg_gameover_pressure | 落档,代码未接 | | public/bg/scenes/gameover_warning.png | P0-6 bg_gameover_warning | 落档,代码未接 |

3.2 16 个图标(全部代码已用,本轮升级高清版)

16 个图标全部在 public/icons/tongfu/{name}.png: coin / reputation-fan / broom / arrest-token / bill-scroll / food-bowl / abacus / ledger-book / recruit-sign / recipe-scroll / backyard-well / kitchen-wok / adventure-bundle / baggage-sack / facility-hammer / alliance-fists

3.3 20 个头像(全部已对接预留路径,本轮升级 webp -> png)

20 个头像全部在 public/assets/avatars/{NN-pinyin}.png: 01-xing-butou / 02-yan-xiaoliu / 03-zhu-wushuang / 04-xiao-mi / 05-qian-zhanggui / 06-qian-furen / 07-sai-xishi / 08-ji-wubing / 09-guo-juxia / 10-bai-sanniang / 11-zhan-hongling / 12-ling-tengyun / 13-bao-daren / 14-duan-zhi-xuanyuan / 15-jianghu-daoke / 16-gankao-shusheng / 17-zoujie-huolang / 18-linjia-guniang / 19-huashan-xiamei / 20-shijing-daniang

4. 命名/路径一致性自检

| 检查项 | 结果 | | :-: | :--- | | 16 图标 命名 vs tongfuIcons.tsx 路径 | 1:1 对齐(本轮修正 1 处:lineage -> recipe-scroll 对齐代码) | | 20 头像 命名 vs assets/avatars/ 既有命名 | 1:1 对齐(本轮修正 2 处:npc-beggar -> 04-xiao-mi, npc-wanderer -> 15-jianghu-daoke) | | 6 背景 落档路径 | 跟 backlog 2.1 指定 public/bg/scenes/ 一致 | | 透明背景(图标) | 白色像素已转 alpha=0 | | 干净裁切(背景) | 顶 label band + 底 path-hint 已裁掉 | | 干净裁切(图标) | 底 label band 已裁掉 | | 干净裁切(头像) | 全图无文字 |

5. 下一步可选动作(给 P1 拍板)

1. 接入 6 张背景(backlog P0-1..P0-6) - 在 MainHallPanel.tsx / 启动页 / EndgamePanel.tsx 加 import, 0.5h
2. 接入 60+ Buff SVG(public/icons/tongfu/buff/*.svg) - 类似 tongfuIcons.tsx 写个 tongfuBuffIcons.tsx 注册表, 1-2h
3. 接入 12 件武林 SVG(public/icons/tongfu/wulin/*.svg) - 同上模式, 0.5h
4. 接入 7 件剧情大图 + 9 宫格表情 - 表情可在 InnCourt.tsx 替代当前 emoji, 大图做剧情背景, 1h
5. 清理 public/assets/ui/cropped/icons-portraits/01.png - 早期裁切残留, 需确认是否还在用
6. 跑一次 npm run build - 验证新图无破坏(已有 26+ 个旧 tsc 错误是设计之外的)

6. 不做什么(明确划走)

• 不动 tongfuIcons.tsx / staffVisuals.ts / data/portraits.ts / gameData.ts 等代码层 - 本轮 0 代码改动
• 不重命名 tongfuIcons.tsx 里的键(已 1:1 对齐)
• 不动 public/icons/tongfu/{attr,func,buff,wulin}/ 任何 SVG - 这是远期线, 本轮不碰
• 不改 docs/uirefactor/素材清单.md - 清单维护走 PM 单独流程
• 不派生新 worker(本任务是审计, 不是 in-flight 派发)