# 实施计划与任务跟踪

> **项目**：反无人机仿真系统后端  
> **文档版本**：V1.5  
> **更新日期**：2026-06-16  

---

## 一、阶段总览

```
Phase 1  ✅ 核心基础
Phase 2  ✅ 想定管理
Phase 3  ✅ 算法层
Phase 4  ✅ 仿真引擎
Phase 5  ✅ 报告生成
Phase 6  ✅ Unity 集成（桥接层 + 示例项目）
Phase 7  ✅ 打磨收尾
Phase 8  ✅ 天气/物理模型统一
Phase 9  ✅ 性能优化 + 架构文档校准
Phase 10 ⏳ 探测实时链路（设计完成，待开发）
────────────────────────
已完成   P1-P9
```

---

## 二、各阶段详情

### Phase 1：核心基础 ✅

**目标**：搭建项目骨架，数据层可读写，单元测试全绿。  
**测试**：27 个

| # | 任务 | 状态 |
|---|------|------|
| 1.1-1.12 | 项目骨架、枚举、数据模型、Repository、ModelService、单元测试 | ✅ |

---

### Phase 2：想定管理 ✅

**目标**：仿真任务的完整 CRUD + 5 步配置保存/加载 + 搜索分页。  
**测试**：20 个

| # | 任务 | 状态 |
|---|------|------|
| 2.1-2.14 | 8 个 Repository、ScenarioService、搜索分页、输入校验、单元测试 | ✅ |

---

### Phase 3：算法层 ✅

**目标**：高斯烟团扩散模型、三种毁伤模型、防御推荐算法全部实现。  
**测试**：26 个

| # | 任务 | 状态 |
|---|------|------|
| 3.1-3.12 | GaussianPuffDispersion、InertGas/ActiveMaterial/ActiveFuel 毁伤模型、DefaultDefenseAdvisor、AlgorithmFactory | ✅ |

**关键设计变更**：
- 推荐算法由弹药规格驱动，查库选型
- 计算多轮次云团（CloudSalvo）确保覆盖率
- 输入校验：无目标/无航路/弹药缺失时返回失败原因
- Kinematics 工具类：抛物线弹道、风矢量、多边形判定

---

### Phase 4：仿真引擎 ✅

**目标**：完整仿真引擎 + 集成测试。  
**测试**：11 个

| # | 任务 | 状态 |
|---|------|------|
| 4.1-4.16 | 6 个实体类、FireSchedule 发射计划、FrameDataStore 分库、Pause/Resume/Stop、集成测试 | ✅ |

**关键设计变更**：
- 引擎重构为纯执行器：`SetFireSchedule()` 接收计划，不包含任何决策
- `TimeScale` 属性支持加速仿真（集成测试 4 倍速）
- 弹道飞行时间用 `Kinematics` 真实计算
- 集成测试：4 个端到端场景全通过（NoDefense/ZoneIntrusion/Piston/Jet）

---

### Phase 5：报告生成 ✅

**目标**：仿真结束后自动生成 Markdown 报告并导出文件。  
**测试**：7 个

| # | 任务 | 状态 |
|---|------|------|
| 5.1-5.8 | ReportGenerator、ReportService、ExportToFile、搜索分页、单元测试 | ✅ |

**注**：PDF/Word 导出暂以 Markdown 替代，后续可扩展。

---

### Phase 6：Unity 集成 ✅

**目标**：将 Core.dll 集成到 Unity，实现完整运行链路。  
**前置条件**：安装 Unity Hub + Editor 22.3.62  
**位置**：`src/Unity/`（完整 Unity 项目）

