tian/CounterDroneBackend

Fork 0

tian 178923c007 对接文档同步：完整 CRUD API 列表

2026-06-18 19:44:53 +08:00

12 KiB

Raw Blame History

后端对接文档（Unity 前端）

版本：V1.7
日期：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              ← 规划器配置（同上）

二、快速开始

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

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

三、完整工作流（5 步）

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

3.1 步骤 1：管理基础数据

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：创建想定

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：运行仿真

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：生成报告

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：回放

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 — 基础数据 + 想定

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)

SimulationRunner — 仿真执行

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 — 报告

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

ReplayController — 回放

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, 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	型号
`DroneSpec`	`Description`	string	描述/用途
`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`	`MuzzleVelocity`	double	初速 (m/s)
`FireUnitSpec`	`CruiseSpeed`	double	巡航速度 (m/s)
`FireUnitSpec`	`RadarRange`	double	雷达距离 (m)
`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`

九、更新后端

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

十、参考

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

12 KiB Raw Blame History Unescape Escape

后端对接文档（Unity 前端）

一、交付物

二、快速开始

三、完整工作流（5 步）

3.1 步骤 1：管理基础数据

3.2 步骤 2：创建想定

3.3 步骤 3：运行仿真

3.4 步骤 4：生成报告

3.5 步骤 5：回放

四、Manager API 速查

ScenarioManager — 基础数据 + 想定

SimulationRunner — 仿真执行

ReportManager — 报告

ReplayController — 回放

五、EntitySnapshot（每帧推送）

六、实体属性速查

七、核心模型

7.1 数据分层

7.2 数据库表

7.3 关键属性

八、默认数据

九、更新后端

十、参考

12 KiB

Raw Blame History