kcode-pi 0.1.0

package/vendor/kingdee-skills/ok-cosmic/references/adv/query-dataset.md

@@ -0,0 +1,149 @@
+# 高性能查询与计算 (QueryServiceHelper & AlgoUtils)
+
+## TL;DR
+- 适用：ORM/DataSet 查询、批量聚合、内存计算和少量确需的 SQL 场景。
+- 先抓：`QueryServiceHelper` 负责取数，`AlgoUtils` 负责 `DataSet` 过滤、聚合和转换。
+- 跳转：只是基础资料加载优先 `BusinessDataServiceHelper.loadFromCache`；字段/元数据确认别读本页。
+- 继续读全文：当你要写批量查询、`DataSet` 聚合或原生 SQL 兜底逻辑时。
+
+## 概述
+数据查询与处理是苍穹性能优化的第一大战场。`QueryServiceHelper` (位于 `kd.bos.servicehelper`) 提供 ORM 与 SQL 查询能力，极大简化了单条或批量数据的检索逻辑；`AlgoUtils` 针对苍穹特有的 `DataSet` 提供了类 Stream 的内存计算 API，是处理大数据量业务逻辑的首选。
+
+> **适用边界**
+> ✅ 适用：单条/批量数据查询、DataSet 内存计算与统计。
+> ❌ 不适用：基础资料查询优先用 `BusinessDataServiceHelper.loadFromCache`；实体查询无法表达的场景才考虑裸 SQL。
+
+## 核心类
+- **`kd.bos.servicehelper.QueryServiceHelper`**: **查询核心**。负责从数据库（ORM 或原生 SQL）获取数据。
+- **`kd.cd.common.util.AlgoUtils`**: **计算核心**。负责对 `DataSet` 进行过滤、聚合与转换。
+- **`kd.bos.algo.DataSet`**: 苍穹高性能数据集对象。
+
+## QueryServiceHelper API 方法
+
+### 1. 单条查询
+- `queryOne(String entityName, String selectFields, QFilter[] filters)`: 查询一条记录。
+- `exists(String entityName, QFilter[] filters)`: 判断是否存在满足条件的记录。
+
+### 2. 集合查询
+- `query(String entityName, String selectFields, QFilter[] filters)`: 查询多条记录，返回 DynamicObjectCollection。
+- `query(String entityName, String selectFields, QFilter[] filters, String orderBy)`: 带排序的查询。
+
+### 3. 数据集查询
+- `queryDataSet(String formId, String algoKey, String selectFields, QFilter[] filters, String orderBy)`: **最常用**。执行实体查询并返回 DataSet。
+- `queryDataSet(String formId, String algoKey, String selectFields, QFilter[] filters, String orderBy, int top)`: 带条数限制的查询。
+- `queryDataSet(DBRoute dbRoute, String sql)`: 原生 SQL 查询。
+- `queryDataSet(DBRoute dbRoute, String sql, Object[] params)`: 带参数的原生 SQL 查询。
+
+## AlgoUtils API 方法
+
+### 1. 流处理
+- `stream(DataSet dataSet)`: 提供对 DataSet 的 Stream 流支持。
+
+### 2. 过滤与转换
+- `filter(DataSet dataSet, Predicate<Row> filter)`: 对数据集执行高效过滤。
+- `nullToZero(DataSet dataSet, String... fields)`: 将为 null 的字段值更新为 0。
+
+### 3. 聚合计算
+- `sumOf(DataSet dataSet, String field)`: 对数据集进行内存求和（返回 BigDecimal）。
+- `listOf(DataSet dataSet, String field)`: 将数据集的一列提取为 List。
+- `listOf(DataSet dataSet, Function<Row, T> function)`: 自定义函数提取为 List。
+- `setOf(DataSet dataSet, String field)`: 将数据集的一列提取为 Set。
+- `setOf(DataSet dataSet, Function<Row, T> function)`: 自定义函数提取为 Set。
+
+### 4. 信息获取
+- `fieldsOf(DataSet dataSet)`: 获取 DataSet 中字段数组。
+- `sizeOf(DataSet dataSet)`: 获取 DataSet 大小。
+- `dump(DataSet dataSet, String... fields)`: 转储 DataSet，按字段分组为 List。
+
+### 5. 数据集创建
+- `newDataSet(DynamicObjectCollection coll)`: 从 DynamicObjectCollection 创建 DataSet。
+- `newDataSet(Map<String, DataType> metaMap, List<Object[]> seqRows)`: 根据类型映射创建。
+- `newDataSet(String[] fields, DataType[] dataTypes, List<Object[]> seqRows)`: 根据字段定义创建。
+- `newDataSet(RowMeta rowMeta, List<Object[]> seqRows)`: 根据 RowMeta 创建。
+- `emptyDataSet(Map<String, DataType> metaMap, int initialSize)`: 生成空行 DataSet。
+- `emptyDataSet(RowMeta rowMeta, int initialSize)`: 根据 RowMeta 生成空行 DataSet。
+- `appendNullRow(DataSet dataSet, int size)`: 为 DataSet 追加空行。
+
+### 6. 行元数据操作
+- `rowAddField(Row row, String field, DataType dataType, Object value)`: Row 对象添加新字段并赋值。
+- `rowMetaAddField(RowMeta rowMeta, String field, DataType dataType)`: RowMeta 添加新字段。
+- `dumpRowMeta(RowMeta rowMeta)`: RowMeta 转换为类型映射。
+
+### 7. 调试输出
+- `print(DataSet dataSet)`: 等距对齐打印 DataSet。
+- `print(DataSet dataSet, int top)`: 打印前 N 条。
+- `print(DataSet dataSet, int top, boolean withJavaType)`: 带类型打印。
+
+## 示例代码
+
+### DataSet 组合查询与计算
+```java
+package kd.cd.common.demo;
+
+import kd.bos.servicehelper.QueryServiceHelper;
+import kd.cd.common.util.AlgoUtils;
+import kd.bos.algo.DataSet;
+import kd.bos.orm.query.QCP;
+import kd.bos.orm.query.QFilter;
+import java.math.BigDecimal;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+public class QueryDemo {
+    public void execute() {
+        // 1. 查询已审核单据及其金额
+        QFilter filter = new QFilter("status", QCP.equals, "C");
+        try (DataSet ds = QueryServiceHelper.queryDataSet("my_bill", "my_bill", "id,totalamount", filter.toArray(), null);
+             DataSet dsForSum = ds.copy();
+             DataSet filtered = AlgoUtils.filter(ds, row ->
+                 row.getBigDecimal("totalamount").compareTo(BigDecimal.valueOf(1000)) > 0)) {
+            // 2. 计算已查询数据的金额合计
+            BigDecimal sum = AlgoUtils.sumOf(dsForSum, "totalamount");
+
+            // 3. 提取高金额单据ID
+            List<Object> ids = AlgoUtils.listOf(filtered, "id");
+        }
+    }
+}
+```
+
+### 快速查询示例
+```java
+public void quickQuery() {
+    // 查一条记录
+    DynamicObject row = QueryServiceHelper.queryOne("my_bill", "id,name",
+            new QFilter[]{new QFilter("number", QCP.equals, "BILL001")});
+
+    // 判断是否存在
+    boolean exists = QueryServiceHelper.exists("my_bill",
+            new QFilter[]{new QFilter("number", QCP.equals, "BILL001")});
+    QFilter filter = new QFilter("status", QCP.equals, "C");
+
+    // 查询多条 → DynamicObjectCollection
+    DynamicObjectCollection rows = QueryServiceHelper.query("my_bill", "id,name", filter.toArray());
+}
+```
+
+### 原生 SQL 查询
+```java
+public void sqlQuery(DBRoute dbRoute) {
+    String sql = "SELECT id, name FROM my_table WHERE status = ?";
+    try (DataSet ds = QueryServiceHelper.queryDataSet(dbRoute, sql, new Object[]{"C"})) {
+        // 处理结果
+        List<Object> ids = AlgoUtils.listOf(ds, "id");
+    }
+}
+```
+
+## 实践建议
+1. **优先使用 DataSet**: 对于处理多单据关联、分录数据计算等场景，`DataSet` 性能远超 `List<DynamicObject>`。
+2. **延迟加载**: 在 `queryDataSet` 时，仅传入必要的 `selectFields`，严禁使用 `*`。
+3. **QFilter 优化**: 尽量在查询阶段完成数据过滤，减少传输到内存中的数据量。
+4. **流关闭**: 使用 `try-with-resources` 确保 DataSet 被正确关闭。
+
+## 常见坑位
+1. **泄露隐患**: `DataSet` 必须在 `finally` 中或使用 `try-with-resources` 调用 `close()`，否则会造成内存溢出。
+2. **空指针问题**: `AlgoUtils` 在执行计算时，如果字段值为空，应先通过 `nullToZero` 转换。
+3. **查询频率**: 严禁在插件的生命周期内高频执行查询，应优先使用已加载到界面模型（Model）中的数据。
+4. **SQL 注入**: 使用原生 SQL 时，务必使用参数化查询而非字符串拼接。

