kcode-pi 0.1.0

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

@@ -0,0 +1,298 @@
+# 插件生命周期合规性检查表
+
+## 🔴 P0 级问题
+
+### 1. Initialize 方法滥用
+**检查点**:
+- `initialize()` 内是否调用了 `addItemClickListener()`？
+- `initialize()` 内是否操作了 UI 控件？
+
+**风险**: 导致内存泄漏，监听器无法正确释放
+
+**修正方案**:
+```java
+// ❌ 错误写法
+@Override
+public void initialize() {
+    this.getView().addItemClickListener(this);
+}
+
+// ✅ 正确写法
+@Override
+public void registerListener(EventObject e) {
+    this.getView().addItemClickListener(this);
+}
+```
+
+---
+
+### 2. 数据绑定事件修改模型
+**检查点**:
+- `beforeBindData()` 内是否调用了 `setValue()`？
+- `afterBindData()` 内是否调用了 `setValue()`？
+
+**风险**: 破坏数据绑定流程，可能导致数据不一致
+
+**修正方案**:
+```java
+// ❌ 错误写法
+@Override
+public void afterBindData(EventObject e) {
+    this.getModel().setValue("field", value);
+}
+
+// ✅ 正确写法
+@Override
+public void afterCreateNewData(EventObject e) {
+    this.getModel().setValue("field", value);
+}
+```
+
+---
+
+### 3. 校验器字段未声明
+**检查点**:
+- `validate()` 方法使用了字段 X
+- `preparePropertys()` 是否返回了字段 X？
+- 若校验器继承 `AbstractValidator`，`validate()` 中通过 `dataEntities` 访问的字段，是否在校验器自身的 `preparePropertys()` 中声明，或在引用该校验器的操作插件（`AbstractOperationServicePlugIn`）的 `onPreparePropertys()` 中通过 `e.getFieldKeys().add()` 预加载？（两处满足其一即合规）
+- 操作插件的 `onAddValidators()` 引用了哪些校验器？这些校验器所需字段是否已在操作插件的 `onPreparePropertys()` 中覆盖？
+
+**风险**: 校验器无法正确获取字段值，导致校验逻辑基于默认值（null/0/false）运行，校验完全失效且不抛错，极难排查
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 校验器使用了字段，但两处均未预加载
+public class MyValidator extends AbstractValidator {
+    @Override
+    public void validate() {
+        for (ExtendedDataEntity extend : dataEntities) {
+            DynamicObject bill = extend.getDataEntity();
+            // 使用了 entryentity 子表，但操作插件和校验器均未在 preparePropertys 中声明
+            DynamicObjectCollection entries = bill.getDynamicObjectCollection("entryentity");
+        }
+    }
+}
+
+// ✅ 正确写法A - 在校验器自身的 preparePropertys 中声明
+public class MyValidator extends AbstractValidator {
+    @Override
+    public Collection<String> preparePropertys() {
+        List<String> fields = new ArrayList<>();
+        fields.add("entryentity");
+        fields.add("entryentity.xsbillentryid");
+        return fields;
+    }
+}
+
+// ✅ 正确写法B - 在引用该校验器的操作插件 onPreparePropertys 中预加载
+public class MyOperationPlugin extends AbstractOperationServicePlugIn {
+    @Override
+    public void onPreparePropertys(PreparePropertysEventArgs e) {
+        super.onPreparePropertys(e);
+        // 覆盖 MyValidator 所需的字段
+        e.getFieldKeys().add("entryentity");
+        e.getFieldKeys().add("entryentity.xsbillentryid");
+    }
+
+    @Override
+    public void onAddValidators(AddValidatorsEventArgs e) {
+        super.onAddValidators(e);
+        e.addValidator(new MyValidator());
+    }
+}
+```
+
+---
+
+### 4. 闭包捕获 this 导致内存泄漏
+**检查点**:
+- Lambda 表达式或匿名类是否捕获了 `this`？
+- 是否在静态上下文中持有插件引用？
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 捕获 this
+button.addActionListener(e -> this.doSomething());
+
+// ✅ 正确写法 - 使用弱引用或解耦
+button.addActionListener(e -> {
+    // 使用局部变量或弱引用
+});
+```
+
+---
+
+### 5. 操作插件字段未声明（onPreparePropertys）
+**检查点**:
+- 操作插件 `beforeExecuteOperationTransaction` / `afterExecuteOperationTransaction` 中使用了字段 X
+- `onPreparePropertys()` 是否通过 `e.getFieldKeys().add()` 声明了字段 X？
+- 分录字段是否使用 `entryEntity.fieldKey` 格式声明？
+
+**风险**: 未声明的字段在操作执行时不会被加载，读取到 null/默认值，导致业务逻辑静默失败
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 使用了字段但未声明
+@Override
+public void beforeExecuteOperationTransaction(BeforeOperationArgs args) {
+    for (DynamicObject entity : args.getDataEntities()) {
+        String billno = entity.getString("billno"); // billno 未声明，可能为 null
+    }
+}
+
+// ✅ 正确写法 - 先声明再使用
+@Override
+public void onPreparePropertys(PreparePropertysEventArgs e) {
+    super.onPreparePropertys(e);
+    e.getFieldKeys().add("billno");
+    e.getFieldKeys().add("status");
+    e.getFieldKeys().add("entryEntity.field1"); // 分录字段
+}
+```
+
+---
+
+### 6. afterExecuteOperationTransaction 误用 getOperationResult
+**检查点**:
+- `afterExecuteOperationTransaction()` 中是否调用了 `args.getOperationResult()`？
+- `AfterOperationArgs` 没有 `getOperationResult()` 方法，不要与 `BeforeOperationArgs` 混淆
+
+**风险**: 编译失败或运行时异常
+
+**修正方案**:
+```java
+// ❌ 错误写法 - AfterOperationArgs 没有 getOperationResult()
+@Override
+public void afterExecuteOperationTransaction(AfterOperationArgs args) {
+    if (args.getOperationResult().isSuccess()) { // 方法不存在！
+        // ...
+    }
+}
+
+// ✅ 正确写法 - afterExecuteOperationTransaction 仅在操作成功后回调，无需判断结果
+@Override
+public void afterExecuteOperationTransaction(AfterOperationArgs args) {
+    // 此方法仅在操作成功后回调，直接处理业务逻辑
+    for (DynamicObject entity : args.getDataEntities()) {
+        updateRelatedData(entity);
+    }
+}
+```
+
+---
+
+### 7. 表单插件生命周期方法顺序错误
+**检查点**:
+- 是否在 `initialize()` 中设置控件可见性？（应在 `afterBindData()` 中）
+- 是否在 `initialize()` 中注册控件事件？（应在 `registerListener()` 中）
+- 是否在 `afterBindData()` 中修改数据对象？（会覆盖用户修改的值）
+- 是否在 `afterCreateNewData()` 中做了仅编辑模式才需要的逻辑？
+
+**风险**: 控件状态不生效、事件监听失效、数据被意外覆盖
+
+**正确的生命周期顺序**:
+```
+preOpenForm → initialize → registerListener →
+afterCreateNewData（仅新增）/ afterLoadData（仅编辑）→
+afterCopyData（仅复制）→ beforeBindData → afterBindData
+→（运行中）propertyChanged / itemClick / beforeDoOperation / afterDoOperation
+→ beforeClosed → destroy
+```
+
+**各方法职责**:
+| 方法 | 正确用途 | 禁止操作 |
+|------|---------|---------|
+| `initialize` | 初始化插件成员变量 | 注册事件、操作UI控件 |
+| `registerListener` | 注册按钮/F7/Tab监听 | 设置字段值 |
+| `afterCreateNewData` | 设置默认字段值（仅新增） | 操作UI控件 |
+| `afterLoadData` | 编辑模式额外初始化 | 操作UI控件 |
+| `afterBindData` | 控制控件显隐/启用 | 修改数据对象(setValue) |
+
+---
+
+### 8. 工作流插件 super 调用规则混淆
+**检查点**:
+- 实现 `IWorkflowPlugin` 接口的插件是否错误调用了 `super.xxx()`？（接口无需调用 super）
+- 继承 `AbstractWorkflowPlugin` 的插件是否遗漏了 `super.xxx()` 调用？（继承类必须调用 super）
+
+**风险**: 接口实现调用 super 编译失败；继承类遗漏 super 导致框架行为异常
+
+**修正方案**:
+```java
+// ❌ 错误写法 - IWorkflowPlugin 接口不需要 super
+public class MyPlugin implements IWorkflowPlugin {
+    @Override
+    public void notify(AgentExecution execution) {
+        super.notify(execution); // 编译错误！接口没有 super
+    }
+}
+
+// ✅ 正确写法 - 接口直接实现
+public class MyPlugin implements IWorkflowPlugin {
+    @Override
+    public void notify(AgentExecution execution) {
+        // 直接编写业务逻辑
+    }
+}
+
+// ✅ 继承 AbstractWorkflowPlugin 必须调用 super
+public class MyApprovalPlugin extends AbstractWorkflowPlugin {
+    @Override
+    public void afterBindData(EventObject e) {
+        super.afterBindData(e); // 必须调用
+        // 审批页面定制逻辑
+    }
+}
+```
+
+---
+
+### 9. 调度任务插件规范
+**检查点**:
+- 调度任务是否继承 `AbstractTask` 并实现 `Plugin` 接口？
+- `execute` 方法签名是否正确：`execute(RequestContext, Map<String, Object>) throws KDException`？
+- 批量处理时是否每条数据单独 try-catch？
+- 大循环是否反馈进度（`feedbackProgress`）？
+- 长任务是否实现 `StopTask` 接口并在循环中检查 `isStop()`？
+
+**风险**: 单条失败影响全局、用户无法感知任务状态、长任务无法停止
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 无进度反馈、无异常隔离
+public class MyTask extends AbstractTask implements Plugin {
+    @Override
+    public void execute(RequestContext ctx, Map<String, Object> map) throws KDException {
+        DynamicObject[] data = BusinessDataServiceHelper.load(...);
+        for (DynamicObject obj : data) {
+            processData(obj); // 单条失败全部中断
+        }
+    }
+}
+
+// ✅ 正确写法 - 逐条隔离 + 进度反馈 + 可停止
+public class MyTask extends AbstractTask implements Plugin, StopTask {
+    @Override
+    public void execute(RequestContext ctx, Map<String, Object> map) throws KDException {
+        DynamicObject[] data = BusinessDataServiceHelper.load(...);
+        int total = data.length;
+        int success = 0, fail = 0;
+        for (int i = 0; i < total; i++) {
+            try {
+                processData(data[i]);
+                success++;
+            } catch (Exception e) {
+                fail++;
+                log.error("处理失败: id={}", data[i].getPkValue(), e);
+            }
+            feedbackProgress(100 * (i + 1) / total, 
+                String.format("已处理 %d/%d", i + 1, total), null);
+            if (isStop()) {
+                log.info("任务被停止");
+                stop();
+                break;
+            }
+        }
+    }
+}
+```