# 后端对接文档（Unity 前端）

> **版本**：V1.8  
> **日期**：2026-06-18  
> **Unity 版本**：2022.3.62f3c1  

---

## 一、交付物

从仓库取以下内容，拖入 Unity 项目：

```
src/Unity/Assets/Plugins/              ← DLL（Core + sqlite + JSON）
src/Unity/Assets/Scripts/Managers/     ← 桥接脚本

将以下文件放到 Unity 项目 Assets/StreamingAssets/ 目录下：
  data/defaults.json                    ← 默认数据（首次运行自动复制到 persistentDataPath）
  data/planner_config.json              ← 规划器配置（同上）
```

---

## 二、快速开始

1. 将 `defaults.json` 和 `planner_config.json` 放到 `Assets/StreamingAssets/`
2. 创建空 GameObject，挂 `SimulationBootstrap`
3. 运行 — 自动种子数据库，选一个 `[Demo]` 想定，启动仿真

> `SimulationBootstrap` 是前端开发的参考模板，展示预设模式（一行代码）和自定义模式两种路径。

---

## 三、完整工作流（5 步）

```
┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌──────────┐    ┌──────────┐
│ 基础数据 CRUD │ → │  创建想定    │ → │  运行仿真    │ → │  生成报告  │ → │  回放    │
│ DataService  │    │ ScenarioMgr │    │ SimRunner   │    │ ReportMgr │    │ Replay   │
└─────────────┘    └─────────────┘    └─────────────┘    └──────────┘    └──────────┘
```

### 3.1 步骤 1：管理基础数据

```csharp
var mgr = GetComponent<ScenarioManager>();
var ds = mgr.DataService;

// 列出所有
var drones = ds.GetAllDrones();
var ammo = ds.GetAllAmmo();
var units = ds.GetAllFireUnits();

// 新增
ds.SaveDrone(new DroneSpec { Id = "custom", Name = "自定义", Model = "DJI-M3", Description = "小型四旋翼", TypicalSpeed = 100, ... });
// 删除
ds.DeleteDrone("custom");

// 7 类全覆盖：DroneSpec / FireUnitSpec / SensorSpec / EnvironmentSpec
//               FormationTemplate / RouteTemplate / AmmunitionSpec
```

### 3.2 步骤 2：创建想定

```csharp
var scenario = GetComponent<ScenarioManager>();

// 方式 A：预设想定（最快）
var demos = scenario.Search("Demo", null, null, 1, 100);
var scenarioId = demos.Items[0].Id;

// 方式 B：自定义
var sc = scenario.CreateScenario("我的想定", "");
scenario.SaveScene(sc.Id, new CombatScene { WindSpeed = 5, WindDirection = (int)WindDirection.E });

// 无人机：引用 DroneSpec (基础数据) + 想定特有字段
scenario.SaveScenarioDrone(sc.Id, new ScenarioDrone {
    DroneSpecId = "shahed", WaveId = "w1", Quantity = 3
});

// 部署：引用 FireUnitSpec (基础数据) + 想定特有字段
scenario.SaveDeployment(sc.Id, new List<ScenarioUnit> {
    new() { FireUnitSpecId = "ground-light", Quantity = 2,
            PositionX = 5000, PositionY = 0, PositionZ = 50,
            AerosolType = 0, MunitionCount = 8, Description = "地面轻型平台" }
});

scenario.SaveRoute(sc.Id, "w1", new RoutePlan(), new List<Waypoint> {
    new() { PosX = 0, PosY = 500, PosZ = 0, Speed = 200 },
    new() { PosX = 10000, PosY = 500, PosZ = 0, Speed = 200 }
});
scenario.SaveCloud(sc.Id, new CloudDispersal { AerosolType = 0, DisperseHeight = 500 });
scenario.UpdateStep(sc.Id, 5);
```

### 3.3 步骤 3：运行仿真

