hy-farm/docs/godot-architecture-refactor-progress.md

# Godot 架构重构进度

## 本轮已完成

- 新增资源层：
  - `scripts/resources/texture_region_catalog.gd`
  - `scripts/resources/atlas_texture_cache.gd`
- 新增状态层：
  - `scripts/state/player_state.gd`
  - `scripts/state/farm_state.gd`
  - `scripts/state/inventory_state.gd`
- 新增规则层：
  - `scripts/domain/rules/crop_phase_rules.gd`
  - `scripts/domain/rules/land_action_rules.gd`
  - `scripts/domain/rules/cost_rules.gd`
- 新增数据映射层：
  - `scripts/domain/mappers/farm_mapper.gd`
  - `scripts/domain/mappers/inventory_mapper.gd`
- 新增接口服务层：
  - `scripts/services/farm_api.gd`
  - `scripts/services/inventory_api.gd`
  - `scripts/services/building_api.gd`
  - `scripts/services/shop_api.gd`
  - `scripts/services/warehouse_api.gd`
  - `scripts/services/dog_api.gd`
  - `scripts/services/friend_api.gd`
- `game_scene.gd` 已改为通过服务层调用接口，UI 主脚本不再直接写业务接口路径。
- 土地动作判断、作物阶段判断、背包数据提取、土地返回数据归一化已迁出 `game_scene.gd`。
- 顶部 HUD、主菜单、世界菜单、弹窗层/Toast、农场缩放手势已从 `game_scene.gd` 迁出：
  - `scripts/ui/hud/top_bar_view.gd`
  - `scripts/ui/menus/main_menu_controller.gd`
  - `scripts/ui/menus/world_menu_controller.gd`
  - `scripts/ui/common/modal_layer_controller.gd`
  - `scripts/ui/common/ui_motion.gd`
  - `scripts/ui/farm/farm_viewport_controller.gd`
- 公共 UI 构建和图集资源访问已迁出：
- `scripts/ui/common/ui_builder.gd`
- `scripts/ui/common/texture_provider.gd`
- `UiBuilder` 已提供统一面板外框和内容底图入口，素材来自 `assets/replacement/panels/panel_shell.png`、`panel_content.png`，避免各面板继续手写旧 `c_panel/inner_page/common_db_10` 背景。
- Egret MovieClip 帧解析已迁到资源层：
  - `scripts/resources/egret_movie_clip_cache.gd`
  - 当前用于场景宠物 `dog1` swf 帧，避免 UI 面板直接重复解析 `{mc,res}` 图集。
- 土地、背包和种植提示已迁出：
  - `scripts/farm/farm_controller.gd`
  - `scripts/ui/farm/land_grid_view.gd`
  - `scripts/ui/farm/land_action_menu.gd`
  - `scripts/ui/farm/plant_tip_view.gd`
  - `scripts/ui/farm/seed_bag_view.gd`
- 主场景深拆第二阶段已完成：
  - `scripts/ui/game_scene_bootstrap.gd`：装配服务、状态、规则、Facade、FarmController 和面板模块。
  - `scripts/ui/game_scene_runtime_assembler.gd`：装配顶部 HUD、主菜单、世界菜单、弹窗层、宠物展示、农场缩放、土地网格、土地动作菜单、种子背包、种植提示和运行时 hit 路由。
  - `scripts/ui/game_scene_panel_router.gd`：统一承接商店、仓库、好友、房屋/土地扩建、狗窝、活动、支付、宠物等弹窗入口。
  - `scripts/ui/scene_hit_router.gd`：顶部/左侧入口、农场建筑入口、直接命中兜底。
  - `scripts/ui/farm/farm_interaction_coordinator.gd`：土地点击、长按、选中光圈、动作菜单、种子/肥料背包和作物提示。
  - `scripts/state/player_inventory_facade.gd`：仓库刷新、奖励发放、消耗扣除、货币和狗饥饿时间写入。
  - `scripts/ui/game_scene_context.gd`：收敛面板和 UI 模块共享依赖，替代 Bootstrap 中的大 callback 字典。
  - `scripts/state/player_state.gd`：合并原 `PlayerDataAccessor`，作为玩家快照唯一权威来源。
  - `scripts/ui/common/icon_texture_provider.gd`：缓存物品、宠物、作物和房屋图标加载。
