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
```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)

---

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