package/vendor/kingdee-skills/ok-cosmic/references/adv/request-context.md

@@ -0,0 +1,88 @@
+# 请求上下文处理 (RequestContextUtils)
+
+## TL;DR
+- 适用：异步线程、后台任务、集成接口里恢复用户、租户和语言上下文。
+- 先抓：优先 `RequestContextUtils.restore()` 或 `Guard`，不要手写 ThreadLocal 传递。
+- 跳转：同步插件线程通常不需要本页；只看上下文字段可读 `base/sdk/sdk-request-context.md`。
+- 继续读全文：当你要确认自动恢复模式、自定义上下文参数或反射风险时。
+
+## 概述
+在苍穹多线程异步开发中，`RequestContext`（包含用户、租户、多语言等）由于依赖 `ThreadLocal` 无法自动传递。`RequestContextUtils` (位于 `kd.cd.common.concurrent`) 提供了上下文的自动恢复功能，确保异步任务能正确继承主线程的身份与权限。本规范适用于后台任务、集成接口与身份模拟场景。
+
+> **适用边界**
+> ✅ 适用：异步线程/后台任务/集成接口中需要恢复用户上下文。
+> ❌ 不适用：同步插件事件中上下文自动可用，无需额外处理。
+
+## 核心类
+- **`kd.cd.common.concurrent.RequestContextUtils`**: **核心工具类**。
+- **`kd.cd.common.concurrent.RequestContextUtils.Guard`**: 上下文守卫接口，支持 try-with-resources。
+- **`kd.bos.context.RequestContext`**: 苍穹核心请求上下文接口。
+
+## 常用 API 方法
+
+### 1. 自动恢复模式（推荐）
+- `switchUser(long userId)`: **最常用**。切换到指定用户身份，并在 try-with-resources 结束时自动恢复。
+- `switchContext(Map<String, Object> params)`: 根据参数切换上下文，并在 try-with-resources 结束时自动恢复。
+
+### 2. Guard 接口
+`Guard` 是一个函数式接口，实现了 `AutoCloseable`，配合 try-with-resources 使用，确保离开作用域时原始上下文被 100% 恢复。
+
+## 示例代码
+
+### 自动恢复模式（推荐）
+```java
+package kd.cd.common.demo;
+
+import kd.cd.common.concurrent.RequestContextUtils;
+import kd.bos.context.RequestContext;
+
+public class AsyncDemo {
+    public void executeWithUser(long targetUserId) {
+        // 使用 try-with-resources 自动恢复
+        try (RequestContextUtils.Guard ignored = RequestContextUtils.switchUser(targetUserId)) {
+            // 此作用域内以 targetUser 身份执行
+            // ...执行业务逻辑...
+        }
+        // 离开作用域后自动恢复原始上下文，确保线程安全
+    }
+}
+```
+
+### 自定义上下文参数
+```java
+public void executeWithCustomContext() {
+    Map<String, Object> params = new HashMap<>();
+    params.put("userId", "12345");
+    params.put("userName", "test");
+
+    try (RequestContextUtils.Guard ignored = RequestContextUtils.switchContext(params)) {
+        // 以切换后的上下文执行业务逻辑
+    }
+    // 自动恢复原始上下文
+}
+```
+
+## 实践建议
+1. **强制使用 Guard 模式**: 使用 `switchUser`/`switchContext` 配合 try-with-resources，杜绝忘记恢复导致的"身份污染"。
+2. **多租户一致性**: 在多租户环境下，身份切换后所有的 `QFilter` 会自动遵循该租户的隔离逻辑。
+3. **配合线程池**: 在高并发环境下，推荐使用此模式自动处理上下文传递。
+
+## 重要说明
+
+### 反射机制风险
+该类通过反射机制直接操作 `RequestContext` 的私有字段，存在以下风险：
+- **脆性风险**: 深度依赖金蝶 BOS 内部实现，若 BOS 版本升级修改了字段定义（一般不会发生此种情况），此类将失效。
+
+### 支持的上下文属性
+通过 `switchContext` 可覆盖的常用属性：
+- `userId` - 用户 ID
+- `userName` - 用户名
+- `userOpenId` - 用户 OpenID
+- `tenantId` - 租户 ID
+- `locale` - 语言环境
+
+## 常见坑位
+1. **忘记恢复**: 强烈推荐使用 Guard 模式。
+2. **空上下文报错**: 如果在静态初始化块中调用切换方法，由于主线程尚无上下文，可能会报错。
+3. **事务关联**: 异步线程默认不继承主线程的数据库事务，如果异步操作涉及写库，需开启独立事务。
+4. **Session 失效**: 备份中不包含 Web Session，仅包含后端业务执行所需的元数据标识。

