kcode-pi 0.1.0

package/vendor/kingdee-skills/ok-cosmic/rules/cheat-sheet.md

@@ -0,0 +1,256 @@
+# 高频 API 速查表
+
+以下 API 签名已确认准确，AI 可直接使用无需脚本验证。
+
+## QFilter 构造与组合 `[查询]`
+
+```java
+import kd.bos.orm.query.QCP;
+import kd.bos.orm.query.QFilter;
+
+// 基本构造
+new QFilter("field", QCP.equals, value)
+new QFilter("field", QCP.not_equals, value)
+new QFilter("field", QCP.large_than, value)
+new QFilter("field", QCP.less_than, value)
+new QFilter("field", QCP.large_equals, value)
+new QFilter("field", QCP.less_equals, value)
+new QFilter("field", QCP.in, new Object[]{v1, v2, v3})
+new QFilter("field", QCP.not_in, new Object[]{v1, v2, v3})
+new QFilter("field", QCP.like, "%keyword%")
+new QFilter("field", QCP.is_null, null)
+new QFilter("field", QCP.is_not_null, null)
+
+// 组合
+filter1.and(filter2)
+filter1.or(filter2)
+```
+
+## Model 读写 `[表单] [单据]`
+
+```java
+import kd.bos.dataentity.entity.DynamicObject;
+import kd.bos.dataentity.entity.DynamicObjectCollection;
+
+// 读取字段值
+Object val = getModel().getValue("fieldKey");                          // 表头字段
+Object val = getModel().getValue("fieldKey", rowIndex);                // 分录字段
+Object val = getModel().getValue("fieldKey", rowIndex, parentRowIndex);// 子分录字段
+
+// 设置字段值（自动触发 propertyChanged）
+getModel().setValue("fieldKey", value);                                // 表头
+getModel().setValue("fieldKey", value, rowIndex);                      // 分录
+
+// 按 ID 设置基础资料字段（自动加载引用对象，比 setValue + loadSingle 更简洁）
+getModel().setItemValueByID("basedataFieldKey", pkId);                 // 表头基础资料
+getModel().setItemValueByID("basedataFieldKey", pkId, rowIndex);       // 分录基础资料
+
+// 按编码设置基础资料字段（已知编码不知 ID 时使用）
+getModel().setItemValueByNumber("basedataFieldKey", number);           // 表头基础资料
+getModel().setItemValueByNumber("basedataFieldKey", number, rowIndex); // 分录基础资料
+
+// 分录操作
+int rowCount = getModel().getEntryRowCount("entryKey");               // 分录行数
+int newRow = getModel().createNewEntryRow("entryKey", rowIndex);      // 新增分录行
+getModel().deleteEntryRow("entryKey", rowIndex);                      // 删除分录行
+DynamicObject rowEntity = getModel().getEntryRowEntity("entryKey", rowIndex); // 获取分录行数据包
+DynamicObject dataEntity = getModel().getDataEntity();                // 获取完整数据包
+DynamicObjectCollection entry = dataEntity.getDynamicObjectCollection("entryKey"); // 分录集合
+```
+
+## View 控制 `[表单] [单据] [列表]`
+
+```java
+import kd.bos.form.FormShowParameter;
+import kd.bos.form.control.Control;
+import kd.bos.list.ListShowParameter;
+
+// 字段锁定/解锁
+getView().setEnable(boolean, "key1", "key2"...);       // 支持多 key
+
+// 字段锁定/解锁(分录按行处理)
+getView().setEnable(boolean, index , "key1", "key2"...);       // 支持多 key
+
+// 字段显示/隐藏
+getView().setVisible(boolean, "key1", "key2"...);      // 支持多 key
+
+// 通知
+getView().showSuccessNotification(String msg);
+getView().showErrorNotification(String msg);
+getView().showTipNotification(String msg);
+
+// 操作
+getView().invokeOperation(String opKey);               // 调用操作
+getView().updateView(String key);                      // 刷新控件
+getView().updateView();                                // 刷新整个视图
+getView().showForm(FormShowParameter/ListShowParameter); // 打开页面
+
+// PageCache（跨事件传值）
+getView().getPageCache().put(String key, String value);
+String val = getView().getPageCache().get(String key);
+
+// 获取控件
+Control ctrl = getView().getControl("controlKey");
+```
+
+## 封装工具类速查 `[通用]`
+
+```java
+import kd.cd.core.util.CharSequenceUtils;
+import kd.cd.core.util.CollectionUtils;
+// fallback
+// import org.apache.commons.lang3.StringUtils;
+// import org.apache.commons.collections4.CollectionUtils;
+import kd.cd.common.util.DynamicObjectUtils;
+import kd.cd.common.operate.OpUtils;
+import kd.bos.orm.query.QFilter;
+
+// 字符串判空
+CharSequenceUtils.isBlank(str)
+CharSequenceUtils.isNotBlank(str)
+CharSequenceUtils.equals(a, b)
+
+// 集合判空
+CollectionUtils.isEmpty(collection)
+CollectionUtils.isNotEmpty(collection)
+
+// DynamicObject 取值
+DynamicObjectUtils.nullSafeGet(dynamicObject, "field")       // 安全取值（空安全）
+DynamicObjectUtils.setOf(dynamicObjects, "field")
+DynamicObjectUtils.listOf(dynamicObjects, "field")
+
+// 查询（标准 API）
+QueryServiceHelper.queryOne(entityId, field, filters)                  // 查一条
+QueryServiceHelper.query(entityId, selectFields, filters)              // 查多条 → DynamicObjectCollection
+QueryServiceHelper.query(entityId, selectFields, filters, orderBy)     // 查多条 + 排序
+QueryServiceHelper.queryDataSet(formId, algoKey, selectFields, filters, orderBy)  // 查 DataSet
+
+// 操作（失败即抛异常，适合大多数场景）
+OpUtils.executeOperateOrThrow(opKey, entityId, new Object[]{pk})
+OpUtils.executeOperateOrThrow(opKey, entityId, dataEntities)
+OpUtils.throwIfFail(operationResult)
+OpUtils.addErrorMessage(plugin, dataEntity, message)
+
+// 操作（需要自行解析结果，适合 MQ 消费、后台任务等"失败不抛异常"场景）
+OperationResult result = OperationServiceHelper.executeOperate(opKey, entityId, pks, option)
+if (!result.isSuccess()) { String errMsg = OpUtils.getCompleteFailMsg(result); /* 自行处理 */ }
+```
+
+## 弹窗与回调 `[表单] [单据]`
+
+```java
+import kd.bos.bill.OperationStatus;
+import kd.bos.form.CloseCallBack;
+import kd.bos.form.ConfirmCallBackListener;
+import kd.bos.form.FormShowParameter;
+import kd.bos.form.MessageBoxOptions;
+import kd.bos.form.ShowType;
+import kd.bos.list.ListShowParameter;
+import kd.cd.common.form.ShowParameterUtils;
+
+// 打开 F7 列表弹窗
+ListShowParameter lsp = ShowParameterUtils.getF7List(formId, multiSelect);
+getView().showForm(lsp);
+
+// 打开普通表单弹窗
+FormShowParameter fsp = ShowParameterUtils.getForm(formId, OperationStatus.ADDNEW, ShowType.Modal, "500px", "300px");
+fsp.setCustomParam("key", value);
+fsp.setCloseCallBack(new CloseCallBack(this, "actionId"));
+getView().showForm(fsp);
+
+// 确认框
+ConfirmCallBackListener listener = new ConfirmCallBackListener("callbackId", this);
+getView().showConfirm("确认信息？", MessageBoxOptions.YesNo, listener);
+```
+
+## 操作链 `[操作]`
+
+```java
+import kd.cd.common.operate.chain.OperateChain;
+
+// 链式操作
+OperateChain.of(dataEntity).save().submit().audit().failThenThrow();
+OperateChain.of(entityId, pkValue).save().submit().failThenDeleteAndThrow();
+```
+
+## BOTP 下推与选单 `[转换]`
+
+```java
+import kd.cd.common.util.BotpUtils;
+import kd.cd.common.util.BotpUtils.PushResult;
+
+// 后台下推并保存（最常用，4 参数：源单标识, 目标单标识, 源单主键, 转换规则ID）
+PushResult result = BotpUtils.pushAndSave(sourceFormId, targetFormId, sourcePk, null);
+result.failThenThrow();
+result.isSuccess();
+result.getErrMsg();
+Object[] targetPks = result.getPks();
+
+// 下推不保存（只生成内存对象）
+PushResult result = BotpUtils.pushNoSave(sourceFormId, targetFormId, sourcePk, null);
+
+// 获取默认转换规则
+String ruleId = BotpUtils.getDefaultRuleId(sourceFormId, targetFormId);
+
+// 正向链路追踪：查所有下游目的单
+Map<Long, Map<String, Set<Long>>> targets = BotpUtils.findAllTargetBills(targetEntityId, entityId, pkValues);
+
+// 反向链路追踪：查直接上游源单
+Map<Long, Set<Long>> sources = BotpUtils.findDirectSourceBills(sourceEntityId, entityId, pkValues);
+```
+
+## 元数据常用操作 `[通用]`
+
+```java
+import kd.bos.entity.MainEntityType;
+import kd.bos.entity.property.EntryType;
+import kd.bos.dataentity.metadata.IDataEntityProperty;
+import kd.cd.common.entity.EntityUtils;
+
+// 获取主实体类型
+MainEntityType mainType = EntityUtils.getMainEntityType(formId);
+
+// 获取字段属性（单据头 & 单据体均适用）
+IDataEntityProperty prop = EntityUtils.getProperty(formId, "fieldKey");
+
+// 获取分录实体类型
+EntryType entryType = EntityUtils.getEntryType(formId, "entryKey");
+
+```
+
+## 异常与日志 `[通用]`
+
+```java
+import kd.bos.exception.ErrorCode;
+import kd.bos.exception.KDBizException;
+import kd.bos.logging.Log;
+import kd.bos.logging.LogFactory;
+
+// 业务异常（统一使用 KDBizException）
+throw new KDBizException(new ErrorCode("myModule", "errCode001"), "业务描述");
+
+// 包装异常（保留原始 cause）
+throw new KDBizException(new ErrorCode("myModule", "errCode002"), e);
+
+// 日志记录（插件内直接使用内置 log）
+log.info("操作完成: billNo={}", billNo);
+log.error("操作失败", e);    // 异常用 error 级别
+
+// 非插件类获取日志
+private static final Log log = LogFactory.getLog(MyService.class);
+```
+
+## 多语言 `[通用]`
+
+```java
+import kd.bos.dataentity.resource.ResManager;
+
+// 标准写法：完整句模板 + 占位符
+String msg = String.format(
+    ResManager.loadKDString("单据 %1$s 的金额 %2$s 超出限额", "MyPlugin_0", "kd-cd-myapp"),
+    billNo, amount
+);
+
+// 错误写法（禁止拼接）
+// String msg = "单据" + billNo + "的金额" + amount + "超出限额";
+```

