kcode-pi 0.1.0

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

@@ -0,0 +1,135 @@
+# 单据操作插件
+
+## TL;DR
+- 适用：服务端事务内的单据操作插件，用于校验、状态转换和级联同步。
+- 先抓：`AbstractOperationServicePlugIn` 的事件顺序，先分清事务前、事务中和事务后。
+- 跳转：若 `AbstractOperationServicePlugInExt` 足够，优先回 `adv/plugin-base.md`；纯 UI 联动别读本页。
+- 继续读全文：当你要确认 `onPreparePropertys`、回滚边界、预置操作清单或常见误用时。
+
+## 概述
+单据操作插件用于在单据操作（保存、提交、审核、删除等）的事务内进行业务逻辑干预。与UI插件不同，操作插件运行在服务端，有数据库事务保护，用于实现关键业务逻辑。
+
+> **适用边界**
+> ✅ 本文档是原生兜底：当 `plugin-base.md`(封装层) 未覆盖你需要的操作事件时使用。
+> ❌ 如果封装层 `AbstractOperationServicePlugInExt` 已满足需求，优先读 `references/adv/plugin-base.md`。
+
+- 适用场景：单据操作的权限校验、数据校验、状态转换、级联数据同步
+- 执行环境：**服务端事务内**（不同于UI插件）
+
+## 核心基类
+- 基类：`kd.bos.entity.plugin.AbstractOperationServicePlugIn`
+- 继承关系：`AbstractOperationServicePlugIn implements IOperationServicePlugIn, IOperationService`
+- 执行位置：**服务端事务内**（不是客户端）
+
+## 核心事件（时间顺序）
+
+- `onPreparePropertys(PreparePropertysEventArgs e)`：// 加载单据数据包前触发；用于补齐操作所需字段，避免后续取值为空
+- `onAddValidators(AddValidatorsEventArgs e)`：// 校验器加载完毕后、执行校验前触发；用于增删校验器
+- `beforeExecuteOperationTransaction(BeforeOperationArgs e)`：// 校验通过后、开启事务前触发；用于最后整理数据
+- `beginOperationTransaction(BeginOperationTransactionArgs e)`：// 事务开启后、数据库提交前触发；用于事务内同步处理
+- `endOperationTransaction(EndOperationTransactionArgs e)`：// 数据写库后、事务提交前触发；用于事务内后置处理
+- `rollbackOperation(RollbackOperationArgs e)`：// 事务提交失败回滚后触发；用于无事务资源补偿
+- `afterExecuteOperationTransaction(AfterOperationArgs e)`：// 事务提交后触发；用于消息通知、日志等后续处理
+
+## 插件内上下文方法
+
+```java
+// 获取操作上下文
+BillEntityType billType = this.billEntityType;  // 单据主实体
+OperateMeta operateMeta = this.operateMeta;    // 操作信息
+OperationResult result = this.operationResult;  // 操作结果
+
+// 获取自定义参数
+Map<String, Object> options = this.getOption();
+String customParam = (String) options.get("paramKey");
+
+// 添加错误信息
+result.addErrorMessage("错误提示文本");
+
+// 添加成功提示
+result.addSuccessMessage("操作成功");
+
+// 设置操作状态
+result.setSuccess(false);  // 标记操作失败
+```
+
+## 示例代码
+
+示例代码统一维护在模板文件中，直接参考：
+
+- [OpPluginTemplate.java](../../../assets/OpPluginTemplate.java)
+
+## 实践建议
+
+1. **必须理解状态转换逻辑**
+   - 单据状态有固定转换路径，不是任意转换
+   - 同一操作绑定多个插件时避免重复状态转换
+
+2. **onPreparePropertys中不要漏字段**
+   - 若操作依赖某字段，必须在此添加
+   - 否则系统加载的数据包会缺失此字段
+
+3. **规则校验优先放onAddValidators，事务前事件只做最后整理**
+   - 明确的业务规则优先注册校验器，失败会在事务开启前阻断
+   - `beforeExecuteOperationTransaction` 更适合最后整理数据、轻量兜底校验与整体取消
+
+4. **数据修改放beginOperationTransaction/endOperationTransaction**
+   - 这两个事件都在事务内，异常会自动回滚
+   - 数据库操作在此区间是安全的
+
+5. **级联数据同步放afterExecuteOperationTransaction**
+   - 此时事务已提交，可放心调用其他服务
+   - 但要做好异常处理，不要中断主逻辑
+
+## 常见坑位
+
+### ❌ 把所有校验都堆进beforeExecuteOperationTransaction
+- 这样会弱化校验器机制，后续复用和错误定位都更差
+- 明确规则优先放 `onAddValidators`，事务前事件只保留少量兜底检查
+
+### ❌ endOperationTransaction后想回滚
+- endOperationTransaction时数据已入库
+- 无法再回滚，只能在beforeExecuteOperationTransaction做校验
+
+### ❌ 多个操作绑定同一状态转换
+```java
+// 错误：一级审批和会审都在同意时调用审核通过操作
+// 导致单据从"已提交"试图再转为"已审核"->失败
+
+// 正确：应在工作流配置中区分不同路径，操作插件不重复
+```
+
+### ❌ 在afterExecuteOperationTransaction里修改单据
+- 此时事务已提交，修改会立即生效
+- 应在beforeExecuteOperationTransaction或事务内完成修改
+
+### ❌ 忽视onPreparePropertys导致字段缺失
+```java
+// 如果操作插件要读某字段但没在onPreparePropertys添加
+// 系统加载的数据包就不含此字段，导致getValue返回null
+```
+
+### ❌ 在操作插件里查询与操作无关的数据
+- 操作插件应只关注当前操作的单据数据
+- 复杂查询逻辑优先写在服务层
+
+## 预置操作清单
+
+系统预置的可绑定操作（其他操作不支持操作插件）：
+
+| 操作 | 功能 |
+|------|------|
+| save | 保存单据到数据库 |
+| saveandnew | 保存后清空界面进入新增 |
+| statusconvert | 切换单据状态 |
+| submit | 提交单据（状态→已提交） |
+| submitandnew | 提交后新增 |
+| unsubmit | 撤销提交（回到暂存） |
+| audit | 审核（状态→已审核） |
+| unaudit | 反审核（状态→暂存） |
+| disable | 禁用 |
+| enable | 启用 |
+| invalid | 作废 |
+| valid | 生效 |
+| delete | 删除 |
+| donothing | 空操作（用于触发事件流程） |

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