- 面板按功能拆成独立模块：
  - `scripts/ui/panels/shop_panel.gd`
  - `scripts/ui/panels/warehouse_panel.gd`
  - `scripts/ui/panels/friend_panel.gd`
  - `scripts/ui/panels/building_panel.gd`
  - `scripts/ui/panels/dog_panel.gd`
  - `scripts/ui/panels/log_panel.gd`
  - `scripts/ui/panels/notice_panel.gd`
  - `scripts/ui/panels/level_gift_panel.gd`
  - `scripts/ui/panels/online_gift_panel.gd`
  - `scripts/ui/panels/pay_panel.gd`
  - `scripts/ui/panels/welfare_panel.gd`
  - `scripts/ui/panels/gold_exchange_panel.gd`
  - `scripts/ui/panels/world_info_panel.gd`
  - `scripts/ui/panels/sign_panel.gd`
  - `scripts/ui/panels/box_panel.gd`
  - `scripts/ui/panels/lottery_panel.gd`
  - `scripts/ui/panels/pet_panel.gd`
- 修复了土地数据收集逻辑，改由 `FarmState.setup_from_player_data()` 统一归一化。
- 删除了临时 `DEBUG/print` 调试输出。

## 当前保留在 GameScene 的职责

`game_scene.gd` 当前 957 行，已低于 1200 行目标；保留职责收敛为场景生命周期、常驻节点引用、上下文桥接、土地快照渲染和少量兼容状态同步。已完成本阶段深拆：

- `GameSceneBootstrap` 已接管 `_setup_architecture_modules()` 和原 `_setup_panel_views()` 装配逻辑。
- `GameSceneRuntimeAssembler` 已接管 HUD/菜单/弹窗/宠物/土地交互运行时装配。
- `GameScenePanelRouter` 已接管 `_open_*_panel` 方法族、房屋/土地扩建入口包装和弹窗 active 状态。
- `SceneHitRouter` 已接管顶部/左侧/土地建筑点击区域注册和直接命中检测。
- `FarmInteractionCoordinator` 已接管长按、土地选择、背包打开、土地高亮等交互胶水。
- `PlayerInventoryFacade` 已接管奖励发放、消耗扣除、仓库刷新等跨模块状态写入。
- `GameSceneContext` 已接管面板共享依赖和 legacy callback 兼容层。
- `PlayerState` 已合并原 `PlayerDataAccessor`，主场景 token、房屋等级、狗饥饿时间等玩家字段访问统一从 `PlayerState` 读取/写入。

下一阶段建议转入 P1 功能拆分：好友完整互动、世界玩法、活动面板像素级对齐，并继续把旧面板从 legacy callbacks 迁到显式 `GameSceneContext` 方法。

## 已验证

