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

> **版本**：V1.6  
> **日期**：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 });
scenario.SaveScenarioDrone(sc.Id, new ScenarioDrone {
    WaveId = "w1", Model = "Shahed-136", Description = "活塞巡飞弹",
    Quantity = 1, DroneType = (int)DroneType.FixedWing,
    TypicalSpeed = 200, TypicalAltitude = 500
});
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.SaveDeployment(sc.Id, new List<ScenarioUnit> {
    new() { EquipmentRole = 1, PlatformType = 1, Quantity = 1,
            PositionX = 5000, AerosolType = 0, MunitionCount = 8,
            Description = "地面轻型平台" }
});
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() / DeleteAmmo()
mgr.DataService.GetAllFireUnits() / GetAllDrones() / GetAllSensors()
mgr.DataService.GetAllEnvironments() / GetAllFormations() / GetAllRoutes()

// 想定 CRUD
mgr.CreateScenario(name, number) / mgr.DeleteScenario(id)
mgr.Search(kw, from, to, page, size)
mgr.SaveScene / SaveScenarioDrone / SaveDeployment / SaveCloud / SaveRoute / UpdateStep
mgr.GetDetail(id) → ScenarioConfig
```

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

---

## 六、实体属性速查

| 实体 | 关键属性 |
|------|------|
| **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, Target, HasArrived |
| **PlatformEntity** | Id, PosX/Y/Z, CurrentVelocity, State, MunitionCount, Cooldown, MuzzleVelocity, CruiseSpeed, ReleaseAltitude, Target, FlightDistance |
| **DetectionEntity** | Id, PosX/Y/Z, Source, IsInRange(), IsDetected() |

---

## 七、核心模型

### 7.1 数据库表

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

### 7.2 关键属性

| 模型 | 属性 | 类型 | 说明 |
|------|------|------|------|
| `ScenarioDrone` | `Model` | string | 型号 |
| `ScenarioDrone` | `Description` | string | 描述/用途 |
| `ScenarioDrone` | `DroneType` | DroneType | Rotor / FixedWing / HighSpeed |
| `ScenarioDrone` | `PowerType` | PowerType | Electric / Piston / Jet |
| `ScenarioDrone` | `TypicalSpeed` | double | 典型速度 (km/h) |
| `ScenarioDrone` | `TypicalAltitude` | double | 典型高度 (m) |
| `Scenario` | `ScenarioNumber` | string | 想定编号（唯一） |
| `Scenario` | `Description` | string | 想定描述 |
| `ScenarioUnit` | `Description` | string | 部署备注 |
| `ScenarioUnit` | `MuzzleVelocity` | double? | 初速 (m/s) |
| `ScenarioUnit` | `CruiseSpeed` | double? | 巡航速度 (m/s)，空基专用 |
| `DroneSpec` | `Model` | string | 型号 |
| `DroneSpec` | `Description` | string | 描述/用途 |
| `FireUnitSpec` | `Description` | string | 描述/用途 |

---

## 八、默认数据

首次运行自动种子，含 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 测试，11 秒（全部通过）** |