package/vendor/kingdee-skills/ok-cosmic/references/adv/view-handler.md

@@ -0,0 +1,157 @@
+# 页面打开与视图管理 (ViewHandler & AutoCloseViewHandler)
+
+## TL;DR
+- 适用：后台/操作插件里打开表单或列表、新页签跳转以及带参数打开界面。
+- 先抓：默认优先 `AutoCloseViewHandler`，链式设置打开模式、组织和数据初始化。
+- 跳转：表单插件内的简单弹窗优先直接 `getView().showForm()` 或回看 `form-utils.md`。
+- 继续读全文：当你要确认组织参数、打开动作差异或后台视图示例时。
+
+## 概述
+在单据交互逻辑中，频繁涉及"点击 A 单据打开 B 单据界面"的需求。`ViewHandler` (位于 `kd.cd.common.form.handler`) 采用了链式 API 封装了复杂的 `FormShowParameter` 逻辑，支持一键实现新增、修改、查看、列表界面的弹出或新页签跳转。特别适用于后台任务中需要打开视图进行数据初始化或验证的场景。
+
+> **适用边界**
+> ✅ 适用：后台/操作插件中打开表单/列表界面、新页签跳转。
+> ❌ 不适用：表单插件中的简单弹窗优先用 `getView().showForm()`，参见 `form-utils.md`。
+
+## 核心类
+- **`kd.cd.common.form.handler.ViewHandler`**: 视图操作核心工具接口。
+- **`kd.cd.common.form.handler.AutoCloseViewHandler`**: **推荐使用**。自动关闭的视图处理器，实现了 `AutoCloseable`。
+- **`kd.bos.form.FormShowParameter`**: 原生表单显示参数。
+- **`kd.bos.bill.OperationStatus`**: 页面操作状态枚举。
+
+## 常用 API 方法
+
+### 1. 工厂方法
+- `ViewHandler.of(String formId)`: 指定目标单据标识。
+- `ViewHandler.of(String formId, Object initOrgId)`: 指定单据及初始化组织ID。
+- `AutoCloseViewHandler.of(String formId)`: **推荐**。创建自动关闭的视图处理器。
+- `AutoCloseViewHandler.of(String formId, Object initOrgId)`: 创建带组织的自动关闭视图处理器。
+
+### 2. 参数设置
+- `addCustomParam(String name, Object value)`: 向目标页面传递自定义业务参数。
+- `setOpenOnDesignerPage()`: 设置忽略许可校验。
+- `beforeOpen(Consumer<FormShowParameter> c)`: 注入原生参数调整代码。
+
+### 3. 界面动作执行
+- `openAddNewView()`: 以新增状态打开。
+- `openAddNewViewAndInit(DynamicObject dataEntity)`: 以新增状态打开并初始化数据。
+- `openModifyView(Object pkValue)`: 以修改状态打开指定单据。
+- `openPeekView(Object pkValue)`: 以只读查看状态打开。
+- `openListView()`: 打开目标单据的列表页。
+- `openView(Object pkValue, OperationStatus operationStatus)`: 指定状态打开。
+- `openViewByShowParameter(FormShowParameter sp)`: 自定义参数打开。
+- `closeView()`: 关闭当前视图。
+
+### 4. 调试方法
+- `peek()`: 提取界面所有数据快照（调试用）。
+- `peekUIMsg()`: 预览 UI 消息队列（调试用）。
+- `peekUIMsgFlat()`: 获取平面化的消息列表（调试用）。
+- `flatList(String field)`: 扁平列出字段值（调试用）。
+
+## 示例代码
+
+### AutoCloseViewHandler 模板（推荐）
+```java
+package kd.cd.common.demo;
+
+import kd.cd.common.form.handler.AutoCloseViewHandler;
+import kd.bos.form.IFormView;
+
+public class ViewHandlerDemo {
+    public void backendOperation() {
+        // 使用 try-with-resources 自动关闭视图
+        try (AutoCloseViewHandler vh = AutoCloseViewHandler.of("kdcd_test")) {
+            vh.beforeOpen(sp -> sp.setAppId("fi"));
+
+            // 打开修改视图
+            IFormView view = vh.openModifyView(1462749241941L);
+
+            // 在后台视图中进行数据操作
+            // ...do something here...
+        } // 自动调用 close()，无需手动关闭
+    }
+}
+```
+
+### 带组织参数的新增视图
+```java
+public void openWithOrg(Long orgId) {
+    try (AutoCloseViewHandler vh = AutoCloseViewHandler.of("my_bill", orgId)) {
+        vh.beforeOpen(sp -> sp.setAppId("fi"));
+        IFormView view = vh.openAddNewView();
+
+        // 操作视图数据...
+    } // 自动关闭
+}
+```
+
+### 带数据初始化的新增视图
+```java
+public void openWithInit(DynamicObject initData) {
+    try (AutoCloseViewHandler vh = AutoCloseViewHandler.of("my_bill")) {
+        // 打开新增视图并初始化数据
+        IFormView view = vh.openAddNewViewAndInit(initData);
+
+        // 继续操作...
+    } // 自动关闭
+}
+```
+
+### 批量新增数据包（推荐）
+在后台场景下批量造单时，通过 `openAddNewView()` 触发完整的页面初始化生命周期（字段默认值、自动填充规则、插件 `afterCreateNewData` 等），提取数据包后统一批量保存，避免循环内逐条保存。
+
+> **性能说明**：循环中多次调用 `open` 方法时，`AutoCloseViewHandler` 会复用同一个 view 实例，仅重载数据包，不会反复创建/销毁视图，因此批量场景下性能开销可控。
+> ❗ **禁止在循环内创建 `AutoCloseViewHandler`**，否则每次迭代都会实例化新的 view 对象，丧失复用优势。正确做法是在循环外创建一次，循环内只调用 `open` 方法。
+```java
+public void batchCreateBills(int count) {
+    List<DynamicObject> list = new ArrayList<>(count);
+
+    try (AutoCloseViewHandler vh = AutoCloseViewHandler.of("kdcd_test")) {
+        for (int i = 0; i < count; i++) {
+            // 打开新增视图，触发完整初始化（默认值、自动填充、插件事件等）
+            IFormView view = vh.openAddNewView();
+            view.getModel().setValue("billno", i);
+            // 提取经过完整初始化的数据包
+            DynamicObject dataEntity = view.getModel().getDataEntity(true);
+            list.add(dataEntity);
+        }
+        // 统一批量保存，避免循环内逐条保存
+        OpUtils.executeOperateOrThrow("save", "kdcd_test", list.toArray(new DynamicObject[0]));
+    }
+}
+```
+
+> 对比 `DynamicObjectUtils.newDynamicObject(formId)` 构建裸数据包，此方式的优势是触发完整的页面初始化生命周期，无需手动设置默认值。详见 [DynamicObjectCrudSample.java](../../assets/snippets/data/DynamicObjectCrudSample.java)。
+
+## ViewHandler vs AutoCloseViewHandler
+
+| 场景 | 推荐使用 | 说明 |
+|------|---------|------|
+| 后台任务打开视图 | `AutoCloseViewHandler` | 配合 try-with-resources 自动关闭 |
+| 前台界面跳转 | `ViewHandler` | 由用户手动关闭或系统管理 |
+| 异步线程中操作 | `AutoCloseViewHandler` | 确保资源释放 |
+
+## 重要说明
+
+### 组织参数处理
+- 传入的 `initOrgId` 对于单据会传入初始化组织参数。
+- 对于基础资料会传入使用组织初始参数（仅当使用组织字段无字段名时）。
+- 在打开新增视图并且主业务组织字段为空时，还会尝试为主业务组织字段赋值。
+
+### 后台视图特点
+- `openPeekView` 相关方法后台默认以查看的方式打开视图，不触发编辑操作的网络互斥。
+- 打开的页面默认拥有权限。
+- **必须关闭视图**：后台打开的视图必须调用 `closeView()` 或使用 `AutoCloseViewHandler`。
+
+## 实践建议
+1. **优先使用 AutoCloseViewHandler**: 后台场景下使用 `AutoCloseViewHandler` 配合 try-with-resources，避免忘记关闭视图导致资源泄露。
+2. **链式调用**: 链式调用极大增强了代码可读性，相比原生 `new FormShowParameter` 可减少 50% 以上的代码量。
+3. **参数解耦原则**: 传递大型数据对象时，建议先存储在 `PageCache` 中，仅通过 `addCustomParam` 传递其 CacheKey。
+4. **状态回调**: 弹出界面返回后，建议在 `closedCallBack` 处理业务逻辑。
+
+## 常见坑位
+1. **主键类型错误**: `openModifyView` 传入的 PK 类型（Long/String）必须与物理存储一致，否则页面会报错。
+2. **PageId 冲突**: 如果自定义 PageId，确保在并发环境下具有唯一性。
+3. **权限校验**: 界面触发的跳转仍会受系统权限体系约束，如果当前用户无权查看目标单据，页面将弹出报错。
+4. **忘记关闭视图**: 使用 `ViewHandler` 时忘记调用 `closeView()` 会导致内存泄露和会话资源占用，**推荐使用 `AutoCloseViewHandler`**。
+5. **循环内创建 `AutoCloseViewHandler`**: 禁止在循环内每次迭代都 `AutoCloseViewHandler.of(...)`，否则每轮都会实例化新的 view 对象，丧失视图复用优势。正确做法是在循环外创建一次，循环内只调用 `open` 方法。

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