@@ -0,0 +1,65 @@
+# 打印插件
+
+## TL;DR
+- 适用：打印数据加载、自定义数据源和打印前后加工。
+- 先抓：`AbstractPrintPlugin` 以及 `beforeLoadData` / `loadCustomData` 两类核心入口。
+- 跳转：报表展示不是本页；文件和附件处理也不是本页。
+- 继续读全文：当你要确认打印上下文、扩展点或自定义数据源示例时。
+
+## 概述
+打印插件用于控制打印数据加载、控件输出前后加工以及自定义数据源取数。
+
+> **适用边界**
+> ✅ 本文档直接使用：打印插件无封装层，直接参考本文档。
+
+## 核心基类
+- 基类：`kd.bos.print.core.plugin.AbstractPrintPlugin`
+- 继承关系：`AbstractPrintPlugin implements IPrintPlugin`
+
+## 核心事件
+
+- `beforeLoadData(BeforeLoadDataEvent evt)`：打印数据加载前触发，可取消默认取数。
+- `loadCustomData(CustomDataLoadEvent evt)`：自定义数据源加载数据时触发。
+- `beforeOutputWidget(BeforeOutputWidgetEvent evt)`：控件输出前触发。
+- `afterOutputWidget(AfterOutputWidgetEvent evt)`：控件输出后触发。
+
+## 插件内上下文方法
+
+以下更适合作为打印插件内主动访问的上下文能力：
+
+- `getMainDataVisitor()`
+- `getDataVisitor(String dataSource)`
+- `getPrintSetting()`
+- `getExtParam()`
+- `getTplInfo()`
+- `isPreview()`
+
+```java
+Map extParam = this.getExtParam();
+Object tplInfo = this.getTplInfo();
+boolean preview = this.isPreview();
+```
+
+## 其他扩展点
+
+- `parseRichImg(...)`：富文本图片解析扩展。
+- `setExtParam(...)` 等 getter/setter：上下文读写接口，不建议写成事件说明。
+
+## 示例代码
+
+示例代码统一维护在模板文件中，直接参考：
+
+- [PrintPluginTemplate.java](../../../assets/PrintPluginTemplate.java)
+
+## 实践建议
+
+1. 取消默认取数后，要在 `loadCustomData(...)` 中补回数据。
+2. 输出前后事件更适合做格式化和控件值调整，不要承载重型查询。
+3. 上下文 getter/setter 保持在模板提示里即可，不必按事件去展开。
+4. 自定义数据源场景优先让模板和数据源标识一一对应。
+
+## 常见坑位
+
+- 把 `getExtParam()`、`getPrintSetting()` 这类上下文访问方法写成事件。
+- 取消了默认取数却没有补自定义数据，导致打印空白。
+- 在输出前后事件里执行过重逻辑，拖慢打印性能。

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