package/vendor/kingdee-skills/ok-cosmic/rules/coding-preferences.md

@@ -0,0 +1,140 @@
+# 编码偏好、默认写法与治理方向
+
+> 本文件为 `style_check.py`（STYLE-\*）、`resource_check.py`（RESOURCE-\*）、`verify_check.py`（VERIFY-\*）的**规则来源**。
+> 幻觉禁忌和场景错配见 [anti-patterns.md](anti-patterns.md)；当前自动 lint 规则前缀为 SCENE-\*。
+
+本文件承载 `ok-cosmic` 的 **B 层** 和 **C 层** 规则：
+
+- **B 层：推荐项 / 新代码默认写法**
+  - 新生成代码默认尽量遵守。
+  - 历史存量代码若暂未满足，不因此直接判为错误。
+  - **"新代码"与"历史修补"的判断标准**：如果当前任务是**新增文件或新增方法**，按新代码标准遵守 B 层；如果是**在已有方法内追加几行逻辑**，优先保持与周围代码风格一致，B 层不强制。不确定时问用户。
+- **C 层：目标态治理 / 渐进优化**
+  - 适合模板升级、专项治理、批量重构。
+  - 默认不作为一次性交付阻断项。
+
+真正的硬红线请看 [constraints.md](constraints.md)。
+
+## B1. 新代码默认写法
+
+### 插件基类与封装优先级
+
+- **[B1.1]** **插件基类（封装层）**：新代码优先选择 `kd.cd.common.plugin` 包下的扩展基类：
+  `AbstractBillPlugInExt`、`AbstractFormPluginExt`、`AbstractListPluginExt`、`AbstractOperationServicePlugInExt`、`AbstractValidatorExt`
+- **[B1.2]** **原生插件基类**：BOTP 转换（`AbstractConvertPlugIn`）和反写（`AbstractWriteBackPlugIn`）没有 `*Ext` 封装版本，直接使用 `kd.bos.entity.botp.plugin` 包下的原生基类。
+- **[B1.3]** 如果必须给出原生写法：
+  先说明为什么仓库封装不适用，再给最小可行实现，不要把原生样板扩散成默认风格。
+- **[B1.4]** 历史项目中大量原生基类写法是可预期的；评估现有代码时，不要因为“不是 Ext 基类”就直接判错。
+
+### 工具类与实现风格
+
+- **[B1.5]** 需要错误汇总时，优先使用 `OpUtils.addErrorMessage(...)`、`OpUtils.getCompleteFailMsg(...)`、`PushResult.failThenThrow()`
+- **[B1.6]** 字符串判空优先使用 `CharSequenceUtils`；当其 API 未覆盖时（如 `trimToEmpty`、`substringBefore` 等），fallback 为 `org.apache.commons.lang3.StringUtils`；不要在**新示例代码**里混用 `ObjectUtils` 做字符串空白判断。
+- **[B1.7]** 集合判空优先使用 `CollectionUtils`（`kd.cd.core.util`）；当其 API 未覆盖时（如 `partition`、`union` 等），fallback 为 `org.apache.commons.collections4.CollectionUtils`；不要在**新示例代码**里手写 `!= null && !isEmpty()`。
+- **[B1.8]** 对异常优先使用日志框架记录；`*Ext` 基类里直接使用内置的 `public final Log log`，非插件类可直接使用 `kd.bos.logging.LogFactory`。
+- **[B1.9]** 未经用户明确要求，不要偏离 `assets/FormPluginTemplate.java` 的代码风格；确需偏离时，在答案里说明原因。
+- **[B1.10]** 若必须新增模板之外的 `import`，需仅新增最小集合，并说明新增原因。
+
+### 业务封装优先级
+
+- **[B1.11]** 对单据状态流转，失败即抛异常的场景优先使用 `OpUtils.executeOperateOrThrow`；需要自行解析操作结果的场景（如 MQ 消费、后台任务、失败后回填错误信息）可直接使用 `OperationServiceHelper.executeOperate` 并检查 `OperationResult`。
+- **[B1.12]** 只有在需要连续调用多个操作时，才优先使用 `OperateChain`；单次 `save`、`submit`、`audit` 优先使用 `OpUtils`。
+- **[B1.13]** 对单据转换，优先使用 `BotpUtils`；不要在**新代码**里手拼 `PushArgs`/`DrawArgs` 等重复样板。
+- **[B1.14]** 处理基础资料（BaseData）相关业务动作时，先查 `BaseDataServiceHelper` 是否已有现成方法。
+- **[B1.15]** 在操作插件里，除非需要准备的字段非常多，否则不要使用 `allFields()`；优先按实际场景显式准备字段。
+- **[B1.16]** 对查询，优先使用 `QueryServiceHelper` + `AlgoUtils`；不要先写裸 SQL 或循环查库。
+- **[B1.17]** `QueryServiceHelper.query(...)` 查出来的是扁平结果集，默认只用于读取、分组、聚合；不要直接 `set(...)` 后 `SaveServiceHelper.update/save(...)`。
+- **[B1.18]** 查询基础资料时，优先使用 `BusinessDataServiceHelper.loadFromCache(...)`；不要对基础资料反复用普通查询接口查库。
+- **[B1.19]** 对动态对象取值，优先使用 `DynamicObjectUtils`；不要直接深链式 `get("a.b.c")`。
+- **[B1.20]** 对附件处理，优先使用 `AttachmentUtils` 和 uploader；不要直接散落调用 `AttachmentServiceHelper`。
+- **[B1.21]** `references/base/*` 只用于补齐原生知识、事件签名和缺失能力；不要因为能写原生 API 就绕开现有封装。
+
+### 查询、资源与提示语
+
+- **[B1.22]** 判断"是否存在"时，**新代码优先**使用 `QueryServiceHelper.exists(...)`，不要使用 `queryOne(...) != null` 这种写法。
+- **[B1.23]** 查询时只取实际需要的字段；除加载完整单据/基础资料外，不要默认 `allFields()` 或无选择地查整包数据。
+- **[B1.24]** `DataSet` 使用后要在最靠近创建/转换的位置关闭；优先用清晰的生命周期包裹，避免跨方法悬挂。
+- **[B1.25]** 需要参数化查询时，优先使用平台查询构造或 KSQL 参数，不要手拼 where 条件字符串。
+- **[B1.26]** 面向用户的提示语要体现业务语义和下一步动作，不要只抛底层异常文本。
+- **[B1.27]** 报表或大结果集处理时，优先复用已查询数据，并用 `algo` 做分组、去重、统计；不要把大聚合逻辑堆进 Java 循环。
+- **[B1.28]** 大数据量查询（如批量同步、报表取数、后台任务处理）时，优先使用分页迭代（`setLimit` + 循环偏移）或流式 `DataSet` 处理；不要一次性全量加载到内存。
+
+## B2. 元数据与脚本配合细则
+
+- **[B2.1]** **元数据查询约束**：调用 `cosmic-form-metadata.py` 时，脚本会无条件展示所有字段；如果概览模式未显示所需字段，请主动在 `--fuzzy` 中增加搜索词进行精准匹配。
+- **[B2.2]** 如果脚本未查到字段或表单元数据，必须提醒用户确认其提供的表单名称/标识是否正确，再继续处理。
+- **[B2.3]** **字段元数据强制验证**：只要要生成/修改代码，且已知目标单据/表单，凡涉及字段（无论用户给中文名还是英文标识），都必须通过 `cosmic-form-metadata.py` 确认字段存在、字段类型、所属实体和特殊取值规则后再写入代码。
+- **[B2.4]** **批量合并**：需要确认多个字段时，必须合并为一次 `--fuzzy` 调用（如 `--fuzzy qty price amount material org`），严禁逐个字段发起多次查询。
+- **[B2.5]** **自动详情**：当 `--fuzzy` 传入 ≥3 个关键词时，脚本自动升级为详情模式（含枚举/refType），无需手动追加 `--show-detail`。
+- **[B2.6]** **常规字段对齐**：仅确认 1-2 个字段标识时，不带 `--show-detail` 和 `--sql`。
+- **[B2.7]** **深度实现（含枚举值）**：当需要编写枚举判断、手动赋值或基础资料关联查询前，带上 `--show-detail`。**枚举/下拉选项值的具体取值属于 A 层硬约束 [A1.8]，必须查 Ext 列确认后才能写入代码，详见 [constraints.md](constraints.md)。**
+- **[B2.8]** **生成 SQL**：除非用户强依赖编写原生 JDBC/SQL 查询，否则默认不要使用 `--sql`。
+
+## C1. 目标态治理项
+
+以下内容仍然推荐，但默认作为长期治理方向，而不是当前一次性交付阻断项：
+
+- **[C1.1]** **验证来源注释**：建议在关键 `@Override` 方法或 BOS SDK 关键调用附近补充“验证来源”注释，作为事实留痕。
+- **[C1.2]** **异常体系统一**：建议逐步把历史项目中的 `RuntimeException`、`IllegalArgumentException` 等，收敛到更明确的业务异常或带 `cause` 的统一异常体系。
+- **[C1.3]** **日志治理**：建议逐步清理历史代码中的 `printStackTrace()`，统一为 `logger.error("问题描述", e)`。
+- **[C1.4]** **存在性判断治理**：建议在后续重构中逐步把 `queryOne(...) != null` 迁移为更明确的存在性判断或领域查询封装。
+- **[C1.5]** **原生基类迁移**：对稳定运行的历史插件，不要求为了“改成 Ext 基类”而进行无收益重构；只有在功能演进、模板升级、公共封装复用收益明确时再迁移。
+
+## C2. 评估历史代码时的默认口径
+
+- **[C2.1]** 发现历史代码使用原生基类、`StringUtils`、`queryOne(...)`、`OperationServiceHelper.executeOperate(...)` 等写法时，先判断其是否触犯 [constraints.md](constraints.md) 中的硬红线。
+- **[C2.2]** 若没有触犯 A 层红线，则应描述为：
+  - “当前可运行的历史写法”
+  - “建议新代码采用的替代写法”
+  - “是否值得在本次需求中顺手收敛”
+- **[C2.3]** 不要把所有历史写法一律描述成"错误"；要区分 **硬错误**、**推荐替换**、**后续治理** 三种层级。
+
+## 自动检测规则速查（STYLE / RESOURCE）
+
+> 以下规则由 `style_check.py` 和 `resource_check.py` 自动扫描。
+> A 层规则 ID 定义在 [a-layer-rules.json](a-layer-rules.json)（单一可信源），报 ERROR 必须修复；B 层报 WARNING，新代码优先修复。
+
+### STYLE-\*: 编码风格
+
+| 规则 ID | 检测模式 | 正确做法 | 层级 |
+|---|---|---|---|
+| STYLE-001 | `StringUtils.isBlank/isEmpty/equals` 等判空方法 | `CharSequenceUtils`（仅 `isBlank/isNotBlank/isEmpty/isNotEmpty/equals`；`trimToEmpty` 等未覆盖方法 fallback `org.apache.commons.lang3.StringUtils`） | B |
+| STYLE-002 | `!= null && !collection.isEmpty()` | `CollectionUtils.isNotEmpty(...)`；`partition` 等未覆盖方法 fallback `org.apache.commons.collections4.CollectionUtils` | B |
+| STYLE-003 | 散落调用 `OperationServiceHelper.save/submit/audit` | `OpUtils` 或 `OperateChain` | B |
+| STYLE-004 | `new PushArgs(...)` | `BotpUtils` | B |
+| STYLE-005 | `new DrawArgs(...)` | `BotpUtils` | B |
+| STYLE-006 | `dynamicObject.get("a.b.c")` 深链取值 | `DynamicObjectUtils` 安全取值 | B |
+| STYLE-007 | 直接调用 `AttachmentServiceHelper` | `AttachmentUtils` + uploader | B |
+| STYLE-008 | `queryOne(...) != null` 判存在 | `QueryServiceHelper.exists(...)` | B |
+| STYLE-009 | `printStackTrace()` | `logger.error("描述", e)` | **A** |
+| STYLE-010 | 操作插件使用 `allFields()` | 显式按场景准备字段 | B |
+| STYLE-011 | SQL/KSQL 字符串拼接 | 参数化查询 | **A** |
+| STYLE-012 | 数据库方言 SQL（`limit`/`rownum`/`nvl`/`isnull`） | KSQL 或平台查询接口 | **A** |
+| STYLE-013 | 中文词条拼接（`"关于" + name + ...`） | 完整句模板 + `String.format(ResManager.loadKDString(...))` | B |
+| STYLE-014 | 循环中 `view.updateView(...)` | 循环结束后统一局部刷新 | **A** |
+| STYLE-015 | 循环中访问数据库（N+1 查询/写入），包括 `for`/`while` 及 `stream().forEach`/`map` 等 lambda 迭代；覆盖 `BusinessDataServiceHelper`/`QueryServiceHelper`/`SaveServiceHelper` | 分组 key → 批量加载 → 本地映射 | **A** |
+| STYLE-016 | 循环中访问 Redis | 批量读取或本地缓存 | **A** |
+| STYLE-017 | `query(...)` 结果直接 `set(...)` / `save` | 先 `query` 出 id，再 `load` 实体包后更新 | B |
+| STYLE-018 | `throw new RuntimeException(...)` 等 | `KDBizException`，保留原始 `cause` | **A** |
+| STYLE-019 | `new Thread(...)` | `kd.bos.threads.ThreadPools` | B |
+| STYLE-020 | `Executors.*` | `ThreadPools.new*` / `ThreadPools.executeOnce*` | B |
+| STYLE-021 | `SerializationUtils.toJsonString(args)` 打印大对象 | 只按需提取关键字段打印 | B |
+| STYLE-022 | 循环中 `ORM.create(...)` | 批量组织数据，按批次处理 | **A** |
+| STYLE-023 | 循环中 `DispatchServiceHelper.invoke*` | 合并/批量调用或先聚合参数 | **A** |
+| STYLE-024 | `new QFilter(field, "=", value)` 第二个参数用字符串 | `new QFilter(field, QCP.equals, value)`，使用 QCP 枚举 | **A** |
+| STYLE-025 | `BusinessDataServiceHelper.load(...)` 未指定查询字段（配合 `EntityUtils.getMainEntityType` / `BusinessDataServiceHelper.newDynamicObject` / `EntityMetadataCache.getDataEntityType` 全量加载） | 使用 `BusinessDataServiceHelper.load(entityName, selectFields, filters)` 指定所需字段 | B |
+| STYLE-026 | 主键/id 用 `== null` / `!= null` / `== 0L` / `<= 0` 判空 | `EntityUtils.isEmptyPk(pk)` / `isNotEmptyPk(pk)`（兼容 null 和 0L） | B |
+| STYLE-027 | BigDecimal 原生加减乘除与比较（`.add()` / `.subtract()` / `.multiply()` / `.divide()` / `.compareTo()`） | `BigDecimalUtils.add()` / `subtract()` / `multiply()` / `divide()` / `equals()` / `largeThan()` | B |
+
+### RESOURCE-\*: 资源管理
+
+| 规则 ID | 检测模式 | 正确做法 | 层级 |
+|---|---|---|---|
+| RESOURCE-001 | 插件成员变量持有 `DataSet`/`InputStream` 等 | 方法内短持有，用完关闭 | B |
+| RESOURCE-002 | 非 `final` 的 `static` 状态变量 | `PageCache` 或实例变量 | B |
+| RESOURCE-003 | `ResManager.loadKDString(...)` 固化为 `static final` | 改为方法内实时获取 | B |
+| RESOURCE-004 | `DataSet` 声明但未 `close()` | try-with-resources 或就近关闭 | **A** |
+
+RESOURCE-004 例外（不报错）：
+- **报表插件等场景中 `return ds;`** — DataSet 作为方法返回值，由调用方/框架负责关闭。
+- **DataSet 参与计算或合并** — `DataSet result = ds1.union(ds2)` 中 `ds1`、`ds2` 被消费，只需 close 最终结果 `result`。