- `game_scene.gd` 和新增 UI 控制器/面板模块通过 Godot `--check-only`。
- `game_scene_bootstrap.gd`、`game_scene_context.gd`、`game_scene_runtime_assembler.gd`、`game_scene_panel_router.gd`、`scene_hit_router.gd`、`farm_interaction_coordinator.gd`、`player_inventory_facade.gd`、`player_state.gd` 均通过 Godot `--check-only`。
- 新增资源、状态、规则、Mapper、Service 脚本全部通过 `--check-only`。
- 工程导入通过：`godot --headless --path godot/FarmGodot --import --quit`。
- P0 验证通过：`godot --headless --path godot/FarmGodot --script res://tools/verify_p0.gd`。
- Web 导出通过：`godot --headless --path godot/FarmGodot --export-release Web build/web/index.html`。
- 本地 H5 预览通过：`http://127.0.0.1:8792/index.html`。
- 自动登录成功，请求 `user/login` 返回 HTTP 200，业务 `status=0`。
- 背包请求 `store-house` 返回 HTTP 200，业务 `status=0`。
- 主场景、土地菜单打开/关闭、主菜单、世界菜单、弹窗、缩放和新增功能入口完成浏览器烟测：`npm run smoke:godot:web`。
- 宠物功能本轮验证通过：`pet_panel.gd`、`egret_movie_clip_cache.gd`、`game_scene.gd`、`game_scene_bootstrap.gd`、`game_scene_runtime_assembler.gd` 通过 `--check-only`；工程 `--import --quit` 和 Web 导出通过；浏览器截图确认主场景宠物、战宠面板、狗窝牌子入口均可用。
- 战宠面板经验条补充验证通过：按 `BattleProssBar2Skin.exml` 的九宫格背景和遮罩结构重做进度条，Web 截图确认经验条不再穿出面板；`pet_panel.gd` 通过 `--check-only`，Web 导出和 `npm run smoke:godot:web` 均通过。
- 家园宠物点击行为补充验证通过：对照旧版 `WidgetDog`，移除场景宠物显示节点、运行时装配层和直接命中路由里的 `open_pet_panel` 绑定；点击家园宠物不再打开战宠面板，世界菜单的战宠入口仍可打开；相关脚本通过 `--check-only`，Web 导出和 `npm run smoke:godot:web` 均通过。
- 统一面板背景本轮验证通过：`batch_prepare_icons.py` 可用 `--cutout` 抠出两张透明素材；所有受影响面板脚本通过 `--check-only`；工程 `--import --quit`、Web 导出、`npm run smoke:godot:web` 和补充 Playwright 截图均通过。
- 异步面板关闭防护本轮验证通过：`LevelGiftPanel` 复现路径已修复，公告、日志、好友、兑换记录、宝箱、签到、福利、宠物、世界信息等同类异步面板增加节点存活校验；相关脚本通过 `--check-only`，Web 导出、`npm run smoke:godot:web` 和等级礼包快速打开/关闭 Playwright 检查均通过。
- 房屋升级和用户信息面板本轮验证通过：`BuildingPanel` 的房屋升级按钮坐标回到旧 EXML 主内容组顶部位置，不再遮盖房屋；`PlayerInfoPanel` 顶部资料区补统一内容底图，标题改用 `roleinfo` 图集标题，用户 ID 清理为整数文本；`BoxPanel`、`LotteryPanel` 右侧装饰节点补显式类型，修复 Web 编译时类型推断失败；相关脚本通过 `--check-only`，Web 导出、Playwright 截图和 `npm run smoke:godot:web` 均通过。

## 验证产物

- `docs/ui-baseline/godot-architecture-refactor-main.png`
- `docs/ui-baseline/godot-architecture-refactor-land-menu.png`
- `docs/ui-baseline/godot-architecture-refactor-land-menu-closed.png`
- `docs/ui-baseline/godot-architecture-refactor-main-menu.png`
- `docs/ui-baseline/godot-architecture-refactor-meta.json`
- `docs/ui-baseline/smoke/*.png`
- `docs/ui-baseline/godot-pet-main.png`
- `docs/ui-baseline/godot-pet-panel.png`
- `docs/ui-baseline/godot-pet-doghouse-click.png`
- `docs/ui-baseline/godot-pet-scene-click-no-panel.png`
- `docs/ui-baseline/godot-world-pet-entry-still-opens.png`
- `docs/ui-baseline/godot-panel-background-shop.png`
- `docs/ui-baseline/godot-panel-background-warehouse.png`
- `docs/ui-baseline/godot-panel-background-friend.png`
- `docs/ui-baseline/godot-panel-background-pet.png`
- `docs/ui-baseline/godot-pet-panel-expbar-fixed.png`
- `docs/ui-baseline/godot-panel-background-dog.png`
- `docs/ui-baseline/godot-house-upgrade-button-position-fixed.png`
- `docs/ui-baseline/godot-player-info-bg-fixed.png`
- `docs/ui-baseline/godot-player-info-title-id-fixed.png`