| # | 任务 | 预估 | 状态 | 说明 |
|---|------|------|------|------|
| 6.1 | 创建 Unity 项目，导入 Core.dll | 1h | ✅ | `src/Unity/` 项目，16 个 DLL → `Assets/Plugins/` |
| 6.2 | 实现 `UnityPathProvider` | 1h | ✅ | `Application.persistentDataPath` 桥接 |
| 6.3 | 实现 `ModelManager` | 3h | ✅ | 导入/删除/查询，含 Verify |
| 6.4 | 实现 `ScenarioManager`（5 步配置） | 4h | ✅ | 完整 CRUD + 搜索分页 + 多批次 Route |
| 6.5 | 实现 `SimulationRunner`（Update 驱动） | 3h | ✅ | Tick 驱动 + 事件订阅 + 实体位置同步 + 炮弹轨迹可视化 |
| 6.6 | 实现 `ReplayController`（帧加载） | 3h | ✅ | 从分库加载帧数据，TotalFrames/GetFrame |
| 6.7 | 实现 `ReportManager` | 2h | ✅ | 生成 + Markdown 导出 |
| 6.8 | 3D 实体可视化 | 4h | ✅ | Drone/Cube、Cloud/Sphere、Munition/Cylinder，逐帧位置同步 |
| 6.9 | 粒子系统参数传递 | 3h | ✅ | 云团半径缩放 + 颜色/透明度动态更新 |
| 6.10 | 端到端联调 + 一键验证 | 6h | ✅ | `ManagerVerification` 7 模块全过，`SimulationBootstrap` 一键 Demo |

**额外交付物**：
- `SimulationBootstrap.cs`：一键创建想定 → 推荐方案 → 启动仿真（Scene 直接运行）
- `simple_simulation.unity`：预配置场景文件
- `ManagerVerification`：Inspector 右键 `Run Full Verification` → Console 7 行 OK

---

### Phase 7：打磨收尾 ✅

| # | 任务 | 状态 |
|---|------|------|
| 7.1 | 性能优化 | ✅ Tick 热路径优化，Unity 满载帧率 <20→200+ FPS（详见总体架构设计第十三章） |
| 7.2 | TTL 清理（FrameDataStore.CleanupExpired + 测试） | ✅ |
| 7.3 | 边界测试（空部署/强风/超长航路/空基弹药） | ✅ |
| 7.4 | 错误处理加固 | ⬜（基本校验已有） |
| 7.5 | 测试覆盖率 | ✅ 95.4% 行 / 80.5% 分支 |
| 7.6 | README + API XML 文档 | ✅ |
| — | 死代码清理（DetectionEntity, EventQueue） | ✅ |
| — | 代码格式化（.editorconfig + dotnet format） | ✅ |

---

## 三、最终指标

| 指标 | 值 |
|------|------|
| 测试总数 | **204**（通过 202，跳过 2） |
| 行覆盖率 | **95.4%**（待重测） |
| 分支覆盖率 | **80.5%**（待重测） |
| 执行时间 | ~7 秒 |
| Core 程序集 | `CounterDrone.Core.dll` (.NET Standard 2.1) |
| 共享物理工具类 | `Kinematics` / `RouteGeometry` / `CloudExpansionModel` / `DamageAssessment` |
| 全局配置 | `data/planner_config.json`（planner 策略参数，代码零默认值） |
| Unity 项目 | `src/Unity/`（Unity 2022.3.62） |
| Unity Manager | 8 个 MonoBehaviour 桥接 + Bootstrap + SqliteConnectionTracker |
| 零 Unity 依赖 | ✅ Core 可脱离 Unity 独立运行和测试 |

---

## 四、Phase 8：天气/物理统一与功能增强

> 8.0（天气/物理统一）已完成；8.1/8.2/8.3 为后续增强功能，部分待开发。
> UI/视觉/动画属于前端同事范畴，以下仅列后端 Core 的功能。

### 8.0 天气与物理模型统一（✅ 已完成）