@@ -0,0 +1,64 @@
+# 报表取数插件
+
+## TL;DR
+- 适用：报表取数插件，接管查询、动态列和 `DataSet` 返回。
+- 先抓：`AbstractReportListDataPlugin` 的 `query`、列定义和树数据入口。
+- 跳转：如果你改的是报表界面交互而不是数据源，去 `plugin-report-form.md`。
+- 继续读全文：当你要写复杂取数、左树右表报表或自定义列定义时。
+
+## 概述
+报表取数插件用于接管报表列表的数据查询与列定义，适合复杂查询、自定义数据源、左树右表联动和动态列场景。
+
+> **适用边界**
+> ✅ 本文档直接使用：报表取数插件无封装层，直接参考本文档。
+
+## 核心基类
+
+
+- 基类：`kd.bos.entity.report.AbstractReportListDataPlugin`
+
+## 核心事件
+
+- `query(ReportQueryParam queryParam, Object selectedObj)`：报表查询入口，返回 `DataSet`。
+- `getColumns(List<AbstractReportColumn> columns)`：调整显示列定义，控制隐藏、顺序、宽度、冻结等属性。
+
+## 插件内上下文方法
+
+以下方法属于查询过程中的上下文访问能力，不建议当成“自动触发事件”处理：
+
+- `getQueryParam()`：获取当前报表查询参数。
+- `getSelectedObj()`：获取左树或左表当前选中对象。
+- `setProgress(int)`：异步查询时回传进度。
+
+```java
+ReportQueryParam qp = this.getQueryParam();
+Object selected = this.getSelectedObj();
+this.setProgress(30);
+```
+
+## 其他扩展点
+
+- `export(...)`：导出时复用或覆盖查询结果。
+- `exportWithSheet(...)`：多 sheet 导出扩展。
+- `queryBatchBy(...)`：分批查询扩展。
+- `getDynamicColumns(...)`：动态列构造扩展。
+
+## 示例代码
+
+示例代码统一维护在模板文件中，直接参考：
+
+- [ReportListDataPluginTemplate.java](../../../assets/ReportListDataPluginTemplate.java)
+
+## 实践建议
+
+1. `query` 只负责取数和必要聚合，格式化尽量放界面插件。
+2. 左树右表场景优先使用 `selectedObj` 限定范围。
+3. 大数据量异步查询时使用 `setProgress(int)` 反馈执行进度。
+4. 列控制集中放在 `getColumns`，不要在 `query` 混入列逻辑。
+
+## 常见坑位
+
+- 把 `getQueryParam()`、`getSelectedObj()`、`setProgress(int)` 当成事件去写说明或示例。
+- 忽略 `selectedObj`，导致左树右表点击节点后仍返回全量数据。
+- `query` 返回空对象而不是合法 `DataSet`。
+- 在 `query` 里逐行远程调用，导致报表超时。

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