package/vendor/kingdee-skills/ok-cosmic/rules/constraints.md

@@ -0,0 +1,61 @@
+# 硬约束与交付红线
+
+> 本文件为**流程与原则守卫**（guidance-only），不直接对应 lint 脚本。
+> 可自动检测的规则见：[anti-patterns.md](anti-patterns.md)（SCENE）、[coding-preferences.md](coding-preferences.md)（STYLE/RESOURCE/VERIFY）。
+
+本文件只承载 `ok-cosmic` 的 **A 层规则**：会直接影响事实准确性、插件上下文、事件阶段和交付正确性的硬约束。
+
+- 命中本文件中的问题，默认按 **阻断交付** 处理。
+- 不属于本文件的"推荐写法"与"目标态治理"，请分别查看：
+  - [coding-preferences.md](coding-preferences.md)
+  - [post-check.md](post-check.md)
+
+## A1. 事实校验与模板约束
+
+- **[A1.1] 拒绝幻觉**：严禁凭记忆或猜测生成任何 API 签名、事件方法名或单据字段标识。
+- **[A1.2] 模板强制先行**：AI 在生成任何苍穹插件代码前，必须先读取对应的 `assets/*.java` 模板文件，并严格遵守模板中的方法签名。
+- **[A1.3] 签名强制校验**：在编写任何 `@Override` 方法或调用 BOS SDK 关键方法前，应通过 `cosmic-api-knowledge.py` 的 `detail` 子命令验证该方法确实存在且签名准确（已在 `rules/cheat-sheet.md` 中列出的 API 可直接使用，无需脚本验证）。`API-*` 事后 lint 规则已废弃，若事前校验被跳过，只能依赖编译、脚本查询或人工确认补救。
+- **[A1.4] 入口对齐协议**：
+   - **UI 控制 (只读/隐藏/弹窗)**：必须通过 `IFormView`（由 `this.getView()` 获取）。
+   - **数据操作 (取值/赋值/结构)**：必须通过 `IDataModel`（由 `this.getModel()` 获取）。
+- **[A1.5] 验证优先级**：在使用原生 SDK 前，必须先查本地 `.md`，再通过脚本验证。
+- **[A1.6] 继承溯源**：利用脚本返回的继承树确认方法是否在基类中。
+- **[A1.7] 代码风格基线**：新生成代码必须以对应模板为主，不得脱离模板随意改写方法签名、生命周期方法或基础骨架。
+- **[A1.8] 枚举/下拉选项值禁猜**：凡是需要使用 `ComboField`、下拉列表等字段的**具体选项值**（无论用于条件判断、状态赋值、QFilter 构造、数据反写还是任何其他场景），**严禁凭空编造或凭经验猜测**。必须先通过 `cosmic-form-metadata.py` 查询该字段，读取返回结果中「附加信息 (Ext)」列的真实枚举映射（如 `A:已审核, B:暂存`），确认后才能将对应的值写入代码。
+- **[A1.9] 字段生成代码强制验证**：只要要生成或修改代码，且已知目标单据/表单（`formId` 或 `billName`），凡涉及字段（无论用户给的是中文名还是英文标识），都必须先通过 `cosmic-form-metadata.py` 验证字段是否存在、字段类型、所属实体（表头/表体/子表体/容器）和特殊取值规则（如 `BasedataPropField` 的 `refType`、`LargeTextField` 的 `{fieldKey}_tag`、Combo/下拉字段 Ext 映射）。未验证前不得直接把用户给出的字段写入代码。
+
+## A2. 平台开发红线
+
+> 以下条目的平台背景详见 [platform-baseline.md](platform-baseline.md)，对应的自动化 lint 规则主要见 [anti-patterns.md](anti-patterns.md)。
+
+- **[A2.1] 绑定阶段禁改数据**：禁止在 `beforeBindData`、`afterBindData` 中修改数据对象。（→ `SCENE-008`）
+- **[A2.2] initialize 边界**：禁止在 `initialize()` 中注册控件事件或做 UI 逻辑。（→ `SCENE-006`, `SCENE-007`）
+- **[A2.3] 元数据访问边界**：业务代码禁止直接访问平台元数据表 `t_meta_xxx`。（→ `SCENE-009`）
+- **[A2.4] 标准产品保护**：禁止继承标准产品表单/单据插件；禁止禁用原厂插件。
+- **[A2.5] 引用对象类型一致**：创建引用对象时必须使用属性复杂类型或当前实体正确类型。（→ `SCENE-010`）
+- **[A2.6] 元数据单例保护**：从缓存获取到的实体元数据必须先 `clone` 再修改。
+- **[A2.7] 设计器/PDM 一致性**：业务对象、字段、默认值、可空性等定义以 PDM 和设计器为准。
+
+## A3. 运行时与运维红线
+
+- **[A3.1] 数据访问红线**：查询必须参数化；`DataSet` 使用完必须关闭；禁止把 SQL/KSQL 条件当字符串随意拼接。（→ `STYLE-011`, `STYLE-012`, `RESOURCE-004`）
+- **[A3.2] 性能红线**：禁止在循环中访问数据库、Redis、`view.updateView()`、`ORM.create()`、`DispatchServiceHelper.invoke*()`。（→ `STYLE-014`, `STYLE-015`, `STYLE-016`, `STYLE-022`, `STYLE-023`）
+- **[A3.3] 日志红线**：统一使用 `kd.bos.logging.Log`；禁止 `printStackTrace()`。（→ `STYLE-009`）
+- **[A3.4] 异常红线**：业务流程中的业务异常不得直接用 `RuntimeException` 伪装。（→ `STYLE-018`）
+
+## A4. 与 B/C 层的边界
+
+- **不属于 A 层**：
+  - "优先使用 `Ext` 基类而不是原生基类"
+  - "优先使用 `OpUtils` / `BotpUtils`"
+  - "优先使用 `QueryServiceHelper.exists(...)` 替代 `queryOne(...)`"
+  - "给每个 `@Override` 都补验证来源注释"
+- 上述内容仍然是有价值的，但默认分别归入：
+  - **B 层推荐项**：新代码默认遵守
+  - **C 层治理项**：适合逐步清理历史项目，不作为当前一次性交付的硬阻断
+
+## A5. 当前默认交付判断
+
+- 命中 `SCENE-*` 中的硬错误，默认必须修复。
+- 命中本文件列出的平台红线或运行时红线，默认必须修复。
+- 若用户明确要求"按历史代码风格补丁式修改"，可保留 **B/C 层** 历史写法，但仍不得突破 **A 层** 红线。