| # | 功能 | 说明 |
|---|------|------|
| 8.0.1 | 天气纳入扩散模型 | ✅ 修复 `GaussianPuffDispersion` 写死 Sunny 的 bug，Phase3 用真实 `env.WeatherType` 推导 Pasquill 稳定度 |
| 8.0.2 | Planner 风偏补偿 | ✅ 抛撒点逆风预置（`cloudGen = 穿越点 − windVec×expansionTime`），云团漂移后回到航路 |
| 8.0.3 | 去除无人机风偏叠加 | ✅ DroneEntity 不再叠加风位移（真实无人机有飞控修正），planner 与引擎速度模型一致 |
| 8.0.4 | PathInSphere 云团参考系修正 | ✅ 毁伤判定改在云团参考系（`drone.Pos − cloud.Center`），修正移动球导致的每 tick ~2m 系统误差 |
| 8.0.5 | ComputeEffectiveRadius 云龄 bug | ✅ 从 `ArrivalTime×2`（无人机飞行时间，概念错误）改为 `expansionTime`（云团自身膨胀时长） |
| 8.0.6 | 物理模型统一架构 | ✅ 新增 `RouteGeometry` 静态工具类，planner 与引擎共用航路几何；planner 删除所有本地物理公式 |
| 8.0.7 | 配置外置 | ✅ 新增 `PlannerConfig` + `planner_config.json`，策略参数（重叠系数、类型系数、弹药匹配、概率阈值）全部从配置读，代码零默认值 |
| 8.0.8 | 云团重叠布局 | ✅ 间距 `2R×(1−重叠比例)`，默认重叠 20%，消除相切处密度空洞；offset 沿航路切向，支持任意方向/折线航路 |

### 8.1 仿真增强

| # | 功能 | 说明 |
|---|------|------|
| 8.1.1 | 探测设备搜索逻辑 | ✅ 事前规划：`DetectionCalculator` 算统一信息网络最早探测点，planner 基于探测边界算到达时间；天气衰减光电；精度影响散布。**实时探测设计完成**（总体架构设计第十四章），待 Phase 10 开发 |
| 8.1.2 | 蜂群运动模型 | ⬜ `FormationMode.Swarm` 枚举已定义，需差异化行为（随机扰动、个体差异） |
| 8.1.3 | 空基平台 + DefensePlanner | ✅ 五步规划引擎，通道模型，物理间隔错发，路径积分毁伤判定 |
| 8.1.4 | 预置典型目标库 | ⬜ 具体无人机型号 JSON 配置（如 DJI Mavic 3、Shahed-136 等），导入 `TargetConfig` 默认值 |
| 8.1.5 | 毁伤曲线参数校准 | ✅ RequiredExposureSeconds 替代硬编码，密度阈值统一在引擎检查 |
| 8.1.6 | Fallback/default 清理 | ✅ 删除所有硬编码默认值和静默 fallback，参数缺失即报错 |

### 8.2 报告与导出

| # | 功能 | 说明 |
|---|------|------|
| 8.2.1 | PDF 导出 | ⬜ QuestPDF 或其他 .NET Standard 2.1 方案调研，`IReportService.ExportReport()` 实现 |
| 8.2.2 | Word 导出 | ⬜ 调研可行方案 |

### 8.3 第三方对接

| # | 功能 | 说明 |
|---|------|------|
| 8.3.1 | 第三方 DLL 接口规范 | ⬜ 与供应商对齐 `ICloudDispersionModel` P/Invoke 签名和调用约定 |
| 8.3.2 | 扩散模型替换验证 | ⬜ 通过 `AlgorithmFactory.Register` 切换到第三方实现后的集成测试 |

---

## 五、Phase 9：性能优化 + 架构文档校准 ✅

**目标**：Tick 热路径性能优化（Unity 满载 <20→200+ FPS）+ 总体架构设计文档与实现对齐。

### 9.1 性能优化（✅ 已完成）

