From eeed692ba6da92ad8bb7595d243226ceb1a71aba Mon Sep 17 00:00:00 2001
From: MHW <wei2309328087@163.com>
Date: Mon, 30 Mar 2026 16:50:38 +0800
Subject: [PATCH] =?UTF-8?q?=E7=81=AB=E5=8A=9B=E8=A7=84=E5=88=99=EF=BC=9A?=
 =?UTF-8?q?=E7=BB=84=E4=BB=B6=E5=8C=B9=E9=85=8D=E4=BF=AE=E6=94=B9=EF=BC=88?=
 =?UTF-8?q?=E6=B3=A8=E9=87=8A=E4=BF=AE=E6=94=B9=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../src/main/resources/rules/README.md        | 374 +++++++++++++-----
 1 file changed, 282 insertions(+), 92 deletions(-)

diff --git a/auto-solution-rule/src/main/resources/rules/README.md b/auto-solution-rule/src/main/resources/rules/README.md
index d91d47c..6e715d0 100644
--- a/auto-solution-rule/src/main/resources/rules/README.md
+++ b/auto-solution-rule/src/main/resources/rules/README.md
@@ -1,88 +1,108 @@
-# fire-rule.drl 说明文档
+# fire-rule.drl 维护说明（业务+开发）
 
-本文档对应当前 `auto-solution-rule/src/main/resources/rules/fire-rule.drl` 的实现，分为三部分：
-- 业务人员修改
-- 业务人员理解
-- 开发人员理解
+本文档对应 `auto-solution-rule/src/main/resources/rules/fire-rule.drl` 当前版本，重点说明：
+- 业务人员改哪里
+- 每个参数改了会产生什么效果
+- 如何快速判断规则是否“命中/不命中”
 
----
+## 1. 先看这一个入口：业务可改区
 
-## 一、业务人员修改（只改这里）
 
-只改 `buildBusinessConfig()` 的配置值，不要改 `rule/function` 代码。
 
-### 1) 武器匹配配置
-- `map_air_targets`：蓝方空中目标 -> 红方武器（逗号分隔，多选）
-- `map_ground_targets`：蓝方地面目标 -> 红方武器
-- `map_armor_targets`：蓝方装甲目标 -> 红方武器
-- `map_artillery_targets`：蓝方炮类目标 -> 红方武器
-- `map_missile_targets`：蓝方导弹能力目标 -> 红方武器
-- `enableAirRule/enableGroundRule/enableArmorRule/enableMissileVehicleRule`：是否启用对应策略
-- `allowMultiGroup`：是否允许多组策略叠加
+只改 `//TODO` 下的 `buildBusinessConfig()`，其他函数不要改。
 
-### 2) 导弹联动配置
-- `enableMissileLinkage`：导弹联动开关
-- `missileCountOffset`：红方导弹数量偏移
-- `missileRangeOffset`：红方导弹范围偏移
-- `minBlueMissileCountForLinkage`：蓝方导弹数量触发阈值
+`buildBusinessConfig()` 里每个参数的效果如下。
 
-### 3) targetId 绑定配置
-- `enableTargetAutoBind`：是否自动给红方武器写 `targetId`
-- `minTargetBindRatio`：最低绑定比例（例：`0.7`）
-- `allowReserveWithoutTarget`：是否允许少量红方武器 `targetId` 为空
+## 2. 参数-效果对照（给业务人员）
 
-### 4) 阵位部署配置
-- `enablePositionRules`：阵位规则总开关
-- `fireUnitSpacingMeters`：火力单元间距（米）
-- `airDeployZonePreference`：飞机优先区（`combat`/`defense`）
-- `defensePriorityWeapons`：优先防区部署武器（逗号分隔）
-- `groundDeployHeight` / `airDeployHeight`：地面/空中部署高度
-- 区域输入固定来自 `blueTask.warZoneLocation` 与 `blueTask.defZoneLocation`（各 4 点经纬度）
+### 2.1 武器名称映射（改名字，不改逻辑）
+- `redStrikeDroneName`：空中反制组中的无人机名称。
+- `redArmedHelicopterName`：空中反制组中的武装直升机名称。
+- `redHowitzerName`：地面反制组中的迫榴炮名称。
+- `redVehicleMortarName`：地面反制组中的车载迫击炮名称。
+- `redAaWeaponName`：空中反制组中的防空导弹武器名称。
+- `redAtRocketName`：装甲反制组中的反坦克火箭名称。
+- `redAtMissileSystemName`：装甲反制组中的反坦克导弹系统名称。
+- `redMissileVehicleName`：导弹补充组中的导弹发射车名称。
 