@@ -0,0 +1,90 @@
+# 报表界面插件
+
+## TL;DR
+- 适用：报表界面插件，控制过滤容器、查询前后处理、导出与展示。
+- 先抓：`AbstractReportFormPlugin` 的查询相关事件和过滤容器上下文。
+- 跳转：如果你要自定义数据源而不是界面交互，去 `plugin-report-data.md`。
+- 继续读全文：当你要改过滤器、导出、行数据加工或报表 F7 行为时。
+
+## 概述
+报表界面插件用于控制过滤容器、查询前后处理、行数据加工、导出行为与列展示。
+
+> **适用边界**
+> ✅ 本文档直接使用：报表界面插件无封装层，直接参考本文档。
+
+术语说明：文档中的 `F7` 指过滤容器里的基础资料/引用数据选择控件弹窗，不是键盘按键事件。
+
+## 核心基类
+- 基类：`kd.bos.report.plugin.AbstractReportFormPlugin`
+- 继承关系：`AbstractReportFormPlugin extends AbstractFormPlugin`
+
+## 核心事件
+
+- `initDefaultQueryParam(...)`：设置默认查询参数。
+- `filterContainerInit(...)`：初始化过滤容器。
+- `filterContainerBeforeF7Select(...)`：过滤容器 F7（基础资料/引用数据选择控件）打开前拦截。
+- `filterContainerSearchClick(...)`：点击过滤容器查询按钮时触发。
+- `verifyQuery(...)`：查询前校验。
+- `beforeQuery(...)`：执行查询前追加或修正查询条件。
+- `afterQuery(...)`：查询完成后处理。
+- `afterCreateColumn(...)`：列创建完成后调整列显示属性。
+- `packageData(...)`：单元格数据打包时格式化前端显示值。
+- `processRowData(...)`：行数据返回后、渲染前进行加工。
+- `preProcessExportData(...)`：导出数据预处理。
+- `setExcelName(...)`：设置导出文件名。
+- `setSortAndFilter(...)`：设置列排序和列过滤能力。
+
+## 插件内上下文方法
+
+以下更适合作为界面插件中的上下文能力，不建议当成“自动触发事件”：
+
+- `getView()`：获取报表视图。
+- `getModel()`：获取报表数据模型。
+- `getQueryParam()`：获取当前查询参数。
+- `getControl("reportlistap")`：获取报表控件，返回 `Control` 基类或具体控件对象。
+
+```java
+ReportList reportList = this.getControl("reportlistap");
+ReportQueryParam qp = this.getQueryParam();
+reportList.setSelectedAll(true);
+```
+
+说明：`this.getControl("reportlistap")` 的返回类型是 `<T extends kd.bos.form.control.Control>`，所有控件都继承自 `kd.bos.form.control.Control`，实际拿到的是具体控件对象，例如 `ReportList`、`BasedataEdit`、`EntryGrid` 等。
+
+## 其他扩展点
+
+- `getComboItems(...)`
+- `colHeadFilterClick(...)`
+- `afterSetModelValue(...)`
+- `loadOtherEntryFilter(...)`
+- `resetColumns(...)`
+- `resetDataCount()`
+- `setCellStyleRules(...)`
+- `setFloatButtomData(...)`
+- `setMergeColums(...)`
+- `setRowCellStyleEvent(...)`
+- `setFlexProperty(...)`
+- `setTreeReportList(...)`
+- `setOtherEntryFilter(...)`
+
+这些方法更适合归为专项扩展点，而不是和核心查询事件并列。
+
+## 示例代码
+
+示例代码统一维护在模板文件中，直接参考：
+
+- [ReportFormPluginTemplate.java](../../../assets/ReportFormPluginTemplate.java)
+
+## 实践建议
+
+1. 查询合法性校验统一放 `verifyQuery(...)`。
+2. 过滤容器初始化与默认参数初始化要配合使用。
+3. `processRowData(...)` 避免逐行查库，导出时会放大性能问题。
+4. 导出相关逻辑放在 `preProcessExportData(...)` 和 `setExcelName(...)`。
+
+## 常见坑位
+
+- 把 `getView()`、`getQueryParam()` 这类上下文访问能力写成事件说明。
+- 在 `packageData(...)` 中实现导出逻辑。
+- `verifyQuery(...)` 不校验空条件导致全表扫描。
+- 把大量专项扩展点和核心查询事件混在一起，模板难以聚焦。

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

