前端对接文档：Manager API、数据模型、集成步骤

docs/对接文档_Unity前端.md

@@ -0,0 +1,175 @@
+# 后端对接文档（Unity 前端）
+
+> **版本**：V1.0  
+> **日期**：2026-06-11  
+> **Unity 版本**：2022.3.62f3c1  
+
+---
+
+## 一、交付物
+
+前端同学从项目仓库取以下两个目录，拖入自己的 Unity 项目：
+
+```
+src/Unity/Assets/Plugins/          ← 16 个 DLL，零配置，拖入即用
+src/Unity/Assets/Scripts/Managers/ ← 6 个 C# 桥接脚本
+```
+
+> 不要改 DLL，以后更新时替换即可。Manager 脚本可以按需修改。
+
+---
+
+## 二、快速验证
+
+1. 拖入上述两个目录后，等 Unity 编译完成
+2. 创建一个空 GameObject，挂 `ManagerVerification` 组件
+3. Inspector 右键 → `Run Full Verification`
+4. Console 看到 7 行 `OK` 即表示集成成功
+
+---
+
+## 三、Manager API
+
+所有 Manager 都是 `MonoBehaviour`，挂到场景即可用。建议做成 Singleton。
+
+### ModelManager — 模型管理
+
+```csharp
+var mgr = GetComponent<ModelManager>();
+
+// 导入模型
+ModelInfo model = mgr.Import("C:/models/drone.fbx", "旋翼无人机");
+// 支持的格式: .fbx .obj .stl .glb .gltf（≤500MB）
+
+// 查询
+List<ModelInfo> all = mgr.GetAll();
+ModelInfo one = mgr.Get("model-id");
+
+// 删除
+mgr.Delete("model-id");
+```
+
+### ScenarioManager — 想定管理
+
+```csharp
+var mgr = GetComponent<ScenarioManager>();
+
+// 创建任务
+SimTask task = mgr.CreateTask("城市防御演习", "");  // 空字符串 = 自动编号
+
+// 5 步配置
+mgr.SaveScene(task.Id, new CombatScene { WindSpeed = 5, ... });
+mgr.SaveTarget(task.Id, new TargetConfig { Quantity = 3, ... });
+mgr.SaveDeployment(task.Id, new List<EquipmentDeployment> { ... });
+mgr.SaveCloud(task.Id, new CloudDispersal { AerosolType = ..., ... });
+mgr.SaveRoute(task.Id, new RoutePlan { ... }, waypointList);
+
+// 算法推荐（需要先填充弹药库 AmmunitionSpec）
+var advisor = new DefaultDefenseAdvisor(ammoCatalog);
+var rec = advisor.Recommend(threatProfile);
+// rec.Best.RecommendedCloud → 云团参数
+// rec.Best.Platforms → 搭载平台部署方案
+// rec.Best.InterceptProbability → 拦截概率 0~1
+
+// 搜索
+var result = mgr.Search("关键词", "2026-01-01", "2026-12-31", page: 1, pageSize: 10);
+```
+
+### SimulationRunner — 仿真运行
+
+```csharp
+var runner = GetComponent<SimulationRunner>();
+
+// 加载想定并启动（需先配置好想定 + 云团的 RecommendedTiming）
+runner.LoadAndStart(taskId);
+
+// 可选：加速
+runner.Engine.TimeScale = 4f;
+
+// 每帧 Update
+void Update() {
+    if (runner.Engine.State == SimulationState.Running) {
+        var result = runner.Engine.Tick(Time.deltaTime);
+        // result.EntitySnapshots → 所有实体位置，更新 3D GameObject
+        // result.NewEvents → 本帧事件
+    }
+}
+
+// 无人机位置
+runner.Engine.Drones[0].PosX / PosY / PosZ
+runner.Engine.Drones[0].Status   // Flying / Destroyed / ReachedTarget
+runner.Engine.Drones[0].Hp       // 0~1
+
+// 云团
+runner.Engine.Clouds[i].Dispersion.Center / Radius / CoreDensity
+```
+
+### ReportManager — 报告
+
+```csharp
+var mgr = GetComponent<ReportManager>();
+
+// 生成（仿真结束后）
+var report = mgr.Generate(taskId, config, events, droneStatus, duration);
+
+// 导出 Markdown 文件
+string path = mgr.Export(report.Id);
+
+// 搜索
+var result = mgr.Search("关键词", null, null, 1, 10);
+```
+
+### ReplayController — 回放
+
+```csharp
+var replay = GetComponent<ReplayController>();
+
+replay.LoadReplay(taskId);
+
+// 逐帧读取
+for (int i = 0; i < replay.TotalFrames; i++) {
+    var frame = replay.GetFrame(i);
+    // frame 是 List<SimFrameRecord>，包含该帧所有实体位置
+}
+```
+
+---
+
+## 四、关键数据模型
+
+| 模型 | 说明 |
+|------|------|
+| `SimTask` | 仿真任务（Id, Name, TaskNumber, Status, CurrentStep） |
+| `CombatScene` | 作战场景（天气/风速/温度/时间） |
+| `TargetConfig` | 目标配置（类型/数量/速度/动力） |
+| `EquipmentDeployment` | 装备部署（探测/发射平台/弹药） |
+| `CloudDispersal` | 云团抛撒配置（类型/位置/时机/规模） |
+| `RoutePlan` + `Waypoint` | 航路规划 |
+| `DefenseSolution` | 推荐方案（气溶胶选型/云团参数/平台部署/拦截概率） |
+| `SimulationReport` | 仿真报告（含 Markdown 内容） |
+| `SimFrameRecord` | 逐帧回放数据 |
+
+完整数据模型见 Core 源码 `Models/` 目录。
+
+---
+
+## 五、更新后端
+
+当后端代码更新后：
+
+```bash
+cd src/CounterDrone.Core
+dotnet publish -c Release -o ../../unity_plugins
+```
+
+然后把 `unity_plugins/` 下的新 DLL 覆盖到 `Assets/Plugins/CounterDrone.Core/` 即可。Manager 脚本一般不需要改。
+
+---
+
+## 六、参考
+
+| 文档 | 位置 |
+|------|------|
+| 架构设计 | `docs/design/architecture/总体架构设计.md` |
+| 测试报告 | `test/reports/`（每次集成测试自动生成） |
+| 测试状态 | 128 测试，95.4% 行覆盖率 |