-### 5) 航迹策略配置
-- `enableTrajectoryRules`：航迹规则总开关
-- `strategyMode`：`auto/shortest/flank/interfere`
-- `enableShortest/enableFlank/enableInterfere`：策略开关
-- `nearDefDistanceMeters`、`farDefDistanceMeters`、`fastSpeedThreshold`：智能选择阈值
-- `flankOffsetMeters`：绕后偏移
-- `interfereOffsetMeters`、`interfereZigzagAmplitude`：干扰偏移与摆动
-- `keepBlueHeight`：是否沿用蓝方高度
-- `redTrackHeightOverride`：不沿用时红方统一高度
+### 2.2 白名单开关（决定“是否匹配”）
+- `enableAirRule`：`true` 时，蓝方空中目标会触发红方空中反制组；`false` 时该组永不触发。
+- `enableGroundRule`：`true` 时，蓝方地面目标会触发红方炮类反制组；`false` 时不触发。
+- `enableArmorRule`：`true` 时，蓝方装甲目标会触发红方反坦克组；`false` 时不触发。
+- `enableMissileVehicleRule`：`true` 时，蓝方有导弹能力可追加导弹发射车；`false` 时不追加。
+- `enableMissileLinkage`：`true` 时开启导弹数量/范围联动；`false` 时不做导弹联动增强。
+- `allowMultiGroup`：
+  - `true`：同一批输入可命中多组策略并叠加武器；
+  - `false`：只命中第一组，后续组不再生效（更“死规则”）。
+- `enableArmedHelicopterOnAir`：空中组中是否包含武装直升机。
 
----
+### 2.3 蓝方类型到红方方案映射（核心，可多选）
 
-## 二、业务人员理解（规则在做什么）
+先解释你提到的 “k”：
+- 这里的 `k` 就是 **key（键名）**，例如 `map_armor_targets`。
+- `v` 是 **value（值）**，例如 `反坦克火箭,反坦克导弹系统`。
+- 规则实际含义就是：`key` 决定“哪类蓝方目标”，`value` 决定“红方上哪些武器”。
 
-### 1) 武器匹配
-- 根据蓝方武器类型匹配红方武器。
-- 映射可多选，可关闭，可允许不命中。
+映射键名中文对照：
+- `map_air_targets`：蓝方是空中目标时，红方使用哪些武器。
+- `map_ground_targets`：蓝方是地面目标时，红方使用哪些武器。
+- `map_armor_targets`：蓝方是装甲目标（坦克/装甲车）时，红方使用哪些武器。
+- `map_artillery_targets`：蓝方是炮类目标时，红方使用哪些武器。
+- `map_missile_targets`：蓝方有导弹能力时，红方使用哪些武器。
 
-### 2) 组件与参数
-- 红方武器自动补组件和参数。
-- 炮类武器组件限制为“炮弹”，单位“范围米”。
+映射规则说明：
+- 值必须是红方武器库内合法名称，否则该项会被忽略。
+- 为空时视为该组不配置，允许不命中。
+- 示例：`map_armor_targets=反坦克火箭,反坦克导弹系统` 表示坦克可同时触发两种红方反制武器。
 
