refactor：重构项目架构为分层结构

## 🏗️ 主要变更 ### 目录结构重构 - 将 core/ 迁移到 _Core/（框架层） - 将 scenes/ 重构为 Scenes/（玩法层）和 UI/（界面层） - 将 data/ 迁移到 Config/（配置层） - 添加 Assets/ 资源层和 Utils/ 工具层 - 将 scripts/ 迁移到 tools/（开发工具） ### 架构分层 - **_Core/**: 框架层 - 全局单例和管理器 - **Scenes/**: 玩法层 - 游戏场景和实体 - **UI/**: 界面层 - HUD、窗口、对话系统 - **Assets/**: 资源层 - 精灵图、音频、字体 - **Config/**: 配置层 - 游戏配置和本地化 - **Utils/**: 工具层 - 通用辅助脚本 ### 文件更新 - 更新 project.godot 中的所有路径引用 - 更新自动加载脚本路径 - 更新测试文件的引用路径 - 添加 REFACTORING.md 详细说明 - 添加 MIGRATION_COMPLETE.md 迁移完成标记 - 更新 README.md 反映新架构 ### 设计原则 - ✅ 清晰的分层（框架/玩法/界面） - ✅ 场景内聚（脚本紧邻场景文件） - ✅ 组件化设计（可复用组件） - ✅ 职责单一（每个目录职责明确） ## 📋 详细信息查看 REFACTORING.md 了解完整的重构说明和迁移映射表 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2025-12-31 11:36:01 +08:00
parent b1f3c0feff
commit 0b533189ec
93 changed files with 1466 additions and 470 deletions
--- a/REFACTORING.md
+++ b/REFACTORING.md
@@ -0,0 +1,222 @@
+# 项目结构重构文档
+
+## 📅 重构时间
+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
+```ini
+# 更新主场景路径
+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
+```gdscript
+# 更新场景路径映射
+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. 组件化设计
+```gdscript
+# 可复用组件放在 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/` 工作
+
+## 📝 迁移检查清单
+
+- [x] 创建新的目录结构
+- [x] 迁移核心管理器
+- [x] 迁移工具类
+- [x] 迁移场景文件
+- [x] 分离 UI 界面
+- [x] 迁移配置文件
+- [x] 重组资源文件
+- [x] 更新 project.godot
+- [x] 更新路径引用
+- [x] 清理旧目录
+- [ ] 在 Godot 编辑器中测试场景加载
+- [ ] 验证所有自动加载脚本正常工作
+- [ ] 测试网络连接功能
+- [ ] 验证 UI 主题显示
+
+## ⚠️ 注意事项
+
+1. **场景引用更新**: 所有旧场景的引用都已更新，但建议在 Godot 编辑器中重新打开项目，让编辑器重新索引文件
+
+2. **.import 文件**: 移动资源文件后，Godot 可能会重新生成 .import 文件，这是正常的
+
+3. **版本控制**: 如果使用 Git，旧文件的删除会在下次提交时体现
+
+4. **测试覆盖**: 迁移后建议运行完整的测试套件确保功能正常
+
+## 🎓 参考资料
+
+- [Godot 官方项目组织建议](https://docs.godotengine.org/en/stable/tutorials/best_practices/project_organization.html)
+- [GDScript 场景组织](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_basics.html#scenes-and-scripts)
+- [ECS 架构模式](https://github.com/SmitUS/Pine-Tree-ECS-For-Godot-4)
+
+---
+
+**重构完成！项目现在拥有清晰的架构，易于维护和扩展。** 🎉