kcode-pi 0.1.0

package/vendor/kingdee-skills/ok-cosmic/references/adv/flex-prop.md

@@ -0,0 +1,114 @@
+# 弹性域自动解析工具 (FlexPropUtils)
+
+## TL;DR
+- 适用：把弹性域 ID 批量解析成结构化键值，而不是直接读 `flex_field*`。
+- 先抓：先确认 `FlexType`，再用 `FlexPropUtils` 做批量解析和结果映射。
+- 跳转：普通字段/基础资料引用不要停在本页，分别去元数据或基础资料查询路径。
+- 继续读全文：当你要处理多行分录弹性域、批量解析或配置加载方式时。
+
+## 概述
+弹性域是苍穹平台提供的高度扩展字段机制。物理上它们以扁平字段（如 `flex_field1`）存储。`FlexPropUtils` (位于 `kd.cd.common.util`) 封装了复杂的映射关系，支持将弹性域 ID 批量解析为结构化的 `Map` 键值对，大幅减少代码量并提高可读性。
+
+> **适用边界**
+> ✅ 适用：弹性域 ID 解析为结构化键值对。
+> ❌ 不适用：普通实体字段读取请用 `entity-metadata.md`；基础资料引用请用 `BaseDataServiceHelper`。
+
+## 核心类
+- **`kd.cd.common.util.FlexPropUtils`**: **弹性域处理核心工具类**。
+- **`kd.cd.common.util.FlexType`**: 弹性域类型枚举。
+
+## FlexType 枚举
+弹性域类型决定了字段映射关系的来源：
+- **`ACT`**: 核算维度
+- **`AUX`**: 辅助属性
+
+## 常用 API 方法
+
+### 1. 弹性域自动解析
+- `parseSingle(DynamicObject flexEntity, FlexType flexType)`: 解析单个弹性域实体，返回值映射。
+- `parse(Collection<DynamicObject> flexEntities, FlexType flexType)`: 批量解析对象集合，返回按主键分组的值映射。
+- `parseByFlexIds(Collection<Object> flexIds, FlexType flexType)`: 直接根据弹性域的主键 ID 进行批量解析，返回按主键分组的值映射。
+
+### 2. 查询方法
+- `queryJsonByFlexIds(Collection<Object> flexIds, FlexType flexType)`: 批量查询并返回弹性域主键映射其 JSON 字符串。
+
+### 3. 配置加载
+- `loadFieldRelationAsMap(FlexType flexType)`: 加载弹性域标识与物理字段名的映射关系。
+
+## 示例代码
+
+### 解析单据中的辅助属性弹性域
+```java
+package kd.cd.common.demo;
+
+import kd.cd.common.util.FlexPropUtils;
+import kd.cd.common.util.FlexType;
+import kd.bos.dataentity.entity.DynamicObject;
+import java.util.Map;
+import java.util.Collection;
+
+public class FlexDemo {
+    public void demo(DynamicObject bill) {
+        // 1. 获取弹性域实体
+        DynamicObject flexEntity = bill.getDynamicObject("flex_field");
+
+        // 2. 解析辅助属性 (AUX) 类型的弹性域
+        Map<String, Object> values = FlexPropUtils.parseSingle(flexEntity, FlexType.AUX);
+
+        // 3. 根据字段 Key 获取解析后的业务值
+        Object color = values.get("flex_color");
+        Object size = values.get("flex_size");
+    }
+}
+```
+
+### 批量解析弹性域
+```java
+public void batchDemo(Collection<Object> flexIds) {
+    // 根据弹性域主键批量解析
+    Map<Object, Map<String, Object>> result = FlexPropUtils.parseByFlexIds(flexIds, FlexType.AUX);
+
+    // 遍历结果
+    for (Map.Entry<Object, Map<String, Object>> entry : result.entrySet()) {
+        Object flexId = entry.getKey();
+        Map<String, Object> fieldValues = entry.getValue();
+
+        // 获取具体字段值
+        Object color = fieldValues.get("flex_color");
+    }
+}
+```
+
+### 从分录中提取弹性域值
+```java
+public void extractFromEntry(DynamicObject bill) {
+    DynamicObjectCollection entries = bill.getDynamicObjectCollection("entry");
+
+    // 收集所有弹性域ID
+    Set<Object> flexIds = DynamicObjectUtils.setOf(entries, "flex_field.id");
+
+    // 批量解析
+    Map<Object, Map<String, Object>> flexValues = FlexPropUtils.parseByFlexIds(flexIds, FlexType.AUX);
+
+    // 匹配分录数据
+    for (DynamicObject entry : entries) {
+        Object flexId = entry.get("flex_field.id");
+        Map<String, Object> values = flexValues.get(flexId);
+        if (values != null) {
+            // 使用解析后的值
+        }
+    }
+}
+```
+
+## 实践建议
+1. **优先使用解析工具**: 严禁直接通过 `get("flex_field1")` 这种方式硬编码逻辑。使用 `FlexPropUtils` 后代码具有更好的业务可读性。
+2. **区分 FlexType**: 当前 commons 中内置的类型为 `ACT`（核算维度）与 `AUX`（辅助属性），调用前必须确认所属类型。
+3. **批量处理性能**: 在分录处理逻辑中，建议收集所有弹性域 ID 后统一调用 `parseByFlexIds` 一次性完成转换。
+4. **空值判断**: 如果弹性域 ID 为空，解析结果通常会返回一个空的 Map。
+
+## 常见坑位
+1. **缓存更新延迟**: 如果在设计器中新发布了弹性域，后台工具类可能需要 10 分钟缓存 TTL 刷新后才能读取到新字段，生产环境可能需要刷新元数据缓存。
+2. **空值判断**: 如果弹性域 ID 为空，解析结果通常会返回一个空的 Map，需要进行空判断。
+3. **字段重复**: 不同类型的弹性域可能包含相同标识的字段，调用时必须确认 `FlexType`。
+4. **返回类型变化**: `parseSingle` 方法实际是从 `parse` 返回的 Map 中提取对应主键的值，注意返回类型是 `Map<String, Object>`。