-### 3) 任务自动命名
-- 任务名按红方最终武器自动生成，确保名称和武器一致。
+### 2.4 数量和阈值（决定“匹配后给多少”）
+- `defaultAirNum`：空中组默认数量。
+- `defaultGroundNum`：地面/装甲组默认数量。
+- `defaultMissileVehicleNum`：导弹发射车默认数量。
+- `shellRangeDefault`：炮类组件参数值，单位固定 `范围米`。
+- `missileCountOffset`：红方导弹数量 = 蓝方导弹数量 + 偏移量。
+- `missileRangeOffset`：红方导弹范围 = 蓝方导弹范围 + 偏移量（单位 `破坏范围米`）。
+- `blueMissileRangeDefault`：蓝方导弹范围缺失时采用的默认值。
+- `minBlueMissileCountForLinkage`：蓝方导弹数量达到该值才触发联动增强。
 
-### 4) 目标绑定
-- 红方武器 `targetId` 自动绑定蓝方 `equipmentId`。
-- 支持同类优先匹配和绑定比例控制。
-- 允许少量空目标做火力冗余。
+### 2.5 全组件数量匹配参数（新增）
+- `enableComponentQuantityMatch`：是否启用全组件数量覆盖（非导弹组件）。
+- `componentDeviceNameMappingCsv`：组件名映射表（逗号分隔），格式 `蓝组件deviceName->红组件deviceName`；为空则默认 `deviceName` 直匹配。
+- `skipMissileComponentsByNameContains`：跳过覆盖关键词：蓝方组件 `deviceName` 包含该关键词则不覆盖；默认 `导弹`（用于保留导弹联动偏移）。
 
-### 5) 阵位部署
-- 依据作战区/防区多边形（4点）生成部署点。
-- 飞机按偏好区部署，重火力优先防区。
-- 支持“每 N 米一个火力单元”覆盖。
+### 2.6 targetId 自动绑定参数（新增）
+- `enableTargetAutoBind`：是否自动给红方武器写入 `targetId`。
+- `minTargetBindRatio`：最低绑定比例（例如 `0.7` 表示至少 70% 红方武器有目标）。
+- `allowReserveWithoutTarget`：
+  - `true`：允许少量红方武器 `targetId` 为空（火力冗余）。
+  - `false`：尽量给每个红方武器分配目标。
 
-### 6) 航迹生成
-- 红方 `trackPoints` 根据蓝方 `trackPoints` 生成。
-- 点数保持一致。
-- 策略可手动选或自动选：
-  - near+fast -> shortest
-  - far+fast -> interfere
-  - 其他 -> flank
+绑定规则说明（固定，不需要业务改代码）：
+- 绑定来源是蓝方武器 `equipmentId`。
+- 匹配优先级按武器类型：
+  - 防空类红方武器优先绑定蓝方空中目标
+  - 反装甲类红方武器优先绑定蓝方装甲目标
+  - 炮类红方武器优先绑定蓝方炮类/地面目标
+  - 导弹发射车优先绑定蓝方导弹能力目标
+- 当优先池不足时自动回退到地面池/全目标池，保证大部分武器有目标。
+
+### 2.7 阵位规则参数（新增）
+- `enablePositionRules`：阵位规则总开关。
+- 阵位输入来源：`blueTask.warZoneLocation` 与 `blueTask.defZoneLocation`（各 4 个经纬点）。
+- `fireUnitSpacingMeters`：防区/作战区点位间距（米），例如 `100` 代表约每 100 米一个火力单元。
+- `airDeployZonePreference`：飞机优先部署区域（`combat` 或 `defense`）。
+- `defensePriorityWeapons`：优先部署在防区的武器名单（逗号分隔）。
+- `groundDeployHeight` / `airDeployHeight`：地面/空中武器部署高度。
+
+阵位规则效果：
+- 新增两条规则：
+  - `阵位规则-区域解析与点位生成`
+  - `阵位规则-武器部署赋位`
+- 飞机可在任意区（按偏好区优先）；反坦克等重火力优先防区。
+- 在多边形区域内按间距生成候选点，并给红方武器写入 `weapon.coordinate`。
+
+阵位输入示例（仅经纬度，4点）：
 