| # | 任务 | 状态 | 说明 |
|---|------|------|------|
| 9.1.1 | DroneEntity 航路几何缓存 | ✅ | 构造时预算 `_totalArc`/`_segLen[]`/`_cumArc[]`，Update 内 O(1) 定位段，消除每帧重复几何运算 |
| 9.1.2 | 仿真期零字符串分配 | ✅ | EntitySnapshot 强类型字段流转，JSON 推迟到 Flush；Unity 端移除 JsonDocument.Parse（最大收益项） |
| 9.1.3 | ControlZoneEntity 顶点 2D 缓存 | ✅ | 构造时缓存 `_vertices2D`，ContainsPoint 零分配 |
| 9.1.4 | 帧数据内存缓存+批量落库 | ✅ | List\<FrameRecord\> struct 缓冲，Flush 单事务 InsertAll |
| 9.1.5 | 毁伤判定快速排斥 | ✅ | 浓度阈值 + 2R 距离两层裁剪 |

> 详见《总体架构设计》第十三章。优化前后实测：Unity 满载渲染帧率 <20 FPS（卡顿）→ 200+ FPS。

### 9.2 架构文档校准（✅ 已完成）

| # | 任务 | 状态 | 说明 |
|---|------|------|------|
| 9.2.1 | 修正文档与实现不符 | ✅ | AlgorithmFactory(Func 工厂)、IDefensePlanner.Plan(4参数)、IDamageModel(RequiredExposureSeconds)、FrameDataStore(类非接口)、删除 IRecordService、DroneEntity 弧长运动、Tick 流程顺序、StateData 双轨 |
| 9.2.2 | 新增性能设计章节 | ✅ | 总体架构设计 第十三章 |
| 9.2.3 | 探测设备行为设计 | ✅ | 总体架构设计 第十四章（双链路 + 3D 球冠 + 5 项决策 + 数据模型清单）|

---

## 六、Phase 10：探测实时链路开发 ⏳（设计完成，待开发）

**目标**：实现仿真运行时实时探测（链路 B），产生 `TargetDetected` 事件 + 可视化数据；并将 planner 探测判定升级到 3D 球冠。
**前置设计**：《总体架构设计》第十四章（V13），5 项行为决策已确认（见 14.6）。
**关键约束**：
- 实时探测是**纯只读观测层**（决策 3/4），不影响 FireSchedule、不驱动拦截；
- **planner 与实时探测必须共用 3D 球冠判定**（`IsInCoverage`）——正确性硬要求，否则会出现"未探测却拦截"的物理错误（详见 T3）。

> 任务依赖关系见 10.5。建议按 T1→T2→T3→T4 顺序，T5/T6 可并行。

### 10.1 数据层（T1）

| # | 任务 | 预估 | 状态 | 说明 |
|---|------|------|------|------|
| T1.1 | EquipmentDeployment 加 4 列 | 0.5h | ⬜ | `MinElevation`/`MaxElevation`/`MinDetectAlt`/`MaxDetectAlt`，均 NULLABLE |
| T1.2 | DetectionSource 类扩展 | 0.5h | ⬜ | 同步加 4 个三维几何属性 |
| T1.3 | BuildDetectionSources 读取新字段 | 0.5h | ⬜ | 缺失时退化球冠（无限制，等价 2D），保证存量数据平滑过渡 |

### 10.2 算法层（T2）

| # | 任务 | 预估 | 状态 | 说明 |
|---|------|------|------|------|
| T2.1 | DetectionCalculator.IsInCoverage | 1h | ⬜ | 3D 球冠判定：水平距离 + 俯仰角 ∈ [Min,Max]Elevation + 高度 ∈ [Min,Max]DetectAlt |
| T2.2 | IsInCoverage 单元测试 | 0.5h | ⬜ | 边界用例：球冠内/外、正顶、俯仰越界、高度越界 |

### 10.3 planner 3D 适配（T3）🔒 正确性硬要求