package/vendor/kingdee-skills/ok-cosmic/references/adv/form-utils.md

@@ -0,0 +1,133 @@
+# 界面视图增强工具 (FormUtils)
+
+## TL;DR
+- 适用：表单/UI 控件启停、可见性、筛选、消息提示和视图信息读取。
+- 先抓：`FormUtils` 只服务有 UI 上下文的场景，优先解决控件和视图层问题。
+- 跳转：后台打开页面改读 `view-handler.md`；服务端事务逻辑改读操作插件文档。
+- 继续读全文：当你要确认控件定位、元数据读取或消息处理 API 时。
+
+## 概述
+界面交互逻辑是插件开发最耗时的地方。`FormUtils` (位于 `kd.cd.common.form`) 提供了一系列针对 `IFormView` 的快捷操作，能够极大简化控件控制、视图判定、消息处理等代码。
+
+> **适用边界**
+> ✅ 适用：表单控件启用/禁用/隐藏、UI 消息、视图判定。
+> ❌ 不适用：后台操作（无 UI 上下文）请用操作插件；后台打开表单/列表请用 `view-handler.md`。
+
+## 核心类
+- **`kd.cd.common.form.FormUtils`**: **界面工具核心类**。
+
+## API 方法全览
+
+### 1. 视图状态与属性
+- `getBillFormId(IFormView view)`: 获取当前表单标识（原标识，非实体标识）。
+- `getBillStatus(IFormView view)`: 获取单据审核状态。
+- `getParentViewNoPlugin(IFormView view)`: 获取无插件的父页面视图。
+- `getViewByPageId(String pageId)`: 通过 PageId 获取视图对象。
+- `getPluginInstance(String pageId, Class<T> clazz)`: 获取某个视图对象的某个插件实例。
+- `getAllPluginInstance(String pageId)`: 获取视图所有插件实例（调试用）。
+
+### 2. 列表控件
+- `getBillList(IFormView view)`: 获取列表控件（BillList）。
+- `getReportList(IFormView view)`: 获取报表列表控件（ReportList）。
+- `getListGrid(IFormView view, Class<T> clazz)`: 获取列表网格控件（泛型）。
+- `getListButtonKeys(String formId, boolean includeDropDown)`: 获取列表所有按钮标识与其对应操作映射。
+
+### 3. 控件筛选与检索
+- `getAllControls(IFormView view)`: 获取当前界面所有控件 Map。
+- `getAllControls(String formId)`: 获取表单中所有控件对象。
+- `getSubControls(Container container, boolean includeContainer)`: 获取容器内的子控件。
+- `selectControls(IFormView view, Predicate<Control> filter)`: 筛选表单控件。
+- `selectSubControls(Container container, Predicate<Control> filter)`: 筛选容器子控件。
+
+### 4. 表单标识获取
+- `getF7ListFormId(String billFormId)`: 获取列表F7标识。
+- `getListFormId(String billFormId)`: 获取列表标识。
+- `getMasterFormId(String extFormId)`: 根据拓展表单标识获取原表单标识。
+
+### 5. 元数据读取（数据库访问）
+- `readListMetadata(String billFormId)`: 查询列表元数据。
+- `readEntityMeta(String formId)`: 查询实体元数据。
+- `readEntityMetaAsMap(String formId, String... fieldKeys)`: 查询实体元数据字段映射。
+- `readFormMeta(String formId)`: 查询表单元数据。
+- `readFormMetaAsMap(String formId, String... fieldKeys)`: 查询表单元数据字段映射。
+
+### 6. UI 消息处理
+- `peekUIMsg(IFormView view)`: 预览视图前端提示信息（调试用）。
+- `getFlatUIMessages(IFormView view, boolean ignoreSuccessMsg)`: 提取视图前端提示信息。
+
+## 示例代码
+
+### 获取视图信息
+```java
+public void analyzeView(IFormView view) {
+    // 获取表单标识
+    String formId = FormUtils.getBillFormId(view);
+
+    // 获取单据状态
+    String status = FormUtils.getBillStatus(view);
+
+    // 获取父页面视图
+    IFormView parentView = FormUtils.getParentViewNoPlugin(view);
+}
+```
+
+### 控件筛选
+```java
+public void filterControls(IFormView view) {
+    String formId = FormUtils.getBillFormId(view);
+
+    // 获取所有控件
+    Map<String, Control> allControls = FormUtils.getAllControls(view);
+
+    // 筛选特定类型控件
+    Map<String, Control> entryGrids = FormUtils.selectControls(view, EntryGrid.class::isInstance);
+
+    // 获取列表按钮映射
+    Map<String, String> buttonOps = FormUtils.getListButtonKeys(formId, true);
+}
+```
+
+### 列表操作
+```java
+public void listOperation(IFormView listView) {
+    String pageId = listView.getPageId();
+
+    // 获取列表控件
+    BillList billList = FormUtils.getBillList(listView);
+
+    // 通过PageId获取视图
+    IFormView targetView = FormUtils.getViewByPageId(pageId);
+
+    // 获取插件实例
+    MyPlugin plugin = FormUtils.getPluginInstance(pageId, MyPlugin.class);
+}
+```
+
+### UI 消息提取
+```java
+public void checkMessages(IFormView view) {
+    // 获取所有非成功消息
+    List<String> messages = FormUtils.getFlatUIMessages(view, true);
+
+    // 预览所有UI消息（调试用）
+    Map<String, ?> uiMsg = FormUtils.peekUIMsg(view);
+}
+```
+
+## 实践建议
+1. **控件筛选**: 使用 `selectControls` 配合方法引用可以快速筛选特定类型控件，如 `EntryGrid.class::isInstance`。
+2. **父视图获取**: 在弹出界面中需要访问父页面时，使用 `getParentViewNoPlugin` 获取。
+3. **按钮映射**: `getListButtonKeys` 可用于动态判断按钮对应的操作，便于条件控制。
+4. **元数据读取**: `readXxxMeta` 系列方法会访问数据库，应避免高频调用。
+
+## 常见坑位
+1. **视图类型判断**: `getBillStatus` 仅适用于 `IBillView` 类型视图，对动态表单会抛异常。
+2. **PageId 时效**: `getViewByPageId` 获取的视图对象仅在当前会话有效。
+3. **控件 Key 区分**: 控件的 Key 与字段标识可能不同，需通过设计器确认。
+4. **元数据缓存**: `readXxxMeta` 方法每次访问数据库，建议缓存结果。
+
+## 相关工具类
+- **`kd.cd.core.util.SystemPropertyUtils`**: 系统配置工具
+  - `isProdEnv()`: 判定是否为生产环境
+  - `get(String key, String def)`: 获取配置项
+  - `getBoolean(String key, boolean def)`: 获取布尔配置项