@@ -0,0 +1,62 @@
+# 后台任务插件
+
+## TL;DR
+- 适用：后台调度任务、批处理、定时同步和夜间修复作业。
+- 先抓：`AbstractTask` 的执行入口、任务参数和日志/异常边界。
+- 跳转：在线请求里的异步处理优先看线程池和请求上下文，不一定需要任务插件。
+- 继续读全文：当你要确认调度模板、上下文对象或失败处理方式时。
+
+## 概述
+后台任务插件用于调度作业中的异步任务执行，适合定时批处理、夜间同步、批量修复等场景。
+
+> **适用边界**
+> ✅ 本文档直接使用：后台任务插件无封装层，直接参考本文档。
+
+## 核心基类
+
+
+- 基类：`kd.bos.schedule.executor.AbstractTask`
+- 继承关系：`AbstractTask implements Task`
+
+## 核心事件
+
+- `execute(RequestContext ctx, Map<String, Object> params)`：调度中心触发任务执行时进入，承载任务主逻辑。
+- `stop()`：调度中心主动停止任务时触发，用于安全退出与资源释放。
+
+## 插件内上下文方法
+
+这些方法更适合作为任务代码里主动调用的上下文能力，不建议继续按“事件”理解：
+
+- `feedbackProgress(...)`：回传进度信息。
+- `feedbackCustomdata(...)`：回传自定义运行数据。
+- `checkIsStop()`：主动检查是否已收到停止指令。
+- `isStop()`：读取当前停止标记。
+- `getMessageHandler()`：获取调度消息处理器。
+- `setTaskId(String)` / `getTaskId()`：访问任务标识。
+- `isSupportReSchedule()`：判断是否支持重新调度。
+
+```java
+this.feedbackProgress(20, "开始执行", null);
+this.checkIsStop();
+this.feedbackCustomdata(java.util.Collections.singletonMap("phase", "load-data"));
+```
+
+## 示例代码
+
+示例代码统一维护在模板文件中，直接参考：
+
+- [TaskTemplate.java](../../../assets/TaskTemplate.java)
+
+## 实践建议
+
+1. 长任务应分阶段调用 `feedbackProgress(...)`。
+2. 每个大步骤后主动调用 `checkIsStop()`，避免无法及时响应停止。
+3. `params` 先做容错校验，避免任务启动即异常。
+4. 任务逻辑尽量保证幂等，防止重跑产生重复副作用。
+
+## 常见坑位
+
+- 把 `feedbackProgress`、`feedbackCustomdata` 当成“自动触发事件”，导致代码放错位置。
+- 长任务完全不检查 `checkIsStop()`，停止指令无法及时生效。
+- 单次处理全量数据，导致内存和事务过大。
+- 异常被吞掉，调度侧显示成功但业务未完成。

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