-### 7) 阵位输入示例（Task 字段）
 ```json
 {
   "warZoneLocation": [
@@ -100,34 +120,204 @@
 }
 ```
 
----
+### 2.8 航迹规则参数（新增）
+- `enableTrajectoryRules`：航迹规则总开关。
+- `strategyMode`：`auto/shortest/flank/interfere`。
+  - `auto`：智能选择策略。
+  - 其他值：强制使用指定策略（若该策略被禁用会自动回退）。
+- `enableShortest` / `enableFlank` / `enableInterfere`：各策略开关。
+- `nearDefDistanceMeters`：蓝方末端点到防区的“近距离阈值”。
+- `farDefDistanceMeters`：蓝方末端点到防区的“远距离阈值”。
+- `fastSpeedThreshold`：蓝方平均速度达到该值视为“高速”。
+- `flankOffsetMeters`：绕后追击偏移幅度（越大绕后越明显）。
+- `interfereOffsetMeters`：干扰轨迹基础偏移。
+- `interfereZigzagAmplitude`：干扰轨迹锯齿振幅（越大摆动越明显）。
+- `keepBlueHeight`：是否沿用蓝方高度。
+- `redTrackHeightOverride`：不沿用时红方统一高度。
 
-## 三、开发人员理解（维护重点）
+航迹智能选择逻辑：
+- `near + fast` -> `shortest`（最短距离追击）
+- `far + fast` -> `interfere`（干扰/诱偏）
+- 其他 -> `flank`（绕后追击）
 
-### 1) 主要规则链（agenda-group: 打击任务）
-- `红方武器自适应装配规则`
-- `导弹联动增强规则`
-- `任务自动匹配规则`
-- `阵位规则-区域解析与点位生成`
-- `阵位规则-武器部署赋位`
-- `航迹规则-生成红方航迹`
+不生成保护：
+- 蓝方 `trackPoints` 为空，或 `defZoneLocation` 点数不足（<3），则不生成红方航迹。
 
-`任务匹配1/2`、`装备组件匹配`、`组件参数匹配` 为 legacy 占位。
+## 3. 当前规则行为（简版）
 
-### 2) 关键函数
-- 武器装配：`configureRedWeaponsByBlue(...)`
-- 导弹联动：`applyMissileLinkage(...)`
-- 任务命名：`assignTaskNameByRedWeapons(...)`
-- 目标绑定：`bindTargetIdsForRedWeapons(...)`
-- 阵位部署：`prepareDeploymentPools(...)`、`applyWeaponDeployment(...)`
-- 航迹生成：`applyTrajectoryGeneration(...)`、`chooseTrajectoryStrategy(...)`、`generateRedTrackPoints(...)`
+- `装备组件匹配`、`组件参数匹配`：已作为 `legacy` 占位，不承担当前业务决策。
+- 主决策在 `红方武器自适应装配规则`：调用 `configureRedWeaponsByBlue(...)`，按“映射配置”添加武器。
+- 导弹增强在 `导弹联动增强规则`：调用 `applyMissileLinkage(...)`，受开关和阈值控制。
+- 全组件数量匹配在 `全组件数量匹配规则`：按红方 `targetId` 绑定蓝方装备，覆盖非导弹组件 `componentParams[0].number`；找不到组件/targetId 允许跳过。
+- 任务命名在 `任务自动匹配规则`：调用 `assignTaskNameByRedWeapons(...)`，按红方最终武器自动生成任务名和 `dataType`。
+- 炮类约束：命中炮类条件时，炮类武器只保留 `炮弹` 组件，单位 `范围米`。
+- `targetId` 绑定：在装配后自动执行，尽量为红方武器绑定蓝方 `equipmentId`，允许少量空值冗余。
+- 阵位部署：按多边形区域和武器类型自动赋位，保证防区火力覆盖。
+- 航迹生成：根据蓝方 `trackPoints` 生成红方 `trackPoints`，点数与蓝方一致，支持三套策略和智能选择。
 