```csharp
var runner = GetComponent<SimulationRunner>();
runner.LoadAndStart(scenarioId);
runner.Engine.TimeScale = 4f;

// 事件
runner.Engine.OnMunitionLaunched += m => { };
runner.Engine.OnCloudGenerated   += c => { };
runner.Engine.OnDroneDestroyed   += d => { };
runner.Engine.OnSimulationEnded  += () => { };

// 逐帧
void Update() {
    var result = runner.Engine.Tick(Time.deltaTime);
    foreach (var snap in result.EntitySnapshots) {
        // snap.EntityType, PosX/Y/Z, VelX/Y/Z, Hp, CloudRadius...
    }
}
```

### 3.4 步骤 4：生成报告

```csharp
var rm = GetComponent<ReportManager>();
var detail = scenario.GetDetail(scenarioId);
var report = rm.Generate(scenarioId, detail, runner.Engine.Events.ToList(),
    runner.Engine.Drones[0].Status.ToString(), runner.Engine.SimulationTime);
string path = rm.Export(report.Id);
```

### 3.5 步骤 5：回放

```csharp
var replay = GetComponent<ReplayController>();
replay.LoadReplay(scenarioId);
for (int i = 0; i < replay.TotalFrames; i++) {
    var frame = replay.GetFrame(i);
    // frame.SimulationTime, frame.EntitySnapshots...
}
```

---

## 四、Manager API 速查

### ScenarioManager — 基础数据 + 想定

```csharp
var mgr = GetComponent<ScenarioManager>();

// 基础数据 CRUD（7 类）
mgr.DataService.GetAllAmmo() / SaveAmmo() / GetAmmo() / DeleteAmmo()
mgr.DataService.GetAllFireUnits() / SaveFireUnit() / GetFireUnit() / DeleteFireUnit()
mgr.DataService.GetAllDrones() / SaveDrone() / GetDrone() / DeleteDrone()
mgr.DataService.GetAllSensors() / SaveSensor() / GetSensor() / DeleteSensor()
mgr.DataService.GetAllEnvironments() / SaveEnvironment() / GetEnvironment() / DeleteEnvironment()
mgr.DataService.GetAllFormations() / SaveFormation() / GetFormation() / DeleteFormation()
mgr.DataService.GetAllRoutes() / SaveRoute() / GetRoute() / DeleteRoute()

// 想定 CRUD
mgr.CreateScenario(name, number) / mgr.UpdateScenario(s) / mgr.DeleteScenario(id)
mgr.Search(kw, from, to, page, size) / mgr.GetDetail(id) → ScenarioConfig

// CombatScene
mgr.SaveScene(id, s) / mgr.GetScene(id)

// ControlZone
mgr.SaveControlZones(id, zones) / mgr.GetControlZones(id) / mgr.DeleteControlZone(id)

// ScenarioDrone
mgr.SaveScenarioDrone(id, d) / mgr.AddScenarioDrone(id, d) / mgr.UpdateScenarioDrone(d)
mgr.DeleteScenarioDrone(id) / mgr.GetScenarioDrones(id)

// ScenarioUnit
mgr.SaveDeployment(id, units) / mgr.AddDeploymentUnit(id, u) / mgr.UpdateDeploymentUnit(u)
mgr.DeleteDeploymentUnit(id) / mgr.GetDeploymentUnits(id)

// Detection
mgr.AddDetection(id, d) / mgr.DeleteDetection(id) / mgr.GetDetections(id)

// CloudDispersal
mgr.SaveCloud(id, c) / mgr.GetCloud(id) / mgr.DeleteCloud(id)

// Route & Waypoint
mgr.SaveRoute(id, waveId, r, wps) / mgr.GetRoutes(id) / mgr.DeleteRoute(id)
mgr.GetWaypoints(id) / mgr.GetWaypointsByWave(id, waveId) / mgr.DeleteWaypoint(id)

// Misc
mgr.UpdateStep(id, step)
mgr.GetEnums() → EnumMetadata  // 所有枚举定义（下拉框数据源）
// EnumMetadata: DroneType, PowerType, PlatformType, AerosolType,
//   WeatherType, WindDirection, SceneType, FormationMode,
//   TriggerMode, ReleaseMode, EquipmentRole
//   每个字段是 Dictionary<string,int> (名称→值)
```

### SimulationRunner — 仿真执行