@@ -0,0 +1,71 @@
+# 左树右表单据列表插件
+
+## TL;DR
+- 适用：左树右表列表插件，处理树初始化、节点选择和树表联动。
+- 先抓：`AbstractTreeListPlugin` 和树模型事件，先分清树模板类型。
+- 跳转：标准列表无树场景先读 `plugin-list.md`；Ext 通用能力回 `adv/plugin-base.md`。
+- 继续读全文：当你要改树筛选、节点点击、列表联动或特殊扩展点时。
+
+## 概述
+左树右表插件在标准列表上增加了“分组树 + 右侧列表”的协同能力，适用于组织树、分类树、业务分组树筛选场景。
+
+> **适用边界**
+> ✅ 本文档是原生兜底：左树右表有两个模板（TreeListPluginTemplate/StandardTreeListPluginTemplate），事件签名参考本文档。
+> ❌ 封装层 Ext 基类的通用部分优先读 `references/adv/plugin-base.md`。
+
+## 核心基类
+- 基类：`kd.bos.list.plugin.AbstractTreeListPlugin`
+- 继承关系：`AbstractTreeListPlugin extends AbstractListPlugin implements ITreeListPlugin, SearchEnterListener`
+
+## 核心事件
+
+- `initializeTree(...)`：树模型初始化时触发。
+- `initTreeToolbar(...)`：树工具栏初始化后触发。
+- `treeNodeClick(...)`：节点点击后触发。
+- `buildTreeListFilter(...)`：基于当前节点构建右侧列表过滤条件。
+- `refreshNode(...)`：树节点刷新时触发。
+- `treeToolbarClick(...)`：树工具栏按钮点击时触发。
+- `search(...)`：树搜索回车时触发。
+- `beforeShowBill(...)`：打开右侧详情前触发。
+
+## 插件内上下文方法
+
+以下属于树列表插件的上下文访问能力，不建议继续按“事件”理解：
+
+- `getTreeListView()`：获取树列表视图模型。
+- `getTreeModel()`：获取树模型。
+- `getView()` / `getModel()`：访问页面视图和数据模型。
+
+```java
+ITreeListView treeListView = this.getTreeListView();
+ITreeModel treeModel = this.getTreeModel();
+Object currentNodeId = treeListView.getCurrentNodeId();
+```
+
+## 其他扩展点
+
+- `setTreeListView(...)`：树列表视图模型注入阶段，偏框架上下文准备，不建议与业务事件并列。
+- `nodeClickFilter()`：返回点击节点时附加到右表的过滤条件，更适合作为过滤扩展点理解。
+- `setCustomerParam()`：树列表自定义参数构建扩展。
+- `expendTreeNode(...)`：有的文档或版本中会出现，但官方说明更推荐统一在 `refreshNode(...)` 处理中做懒加载。
+
+## 示例代码
+
+示例代码统一维护在模板文件中，直接参考：
+
+- [TreeListPluginTemplate.java](../../../assets/TreeListPluginTemplate.java)
+- [StandardTreeListPluginTemplate.java](../../../assets/StandardTreeListPluginTemplate.java)
+
+## 实践建议
+
+1. 树节点驱动右表过滤优先放在 `buildTreeListFilter(...)`。
+2. 需要树模型时通过 `getTreeModel()` 访问，不要把它当成事件。
+3. 懒加载场景优先统一放在 `refreshNode(...)` 处理。
+4. 打开详情页前如需透传来源信息，可放在 `beforeShowBill(...)`。
+
+## 常见坑位
+
+- 把 `getTreeListView()`、`getTreeModel()` 这类上下文方法写进事件总览。
+- 在 `treeNodeClick(...)` 里直接写大量查询逻辑，导致点击卡顿。
+- 节点懒加载和刷新逻辑分散在多个事件里，后续难维护。
+- 只在 `initializeTree(...)` 加节点，没有同步处理 `refreshNode(...)`。

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

