kcode-pi 0.1.0

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

@@ -0,0 +1,285 @@
+# 苍穹平台 API 使用规范检查表
+
+## 🔴 P0 级问题
+
+### 1. DispatchServiceHelper 调用规范
+**检查点**:
+- 跨云跨应用调用是否通过 `DispatchServiceHelper.invokeService()` 调用？
+- 是否直接依赖其他应用的 jar 包调用方法？
+- 服务工厂路由规则是否正确？（`{isv}.{cloudId}.{appId}.ServiceFactory`）
+- 调用结果是否做了异常处理？
+
+**风险**: 直接依赖 jar 包会导致版本冲突；路由错误导致服务找不到
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 直接依赖其他应用 jar 包
+OtherAppService service = new OtherAppService();
+service.doSomething();
+
+// ✅ 正确写法 - 微服务调用
+try {
+    Object result = DispatchServiceHelper.invokeService(
+        "isv.ti.bo",       // Factory 类限定前缀
+        "appId",           // 应用 Id
+        "xxxService",      // 注册的服务名称
+        "methodName",      // 调用方法
+        new Object[]{...}  // 入参
+    );
+} catch (Exception e) {
+    logger.error("微服务调用失败", e);
+    throw new KDBizException("服务调用失败: " + e.getMessage());
+}
+```
+
+---
+
+### 2. TX 事务 API 使用规范
+**检查点**:
+- `TX.required()` / `TX.requiresNew()` 是否使用了 try-with-resources？
+- catch 块中是否调用了 `h.markRollback()`？
+- 事务内是否包含了外部 HTTP 调用或 MQ 发送？
+- 事务类型选择是否合理？
+
+**风险**: 事务未正确管理导致数据不一致
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 未 markRollback
+try (TXHandle h = TX.required("save")) {
+    try {
+        doSomething();
+    } catch (Exception e) {
+        logger.error("失败", e);
+        // 缺少 h.markRollback()!
+    }
+}
+
+// ✅ 正确写法
+try (TXHandle h = TX.required("save")) {
+    try {
+        doSomething();
+    } catch (Throwable e) {
+        h.markRollback();
+        throw e;
+    }
+}
+```
+
+---
+
+### 3. QFilter 构造安全
+**检查点**:
+- `QFilter` 条件参数是否来自用户输入？是否存在注入风险？
+- 多值匹配是否使用了 `QCP.in` 而非 `QCP.equals`？
+- 空值判断是否使用了 `QCP.is_null` 而非 `QCP.equals` null？
+- 日期范围是否使用了 `QCP.large_equals` 和 `QCP.less_equals`？
+
+**风险**: 查询逻辑错误，获取到错误数据
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 操作符使用错误
+new QFilter("status", QCP.equals, Arrays.asList("A", "B")); // 应用 in
+new QFilter("name", QCP.equals, null); // 应用 is_null
+
+// ✅ 正确写法
+new QFilter("status", QCP.in, new String[]{"A", "B"});
+new QFilter("name", QCP.is_null, null);
+new QFilter("bizdate", QCP.large_equals, startDate)
+    .and(new QFilter("bizdate", QCP.less_equals, endDate));
+```
+
+---
+
+## 🟠 P1 级问题
+
+### 4. setValue/getValue 使用规范
+**检查点**:
+- 分录字段 `setValue` 是否传入了 `rowIndex`？
+- 分录字段 `getValue` 是否传入了 `rowIndex`？
+- F7 基础资料字段赋值是否只传了 Long id？
+- `setValue` 后需要刷新界面时是否调用了 `updateView`？
+
+**风险**: 修改错误行数据、F7 赋值报错
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 分录字段未传 rowIndex
+getModel().setValue("entryField", value); // 不知道修改哪一行!
+
+// ✅ 正确写法
+int rowIndex = e.getChangeSet()[0].getRowIndex();
+getModel().setValue("entryField", value, rowIndex);
+
+// ❌ 错误写法 - F7 字段传 DynamicObject
+getModel().setValue("org", orgDynamicObject); // 报错!
+
+// ✅ 正确写法 - F7 字段只传 id
+getModel().setValue("org", orgDynamicObject.getLong("id"));
+```
+
+---
+
+### 5. setValueFast 适用场景
+**检查点**:
+- 大数据包（分录 > 100 行）批量赋值是否仍使用 `model.setValue`？
+- 应在大数据包场景使用 `property.setValueFast` 提升性能
+
+**风险**: 大量 `setValue` 触发大量 `propertyChanged`，界面严重卡顿
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 大数据包用 setValue
+for (int i = 0; i < 500; i++) {
+    getModel().setValue("field1", value1, i); // 每次触发 propertyChanged
+}
+
+// ✅ 正确写法 - 使用 setValueFast
+DynamicObjectCollection entries = getModel().getEntryEntity("entryEntity");
+for (DynamicObject entry : entries) {
+    for (DynamicProperty prop : properties) {
+        prop.setValueFast(entry, newValue);
+    }
+}
+getView().updateView("entryEntity"); // 循环外统一刷新
+```
+
+---
+
+### 6. loadSingle vs queryOne 选择
+**检查点**:
+- 只读场景是否错误使用了 `loadSingle`？（应使用 `queryOne`）
+- 需要保存回库的场景是否使用了 `queryOne`？（应使用 `loadSingle`）
+- 判断存在是否使用了 `loadSingle`？（应使用 `exists` 或 `queryOne` 只查id）
+- 高频读取基础资料是否使用了 `loadSingleFromCache`？
+
+**数据访问方法选择速查**:
+| 场景 | 推荐方法 |
+|------|---------|
+| 判断是否存在 | `QueryServiceHelper.exists()` |
+| 读取少量字段（只读） | `QueryServiceHelper.queryOne()` |
+| 读取完整数据包（需保存） | `BusinessDataServiceHelper.loadSingle()` |
+| 大数据量流式处理 | `QueryServiceHelper.queryDataSet()` |
+| 高频读取基础资料 | `BusinessDataServiceHelper.loadSingleFromCache()` |
+| 批量加载 | `BusinessDataServiceHelper.load()` |
+
+---
+
+### 7. PageCache 使用限制
+**检查点**:
+- `getPageCache().put()` 的值是否为 String 类型？
+- 复杂对象是否先序列化为 JSON 再存入？
+- 是否在 PageCache 中存储了大量数据（超过 1MB）？
+
+**风险**: 非 String 类型存入 PageCache 导致类型转换异常
+
+**修正方案**:
+```java
+// ❌ 错误写法
+getPageCache().put("ids", idList); // 类型不对
+
+// ✅ 正确写法
+getPageCache().put("ids", SerializationUtils.toJsonString(idList));
+String idsJson = getPageCache().get("ids");
+List<Long> ids = SerializationUtils.fromJsonString(idsJson, List.class);
+```
+
+---
+
+### 8. FormShowParameter 参数传递
+**检查点**:
+- `getCustomParams().put()` 传递的值是否可序列化？
+- 是否传递了 DynamicObject 等不可序列化的复杂对象？
+
+**风险**: 序列化失败导致弹窗打开异常
+
+**修正方案**:
+```java
+// ❌ 错误写法
+param.getCustomParams().put("data", dynamicObject); // 不可序列化
+
+// ✅ 正确写法
+param.getCustomParams().put("dataId", dynamicObject.getLong("id"));
+param.getCustomParams().put("dataName", dynamicObject.getString("name"));
+```
+
+---
+
+### 9. 日志框架使用
+**检查点**:
+- 是否使用了 `kd.bos.logging.Log` 而非其他日志框架？
+- 是否使用了 `System.out.println`？
+- debug 日志是否用 `isDebugEnabled()` 包裹？
+- 是否用 `SerializationUtils.toJsonString()` 打印大对象？（极耗 CPU）
+- error 日志是否传入了异常对象？
+
+**风险**: 日志不规范导致排查困难，性能问题
+
+**修正方案**:
+```java
+// ✅ 正确用法
+private static final Log logger = LogFactory.getLog(MyClass.class);
+
+if (logger.isDebugEnabled()) {
+    logger.debug("详细信息: {}", detail);
+}
+logger.error("操作失败", e); // 必须传入异常对象
+```
+
+---
+
+## 🟡 P2 级问题
+
+### 10. queryDataSet algoKey 无意义
+**检查点**:
+- `QueryServiceHelper.queryDataSet()` 的第一个参数 algoKey 是否使用了有意义的标识？
+
+**修正方案**:
+```java
+// ❌ 错误写法
+QueryServiceHelper.queryDataSet("q", "entity", "id", null);
+
+// ✅ 正确写法
+QueryServiceHelper.queryDataSet("scmc.ccm.queryMaterial", "bd_material", "id,name", filters);
+```
+
+---
+
+### 11. 操作自定义参数命名
+**检查点**:
+- `OperateOption.setVariableValue()` 的 key 是否使用了业务域前缀？
+
+**修正方案**:
+```java
+// ❌ 错误写法
+option.setVariableValue("flag", "true"); // 可能冲突
+
+// ✅ 正确写法
+option.setVariableValue("scmc_ccm_skipValidation", "true");
+```
+
+---
+
+### 12. 异常类型使用规范
+**检查点**:
+- 是否统一使用 `KDException` / `KDBizException`？
+- 有原始异常时是否作为 cause 传入？
+- UI 层捕获异常后是否给出了业务语义提示？
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 原始异常丢失
+try {
+    doSomething();
+} catch (Exception e) {
+    throw new KDException(new ErrorCode("xxx", "操作失败")); // 丢失原始异常
+}
+
+// ✅ 正确写法
+try {
+    doSomething();
+} catch (Exception e) {
+    throw new KDException(new ErrorCode("xxx", e.getMessage()), e);
+}
+```

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

