kcode-pi 0.1.0

package/vendor/kingdee-skills/ok-cosmic/references/adv/attachment-api.md

@@ -0,0 +1,114 @@
+# 附件与文件系统工具 (AttachmentUtils)
+
+## TL;DR
+- 适用：附件面板复制、附件 DTO 绑定、跨单据附件同步和签名 URL 处理。
+- 先抓：优先用 `AttachmentUtils` 处理复制、绑定、下载与 URL 判定，少直接拼底层服务。
+- 跳转：纯文件流上传下载且不挂业务附件面板时，改读 `base/sdk/sdk-file.md`。
+- 继续读全文：当你要确认 `CopyFeature` 选项、面板绑定细节或跨单据同步示例时。
+
+## 概述
+苍穹的附件系统涉及物理文件、URL 签名与业务面板绑定。`AttachmentUtils` (位于 `kd.cd.common.attachment`) 旨在简化跨单据附件同步、文件在线下载以及附件面板的全方位管理。本规范支持所有涉及文件流的操作场景。
+
+> **适用边界**
+> ✅ 适用：附件上传/下载/复制/同步/面板绑定。
+> ❌ 不适用：纯文件流操作（无业务面板）请直接用 SDK `FileServiceHelper`。
+
+## 核心类
+- **`kd.cd.common.attachment.AttachmentUtils`**: **附件处理核心工具类**。
+- **`kd.bos.servicehelper.AttachmentServiceHelper`**: 原生附件服务帮助类。
+- **`kd.bos.servicehelper.AttDto`**: 附件数据传输对象。
+- **`kd.cd.common.attachment.CopyFeature`**: 附件复制选项配置。
+- **`kd.cd.common.attachment.BindType`**: 绑定类型枚举。
+
+## 常用 API 方法
+
+### 1. 附件面板复制与绑定
+- `copyToPanel(String srcFormId, Object srcPk, String srcPanel, String tarFormId, Object tarPk, String tarPanel)`: **最常用**。实现附件面板的全量文件复制。
+- `copyToPanel(String srcFormId, Object srcPk, String srcPanel, String tarFormId, Object tarPk, String tarPanel, CopyFeature feature)`: 带复制选项的附件面板复制。
+- `copyToPanel(Collection<Long> attPks, String tarFormId, Object tarPk, String tarPanel)`: 根据附件主键集复制。
+- `copyToPanel(Collection<Long> attPks, String tarFormId, Object tarPk, String tarPanel, CopyFeature feature)`: 根据附件主键集复制，带复制选项。
+- `bind(String entityId, Object pkValue, List<AttDto> attDtos)`: 将上传的文件正式绑定到具体单据主键（转正）。
+- `bindSingle(String entityId, Object pkValue, AttDto attDto)`: 绑定单个文件。
+
+### 2. 文件解析与操作
+- `download(String pathOrUrl)`: 将 URL 下载并转换为 `InputStream` 流。**调用方必须负责关闭返回的 InputStream**。
+- `physicDelete(String... pathOrUrls)`: 物理删除文件（兼容文件服务器或文件缓存删除）。
+- `getFileName(String path)`: 获取文件名。
+- `getSuffix(String str)`: 获取后缀。
+- `isValidPath(String path)`: 判定是否为有效路径。
+
+### 3. URL 逻辑判定
+- `isDownloadUrl(String path)`: 判定是否为下载链接。
+- `isTempUrl(String path)`: 判定是否为临时存储区链接。
+- `isImageType(String str)`: 判定是否为图片。
+
+### 4. 辅助方法
+- `newAttDto(String panelOrField, String path, long size, Object entryRowPk, Consumer<AttDto> consumer)`: 生成附件信息Dto。
+- `stripFromDownloadUrl(String url)`: 从下载URL中提取路径。
+- `stripParameter(String path)`: 去掉下载路径后的查询参数与片段。
+- `decodeUtf8(String path)`: UTF-8解码。
+
+## 示例代码
+
+### 自动同步订单附件到入库单
+```java
+package kd.cd.common.demo;
+
+import kd.cd.common.attachment.AttachmentUtils;
+
+public class AttDemo {
+    public void sync(Object orderPk, Object inbillPk) {
+        // 1. 同步全量附件面板内容，内部已自动处理物理引用
+        AttachmentUtils.copyToPanel(
+            "pm_purorderbill", orderPk, "att_panel",
+            "stk_purinbill", inbillPk, "att_panel"
+        );
+    }
+}
+```
+
+### 下载并处理附件
+```java
+public void processAttachment(String fileUrl) {
+    // 使用 try-with-resources 确保流关闭
+    try (InputStream is = AttachmentUtils.download(fileUrl)) {
+        // 处理文件流
+    } catch (IOException e) {
+        // 异常处理
+    }
+}
+```
+
+### 生成并绑定附件Dto
+```java
+public void bindNewAttachment(String entityId, Object pkValue, String path, long size) {
+    AttDto attDto = AttachmentUtils.newAttDto("att_panel", path, size, null, dto -> {
+        dto.setName("附件名称");
+    });
+    State result = AttachmentUtils.bindSingle(entityId, pkValue, attDto);
+    if (!result.isSuccess()) {
+        throw new KDBizException(result.getMessage());
+    }
+}
+```
+
+## CopyFeature 配置选项
+`CopyFeature` 用于控制附件复制时的行为：
+- `setCreatorId(Long)` - 设置创建人ID
+- `setUseCurrentUserAsCreator(boolean)` - 是否使用当前用户作为创建人
+- `setCopyLastModifyTime(boolean)` - 是否复制最后修改时间
+- `setUseCurrentUserAsModifier(boolean)` - 是否使用当前用户作为修改人
+- `setFileSource(Integer)` - 设置文件来源
+- `setClearDesc(boolean)` - 是否清除描述
+
+## 实践建议
+1. **优先使用面板复制**: 不要手动解析附件子表获取 URL 拼接。使用 `copyToPanel` 最稳健，且性能最优。
+2. **区分正式区与临时区**: 前端上传的文件位于临时区，如果不调用 `bind` 绑定到单据，系统会在一定时间后自动清理。
+3. **文件名转义**: 处理含中文字符的文件名时，必须确认编码环境，防止出现乱码。
+4. **流关闭**: `download` 方法返回的 InputStream 必须由调用方关闭，建议使用 try-with-resources。
+
+## 常见坑位
+1. **物理删除误伤**: `physicDelete` 会立刻销毁物理文件，如果该文件被多个单据引用，可能导致其他单据附件失效。
+2. **下载 URL 超时**: 直接将 `download` 获取的 InputStream 返回前端时，如果流未及时关闭，可能导致连接池溢出。
+3. **附件面板标识错误**: `copyToPanel` 的参数是面板的 **Key**，而非字段 Key，请在设计器属性栏确认。
+4. **流未关闭**: 忘记关闭 `download` 返回的 InputStream 会导致文件句柄泄露或底层连接池耗尽。