package/vendor/kingdee-skills/ok-cosmic/references/adv/operate-chain.md

@@ -0,0 +1,159 @@
+# 业务操作与链式事务 (OpUtils & OperateChain)
+
+## TL;DR
+- 适用：保存、提交、审核、删除等单据操作，尤其是多步链式执行。
+- 先抓：单次操作优先 `OpUtils`，多步流程再上 `OperateChain`。
+- 跳转：下推/选单改读 `botp-convert.md`；纯插件事件时再读 `base/plugin/plugin-operation.md`。
+- 继续读全文：当你要确认事务边界、结果处理、回滚删除或字段准备写法时。
+
+## 概述
+业务单据的操作（保存、审核、下推等）是苍穹逻辑流转的基石。`OpUtils` (位于 `kd.cd.common.operate`) 提供了一键执行操作并反馈异常的原子 API；`OperateChain` 提供了流式 API 以执行复杂的操作组。本规范旨在确保单据操作的一致性与健壮性。
+
+> **适用边界**
+> ✅ 适用：需要连续执行多个操作（如保存→提交→审核）的链式场景。
+> ❌ 不适用：单次操作（仅 save / submit / audit）优先用 `OpUtils.executeOperateOrThrow`，更简洁。
+
+## OpUtils vs OperationServiceHelper 选择指南
+
+| 维度 | `OpUtils.executeOperateOrThrow` | `OperationServiceHelper.executeOperate` |
+|------|------|------|
+| **失败行为** | 自动抛出异常，回滚事务 | 返回 `OperationResult`，需自行检查 |
+| **适合场景** | 大多数业务场景：操作插件、表单插件、服务层 | MQ 消费、后台任务、失败后需回填错误信息 | 
+| **代码风格** | 一行调用，fail-fast | 需 if/else 分支处理成功/失败 |
+| **典型用法** | `OpUtils.executeOperateOrThrow("audit", entityId, pks)` | `OperationResult r = OperationServiceHelper.executeOperate("audit", entityId, pks, null); if (!r.isSuccess()) { String errMsg = OpUtils.getCompleteFailMsg(r); }` |
+
+> **简单原则**：“失败就应该回滚”用 `OpUtils`；“失败不回滚，我要自己处理”用 `OperationServiceHelper`，用 `OpUtils.getCompleteFailMsg(result)` 提取完整错误信息。
+
+## 核心基类/工具类
+- **`kd.cd.common.operate.OpUtils`**: **核心操作工具类**。
+- **`kd.cd.common.operate.chain.OperateChain`**: 链式操作器。
+- **`kd.cd.common.operate.chain.ChainStorage`**: 操作链数据存储。
+- **`kd.bos.entity.operate.result.OperationResult`**: 单据操作结果。
+
+## OpUtils API 方法
+
+### 1. 核心操作执行
+- `executeOperateOrThrow(String opKey, String entityId, DynamicObject[] dataEntities)`: **最常用**。执行操作，失败则抛出异常回滚事务。
+- `executeOperateOrThrow(String opKey, String entityId, Object[] pks)`: 根据主键执行操作。
+- `executeOperateOrThrow(String opKey, String entityId, DynamicObject[] dataEntities, OperateOption option)`: 带操作参数执行。
+- `executeOperateOrThrow(String opKey, String entityId, Object[] pks, OperateOption option)`: 带操作参数根据主键执行。
+- `throwIfFail(OperationResult result)`: 针对手动执行的操作结果进行校验并回滚。
+
+### 2. 回滚删除
+- `rollbackAndDelete(String entityId, Object pkValue)`: 如果后续逻辑失败，自动反审核并删除本单据。
+- `rollbackAndDelete(IFormView view)`: 基于视图的回滚删除。
+- `rollbackAndDelete(String entityId, Object pkValue, boolean requireNewTXForEachStage)`: 可控制事务隔离级别。
+
+### 3. 字段准备（操作插件用）
+- `prepareEntryFields(MainEntityType mainType, String... entryKeys)`: 一键生成包含分录所有子字段的列表（推荐）。
+- `prepareAllFields(MainEntityType mainType)`: 准备所有加载字段（仅推荐公共插件中使用）。
+
+### 4. 错误消息处理
+- `addErrorMessage(AbstractOperationServicePlugIn plugin, DynamicObject dataEntity, String message)`: 在操作插件中手动回填校验错误消息。
+- `addErrorMessage(AbstractOperationServicePlugIn plugin, DynamicObject dataEntity, String title, String message)`: 带标题的错误消息。
+- `addErrorMessage(AbstractOperationServicePlugIn plugin, DynamicObject dataEntity, String title, String errCode, String message)`: 完整错误消息。
+- `addValidatorErrorMsg(AbstractValidator validator, ExtendedDataEntity extDataEntity, String errCode, String message)`: 校验器错误消息。
+- `getCompleteFailMsg(OperationResult result)`: 提取全量分录中的所有错误消息。
+- `getChsName(String entityId, String opKey)`: 获取操作中文名。
+
+## OperateChain API 方法
+
+### 1. 工厂方法
+- `OperateChain.of(String entityId, Object pkValue)`: 根据实体标识和主键创建。
+- `OperateChain.of(DynamicObject dataEntity)`: 根据数据包创建。
+- `OperateChain.of(IFormView view)`: 根据视图创建。
+
+### 2. 链式操作方法
+- `save()`: 保存。
+- `save(OperateOption option)`: 带参数保存。
+- `submit()`: 提交。
+- `submit(OperateOption option)`: 带参数提交。
+- `submitNoWF()`: 提交（不触发工作流）。
+- `submitNoWF(OperateOption option)`: 带参数提交（不触发工作流）。
+- `audit()`: 审核。
+- `audit(OperateOption option)`: 带参数审核。
+- `unSubmit()`: 撤销提交。
+- `unSubmit(OperateOption option)`: 带参数撤销提交。
+- `unAudit()`: 反审核。
+- `unAudit(OperateOption option)`: 带参数反审核。
+- `delete()`: 删除。
+- `delete(OperateOption option)`: 带参数删除。
+- `operate(String opKey)`: 执行自定义操作。
+- `operate(String opKey, OperateOption option)`: 带参数执行自定义操作。
+
+### 3. 结果处理
+- `isSuccess()`: 判断操作链是否成功。
+- `storage()`: 获取操作链数据存储。
+- `failThenDelete()`: 失败后删除单据。
+- `failThenDeleteAndThrow()`: 失败后删除并抛异常。
+- `failThenDeleteAndThrow(String tip)`: 失败后删除并抛异常（带提示）。
+- `failThenThrow()`: 失败后抛异常。
+- `failThenThrow(String tip)`: 失败后抛异常（带提示）。
+
+### 4. 事务控制
+- `requireNewTXForEachStage(boolean require)`: 是否为每个操作阶段开启独立事务。
+- `getGlobalOptionControl()`: 获取全局操作参数控制器。
+
+## 示例代码
+
+### 静默审核单据模板
+```java
+package kd.cd.common.demo;
+
+import kd.cd.common.operate.OpUtils;
+
+public class OpDemo {
+    public void auditBill(String formId, Object pkId) {
+        // 1. 调用审核操作，失败将自动抛出带完整错误描述的异常
+        OpUtils.executeOperateOrThrow("audit", formId, new Object[]{pkId});
+    }
+}
+```
+
+### 链式操作模板
+```java
+public void chainOperation(DynamicObject dataEntity) {
+    // 链式操作：保存 -> 提交 -> 审核 -> 自定义操作
+    OperateChain chain = OperateChain.of(dataEntity);
+    if (!chain.save().submit().audit().operate("pay").isSuccess()) {
+        String errMsg = chain.storage().getErrMsg();
+        // 处理失败逻辑
+    }
+}
+```
+
+### 失败后删除
+```java
+public void operateWithRollback(String entityId, Object pkValue) {
+    // 创建单据后，后续操作失败则自动回滚删除
+    OperateChain chain = OperateChain.of(entityId, pkValue);
+    chain.save().submit().audit();
+    chain.failThenDelete();  // 如果前面操作失败，会自动回滚删除
+}
+```
+
+### 操作插件字段准备
+```java
+public class MyOperationPlugin extends AbstractOperationServicePlugInExt {
+    @Override
+    public void onPreparePropertys(PreparePropertysEventArgs e) {
+        // 加载分录所有字段(不推荐，只适用公共的操作插件，不要轻易尝试)
+        e.setFieldKeys(allFields());
+        // 或仅加载特定分录字段
+        e.setFieldKeys(entryFields("entry1", "entry2"));
+    }
+}
+```
+
+## 实践建议
+1. **优先使用 OrThrow**: 失败即回滚的场景，`executeOperateOrThrow` 是保持业务逻辑清晰的最佳方式。
+2. **需结果分支时用原生 API**: MQ 消费、后台任务等“失败不抛异常”场景，直接用 `OperationServiceHelper.executeOperate` 并检查 `OperationResult`。
+3. **多语言注意**: 所有的错误消息回填建议使用多语言属性。
+4. **事务范围**: 在操作插件中使用 `OpUtils` 时，其操作会自动被包在当前的数据库事务中。
+5. **链式操作**: 使用 `OperateChain` 可以优雅地处理连续操作，支持短路（前一操作失败后不再执行后续操作）。
+
+## 常见坑位
+1. **ID 数组错误**: `executeOperateOrThrow` 的 ID 数组必须类型一致（长整型或字符串），混合类型会导致单据找不到。
+2. **状态拦截**: 对已审核单据再次执行 `audit` 操作会返回失败，执行前应检查单据状态。
+3. **忽略结果检查**: 若直接使用 `OperationServiceHelper` 却不检查 `OperationResult`，会导致逻辑静默失败；应始终检查 `result.isSuccess()` 或使用 `OpUtils.throwIfFail(result)` 托底。
+4. **独立事务**: 开启 `requireNewTXForEachStage(true)` 后链路将失去"整体原子性"，需自行处理补偿逻辑。