@@ -0,0 +1,82 @@
+# 工作流插件
+
+## TL;DR
+- 适用：工作流运行期扩展，处理参与人、条件、通知和审批记录定制。
+- 先抓：`IWorkflowPlugin` 及其接口事件；这是接口型插件，不是常规 `super` 生命周期。
+- 跳转：普通单据审核流转别误用本页；那通常是操作插件或下推链路。
+- 继续读全文：当你要写动态审批人、条件分支或流程通知时。
+
+## 概述
+工作流插件用于在流程运行时参与参与人计算、条件判断、流程通知和审批记录格式化。
+
+> **适用边界**
+> ✅ 本文档直接使用：工作流插件是接口型（`IWorkflowPlugin`），无封装层，无需调用 super。
+
+- 适用场景：动态审批人、条件分支、流程通知、审批记录定制
+
+## 核心基类
+
+- 基类：`kd.bos.workflow.engine.extitf.IWorkflowPlugin`
+
+## 核心事件
+
+- `calcUserIds(AgentExecution execution)`：参与人计算阶段触发。
+- `hasTrueCondition(AgentExecution execution)`：条件分支判断阶段触发。
+- `notify(AgentExecution execution)`：流程通知阶段触发。
+- `notifyByWithdraw(AgentExecution execution)`：流程撤回阶段触发。
+- `formatFlowRecord(IApprovalRecordItem item)`：审批记录展示格式化时触发。
+
+## 插件内上下文方法
+
+以下更适合作为 `AgentExecution` 上的上下文访问能力，而不是插件“事件”：
+
+- `execution.getBusinessKey()`
+- `execution.getEntityNumber()`
+- `execution.getCurrentFlowElement()`
+- `execution.getVariable(...)`
+- `execution.setVariable(...)`
+- `execution.getCurrentTaskResult()`
+- `execution.getStartUserId()`
+- `execution.setAssigneeList(...)`
+
+```java
+String businessKey = execution.getBusinessKey();
+Object amount = execution.getVariable("amount");
+execution.setVariable("lastNodeName", "财务审核");
+```
+
+## 其他扩展点
+
+以下方法存在于接口默认实现或扩展能力中，但不建议在模板里与核心事件同层表达：
+
+- `filterParticipant(...)`
+- `handleTask(...)`
+- `afterHandleTask(...)`
+- `afterCancelTask(...)`
+- `aggregateBills(...)`
+- `getJointAuditResult(...)`
+- `getExpireTime(...)`
+- `getBillPermissions(...)`
+- `validatePlugin(...)`
+- `resetYZJGroupProperty(...)`
+
+## 示例代码
+
+示例代码统一维护在模板文件中，直接参考：
+
+- [IWorkflowPluginTemplate.java](../../../assets/IWorkflowPluginTemplate.java)
+
+## 实践建议
+
+1. 参与人计算和条件分支尽量独立实现，避免职责混杂。
+2. `notify` 与 `notifyByWithdraw` 尽量成对设计，保证状态可恢复。
+3. 耗时逻辑不要放在 `notify` 中阻塞流程。
+4. 流程变量与单据数据是两套数据，要显式同步。
+5. `IWorkflowPlugin` 是接口型插件，不存在“先调用 `super.xxx()`”这一要求。
+
+## 常见坑位
+
+- 把 `execution.getVariable(...)`、`execution.setAssigneeList(...)` 这类上下文访问方法写成插件事件。
+- 一个插件同时塞太多流程扩展点，后续维护困难。
+- `notify` 修改了单据状态，但 `notifyByWithdraw` 没有补偿恢复。
+- 参与人计算完成后没有真正替换审批人列表。

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