| # | 任务 | 预估 | 状态 | 说明 |
|---|------|------|------|------|
| T3.1 | EarliestDetection 改采样法 | 2h | ⬜ | 从"线段-圆解析求交"改为"沿航路采样点（步长≤50m）调 IsInCoverage" |
| T3.2 | DefensePlannerTests 回归验证 | 1h | ⬜ | 跑全量测试验证；若有测试因 3D 高度门限导致"探测不到→拦截失败"而失败，需核查是测试用例高度设置问题还是真实回归 |

> 🔒 **T3 不可砍、不可降级为 2D**。这是正确性硬约束，不是精度优化：
> - 仿真是按 planner 规划执行的，**planner 的探测判定 = 仿真的事实依据**。
> - 若 planner 保留 2D 圆判定，会出现"目标高度超出探测设备真实 3D 球冠范围（探测不到），但 planner 按 2D 判定能发现并规划拦截、仿真照此摧毁"的**物理错误结局**——防空系统不可能拦截它没发现的目标。
> - 因此 planner 必须与实时探测共用 `IsInCoverage`（详见总体架构设计 14.2.1）。
>
> **关于采样误差（已澄清，可放心）**：采样法 vs 解析法的弧长误差 ≤ 一个步长（50m），换算到推荐抛撒时机 ≤ ~1.5s（120km/h），远小于云团膨胀窗口（~30s）和云团重叠冗余，**不影响火力计划结果**。所以 T3 的重点是用 3D 几何保证"该探测的能探测、不该探测的探测不到"，而非追求采样精度。

### 10.4 引擎层（T4）

| # | 任务 | 预估 | 状态 | 说明 |
|---|------|------|------|------|
| T4.1 | DetectionEntity 运行时实体 | 1h | ⬜ | 持有 DetectionSource + 每无人机探测状态机（Undetected ⇄ Detected） |
| T4.2 | SimulationEngine 加 _detectionEntities | 0.5h | ⬜ | Initialize 时构建，Tick 第 5 步遍历 |
| T4.3 | Tick 第 5 步实时扫描 | 2h | ⬜ | 决策 1（离开回退）、决策 2（融合取最早/同刻取精度高），触发 TargetDetected |
| T4.4 | SimulationEngineTests 验证 | 1h | ⬜ | 断言：进入探测范围触发事件、离开后再次进入重新触发、多设备融合取最早 |

### 10.5 前端 / 报告（T5，可并行）

| # | 任务 | 预估 | 状态 | 说明 |
|---|------|------|------|------|
| T5.1 | Unity 探测范围可视化 | — | ⬜ | 前端范畴：3D 球冠 wireframe / 发现标记（决策 4 仅可视化） |
| T5.2 | 时序图/报告纳入 TargetDetected | 0.5h | ⬜ | ReportGenerator 时序表增加发现事件 |

### 10.6 任务依赖与顺序

```
T1（数据层）→ T2（算法层 IsInCoverage）
                    ↓
        T3（planner 3D 适配 ⚠️耦合点）→ T4（引擎实时扫描）
                                              ↓
                                         T5（前端/报告，可并行）
```

**总预估**：约 11h（T1 1.5h + T2 1.5h + T3 3h + T4 4.5h + T5.2 0.5h；前端 T5.1 不计入后端）。

---

## 七、里程碑

| 里程碑 | 状态 |
|------|------|
| M1 — 数据层就绪 | ✅ |
| M2 — 想定可配置 | ✅ |
| M3 — 算法可计算 | ✅ |
| M4 — 仿真可运行 | ✅ |
| M5 — 报告可生成 | ✅ |
| M6 — Unity 可演示 | ✅ |
| M7 — 交付就绪 | ✅ |
| M8 — 天气/物理模型统一 | ✅ |
| M9 — 性能优化 + 文档校准 | ✅ |
| M10 — 探测实时链路 | ⏳ 设计完成（V13），待开发 |

---

## 八、状态图例

| 符号 | 含义 |
|------|------|
| ⬜ | 未开始 |
| 🔄 | 进行中 |
| ✅ | 已完成 |
| ⏸️ | 阻塞 |
| ❌ | 放弃 |
