docs: 重写对接文档 — 五步完整工作流（基础数据→想定→仿真→报告→回放）
This commit is contained in:
parent
5d79e26e0f
commit
4c2c18cfcc
@ -27,207 +27,187 @@ src/Unity/Assets/Scripts/Managers/ ← 桥接脚本
|
||||
2. 创建空 GameObject，挂 `SimulationBootstrap`
|
||||
3. 运行 — 自动种子数据库，选一个 `[Demo]` 想定，启动仿真
|
||||
|
||||
> `SimulationBootstrap` 是前端开发的参考模板，展示预设模式（一行代码）和自定义模式（用 DefaultData 预设组装）两种路径。
|
||||
|
||||
> 如需验证全部模块，挂 `ManagerVerification` → Inspector 右键 `Run Full Verification`。
|
||||
> `SimulationBootstrap` 是前端开发的参考模板，展示预设模式（一行代码）和自定义模式两种路径。
|
||||
|
||||
---
|
||||
|
||||
## 三、核心流程（使用预设想定）
|
||||
## 三、完整工作流（5 步）
|
||||
|
||||
### 3.1 列出预设想定
|
||||
|
||||
```csharp
|
||||
var scenario = GetComponent<ScenarioManager>();
|
||||
var demos = scenario.Search("Demo", null, null, 1, 100);
|
||||
// → 返回 6 个预设想定：
|
||||
// [Demo] 无防御-无人机抵达目标
|
||||
// [Demo] 管控区域侵入
|
||||
// [Demo] 活塞拦截-西风5ms
|
||||
// [Demo] 喷气式拦截-活性材料
|
||||
// [Demo] 空基拦截-东风5ms
|
||||
// [Demo] 3架空基编队拦截
|
||||
```
|
||||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌──────────┐ ┌──────────┐
|
||||
│ 基础数据 CRUD │ → │ 创建想定 │ → │ 运行仿真 │ → │ 生成报告 │ → │ 回放 │
|
||||
│ DataService │ │ ScenarioMgr │ │ SimRunner │ │ ReportMgr │ │ Replay │
|
||||
└─────────────┘ └─────────────┘ └─────────────┘ └──────────┘ └──────────┘
|
||||
```
|
||||
|
||||
### 3.2 启动仿真（一行代码）
|
||||
|
||||
```csharp
|
||||
var runner = GetComponent<SimulationRunner>();
|
||||
|
||||
// 选一个预设想定，直接运行（引擎自动调用 Planner 生成发射计划）
|
||||
runner.LoadAndStart(demos.Items[0].Id); // 例如：活塞拦截-西风5ms
|
||||
runner.Engine.TimeScale = 4f; // 加速
|
||||
|
||||
// 订阅事件
|
||||
runner.Engine.OnMunitionLaunched += m => Instantiate(shellPrefab, ToVector3(m.PosX, m.PosY, m.PosZ));
|
||||
runner.Engine.OnCloudGenerated += c => SpawnCloud(c.PosX, c.PosY, c.PosZ, c.Radius);
|
||||
runner.Engine.OnDroneDestroyed += d => PlayExplosion(d.PosX, d.PosY, d.PosZ);
|
||||
runner.Engine.OnTargetDetected += (d, det) => ShowDetectionMark(d.PosX, d.PosY, d.PosZ);
|
||||
runner.Engine.OnDroneReachedTarget += d => ShowReached(d.PosX, d.PosY, d.PosZ);
|
||||
runner.Engine.OnZoneIntruded += (d, z) => AlertIntrusion(z.Name);
|
||||
runner.Engine.OnSimulationEnded += () => GenerateReport();
|
||||
```
|
||||
|
||||
### 3.3 自定义想定（高级）
|
||||
|
||||
```csharp
|
||||
var scenario = GetComponent<ScenarioManager>();
|
||||
var task = scenario.CreateTask("自定义想定", "");
|
||||
|
||||
// 使用默认数据预设快速配置
|
||||
var defaults = DefaultData.Load(new UnityPathProvider());
|
||||
scenario.SaveScene(task.Id, defaults.Weather.First(w => w.Id == "sunny-calm").ToCombatScene());
|
||||
scenario.SaveTarget(task.Id, defaults.Targets.First(p => p.Id == "shahed").ToTargetConfig());
|
||||
scenario.SaveRoute(task.Id, "default",
|
||||
defaults.Formations.First(f => f.Id == "single").ToRoutePlan(),
|
||||
defaults.Routes.First(r => r.Id == "5km-h500").ToWaypoints(200));
|
||||
scenario.SaveDeployment(task.Id, new List<EquipmentDeployment>
|
||||
{
|
||||
defaults.FireUnits.First(f => f.Id == "ground-light")
|
||||
.ToEquipmentDeployment(AerosolType.InertGas, 1, 1500, 0, 50),
|
||||
});
|
||||
scenario.SaveCloudDispersal(task.Id, new CloudDispersal
|
||||
{ AerosolType = (int)AerosolType.InertGas, DisperseHeight = 500 });
|
||||
scenario.UpdateStep(task.Id, 5);
|
||||
|
||||
// 运行
|
||||
var runner = GetComponent<SimulationRunner>();
|
||||
runner.LoadAndStart(task.Id);
|
||||
```
|
||||
|
||||
### 3.3 仿真事件一览
|
||||
|
||||
| 事件 | 参数 | 触发时机 |
|
||||
|------|------|------|
|
||||
| `OnTargetDetected` | `DroneEntity`, `DetectionEntity` | 无人机首次进入探测设备 3D 球冠范围（离开后再次进入会重新触发） |
|
||||
| `OnMunitionLaunched` | `MunitionEntity` | 发射计划时间到达 |
|
||||
| `OnCloudGenerated` | `CloudEntity` | 弹药到达释放高度 |
|
||||
| `OnDroneDestroyed` | `DroneEntity` | HP ≤ 0 |
|
||||
| `OnDroneReachedTarget` | `DroneEntity` | 到达最后航路点 |
|
||||
| `OnZoneIntruded` | `DroneEntity`, `ControlZoneEntity` | 进入管控区 |
|
||||
| `OnSimulationEnded` | 无 | 所有无人机状态 ≠ Flying |
|
||||
|
||||
---
|
||||
|
||||
## 四、Manager API
|
||||
|
||||
### ScenarioManager
|
||||
### 3.1 步骤 1：管理基础数据
|
||||
|
||||
```csharp
|
||||
var mgr = GetComponent<ScenarioManager>();
|
||||
SimTask task = mgr.CreateTask("任务名", ""); // 空字符串 = 自动编号 SIM-yyyyMMdd-xxx
|
||||
mgr.SaveScene(id, combatScene);
|
||||
mgr.SaveTarget(id, targetConfig);
|
||||
mgr.SaveDeployment(id, equipmentList);
|
||||
mgr.SaveCloud(id, cloudDispersal);
|
||||
mgr.SaveRoute(id, "default", routePlan, waypoints);
|
||||
TaskFullConfig detail = mgr.GetDetail(id);
|
||||
PagedResult<SimTask> result = mgr.Search("关键词", from, to, page, pageSize);
|
||||
var ds = mgr.DataService;
|
||||
|
||||
// 列出所有
|
||||
var drones = ds.GetAllDrones();
|
||||
var ammo = ds.GetAllAmmo();
|
||||
var units = ds.GetAllFireUnits();
|
||||
|
||||
// 新增
|
||||
ds.SaveDrone(new DroneSpec { Id = "custom", Name = "自定义", TypicalSpeed = 100, ... });
|
||||
// 删除
|
||||
ds.DeleteDrone("custom");
|
||||
|
||||
// 7 类全覆盖：DroneSpec / FireUnitSpec / SensorSpec / EnvironmentSpec
|
||||
// FormationTemplate / RouteTemplate / AmmunitionSpec
|
||||
```
|
||||
|
||||
### SimulationRunner
|
||||
### 3.2 步骤 2：创建想定
|
||||
|
||||
```csharp
|
||||
var scenario = GetComponent<ScenarioManager>();
|
||||
|
||||
// 方式 A：预设想定（最快）
|
||||
var demos = scenario.Search("Demo", null, null, 1, 100);
|
||||
var taskId = demos.Items[0].Id;
|
||||
|
||||
// 方式 B：自定义
|
||||
var task = scenario.CreateTask("我的想定", "");
|
||||
scenario.SaveScene(task.Id, new CombatScene { WindSpeed = 5, WindDirection = (int)WindDirection.E });
|
||||
scenario.SaveTarget(task.Id, new TargetConfig { WaveId = "w1", Quantity = 1, TypicalSpeed = 200, TypicalAltitude = 500 });
|
||||
scenario.SaveRoute(task.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(task.Id, new List<EquipmentDeployment> {
|
||||
new() { EquipmentRole = 1, PlatformType = 1, Quantity = 1, PositionX = 5000, AerosolType = 0, MunitionCount = 8 }
|
||||
});
|
||||
scenario.SaveCloud(task.Id, new CloudDispersal { AerosolType = 0, DisperseHeight = 500 });
|
||||
scenario.UpdateStep(task.Id, 5);
|
||||
```
|
||||
|
||||
### 3.3 步骤 3：运行仿真
|
||||
|
||||
```csharp
|
||||
var runner = GetComponent<SimulationRunner>();
|
||||
runner.Engine.SetFireSchedule(fireEvents); // 从推荐方案取
|
||||
runner.LoadAndStart(taskId);
|
||||
runner.Engine.TimeScale = 4f;
|
||||
runner.Engine.State / Drones / Clouds / Munitions / Platforms / DetectionEntities / Events
|
||||
runner.DataService // 基础数据 CRUD（见第五节）
|
||||
runner.Stop();
|
||||
|
||||
// 事件
|
||||
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...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### ReportManager
|
||||
### 3.4 步骤 4：生成报告
|
||||
|
||||
```csharp
|
||||
var mgr = GetComponent<ReportManager>();
|
||||
var config = scenario.GetDetail(taskId);
|
||||
var report = mgr.Generate(taskId, config, runner.Engine.Events.ToList(),
|
||||
runner.Engine.Drones[0].Status.ToString(),
|
||||
runner.Engine.SimulationTime);
|
||||
string path = mgr.Export(report.Id); // → persistentDataPath/reports/xxx.md
|
||||
var rm = GetComponent<ReportManager>();
|
||||
var detail = scenario.GetDetail(taskId);
|
||||
var report = rm.Generate(taskId, detail, runner.Engine.Events.ToList(),
|
||||
runner.Engine.Drones[0].Status.ToString(), runner.Engine.SimulationTime);
|
||||
string path = rm.Export(report.Id);
|
||||
```
|
||||
|
||||
### ReplayController
|
||||
### 3.5 步骤 5：回放
|
||||
|
||||
```csharp
|
||||
var replay = GetComponent<ReplayController>();
|
||||
replay.LoadReplay(taskId);
|
||||
// replay.TotalFrames / replay.GetFrame(frameIndex)
|
||||
for (int i = 0; i < replay.TotalFrames; i++) {
|
||||
var frame = replay.GetFrame(i);
|
||||
// frame.SimulationTime, frame.EntitySnapshots...
|
||||
}
|
||||
```
|
||||
|
||||
### EntitySnapshot（每帧推送）
|
||||
---
|
||||
|
||||
## 四、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.CreateTask(name, "") / mgr.DeleteTask(id) / mgr.Search(kw, from, to, page, size)
|
||||
mgr.SaveScene / SaveTarget / SaveDeployment / SaveCloud / SaveRoute / UpdateStep
|
||||
mgr.GetDetail(id) → TaskFullConfig
|
||||
```
|
||||
|
||||
### SimulationRunner — 仿真执行
|
||||
|
||||
```csharp
|
||||
var runner = GetComponent<SimulationRunner>();
|
||||
runner.LoadAndStart(taskId);
|
||||
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(taskId, detail, events, status, duration) → SimulationReport
|
||||
rm.Export(reportId) → 文件路径
|
||||
```
|
||||
|
||||
### ReplayController — 回放
|
||||
|
||||
```csharp
|
||||
var replay = GetComponent<ReplayController>();
|
||||
replay.LoadReplay(taskId);
|
||||
replay.TotalFrames / replay.GetFrame(index)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、EntitySnapshot（每帧推送）
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `EntityId` | string | 实体唯一 ID |
|
||||
| `EntityType` | enum | Drone/Platform/Munition/Cloud/DetectionEquip |
|
||||
| `EntityType` | enum | Drone / Platform / Munition / Cloud / DetectionEquip |
|
||||
| `PosX/Y/Z` | float | 三维位置 |
|
||||
| `VelX/Y/Z` | float | 瞬时速度 (m/s) |
|
||||
| `Hp` | float | 无人机血量 (0~1) |
|
||||
| `DamageStage` | int | 损伤阶段 (0~N) |
|
||||
| `PlatformStateStr` | string | 平台状态 (Idle/FlyingToTarget/ReadyToRelease) |
|
||||
| `DamageStage` | int | 损伤阶段 |
|
||||
| `PlatformStateStr` | string | Idle / FlyingToTarget / ReadyToRelease |
|
||||
| `CloudRadius` | float | 云团有效半径 |
|
||||
| `CloudOpacity` | float | 云团不透明度 (0~1) |
|
||||
| `CloudPhase` | int | 云团扩散阶段 (1/2/3) |
|
||||
| `CloudElapsed` | float | 云团已存在时间 (s) |
|
||||
| `CloudOpacity` | float | 不透明度 (0~1) |
|
||||
| `CloudPhase` | int | 扩散阶段 (1/2/3) |
|
||||
| `CloudElapsed` | float | 已存在时间 (s) |
|
||||
|
||||
### 实体属性（直接访问）
|
||||
---
|
||||
|
||||
## 六、实体属性速查
|
||||
|
||||
| 实体 | 关键属性 |
|
||||
|------|------|
|
||||
| **DroneEntity** | Id, PosX/Y/Z, Hp, Status, ExposureTime, TargetType, PowerType, Wingspan, CruiseSpeed, Route, TraveledArc, TotalArc, Progress |
|
||||
| **CloudEntity** | Id, PosX/Y/Z, Radius, Density, Phase, Elapsed, IsDissipated, AerosolType |
|
||||
| **MunitionEntity** | Id, PosX/Y/Z, Velocity, StartX/Y/Z, LaunchTime, ElapsedTime, LaunchAngle, Azimuth, MuzzleVelocity, FlightDuration, TargetX/Y/Z, ReleaseAltitude, HasArrived |
|
||||
| **PlatformEntity** | Id, PosX/Y/Z, CurrentVelocity, State, MunitionCount, Cooldown, MuzzleVelocity, CruiseSpeed, ReleaseAltitude, TargetX/Y/Z, FlightDistance |
|
||||
| **DroneEntity** | Id, PosX/Y/Z, Hp, Status, Type, 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() |
|
||||
|
||||
---
|
||||
|
||||
## 五、基础数据 CRUD（DataService）
|
||||
|
||||
`SimulationRunner.DataService` 提供 7 类基础数据的增删改查：
|
||||
|
||||
```csharp
|
||||
var ds = runner.DataService;
|
||||
|
||||
// 弹药
|
||||
var ammo = ds.GetAllAmmo();
|
||||
ds.SaveAmmo(new AmmunitionSpec { Id = "custom", ... });
|
||||
ds.DeleteAmmo("custom");
|
||||
|
||||
// 火力单元规格
|
||||
ds.GetAllFireUnits();
|
||||
ds.SaveFireUnit(spec);
|
||||
ds.DeleteFireUnit(id);
|
||||
|
||||
// 无人机规格
|
||||
ds.GetAllDrones();
|
||||
ds.SaveDrone(spec);
|
||||
ds.DeleteDrone(id);
|
||||
|
||||
// 传感器规格
|
||||
ds.GetAllSensors();
|
||||
ds.SaveSensor(spec);
|
||||
ds.DeleteSensor(id);
|
||||
|
||||
// 环境规格
|
||||
ds.GetAllEnvironments();
|
||||
ds.SaveEnvironment(spec);
|
||||
ds.DeleteEnvironment(id);
|
||||
|
||||
// 编队模板
|
||||
ds.GetAllFormations();
|
||||
ds.SaveFormation(spec);
|
||||
ds.DeleteFormation(id);
|
||||
|
||||
// 航线模板
|
||||
ds.GetAllRoutes();
|
||||
ds.SaveRoute(spec);
|
||||
ds.DeleteRoute(id);
|
||||
```
|
||||
|
||||
### 规格类命名对照
|
||||
## 七、规格类命名对照
|
||||
|
||||
| 旧名 | 新名 | SQLite 表 |
|
||||
|------|------|------|
|
||||
@ -241,48 +221,35 @@ ds.DeleteRoute(id);
|
||||
|
||||
---
|
||||
|
||||
## 六、默认数据
|
||||
## 八、默认数据
|
||||
|
||||
首次运行 `DatabaseManager.OpenMainDb()` 自动从 `data/defaults.json` 种子数据库：
|
||||
首次运行自动种子，含 6 个 `[Demo]` 预设想定：
|
||||
|
||||
| 类别 | 内容 | 示例 ID |
|
||||
|------|------|------|
|
||||
| 弹药 | 3 种 | `inert` / `active` / `fuel` |
|
||||
| 编队 | 6 种 | `single` / `line-3` / `swarm-10` |
|
||||
| 航线 | 6 条 | `3km-h300` / `5km-h500` / `10km-h500` / `20km-h500` |
|
||||
| 火力单元 | 4 种 | `ground-light` / `ground-standard` / `ground-heavy` / `air-standard` |
|
||||
| 无人机 | 6 种 | `quadcopter` / `shahed` / `cruise-missile` |
|
||||
| 探测设备 | 4 种 | `radar-mr` / `eo-station` |
|
||||
| 天气 | 6 种 | `sunny-calm` / `fog` / `night` |
|
||||
| 预设想定 | 6 个 | `[Demo] 活塞拦截-西风5ms` |
|
||||
|
||||
所有默认数据名称含 `[Demo]` 前缀，UI 中可识别。预设可通过 API 直接获取：
|
||||
|
||||
```csharp
|
||||
var defaults = DefaultData.Load(new UnityPathProvider());
|
||||
var ammo = defaults.Ammunition.First(a => a.Id == "inert");
|
||||
var route = defaults.Routes.First(r => r.Id == "5km-h500").ToWaypoints(200);
|
||||
var unit = defaults.FireUnits.First(f => f.Id == "ground-light").ToEquipmentDeployment(AerosolType.InertGas, 1, 1500, 0, 50);
|
||||
```
|
||||
| 类别 | 示例 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
|
||||
# 覆盖 Assets/Plugins/CounterDrone.Core/ 下所有 DLL
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 八、参考
|
||||
## 十、参考
|
||||
|
||||
| 文档 | 位置 |
|
||||
|------|------|
|
||||
| 架构设计 | `docs/design/architecture/总体架构设计.md` |
|
||||
| 实体事件映射 | `docs/design/technical/仿真器实体与事件映射.md` |
|
||||
| 任务跟踪 | `docs/implementation/tasks/实施计划与任务跟踪.md` |
|
||||
| 测试报告 | `test/reports/`（每次集成测试自动生成） |
|
||||
| 测试状态 | **243 测试，11 秒（全部通过）** |
|
||||
|
||||
Loading…
Reference in New Issue
Block a user