kcode-pi 0.1.0

package/vendor/kingdee-skills/cosmic-unittest/patterns/common-module.md

@@ -0,0 +1,355 @@
+# Common Module 公共模块测试模式
+
+## 适用范围
+
+`<模块组>-common` 工程中的所有类，按类型分为三种测试模式：
+- **POJO / DTO / Bean 类**：纯数据对象，getter/setter 测试
+- **枚举类（Enum）**：含业务方法的枚举
+- **工具类（Utils）**：含静态方法的工具类
+
+## 测试文件位置
+
+```
+<模块组>-common/src/test/java/kd/<包路径>/common/{subpackage}/XxxTest.java
+```
+
+与被测类保持相同的包路径。
+
+---
+
+## POJO / DTO / Bean 测试模式 {#POJO}
+
+### 适用类型
+
+纯数据对象类，只包含属性字段和 getter/setter 方法。
+如：`InvokeResult`、`ExecuteTaskModel`、`PlanPushTransferInfo`、`DailyPlanBean` 等。
+
+### 基类选择
+
+| 场景 | 基类 |
+|------|------|
+| 纯 POJO（无框架依赖） | 无需基类，或继承 `AbstractJunitNoDependenciesResManagerTest` |
+| 含 Builder 模式 | 同上 |
+
+### 模板结构
+
+```java
+package kd.<包路径>.common.pojo;
+
+import kd.bos.test.ext.annotaions.UnittestCaseInfo;
+import org.junit.Before;
+import org.junit.Test;
+
+import static org.junit.Assert.*;
+
+/**
+ * XxxModel 单元测试
+ * @author 作者
+ * @date YYYY/MM/DD
+ */
+public class XxxModelTest {
+
+    private XxxModel model;
+
+    @Before
+    public void setUp() {
+        model = new XxxModel();
+    }
+
+    @UnittestCaseInfo(
+        author = "<name> <<name>@kingdee.com>",
+        title = "Test get set fieldName",
+        targetClass = "kd.<包路径>.common.pojo.XxxModel",
+        targetMethod = "getsetfieldname",
+        lastUpdateTime = "yyyy-MM-dd HH:mm:ss",
+        lastUpdateAuthor = "<name> <<name>@kingdee.com>",
+        methodSignature = "public String getFieldName() / public void setFieldName(String value)",
+        testPoints = {"Functionality"},
+        description = "Test get set fieldName"
+    )
+    @Test
+    public void testGetSetFieldName() {
+        // step 设置属性
+        String value = "testValue";
+        model.setFieldName(value);
+
+        // assert 验证 getter 返回值
+        assertEquals(value, model.getFieldName());
+    }
+
+    @Test
+    public void testSuccessFactory() {
+        // step 测试静态工厂方法
+        XxxModel result = XxxModel.success("data");
+
+        // assert 验证工厂方法结果
+        assertTrue(result.isSuccess());
+        assertEquals("data", result.getData());
+    }
+
+    @Test
+    public void testToString() {
+        // step 设置属性
+        model.setFieldName("test");
+
+        // assert 验证 toString
+        String str = model.toString();
+        assertTrue(str.contains("fieldName=test"));
+    }
+}
+```
+
+### POJO 测试要点
+
+1. **不需要任何 Mock** — 纯 Java 对象，直接 new 和调用
+2. **每个 getter/setter 一个测试方法**
+3. **静态工厂方法**（如 `success()`/`failure()`）单独测试
+4. **Builder 模式**需测试链式调用和 `build()` 结果
+5. **toString()** 验证包含关键属性
+
+### Builder 模式测试示例
+
+```java
+@Test
+public void testBuilder() {
+    XxxModel model = new XxxModel.Builder()
+        .setField1("value1")
+        .setField2(100L)
+        .build();
+
+    assertEquals("value1", model.getField1());
+    assertEquals(Long.valueOf(100L), model.getField2());
+}
+```
+
+---
+
+## 枚举类测试模式 {#Enum}
+
+### 适用类型
+
+含业务方法的枚举类（不是纯值枚举），如 `PushOperationCodeEnum`、`ExecuteTaskStatusEnum` 等。
+纯值枚举（只有常量值没有方法）一般不需要写测试。
+
+### 基类选择
+
+继承 `AbstractJunitNoDependenciesTest`（不需要 ResManager）
+
+### 模板结构
+
+```java
+package kd.<包路径>.common.enums;
+
+import kd.bos.test.ext.annotaions.UnittestCaseInfo;
+import kd.bos.unittest.AbstractJunitNoDependenciesTest;
+import org.junit.Test;
+
+public class XxxEnumTest extends AbstractJunitNoDependenciesTest {
+
+    @UnittestCaseInfo(
+        author = "<name> <<name>@kingdee.com>",
+        title = "Test getByCode with valid code",
+        targetClass = "kd.<包路径>.common.enums.XxxEnum",
+        targetMethod = "getbycode",
+        lastUpdateTime = "yyyy-MM-dd HH:mm:ss",
+        lastUpdateAuthor = "<name> <<name>@kingdee.com>",
+        methodSignature = "public static XxxEnum getByCode(String code)",
+        testPoints = {"Functionality"},
+        description = "Test getByCode with valid code"
+    )
+    @Test
+    public void testGetByCode_ValidCode() {
+        // step 测试有效的枚举 code
+        XxxEnum result = XxxEnum.getByCode("A");
+
+        // assert
+        assertEquals(XxxEnum.SOME_VALUE, result);
+    }
+
+    @Test
+    public void testGetByCode_InvalidCode() {
+        // step 测试无效的枚举 code
+        XxxEnum result = XxxEnum.getByCode("INVALID");
+
+        // assert 应返回 null
+        assertNull(result);
+    }
+
+    @Test
+    public void testGetByCode_EmptyCode() {
+        // step 测试空字符串
+        String result = XxxEnum.matchMethod("");
+
+        // assert
+        assertEquals("", result);
+    }
+}
+```
+
+### 枚举测试要点
+
+1. 测试**有效值**、**无效值**、**空值**三种场景
+2. 测试枚举的 `getCode()` / `getName()` 等访问器
+3. 测试枚举的匹配/转换方法（如 `matchPushTargetBill()`）
+
+---
+
+## 工具类测试模式 {#Utils}
+
+### 适用类型
+
+`<模块组>-common/src/main/java/kd/<包路径>/common/utils/` 下的工具类，
+如 `BillPushUtil`、`FormPluginUtil`、`ApiInterfaceUtil`、`MetadataUtils` 等。
+
+### 基类选择
+
+| 场景 | 基类 |
+|------|------|
+| 依赖多个常见服务 | 继承 common 包的 `BaseTest`（已封装 10 个常用 Mock） |
+| 依赖少量特定服务 | 继承 `AbstractJunitNoDependenciesResManagerTest`，自行管理 Mock |
+
+### common 包 BaseTest 预置的 Mock
+
+common 包的 `BaseTest`（`kd.<包路径>.common.BaseTest`，实际路径需在 `<模块组>-common/src/test/java/` 下查找）预置了：
+- OrgUnitServiceHelper
+- BillTypeParamHelper
+- ResManager（thenAnswer 返回第一个参数）
+- SystemParamServiceHelper
+- QueryServiceHelper
+- BusinessDataServiceHelper
+- OperationServiceHelper
+- BaseDataServiceHelper
+- SaveServiceHelper
+- **EntityMetadataCache**（比 business 工程多了这个）
+
+### 模板结构
+
+```java
+package kd.<包路径>.common.utils;
+
+import kd.bos.test.ext.annotaions.UnittestCaseInfo;
+import kd.bos.unittest.mock.DynamicObjectMocker;
+import kd.<包路径>.common.BaseTest;  // common 包自带的 BaseTest（实际包路径需查找）
+import org.junit.Test;
+import org.mockito.MockedStatic;
+
+import static org.mockito.ArgumentMatchers.*;
+import static org.mockito.Mockito.*;
+
+public class XxxUtilTest extends BaseTest {
+
+    // 如需额外 Mock（BaseTest 未覆盖的），在此声明
+    // MockedStatic<SpecialHelper> specialHelper;
+
+    @UnittestCaseInfo(
+        author = "<name> <<name>@kingdee.com>",
+        title = "Test method with valid input",
+        targetClass = "kd.<包路径>.common.utils.XxxUtil",
+        targetMethod = "methodname",
+        lastUpdateTime = "yyyy-MM-dd HH:mm:ss",
+        lastUpdateAuthor = "<name> <<name>@kingdee.com>",
+        methodSignature = "public static ReturnType methodName(params)",
+        testPoints = {"Functionality"},
+        description = "Test method with valid input"
+    )
+    @Test
+    public void testMethod_ValidInput() {
+        //step 配置 Mock 返回值（直接使用 BaseTest 的成员变量）
+        queryServiceHelper.when(() -> QueryServiceHelper.query(anyString(), anyString(), any()))
+            .thenReturn(new DynamicObjectMocker().add("id", 1L).getCollection());
+
+        //step 执行被测方法
+        Object result = XxxUtil.targetMethod(param);
+
+        //assert 断言结果
+        assertNotNull(result);
+    }
+
+    @Test
+    public void testMethod_EmptyInput() {
+        //step 测试空输入
+        Object result = XxxUtil.targetMethod(null);
+
+        //assert
+        assertNull(result);
+    }
+}
+```
+
+### 工具类特殊技巧
+
+#### 1. MockedConstruction（Mock 构造函数）
+
+> 此为通用技巧，详见 SKILL.md 2.8 节。此处展示 common 工程的典型用法。
+
+当工具类内部 new 了某个对象时，使用 `Mockito.mockConstruction`：
+
+```java
+@Test
+public void testDoPush() {
+    try (MockedStatic<ConvertServiceHelper> convertServiceHelper = mockStatic(ConvertServiceHelper.class);
+         MockedConstruction<PushArgs> pushArgsMock = Mockito.mockConstruction(PushArgs.class)) {
+
+        //step 执行
+        BillPushUtil.doPush("src", "target", "ruleId", params, rows);
+
+        //assert
+        convertServiceHelper.verify(() -> ConvertServiceHelper.push(any()));
+    }
+}
+```
+
+#### 2. Mock 表单控件
+
+测试 FormPluginUtil 等涉及 UI 控件的方法：
+
+```java
+@Test
+public void testGetSelectedRowData() {
+    // step Mock 表单控件
+    IFormView view = mock(IFormView.class);
+    EntryGrid entryGrid = mock(EntryGrid.class);
+    IDataModel model = mock(IDataModel.class);
+
+    when(view.getControl("entryKey")).thenReturn(entryGrid);
+    when(entryGrid.getSelectRows()).thenReturn(new int[]{0, 1});
+
+    DynamicObjectCollection entries = new DynamicObjectCollection();
+    entries.add(new DynamicObjectMocker().add("id", 1).getObject());
+    entries.add(new DynamicObjectMocker().add("id", 2).getObject());
+    when(model.getEntryCurrentRowIndex("entryKey")).thenReturn(0);
+
+    // step 执行
+    List<DynamicObject> result = FormPluginUtil.getSelectedRowData(model, view, "entryKey");
+
+    // assert
+    assertEquals(2, result.size());
+}
+```
+
+#### 3. try-with-resources 管理方法级 Mock
+
+当某些 MockedStatic 只在单个测试方法中使用时：
+
+```java
+@Test
+public void testMethod() {
+    try (MockedStatic<SpecialHelper> specialHelper = mockStatic(SpecialHelper.class)) {
+        specialHelper.when(() -> SpecialHelper.doSomething(any())).thenReturn(result);
+        // ... 测试逻辑
+    }
+    // 自动关闭，无需 @After
+}
+```
+
+---
+
+## common 工程类型分布参考
+
+| 类型 | 数量 | 是否需要测试 | 测试模式 |
+|------|------|------------|---------|
+| 常量类（Const） | ~21 | 通常不需要 | — |
+| 枚举类（Enum） | ~24 | 含业务方法时需要 | Enum 模式 |
+| POJO/DTO/Bean | ~25 | 需要 | POJO 模式 |
+| 工具类（Utils） | ~19 | 需要 | Utils 模式 |
+| 业务模块类 | ~12 | 需要 | Utils 模式 |