@@ -0,0 +1,76 @@
+# 单据界面插件
+
+## TL;DR
+- 适用：单据界面插件的原生兜底，封装层没覆盖到的单据事件时再读本页。
+- 先抓：`AbstractBillPlugIn`、额外监听器和单据特有事件时机。
+- 跳转：若 `AbstractBillPlugInExt` 足够，优先回到 `adv/plugin-base.md`。
+- 继续读全文：当你要确认工具栏、F7、操作后回调或单据关闭等具体事件时。
+
+## 概述
+单据界面插件继承动态表单插件能力，并增加单据特有事件，适合处理加载后初始化与单据交互控制。
+
+> **适用边界**
+> ✅ 本文档是原生兜底：当 `plugin-base.md`(封装层) 未覆盖你需要的单据事件时使用。
+> ❌ 如果封装层 `AbstractBillPlugInExt` 已满足需求，优先读 `references/adv/plugin-base.md`。
+
+- 适用场景：单据加载初始化、字段联动、操作前后 UI 协同
+
+术语说明：文档中的 `F7` 指基础资料、引用数据等选择控件弹窗，不是键盘按键事件。
+
+## 核心基类
+
+
+- 基类：`kd.bos.bill.AbstractBillPlugIn`
+- 继承关系：`AbstractBillPlugIn extends AbstractFormPlugin implements IBillPlugin`
+
+## 额外监听器
+
+- `BeforeF7SelectListener`：F7（基础资料/引用数据选择控件）选择前拦截
+- `ItemClickListener`：菜单/按钮点击监听
+- `ClickListener`：控件通用点击监听
+- `TreeNodeClickListener`：树节点点击监听
+
+## 核心事件
+
+- `afterLoadData(EventObject e)`：// 单据数据加载完成后触发，适合做加载后初始化
+- `beforeDoOperation(EventObject e)`：// 操作执行前触发，适合做前置校验/参数整理
+- `afterDoOperation(EventObject e)`：// 操作执行后触发，适合做结果提示/刷新协同
+- `propertyChanged(EventObject e)`：// 字段值变更后触发，适合做联动赋值
+
+说明：单据插件同时支持动态表单全套事件（生命周期与交互事件与 `plugin-form.md` 一致）。
+
+## 插件内上下文方法
+
+```java
+// 视图与模型
+IFormView view = this.getView();
+IDataModel model = this.getModel();
+
+// 读取单据常用字段
+String billNo = (String) model.getValue("billno");
+String billStatus = (String) model.getValue("billstatus");
+
+// 控件级操作
+Control control = view.getControl("fieldkey");
+BasedataEdit basedataEdit = view.getControl("basedatafield");
+view.setEnable(false, "fieldkey");
+```
+
+说明：`view.getControl("fieldkey")` 的返回类型是 `<T extends kd.bos.form.control.Control>`，所有控件都继承自 `kd.bos.form.control.Control`，实际拿到的是具体控件对象，例如 `BasedataEdit`、`EntryGrid`、`ProgressBar` 等。
+
+## 示例代码
+
+示例代码统一维护在模板文件中，直接参考：
+
+- [BillPlugInTemplate.java](../../../assets/BillPlugInTemplate.java)
+
+## 实践建议
+
+1. 加载后初始化优先放 `afterLoadData`。
+2. 事务级校验放操作插件，UI 插件只做交互提示与轻校验。
+3. 字段联动优先在 `propertyChanged`，避免分散在多个事件。
+
+## 常见坑位
+
+- 新增单据不触发 `afterLoadData`，初始化逻辑需兼顾 `afterCreateNewData`。
+- 在 UI 插件中直接改状态字段替代操作流，容易与业务状态机冲突。

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

