kcode-pi 0.1.0

package/vendor/kingdee-skills/kingdee-cosmic-reviewer/references/operation-plugin-checklist.md

@@ -0,0 +1,442 @@
+# 操作插件场景检查表
+
+## 🔴 P0 级问题
+
+### 1. onPreparePropertys 未声明使用字段
+**检查点**:
+- 操作插件中 `beginOperationTransaction` / `endOperationTransaction` 等方法使用了实体字段，但 `onPreparePropertys` 未通过 `e.getFieldKeys().add()` 声明？
+- 校验器 `validate` 中使用了字段，但关联的 `preparePropertys` 未返回对应字段？
+
+**风险**: 未声明的字段在操作执行时不会被预加载，运行时值为 null，导致业务逻辑静默失效
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 使用了字段但未声明
+@Override
+public void beginOperationTransaction(BeginOperationTransactionArgs e) {
+    for (DynamicObject obj : e.getDataEntities()) {
+        String status = obj.getString("billstatus"); // 未声明，可能为 null
+    }
+}
+
+// ✅ 正确写法 - 在 onPreparePropertys 中声明
+@Override
+public void onPreparePropertys(PreparePropertysEventArgs e) {
+    super.onPreparePropertys(e);
+    e.getFieldKeys().add("billstatus");
+    e.getFieldKeys().add("entryentity.material");
+    e.getFieldKeys().add("entryentity.qty");
+}
+```
+
+---
+
+### 2. beforeExecuteOperationTransaction 中独立保存
+**检查点**:
+- `beforeExecuteOperationTransaction` 中是否调用了 `SaveServiceHelper.save()` 或 `SaveServiceHelper.update()`？
+- 是否在事务钩子内创建了独立的保存操作？
+
+**风险**: 事务钩子内独立保存会脱离当前事务，导致数据不一致；若主事务回滚，独立保存的数据不会回滚
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 事务钩子内独立保存
+@Override
+public void beforeExecuteOperationTransaction(BeforeOperationArgs e) {
+    for (DynamicObject obj : e.getDataEntities()) {
+        obj.set("amount", calculateAmount(obj));
+        SaveServiceHelper.save(new DynamicObject[]{obj}); // 脱离事务！
+    }
+}
+
+// ✅ 正确写法 - 直接修改数据实体，由框架统一保存
+@Override
+public void beforeExecuteOperationTransaction(BeforeOperationArgs e) {
+    for (DynamicObject obj : e.getDataEntities()) {
+        obj.set("amount", calculateAmount(obj));
+        // 不需要手动保存，框架会在事务内统一处理
+    }
+}
+```
+
+---
+
+### 3. 自定义校验器字段未声明
+**检查点**:
+- 自定义校验器（继承 `AbstractValidator`）的 `validate` 方法中使用了字段，但 `preparePropertys` 未返回？
+- 关联的操作插件 `onPreparePropertys` 是否也声明了校验器需要的字段？
+
+**风险**: 校验器拿到的字段值为默认值（null/0），校验逻辑基于错误数据静默通过
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 校验器未声明字段
+public class MyValidator extends AbstractValidator {
+    @Override
+    public void validate() {
+        for (ExtendedDataEntity entity : getDataEntities()) {
+            BigDecimal qty = entity.getDataEntity().getBigDecimal("qty"); // 未声明
+        }
+    }
+}
+
+// ✅ 正确写法
+public class MyValidator extends AbstractValidator {
+    @Override
+    public Set<String> preparePropertys() {
+        Set<String> fields = super.preparePropertys();
+        if (fields == null) {
+            fields = new HashSet<>();
+        }
+        fields.add("qty");
+        fields.add("entryentity.material");
+        return fields;
+    }
+
+    @Override
+    public void validate() {
+        for (ExtendedDataEntity entity : getDataEntities()) {
+            BigDecimal qty = entity.getDataEntity().getBigDecimal("qty");
+            if (qty == null || qty.compareTo(BigDecimal.ZERO) <= 0) {
+                addErrorMessage(entity, "数量必须大于零");
+            }
+        }
+    }
+}
+```
+
+---
+
+### 4. 交互式操作死循环（KDInteractionException）
+**检查点**:
+- 抛出 `KDInteractionException` 前是否先检查了交互确认结果（`InteractionConfirmResult`）？
+- 交互标识（sponsor）是否唯一且固定？
+
+**风险**: 用户确认后再次进入操作，再次抛出交互异常，形成死循环
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 未检查回调，死循环
+@Override
+public void beforeExecuteOperationTransaction(BeforeOperationArgs e) {
+    throw new KDInteractionException("sponsor", ctx); // 每次都抛！
+}
+
+// ✅ 正确写法 - 先检查是否为回调
+private static final String SPONSOR = "com.xxx.MyPlugin";
+
+@Override
+public void beforeExecuteOperationTransaction(BeforeOperationArgs e) {
+    String confirmStr = this.getOption().getVariableValue(
+        OperateOptionConst.INTERACTIONCONFIRMRESULT, "");
+    InteractionConfirmResult confirmResult =
+        InteractionConfirmResult.fromJsonString(confirmStr);
+    if (confirmResult.getResults().containsKey(SPONSOR)) {
+        MessageBoxResult result = MessageBoxResult.valueOf(
+            confirmResult.getResults().get(SPONSOR));
+        if (result == MessageBoxResult.Yes) {
+            return; // 用户已确认，继续执行
+        } else {
+            e.cancel = true;
+            return;
+        }
+    }
+    // 首次进入，抛出交互
+    InteractionContext ctx = new InteractionContext();
+    ctx.setSimpleMessage("确认继续？");
+    throw new KDInteractionException(SPONSOR, ctx);
+}
+```
+
+---
+
+## 🟠 P1 级问题
+
+### 5. OperationResult 未检查即使用
+**检查点**:
+- 调用 `OperationServiceHelper.executeOperate()` 后是否检查了 `OperationResult.isSuccess()`？
+- 操作失败时是否有错误处理逻辑？
+
+**风险**: 操作失败但代码继续执行后续逻辑，导致数据不一致
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 未检查操作结果
+OperationServiceHelper.executeOperate("submit", "demo_bill", ids, option);
+// 直接执行后续逻辑...
+
+// ✅ 正确写法
+OperationResult result = OperationServiceHelper.executeOperate(
+    "submit", "demo_bill", ids, option);
+if (!result.isSuccess()) {
+    String errorMsg = result.getAllErrorInfo();
+    logger.error("提交操作失败: {}", errorMsg);
+    throw new KDException(errorMsg);
+}
+Object[] successIds = result.getSuccessPkIds().toArray();
+```
+
+---
+
+### 6. 操作错误提示级别不当
+**检查点**:
+- 校验器中使用 `addErrorMessage` 时是否区分了错误级别（Error/Warning）？
+- Warning 级别的提示是否允许用户忽略继续？
+
+**风险**: 所有问题都用 Error 级别会阻断操作；都用 Warning 级别则无法阻止严重问题
+
+**修正方案**:
+```java
+// ✅ 正确写法 - 区分错误级别
+@Override
+public void validate() {
+    for (ExtendedDataEntity entity : getDataEntities()) {
+        BigDecimal qty = entity.getDataEntity().getBigDecimal("qty");
+        if (qty == null || qty.compareTo(BigDecimal.ZERO) <= 0) {
+            // Error 级别 - 阻断操作
+            addErrorMessage(entity, "数量必须大于零");
+        }
+        if (qty != null && qty.compareTo(new BigDecimal("10000")) > 0) {
+            // Warning 级别 - 允许用户忽略
+            addMessage(entity, "数量超过10000，请确认是否正确",
+                ErrorLevel.Warning);
+        }
+    }
+}
+```
+
+---
+
+### 7. afterExecuteOperationTransaction 误用 getOperationResult
+**检查点**:
+- `afterExecuteOperationTransaction` 的参数类型是 `AfterOperationArgs`，是否错误调用了 `getOperationResult()`？
+
+**风险**: `AfterOperationArgs` 没有 `getOperationResult()` 方法，编译通过但运行时报错
+
+**修正方案**:
+```java
+// ❌ 错误写法 - AfterOperationArgs 无此方法
+@Override
+public void afterExecuteOperationTransaction(AfterOperationArgs e) {
+    e.getOperationResult(); // 方法不存在！
+}
+
+// ✅ 正确写法 - 使用 AfterOperationArgs 提供的方法
+@Override
+public void afterExecuteOperationTransaction(AfterOperationArgs e) {
+    DynamicObject[] entities = e.getDataEntities();
+    for (DynamicObject entity : entities) {
+        // 直接处理数据实体
+    }
+}
+```
+
+---
+
+### 8. 操作事件时序错误
+**检查点**:
+- 数据修改是否放在了正确的事件中？
+- `endOperationTransaction` 中是否执行了应在 `beginOperationTransaction` 中完成的逻辑？
+
+**风险**: 事件时序错误导致数据修改不在事务内，或修改被后续逻辑覆盖
+
+**事件时序说明**:
+```
+onPreparePropertys → onAddValidators → validate
+→ beforeExecuteOperationTransaction（事务开始前，可取消操作）
+→ beginOperationTransaction（事务内，修改数据实体）
+→ endOperationTransaction（事务内，后置处理如写日志）
+→ afterExecuteOperationTransaction（事务提交后，不可回滚）
+→ rollbackOperation（事务回滚时触发）
+```
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 在事务提交后修改数据
+@Override
+public void afterExecuteOperationTransaction(AfterOperationArgs e) {
+    for (DynamicObject obj : e.getDataEntities()) {
+        obj.set("status", "C"); // 事务已提交，修改不会被保存！
+    }
+}
+
+// ✅ 正确写法 - 在事务内修改数据
+@Override
+public void beginOperationTransaction(BeginOperationTransactionArgs e) {
+    for (DynamicObject obj : e.getDataEntities()) {
+        obj.set("status", "C"); // 事务内修改，会被统一提交
+    }
+}
+```
+
+---
+
+### 9. 后台调用操作未设置 IGNOREINTERACTION
+**检查点**:
+- 后台代码（非表单触发）调用 `OperationServiceHelper.executeOperate()` 时，操作插件可能抛出 `KDInteractionException`，是否设置了 `IGNOREINTERACTION`？
+
+**风险**: 后台无法弹出交互对话框，操作会失败且不重试
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 后台调用未忽略交互
+OperateOption option = OperateOption.create();
+OperationServiceHelper.executeOperate("submit", "demo_bill", ids, option);
+
+// ✅ 正确写法 - 后台调用忽略交互
+OperateOption option = OperateOption.create();
+option.setVariableValue(OperateOptionConst.IGNOREINTERACTION, String.valueOf(true));
+option.setVariableValue(OperateOptionConst.IGNOREWARN, String.valueOf(true));
+OperationServiceHelper.executeOperate("submit", "demo_bill", ids, option);
+```
+
+---
+
+## 🟡 P2 级问题
+
+### 10. 操作自定义参数命名冲突
+**检查点**:
+- `OperateOption.setVariableValue()` 的 key 是否使用了过于简单的名称（如 "flag"、"type"）？
+
+**风险**: 与其他插件或框架内置参数冲突，导致参数被覆盖
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 参数名过于简单
+option.setVariableValue("flag", "true");
+
+// ✅ 正确写法 - 带业务域前缀
+option.setVariableValue("scmc_ccm_skipValidation", "true");
+```
+
+---
+
+### 11. 操作内置服务与操作插件混淆
+**检查点**:
+- 通用性强的操作逻辑是否仍写在操作插件中而非操作内置服务？
+- 操作内置服务（`AbstractOpBizRuleAction`）是否正确使用了 `getBizRule()` 获取配置参数？
+
+**风险**: 通用逻辑写在操作插件中无法复用，每个操作都需要重复编写
+
+**建议**: 将通用操作逻辑（如写日志、更新状态）抽象为操作内置服务，通过配置绑定到多个操作上复用
+
+---
+
+### 12. endOperationTransaction 中触发其他操作
+**检查点**:
+- `endOperationTransaction` 中是否调用了 `OperationServiceHelper.executeOperate()` 触发另一个操作？
+- 被触发的操作是否会再次触发当前操作形成递归？
+
+**风险**: 操作链形成循环调用，事务嵌套过深导致死锁或栈溢出
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 事务内触发其他操作
+@Override
+public void endOperationTransaction(EndOperationTransactionArgs e) {
+    for (DynamicObject obj : e.getDataEntities()) {
+        Object[] ids = new Object[]{obj.getLong("id")};
+        // 事务内触发新操作，可能导致事务嵌套
+        OperationServiceHelper.executeOperate("submit", "demo_bill", ids);
+    }
+}
+
+// ✅ 正确写法 - 使用 afterExecuteOperationTransaction（事务提交后）
+@Override
+public void afterExecuteOperationTransaction(AfterOperationArgs e) {
+    for (DynamicObject obj : e.getDataEntities()) {
+        Object[] ids = new Object[]{obj.getLong("id")};
+        OperateOption option = OperateOption.create();
+        option.setVariableValue(OperateOptionConst.IGNOREINTERACTION, "true");
+        OperationServiceHelper.executeOperate("submit", "demo_bill", ids, option);
+    }
+}
+```
+
+---
+
+### 13. 批量操作数据量过大未分批
+**检查点**:
+- 操作插件处理的数据量是否可能超过 1000 条？
+- 是否在操作插件内部做了分批处理？
+
+**风险**: 单次操作数据量过大，事务过长导致数据库锁等待超时
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 一次性处理所有数据
+@Override
+public void beginOperationTransaction(BeginOperationTransactionArgs e) {
+    for (DynamicObject obj : e.getDataEntities()) {
+        // 如果有 10000 条数据，全在一个事务内处理
+        processData(obj);
+    }
+}
+
+// ✅ 正确写法 - 操作层面分批（调用方控制）
+// 在调用方分批提交
+int batchSize = 500;
+List<Object> allIds = getAllIds();
+for (int i = 0; i < allIds.size(); i += batchSize) {
+    List<Object> batchIds = allIds.subList(i, Math.min(i + batchSize, allIds.size()));
+    OperationServiceHelper.executeOperate("save", entityName,
+        batchIds.toArray());
+}
+```
+
+---
+
+### 14. rollbackOperation 中执行数据库写操作
+**检查点**:
+- `rollbackOperation` 回调中是否执行了 `SaveServiceHelper.save()` 或其他写数据库操作？
+- 回滚处理中是否尝试记录日志到数据库？
+
+**风险**: 事务回滚后再执行写操作可能被一起回滚，或导致新的异常覆盖原始异常
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 回滚中写数据库
+@Override
+public void rollbackOperation(RollbackOperationArgs e) {
+    DynamicObject log = new DynamicObject();
+    log.set("message", "操作失败: " + e.getException().getMessage());
+    SaveServiceHelper.save(new DynamicObject[]{log}); // 可能也被回滚！
+}
+
+// ✅ 正确写法 - 回滚中只记录内存日志
+@Override
+public void rollbackOperation(RollbackOperationArgs e) {
+    logger.error("操作回滚，原因: {}", e.getException().getMessage(), e.getException());
+    // 如果需要持久化日志，使用异步方式在事务外执行
+}
+```
+
+---
+
+### 15. 多个操作插件执行顺序依赖
+**检查点**:
+- 同一操作绑定了多个操作插件时，是否存在执行顺序依赖？
+- 插件之间是否通过 `OperateOption` 传递状态数据？
+
+**风险**: 插件执行顺序不确定，依赖特定顺序的逻辑可能在不同环境下表现不一致
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 插件A设置标记，插件B依赖该标记
+// PluginA:
+@Override
+public void beginOperationTransaction(BeginOperationTransactionArgs e) {
+    this.getOption().setVariableValue("pluginA_done", "true");
+}
+// PluginB:
+@Override
+public void beginOperationTransaction(BeginOperationTransactionArgs e) {
+    String flag = this.getOption().getVariableValue("pluginA_done", "");
+    if (!"true".equals(flag)) {
+        return; // 假设 A 先执行，但顺序不保证！
+    }
+}
+
+// ✅ 正确写法 - 合并为一个插件，或使用操作链（前置操作 → 后置操作）
+// 将有依赖关系的逻辑放在同一个插件中，通过方法拆分保持清晰
+```