package/vendor/kingdee-skills/cosmic-unittest/patterns/convert-plugin.md

@@ -0,0 +1,130 @@
+# ConvertPlugin 转换插件测试模式
+
+## 适用范围
+
+`<模块组>-opplugin` 工程中的 BOTP 转换插件（下推/反写插件），如：
+- 继承 `AbstractConvertPlugIn` 的类
+- 实现 `afterConvert`、`beforeBuildRowCondition`、`afterBuildDrawFilter` 等方法的类
+
+## 测试文件位置
+
+```
+<模块组>-opplugin/src/test/java/kd/<包路径>/opplugin/convertplugin/XxxConvertPluginTest.java
+```
+
+或
+
+```
+<模块组>-opplugin/src/test/java/kd/<包路径>/opplugin/common/botp/XxxBotpConvertPluginTest.java
+```
+
+## 模板结构
+
+```java
+package kd.<包路径>.opplugin.convertplugin;
+
+import kd.bos.dataentity.entity.DynamicObject;
+import kd.bos.entity.BillEntityType;
+import kd.bos.entity.ExtendedDataEntity;
+import kd.bos.entity.botp.runtime.ConvertOperationResult;
+import kd.bos.form.unittest.DisplayName;
+import kd.bos.test.ext.annotaions.UnittestCaseInfo;
+import kd.bos.unittest.AbstractJunitNoDependenciesResManagerTest;
+import kd.bos.unittest.mock.DynamicObjectMocker;
+import org.junit.After;
+import org.junit.Before;
+import org.junit.Test;
+import org.mockito.MockedStatic;
+
+import static org.mockito.ArgumentMatchers.*;
+import static org.mockito.Mockito.*;
+
+public class XxxConvertPluginTest extends AbstractJunitNoDependenciesResManagerTest {
+
+    MockedStatic<SomeHelper> someHelper;
+
+    @Before
+    public void before() {
+        someHelper = mockStatic(SomeHelper.class);
+    }
+
+    @After
+    public void after() {
+        someHelper.close();
+    }
+
+    // 构建源单和目标单数据
+    private ExtendedDataEntity[] buildSrcData() {
+        DynamicObject srcBill = new DynamicObjectMocker()
+            .add("id", 1L)
+            .add("billno", "SRC-001")
+            .add("entryentity", new DynamicObjectMocker()
+                .add("id", 10L)
+                .add("qty", BigDecimal.TEN)
+                .getCollection())
+            .getObject();
+        return new ExtendedDataEntity[]{new ExtendedDataEntity(srcBill, 0, 0)};
+    }
+
+    private ExtendedDataEntity[] buildDestData() {
+        DynamicObject destBill = new DynamicObjectMocker()
+            .add("id", 2L)
+            .add("entryentity", new DynamicObjectMocker()
+                .add("id", 20L)
+                .add("srcqty", BigDecimal.TEN)
+                .getCollection())
+            .getObject();
+        return new ExtendedDataEntity[]{new ExtendedDataEntity(destBill, 0, 0)};
+    }
+
+    @UnittestCaseInfo(
+        author = "<name> <<name>@kingdee.com>",
+        title = "Test after convert normal",
+        targetClass = "kd.<包路径>.opplugin.convertplugin.XxxConvertPlugin",
+        targetMethod = "afterconvert",
+        lastUpdateTime = "yyyy-MM-dd HH:mm:ss",
+        lastUpdateAuthor = "<name> <<name>@kingdee.com>",
+        methodSignature = "public void afterConvert(AfterConvertEventArgs e)",
+        testPoints = {"Functionality"},
+        description = "Test after convert normal"
+    )
+    @Test
+    @DisplayName("转换后处理：正常场景")
+    public void testAfterConvert_Normal() {
+        //step 构建插件实例
+        XxxConvertPlugin plugin = new XxxConvertPlugin();
+
+        //step 构建转换结果
+        ConvertOperationResult convertResult = mock(ConvertOperationResult.class);
+        // 配置源单和目标单数据...
+
+        //step 执行转换后方法
+        plugin.afterConvert(afterConvertEventArgs);
+
+        //assert 验证目标单字段是否被正确赋值
+        assertEquals(expectedValue, destBill.get("fieldKey"));
+    }
+}
+```
+
+## 关键要点
+
+1. **转换插件测试重点**是验证源单字段到目标单字段的映射逻辑
+2. 通常需要 Mock `BillEntityType`、`ExtendedDataEntitySet` 等转换框架对象
+3. 源单和目标单都用 DynamicObjectMocker 构造
+4. 断言重点：目标单的字段值是否被正确设置
+
+## Mock 转换框架对象示例
+
+```java
+// Mock BillEntityType
+BillEntityType srcEntityType = mock(BillEntityType.class);
+when(srcEntityType.getName()).thenReturn("mmc_outsourcesend");
+
+BillEntityType destEntityType = mock(BillEntityType.class);
+when(destEntityType.getName()).thenReturn("mmc_processsettle");
+
+// Mock ExtendedDataEntitySet
+ExtendedDataEntitySet srcDataEntitySet = mock(ExtendedDataEntitySet.class);
+when(srcDataEntitySet.FindByPK(anyLong())).thenReturn(srcExtendedDataEntity);
+```