package/vendor/kingdee-skills/ok-cosmic/references/adv/botp-convert.md

@@ -0,0 +1,98 @@
+# 单据转换与下推 (BotpUtils & PushResult)
+
+## TL;DR
+- 适用：下推、选单、来源追踪和转换结果处理。
+- 先抓：默认优先 `BotpUtils` / `PushResult`，不要先手写原生转换服务调用。
+- 跳转：只是保存/提交/审核改读 `operate-chain.md`；只是转换插件事件再读 `base/plugin/plugin-botp.md`。
+- 继续读全文：当你要确认上拉、链路追踪或后台自动下推模板时。
+
+## 概述
+单据下推（Push）与转换（Convert）是苍穹实现业务流转（如订单下推入库）的核心机制。`BotpUtils` (位于 `kd.cd.common.util`) 对原生的转换服务进行了深度简化，支持一键下推并保存、下推并显示界面、上拉数据以及多层级的正/反向链路追踪。
+
+> **适用边界**
+> ✅ 适用：下推/选单/来源追踪/转换结果处理。
+> ❌ 不适用：单纯的操作执行（保存/审核）请用 `OpUtils`；转换插件的事件扩展请用 `ConvertPlugInTemplate`。
+
+## 核心类
+- **`kd.cd.common.util.BotpUtils`**: **下推核心工具类**。
+- **`kd.cd.common.util.PushResult`**: 下推结果封装对象，可通过 `getPks()`、`getDatapacks()`、`getSingleDataPack()` 获取结果，并通过 `failThenThrow()` 直接抛出失败详情。
+- **`kd.bos.entity.botp.runtime.ConvertOperationResult`**: 原生转换结果。
+
+## 常用 API 方法
+
+### 1. 下推操作 (BotpUtils)
+- `pushAndSave(String sourceEntityId, String targetEntityId, Object srcPkValue, String ruleId)`: 一对一后台下推并自动保存的简版重载。
+- `pushAndSave(String sourceEntityId, String targetEntityId, Object srcPkValue, Map<String, List<Long>> entryMapping, String ruleId, Consumer<PushArgs> consumer)`: **最常用**。一对一后台下推并自动保存。
+- `pushNoSave(String sourceEntityId, String targetEntityId, Object srcPkValue, String ruleId)`: 一对一后台下推但不保存的简版重载。
+- `pushNoSave(String sourceEntityId, String targetEntityId, Object srcPkValue, Map<String, List<Long>> entryMapping, String ruleId, Consumer<PushArgs> consumer)`: 下推生成内存对象，不持久化。
+- `push(boolean autoSave, String sourceEntityId, String targetEntityId, List<ListSelectedRow> selectedRows, String ruleId, Consumer<PushArgs> consumer)`: 基于 `selectedRows` 的通用下推入口。
+- `push(boolean autoSave, PushArgs pushArgs)`: 通用下推方法。
+- `pushAndShowTarget(IFormView view, boolean autoSave, String sourceEntityId, String targetEntityId, List<ListSelectedRow> selectedRows, String ruleId, Consumer<PushArgs> consumer)`: 按选择行下推并直接打开目标单。
+- `pushAndShowTarget(IFormView view, boolean autoSave, PushArgs pushArgs)`: 下推并直接在界面弹出目的单。
+
+### 2. 上拉操作 (BotpUtils)
+- `drawToBill(IFormView view, String sourceEntityId, Collection<ListSelectedRow> selectRows, String ruleId, Consumer<DrawArgs> consumer)`: 下拉数据至当前单据。
+
+### 3. 链路追踪 (BotpUtils)
+- `findAllTargetBills(String targetEntityId, String entityId, Collection<Long> pkValues)`: 正向查找生成的全量目的单，按当前单据主键分组。
+- `findAllTargetBillsFlat(String targetEntityId, String entityId, Collection<Long> pkValues)`: 正向查找，不分组。
+- `findAllSourceBills(String sourceEntityId, String entityId, Collection<Long> pkValues)`: 反向查找来源单据，按当前单据主键分组。
+- `findAllSourceBillsFlat(String sourceEntityId, String entityId, Collection<Long> pkValues)`: 反向查找，不分组。
+- `findDirectTargetBills(String targetEntityId, String entityId, Collection<Long> pkValues)`: 查找直接下游（第一层）。
+- `findDirectSourceBills(String sourceEntityId, String entityId, Collection<Long> pkValues)`: 查找直接上游（第一层）。
+
+### 4. 辅助方法
+- `loadTargetEntities(ConvertOperationResult result)`: 从下推结果中加载完整的目的单 DynamicObject。
+- `getConvertFailMsg(ConvertOperationResult result)`: 获取下推失败信息详情。
+- `getDefaultRuleId(String sourceEntityId, String targetEntityId)`: 获取默认转换规则ID（启用状态）。
+- `buildSelectedRows(Map<Object, Map<String, List<Long>>> billData)`: 构建下推选择行信息。
+- `PushResult.failThenThrow()`: 下推失败时直接抛出 `PushConvertFailureException`。
+- `PushResult.getDatapacks()`: 获取目标单数据包；自动保存场景下会懒加载。
+- `PushResult.getSingleDataPack()`: 获取单张目标单数据包。
+
+## 示例代码
+
+### 后台自动下推模板
+```java
+package kd.cd.common.demo;
+
+import kd.cd.common.util.BotpUtils;
+import kd.cd.common.util.PushResult;
+
+public class PushDemo {
+    public void autoPush(String sourceFormId, String targetFormId, Object sourcePk) {
+        // 1. 下推并保存
+        PushResult result = BotpUtils.pushAndSave(sourceFormId, targetFormId, sourcePk, null);
+        result.failThenThrow();
+
+        // 2. 获取生成的单据主键
+        Object[] targetPks = result.getPks();
+
+        // 3. 需要时可继续读取完整数据包
+        result.getSingleDataPack();
+    }
+}
+```
+
+### 链路追踪示例
+```java
+public void traceBills(String entityId, Collection<Long> pkValues) {
+    // 查询所有下游目标单（按当前单据主键分组）
+    Map<Long, Map<String, Set<Long>>> targetBills = BotpUtils.findAllTargetBills(entityId, pkValues);
+
+    // 查询特定类型的直接上游源单
+    Map<Long, Set<Long>> sourceBills = BotpUtils.findDirectSourceBills("pm_purorderbill", entityId, pkValues);
+}
+```
+
+## 实践建议
+1. **RuleId 获取**: 建议通过 `BotpUtils.getDefaultRuleId` 获取单据间的默认规则，避免硬编码。
+2. **分录下推**: 使用 `entryMapping` 参数可精确控制需要下推的分录行。
+3. **加载明细**: `loadTargetEntities` 获取的对象包含分录的全量数据。
+4. **链路追踪**: 使用 `findDirectXxx` 方法仅查询直接关联，`findAllXxx` 方法递归查询全量关联。
+
+## 常见坑位
+1. **规则未分配**: 如果返回空结果，优先检查"转换规则"是否在目标组织中已发布。
+2. **分录转换缺失**: 如果 RuleId 中未配置分录，下推后的单据将只有表头。
+3. **主键精度丢失**: `Object` 类型的 ID 在跨系统传递时需注意 JS 的数字精度限制（Long -> String）。
+4. **参数顺序**: 注意 pushAndSave/pushNoSave 的参数顺序是 `(sourceEntityId, targetEntityId, ...)` 而非旧版的 `(targetId, ruleId, sourceIds, orgId)`。