@@ -0,0 +1,71 @@
+# 单据反写插件
+
+## TL;DR
+- 适用：反写插件，处理下游结果回写上游、超额校验、行关闭和补偿。
+- 先抓：`AbstractWriteBackPlugIn` 的回写事件顺序，先区分下推阶段和反写阶段。
+- 跳转：只是调用下推/选单业务动作时，优先读 `adv/botp-convert.md`。
+- 继续读全文：当你要改数量金额反写、关闭控制或回滚补偿逻辑时。
+
+## 概述
+单据反写插件用于下游单据在保存/审核等操作时，把计算结果反写回上游单据，并参与关闭行、超额检查、保存回滚等完整流程。
+
+> **适用边界**
+> ✅ 本文档是原生兜底：反写插件没有 Ext 封装，直接读本文档。
+> ❌ 下推/选单的业务调用优先用 `BotpUtils`，参见 `references/adv/botp-convert.md`。
+
+- 适用场景：数量金额反写、上游行关闭控制、超额校验定制、反写补偿
+
+## 核心基类
+- 基类：`kd.bos.entity.botp.plugin.AbstractWriteBackPlugIn`
+- 继承关系：`AbstractWriteBackPlugIn implements IWriteBackPlugIn`
+
+## 核心事件
+
+- `preparePropertys`：// 读取下游目标单前，准备所需目标字段
+- `beforeTrack`：// 构建关联记录前，可取消本关联主实体反写
+- `beforeCreateArticulationRow`：// 构建单行关联记录前，可取消该行反写
+- `beforeExecWriteBackRule`：// 执行反写规则前，可禁用当前规则
+- `afterCalcWriteValue`：// 反写值计算后，修正分配量
+- `beforeReadSourceBill`：// 读取源单前，准备源单字段
+- `afterReadSourceBill`：// 读取源单后，补充第三方数据
+- `afterCommitAmount`：// 反写写入源单行后，做连锁更新
+- `beforeExcessCheck`：// 超额检查前，可取消检查
+- `afterExcessCheck`：// 超额检查后，决定提示/中断
+- `beforeCloseRow`：// 关闭上游行前（可跳过关闭条件检查）
+- `afterCloseRow`：// 上游行关闭状态写入后
+- `beforeSaveTrans`：// 开启保存事务前，准备第三方数据
+- `beforeSaveSourceBill`：// 源单保存前
+- `afterSaveSourceBill`：// 源单保存后
+- `rollbackSave`：// 保存失败回滚补偿
+- `finishWriteBack`：// 反写结束释放资源（如网控）
+
+## 插件内上下文方法
+
+```java
+// 上下文
+BillEntityType targetSubMainType = this.getTargetSubMainType();
+String opType = this.getOpType();  // Draft/Save/Audit/UnAudit/Delete/...
+LinkSetItemElement currLinkSetItem = this.getCurrLinkSetItem();
+```
+
+- `setContext(...)`：框架设置当前上下文的初始化入口，更适合作为上下文准备能力理解，而不是业务事件。
+
+## 示例代码
+
+示例代码统一维护在模板文件中，直接参考：
+
+- [WriteBackPlugInTemplate.java](../../../assets/WriteBackPlugInTemplate.java)
+
+## 实践建议
+
+1. `preparePropertys` 与 `beforeReadSourceBill` 必须明确字段准备，避免后续空值。
+2. 超额场景优先在 `afterExcessCheck` 做统一提示策略。
+3. 涉及第三方系统写入，优先用 `beforeSaveTrans` + `rollbackSave` 做补偿闭环。
+4. 资源申请（网控、缓存句柄）必须在 `finishWriteBack` 释放。
+
+## 常见坑位
+
+- 忽略 `rollbackSave`，保存失败后外部系统数据不一致。
+- 在 `beforeExcessCheck` 一律取消检查，导致业务失控。
+- `beforeTrack`/`beforeCreateArticulationRow` 误取消后反写缺失。
+- `finishWriteBack` 未释放资源引发后续并发问题。