@@ -0,0 +1,70 @@
+# 单据转换插件
+
+## TL;DR
+- 适用：BOTP 转换插件本体，处理源单取数、目标单建单、字段映射和分单合单。
+- 先抓：`AbstractConvertPlugIn` 和转换事件顺序，先区分“业务调用”还是“转换规则扩展”。
+- 跳转：如果只是执行下推/追踪来源，优先读 `adv/botp-convert.md` 的 `BotpUtils`。
+- 继续读全文：当你要改转换规则、选单逻辑或目标单数据填充时。
+
+## 概述
+单据转换插件用于在业务流转换（下推、选单）过程中介入源单取数、目标单创建、字段映射与关联关系生成。
+
+> **适用边界**
+> ✅ 本文档是原生兜底：BOTP 转换/反写没有 Ext 封装，直接读本文档。
+> ❌ 下推/选单的业务调用优先用 `BotpUtils`，参见 `references/adv/botp-convert.md`。
+
+- 适用场景：下推规则扩展、选单逻辑增强、字段映射补充、分单合单策略调整
+
+## 核心基类
+- 基类：`kd.bos.entity.botp.plugin.AbstractConvertPlugIn`
+- 继承关系：`AbstractConvertPlugIn implements IConvertPlugIn`
+
+## 核心事件
+
+- `initVariable`：// 初始化上下文变量（源单主实体、目标单主实体、转换规则、转换方式）
+- `afterBuildQueryParemeter`：// 构建取数参数后，可追加字段与过滤条件
+- `beforeBuildRowCondition`：// 编译行过滤条件前，可替换/追加规则条件
+- `afterBuildRowCondition`：// 编译行过滤条件后，可补充诊断信息或微调最终条件
+- `beforeGetSourceData`：// 取源单数据前，可调整语句与条件
+- `afterGetSourceData`：// 取源单数据后，可补充第三方数据或替换源数据
+- `beforeBuildGroupMode`：// 分单/合并策略构建前，可调整分单合并依赖字段
+- `beforeCreateTarget`：// 创建目标单前（官方说明仅选单场景触发）
+- `afterCreateTarget`：// 创建目标单后（官方说明主要下推场景触发）
+- `afterFieldMapping`：// 字段映射完成后，补充目标字段赋值
+- `afterBizRule`：// 业务规则执行后，做最终字段修正
+- `beforeCreateLink`：// 生成关联关系前，可取消/调整关联关系
+- `afterCreateLink`：// 生成关联关系后，补充关联携带数据
+- `afterBuildDrawFilter`：// 选单条件生成后，追加插件过滤条件
+- `afterConvert`：// 转换流程最后事件，做最终修正
+
+## 插件内上下文方法
+
+```java
+// 上下文获取
+BillEntityType srcMainType = this.getSrcMainType();
+BillEntityType tgtMainType = this.getTgtMainType();
+ConvertRuleElement rule = this.getRule();
+ConvertOpType opType = this.getOpType();  // 下推/选单
+```
+
+## 示例代码
+
+示例代码统一维护在模板文件中，直接参考：
+
+- [ConvertPlugInTemplate.java](../../../assets/ConvertPlugInTemplate.java)
+
+## 实践建议
+
+1. 先在 `initVariable` 明确当前上下文（下推/选单）再分支处理。
+2. 源单过滤尽量放 `beforeBuildRowCondition` 与 `beforeGetSourceData`，避免后置大规模删数据。
+3. 字段补齐优先放 `afterFieldMapping`，规则执行后的兜底修正再放 `afterBizRule`。
+4. 选单场景的额外过滤优先放 `afterBuildDrawFilter`，不要把选单过滤和普通取数过滤混写。
+5. 关联追溯场景谨慎处理 `beforeCreateLink`，取消后会影响上下游可追踪性。
+
+## 常见坑位
+
+- 误把 `beforeCreateTarget` 当所有场景必触发，导致逻辑漏执行。
+- 在 `afterConvert` 做大量数据库操作，影响转换时长。
+- 漏掉源单关键字段准备，后续事件中字段取值为 null。
+- 选单场景忘记区分 `afterBuildDrawFilter` 与普通取数过滤，导致过滤位置不稳定。
+- 关联关系被取消后，后续反写/追踪功能异常。