package/vendor/kingdee-skills/ok-cosmic/references/adv/dynamic-object.md

@@ -0,0 +1,113 @@
+# 动态对象处理全览 (DynamicObject & DynamicObjectUtils)
+
+## TL;DR
+- 适用：`DynamicObject` 安全取值、分录提取、批量扁平化和序列化。
+- 先抓：优先 `DynamicObjectUtils`，避免原生 `get()` + 强转连写导致空指针和类型错误。
+- 跳转：看字段结构/属性元数据改读 `entity-metadata.md`；查询取数改读 `query-dataset.md`。
+- 继续读全文：当你要写深路径取值、批量提取或克隆/状态判断代码时。
+
+## 概述
+`DynamicObject` 是苍穹数据的核心载体（内存中的数据包）。`DynamicObjectUtils` (位于 `kd.cd.common.util`) 提供了对这些对象及其集合的高效、安全操作。由于原生 API 容易引发 `NullPointerException` 或类型转换异常，推荐一律使用工具类进行数据存取。
+
+> **适用边界**
+> ✅ 适用：DynamicObject 安全取值/批量提取/集合操作。
+> ❌ 不适用：元数据结构解析请用 `entity-metadata.md`；查询构建请用 `query-dataset.md`。
+
+## 核心类
+- **`kd.bos.dataentity.entity.DynamicObject`**: 基础数据载体（单对象）。
+- **`kd.bos.dataentity.entity.DynamicObjectCollection`**: 动态对象集合（通常用于表示单据的分录）。
+- **`kd.cd.common.util.DynamicObjectUtils`**: **核心工具类**。
+
+## 常用 API 方法
+
+### 1. 安全取值与设置 (单对象)
+- `safeGetValue(DynamicObject dyn, String propKey)`: **最常用**。安全获取字段值，字段不存在时返回 null。
+- `safeSetValue(DynamicObject dyn, String propKey, Object value)`: 安全设置值，字段不存在时不抛异常。
+- `nullSafeGet(DynamicObject dyn, String field)`: 空安全获取字段值。
+- `getPkValue(DynamicObject dyn)`: 获取主键。
+- `containsKey(DynamicObject dyn, String key)`: 判断是否包含某字段属性。
+- `containsKey(DynamicObjectCollection coll, String key)`: 判断集合是否包含某字段。
+
+### 2. 扁平提取 (深层路径)
+- `flatSetOf(DynamicObject dyn, String expr)`: **深路径提取**。扁平列出动态对象中某字段的所有值，收集为 Set。示例：`"entry.subentry.field"`。
+- `flatListOf(DynamicObject dyn, String expr)`: 同上，返回 List。
+
+### 3. 批量属性提取 (集合/分录)
+- `arrayOfIds(DynamicObject[] array)`: 快速提取数组内所有对象的主键 ID。
+- `arrayOfIds(Collection<DynamicObject> coll)`: 快速提取集合内所有对象的主键 ID。
+- `setOfIds(DynamicObject[] array)`: 提取主键 ID，返回 Set。
+- `setOfIds(Collection<DynamicObject> coll)`: 提取主键 ID，返回 Set。
+- `setOf(Collection<DynamicObject> coll, String field)`: 提取并去重某一属性。
+- `listOf(Collection<DynamicObject> coll, String field)`: 提取属性，返回列表。
+- `sumOf(Collection<DynamicObject> coll, String decimalField)`: 对数值字段执行内存汇总。
+
+### 4. 数据集转换与序列化
+- `toDataSet(DynamicObjectCollection coll)`: 集合转数据集（DataSet）以执行高性能计算。
+- `toDataSet(DynamicObjectCollection coll, String... selectFields)`: 选择字段转换。
+- `fromDataSet(DataSet ds)`: 将计算结果转换回对象集合。
+- `serialize(DynamicObject... dynArr)`: 序列化动态对象。
+- `deSerialize(String serialized, DynamicObjectType dt)`: 反序列化动态对象。
+
+### 5. 对象创建与克隆
+- `clone(DynamicObject dyn)`: 深度克隆数据对象，默认清除主键值。
+- `newDynamicObject(String formId)`: 根据表单标识生成新的动态对象。
+- `newDynamicObject(DynamicObjectType dt)`: 根据类型生成新的动态对象。
+
+### 6. 属性信息
+- `getPropKeys(DynamicObject dyn)`: 获取属性标识集。
+- `getPropKeys(DynamicObjectCollection coll)`: 获取集合属性标识集。
+- `dump(DynamicObject dyn)`: 转储 DynamicObject 为 Map。
+
+### 7. 状态判断
+- `isNewCreate(DynamicObject dyn)`: 判断数据包是否为新增（不来源于数据库）。
+
+## 示例代码
+
+### 安全链式取值与分录统计
+```java
+package kd.cd.common.demo;
+
+import kd.cd.common.util.DynamicObjectUtils;
+import kd.bos.dataentity.entity.DynamicObjectCollection;
+import java.math.BigDecimal;
+
+public class DataDemo {
+    public void process(DynamicObject bill) {
+        // 1. 安全获取基础资料名称，无视空指针风险
+        String orgName = DynamicObjectUtils.nullSafeGet(bill, "org.name");
+
+        // 2. 统计分录中所有行特定金额之和
+        DynamicObjectCollection entry = bill.getDynamicObjectCollection("billentry");
+        BigDecimal totalAmount = DynamicObjectUtils.sumOf(entry, "amount");
+
+        // 3. 提取分录中所有物料ID
+        Set<Object> materialIds = DynamicObjectUtils.setOf(entry, "material.id");
+
+        // 4. 深路径扁平提取
+        Set<Object> allSubValues = DynamicObjectUtils.flatSetOf(bill, "entry.subentry.field");
+    }
+}
+```
+
+### 判断单据是否新增
+```java
+public void checkBillStatus(DynamicObject bill) {
+    if (DynamicObjectUtils.isNewCreate(bill)) {
+        // 新增单据，尚未保存到数据库
+    } else {
+        // 已存在的单据
+    }
+}
+```
+
+## 实践建议
+1. **优先使用 Path 取值**: 在处理多级关联（如单据->物料->规格型号）时，使用 `flatSetOf("material.model")` 而不是逐层 `.get(...)`。
+2. **批量查询原则**: 严禁在分录循环中查询数据库。应先提取分录中所有 ID（使用 `setOfIds`），执行一次批量查询后，再进行内存匹配。
+3. **内存字段管理**: 动态添加的字段在使用 `toDataSet` 前需确保已注册在元数据中。
+4. **序列化场景**: `serialize`/`deSerialize` 适用于跨进程传递或缓存存储。
+
+## 常见坑位
+1. **类型强转错误**: 从 `safeGetValue` 获取的值必须根据元数据定义的字段类型进行强转（如 `Long`, `BigDecimal`, `Date`），严禁凭经验判断。
+2. **脏数据未提交**: 手动修改 `DynamicObject` 的值后，如果不希望触发操作插件的变更逻辑，需通过 `clearDirty` 控制。
+3. **集合引用失效**: 对 `DynamicObjectCollection` 执行 `clear()` 后，之前获取的引用将变为空，操作前需确认状态。
+4. **克隆后主键**: `clone` 方法默认清除主键值，如需保留主键请手动设置。

