kcode-pi 0.1.0

package/vendor/kingdee-skills/cosmic-unittest/SKILL.md

@@ -0,0 +1,788 @@
+---
+name: cosmic-unittest
+version: "1.4"
+description: |
+  苍穹模块单元测试编写技能 — 适用于任何遵循 common / business / opplugin / formplugin 四工程结构的苍穹模块。
+  当用户说"写单测"、"写单元测试"、"写测试"、"写测试用例"、"补单测"、"补测试"、"加测试"、"生成测试"、
+  "unittest"、"unit test"、"test case"，或打开苍穹模块的 Java 源码/测试文件并要求编写测试时触发。
+globs:
+  # 源码文件（用户打开被测类时触发）
+  - "**/*-common/src/main/**/*.java"
+  - "**/*-business/src/main/**/*.java"
+  - "**/*-opplugin/src/main/**/*.java"
+  - "**/*-formplugin/src/main/**/*.java"
+  # 测试文件（用户打开或编辑已有测试时触发）
+  - "**/*-common/src/test/**/*.java"
+  - "**/*-business/src/test/**/*.java"
+  - "**/*-opplugin/src/test/**/*.java"
+  - "**/*-formplugin/src/test/**/*.java"
+---
+
+# 苍穹模块单元测试编写技能
+
+## 技能说明
+
+本技能适用于任何遵循「四工程结构」的金蝶云苍穹模块，包括但不限于：
+- **mmc-sfc**（SFC 车间管理）、**bd-mpdm**（生产数据管理）、**sys-xkbase** 等各业务模块
+
+四大工程角色通用定义：
+- **`<模块组>-common`**：公共模块（常量类 / 枚举类 / POJO / 工具类）
+- **`<模块组>-business`**：静态帮助类 / 业务逻辑
+- **`<模块组>-opplugin`**：操作插件（Validator / OpPlugin / ConvertPlugin）
+- **`<模块组>-formplugin`**：表单插件（继承 AbstractFormPlugin / AbstractListPlugin / AbstractBillPlugin 的子类）
+
+> `<模块组>` 是被测类所在模块的前缀，需在 Step 0 中自动识别（如 `mmc-sfc`、`bd-mpdm`）。
+
+---
+
+## 目录结构
+
+```
+cosmic-unittest/
+├── SKILL.md                    ← 本文件：技能入口与决策树
+├── patterns/
+│   ├── common-module.md        ← 公共模块测试模式（POJO / 枚举 / 工具类）
+│   ├── business-helper.md      ← 业务帮助类测试模式
+│   ├── validator.md            ← 校验器测试模式
+│   ├── op-plugin.md            ← 操作插件测试模式
+│   ├── convert-plugin.md       ← 转换插件测试模式
+│   └── formplugin.md           ← 表单插件测试模式（formplugin 工程专用）
+└── examples/
+    ├── common-test.md          ← 完整 common 测试示例（POJO / 枚举 / 工具类）
+    ├── business-test.md        ← 完整 business 测试示例
+    ├── validator-test.md       ← 完整 validator 测试示例
+    ├── op-plugin-test.md       ← 完整 op-plugin 测试示例
+    └── formplugin-test.md      ← 完整 formplugin 测试示例（BasePluginTest<T> 继承模式）
+```
+
+---
+
+## Step 0: 判断测试类型
+
+### Step 0.0: 识别模块组前缀
+
+**首先**从被测类的包名或文件路径中提取**模块组前缀**：
+
+```
+包名示例                           对应模块组前缀
+kd.mmc.sfc.business.XxxHelper   →  mmc-sfc
+kd.bd.mpdm.business.XxxHelper   →  bd-mpdm
+kd.sys.xkbase.business.XxxHelper →  sys-xkbase
+```
+
+识别后将前缀统一称为 `<模块组>`，后续所有工程名、包名、路径均基于此进行推导。
+
+### Step 0.1: 根据工程类型决定测试模式
+
+### ⚡ 按需加载 pattern 文件（性能优化）
+
+根据 Step 0.1 识别出的工程类型，**只读取对应的 1 个 pattern 文件**，禁止全量加载所有 pattern：
+
+| 工程类型 | 读取的 pattern 文件 | 按需参考的 example 文件 |
+|---------|-------------------|---------------------|
+| common - POJO/DTO | `patterns/common-module.md` #POJO 段 | `examples/common-test.md` POJO 段 |
+| common - 枚举 | `patterns/common-module.md` #Enum 段 | `examples/common-test.md` Enum 段 |
+| common - 工具类 | `patterns/common-module.md` #Utils 段 | `examples/common-test.md` Utils 段 |
+| business | `patterns/business-helper.md` | `examples/business-test.md` |
+| opplugin - Validator | `patterns/validator.md` | `examples/validator-test.md` |
+| opplugin - OpPlugin | `patterns/op-plugin.md` | `examples/op-plugin-test.md` |
+| opplugin - ConvertPlugin | `patterns/convert-plugin.md` | `examples/op-plugin-test.md`（参考结构） |
+| formplugin | `patterns/formplugin.md` | `examples/formplugin-test.md` |
+
+> example 文件仅在需要参考具体写法时读取，非必读。
+
+### Step 0.2: 批量测试识别（同工程多个类）
+
+若用户一次提交了**同一工程下多个被测类**，采用批量模式提升效率：
+
+```
+批量模式流程
+│
+├─ Step 1：并行读取所有被测类源码，统一完成分析（含 Bug 检查）
+├─ Step 2：跳过分析摘要确认（遵循用户偏好），直接生成代码
+├─ Step 3：依次生成所有测试类代码（可并行生成互不依赖的测试类）
+└─ Step 4：全部生成完成后，执行一次 Gradle 运行，统一验证
+```
+
+> 批量模式的核心价值：① **Gradle 只冷启动一次**；② **文件读取并行化**（所有被测类源码同一轮并行读取）；③ **测试类生成可并行**（同工程不同被测类的测试类互不依赖）。
+
+### ⚡ 批量模式并行策略（性能优化）
+
+批量模式下，各步骤的并行执行策略：
+
+| 步骤 | 并行策略 | 说明 |
+|------|---------|------|
+| 源码读取 | 所有被测类 + 所有常量类 + BaseTest 同一轮并行读取 | 减少多轮串行等待 |
+| 逻辑分析 | 逐类分析，但汇总输出一次 | 批量模式仍跳过确认环节 |
+| 代码生成 | 互不依赖的测试类可并行生成 | 同工程的 BaseTest 共享，减少重复读取 |
+| Gradle 验证 | 只执行一次 `gradle :<模块组>-<工程>:test` | 所有测试类合并一次运行 |
+
+收到用户「写单元测试」请求时，根据被测类所在工程决定测试模式：
+
+```
+被测类在哪个工程?
+│
+├─ <模块组>-common（公共模块：常量 / 枚举 / POJO / 工具类）
+│   ├─ POJO / DTO / Bean 类（纯 getter/setter）
+│   │   → 使用 POJO 测试模式（读 patterns/common-module.md #POJO）
+│   │   → 无需 Mock，无需基类，直接 new 对象测试
+│   │
+│   ├─ 枚举类（含业务方法如 getByCode / match）
+│   │   → 使用 Enum 测试模式（读 patterns/common-module.md #Enum）
+│   │   → 继承 AbstractJunitNoDependenciesTest
+│   │
+│   └─ 工具类（XxxUtil / XxxUtils，含静态方法）
+│       → 使用 Common Utils 测试模式（读 patterns/common-module.md #Utils）
+│       → 继承当前模块 common 工程的 BaseTest 或 AbstractJunitNoDependenciesResManagerTest
+│   → 测试文件放在: <模块组>-common/src/test/java/...
+│
+├─ <模块组>-business（XxxHelper / XxxService 等静态工具类）
+│   → 使用 Business Helper 测试模式（读 patterns/business-helper.md）
+│   → 测试文件放在: <模块组>-business/src/test/java/...
+│
+├─ <模块组>-opplugin
+│   ├─ Validator 目录下的校验器类
+│   │   → 使用 Validator 测试模式（读 patterns/validator.md）
+│   │
+│   ├─ 继承 AbstractOperationServicePlugIn 的操作插件
+│   │   → 使用 OpPlugin 测试模式（读 patterns/op-plugin.md）
+│   │
+│   └─ ConvertPlugin / BotpPlugin 等转换插件
+│       → 使用 ConvertPlugin 测试模式（读 patterns/convert-plugin.md）
+│   → 测试文件放在: <模块组>-opplugin/src/test/java/...
+│
+└─ <模块组>-formplugin（表单插件，继承 AbstractFormPlugin / AbstractListPlugin / AbstractBillPlugin 的子类）
+    → 使用 FormPlugin 测试模式（读 patterns/formplugin.md）
+    → 基类与参数获取优先级：
+       1. 优先在 <模块组>-formplugin/src/test/java/ 下搜索 BasePluginTest 获取测试所需参数及 mock 取值逻辑
+       2. 若 BasePluginTest 中未定义相关逻辑，参考同包及子包下 *Test 结尾类的类似写法
+       3. 若以上均无可参考案例，尝试使用苍穹公共单测框架，并**主动告知用户**缺失的取值逻辑，由用户补充到 BasePluginTest
+    → 测试文件放在: <模块组>-formplugin/src/test/java/... （与被测类保持相同包路径）
+```
+
+---
+
+## Step 0.5: 获取 Author 信息
+
+在生成 `@UnittestCaseInfo` 注解前，按以下优先级获取作者信息：
+
+### 优先级 1：从缓存文件读取（快速路径）
+
+尝试读取 `.qoder/skills/cosmic-unittest/author-cache.json`：
+
+```json
+{
+  "author": "zhang_san <zhang_san@kingdee.com>",
+  "lastUpdateAuthor": "zhang_san <zhang_san@kingdee.com>"
+}
+```
+
+若文件存在且 `author` 字段非空，**直接使用缓存值，跳过 git config 命令**。
+
+### 优先级 2：从 git config 读取并写入缓存
+
+若缓存文件不存在或 `author` 为空，执行：
+
+```bash
+git config user.name
+git config user.email
+```
+
+读取成功后：
+1. 按格式拼接：`"<name> <<name>@kingdee.com>"`，例如 `"zhang_san <zhang_san@kingdee.com>"`
+2. **将结果写入 `.qoder/skills/cosmic-unittest/author-cache.json`**，供后续直接复用
+
+### 优先级 3：询问用户
+
+若 git config 读取失败，主动询问用户提供姓名和邮箱，填写后同样写入缓存文件。
+
+### .gitignore 检查
+
+首次写入 `author-cache.json` 后，检查项目根目录的 `.gitignore` 是否已包含该文件的忽略规则：
+
+```
+.qoder/skills/cosmic-unittest/author-cache.json
+```
+
+若未忽略，**提示用户将上述规则添加到 `.gitignore`**，避免个人信息被提交到 git 仓库。
+
+---
+
+> `lastUpdateTime` = 用例编写时的当前时间，格式 `yyyy-MM-dd HH:mm:ss`
+
+---
+
+## Step 1: 分析被测类
+
+### 快速模式判断（POJO / 枚举 → 跳过分析摘要）
+
+若被测类属于以下**极简场景**，**直接跳过「被测逻辑分析」摘要输出，立即生成测试代码**：
+
+| 极简场景 | 判断依据 |
+|---------|--------|
+| **POJO / DTO / Bean** | 类中只有字段 + getter/setter/构造方法，无业务逻辑方法 |
+| **纯枚举类** | 仅含枚举值定义，无自定义业务方法（如 `getByCode` / `match`）；或只有一个简单的 `getByCode` 静态方法 |
+
+> 对于上述场景，无需 Mock、无分支、无依赖，分析摘要价值极低，直接生成代码效率更高。
+
+---
+
+其余类型（工具类 / Business Helper / Validator / OpPlugin / FormPlugin）按完整流程执行：
+
+1. 读取被测类的完整源码
+2. 识别所有 public / protected 方法
+3. 识别被测方法中调用的**静态方法**（这些需要 MockedStatic）
+4. 识别被测方法中依赖的**外部服务**（QueryServiceHelper、BusinessDataServiceHelper 等）
+5. 识别方法参数中的 **DynamicObject** 结构（需要 DynamicObjectMocker 构造）
+6. **识别被测方法中的 switch 分支和判断分支**（用于 Step 3 设计测试方法拆分策略）
+7. **检查被测代码是否存在 Bug**（见下方说明）
+
+### ⚡ 并行全量读取（性能优化）
+
+读取被测类源码后，**立即将以下所有文件读取并行发起**，在同一轮 tool calls 中一次性拿齐，不得串行逐个等待：
+
+| 读取目标 | 搜索/读取方式 | 说明 |
+|---------|-------------|------|
+| 常量类 / 枚举类 | 从 import 提取 `Const/Consts/Enum` 结尾的类名，grep_code 并行搜索 | 搜索实际使用的字段值 |
+| BaseTest 源码 | search_file 搜索 `BaseTest.java` 或 `BasePluginTest.java` | 确认预置 MockedStatic |
+| 对应 pattern 文件 | 直接 read_file（Step 0.1 已确定文件名） | 若 Step 0 未读取则在此补读 |
+| 被测方法调用的关联类 | 从 import 提取同模块的 Helper/Service 类 | 读取方法签名 |
+
+```
+示例（一轮并行 tool calls）：
+1. grep_code → ProcessPlanConsts 中被测方法使用的字段
+2. grep_code → SendWorkConsts 中被测方法使用的字段
+3. search_file → BaseTest.java
+4. read_file → patterns/op-plugin.md
+5. grep_code → BillUnitAndQtytHelper 方法签名
+```
+
+> 本次优化来源：v1.3 已实现常量并行读取，v1.4 将其扩展为「全量并行」，
+> 将 BaseTest、pattern、关联类的读取也纳入同一批次，减少多轮串行等待。
+
+### ⚡ 智能 Mock 推断（性能优化）
+
+从被测类的 import 语句中，**自动推断**需要 Mock 的静态类，与「常用 Mock 清单」对照匹配：
+
+```
+推断规则：
+1. 扫描被测类所有 import，提取「常用 Mock 清单」中出现的类
+2. 将这些类标记为「候选 Mock 类」
+3. 结合 BaseTest 已预置的 MockedStatic 进行去重（详见优化4）
+4. 仅对「候选 Mock 类 - BaseTest 已预置」的差集声明新的 MockedStatic
+```
+
+**常见 import → Mock 映射表**：
+
+| import 中的类 | 需 Mock 的方式 |
+|-------------|-------------|
+| `kd.bos.servicehelper.QueryServiceHelper` | `mockStatic` + `.when(() -> query(...))` |
+| `kd.bos.servicehelper.BusinessDataServiceHelper` | `mockStatic` + `.when(() -> loadSingle/load/loadFromCache(...))` |
+| `kd.bos.servicehelper.OperationServiceHelper` | `mockStatic` + `.when(() -> executeOperate(...))` |
+| `kd.bos.servicehelper.SaveServiceHelper` | `mockStatic` + `.when(() -> save/update(...))` |
+| `kd.bos.servicehelper.base.BaseDataServiceHelper` | `mockStatic` + `.when(() -> getBaseDataFromCache(...))` |
+| `kd.bos.org.service.OrgUnitServiceHelper` | `mockStatic`（通常无需 stub 方法） |
+| `kd.bos.servicehelper.SystemParamServiceHelper` | `mockStatic` + `.when(() -> getParameterValue(...))` |
+| `kd.bos.resmanager.ResourceManager` | `mockStatic` + `.when(() -> loadKDString(...)).thenAnswer(inv -> inv.getArgument(0))` |
+| `kd.bos.servicehelper.BillTypeParamHelper` | `mockStatic`（通常无需 stub 方法） |
+| `kd.bos.db.DB` | `mockStatic`（**必须**先 ClassPool defrost，详见 2.6 节） |
+| `kd.mmc.sfc.helper.ProcessSettleHelper` | **禁止**直接 mockStatic，必须用 `ProcessSettleMockHelper`（详见 2.7 节） |
+| `kd.bos.cache.CacheFactory` | `mockStatic` + 链式 stub |
+
+> 该映射表替代人工逐个判断「这个类需不需要 Mock」，将依赖识别从经验驱动变为规则驱动。
+
+### Bug 检查要求
+
+在阅读源码阶段，必须对被测代码进行 Bug 审查。**发现 Bug 时不得让测试用例「绕过」或「迁就」该 Bug 使测试通过**，而应：
+
+1. **让测试暴露 Bug**：断言应反映**正确的预期行为**，而非当前有缺陷的实际行为，使测试失败以暴露 Bug
+2. **在测试方法上方标注**：用注释 `// ⚠️ BUG: <说明>` 标注该测试预期失败的原因
+3. **同步告知用户**：生成测试完成后，在回复中明确列出发现的 Bug，说明位置和原因
+
+**常见 Bug 类型：**
+
+| Bug 类型 | 示例 | 应对方式 |
+|---------|------|----------|
+| 边界判断方向错误 | `> 0` 应为 `>= 0` | 测试临界值，断言正确预期结果（测试会失败，暴露 Bug） |
+| 空指针风险 | 未判 null 直接调用方法 | 构造 null 入参，断言不抛异常 |
+| 逻辑取反错误 | `if (!condition)` 逻辑反了 | 断言正确分支输出 |
+| 数值计算错误 | 加减乘除逻辑有误 | 用具体数值断言期望的正确计算结果 |
+| 集合判断遗漏 | 未判空直接取第一个元素 | 构造空集合，断言不抛异常 |
+
+### 分析结果输出要求
+
+**完成 Step 1 分析后，必须在回复中输出以下结构化摘要，并等待用户确认后再进入 Step 2：**
+
+```
+## 被测逻辑分析
+
+**被测类**：全限定类名
+**被测方法**：方法签名列表
+
+### 核心逻辑梳理
+- 列出每个被测方法的主要分支和执行路径
+
+### 依赖识别
+- 静态方法（需 MockedStatic）：列出类名.方法名
+- 外部服务（需 Mock）：列出类名
+- DynamicObject 字段：列出需构造的字段及类型
+
+### Bug 检查结果
+- ✅ 未发现 Bug  /  ⚠️ 发现 Bug（详细说明位置和原因）
+```
+
+输出摘要后，**必须追加以下提示，等待用户反馈**：
+
+> 以上为分析结果，如有以下情况请现在告知，否则回复「继续」即可开始生成代码：
+> - Mock 依赖识别有误（如遗漏了某个 Helper、或识别了不需要 Mock 的类）
+> - 分支覆盖策略需要调整
+> - 有需要特殊处理的字段或业务规则
+
+> 不得跳过此输出直接给出代码。即使逻辑简单，也必须输出“未发现 Bug”的结论。
+
+---
+
+## Step 2: 编写测试类
+
+### 2.1 通用规则
+
+| 规则 | 说明 |
+|------|------|
+| 测试框架 | JUnit 4（@Test / @Before / @After） |
+| Mock 框架 | Mockito 2.x + MockedStatic |
+| **Mockito 静态导入** | **禁止**使用 `import static org.mockito.ArgumentMatchers.*` 和 `import static org.mockito.Mockito.*` 通配符导入；必须显式逐个导入，标准模板：`any` / `anyBoolean` / `anyInt` / `anyLong` / `anyString` / `eq` / `isNull`（ArgumentMatchers），`atLeastOnce` / `mock` / `never` / `verify` / `when`（Mockito），按需单独添加其他方法 |
+| 数据构造 | `DynamicObjectMocker`（链式 `.add(key, value)` 构造 DynamicObject） |
+| 基类选择 | 无 ResManager 依赖 → `AbstractJunitNoDependenciesTest`；有 ResManager → `AbstractJunitNoDependenciesResManagerTest` |
+| 反射工具 | `ReflectHelper.invokeProtectedMethod()` 测试 protected 方法；`ReflectHelper.invokeStaticMethod()` 测试 private static 方法 |
+| 资源释放 | 所有 MockedStatic 必须在 `@After` 中 `.close()` |
+| 注解 | 每个 @Test 方法**必须**加 `@UnittestCaseInfo` 和 `@DisplayName` |
+| 断言质量 | **禁止假断言，禁止缺失断言**：① 不允许出现 `assertTrue(true)`、`assertFalse(false)`、`assertEquals(x, x)` 等永真/永假断言；② **每个 @Test 方法必须至少包含一条有效的 `assert` 或 `verify` 调用**，不允许测试方法中无任何断言（包括注释掉断言、只有 step 没有 assert 等）。每个断言必须验证被测方法的**实际输出或副作用**（如返回值、Mock 交互 `verify()`、抛出异常、DynamicObject 字段值变化等）。对于「提前返回」场景，使用 `verify(mock, never()).method()` 断言某个下游调用未被触发 |
+| DynamicObject 断言 | 对 DynamicObject 取值断言时，除 `getDate(...)` 外（可能为 null），`getString()`、`getBigDecimal()`、`getLong()` 等默认不会为 null，使用基本值判定：空字符串用 `assertEquals("", obj.getString(...))`、空数值用 `assertEquals(0L, obj.getLong(...))`、空 BigDecimal 用 `assertEquals(BigDecimal.ZERO, obj.getBigDecimal(...))` |
+| switch 分支策略 | 被测方法中的 **switch 分支**，每个 case 必须拆为**独立的测试方法**；case 内部的多个场景允许在同一方法中测试（过于复杂时可进一步拆分） |
+| 判断分支覆盖 | 被测方法（含关联调用的其他方法）中的 **if/else 判断分支**，需尽量覆盖所有条件组合（笛卡尔积），可将不同条件取值合并到同一个测试方法中 |
+| 常量/枚举引用 | 若引用的常量类、枚举类**无法找到**，必须**主动告知用户**，由用户补充文件位置或源码。**禁止**忽略使用逻辑或用字面值替代 |
+
+### ⚡ BaseTest Mock 继承去重（性能优化）
+
+测试类继承 BaseTest 后，BaseTest 已预置的 MockedStatic **不得重复声明**。按以下规则去重：
+
+```
+去重流程：
+1. 读取 BaseTest 源码，提取所有 @Before 中初始化的 MockedStatic 字段
+2. 在「智能 Mock 推断」产出的「候选 Mock 类」中，减去 BaseTest 已预置的类
+3. 测试类仅需声明「差集」对应的 MockedStatic 成员变量
+4. 在 @Before 中仅初始化差集的 MockedStatic
+5. 在 @After 中仅关闭差集的 MockedStatic
+```
+
+**典型场景示例**（business 工程）：
+
+```java
+// BaseTest 已预置：QueryServiceHelper、BusinessDataServiceHelper 等 8+2 个
+// 被测类还需要：ProcessPlanHelper（不在 BaseTest 中）
+
+public class SomeHelperTest extends BaseTest {
+    // 仅声明 BaseTest 未预置的
+    MockedStatic<ProcessPlanHelper> processPlanHelper;
+
+    @Before
+    public void before() {
+        super.before();  // 触发 BaseTest 的预置 Mock
+        processPlanHelper = Mockito.mockStatic(ProcessPlanHelper.class);
+    }
+
+    @After
+    public void after() {
+        processPlanHelper.close();
+        super.after();  // BaseTest 关闭其预置 Mock
+    }
+}
+```
+
+> 去重的好处：① 减少 MockedStatic 声明和初始化代码量；② 避免 BaseTest 与测试类对同一类重复 mock 导致冲突；
+> ③ 测试类代码更简洁，关注点集中在业务特有的 Mock 上。
+
+### 2.2 @UnittestCaseInfo 注解规范
+
+```java
+@UnittestCaseInfo(
+    author = "<name> <<name>@kingdee.com>",          // 格式：git config user.name 拼接邮箱，如 "zhang_san <zhang_san@kingdee.com>"
+    title = "英文标题（简短描述测试目的）",
+    targetClass = "被测类全限定名",
+    targetMethod = "被测方法名（小写）",
+    lastUpdateTime = "yyyy-MM-dd HH:mm:ss",          // 用例编写时的当前时间
+    lastUpdateAuthor = "<name> <<name>@kingdee.com>", // 格式同 author
+    methodSignature = "被测方法完整签名",
+    testPoints = {"Functionality"},
+    description = "英文描述"
+)
+```
+
+### 2.3 测试方法注释规范
+
+```java
+@Test
+@DisplayName("中文描述：测试场景说明")
+public void testMethodName_ScenarioDescription() {
+    //step 准备测试数据 / 构建 Mock
+    ...
+    //step 执行被测方法
+    ...
+    //assert 断言结果
+    ...
+    reset();  // 如有 reset 方法
+}
+```
+
+### 2.4 MockedStatic 生命周期
+
+```java
+// 声明为成员变量
+MockedStatic<XxxServiceHelper> xxxServiceHelper;
+
+@Before
+public void before() {
+    xxxServiceHelper = Mockito.mockStatic(XxxServiceHelper.class);
+    // 配置通用返回值...
+}
+
+@After
+public void after() {
+    xxxServiceHelper.close();  // 必须关闭！
+}
+
+public void reset() {
+    xxxServiceHelper.reset();  // 在测试方法末尾重置状态
+}
+```
+
+### 2.5 DynamicObjectMocker 用法
+
+```java
+// 简单对象
+DynamicObject obj = new DynamicObjectMocker()
+    .add("id", 1L)
+    .add("billno", "TEST-001")
+    .add("status", "A")
+    .getObject();
+
+// 嵌套对象（基础资料引用）
+DynamicObject obj = new DynamicObjectMocker()
+    .add("material", new DynamicObjectMocker()
+        .add("id", 100L)
+        .add("masterid.id", 100L)
+        .getObject())
+    .add("unit", new DynamicObjectMocker()
+        .add("id", 1L)
+        .add("precision", 2)
+        .getObject())
+    .getObject();
+
+// 分录集合
+DynamicObject bill = new DynamicObjectMocker()
+    .add("id", 1L)
+    .add("entryentity", new DynamicObjectMocker()
+        .add("id", 10L)
+        .add("seq", 1)
+        .add("qty", BigDecimal.TEN)
+        .getCollection())   // 注意：分录用 getCollection()
+    .getObject();
+
+// 多行分录（用于遍历/stream 的场景）
+DynamicObjectCollection entries = new DynamicObjectCollection();
+entries.add(new DynamicObjectMocker().add("id", 1L).add("qty", BigDecimal.ONE).getObject());
+entries.add(new DynamicObjectMocker().add("id", 2L).add("qty", BigDecimal.TEN).getObject());
+DynamicObject bill = new DynamicObjectMocker()
+    .add("entryentity", entries)
+    .getObject();
+
+// ⚠️ 当被测代码用 isEmpty()/size() 作为分支判断时，必须 mock 集合：
+// new DynamicObjectCollection().add() 不能保证 isEmpty()/size() 返回正确值
+DynamicObjectCollection entries = mock(DynamicObjectCollection.class);
+when(entries.isEmpty()).thenReturn(false);
+when(entries.size()).thenReturn(2);
+```
+
+### 2.6 kd.bos.db.DB 类特殊 Mock
+
+由于 `kd.bos.db.DB` 类的特殊性（字节码冻结问题），对该类的静态方法进行 mock 前，**必须**先执行 ClassPool defrost 处理：
+
+```java
+public class SomeClassTest {
+
+    // 定义变量
+    MockedStatic<DB> dbMocked = Mockito.mockStatic(DB.class);
+
+    @Before
+    public void before() {
+        // 对 DB.class 可能已存在的 mock 执行释放
+        try {
+            CtClass cls = ClassPool.getDefault().get(DB.class.getName());
+            if (cls.isFrozen()) {
+                cls.defrost();
+            }
+        } catch (Exception e) {}
+        // 赋值新的 mock
+        dbMocked = Mockito.mockStatic(DB.class);
+    }
+
+    @After
+    public void after() {
+        dbMocked.close();
+    }
+}
+```
+
+此模式遵循 2.4 节的 MockedStatic 生命周期规则：多方法使用时定义为成员变量 + @Before/@After 管理。
+
+### 2.7 ProcessSettleHelper 特殊 Mock
+
+由于 `ProcessSettleHelper` 内部使用了苍穹平台分布式缓存，常规 `Mockito.mockStatic()` 无法满足缓存使用需求，**必须**使用专用的 Helper：
+
+```java
+MockedStatic<ProcessSettleHelper> processSettleHelper =
+    ProcessSettleMockHelper.mockDistributeSessionlessCache();
+```
+
+- `ProcessSettleMockHelper` 是各工程各自在 **test 目录下**提供的辅助类
+- 查找策略：在**当前被测类所属工程**的 `src/test/java/` 下搜索 `ProcessSettleMockHelper`
+- 若当前工程下找不到该类，**主动告知用户**，由用户在对应工程 test 目录下添加
+- **禁止**固定引用其他工程（如 formplugin）的 ProcessSettleMockHelper
+
+### 2.8 MockedConstruction（Mock 构造函数）
+
+当被测代码内部通过 `new Xxx()` 创建了某个对象，而该对象需要被 mock 时，使用 `Mockito.mockConstruction`：
+
+```java
+@Test
+public void testMethod() {
+    try (MockedConstruction<PushArgs> pushArgsMock =
+             Mockito.mockConstruction(PushArgs.class)) {
+
+        //step 执行被测方法（内部会 new PushArgs()）
+        SomeUtil.doSomething(params);
+
+        //assert 验证 PushArgs 被正确构造和使用
+        assertEquals(1, pushArgsMock.constructed().size());
+        PushArgs constructed = pushArgsMock.constructed().get(0);
+        verify(constructed).setSomeProperty(any());
+    }
+}
+```
+
+- 适用场景：被测方法内部 `new` 了无法通过参数注入的对象
+- 使用 **try-with-resources** 管理生命周期，自动关闭
+- 可与 `MockedStatic` 同时使用（在同一个 try 块中声明）
+
+### 2.9 CommonMockObject 工具
+
+`CommonMockObject` 提供了一组通用的 Mock 数据构建工具方法，所有工程均可使用：
+
+| 方法 | 说明 | 适用范围 |
+|------|------|--------|
+| `CommonMockObject.mockMainEntityType()` | Mock 主实体类型 | 通用 |
+| `CommonMockObject.getDynByString(jsonString)` | 从 JSON 字符串构造 DynamicObject | 通用 |
+| `CommonMockObject.getDynsByString(jsonString)` | 从 JSON 字符串构造 DynamicObject[] | 通用 |
+| `CommonMockObject.getDynMockerByMap(map)` | 从 Map 构造 DynamicObjectMocker（支持嵌套） | 通用 |
+| `CommonMockObject.getDynByMap(map)` | 从 Map 构造 DynamicObject | 通用 |
+| `CommonMockObject.getTestModel()` | 获取 Mock 的 IDataModel | formplugin（表单插件场景） |
+| `CommonMockObject.getTestView()` | 获取 Mock 的 IFormView | formplugin（表单插件场景） |
+
+使用示例：
+
+```java
+// 从 JSON 构造 DynamicObject（适用于复杂嵌套数据）
+DynamicObject obj = CommonMockObject.getDynByString("{\"id\":1,\"billno\":\"TEST-001\"}");
+
+// 从 Map 构造（适用于需要动态组装字段的场景）
+Map<String, Object> map = new HashMap<>();
+map.put("id", 1L);
+map.put("status", "A");
+DynamicObject obj = CommonMockObject.getDynByMap(map);
+
+// Mock 主实体类型（opplugin 场景常用）
+CommonMockObject.mockMainEntityType();
+```
+
+### 2.10 thenAnswer 动态返回模式
+
+当同一个 Mock 方法被不同参数多次调用，且需要根据入参动态返回不同结果时，使用 `thenAnswer` 代替 `thenReturn`：
+
+```java
+// thenReturn：只能返回固定值
+queryServiceHelper.when(() -> QueryServiceHelper.query(anyString(), anyString(), any()))
+    .thenReturn(fixedResult);
+
+// thenAnswer：根据入参动态返回
+queryServiceHelper.when(() -> QueryServiceHelper.query(anyString(), anyString(), any()))
+    .thenAnswer(invocation -> {
+        String entityName = invocation.getArgument(0);  // 取第1个参数
+        if ("mmc_processplan".equals(entityName)) {
+            return mockProcessPlanData();   // 查工序计划 -> 返回工序计划数据
+        }
+        if ("mmc_sendwork".equals(entityName)) {
+            return mockSendWorkData();      // 查派工单 -> 返回派工单数据
+        }
+        return new DynamicObjectCollection();  // 其他 -> 返回空集合
+    });
+```
+
+适用场景：被测方法内部对同一个 ServiceHelper 发起多次不同参数的调用，每次期望不同结果。
+
+---
+
+## Step 3: 选择测试场景
+
+为每个被测方法设计以下场景：
+
+| 场景类型 | 说明 | 示例 |
+|---------|------|------|
+| 正常路径 | 标准输入，预期正常输出 | 数据完整时校验通过 |
+| 边界条件 | 空值 / 空集合 / 零值 | 分录为空、数量为0 |
+| **边界值（重点）** | **比较运算符的临界点，必须覆盖「刚好满足」和「刚好不满足」两侧** | 见下表 |
+| 异常路径 | 异常输入或依赖服务异常 | 查询返回 null、抛异常 |
+| 业务规则 | 特定业务条件分支 | 单据状态不同的处理逻辑 |
+
+### 边界值覆盖要求
+
+**必须为每个比较运算符设计恰好覆盖两侧的测试用例：**
+
+| 比较运算符 | 必须覆盖的值 | 示例（可退回数量校验） |
+|-----------|------------|---------------------|
+| `> 0`（大于零） | 等于0（不通过）、大于0（通过） | qty=0 → 校验失败；qty=0.01 → 校验通过 |
+| `>= 0`（大于等于零） | 等于0（通过）、小于0（不通过） | qty=0 → 通过；qty=-0.01 → 失败 |
+| `a.compareTo(b) > 0` | a==b（不通过）、a>b（通过）、a<b（不通过） | rejectQty=canRejectQty（边界相等）、超出（失败）、未超出（通过） |
+| `a.compareTo(b) >= 0` | a<b（不通过）、a==b（通过）、a>b（通过） | 同上，覆盖相等时通过的情况 |
+| `size() > N` | size==N（不通过）、size==N+1（通过） | 分录恰好N条 vs N+1条 |
+| `isEmpty()` | 空集合、恰好1条、多条 | entryIdSet 为空 / 1个 / 多个 |
+
+**原则：临界值（boundary value）必须至少出现一个测试用例，不能只测「远离边界」的正常值。**
+
+### switch / 判断分支拆分策略
+
+| 分支类型 | 测试方法拆分规则 | 示例 |
+|---------|---------------|------|
+| **switch 分支** | 每个 case **必须**定义为独立的测试方法 | `testPropertyChanged_CaseFieldA()`、`testPropertyChanged_CaseFieldB()` |
+| switch case 内部多场景 | 允许在同一方法中测试多个场景（过于复杂时可进一步拆分） | 一个 case 内有 3 个 if 分支，可在一个方法中覆盖 |
+| **if/else 判断分支** | 需覆盖所有条件组合（笛卡尔积），可合并到同一测试方法 | 2 个布尔条件 → 4 种组合，可用 4 组数据在一个方法中测试 |
+| 被测方法调用的其他方法中的分支 | 同上，关联方法的判断分支也需要覆盖 | 被测方法内部调用了 `checkStatus()`，该方法的分支也需覆盖 |
+
+---
+
+## Step 4: 验证与运行
+
+测试类编写完成后，执行以下检查闭环：
+
+1. **代码静态分析（门控：发现问题必须先修复，不得直接运行 Gradle）**
+   - 确认 import 语句完整
+   - 确认所有 MockedStatic 都在 @After 中关闭
+   - 确认测试方法命名清晰（testXxx_Scenario 格式）
+   - 确认常量类/枚举类引用正确（非字面値替代）
+   - 确认 DynamicObject 断言使用基本値（非 null 判定）
+   - 确认每个 @Test 方法均有有效的 assert 或 verify 调用
+   - 确认 BaseTest 已预置的 MockedStatic 未重复声明
+   - 确认 MockedStatic 初始化顺序正确（super.before() 在前，自有 Mock 在后）
+   - **⚠️ 若以上任一项不满足，必须先修复，再执行第 2 步**
+
+2. **运行测试用例**
+
+   ### ⚡ Gradle 运行前环境快速判断（跳过无效探测）
+
+   **在运行 Gradle 前，先执行以下两项快速检查，任一失败则直接跳过 Gradle，提示用户在 IDE 中运行：**
+
+   | 检查项 | 检查方式 | 失败时处理 |
+   |--------|---------|----------|
+   | ① biz lib 中是否存在被测模块的 jar | `ls <biz路径>/<模块组>-formplugin*.jar`（或对应工程） | 不存在 → 跳过 Gradle，提示「请先在 IDE 中 Build 工程或运行 copytolib，再通过 IDE 运行测试」 |
+   | ② config.gradle 中的 biz 路径在本机是否真实存在 | 读取 `config.gradle` 中的 `biz` 路径，执行 `ls <biz路径>` | 路径不存在 → 跳过 Gradle，提示「config.gradle 路径与本机不符，请在 IDE 中运行测试」 |
+
+   > 本次优化来源：InsideAcceptEditPlugin 测试中，花费 ~8 分钟探测 gradle 可执行文件位置、
+   > 尝试构建依赖链，最终因 mmc-sfc-common.jar 未构建而失败，属于完全可预判的无效耗时。
+
+   通过环境判断后，运行 Gradle test 任务验证（根据识别到的模块组前缀替换 `<模块组>`）：
+   `gradle :<模块组>-common:test` / `gradle :<模块组>-business:test` / `gradle :<模块组>-opplugin:test` / `gradle :<模块组>-formplugin:test`
+   例如 mmc-sfc 模块：`gradle :mmc-sfc-common:test` / `gradle :mmc-sfc-business:test` / ...
+
+3. **错误修复**
+   - 对出现的错误内容进行修复（如不完善的 mock 导致取值报错、断言与实际结果不匹配等）
+   - 修复后**重新运行**验证，直到用例全部通过
+   - 输出最终结果
+
+---
+
+## BaseTest 差异对比
+
+四个工程各有自己的 `BaseTest` / `BasePluginTest`，注意包名和预置 Mock 的差异。
+
+**通用发现规则**：不同模块组的 BaseTest 包名遵循相同规律，**实际使用时必须先读取目标工程的 BaseTest 源码**，确认其预置了哪些 MockedStatic。
+
+| 工程 | BaseTest 包名规律 | 查找路径 |
+|--------|--------------|---------------|
+| `<模块组>-common` | `kd.<包路径>.common.BaseTest` | `<模块组>-common/src/test/java/.../BaseTest.java` |
+| `<模块组>-business` | `kd.<包路径>.business.BaseTest` | `<模块组>-business/src/test/java/.../BaseTest.java` |
+| `<模块组>-opplugin` | `kd.<包路径>.opplugin.BaseTest` | `<模块组>-opplugin/src/test/java/.../BaseTest.java` |
+| `<模块组>-formplugin` | `kd.<包路径>.formplugin.BasePluginTest` | `<模块组>-formplugin/src/test/java/.../BasePluginTest.java` |
+
+**mmc-sfc 模块已知预置 Mock（作为参考）**：
+
+| 工程 | BaseTest 包名 | 额外预置 Mock |
+|--------|--------------|---------------|
+| mmc-sfc-common | `kd.mmc.sfc.common.BaseTest` | SaveServiceHelper + EntityMetadataCache |
+| mmc-sfc-business | `kd.mmc.sfc.business.BaseTest` | SaveServiceHelper + IDataModel/IFormView（CommonMockObject）；BillUnitAndQtytHelper 仅声明字段未自动初始化 |
+| mmc-sfc-opplugin | `kd.mmc.sfc.opplugin.BaseTest` | Singleton + BFTrackerServiceHelper + MutexUtils |
+| mmc-sfc-formplugin | `kd.mmc.sfc.formplugin.BasePluginTest` | 表单插件专用参数与 mock（IFormView / IDataModel / AbstractFormPlugin 上下文等），详见 patterns/formplugin.md |
+
+三者（common / business / opplugin）都共同预置了 8 个 MockedStatic：OrgUnitServiceHelper、BillTypeParamHelper、ResManager、SystemParamServiceHelper、QueryServiceHelper、BusinessDataServiceHelper、OperationServiceHelper、BaseDataServiceHelper。其中 common 和 business 额外共享 SaveServiceHelper（opplugin 无此项）。
+
+formplugin 的 BasePluginTest 独立管理，具体预置内容以实际文件为准。
+
+---
+
+## 常用 Mock 清单
+
+以下是苍穹模块单元测试中高频需要 Mock 的静态类：
+
+| 静态类 | 用途 | 常见 Mock 方式 |
+|--------|------|---------------|
+| `QueryServiceHelper` | 数据库查询 | `.when(() -> query(...)).thenReturn(...)` |
+| `BusinessDataServiceHelper` | 业务数据加载 | `.when(() -> loadSingle/load/loadFromCache(...)).thenReturn(...)` |
+| `OperationServiceHelper` | 操作执行 | `.when(() -> executeOperate(...)).thenReturn(opResult)` |
+| `SaveServiceHelper` | 数据保存 | `.when(() -> save/update(...)).thenReturn(...)` |
+| `BaseDataServiceHelper` | 基础资料 | `.when(() -> getBaseDataFromCache(...)).thenReturn(...)` |
+| `OrgUnitServiceHelper` | 组织单元 | 通常直接 mockStatic |
+| `SystemParamServiceHelper` | 系统参数 | `.when(() -> getParameterValue(...)).thenReturn(...)` |
+| `ResManager` | 多语言资源 | `.when(() -> loadKDString(...)).thenAnswer(inv -> inv.getArgument(0))` |
+| `BillTypeParamHelper` | 单据类型参数 | 通常直接 mockStatic |
+| `ProcessPlanHelper` | 工序计划业务 | 按需 Mock 具体方法 |
+| `AttachmentServiceHelper` | 附件服务 | Mock upload/remove/getAttachments |
+| `CacheFactory` | 缓存工厂 | Mock getCommonCacheFactory 链式调用 |
+| `BFTrackerServiceHelper` | BOTP 追踪 | 通常直接 mockStatic |
+| `EntityMetadataCache` | 元数据缓存 | 通常直接 mockStatic（common 工程常用） |
+| `ConvertServiceHelper` | BOTP 转换服务 | Mock push/convert 方法 |
+| `ProcessSettleHelper` | 工序结算（含分布式缓存） | **必须**用 `ProcessSettleMockHelper.mockDistributeSessionlessCache()` 创建，不可直接 mockStatic；ProcessSettleMockHelper 在各工程各自 test 目录下查找，找不到则告知用户添加（详见 2.7 节） |
+| `DB`（kd.bos.db.DB） | 数据库操作 | **必须**先执行 ClassPool defrost 处理再 mockStatic（详见 2.6 节） |
+
+---
+
+## 高频混淆场景
+
+| 场景 | ❌ 错误做法 | ✅ 正确做法 |
+|------|-----------|-----------|
+| 测试 protected 方法 | 改方法可见性为 public | 用 `ReflectHelper.invokeProtectedMethod()` |
+| 测试 private static 方法 | 跳过或改可见性 | 用 `ReflectHelper.invokeStaticMethod()` |
+| 校验器收集错误消息 | 直接调用 validate 不收集 | 匿名子类重写 `addMessage/addErrorMessage` 收集到 List |
+| 构建分录数据 | 手动 new DynamicObject | 用 `DynamicObjectMocker` 链式构造 |
+| Mock 静态方法后不关闭 | 忘记 close | @After 中**必须** close 所有 MockedStatic |
+| ResManager 多语言 | 直接返回空字符串 | thenAnswer 返回第一个参数（保持可读性） |
+| POJO 测试用 Mock | 给纯 POJO 加 MockedStatic | 直接 new 对象，无需任何 Mock |
+| common 工具类 new 内部对象 | 无法 Mock 构造函数 | 用 `Mockito.mockConstruction()` Mock 构造函数 |
+| 断言写法 | `assertTrue(true)` / `assertFalse(false)` 等假断言，或测试方法中根本没有任何 `assert`/`verify` 调用 | 断言被测方法的真实输出或用 `verify()` 校验交互；「提前返回」场景用 `verify(mock, never()).method()` 断言下游调用未被触发 |
+| Mockito 重载方法歧义 | `any()` 无法区分 `method(DynamicObject)` 和 `method(List<Long>)` | 显式指定类型：`any(DynamicObject.class)` |
+| Mockito varargs 参数匹配 | `verify(view).setEnable(eq(true), any(String[].class))` | `verify(view).setEnable(eq(true), anyString())`（varargs 用 `anyString()` 而非 `any(String[].class)`） |
+| `any()` 在非 Object 类型参数上歧义 | `any()` 用于 `Date`/`Set`/`String` 等具体类型参数 | 必须明确类型：`any(Date.class)`、`any(Set.class)`、`anyString()` 等；`any()` 仅在参数类型为 `Object` 且无重载歧义时使用 |
+| Mock 前未确认方法签名 | `anyLong()` 匹配 `String` 参数导致运行时失败 | **编写 mock 前必须读取被测方法的真实签名**，确保 `anyXxx()` 与参数类型一致 |
+| `DynamicObjectCollection` 状态控制 | `new DynamicObjectCollection().add(item)` 后 `isEmpty()/size()` 不可靠（框架类需要 DynamicObjectType 初始化） | 当被测代码以 `isEmpty()/size()` 作为分支条件时，改用 `mock(DynamicObjectCollection.class)` 并显式 stub：`when(entries.isEmpty()).thenReturn(false); when(entries.size()).thenReturn(1)` |
+| 点分隔字段名的 DynamicObject 访问 | `DynamicObjectMocker.add("entryentity.id", 100L)` 后 `obj.getLong("entryentity.id")` 抛 `ORMDesignException` | `DynamicObjectMocker` 创建的是 Simple 类型实体，点分隔的字段名会被解析为嵌套路径导航。**对于 QueryServiceHelper.query() 平展查询结果中含点号字段的 DynamicObject**，必须使用 `mock(DynamicObject.class)` + `when(obj.getLong/getBigDecimal("key")).thenReturn(value)` |
+| Mock DB 类 | 直接 `Mockito.mockStatic(DB.class)` | 必须先执行 ClassPool defrost 处理（详见 2.6 节），否则可能因字节码冻结导致 mock 失败 |
+| Mock ProcessSettleHelper | 直接 `Mockito.mockStatic(ProcessSettleHelper.class)` | 必须用 `ProcessSettleMockHelper.mockDistributeSessionlessCache()`（详见 2.7 节），在当前工程 test 目录下查找该 Helper，找不到则告知用户添加 |
+| 常量/枚举类引用不到 | 用字面值 `"A"` 替代 `StatusEnum.APPROVED` | **禁止字面值替代**，主动告知用户补充常量/枚举类的文件位置或源码 |
+| DynamicObject 空值断言 | `assertNull(obj.getString("field"))` | `getString()`、`getLong()`、`getInt()`、`getBigDecimal()`、`getBoolean()` 在苍穹平台默认配置下不返回 null（即使 `set(key, null)`，平台会转为基本值）：空字符串用 `assertEquals("", obj.getString(...))`、空数值用 `assertEquals(0L, obj.getLong(...))`、空 BigDecimal 用 `assertEquals(BigDecimal.ZERO, obj.getBigDecimal(...))`、布尔用 `assertFalse(obj.getBoolean(...))`。若被测代码对 getter 结果做了 `null` 检查（如 `if (obj.getBigDecimal("qty") != null)`），说明该字段可能开启了「允许为空」，测试用例必须覆盖 null 和非 null 两个分支；无法判断时默认按非 null 处理，但在测试方法中添加注释 `// 假设字段未开启"允许为空"，若实际可为 null 请告知`。`getDate(key)` 是例外，始终可能为 null，需用 `assertNull` 或具体日期值断言 |