whale-town-front/REFACTORING.md

项目结构重构文档

📅 重构时间

2025-12-31

🎯 重构目标

将项目从混乱的文件结构重构为清晰、模块化的架构，采用 Godot 最佳实践。

📊 重构前后对比

旧结构问题

❌ core/           - 概念模糊，混合了框架和业务逻辑
❌ module/         - 空壳目录，设计未落地
❌ scripts/        - 与 scenes/ 重复，脚本分散
❌ scenes/         - 场景、预制体、脚本混在一起
❌ data/           - 配置和运行时数据不分

新结构优势

✅ _Core/          - 框架层：全局单例和系统
✅ Scenes/         - 玩法层：按游戏世界组织
✅ UI/             - 界面层：独立的UI管理
✅ Assets/         - 资源层：纯美术资源
✅ Config/         - 配置层：静态数据
✅ Utils/          - 工具层：通用函数库

🏗️ 新的目录结构

res://
├── _Core/                      # [框架层] 游戏的底层框架，单例，全局管理器
│   ├── managers/               # 游戏管理器
│   │   ├── GameManager.gd      # 游戏状态管理
│   │   ├── SceneManager.gd     # 场景管理（已更新路径）
│   │   ├── NetworkManager.gd   # 网络通信
│   │   └── ResponseHandler.gd  # API响应处理
│   ├── systems/                # 核心系统
│   │   └── EventSystem.gd      # 事件系统
│   └── singletons/             # 其他单例（待扩展）
│
├── Scenes/                     # [玩法层] 具体的游戏场景、实体、地图
│   ├── Maps/                   # 地图场景
│   │   └── main_scene.tscn     # 主游戏场景
│   ├── Entities/               # 游戏实体
│   │   ├── Player/             # 玩家实体
│   │   ├── NPC/                # NPC实体
│   │   └── Interactables/      # 交互物
│   └── Components/             # 可复用组件
│
├── UI/                         # [界面层] 所有UI相关的预制体和逻辑
│   ├── HUD/                    # 抬头显示（常驻）
│   ├── Windows/                # 模态窗口
│   │   └── LoginWindow.tscn    # 登录窗口（原auth_scene.tscn）
│   ├── Dialog/                 # 对话系统
│   └── Theme/                  # 全局样式
│       ├── MainTheme.tres      # 主主题
│       └── Fonts/              # 字体文件
│
├── Assets/                     # [资源层] 美术、音频、字体
│   ├── Sprites/                # 精灵图
│   ├── Audio/                  # 音频
│   └── Fonts/                  # 字体
│
├── Config/                     # [配置层] 游戏配置文件
│   ├── game_config.json        # 游戏配置
│   └── zh_CN.json              # 中文本地化
│
├── Utils/                      # [工具层] 通用辅助脚本
│   └── StringUtils.gd          # 字符串工具
│
└── Tests/                      # [测试层] 单元测试脚本
    ├── api/                    # API测试
    ├── auth/                   # 认证测试
    ├── integration/            # 集成测试
    ├── performance/            # 性能测试
    └── unit/                   # 单元测试

🔄 迁移映射表

旧路径	新路径	说明
core/managers/*	_Core/managers/	框架层管理器
core/systems/*	_Core/systems/	框架层系统
core/utils/*	Utils/	工具类
scenes/main_scene.tscn	Scenes/Maps/main_scene.tscn	主游戏场景
scenes/auth_scene.tscn	UI/Windows/LoginWindow.tscn	登录窗口
data/configs/*.json	Config/	配置文件
data/localization/*.json	Config/	本地化配置
assets/ui/chinese_theme.tres	UI/Theme/MainTheme.tres	UI主题
assets/fonts/*	UI/Theme/Fonts/	字体文件

✂️ 已删除的目录

• ❌ core/ - 已迁移到 _Core/
• ❌ module/ - 空目录，未使用
• ❌ scripts/ - 脚本应内联到场景目录
• ❌ scenes/ - 已迁移到 Scenes/ 和 UI/
• ❌ data/ - 配置已移至 Config/

🔧 已更新的配置文件

project.godot

# 更新主场景路径
run/main_scene="res://Scenes/Maps/main_scene.tscn"

# 更新自动加载路径
GameManager="*res://_Core/managers/GameManager.gd"
SceneManager="*res://_Core/managers/SceneManager.gd"
EventSystem="*res://_Core/systems/EventSystem.gd"
NetworkManager="*res://_Core/managers/NetworkManager.gd"
ResponseHandler="*res://_Core/managers/ResponseHandler.gd"

SceneManager.gd

# 更新场景路径映射
var scene_paths: Dictionary = {
    "main": "res://Scenes/Maps/main_scene.tscn",
    "auth": "res://UI/Windows/LoginWindow.tscn",
    # ... 其他场景路径
}

测试文件

• tests/auth/enhanced_toast_test.gd - 已更新脚本路径
• tests/auth/auth_ui_test.tscn - 已更新场景路径

🎨 设计原则

1. 清晰的分层

• _Core: 框架代码，与具体游戏逻辑无关
• Scenes: 游戏世界，地图和实体
• UI: 所有界面，HUD和弹窗
• Config: 静态数据，策划可编辑

2. 组件化设计

# 可复用组件放在 Scenes/Components/
Scenes/Components/
├── InteractableArea.tscn    # 让任何物体"可交互"
├── MovementSync.gd          # 网络位置同步
└── NameTag3D.tscn           # 头顶名字条

3. 场景内聚

• 每个 .tscn 配套一个 .gd
• 脚本紧邻场景文件存放
• 符合 Godot 原生开发习惯

4. 职责单一

UI/Windows/     - 模态窗口（登录、设置、商店）
UI/HUD/         - 常驻界面（聊天框、状态栏）
UI/Dialog/      - 对话系统

🚀 后续建议

待完善的功能

1. 组件化开发

   • 创建 Scenes/Components/ 下的可复用组件
   • 使用组合优于继承的设计模式

2. UI 独立化

   • 补充 UI/HUD/ 下的常驻界面
   • 创建 UI/Dialog/ 对话系统

3. 场景管理

   • 补充更多地图场景到 Scenes/Maps/
   • 添加玩家实体到 Scenes/Entities/Player/

4. 配置驱动

   • 将硬编码的数值移到 Config/
   • 使用 Resource 文件管理游戏数据

团队协作

• 美术组: 主要在 Assets/ 工作
• 策划组: 主要在 Config/ 工作
• 程序组: 主要在 _Core/, Scenes/, UI/ 工作
• 测试组: 主要在 Tests/ 工作

📝 迁移检查清单

• 创建新的目录结构
• 迁移核心管理器
• 迁移工具类
• 迁移场景文件
• 分离 UI 界面
• 迁移配置文件
• 重组资源文件
• 更新 project.godot
• 更新路径引用
• 清理旧目录
• 在 Godot 编辑器中测试场景加载
• 验证所有自动加载脚本正常工作
• 测试网络连接功能
• 验证 UI 主题显示

⚠️ 注意事项

1. 场景引用更新: 所有旧场景的引用都已更新，但建议在 Godot 编辑器中重新打开项目，让编辑器重新索引文件

2. .import 文件: 移动资源文件后，Godot 可能会重新生成 .import 文件，这是正常的

3. 版本控制: 如果使用 Git，旧文件的删除会在下次提交时体现

4. 测试覆盖: 迁移后建议运行完整的测试套件确保功能正常

🎓 参考资料

• Godot 官方项目组织建议
• GDScript 场景组织
• ECS 架构模式

---

重构完成！项目现在拥有清晰的架构，易于维护和扩展。 🎉