package/vendor/kingdee-skills/ok-cosmic/references/adv/plugin-base.md

@@ -0,0 +1,218 @@
+# 扩展插件基类 (Plugin Base Extensions)
+
+## TL;DR
+- 适用：所有可继承 Ext 基类的表单、单据、列表、操作插件都应先读本页。
+- 先抓：选对 `Abstract*Ext` 基类，再复用已封装的日志、取值、监听注册和列表能力。
+- 跳转：BOTP 转换、反写、工作流、OpenAPI 这类无 Ext 封装场景不要停在本页。
+- 继续读全文：当你要确认 `@Override` 签名、生命周期或扩展方法全集时。
+
+## 概述
+扩展插件基类（Ext 系列）是基于金蝶苍穹原生插件类的二次封装。通过继承 `kd.cd.common.plugin` 下的基类，开发者可以直接获得统一的 `log` 对象，以及视图/元数据/取值等常用扩展方法。这是 `kd-cd-cosmic-commons` 框架的基础能力之一。
+
+> **适用边界**
+> ✅ 适用：所有需要继承 Ext 基类的表单/单据/列表/操作插件。
+> ❌ 不适用：BOTP 转换插件和反写插件没有 Ext 封装，直接用原生基类。
+
+## 核心基类
+
+### 基础插件
+- **`kd.cd.common.plugin.AbstractBasePlugInExt`**: 基础插件扩展。
+
+### 单据插件
+- **`kd.cd.common.plugin.AbstractBillPlugInExt`**: **单据插件首选**。封装了原生 `AbstractBillPlugIn`，内置 `log` 对象，实现 `IBillPluginExtension` 和 `BeforeF7SelectListener`。
+
+### 表单插件
+- **`kd.cd.common.plugin.AbstractFormPluginExt`**: 动态表单插件扩展。
+
+### 列表插件
+- **`kd.cd.common.plugin.AbstractListPluginExt`**: 列表插件扩展，强化了选中行（SelectedRows）的处理。
+
+### 操作插件
+- **`kd.cd.common.plugin.AbstractOperationServicePlugInExt`**: 操作插件扩展，简化了 `onPreparePropertys` 字段准备。
+
+### 校验器
+- **`kd.cd.common.plugin.AbstractValidatorExt`**: 校验器扩展。
+
+## 常用 API 方法
+
+### 通用能力 (所有基类)
+- `log.info(String msg, Object... args)`: 统一的 `kd.bos.logging.Log` 日志对象。
+
+### 操作插件特有 (`AbstractOperationServicePlugInExt`)
+- `allFields()`: 一键生成包含所有字段的列表。
+- `entryFields(String... entryKeys)`: 一键生成包含分录所有子字段的列表。
+- `addErrorMessage(DynamicObject dataEntity, String message)`: 快速回填操作错误。
+- `addErrorMessage(DynamicObject dataEntity, String title, String message)`: 带标题的错误消息。
+- `addErrorMessage(DynamicObject dataEntity, String title, String errCode, String message)`: 完整错误消息。
+- `arrayOfIds(DynamicObject[] array)`: 提取主键数组。
+- `setOfIds(DynamicObject[] array)`: 提取主键集合。
+- `listOf(DynamicObject[] array, String field)`: 提取字段值列表。
+- `setOf(DynamicObject[] array, String field)`: 提取字段值集合。
+
+### IFormPluginExtension 接口方法
+- `getValue(String key)`: 获取字段值。
+- `getValue(String key, int rowIndex)`: 获取分录字段值。
+- `getValue(String key, int rowIndex, int parentRowIndex)`: 获取分录分录字段值。
+- `getFlatValues(String key)`: 扁平获取字段所有值，返回 `List<T>`。
+- `getBaseDataQuoteType(String baseDataField)`: 获取基础资料引用类型。
+- `getEntryPropKeys(String entryKey)`: 获取分录字段标识集。
+- `getEntryProperties(String entryKey)`: 获取分录字段属性映射。
+- `getProperties(Predicate<IDataEntityProperty> predicate)`: 筛选字段属性。
+- `getProperty(String field)`: 获取字段属性。
+- `getEntryType(String entryKey)`: 获取分录类型。
+- `getMainEntityType()`: 获取主实体类型。
+- `view()`: 获取当前视图。
+
+### 监听器注册方法
+- `addEntryRowClickListeners(String... entryKeys)`: 批量注册分录行点击监听。
+- `addTabSelectListeners(String... tabKeys)`: 批量注册页签选择监听。
+- `addHyperClickListeners(String... keys)`: 批量注册超链接点击监听。
+- `addItemClickListeners(String... keys)`: 批量注册菜单项点击监听。
+- `addBeforeF7SelectListeners(String... keys)`: 批量注册 F7 弹出前监听。
+
+### 数据更新方法
+- `updateEntryView(String entryKey, DynamicObjectCollection rowData)`: 更新分录视图数据。
+
+### 列表插件补充方法 (`AbstractListPluginExt`)
+- `getButtonKeys(boolean includeDropDown)`: 获取列表按钮标识与操作映射。
+- `getBillList()`: 获取列表控件。
+- `getSelectedRowPkValues()`: 获取当前选中行主键集合。
+- `clearSelectRows()`: 清空当前列表选中项。
+
+### 调试方法
+- `peek()`: 预览实体结构（调试用）。
+
+## 示例代码
+
+### 标准单据插件模板
+```java
+package kd.cd.common.demo;
+
+import kd.cd.common.plugin.AbstractBillPlugInExt;
+import kd.cd.common.entity.EntityUtils;
+import kd.bos.form.events.AfterDoOperationEventArgs;
+
+public class MyBillPlugin extends AbstractBillPlugInExt {
+    @Override
+    public void afterDoOperation(AfterDoOperationEventArgs e) {
+        super.afterDoOperation(e);
+        if ("audit".equals(e.getOperationKey())) {
+            String billNo = getValue(EntityUtils.getBillNoKey(getBillFormId()));
+            log.info("单据 {} 审核成功", billNo);
+        }
+    }
+}
+```
+
+### 操作插件模板
+```java
+public class MyOperationPlugin extends AbstractOperationServicePlugInExt {
+    @Override
+    public void onPreparePropertys(PreparePropertysEventArgs e) {
+        // 加载所有字段
+        e.setFieldKeys(allFields());
+
+        // 或仅加载特定分录字段
+        e.setFieldKeys(entryFields("entry1", "entry2"));
+    }
+
+    @Override
+    public void beginOperationTransaction(BeginOperationTransactionArgs e) {
+        DynamicObject bill = e.getDataEntities()[0];
+        if (Boolean.TRUE.equals(bill.getBoolean("forbidflag"))) {
+            addErrorMessage(bill, "操作失败，请检查数据");
+        }
+    }
+}
+```
+
+### 使用扩展方法
+```java
+public class DemoPlugin extends AbstractBillPlugInExt {
+    public void demo() {
+        // 获取字段值（支持深路径）
+        String orgName = getValue("org.name");
+
+        // 扁平获取分录所有物料ID
+        List<Object> materialIds = getFlatValues("entry.material.id");
+
+        // 获取分录字段信息
+        Set<String> entryFields = getEntryPropKeys("entry");
+
+        // 获取基础资料引用类型
+        String baseType = getBaseDataQuoteType("material");
+
+        // 调试预览
+        Object data = peek();
+    }
+}
+```
+
+## 方法签名快照（生成 @Override 时直接对照）
+
+### AbstractFormPluginExt / AbstractBillPlugInExt 生命周期
+```java
+public void initialize()
+public void registerListener(EventObject e)
+public void preOpenForm(PreOpenFormEventArgs e)
+public void createNewData(BizDataEventArgs e)
+public void afterCreateNewData(EventObject e)
+public void loadData(LoadDataEventArgs e)
+public void afterLoadData(EventObject e)
+public void beforeBindData(EventObject e)
+public void afterBindData(EventObject e)
+public void afterCopyData(EventObject e)
+public void propertyChanged(PropertyChangedArgs e)
+public void beforeDoOperation(BeforeDoOperationEventArgs args)
+public void afterDoOperation(AfterDoOperationEventArgs args)
+public void beforeItemClick(BeforeItemClickEvent evt)
+public void itemClick(ItemClickEvent evt)
+public void beforeClick(BeforeClickEvent evt)
+public void click(EventObject evt)
+public void beforeF7Select(BeforeF7SelectEvent e)
+public void confirmCallBack(MessageBoxClosedEvent evt)
+public void closedCallBack(ClosedCallBackEvent e)
+public void clientCallBack(ClientCallBackEvent e)
+public void beforeClosed(BeforeClosedEvent e)
+public void customEvent(CustomEventArgs e)
+public void TimerElapsed(TimerElapsedArgs e)
+public void afterAddRow(AfterAddRowEventArgs e)
+public void afterDeleteRow(AfterDeleteRowEventArgs e)
+public void afterDeleteEntry(AfterDeleteEntryEventArgs e)
+public void destory()   // 注意：不是 destroy
+```
+
+### AbstractListPluginExt 特有
+```java
+public void setFilter(SetFilterEventArgs e)
+public void afterCreateNewData(EventObject e)
+public void beforeDoSelectRow(BeforeDoSelectRowEventArgs e)
+```
+
+### AbstractOperationServicePlugInExt 生命周期
+```java
+public void onPreparePropertys(PreparePropertysEventArgs e)
+public void onAddValidators(AddValidatorsEventArgs e)
+public void beforeExecuteOperationTransaction(BeforeOperationArgs e)
+public void beginOperationTransaction(BeginOperationTransactionArgs e)
+public void endOperationTransaction(EndOperationTransactionArgs e)
+public void afterExecuteOperationTransaction(AfterOperationArgs e)
+public void onReturnOperation(ReturnOperationArgs e)
+```
+
+### AbstractValidatorExt
+```java
+public void validate(ExtendedDataEntity[] dataEntities, ValidateContext validateContext)
+```
+
+## 实践建议
+1. **继承型插件强制使用 super**: 对继承型插件基类（如 `AbstractFormPluginExt`、`AbstractListPlugin`、`AbstractOperationServicePlugIn` 等），重写生命周期方法时务必先调用 `super.xxx()`，确保基类中的上下文初始化逻辑正常运行；接口型插件（如 `IWorkflowPlugin`）不适用此规则。
+2. **包名校验**: 导入时必须认准 `kd.cd.common.plugin`，避免误导至原生的 `kd.bos` 类。
+3. **轻量化插件**: 插件层只保留贴近触发点的编排与控制逻辑；复杂计算、可复用业务规则与跨模块数据处理应剥离至服务层（Service）。
+4. **使用扩展方法**: 优先使用基类提供的扩展方法（如 `getValue`, `getFlatValues` 等），减少重复代码。
+
+## 常见坑位
+1. **序列化问题**: 插件类会被序列化存储在 Session 中，严禁在插件成员变量中持有不可序列化的对象（如 `DataSet`, `InputStream`）。
+2. **空指针异常**: 在 `initialize` 阶段 `this.getView()` 可能尚未完全准备好，UI 操作建议推迟到 `registerListener` 之后。
+3. **多实例冲突**: 同一个表单打开多个页签时，静态变量（static）会共享，严禁在插件中使用非 final 的静态变量存储状态。
+4. **忘记调用 super**: 重写生命周期方法时忘记调用 `super.xxx()`，可能导致基类的初始化逻辑不执行。