# MapEntity 设计规范（开发约束）

最后更新：2026-03-02

## 1. 目标与边界

`MapEntity` 现在是战斗地图域的编排层（orchestrator），目标是：
- 对外暴露地图能力（格子查询、路径查询、建造操作入口）。
- 在 Unity 生命周期中初始化/清理各子服务。
- 承担输入与 UI 用例的连接，不承载具体业务算法细节。

`MapEntity` 不应再直接实现以下细节：
- Tile 扫描与路径缓存算法。
- 防御塔映射字典的增删改查细节。
- 选中状态与攻击范围显示细节。
- 鼠标拾取与 `CombatSelectFormUserData` 组装细节。

---

## 2. 模块划分（当前标准）

### 2.1 MapEntity（编排层）

文件：`Assets/GameMain/Scripts/Entity/EntityLogic/MapEntity.cs`

职责：
- 生命周期编排：`OnInit / OnShow / OnUpdate / OnHide`
- 子服务初始化与清理
- UI 用例绑定（`CombatSelectFormUseCase`）
- 将输入结果分发到选择器/建造器

### 2.2 MapTopologyService（地图拓扑层）

当前文件：`Assets/GameMain/Scripts/Scene/Map/TowerPlacementService.cs`（同文件内）

职责：
- 扫描 Tilemap，构建 `PathCells` / `FoundationCells`
- 缓存 `Spawner -> 默认路径`
- 提供路径查询：
  - `TryGetNearestPathCell`
  - `TryGetDefaultPathCells`
  - `TryFindPathCells`
  - `TryFindPathWorldPoints`

约束：
- 只处理“地图拓扑与路径”，不处理经济、建塔、UI。

### 2.3 CombatSelectInputService（输入解析层）

文件：`Assets/GameMain/Scripts/Entity/EntityLogic/CombatSelectInputService.cs`

职责：
- 鼠标屏幕坐标 -> 世界坐标
- 判定点击对象类型（`None/Foundation/Tower`）
- 组装 `CombatSelectFormUserData`

约束：
- 只读上下文，不改变游戏状态。
- Foundation/Tower 点击时，UI 定位由 Cell 中心决定（稳定定位）。

### 2.4 TowerPlacementService（塔部署层）

当前文件：`Assets/GameMain/Scripts/Scene/Map/TowerPlacementService.cs`

职责：
- 建造 / 升级 / 销毁（含升级失败回滚）
- 维护塔映射状态：
  - `foundationCell -> towerEntityId`
  - `towerEntityId -> foundationCell`
  - `towerEntityId -> towerStats`
- 提供整局清理接口

约束：
- 仅处理塔生命周期与映射，不处理选中态和 UI。

### 2.5 TowerSelectionPresenter（选择展示层）

文件：`Assets/GameMain/Scripts/Scene/Map/TowerSelectionPresenter.cs`

职责：
- 维护当前选中对象
- 根据选中状态切换攻击范围显示（通过 `DefenseTowerEntity.SetAttackRangeVisible`）

约束：
- 不做建造/升级/销毁。

---

## 3. 运行时主流程（简版）

1. `MapEntity.OnInit` 初始化 4 个服务：
   - `MapTopologyService`
   - `CombatSelectInputService`
   - `TowerPlacementService`
   - `TowerSelectionPresenter`
2. `MapEntity.OnShow` 刷新地图拓扑，配置 UI action。
3. 每帧 `OnUpdate`：
   - 采集输入（InputService）
   - 更新选中对象（SelectionPresenter）
   - 打开/刷新 UI
4. UI Build/Upgrade/Destroy action 回调：
   - 通过 PlacementService 改变塔状态
   - 通过 SelectionPresenter 同步选中和范围显示
5. `OnHide`：
   - 关闭 UI
   - 清理塔实体
   - 清理拓扑/选择/映射运行时状态

---

## 4. 核心不变量（必须保持）

1. `MapEntity` 只编排，不承载业务细节实现。
2. `TowerPlacementService` 是塔映射状态的唯一写入口。
3. `MapTopologyService` 是 Path/Foundation 数据的唯一来源。
4. “当前可见攻击范围”同一时刻最多一个塔。
5. 清场顺序固定：先隐藏塔，再清空映射与选择，再清理拓扑缓存。

---

## 5. 扩展开发规范

### 5.1 新增地图规则（地形、禁建、动态阻挡）

优先改 `MapTopologyService`，不要直接改 `MapEntity`。

### 5.2 新增建造规则（费用、限制、回滚策略）

优先改 `TowerPlacementService`，不要在 `MapEntity` 写分支。

### 5.3 新增点击交互或 UI 定位策略

优先改 `CombatSelectInputService`。

### 5.4 新增选中表现（特效、描边、信息面板联动）

优先改 `TowerSelectionPresenter`。

---

## 6. 代码变更检查清单（PR 自检）

1. 是否把新业务放进了对应服务，而不是 `MapEntity`？
2. 是否破坏了“服务唯一写入口”不变量？
3. Build/Upgrade 失败是否有完整回滚和金币返还？
4. 清理路径是否覆盖了 `OnHide` 与重进地图场景？
5. `dotnet build GeometryTD.sln` 是否通过？