hy-farm/docs/godot-refactor-status-priority.md

Godot 重构进度与功能缺口优先级

更新时间：2026-05-12

依据

本清单基于当前本地代码和原 H5 参考核对，不按记忆推断。

• Godot 当前实现：godot/FarmGodot/scripts/ui/game_scene.gd
• Godot 服务层：godot/FarmGodot/scripts/services/*.gd
• Godot 配置层：godot/FarmGodot/scripts/core/game_config_catalog.gd
• 原 H5 面板通知：muchang/home/web/game/js/main/00-runtime-and-notify.js
• 原 H5 主场景入口：muchang/home/web/game/js/main/03-game-ui-core.js
• 原 H5 面板和中介：muchang/home/web/game/js/main/05-config-and-panels.js、07-mediators.js
• 原 H5 世界/宠物/游乐园/竞技：13-world-features.js、15-battle-pet-full.js、16-amusement-park-full.js、17-sports-full.js
• 最近验证截图：docs/ui-baseline/godot-new2-final-*.png

当前重构进度

已完成

• Godot 4.6.2 工程、Web 导出预设和 H5 本地预览流程。
• Egret 原资源同步到 godot/FarmGodot/assets/egret/。
• 自动登录：13800000001 / 123456。
• 后端协议：ApiClient 已按原 H5 msg=<base64(JSON)> 方式请求。
• 主农场第一版：
  • 顶部玩家信息、经验、金币、钻石、战力。
  • 农场背景、房屋、狗屋、围栏、土地、宠物牌。
  • 左侧活动入口、右下家园入口、左下世界入口。
  • 双指缩放土地场景，UI 不跟随缩放。
• 土地基础玩法：
  • 播种、收获、铲除、施肥、除虫、除草。
  • 成长倒计时、成熟自动刷新、成熟点击收获。
  • 种子包、化肥包、土地异常状态图标。
• 家园菜单第一版：
  • 商店、仓库、好友入口。
  • 商店购买、仓库出售、好友排行。
• 建筑和扩展：
  • 房屋升级面板和接口。
  • 土地扩建面板和接口。
  • 狗窝面板、狗粮喂养。
• 活动和系统入口：
  • 日志、系统公告、福利大厅、兑换金币。
  • 等级礼包、在线礼包、每日签到、宝箱、幸运转盘。
  • 宠物列表、宠物显示、宠物喂养、宠物参战。
  • 世界弹出菜单：投放、收获、喂养、去农场。
• 架构拆分：
  • scripts/services/：接口服务层已建立。
  • scripts/state/：玩家、农场、背包状态层已建立。
  • scripts/domain/rules/：土地动作、作物阶段、成本判断已建立。
  • scripts/domain/mappers/：农场和背包数据映射已建立。
  • scripts/resources/：图集区域和纹理缓存已建立。
  • scripts/ui/hud/top_bar_view.gd：顶部 HUD 渲染已迁出。
  • scripts/ui/menus/：主菜单和世界菜单控制器已迁出。
  • scripts/ui/common/：弹窗层、Toast、按钮动效公共逻辑已迁出。
  • scripts/ui/farm/farm_viewport_controller.gd：农场拖动视口、双指/滚轮缩放已迁出。
  • scripts/ui/game_scene_runtime_assembler.gd：HUD、菜单、弹窗、宠物展示、农场缩放、土地网格、土地菜单、背包、种植提示和 hit 路由装配已迁出。
  • scripts/ui/game_scene_panel_router.gd：所有面板入口、弹窗打开/关闭和仓库/好友入口状态已迁出。
  • scripts/ui/game_scene_context.gd：面板共享依赖和 legacy callback 兼容层已收敛。
  • scripts/state/player_state.gd：合并原玩家字段访问器，玩家快照只保留一个权威来源。
  • scripts/ui/common/icon_texture_provider.gd：物品、宠物、作物和房屋图标加载已集中缓存。

部分完成

• UI 对齐：主场景和大部分面板已能打开并使用原资源，但不是像素级一致。
• 动效：主菜单、世界菜单、土地菜单、弹窗有 Tween；仍未覆盖所有原版细节动效。
• 好友：只完成排行和列表；搜索、申请、访问好友家园、好友互动仍是占位提示。
• 世界功能：只完成菜单和信息型面板；游乐园、竞技场、成就领取、战宠对战还不是完整玩法。
• 福利大厅：VIP/卡数据显示和领取已接；购买周卡/月卡已接入充值下单入口，支付完成回调仍需海外平台 SDK。
• 兑换金币：兑换和记录已接；UI 仍是 Godot 第一版排版，不是原版完整皮肤。
• 资源系统：可读 Egret 图集 JSON 并缓存 AtlasTexture；没有批量生成 .tres 和 EXML 辅助转换工具。
• 架构：服务/状态/规则、公共 UI、运行时装配、面板路由、土地交互和主要面板已拆出；game_scene.gd 当前 957 行，已低于 1200 行目标，后续风险集中在旧面板 legacy callbacks。

明确未补齐

• 充值/支付：原 H5 有 OPEN_PAY 和 pay/pay；Godot 已接 Top Up、周卡/月卡购买入口和支付下单 URL 跳转，实际支付完成回调仍需接海外平台 SDK。
• 换肤/背景：原 H5 有 OPEN_SKIN 和 farm/change-bg；Godot 当前商店背景 tab 不是完整换肤流程。
• 玩家信息：原 H5 有 OPEN_PLAYER_INFO；Godot 当前头像点击没有完整角色信息面板。
• 好友搜索/申请/请求处理/赠送/互动/访问好友农场：Godot 当前大多是 toast 占位。
• 竞技场完整玩法：挑战列表、挑战、周奖励、领奖未补齐。
• 游乐园完整玩法：进入、翻牌/抽奖/奖励结算未补齐。
• 成就完整玩法：领取成就奖励未做完整交互。
• 战宠完整玩法：战斗详情、对战流程、战斗结果未补齐。
• 音频、FNT、全部原版动画、所有面板像素级对照未完成。

P0：必须优先补齐

P0 是继续开发和第一版可玩闭环的阻断项。

项目	当前状态	依据	下一步
拆分 game_scene.gd	P0 完成：土地、背包、公共 UI、菜单、HUD、弹窗层、商店/仓库/好友/建筑/狗/活动/支付/福利/兑换/世界/签到/宝箱/转盘/宠物面板、启动装配、运行时装配、面板路由、hit 路由、土地交互协调、库存 Facade、玩家状态、场景上下文已拆成模块	wc -l godot/FarmGodot/scripts/ui/game_scene.gd 当前低于 1200 行；新增 GameSceneBootstrap、GameSceneRuntimeAssembler、GameScenePanelRouter、SceneHitRouter、FarmInteractionCoordinator、PlayerInventoryFacade、PlayerState、GameSceneContext	P1 继续把旧面板从 legacy callbacks 迁到显式 Context 方法
UI 像素级一致	功能入口已按原素材补齐并保留烟测截图；仍需逐页和 Egret 基准压差异	docs/ui-baseline/smoke/*.png	每个入口固定 Egret/Godot 对照截图，按主场景、土地、活动、家园面板逐页压差异
浇水	已完成	原 H5 KICK_WATER -> farm/disease type=0；LandActionRules 已接 ACTION_WATER	干旱土地菜单显示浇水图标，执行 farm/disease type=0，刷新土地状态
土地升级	已完成第一版闭环	原 H5 OPEN_LAND_UPGRADE -> farm/upgrade-land；BuildingApi.upgrade_land()	顶部 Land Up 打开原版布局面板，按土地等级/顺位取配置，校验等级/材料/前置土地，成功刷新土地
充值/支付入口	已完成第一版闭环	原 H5 OPEN_PAY -> pay/pay；Godot 新增 PayApi	Top Up 和福利卡购买打开充值面板，pay/pay 成功后 Web 端用 JavaScriptBridge 跳转支付 URL
状态一致性	P0 完成：奖励、消耗、仓库刷新、货币写入走 PlayerInventoryFacade，玩家快照字段统一走 PlayerState	主场景内玩家字段不再依赖 PlayerDataAccessor，PlayerInventoryFacade 也改为引用 PlayerState	P1 把世界/好友等跨模块状态继续收敛到显式 State/Facade apply
真实 Web 烟测流程	已完成	tools/smoke_godot_web.mjs	覆盖主场景、Top Up、Land Up、福利大厅、土地菜单、世界菜单、缩放；截图输出到 docs/ui-baseline/smoke/

P1：第一版完整度补齐

P1 是原版主要系统补齐项，不一定阻断农场主循环，但会影响“功能逻辑一致”。

项目	当前状态	依据	下一步
好友完整系统	排行和好友列表已接，搜索/申请/请求/访问/互动未接	Godot 里 好友搜索面板后续补齐、查看家园、互动 为 toast	补 friend/find、friend/add、friend/get-respond-list、friend/respond-list、friend/respond，再做好友农场场景
好友农场和互动	无 SceneNotify.OPEN_OTHER_GAME 对应完整场景	原 H5 GO_OTHER_FARM、interaction/interaction	支持访问他人农场、放虫/放草/浇水/除虫/除草互动，区分自己和好友土地菜单
世界-成就	只展示列表，没有完整领取/分页/状态	Godot 有 fetch_achievements/claim_achievement，UI 未完整绑定领取	补成就详情、领取按钮、领取后状态刷新
世界-竞技场	只展示基础数据和排行	原 H5 有 arena/get-challenge-list、arena/challenge、arena/week-gift-list、arena/get-gift	补挑战列表、挑战流程、战斗结果、每周奖励
世界-游乐园	只展示次数和奖励配置	原 H5 有 comm/enter-pleasure-ground、comm/pleasure-ground	补进入、玩法步骤、奖励结算和次数扣除
世界-战宠对战	宠物列表/喂养/参战已接，对战未接	原 H5 有 pet/battle、pet/get-battle-info	补战宠对战入口、战斗详情、结果动画
换肤/背景	商店背景 tab 和换肤系统未闭环	原 H5 OPEN_SKIN -> farm/change-bg	补 SkinPanel、已拥有背景列表、应用背景、购买背景后的状态刷新
玩家信息	未做完整角色信息面板	原 H5 OPEN_PLAYER_INFO	头像点击打开角色资料，支持昵称/形象信息展示
活动面板细节	已能打开，部分逻辑和动效仍简化	宝箱、签到、福利、转盘等 Godot UI 为第一版	对照原皮肤补齐分页、倒计时、按钮状态、领奖动画、奖励弹窗
商店/仓库完整性	基础购买/出售已接	原 H5 商店含普通/神秘/背景，仓库含多分类	补完整分类、数量选择、使用道具、背景商品、不可售状态

P2：质量、工具和发布能力

P2 不阻断第一版功能闭环，但影响长期效率、质量和海外发布。

项目	当前状态	下一步
EXML 辅助转换工具	未实现	做 EXML 坐标/九宫格/资源名提取工具，减少手写 UI 坐标
Egret 图集批量 .tres 生成	局部使用运行时图集缓存	批量生成 Godot 可引用 AtlasTexture 或统一运行时缓存索引
FNT/字体一致性	部分位图字和字体仍不完全一致	系统整理 FNT 解析和 Label 替换规则
音频系统	原资源已迁入，运行时播放未完整接入	补背景音乐、点击音效、奖励音效、开关设置
动效库	基础按钮/点击动效已抽到 UiMotion，部分面板和土地动效仍在各自模块	继续抽通用弹入、奖励飞字、面板切换动画
自动化测试	只有手动命令和截图脚本片段	增加 Godot check、Web 导出、Playwright 烟测的一键脚本
CI/构建脚本	未固化	添加本地 tools/export_web.sh 或 Makefile，后续接 CI
配置环境切换	后端地址写在 project.godot	增加 dev/staging/prod 配置方案，避免手动改 base_url
海外 SDK	未接	支付、广告、统计、登录平台 SDK 通过 Web JavaScriptBridge 薄封装
代码清理	仍有重复/临时逻辑风险	清理重复 return、toast 占位、直接字典读写和未使用常量
文档同步	旧进度文档部分过期	用本文档作为当前优先级源，阶段完成后同步 README.MD 和迁移进度

建议执行顺序

1. 已完成：P0-2 浇水和土地升级，完成农场核心土地闭环。
2. 已完成：P0-3 充值/支付入口的可替换接口层，Top Up 和福利卡购买不再是占位。
3. 已完成：P0-4 Playwright Web 烟测脚本，导出后可固定跑主场景、土地、活动、世界、缩放。
4. 已完成：P0-1 game_scene.gd 深拆当前阶段，启动装配、hit 路由、土地交互、库存状态写入已迁出。
5. P1：按世界功能和好友功能拆独立模块，先做接口闭环，再压 UI。