```csharp
var runner = GetComponent<SimulationRunner>();
runner.LoadAndStart(scenarioId);
runner.Engine.TimeScale = 4f;
runner.Engine.State / Drones / Clouds / Munitions / Platforms / DetectionEntities / Events
runner.Engine.Tick(dt) → SimulationFrameResult { EntitySnapshots, NewEvents }
runner.Engine.OnMunitionLaunched / OnCloudGenerated / OnDroneDestroyed / ...
runner.Stop();
```

### ReportManager — 报告

```csharp
var rm = GetComponent<ReportManager>();
rm.Generate(scenarioId, detail, events, status, duration) → SimulationReport
rm.Export(reportId) → 文件路径
rm.Export(reportId, "D:\\MyReports")  // 支持指定导出路径
```

### ReplayController — 回放

```csharp
var replay = GetComponent<ReplayController>();
replay.LoadReplay(scenarioId);
replay.TotalFrames / replay.GetFrame(index)
```

---

## 五、EntitySnapshot（每帧推送）

| 字段 | 类型 | 说明 |
|------|------|------|
| `EntityId` | string | 实体唯一 ID |
| `EntityType` | enum | Drone / Platform / Munition / Cloud / DetectionEquip |
| `PosX/Y/Z` | float | 三维位置 |
| `VelX/Y/Z` | float | 瞬时速度 (m/s) |
| `Hp` | float | 无人机血量 (0~1) |
| `DamageStage` | int | 损伤阶段 |
| `PlatformStateStr` | string | Idle / FlyingToTarget / ReadyToRelease |
| `CloudRadius` | float | 云团有效半径 |
| `CloudOpacity` | float | 不透明度 (0~1) |
| `CloudPhase` | int | 扩散阶段 (1/2/3) |
| `CloudElapsed` | float | 已存在时间 (s) |
| `ModelId` | string? | 3D 模型 ID（Unity 实例化用） |

---

## 六、实体属性速查

| 实体 | 关键属性 |
|------|------|
| **DroneEntity** | Id, PosX/Y/Z, Hp, Status, DroneType, Wingspan, CruiseSpeed, Route, TraveledArc, TotalArc, Progress |
| **CloudEntity** | Id, PosX/Y/Z, Radius, Density, Phase, Elapsed, IsDissipated |
| **MunitionEntity** | Id, PosX/Y/Z, Velocity, Start, LaunchTime, ElapsedTime, LaunchAngle, Azimuth, MuzzleVelocity, FlightDuration, TargetX/Y/Z, HasArrived |
| **PlatformEntity** | Id, PosX/Y/Z, CurrentVelocity, State, MunitionCount, Cooldown, MuzzleVelocity, CruiseSpeed, ReleaseAltitude, TargetX/Y/Z, FlightDistance |
| **DetectionEntity** | Id, PosX/Y/Z, Source, IsInRange(), IsDetected() |

---

## 七、核心模型

### 7.1 数据分层

```
基础数据（全局模板）              想定数据（归属 ScenarioId）
─────────────────              ──────────────────────────
DroneSpec                       ScenarioDrone (DroneSpecId FK)
FireUnitSpec                    ScenarioUnit  (FireUnitSpecId / SensorSpecId FK)
SensorSpec
AmmunitionSpec
EnvironmentSpec
FormationTemplate
RouteTemplate
ModelInfo
```

### 7.2 数据库表

| 模型 | SQLite 表 | 说明 |
|------|------|------|
| `Scenario` | `Scenario` | 想定任务 |
| `CombatScene` | `CombatScene` | 作战环境 |
| `ScenarioDrone` | `ScenarioDrone` | 无人机批次（引用 DroneSpec） |
| `ScenarioUnit` | `ScenarioUnit` | 装备部署（引用 FireUnitSpec/SensorSpec） |
| `CloudDispersal` | `CloudDispersal` | 云团抛撒配置 |
| `RoutePlan` | `RoutePlan` | 航路规划 |
| `Waypoint` | `Waypoint` | 航路点 |
| `ControlZone` | `ControlZone` | 管控区域 |
| `SimulationReport` | `SimulationReport` | 仿真报告 |
| `DroneSpec` | `DroneSpec` | 无人机基础模板 |
| `FireUnitSpec` | `FireUnitSpec` | 火力单元基础模板 |
| `SensorSpec` | `SensorSpec` | 传感器基础模板 |
| `AmmunitionSpec` | `AmmunitionSpec` | 弹药基础参数 |
| `EnvironmentSpec` | `EnvironmentSpec` | 环境基础模板 |
| `FormationTemplate` | `FormationTemplate` | 编队基础模板 |
| `RouteTemplate` | `RouteTemplate` | 航线基础模板 |
| `ModelInfo` | `ModelInfo` | 3D 模型元数据 |