package/vendor/kingdee-skills/kingdee-cosmic-reviewer/references/test-mock-checklist.md

@@ -0,0 +1,120 @@
+# 单元测试 Mock 策略检查表
+
+## 🔴 P0 级问题
+
+### 1. 静态方法 Mock 未隔离
+**检查点**:
+- 是否使用 `MockedStatic` 但未用 try-with-resources？
+- 静态 Mock 是否正确关闭？
+
+**风险**: 测试污染，Mock 泄漏到其他测试
+
+**修正方案**:
+```java
+// ❌ 错误写法 - Mock 未隔离
+MockedStatic<BusinessDataServiceHelper> mock = mockStatic(BusinessDataServiceHelper.class);
+mock.when(() -> BusinessDataServiceHelper.loadSingle(...)).thenReturn(obj);
+// mock 未关闭！
+
+// ✅ 正确写法 - try-with-resources
+try (MockedStatic<BusinessDataServiceHelper> mock = mockStatic(BusinessDataServiceHelper.class)) {
+    mock.when(() -> BusinessDataServiceHelper.loadSingle(...)).thenReturn(obj);
+    // 测试代码
+}
+```
+
+---
+
+### 2. 可变参数重载匹配错误
+**检查点**:
+- `any()` 是否未强转？
+- `eq()` 匹配是否正确？
+
+**风险**: Mock 不生效，测试失败
+
+**修正方案**:
+```java
+// ❌ 错误写法
+when(service.method(any())).thenReturn(result); // any() 可能匹配错误
+
+// ✅ 正确写法 - 明确类型
+when(service.method(any(String.class))).thenReturn(result);
+when(service.method(any(Long.class))).thenReturn(result);
+when(service.method(eq("specific"))).thenReturn(result);
+```
+
+---
+
+## 🟠 P1 级问题
+
+### 3. 测试数据未清理
+**检查点**:
+- 测试是否创建了数据但未清理？
+- 是否使用 `@BeforeEach`/`@AfterEach` 管理数据？
+
+**修正方案**:
+```java
+// ✅ 使用生命周期管理
+@AfterEach
+public void cleanup() {
+    // 清理测试数据
+    TestDataServiceHelper.deleteTestData(billIds);
+}
+```
+
+---
+
+### 4. Mock 返回值不一致
+**检查点**:
+- Mock 返回值是否符合业务逻辑？
+- 是否 Mock 了所有必要的方法？
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 返回 null
+when(obj.getString("field")).thenReturn(null);
+
+// ✅ 正确写法 - 返回合理值
+when(obj.getString("field")).thenReturn("expectedValue");
+when(obj.getBigDecimal("amount")).thenReturn(BigDecimal.valueOf(100));
+```
+
+---
+
+## 🟡 P2 级问题
+
+### 5. 测试命名不规范
+**检查点**:
+- 测试方法名是否清晰描述测试场景？
+
+**修正方案**:
+```java
+// ❌ 错误写法
+@Test
+public void test1() { }
+
+// ✅ 正确写法
+@Test
+public void shouldReturnErrorWhenAmountIsNegative() { }
+```
+
+---
+
+### 6. 断言不充分
+**检查点**:
+- 是否只验证了返回值，未验证副作用？
+
+**修正方案**:
+```java
+// ✅ 完整断言
+@Test
+public void shouldSaveDataCorrectly() {
+    // when
+    service.save(data);
+    
+    // then
+    verify(repository).save(data);
+    assertThat(data.getId()).isNotNull();
+    assertThat(data.getCreateTime()).isNotNull();
+}
+```