package/vendor/kingdee-skills/ok-cosmic/references/adv/entity-metadata.md

@@ -0,0 +1,123 @@
+# 实体元数据解析工具 (EntityUtils)
+
+## TL;DR
+- 适用：查实体 key、字段属性、分录结构以及下拉/枚举元数据。
+- 先抓：用 `EntityUtils` 拿实体标识、属性对象、分录字段和 `Combo` 信息。
+- 跳转：操作数据值本身改读 `dynamic-object.md`；弹性域解析改读 `flex-prop.md`。
+- 继续读全文：当你要写元数据驱动代码、动态取字段或调试实体结构时。
+
+## 概述
+元数据（Metadata）驱动是苍穹的核心设计。`EntityUtils` (位于 `kd.cd.common.entity`) 对原生的实体元数据进行了深层封装，提供了获取实体标识、属性解析、下拉列表（Combo）以及分录结构的极简 API。旨在减少元数据读取时的深路径嵌套。
+
+> **适用边界**
+> ✅ 适用：获取实体标识/属性解析/下拉枚举/分录结构。
+> ❌ 不适用：DynamicObject 数据操作请用 `dynamic-object.md`；弹性域字段解析请用 `flex-prop.md`。
+
+## 核心类
+- **`kd.cd.common.entity.EntityUtils`**: **元数据解析核心工具类**。
+- **`kd.bos.entity.MainEntityType`**: 苍穹单据主实体元数据。
+- **`kd.bos.dataentity.metadata.IDataEntityProperty`**: 实体属性元数据。
+
+## 常用 API 方法
+
+### 1. 实体标识与关键标识
+- `getEntityId(String formId)`: **最常用**。根据表单标识获取其关联的数据实体名。
+- `getPrimaryKey(String formId)`: 获取实体的 ID 字段 Key（通常为 "id"）。
+- `getBillNoKey(String formId)`: 获取实体的单据编号字段 Key（如 "billno"）。
+- `getBillStatusKey(String formId)`: 获取实体的单据状态字段 Key（如 "billstatus"）。
+- `getPkAndBillnoKey(String formId)`: 获取主键与单据编码字段标识（Pair）。
+
+### 2. 属性解析与检索
+- `getProperty(String formId, String field)`: 获取特定属性的元数据定义（单据头&单据体）。
+- `getProperty(MainEntityType mainType, String field)`: 从主实体类型获取属性。
+- `selectProperties(String formId, Predicate<IDataEntityProperty> predicate)`: 根据字段属性筛选字段。
+- `getAllProperties(String formId)`: 获取表单实体中所有字段属性映射。
+- `getEntryPropKeys(String formId, String entryKey)`: 获取分录包含的所有子字段 Key。
+- `getEntryProperties(String formId, String entryKey)`: 获取分录字段属性映射。
+- `getPropKeyWithPrefix(String formId, String field)`: 获取带父级前缀的字段标识（如 entry.subentry.field）。
+- `getParentPropKey(String formId, String field)`: 获取字段所属父级属性标识。
+
+### 3. 下拉与枚举
+- `getComboItemMap(String formId, String comboKey)`: 获取下拉列表的所有枚举值（值 -> 名称）。
+
+### 4. 类型与结构
+- `getMainEntityType(String formId)`: 获取主实体类型（兼容PC布局）。
+- `getDynamicObjectType(String formId)`: 获取动态对象类型。
+- `getDynamicObjectType(String formId, String selectProperties)`: 获取仅含部分字段属性的动态对象类型。
+- `getEntryType(String formId, String entryKey)`: 获取分录实体类型。
+- `getTableDefine(String formId)`: 获取表单实体表定义。
+
+### 5. 实体信息
+- `getChsName(String formId)`: 获取表单实体中文描述名。
+- `getAppId(String formId)`: 获取 AppId。
+- `getDBRoute(String formId)`: 获取实体数据库路由。
+- `getBaseDataQuoteType(String formId, String baseDataField)`: 获取基础资料引用类型。
+- `getAliasState(String formId, String field)`: 获取字段数据库字段状态。
+- `getLinkEntryRelation(String formId)`: 获取表单实体关联关系映射字段信息。
+
+### 6. 数据校验工具
+- `isEmptyPk(Object pkValue)`: **最常用**。安全判定单据主键是否为空（兼容 0L 或空字符串）。
+- `isNotEmptyPk(Object pkValue)`: 判定主键非空。
+- `checkNotEmptyPk(Object pkValue, String expr)`: 校验主键值非空，为空时抛出异常。
+
+### 7. 扁平提取（调试用）
+- `flatListValue(DynamicObject dataEntity, String field)`: 扁平列出主实体中某字段的所有值。
+- `peek(Object o)`: 预览实体结构（仅调试）。
+
+## 示例代码
+
+### 动态获取单据显示名
+```java
+package kd.cd.common.demo;
+
+import kd.cd.common.entity.EntityUtils;
+
+public class MetaDemo {
+    public void getInfo(String formId, Object pkValue) {
+        // 1. 获取实体标识
+        String entityId = EntityUtils.getEntityId(formId);
+
+        // 2. 获取主键和编号对应的 Key
+        String pkKey = EntityUtils.getPrimaryKey(formId);
+        String noKey = EntityUtils.getBillNoKey(formId);
+
+        // 3. 获取下拉列表的中文字符
+        Map<String, String> items = EntityUtils.getComboItemMap(formId, "billstatus");
+
+        // 4. 获取实体中文名
+        String chsName = EntityUtils.getChsName(formId);
+
+        // 5. 校验主键非空
+        if (EntityUtils.isEmptyPk(pkValue)) {
+            // 单据尚未保存
+        }
+    }
+}
+```
+
+### 获取分录字段信息
+```java
+public void analyzeEntry(String formId, String entryKey) {
+    // 获取分录所有字段标识
+    Set<String> fieldKeys = EntityUtils.getEntryPropKeys(formId, entryKey);
+
+    // 获取分录字段属性映射
+    Map<String, IDataEntityProperty> properties = EntityUtils.getEntryProperties(formId, entryKey);
+
+    // 获取带前缀的字段标识
+    String fullKey = EntityUtils.getPropKeyWithPrefix(formId, "entry.field");
+    // 结果: "entry.field" 或 "entity.entry.field"
+}
+```
+
+## 实践建议
+1. **优先使用 getBillNoKey**: 在通用插件中获取单据编号，不要写死 "billno"，以应对客户在设计器中对字段标识的调整。
+2. **分录字段前缀**: 拼接分录字段名时，建议使用 `getPropKeyWithPrefix` 自动补全前缀。
+3. **缓存重用**: 对于元数据的频繁读取，建议在方法内部缓存 `MainEntityType` 的引用。
+4. **主键判空**: 使用 `isEmptyPk` 而非 `== null`，因为苍穹主键默认为 0L。
+
+## 常见坑位
+1. **基础资料扩展失效**: 对于动态扩展的字段，如果扩展未发布，`getProperty` 会返回 null。
+2. **区分 FormId 与 EntityId**: 表单标识（UI）和实体标识（DB）有时不同（如基础资料扩展），调用时务必核实参数。
+3. **主键默认值**: 苍穹主键默认为 0L，使用 `isEmptyPk` 可以精准识别单据是否已入库。
+4. **属性对象共享**: `getProperty` 返回的对象是全局缓存共用的，禁止对其进行 set 操作。

