kcode-pi 0.1.0

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

@@ -0,0 +1,491 @@
+# 编码规范与标准检查表
+
+## 🔴 P0 级问题
+
+### 1. 空指针风险 - 链式调用未判空
+**检查点**:
+- `getDynamicObject("xxx").getPkValue()` 是否未判空？
+- `getDynamicObject("xxx").getString()` 是否未判空？
+- 任何 `getXxx()` 返回对象后直接调用方法是否未判空？
+
+**风险**: NullPointerException 导致程序崩溃
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 链式调用未判空
+Long orgId = (Long)bill.getDynamicObject("org").getPkValue();
+String name = data.getDynamicObject("user").getString("name");
+
+// ✅ 正确写法 - 先判空再调用
+DynamicObject orgObj = bill.getDynamicObject("org");
+if (orgObj == null) {
+    throw new KDBizException("组织信息不能为空");
+}
+Long orgId = (Long)orgObj.getPkValue();
+
+// ✅ 或者使用 Optional
+Long orgId = Optional.ofNullable(bill.getDynamicObject("org"))
+    .map(DynamicObject::getPkValue)
+    .map(id -> (Long)id)
+    .orElseThrow(() -> new KDBizException("组织信息不能为空"));
+```
+
+---
+
+### 2. 数组访问未判空
+**检查点**:
+- `getDataEntities()[0]` 是否未判空？
+- `this.dataEntities[0]` 是否未判空？
+
+**风险**: ArrayIndexOutOfBoundsException 或 NullPointerException
+
+**修正方案**:
+```java
+// ❌ 错误写法
+DynamicObject data = e.getDataEntities()[0];
+
+// ✅ 正确写法
+DynamicObject[] entities = e.getDataEntities();
+if (entities == null || entities.length == 0) {
+    return;
+}
+DynamicObject data = entities[0];
+```
+
+---
+
+## 🟠 P1 级问题
+
+### 3. BigDecimal 未处理 null
+**检查点**:
+- `getBigDecimal("xxx")` 返回值是否可能为 null？
+- 使用 `compareTo()` 前是否判空？
+
+**⚠️ 误判排除**:
+- **苍穹 `DynamicObject.getBigDecimal()` 特殊规则**: 若元数据定义该字段不允许为空（即非空字段），`getBigDecimal()` 会返回 `BigDecimal.ZERO` 而非 null，此时无需额外判空
+- 仅当字段在元数据中定义为**可空**，或通过 `DataSet.Row.getBigDecimal()` 获取时，才需要判空
+- **审查时应先确认字段来源**：`DynamicObject` 的非空字段获取 → 无需判空（不报问题）；`DataSet.Row` 获取或可空字段 → 需要判空
+
+**风险**: NullPointerException（仅在可空字段或 DataSet 场景下）
+
+**修正方案**:
+```java
+// ⚠️ 以下场景无需判空（DynamicObject 非空字段，框架保证返回 BigDecimal.ZERO）
+BigDecimal qty = entry.getBigDecimal("qty"); // 元数据定义非空，返回 ZERO 不会 null
+if (qty.compareTo(BigDecimal.ZERO) > 0) { ... } // 安全
+
+// ❌ 错误写法 - DataSet.Row 获取的值可能为 null
+BigDecimal qty = row.getBigDecimal("qty"); // DataSet.Row 可能返回 null
+if (qty.compareTo(BigDecimal.ZERO) > 0) { ... }
+
+// ✅ 正确写法 - DataSet.Row 或可空字段场景
+BigDecimal qty = row.getBigDecimal("qty");
+if (qty != null && qty.compareTo(BigDecimal.ZERO) > 0) { ... }
+
+// ✅ 或者使用工具方法
+BigDecimal qty = ObjectUtils.defaultIfNull(row.getBigDecimal("qty"), BigDecimal.ZERO);
+```
+
+---
+
+### 4. 集合操作不规范
+**检查点**:
+- 使用 `size() > 0` 而非 `!isEmpty()`？
+- 集合遍历时是否检查元素是否为 null？
+
+**修正方案**:
+```java
+// ❌ 错误写法
+if (list != null && list.size() > 0) { ... }
+
+// ✅ 正确写法
+if (list != null && !list.isEmpty()) { ... }
+
+// ✅ 使用工具类（推荐）
+if (CollectionUtils.isNotEmpty(list)) { ... }
+```
+
+---
+
+### 5. this.dataEntities 直接访问
+**检查点**:
+- Validator 中直接使用 `this.dataEntities` 是否判空？
+
+**修正方案**:
+```java
+// ❌ 错误写法
+public void validate() {
+    for(ExtendedDataEntity data : this.dataEntities) { ... }
+}
+
+// ✅ 正确写法
+public void validate() {
+    if (this.dataEntities == null || this.dataEntities.length == 0) {
+        return;
+    }
+    for(ExtendedDataEntity data : this.dataEntities) { ... }
+}
+```
+
+---
+
+## 🟡 P2 级问题
+
+### 6. 硬编码中文字符串
+**检查点**:
+- 代码中是否有 `"中文"` 字符串？
+- 是否直接使用中文字符串作为提示信息？
+
+**风险**: 无法国际化，维护困难
+
+**修正方案**:
+```java
+// ❌ 错误写法
+this.getView().showMessage("操作成功");
+
+// ✅ 正确写法
+String msg = ResManager.loadKDString("操作成功", "key", "module");
+this.getView().showMessage(msg);
+```
+
+---
+
+### 7. 异常日志丢失堆栈
+**检查点**:
+- `catch` 块中是否只打印了 `e.getMessage()`？
+- `logger.error()` 是否没有传入异常对象？
+
+**风险**: 无法定位问题根因
+
+**修正方案**:
+```java
+// ❌ 错误写法
+try {
+    // ...
+} catch (Exception e) {
+    logger.error("操作失败: " + e.getMessage()); // 丢失堆栈！
+}
+
+// ✅ 正确写法
+try {
+    // ...
+} catch (Exception e) {
+    logger.error("操作失败", e); // 保留完整堆栈
+}
+```
+
+---
+
+### 8. 魔法数字
+**检查点**:
+- 代码中是否有未解释的数字常量？
+
+**修正方案**:
+```java
+// ❌ 错误写法
+if (status == 1) { ... }
+
+// ✅ 正确写法
+private static final int STATUS_ENABLED = 1;
+if (status == STATUS_ENABLED) { ... }
+```
+
+---
+
+### 9. 变量命名不规范
+**检查点**:
+- 变量名是否符合驼峰命名规范？
+- 常量是否使用全大写下划线？
+
+**修正方案**:
+```java
+// ❌ 错误写法
+String UserName;
+int max_count;
+
+// ✅ 正确写法
+String userName;
+int MAX_COUNT;
+```
+
+---
+
+### 10. 空异常处理
+**检查点**:
+- 是否有空 `catch` 块？
+
+**修正方案**:
+```java
+// ❌ 错误写法
+try {
+    // ...
+} catch (Exception e) {
+    // 吞掉异常
+}
+
+// ✅ 正确写法
+try {
+    // ...
+} catch (Exception e) {
+    logger.error("处理失败", e);
+    throw new RuntimeException("处理失败", e);
+}
+```
+
+---
+
+### 11. 常量声明不规范
+**检查点**:
+- 实例字段是否应该声明为 static final？
+
+**修正方案**:
+```java
+// ❌ 错误写法
+public class MyValidator {
+    private final BigDecimal ZERO;  // 每个实例都创建
+    
+    public MyValidator() {
+        this.ZERO = BigDecimal.ZERO;
+    }
+}
+
+// ✅ 正确写法
+public class MyValidator {
+    private static final BigDecimal ZERO = BigDecimal.ZERO;  // 类级别常量
+}
+```
+
+---
+
+### 12. 冗余代码
+**检查点**:
+- 是否有无用的空构造函数？
+- 是否有未使用的导入？
+- 是否有注释掉的代码？
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 冗余空构造函数
+public class MyPlugin {
+    public MyPlugin() {
+        super();  // 完全冗余
+    }
+}
+
+// ✅ 正确写法 - 删除冗余代码
+public class MyPlugin {
+    // 编译器会自动生成默认构造函数
+}
+```
+
+---
+
+## 命名规范检查
+
+### 13. Java 类命名不规范
+**检查点**:
+- 普通类是否使用 UpperCamelCase？
+- DO/BO/DTO/VO 等缩写是否全大写保留？（`UserDO` 而非 `UserDo`）
+- 抽象类是否以 `Abstract` 开头？
+- 异常类是否以 `Exception` 结尾？
+- 枚举类是否以 `Enum` 后缀，成员是否全大写+下划线？
+- 是否存在随意缩写？（`AbstractClass` → `AbsClass`、`condition` → `condi` 均不可接受）
+
+**插件类名后缀规则**:
+| 类型 | 后缀 | 示例 |
+|------|------|------|
+| 表单插件 | `FormPlugin` | `PurchaseFormPlugin` |
+| 单据插件 | `BillPlugin` | `PurchaseBillPlugin` |
+| 列表插件 | `ListPlugin` | `PurchaseListPlugin` |
+| 操作插件 | `OpPlugin` | `PurchaseOpPlugin` |
+| 报表插件 | `RptPlugin` | `PurchaseRptPlugin` |
+
+---
+
+### 14. 变量/常量命名不规范
+**检查点**:
+- 类型名词是否放词尾？（`startTime` 而非 `startedAt`，`nameList` 而非 `listName`）
+- 常量是否全大写+下划线？（`TERMINATED_THREAD_COUNT`）
+- POJO 布尔字段是否加了 `is` 前缀？（`Boolean isDeleted` → RPC 反序列化误读为 `deleted`）
+- 子父类成员变量是否同名？
+- 同一方法不同代码块的局部变量是否同名？
+
+**修正方案**:
+```java
+// ❌ 错误写法 - POJO 布尔字段加 is 前缀
+public class OrderDTO {
+    private Boolean isDeleted; // RPC 反序列化会误读为 deleted 字段
+}
+
+// ✅ 正确写法
+public class OrderDTO {
+    private Boolean deleted;
+}
+```
+
+---
+
+### 15. 注释规范缺失
+**检查点**:
+- 类/接口是否有 Javadoc 注释？
+- public 方法是否有完整的 Javadoc（@param、@return、@throws）？
+- public 常量/属性是否有注释？
+- 是否使用 `System.out.println` 代替日志？
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 无注释
+public class AttachmentSaveServiceHelper {
+    public static DynamicObject buildAttachDetail(DynamicObject typeDy, Long targetId,
+            Map<String, Object> attach) throws Exception { ... }
+}
+
+// ✅ 正确写法
+/**
+ * 附件上传帮助类
+ * @author xxx
+ * @since 2020-11-20
+ */
+public class AttachmentSaveServiceHelper {
+    /**
+     * 构建附件明细信息
+     * @param typeDy   附件类型实体
+     * @param targetId 附件 ID
+     * @param attach   附件信息
+     * @return appendix dynamic object
+     * @throws Exception exception
+     */
+    public static DynamicObject buildAttachDetail(DynamicObject typeDy, Long targetId,
+            Map<String, Object> attach) throws Exception { ... }
+}
+```
+
+---
+
+### 16. 插件继承关系错误
+**检查点**:
+- 表单插件类型与继承基类是否匹配？
+
+**正确的继承关系**:
+| 场景 | 继承基类 |
+|------|---------|
+| 单据页面 | `AbstractBillPlugIn` |
+| 基础资料页面 | `AbstractBasePlugIn` |
+| 动态表单页面 | `AbstractFormPlugIn` |
+| 列表页面 | `AbstractListPlugIn` |
+| 移动表单 | `AbstractMobFormPlugin` |
+| 移动单据 | `AbstractMobBillPlugin` |
+| 移动列表 | `AbstractMobListPlugIn` |
+| 操作服务插件 | `AbstractOperationServicePlugIn` |
+| 单据转换插件 | `AbstractConvertPlugIn` |
+
+---
+
+### 17. 日志使用不规范
+**检查点**:
+- 是否使用 `System.out.println` 而非平台日志？
+- 是否使用了非平台日志框架？（必须使用 `kd.bos.logging.Log`）
+- 是否用 JSON 序列化打印页面对象？（`SerializationUtils.toJsonString` 极耗 CPU）
+- debug 日志是否用 `isDebugEnabled()` 包裹？
+- error 日志是否传入了异常对象？
+
+**修正方案**:
+```java
+// ❌ 错误写法
+System.out.println("Debug: " + info);
+SerializationUtils.toJsonString(pageObject); // 极耗 CPU
+
+// ✅ 正确写法
+private static final Log logger = LogFactory.getLog(MyClass.class);
+
+if (logger.isDebugEnabled()) {
+    logger.debug("Debug: " + info);
+}
+logger.error("操作失败", e); // 必须传入异常对象
+```
+
+---
+
+### 18. 异常处理不规范
+**检查点**:
+- 是否统一使用 `KDException`？
+- 有原始异常时是否作为 cause 传入？
+- 是否直接调用 `Throwable.printStackTrace()`？
+- 是否有空 catch 块（隐藏异常）？
+- UI 层捕获异常后是否给出了业务语义提示（让用户知道下一步怎么处理）？
+
+**修正方案**:
+```java
+// ❌ 错误写法
+try {
+    // ...
+} catch (Exception e) {
+    e.printStackTrace(); // 禁止
+}
+
+// ❌ 错误写法 - 原始异常未作为 cause
+try {
+    // ...
+} catch (Exception e) {
+    throw new KDException(new ErrorCode("xxx", "操作失败")); // 丢失原始异常
+}
+
+// ✅ 正确写法
+try {
+    // ...
+} catch (Exception e) {
+    throw new KDException(new ErrorCode("xxx", e.getMessage()), e); // 保留原始异常
+}
+```
+
+---
+
+### 19. 分录字段与单头字段 API 混用
+**检查点**:
+- 操作分录字段时是否使用了单头字段的 `setEnable`/`setVisible` API？
+- 单头 API 操作分录字段不会报错但不生效（静默失败）
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 用单头 API 操作分录字段（静默失败，不报错但不生效）
+getView().setEnable(Boolean.FALSE, new String[]{"entryFieldKey"});
+
+// ✅ 正确写法 - 分录字段必须传 rowIndex
+int rowCount = getModel().getEntryRowCount("entryEntity");
+for (int i = 0; i < rowCount; i++) {
+    getView().setEnable(Boolean.FALSE, i, new String[]{"entryFieldKey"});
+}
+```
+
+---
+
+### 20. F7 字段赋值方式错误
+**检查点**:
+- `setValue` 写 F7 基础资料字段时是否传了整个 DynamicObject？（应只传 Long id）
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 传整个 DynamicObject
+DynamicObject org = (DynamicObject) getModel().getValue("org");
+getModel().setValue("owner", org); // 运行时报错
+
+// ✅ 正确写法 - 只传 id
+getModel().setValue("owner", org.getLong("id"));
+```
+
+---
+
+### 21. 引用对象赋值类型不一致
+**检查点**:
+- 不同实体类型的 DynamicObject 是否直接赋值？（需保证对象类型一致）
+
+**修正方案**:
+```java
+// ❌ 错误写法 - 实体类型不一致直接赋值
+DynamicObject customerObj = (DynamicObject) EntityMetadataCache.getData("bd_customer", pk);
+prop.setValueFast(dataEntity, customerObj); // 类型不一致！
+
+// ✅ 正确写法 - 通过当前实体自身类型创建实例
+MainEntityType et = this.getModel().getDataEntityType();
+DynamicObject dataEntity = (DynamicObject) et.createInstance();
+```