@@ -0,0 +1,261 @@
+# 数据访问与事务检查表
+
+## 🔴 P0 级问题
+
+### 1. 事务内 DataSet 在事务外使用
+**检查点**:
+- 在 `TX.required` / `TX.requiresNew` 事务块内查询的 DataSet，是否在事务块外部使用？
+
+**风险**: 事务结束后 DataSet 关联的数据库连接已释放，继续使用会抛异常或返回错误数据
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 事务内查询的 DataSet 在事务外使用
+DataSet ds;
+try (TXHandle h = TX.required("query")) {
+    try {
+        ds = QueryServiceHelper.queryDataSet("q", "entity", "id,name", null);
+    } catch (Throwable e) {
+        h.markRollback();
+        throw e;
+    }
+}
+// ds 在事务外使用，连接已释放！
+for (Row row : ds) { ... }
+
+// ✅ 正确写法 - 在事务内完成数据处理
+List<String> names = new ArrayList<>();
+try (TXHandle h = TX.required("query")) {
+    try {
+        try (DataSet ds = QueryServiceHelper.queryDataSet("q", "entity", "id,name", null)) {
+            for (Row row : ds) {
+                names.add(row.getString("name"));
+            }
+        }
+    } catch (Throwable e) {
+        h.markRollback();
+        throw e;
+    }
+}
+```
+
+---
+
+### 2. 跨库写操作
+**检查点**:
+- 一个事务内是否写了两个或以上的物理库？
+- 是否在同一事务中操作了不同微服务节点的数据？
+
+**风险**: 平台禁止跨库写，DB 检测到会直接抛异常；跨节点事务同样被禁止
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 一个事务内写两个库
+try (TXHandle h = TX.required("crossDb")) {
+    try {
+        SaveServiceHelper.save(entityA); // 库A
+        SaveServiceHelper.save(entityB); // 库B - 跨库写！
+    } catch (Throwable e) {
+        h.markRollback();
+        throw e;
+    }
+}
+
+// ✅ 正确写法 - 使用 MQ 异步解耦
+try (TXHandle h = TX.required("saveA")) {
+    try {
+        SaveServiceHelper.save(entityA);
+        // 发送 MQ 消息，由消费者在另一个事务中写库B
+        publisher.publish(message);
+    } catch (Throwable e) {
+        h.markRollback();
+        throw e;
+    }
+}
+```
+
+---
+
+### 3. 事务中未 markRollback
+**检查点**:
+- `TX.required` / `TX.requiresNew` 事务块的 catch 中是否调用了 `h.markRollback()`？
+- TXHandle 是否使用了 try-with-resources？
+
+**风险**: 业务异常未标记回滚，事务可能被错误提交，导致数据不一致
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 未标记回滚
+try (TXHandle h = TX.required("save")) {
+    try {
+        doSomething();
+    } catch (Exception e) {
+        logger.error("失败", e);
+        // 缺少 h.markRollback()，事务可能被提交！
+    }
+}
+
+// ✅ 正确写法
+try (TXHandle h = TX.required("save")) {
+    try {
+        doSomething();
+    } catch (Throwable e) {
+        h.markRollback();
+        throw e;
+    }
+}
+```
+
+---
+
+## 🟠 P1 级问题
+
+### 4. QFilter 条件缺失导致全表扫描
+**检查点**:
+- `QueryServiceHelper.queryDataSet()` / `BusinessDataServiceHelper.load()` 的 filters 参数是否为 null 或空数组？
+- 查询是否缺少组织、日期等基本过滤条件？
+
+**风险**: 无过滤条件查询导致全表扫描，大数据量时严重影响性能
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 无过滤条件
+DynamicObject[] all = BusinessDataServiceHelper.load("entity", "id,name", null);
+
+// ✅ 正确写法 - 添加过滤条件
+QFilter orgFilter = new QFilter("org", QCP.equals, orgId);
+QFilter statusFilter = new QFilter("billstatus", QCP.equals, "C");
+DynamicObject[] data = BusinessDataServiceHelper.load(
+    "entity", "id,name",
+    new QFilter[]{orgFilter.and(statusFilter)});
+```
+
+---
+
+### 5. QFilter 字段层级过深
+**检查点**:
+- QFilter 或 selectFields 中的字段层级是否超过 4 层（如 `a.b.c.d.e`）？
+
+**风险**: 多层级关联查询会产生笛卡尔积，数据量指数级增长，导致 OOM 或超时
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 字段层级过深
+QFilter filter = new QFilter("entry.material.group.parent.name", QCP.equals, "xxx");
+
+// ✅ 正确写法 - 拆分为多次查询
+// 第一步：查询物料分组
+DynamicObject group = QueryServiceHelper.queryOne(
+    "bd_materialgroup", "id", new QFilter[]{new QFilter("parent.name", QCP.equals, "xxx")});
+// 第二步：用分组ID查询
+QFilter filter = new QFilter("entry.material.group", QCP.equals, group.getLong("id"));
+```
+
+---
+
+### 6. 数据访问方法选择不当
+**检查点**:
+- 只需判断数据是否存在时，是否使用了 `loadSingle` 或 `load`？
+- 只需读取少量字段时，是否使用了 `loadSingle`（加载完整数据包）？
+- 需要层级结构数据时，是否使用了 `queryOne`（返回拉平结构）？
+
+**方法选择指南**:
+| 场景 | 推荐方法 | 不推荐 |
+|------|---------|--------|
+| 判断是否存在 | `QueryServiceHelper.queryOne` 查 id | `loadSingle` |
+| 读取少量字段 | `QueryServiceHelper.queryOne/queryDataSet` | `loadSingle` |
+| 读取完整数据包（含层级） | `BusinessDataServiceHelper.loadSingle` | `queryOne` |
+| 大数据量流式处理 | `QueryServiceHelper.queryDataSet` | `load` |
+| 批量加载 | `BusinessDataServiceHelper.load` | 循环 `loadSingle` |
+| 利用缓存 | `BusinessDataServiceHelper.loadSingleFromCache` | `loadSingle` |
+
+---
+
+### 7. 大事务风险
+**检查点**:
+- 事务块内是否包含了大量数据操作或耗时逻辑？
+- 事务块内是否调用了外部 HTTP 接口或微服务？
+
+**风险**: 大事务执行效率低，可能造成长时间锁等待、锁冲突，进而发生阻塞或死锁
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 大事务包含外部调用
+try (TXHandle h = TX.required("bigTx")) {
+    try {
+        SaveServiceHelper.save(entities);
+        httpClient.callExternalApi(); // 外部调用在事务内！
+        updateRelatedData();
+    } catch (Throwable e) {
+        h.markRollback();
+        throw e;
+    }
+}
+
+// ✅ 正确写法 - 拆分事务，外部调用放在事务外
+try (TXHandle h = TX.required("saveTx")) {
+    try {
+        SaveServiceHelper.save(entities);
+    } catch (Throwable e) {
+        h.markRollback();
+        throw e;
+    }
+}
+// 事务外调用外部接口
+httpClient.callExternalApi();
+```
+
+---
+
+### 8. QFilter 操作符使用错误
+**检查点**:
+- 多值匹配是否使用了 `QCP.equals` 而非 `QCP.in`？
+- 模糊查询是否使用了 `QCP.equals` 而非 `QCP.like`？
+- 空值判断是否使用了 `QCP.equals` null 而非 `QCP.is_null`？
+
+**修正方案**:
+```java
+// ❌ 错误写法
+new QFilter("status", QCP.equals, Arrays.asList("A", "B")); // 应用 in
+new QFilter("name", QCP.equals, null); // 应用 is_null
+
+// ✅ 正确写法
+new QFilter("status", QCP.in, new String[]{"A", "B"});
+new QFilter("name", QCP.is_null, null);
+new QFilter("name", QCP.like, "%关键字%");
+```
+
+---
+
+## 🟡 P2 级问题
+
+### 9. queryDataSet 的 algoKey 无意义
+**检查点**:
+- `QueryServiceHelper.queryDataSet()` 的第一个参数 algoKey 是否使用了有意义的标识？
+
+**风险**: 无意义的 algoKey 不利于后续性能分析和问题定位
+
+**修正方案**:
+```java
+// ❌ 错误写法
+QueryServiceHelper.queryDataSet("q", "entity", "id", null);
+QueryServiceHelper.queryDataSet("test", "entity", "id", null);
+
+// ✅ 正确写法 - 使用有意义的标识
+QueryServiceHelper.queryDataSet("scmc.ccm.queryMaterial", "bd_material", "id,name", filters);
+```
+
+---
+
+### 10. 事务传播类型选择不当
+**检查点**:
+- 需要独立事务的场景（如写日志）是否使用了 `TX.required`（会加入外层事务）？
+- 只读查询是否使用了 `TX.required`（不必要的事务开销）？
+
+**事务传播选择指南**:
+| 场景 | 推荐类型 |
+|------|---------|
+| 业务数据保存 | `TX.required` |
+| 独立写日志/审计 | `TX.requiresNew` |
+| 只读查询 | `TX.notSupported` 或不开事务 |
+| 子操作允许部分失败 | `TX.nested` |