package/vendor/kingdee-skills/ok-cosmic/references/adv/event-lifecycle.md

@@ -0,0 +1,184 @@
+# 插件事件生命周期图
+
+## TL;DR
+
+- 适用：你已经命中插件类型，但不确定事件触发顺序、该把逻辑放在哪个阶段时，先读本页。
+- 先抓：先看对应插件类型的生命周期图，再看“放置策略速查”。
+- 边界：本页只解决“事件先后顺序 + 适合放什么逻辑”；具体方法签名、原生事件全集仍回各插件文档确认。
+- 跳转：
+  - 表单 / 单据：`plugin-base.md`、`plugin-form.md`、`plugin-bill.md`
+  - 列表：`plugin-base.md`、`plugin-list.md`
+  - 操作：`plugin-base.md`、`plugin-operation.md`
+  - 转换：`plugin-botp.md`
+  - 反写：`plugin-writeback.md`
+
+## 一页总原则
+
+- `initialize`：做轻量初始化；不要注册监听，不要做 UI 可见性/启用状态逻辑。
+- `registerListener`：只注册监听；不要依赖已绑定的数据，不要在这里 `model.getValue(...)`。
+- `createNewData` / `loadData` / `afterLoadData`：做数据包初始化、补字段、加载后整理。
+- `beforeBindData` / `afterBindData`：处理绑定前后和 UI 状态；不要在绑定阶段改数据对象。
+- 操作插件：先区分事务前、事务中、事务后；明确规则优先放校验器。
+- 转换 / 反写插件：先看当前是在“转换阶段”还是“回写阶段”，再判断事件位置。
+
+## 表单 / 单据插件
+
+单据插件继承动态表单生命周期；已有单据更常落在 `loadData/afterLoadData`，新建单据更常落在 `createNewData/afterCreateNewData`。
+
+```mermaid
+flowchart TD
+    A["preOpenForm"] --> B["initialize"]
+    B --> C["registerListener"]
+    C --> D{"新建还是加载已有数据"}
+    D -->|新建| E["createNewData"]
+    E --> F["afterCreateNewData"]
+    D -->|加载已有| G["loadData"]
+    G --> H["afterLoadData"]
+    F --> I["beforeBindData"]
+    H --> I
+    I --> J["afterBindData"]
+    J --> K["propertyChanged / click / beforeDoOperation / afterDoOperation"]
+    K --> L["beforeClosed"]
+    L --> M["destory"]
+```
+
+### 放置策略
+
+| 事件 | 适合放什么 | 不要放什么 |
+|---|---|---|
+| `initialize` | 轻量初始化、上下文准备 | 监听注册、UI 状态逻辑 |
+| `registerListener` | `add*Listener`、监听器注册 | `model.getValue(...)`、联动赋值 |
+| `createNewData` | 新建默认值、数据包初始化 | 控件可见性 / 启用状态 |
+| `afterLoadData` | 已有单据加载后整理 | 事务级校验 |
+| `beforeBindData` / `afterBindData` | UI 刷新前后、界面状态控制 | `setValue(...)`、改数据包 |
+| `propertyChanged` | 字段联动、即时补值 | 跨事务级复杂状态流转 |
+
+## 列表插件
+
+列表插件没有 `createNewData/loadData` 这一段，重点是列表绑定前后和列表交互事件。
+
+```mermaid
+flowchart TD
+    A["preOpenForm"] --> B["initialize"]
+    B --> C["registerListener"]
+    C --> D["beforeBindData"]
+    D --> E["afterBindData"]
+    E --> F["itemClick / listRowClick / setFilter / beforeShowBill"]
+```
+
+### 放置策略
+
+| 事件 | 适合放什么 | 不要放什么 |
+|---|---|---|
+| `registerListener` | 列表按钮、行点击、超链接等监听注册 | 依赖已选中行的数据处理 |
+| `beforeBindData` | 绑定前过滤准备 | 直接改行数据对象 |
+| `afterBindData` | 列表展示、过滤容器状态协同 | 批量持久化写库 |
+| `itemClick` / `listRowClick` | 批量动作入口、打开页面、交互编排 | 事务内核心业务逻辑 |
+
+## 操作插件
+
+操作插件运行在服务端事务链路，要先分清“字段准备”“校验”“事务内处理”“事务后处理”。
+
+```mermaid
+flowchart TD
+    A["onPreparePropertys"] --> B["onAddValidators"]
+    B --> C["beforeExecuteOperationTransaction"]
+    C --> D["beginOperationTransaction"]
+    D --> E["endOperationTransaction"]
+    E --> F["afterExecuteOperationTransaction"]
+    F --> G["onReturnOperation"]
+    D --> R["rollbackOperation"]
+```
+
+### 放置策略
+
+| 事件 | 适合放什么 | 不要放什么 |
+|---|---|---|
+| `onPreparePropertys` | 补操作所需字段 | 业务校验、状态写回 |
+| `onAddValidators` | 注册校验器、前置阻断 | 事务内数据修改 |
+| `beforeExecuteOperationTransaction` | 最后整理、轻量兜底校验 | 大量规则校验堆叠 |
+| `beginOperationTransaction` / `endOperationTransaction` | 事务内同步处理、状态更新 | 事务后通知类逻辑 |
+| `afterExecuteOperationTransaction` | 消息通知、日志、外部后续动作 | 再修改主单据事务数据 |
+
+## 转换插件
+
+转换插件关注源单取数、目标单创建、字段映射和关联关系生成。先区分“下推/选单业务动作”还是“转换规则扩展”。
+
+```mermaid
+flowchart TD
+    A["initVariable"] --> B["afterBuildQueryParemeter"]
+    B --> C["beforeBuildRowCondition"]
+    C --> D["afterBuildRowCondition"]
+    D --> E["beforeGetSourceData"]
+    E --> F["afterGetSourceData"]
+    F --> G["beforeBuildGroupMode"]
+    G --> H["beforeCreateTarget"]
+    H --> I["afterCreateTarget"]
+    I --> J["afterFieldMapping"]
+    J --> K["afterBizRule"]
+    K --> L["beforeCreateLink"]
+    L --> M["afterCreateLink"]
+    M --> N["afterBuildDrawFilter"]
+    N --> O["afterConvert"]
+```
+
+### 放置策略
+
+| 事件 | 适合放什么 | 不要放什么 |
+|---|---|---|
+| `initVariable` | 识别下推/选单上下文 | 直接写目标单字段 |
+| `beforeGetSourceData` / `afterGetSourceData` | 源单过滤、补第三方数据 | 映射完成后的兜底修正 |
+| `afterFieldMapping` | 映射后补值 | 过早取消关联 |
+| `afterBizRule` | 规则执行后的最终修正 | 大量外部 IO |
+| `beforeCreateLink` / `afterCreateLink` | 调整上下游关联关系 | 随意取消导致追踪断裂 |
+
+## 反写插件
+
+反写插件是 BOTP 回写阶段的专用链路，不等于一般意义上的“更新关联实体”。
+
+```mermaid
+flowchart TD
+    A["preparePropertys"] --> B["beforeTrack"]
+    B --> C["beforeCreateArticulationRow"]
+    C --> D["beforeExecWriteBackRule"]
+    D --> E["afterCalcWriteValue"]
+    E --> F["beforeReadSourceBill"]
+    F --> G["afterReadSourceBill"]
+    G --> H["afterCommitAmount"]
+    H --> I["beforeExcessCheck"]
+    I --> J["afterExcessCheck"]
+    J --> K["beforeCloseRow"]
+    K --> L["afterCloseRow"]
+    L --> M["beforeSaveTrans"]
+    M --> N["beforeSaveSourceBill"]
+    N --> O["afterSaveSourceBill"]
+    O --> P["finishWriteBack"]
+    N --> R["rollbackSave"]
+```
+
+### 放置策略
+
+| 事件 | 适合放什么 | 不要放什么 |
+|---|---|---|
+| `preparePropertys` / `beforeReadSourceBill` | 补字段准备 | 直接做反写结果修正 |
+| `beforeExecWriteBackRule` / `afterCalcWriteValue` | 控制规则是否执行、修正反写值 | 事务补偿逻辑 |
+| `beforeExcessCheck` / `afterExcessCheck` | 超额校验、提示策略 | 一刀切取消全部检查 |
+| `beforeSaveTrans` / `rollbackSave` | 外部补偿、第三方一致性闭环 | 忽略失败回滚 |
+| `finishWriteBack` | 释放网控、缓存句柄等资源 | 留资源不释放 |
+
+## 常见错位速查
+
+| 误放位置 | 常见后果 | 正确位置 |
+|---|---|---|
+| 在 `initialize()` 中注册监听或写 UI 状态 | 生命周期过早，逻辑失效或错时 | `registerListener` / `afterBindData` |
+| 在 `registerListener` 中读模型值 | 数据尚未绑定 | `afterBindData` / `propertyChanged` |
+| 在 `beforeBindData` / `afterBindData` 中 `setValue(...)` | 绑定阶段改数据，容易出错 | `createNewData` / `afterLoadData` / `propertyChanged` / 保存前 |
+| 在 UI 插件中承担事务级校验或状态流转 | 与服务端状态机冲突 | 操作插件 |
+| 把“业务上说反写”直接理解成反写插件 | 场景误判 | 先判断是不是普通实体更新，只有明确插件语义时才走反写插件 |
+
+## 继续读取建议
+
+- 只是不确定“该放哪个事件”：本页足够。
+- 要确认方法签名：回 [plugin-base.md](plugin-base.md) 或对应原生插件文档。
+- 要确认具体控件/字段联动做法：回对应 `form-utils.md`、`plugin-form.md`、`plugin-bill.md`。
+- 要确认转换 / 反写事件细节：回 `plugin-botp.md`、`plugin-writeback.md`。