### 7.3 关键属性

| 模型 | 属性 | 类型 | 说明 |
|------|------|------|------|
| `ScenarioDrone` | `DroneSpecId` | string | FK → DroneSpec |
| `ScenarioDrone` | `WaveId` | string | 批次 ID |
| `ScenarioDrone` | `Quantity` | int | 数量 |
| `ScenarioUnit` | `FireUnitSpecId` | string | FK → FireUnitSpec（发射平台） |
| `ScenarioUnit` | `SensorSpecId` | string | FK → SensorSpec（探测设备） |
| `ScenarioUnit` | `PositionX/Y/Z` | double | 部署位置 |
| `ScenarioUnit` | `AerosolType` | int? | 挂载弹药类型 |
| `ScenarioUnit` | `MunitionCount` | int? | 弹药数量 |
| `ScenarioUnit` | `Description` | string | 部署备注 |
| `DroneSpec` | `Model` | string | 型号名称（非 3D 模型，3D 模型见 ModelId） |
| `DroneSpec` | `Description` | string | 描述/用途 |
| `DroneSpec` | `ModelId` | string | 3D 模型 FK → ModelInfo |
| `DroneSpec` | `DroneType` | DroneType | Rotor / FixedWing / HighSpeed |
| `DroneSpec` | `PowerType` | PowerType | Electric / Piston / Jet |
| `DroneSpec` | `TypicalSpeed` | double | 典型速度 (km/h) |
| `DroneSpec` | `TypicalAltitude` | double | 典型高度 (m) |
| `FireUnitSpec` | `Description` | string | 描述/用途 |
| `FireUnitSpec` | `ModelId` | string | 3D 模型 FK → ModelInfo |
| `FireUnitSpec` | `MuzzleVelocity` | double | 初速 (m/s) |
| `FireUnitSpec` | `CruiseSpeed` | double | 巡航速度 (m/s) |
| `FireUnitSpec` | `RadarRange` | double | 雷达距离 (m) |
| `ModelInfo` | `EntityType` | int | 实体类型 0=Drone 1=Platform 2=DetectionEquip |
| `ModelInfo` | `FilePath` | string | 模型文件路径 |
| `Scenario` | `ScenarioNumber` | string | 想定编号（唯一） |
| `Scenario` | `Description` | string | 想定描述 |
| `SimulationReport` | `DroneCount` | int | 无人机总数 |
| `SimulationReport` | `UnitCount` | int | 装备总数 |

---

## 八、默认数据

首次运行自动种子，含 6 个 `[Demo]` 预设想定：

| 类别 | 示例 ID |
|------|------|
| 弹药 | `inert` / `active` / `fuel` |
| 编队 | `single` / `line-3` / `swarm-10` |
| 航线 | `5km-h500` / `10km-h500` / `20km-h500` |
| 火力单元 | `ground-light` / `air-standard` |
| 无人机 | `shahed` / `quadcopter` / `cruise-missile` |
| 传感器 | `radar-mr` / `eo-station` |
| 环境 | `sunny-calm` / `fog` / `night` |

---

## 九、更新后端

```bash
cd src/CounterDrone.Core
dotnet publish -c Release -o ../../unity_plugins
```

---

## 十、参考

| 文档 | 位置 |
|------|------|
| 架构设计 | `docs/design/architecture/总体架构设计.md` |
| 实体事件映射 | `docs/design/technical/仿真器实体与事件映射.md` |
| 测试状态 | **238 测试，10 秒（全部通过）** |