kcode-pi 0.1.0

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

@@ -0,0 +1,508 @@
+# 表单插件场景检查表
+
+## 🔴 P0 级问题
+
+### 1. propertyChanged 循环触发
+**检查点**:
+- `propertyChanged` 中是否存在 A 字段改 B、B 字段改 A 的循环联动？
+- 批量 `setValue` 是否未用 `beginInit/endInit` 包裹导致递归触发？
+
+**风险**: 无限递归导致栈溢出或界面卡死
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 循环触发
+@Override
+public void propertyChanged(PropertyChangedArgs e) {
+    String key = e.getProperty().getName();
+    if ("fieldA".equals(key)) {
+        getModel().setValue("fieldB", newValue); // 触发 fieldB 的 propertyChanged
+    }
+    if ("fieldB".equals(key)) {
+        getModel().setValue("fieldA", newValue); // 又触发 fieldA，死循环！
+    }
+}
+
+// ✅ 正确写法 - 使用 beginInit 避免递归
+@Override
+public void propertyChanged(PropertyChangedArgs e) {
+    String key = e.getProperty().getName();
+    if ("fieldA".equals(key)) {
+        getModel().beginInit();
+        try {
+            getModel().setValue("fieldB", newValue);
+            getModel().setValue("fieldC", newValue2);
+        } finally {
+            getModel().endInit();
+        }
+        getView().updateView("fieldB");
+        getView().updateView("fieldC");
+    }
+}
+```
+
+---
+
+### 2. beforeDoOperation 校验失败未 setCancel
+**检查点**:
+- `beforeDoOperation` 中校验不通过时是否调用了 `args.setCancel(true)`？
+- 是否只显示了提示但未取消操作？
+
+**风险**: 校验失败但操作仍然继续执行，数据被错误保存
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 校验失败但未取消操作
+@Override
+public void beforeDoOperation(BeforeDoOperationEventArgs args) {
+    super.beforeDoOperation(args);
+    if (getModel().getValue("requiredField") == null) {
+        getView().showTipNotification("字段不能为空");
+        // 缺少 args.setCancel(true)，操作仍会继续！
+    }
+}
+
+// ✅ 正确写法
+@Override
+public void beforeDoOperation(BeforeDoOperationEventArgs args) {
+    super.beforeDoOperation(args);
+    FormOperate formOperate = (FormOperate) args.getSource();
+    if ("save".equals(formOperate.getOperateKey())) {
+        if (getModel().getValue("requiredField") == null) {
+            args.setCancel(true);
+            getView().showTipNotification("字段不能为空");
+            return;
+        }
+    }
+}
+```
+
+---
+
+### 3. 交互式操作未检查回调标识（死循环）
+**检查点**:
+- 操作插件中抛出 `KDInteractionException` 前是否先检查了交互确认结果？
+- 交互标识（sponsor）是否唯一且固定？
+
+**风险**: 用户确认后再次进入操作，再次抛出交互异常，形成死循环
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 未检查回调，死循环
+@Override
+public void beforeExecuteOperationTransaction(BeforeOperationArgs e) {
+    InteractionContext ctx = new InteractionContext();
+    ctx.setSimpleMessage("确认继续？");
+    throw new KDInteractionException("sponsor", ctx); // 每次都抛，死循环！
+}
+
+// ✅ 正确写法 - 先检查是否为回调
+private static final String INTERACTION_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(INTERACTION_SPONSOR)) {
+        // 已经是回调，根据用户选择处理
+        MessageBoxResult result = MessageBoxResult.valueOf(
+            confirmResult.getResults().get(INTERACTION_SPONSOR));
+        if (result == MessageBoxResult.Yes) {
+            return; // 用户确认，继续执行
+        } else {
+            e.cancel = true;
+            return;
+        }
+    }
+    // 首次进入，抛出交互
+    InteractionContext ctx = new InteractionContext();
+    ctx.setSimpleMessage("确认继续？");
+    throw new KDInteractionException(INTERACTION_SPONSOR, ctx);
+}
+```
+
+---
+
+## 🟠 P1 级问题
+
+### 4. registerListener 未调用 super
+**检查点**:
+- `registerListener` 方法是否调用了 `super.registerListener(e)`？
+- 其他生命周期方法（`afterBindData`、`propertyChanged` 等）是否调用了 super？
+
+**风险**: 框架默认行为被跳过，可能导致其他插件的监听器失效
+
+**修正方案**:
+```java
+// ❌ 错误写法
+@Override
+public void registerListener(EventObject e) {
+    addItemClickListeners("tbmain"); // 缺少 super 调用
+}
+
+// ✅ 正确写法
+@Override
+public void registerListener(EventObject e) {
+    super.registerListener(e);
+    addItemClickListeners("tbmain");
+}
+```
+
+---
+
+### 5. F7 监听未注册
+**检查点**:
+- 使用 `beforeF7Select` / `afterF7Select` 事件但未在 `registerListener` 中注册监听？
+- 插件类是否实现了 `BeforeF7SelectListener` / `AfterF7SelectListener` 接口？
+
+**风险**: F7 事件不触发，过滤条件不生效
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 未注册监听
+public class MyPlugin extends AbstractFormPlugin implements BeforeF7SelectListener {
+    @Override
+    public void beforeF7Select(BeforeF7SelectEvent e) {
+        // 永远不会被调用！
+    }
+}
+
+// ✅ 正确写法 - 在 registerListener 中注册
+public class MyPlugin extends AbstractFormPlugin implements BeforeF7SelectListener {
+    @Override
+    public void registerListener(EventObject e) {
+        super.registerListener(e);
+        BasedataEdit f7 = (BasedataEdit) getControl("fieldName");
+        if (f7 != null) {
+            f7.addBeforeF7SelectListener(this);
+        }
+    }
+
+    @Override
+    public void beforeF7Select(BeforeF7SelectEvent e) {
+        // 正确触发
+    }
+}
+```
+
+---
+
+### 6. 分录字段操作未传 rowIndex
+**检查点**:
+- `propertyChanged` 中操作分录字段时是否通过 `e.getChangeSet()[0].getRowIndex()` 获取行号？
+- `setValue` 分录字段时是否传入了 rowIndex 参数？
+
+**风险**: 修改了错误行的数据，或修改了所有行
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 分录字段未传 rowIndex
+@Override
+public void propertyChanged(PropertyChangedArgs e) {
+    if ("material".equals(e.getProperty().getName())) {
+        DynamicObject material = (DynamicObject) getModel().getValue("material");
+        getModel().setValue("relatedField", material.get("name")); // 缺少 rowIndex！
+    }
+}
+
+// ✅ 正确写法
+@Override
+public void propertyChanged(PropertyChangedArgs e) {
+    if ("material".equals(e.getProperty().getName())) {
+        int rowIndex = e.getChangeSet()[0].getRowIndex();
+        DynamicObject material = (DynamicObject) getModel().getValue("material", rowIndex);
+        if (material != null) {
+            getModel().setValue("relatedField", material.get("name"), rowIndex);
+        }
+    }
+}
+```
+
+---
+
+### 7. closedCallBack 未校验 actionId
+**检查点**:
+- `closedCallBack` 中是否根据 `e.getActionId()` 区分不同弹窗的回调？
+- 是否直接处理 `returnData` 而未判断来源？
+
+**风险**: 多个弹窗的回调混淆，数据被错误处理
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 未区分回调来源
+@Override
+public void closedCallBack(ClosedCallBackEvent e) {
+    Object data = e.getReturnData();
+    getModel().setValue("field", data); // 不知道是哪个弹窗返回的！
+}
+
+// ✅ 正确写法
+@Override
+public void closedCallBack(ClosedCallBackEvent e) {
+    if ("selectCallback".equals(e.getActionId())) {
+        Object data = e.getReturnData();
+        if (data != null) {
+            getModel().setValue("field", data);
+            getView().updateView("field");
+        }
+    }
+}
+```
+
+---
+
+### 8. 字符串比较方式不安全
+**检查点**:
+- 是否使用 `variable.equals("constant")` 而非 `"constant".equals(variable)`？
+- `getItemKey()` / `getOperateKey()` 返回值是否可能为 null？
+
+**风险**: 变量为 null 时抛出 NullPointerException
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 变量在前，可能 NPE
+if (evt.getItemKey().equals("btnSave")) { ... }
+
+// ✅ 正确写法 - 常量在前
+if ("btnSave".equals(evt.getItemKey())) { ... }
+```
+
+---
+
+## 🟡 P2 级问题
+
+### 9. FormShowParameter 参数不可序列化
+**检查点**:
+- `getCustomParams().put()` 传递的值是否可序列化？
+- 是否传递了 DynamicObject 等不可序列化的复杂对象？
+
+**风险**: 序列化失败导致弹窗打开异常
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 传递不可序列化对象
+param.getCustomParams().put("data", dynamicObject);
+
+// ✅ 正确写法 - 只传基本类型或 String
+param.getCustomParams().put("dataId", dynamicObject.getLong("id"));
+param.getCustomParams().put("dataName", dynamicObject.getString("name"));
+```
+
+---
+
+### 10. PageCache 值类型限制
+**检查点**:
+- `getPageCache().put()` 的值是否为 String 类型？
+- 复杂对象是否先序列化为 JSON 再存入？
+
+**风险**: 非 String 类型存入 PageCache 可能导致类型转换异常
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 存入非 String 类型
+getPageCache().put("ids", idList);
+
+// ✅ 正确写法 - 序列化后存入
+getPageCache().put("ids", SerializationUtils.toJsonString(idList));
+// 读取时反序列化
+String idsJson = getPageCache().get("ids");
+List<Long> ids = SerializationUtils.fromJsonString(idsJson, List.class);
+```
+
+---
+
+### 11. 列表 setFilter 未调用 super
+**检查点**:
+- 列表插件 `setFilter` 方法是否调用了 `super.setFilter(e)`？
+
+**风险**: 框架默认过滤逻辑被跳过，可能导致数据权限失效
+
+**修正方案**:
+```java
+// ❌ 错误写法
+@Override
+public void setFilter(SetFilterEvent e) {
+    e.getQFilters().add(new QFilter("status", QCP.equals, "A"));
+    // 缺少 super 调用
+}
+
+// ✅ 正确写法
+@Override
+public void setFilter(SetFilterEvent e) {
+    super.setFilter(e);
+    e.getQFilters().add(new QFilter("status", QCP.equals, "A"));
+}
+```
+
+---
+
+### 12. afterBindData 中 setValue 触发 propertyChanged
+**检查点**:
+- `afterBindData` 中是否直接调用 `getModel().setValue()` 而未使用 `beginInit/endInit` 包裹？
+- 此 setValue 是否会触发 `propertyChanged` 中的联动逻辑导致死循环或数据覆盖？
+
+**风险**: afterBindData 触发 propertyChanged，propertyChanged 中的联动逻辑再次修改数据，导致循环或数据错误
+
+**修正方案**:
+```java
+// ❌ 错误写法 - afterBindData 中直接 setValue
+@Override
+public void afterBindData(EventObject e) {
+    super.afterBindData(e);
+    getModel().setValue("calcField", computeValue()); // 触发 propertyChanged
+}
+
+// ✅ 正确写法 - 使用 beginInit 屏蔽联动
+@Override
+public void afterBindData(EventObject e) {
+    super.afterBindData(e);
+    getModel().beginInit();
+    try {
+        getModel().setValue("calcField", computeValue());
+    } finally {
+        getModel().endInit();
+    }
+    getView().updateView("calcField");
+}
+```
+
+---
+
+### 13. 分录行删除后仍使用原行号
+**检查点**:
+- `afterDeleteRow` 中是否使用了删除前缓存的行号访问分录数据？
+- 删除行后是否重新获取了行数和行号？
+
+**风险**: 删除行后行号偏移，使用旧行号访问到错误数据或数组越界
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 删除行后使用原行号
+@Override
+public void afterDeleteRow(AfterDeleteRowEventArgs e) {
+    super.afterDeleteRow(e);
+    int rowCount = getModel().getEntryRowCount("entryentity");
+    for (int i = 0; i < rowCount; i++) {
+        // 应重新计算而非依赖删除前的缓存行号
+        recalcRow(i);
+    }
+}
+
+// ✅ 正确写法 - 基于当前实际行重新遍历
+@Override
+public void afterDeleteRow(AfterDeleteRowEventArgs e) {
+    super.afterDeleteRow(e);
+    DynamicObjectCollection entries = getModel().getEntryEntity("entryentity");
+    getModel().beginInit();
+    try {
+        for (int i = 0; i < entries.size(); i++) {
+            recalcRow(i);
+        }
+    } finally {
+        getModel().endInit();
+    }
+    getView().updateView("entryentity");
+}
+```
+
+---
+
+### 14. entryRowClick 未校验行号有效性
+**检查点**:
+- `entryRowClick` 事件中是否直接使用行号访问数据而未校验有效性？
+- 行号是否可能为 -1（未选中任何行时）？
+
+**风险**: 行号为 -1 时直接 getValue 导致 IndexOutOfBoundsException
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 未校验行号
+@Override
+public void entryRowClick(RowClickEvent e) {
+    super.entryRowClick(e);
+    int row = e.getRow();
+    Object value = getModel().getValue("material", row); // row 可能为 -1
+}
+
+// ✅ 正确写法
+@Override
+public void entryRowClick(RowClickEvent e) {
+    super.entryRowClick(e);
+    int row = e.getRow();
+    if (row < 0) {
+        return;
+    }
+    Object value = getModel().getValue("material", row);
+}
+```
+
+---
+
+### 15. flexEdit 动态编辑控制遗漏
+**检查点**:
+- 使用 `flexEdit` 控制分录字段可编辑性时，是否在 `afterBindData` 和 `afterCreateNewData` 中都设置了？
+- 新增行时是否遗漏了编辑控制？
+
+**风险**: 新增行的字段编辑状态与预期不一致
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 只在 afterBindData 中设置
+@Override
+public void afterBindData(EventObject e) {
+    super.afterBindData(e);
+    setEntryFieldEditable();
+}
+
+// ✅ 正确写法 - afterBindData 和 afterCreateNewData 都设置
+@Override
+public void afterBindData(EventObject e) {
+    super.afterBindData(e);
+    setEntryFieldEditable();
+}
+
+@Override
+public void afterCreateNewData(EventObject e) {
+    super.afterCreateNewData(e);
+    setEntryFieldEditable();
+}
+
+private void setEntryFieldEditable() {
+    int rowCount = getModel().getEntryRowCount("entryentity");
+    for (int i = 0; i < rowCount; i++) {
+        String status = (String) getModel().getValue("linestatus", i);
+        getView().setEnable("A".equals(status), i, "qty", "price");
+    }
+}
+```
+
+---
+
+### 16. 多页签子页面插件通信错误
+**检查点**:
+- 多页签表单中，子页面插件是否通过 `getView().getParentView()` 获取父页面？
+- 是否在父页面未加载时就尝试访问父页面控件？
+
+**风险**: 父页面未加载完成时获取 parentView 为 null，导致 NPE
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 未判空 parentView
+@Override
+public void afterBindData(EventObject e) {
+    super.afterBindData(e);
+    IFormView parentView = getView().getParentView();
+    Object parentValue = parentView.getModel().getValue("headField"); // 可能 NPE
+}
+
+// ✅ 正确写法
+@Override
+public void afterBindData(EventObject e) {
+    super.afterBindData(e);
+    IFormView parentView = getView().getParentView();
+    if (parentView != null && parentView.getModel() != null) {
+        Object parentValue = parentView.getModel().getValue("headField");
+    }
+}
+```