From 6b005cf9cc074fb773914b6fc6dbaf14aa6d28c7 Mon Sep 17 00:00:00 2001 From: tian <11429339@qq.com> Date: Tue, 16 Jun 2026 11:27:13 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=B7=9F=E8=B8=AA=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E6=9B=B4=E6=96=B0=E8=87=B3=20V1.5=20+=20=E6=8E=A2=E6=B5=8B?= =?UTF-8?q?=E7=BB=9F=E4=B8=80=E5=8E=9F=E5=88=99=E5=AE=9A=E6=80=A7=E7=BA=A0?= =?UTF-8?q?=E6=AD=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1. 实施计划与任务跟踪 V1.4 -> V1.5： - 阶段总览补 Phase 9(完成)/Phase 10(待开发) - 校准现状：7.1 性能优化 ✅(<20->200+ FPS)、8.1.1 探测设计完成 - 测试数 191 -> 204，执行时间 41s -> 7s - Phase 8 标题去掉误导性 ✅，未完成项(蜂群/PDF/Word/第三方)补 ⬜ - 新增 Phase 9：性能优化 5 项 + 文档校准 3 项(均 ✅) - 新增 Phase 10：探测实时链路任务拆解(T1-T5, 依赖图, 总预估 11h) - 里程碑补 M8/M9/M10 2. 探测统一原则定性纠正(总体架构设计 14.2/14.2.1/14.7)： - 原表述"统一原则"被弱化为"好看的对称"，且有"planner 可保留 2D"备选方案 - 纠正：仿真是按 planner 规划执行的，planner 探测判定 = 仿真事实依据 - planner 若用 2D 判定"能发现"但目标高度超出 3D 球冠范围，会导致 "未探测却拦截并摧毁"的物理错误结局 - 统一原则是正确性硬约束，T3 不可砍、不可降级为 2D - 澄清两个独立问题：采样误差(<=1.5s)不影响火力计划(正确)； 2D->3D 几何升级不可省略(我之前漏了) --- docs/design/architecture/总体架构设计.md | 12 +- .../tasks/实施计划与任务跟踪.md | 143 +++++++++++++++--- 2 files changed, 131 insertions(+), 24 deletions(-) diff --git a/docs/design/architecture/总体架构设计.md b/docs/design/architecture/总体架构设计.md index e2c94bd..a844290 100644 --- a/docs/design/architecture/总体架构设计.md +++ b/docs/design/architecture/总体架构设计.md @@ -1742,7 +1742,7 @@ float EffectiveRange(float radarRange, float eoRange, float irRange, float visib } ``` -> **统一原则**：planner 的静态估算与运行时实时扫描必须用同一个探测几何判定，否则会出现"规划以为能发现、运行时却没发现"的不一致。 +> **统一原则（正确性硬约束）**：planner 的事前规划与运行时实时探测**必须用同一个 3D 球冠判定模型**（`IsInCoverage`）。原因：仿真是按 planner 规划执行的，planner 的探测判定就是仿真的事实依据——若 planner 用比真实探测能力更宽松的几何（如 2D 圆），会规划出"未探测却拦截"的物理错误结局（详见 14.2.1）。 ### 14.2.1 三维球冠探测几何（决策 5） @@ -1788,7 +1788,13 @@ bool IsInCoverage( } ``` -> **planner 适配**：`EarliestDetection`/`EarliestEntryArc` 当前用线段-圆求交，升级 3D 后需改为"沿航路逐采样点调用 `IsInCoverage`"（解析求三维球冠-折线交点复杂度高，采样法足够且与实时探测判定一致）。这是 3D 升级的主要工作量。 +> **planner 必须升级到 3D（正确性硬要求，非精度优化）**： +> `EarliestDetection`/`EarliestEntryArc` 当前用线段-圆求交（纯 2D），必须改为"沿航路逐采样点调用 `IsInCoverage`"。 +> **原因**：仿真是按 planner 规划执行的——planner 判定"威胁能被发现"→ 据此规划拦截→ 仿真照此执行→ 威胁被摧毁。若 planner 用 2D 判定"能发现"，但威胁实际高度超出 3D 球冠范围（探测设备真实能力达不到），就会出现**"根本没探测到、却被规划拦截并摧毁"的物理错误结局**——防空系统不可能拦截它没发现的目标。 +> +> 因此 planner 与实时探测**必须共用同一个 3D 球冠判定**（`IsInCoverage`），这不是为了"好看的统一"，而是正确性硬约束。 +> +> **采样法 vs 解析法**：三维球冠-折线解析求交复杂度高，改用沿航路采样（步长 ≤ 50m）。采样引入的弧长误差 ≤ 一个步长，换算到推荐抛撒时机 ≤ ~1.5s（典型 120km/h），远小于云团膨胀窗口（~30s）和云团重叠冗余，**不影响火力计划结果**。所以采样误差可接受，但 2D→3D 的几何升级不可省略。 ### 14.3 探测源构成 @@ -1905,7 +1911,7 @@ FOR EACH 飞行无人机（维护"本帧已发现该目标的最优探测设备" | **DetectionSource 类加字段** | 14.5.1 | 同上 4 个三维几何字段 | 待加属性 | | **DetectionCalculator.IsInCoverage** | 14.2.1 | 三维球冠判定（水平距离 + 俯仰角 + 高度门限），planner 与实时探测共用 | 待实现 | | **DetectionCalculator.EffectiveRange** | 14.2 | 现有签名不变（返回综合水平距离基准），3D 判定在其上层 | 已实现（基础） | -| **planner 适配 3D** | 14.2.1 | `EarliestDetection` 由"线段-圆求交"改为"沿航路采样点调 IsInCoverage" | 待改造 | +| **planner 适配 3D** | 14.2.1 | `EarliestDetection` 由"线段-圆求交"改为"沿航路采样点调 IsInCoverage"。**正确性硬要求**：planner 判定=仿真事实，必须与真实 3D 探测能力一致，否则"未探测却拦截" | 待改造 | | **SimulationEngine 加 _detectionEntities** | 5.1 | Initialize 时从配置构建 `List`，Tick 第5步遍历 | 待实现 | | **Tick 第5步实时探测** | 5.3 / 14.5.2 | 扫描 + 状态机 + 决策1/2/3/4 落地，触发 `TargetDetected` | 待实现 | diff --git a/docs/implementation/tasks/实施计划与任务跟踪.md b/docs/implementation/tasks/实施计划与任务跟踪.md index 90b2ba4..237fe7d 100644 --- a/docs/implementation/tasks/实施计划与任务跟踪.md +++ b/docs/implementation/tasks/实施计划与任务跟踪.md @@ -1,8 +1,8 @@ # 实施计划与任务跟踪 > **项目**：反无人机仿真系统后端 -> **文档版本**：V1.4 -> **更新日期**：2026-06-15 +> **文档版本**：V1.5 +> **更新日期**：2026-06-16 --- @@ -16,9 +16,11 @@ Phase 4 ✅ 仿真引擎 Phase 5 ✅ 报告生成 Phase 6 ✅ Unity 集成（桥接层 + 示例项目） Phase 7 ✅ 打磨收尾 -Phase 8 🔄 待开发（天气/物理模型统一已完成） +Phase 8 ✅ 天气/物理模型统一 +Phase 9 ✅ 性能优化 + 架构文档校准 +Phase 10 ⏳ 探测实时链路（设计完成，待开发） ──────────────────────── -已完成 P1-P7 +已完成 P1-P9 ``` --- @@ -124,7 +126,7 @@ Phase 8 🔄 待开发（天气/物理模型统一已完成） | # | 任务 | 状态 | |---|------|------| -| 7.1 | 性能优化 | ⬜（非关键，实体少时自然 < 5ms） | +| 7.1 | 性能优化 | ✅ Tick 热路径优化，Unity 满载帧率 <20→200+ FPS（详见总体架构设计第十三章） | | 7.2 | TTL 清理（FrameDataStore.CleanupExpired + 测试） | ✅ | | 7.3 | 边界测试（空部署/强风/超长航路/空基弹药） | ✅ | | 7.4 | 错误处理加固 | ⬜（基本校验已有） | @@ -139,10 +141,10 @@ Phase 8 🔄 待开发（天气/物理模型统一已完成） | 指标 | 值 | |------|------| -| 测试总数 | **191** | +| 测试总数 | **204**（通过 202，跳过 2） | | 行覆盖率 | **95.4%**（待重测） | | 分支覆盖率 | **80.5%**（待重测） | -| 执行时间 | ~41 秒 | +| 执行时间 | ~7 秒 | | Core 程序集 | `CounterDrone.Core.dll` (.NET Standard 2.1) | | 共享物理工具类 | `Kinematics` / `RouteGeometry` / `CloudExpansionModel` / `DamageAssessment` | | 全局配置 | `data/planner_config.json`（planner 策略参数，代码零默认值） | @@ -152,9 +154,10 @@ Phase 8 🔄 待开发（天气/物理模型统一已完成） --- -## 四、Phase 8：待开发功能（后端范围） +## 四、Phase 8：天气/物理统一与功能增强 -> UI/视觉/动画属于前端同事范畴，以下仅列后端 Core 需实现的功能。 +> 8.0（天气/物理统一）已完成；8.1/8.2/8.3 为后续增强功能，部分待开发。 +> UI/视觉/动画属于前端同事范畴，以下仅列后端 Core 的功能。 ### 8.0 天气与物理模型统一（✅ 已完成） @@ -173,30 +176,125 @@ Phase 8 🔄 待开发（天气/物理模型统一已完成） | # | 功能 | 说明 | |---|------|------| -| 8.1.1 | 探测设备搜索逻辑 | ✅ 事前规划已接入探测能力：`DetectionCalculator` 算统一信息网络最早探测点，planner 基于探测边界（非上帝视角起点）算到达时间；天气（Visibility）衰减光电探测距离；探测精度影响抛撒散布。实时探测→火控链路留作未来增强 | -| 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.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.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` 切换到第三方实现后的集成测试 | +| 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\ 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 不计入后端）。 + +--- + +## 七、里程碑 | 里程碑 | 状态 | |------|------| @@ -207,10 +305,13 @@ Phase 8 🔄 待开发（天气/物理模型统一已完成） | M5 — 报告可生成 | ✅ | | M6 — Unity 可演示 | ✅ | | M7 — 交付就绪 | ✅ | +| M8 — 天气/物理模型统一 | ✅ | +| M9 — 性能优化 + 文档校准 | ✅ | +| M10 — 探测实时链路 | ⏳ 设计完成（V13），待开发 | --- -## 六、状态图例 +## 八、状态图例 | 符号 | 含义 | |------|------|