-### 3) Drools 注意事项
-- DRL function 避免泛型签名（如 `List<Coordinate>`），统一用原始 `List/Map`。
-- 读取配置统一走 `readIntCfg/readBooleanCfg/readDoubleCfg`。
-- 新规则尽量参数化放进 `buildBusinessConfig()`，不要硬编码常量在函数里。
+## 3.1 任务名称自动匹配（新增）
 
-### 4) 输入约定
-- 阵位：`blueTask.warZoneLocation/defZoneLocation`（`List<Coordinate>`，4 点）
-- 航迹：`blueTask.trackPoints` 非空才会生成红方航迹
-- 目标绑定：蓝方武器应提供 `equipmentId`
+任务命名依据：**红方最终武器**（不是蓝方任务名关键字）。
+
+当前分类优先级：
+- 导弹突击（导弹发射车）
+- 防空压制（防空导弹武器/火力打击无人机/武装直升机）
+- 反装甲打击（反坦克火箭/反坦克导弹系统）
+- 炮火压制（迫榴炮/车载迫击炮）
+- 通用打击（兜底）
+
+业务可调模板（在 `buildBusinessConfig()`）：
+- `taskName_missile_strike` / `taskDataType_missile_strike`
+- `taskName_air_defence` / `taskDataType_air_defence`
+- `taskName_anti_armor` / `taskDataType_anti_armor`
+- `taskName_artillery` / `taskDataType_artillery`
+- `taskName_general` / `taskDataType_general`
+
+效果说明：
+- 只改这些模板文字，不改函数，也能改变最终任务展示名。
+- 若分类与武器不一致，会自动回落到 `通用打击任务`，避免“任务名和武器不符”。
+
+## 4. 快速修改示例（业务常用）
+
+- 想让规则更“死”：
+  - 把 `allowMultiGroup` 改成 `false`。
+- 想让“坦克只上反坦克火箭，不上导弹系统”：
+  - 把 `map_armor_targets` 改成 `反坦克火箭`。
+- 想让“坦克同时上火箭和导弹系统”：
+  - 把 `map_armor_targets` 改成 `反坦克火箭,反坦克导弹系统`。
+- 想允许更多不命中：
+  - 关闭部分开关，例如 `enableGroundRule=false`、`enableArmorRule=false`。
+- 想让导弹联动更难触发：
+  - 提高 `minBlueMissileCountForLinkage`，例如从 `1` 调到 `3`。
+- 想提升炮类打击范围：
+  - 调大 `shellRangeDefault`，例如 `1500 -> 1800`。
+
+## 5. 测试 JSON（按你项目常用的 Task 入参格式）
+
+说明：下面 JSON 是 **单个 Task** 格式，不是 `FactTask` 包装格式。
+如果你的执行入口最终需要 `FactTask`，则由开发在服务层把“蓝方 Task + 红方 Task”组装后再 `insert` 规则引擎。
+
+### 5.1 不命中样例（蓝方 Task）
+说明：该样例仅用于蓝方任务输入结构校验；若业务把对应映射留空或关闭开关，则允许不命中。
+
+```json
+{
+  "id": "blue-miss-001",
+  "side": "蓝方",
+  "dataType": "打击",
+  "threatLevel": "2",
+  "taskWeapons": [
+    {
+      "name": "攻击直升机",
+      "supportType": "overhead",
+      "number": 1,
+      "components": []
+    }
+  ]
+}
+```
+
+### 5.2 命中样例（蓝方 Task）
+说明：该蓝方输入同时包含空中和装甲特征，且有导弹组件，满足命中与联动测试条件。
+
+```json
+{
+  "id": "blue-hit-001",
+  "side": "蓝方",
+  "dataType": "打击",
+  "threatLevel": "3",
+  "taskWeapons": [
+    {
+      "name": "攻击直升机",
+      "supportType": "overhead",
+      "number": 2,
+      "components": [
+        {
+          "deviceName": "机载导弹",
+          "componentParams": [
+            {
+              "attDefaultValue": "260",
+              "attExplain": "破坏范围米",
+              "number": 2
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "name": "主战坦克",
+      "supportType": "ground",
+      "number": 2,
+      "components": []
+    }
+  ]
+}
+```
+
+### 5.3 红方初始 Task 样例（通常为空列表）
+说明：用于和蓝方 Task 组装成规则输入对象。
+
+```json
+{
+  "id": "red-init-001",
+  "side": "红方",
+  "dataType": "打击",
+  "threatLevel": "1",
+  "taskWeapons": []
+}
+```
+
+### 5.4 航迹规则不生成样例（缺防区）
+```json
+{
+  "id": "blue-track-miss-001",
+  "side": "蓝方",
+  "dataType": "打击",
+  "threatLevel": "2",
+  "defZoneLocation": [],
+  "trackPoints": [
+    { "index": 0, "longitude": 116.3801, "latitude": 39.9001, "height": 100, "speed": 210 },
+    { "index": 1, "longitude": 116.3810, "latitude": 39.9010, "height": 100, "speed": 220 }
+  ],
+  "taskWeapons": []
+}
+```
+
+### 5.5 航迹规则命中样例（可生成）
+```json
+{
+  "id": "blue-track-hit-001",
+  "side": "蓝方",
+  "dataType": "打击",
+  "threatLevel": "3",
+  "defZoneLocation": [
+    { "longitude": 116.4001, "latitude": 39.9201 },
+    { "longitude": 116.4051, "latitude": 39.9201 },
+    { "longitude": 116.4051, "latitude": 39.9251 },
+    { "longitude": 116.4001, "latitude": 39.9251 }
+  ],
+  "trackPoints": [
+    { "index": 0, "longitude": 116.3801, "latitude": 39.9001, "height": 120, "speed": 240 },
+    { "index": 1, "longitude": 116.3840, "latitude": 39.9040, "height": 120, "speed": 245 },
+    { "index": 2, "longitude": 116.3880, "latitude": 39.9080, "height": 120, "speed": 250 },
+    { "index": 3, "longitude": 116.3920, "latitude": 39.9120, "height": 120, "speed": 248 }
+  ],
+  "taskWeapons": []
+}
+```
+
+## 6. 开发人员说明（放在末尾）
+
+- **入口约定**：业务仅改 `buildBusinessConfig()`，开发改函数实现时不要破坏该入口。
+- **类型约定**：配置读取统一走 `readIntCfg(...)` / `readBooleanCfg(...)`，避免 `Map` 强转异常。
+- **策略收敛**：`configureRedWeaponsByBlue(...)` 使用 `matchedAny + allowMultiGroup` 控制“单组命中/多组叠加”。
+- **映射解析**：通过 `parseMappedWeaponNames(...)` 将逗号分隔配置解析为武器列表，非法名称会被 `isValidRedWeaponNameByConfig(...)` 过滤。
+- **联动门控**：`applyMissileLinkage(...)` 必须同时满足：
+  - `enableMissileLinkage=true`
+  - 蓝方导弹数量 `>= minBlueMissileCountForLinkage`
+- **目标绑定**：`bindTargetIdsForRedWeapons(...)` 基于蓝方 `equipmentId` 分配 `targetId`，支持“优先匹配 + 绑定率阈值 + 冗余空目标”。
+- **阵位部署**：`prepareDeploymentPools(...)` + `applyWeaponDeployment(...)` 负责区域解析、点位生成与部署赋位。
+- **航迹生成**：`applyTrajectoryGeneration(...)` + `chooseTrajectoryStrategy(...)` + `generateRedTrackPoints(...)` 负责红方航迹策略生成。
+- **任务命名**：`assignTaskNameByRedWeapons(...)` 仅基于红方最终武器，避免旧版按蓝方 `drawName` 关键字造成误判。
+- **legacy 区域**：`装备组件匹配`、`组件参数匹配` 及 legacy 函数区只保留回滚，不建议继续扩展。
+- **新增武器建议**：优先补 `isAirWeapon/isGroundWeapon/isArmorWeapon/isArtilleryWeapon` 分类，再补 `ensureBasicRedComponents(...)` 模板。