kcode-pi 0.1.0

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

@@ -0,0 +1,165 @@
+# 动态表单插件
+
+## TL;DR
+- 适用：动态表单插件原生兜底，封装层没覆盖的 UI 生命周期和监听器时读本页。
+- 先抓：`AbstractFormPlugin`、`registerListener`、核心事件顺序和上下文方法。
+- 跳转：能用 `AbstractFormPluginExt` 就优先回到 `adv/plugin-base.md`；纯后台逻辑别读本页。
+- 继续读全文：当你要确认字段联动、F7、页签/分录监听或文末坑位时。
+
+## 概述
+动态表单是金蝶云苍穹的基础 UI 承载，支持各类表单场景（单据、基础资料、活动等）。动态表单插件用于在表单加载、初始化、交互全生命周期进行业务逻辑干预。
+
+> **适用边界**
+> ✅ 本文档是原生兜底：当 `plugin-base.md`(封装层) 未覆盖你需要的表单事件时使用。
+> ❌ 如果封装层 `AbstractFormPluginExt` 已满足需求，优先读 `references/adv/plugin-base.md`。
+
+- 适用场景：表单字段联动、控件状态管理、事件拦截、参数验证
+
+术语说明：文档中的 `F7` 指基础资料、引用数据等“选择引用数据”的控件弹窗场景，不是键盘按键事件。
+
+## 核心基类
+
+
+- 基类：`kd.bos.form.plugin.AbstractFormPlugin`
+- 继承关系：`AbstractFormPlugin extends AbstractDataModelPlugin implements IFormPlugin`
+
+## 额外监听器
+
+- `BeforeF7SelectListener`：F7（基础资料/引用数据选择控件）弹出前，调整过滤条件
+- `RowClickEventListener`：表格行点击
+- `TreeNodeClickListener`：树形节点点击
+- `TreeNodeCheckListener`：树形节点勾选
+- `TabSelectListener`：标签页切换
+- `ItemClickListener`：菜单/按钮点击
+- `ClickListener`：控件通用点击
+- `ProgresssListener`：进度条变化
+
+## 核心事件
+
+- `setPluginName`：// 显示界面前，准备显示配置时触发
+- `preOpenForm`：// 显示界面前，准备参数时触发
+- `loadCustomControlMetas`：// 显示界面前，构建参数时触发
+- `setView`：// 表单视图模型初始化时调用，传入 IFormView
+- `initialize`：// 表单视图初始化后触发
+- `registerListener`：// 创建后触发，用于注册控件监听
+- `getEntityType`：// 创建数据包前触发
+- `createNewData`：// 开始新建数据包时触发
+- `afterCreateNewData`：// 新建数据包完毕后触发
+- `beforeBindData`：// 刷新前端前触发
+- `afterBindData`：// 刷新前端后触发
+- `beforeItemClick`：// 菜单按钮点击前触发
+- `itemClick`：// 菜单按钮点击时触发
+- `beforeDoOperation`：// 执行操作前触发
+- `afterDoOperation`：// 执行操作后触发
+- `confirmCallBack`：// 确认提示后触发
+- `closedCallBack`：// 子界面关闭时触发
+- `flexBeforeClosed`：// 弹性域维护界面关闭时触发
+- `onGetControl`：// 获取控件编程模型时触发
+- `customEvent`：// 自定义控件定制事件触发
+- `TimerElapsed`：// 定时触发
+- `beforeClosed`：// 界面关闭前触发
+- `destory`：// 界面关闭后释放资源时触发
+- `pageRelease`：// 界面关闭后释放资源时触发
+- `beforeclick`：// 点击前校验事件
+- `click`：// 点击后触发操作事件
+- `propertyChanged`：// 修改字段值后触发
+
+## 插件内上下文方法
+
+```java
+// 获取表单视图模型
+IFormView view = this.getView();
+
+// 获取表单数据模型
+IDataModel model = this.getModel();
+
+// 获取指定控件
+Control control = this.getView().getControl("controlKey");
+BasedataEdit basedataEdit = this.getView().getControl("basedatafield");
+EntryGrid entryGrid = this.getView().getControl("entryentity");
+
+// 获取字段值
+Object value = this.getModel().getValue("fieldKey");
+
+// 设置字段值（自动触发propertyChanged）
+this.getModel().setValue("fieldKey", newValue);
+
+// 控件启用/禁用
+this.getView().setEnable(false, "controlKey");
+
+// 控件隐显
+this.getView().setVisible(false, "controlKey");
+
+// 获取完整数据包
+DynamicObject dataEntity = model.getDataEntity();
+```
+
+说明：`this.getView().getControl("controlKey")` 的返回类型是 `<T extends kd.bos.form.control.Control>`，所有控件都继承自 `kd.bos.form.control.Control`，实际拿到的是具体控件对象，例如 `BasedataEdit`、`EntryGrid`、`ProgressBar` 等。
+
+## 示例代码
+
+示例代码统一维护在模板文件中，直接参考：
+
+- [FormPluginTemplate.java](../../../assets/FormPluginTemplate.java)
+
+## 实践建议
+
+1. **registerListener中统一注册所有监听**
+   - 不要分散在多个事件中注册监听
+   - 每个监听最多 add 一次
+
+2. **propertyChanged做联动**
+   - 修改后的级联操作放propertyChanged
+
+3. **afterCreateNewData内赋值不触发propertyChanged**
+   - 文档明确说明此时不触发propertyChanged
+   - 需要联动时在afterBindData里处理
+
+4. **子页面返回统一走closedCallBack**
+   - 不要在各处open子页面时写回调
+   - 所有子页面返回由closedCallBack统一处理
+
+5. **重逻辑不要放插件**
+   - 复杂业务逻辑写服务层
+   - UI插件仅做编排与界面控制
+
+## 常见坑位
+
+### ❌ 仅implements接口不注册监听
+```java
+// 错误：只implements但没注册
+public class TreeClickBad extends AbstractFormPlugin implements TreeNodeClickListener {
+    @Override
+    public void treeNodeClick(TreeNodeClickEvent e) {
+        // 永远不会被调用
+    }
+}
+
+// 正确：implement后在registerListener注册
+public class TreeClickGood extends AbstractFormPlugin implements TreeNodeClickListener {
+    @Override
+    public void registerListener(EventObject e) {
+        super.registerListener(e);
+        TreeView tv = this.getView().getControl("treeKey");
+        if (tv != null) {
+            tv.addTreeNodeClickListener(this);  // 必须注册
+        }
+    }
+}
+```
+
+### ❌ 在registerListener里调用model.getValue
+- 此时数据尚未绑定，getValue返回null
+- 应在afterBindData或propertyChanged里操作
+
+### ❌ 期望afterCreateNewData触发propertyChanged
+- 此时赋值不会触发propertyChanged事件
+- 级联更新需在afterBindData里显式处理
+
+### ❌ 嵌套树/表格重复注册监听
+- 同一控件avoid重复addListener
+- 使用标识符检查是否已注册
+
+### ❌ destory拼写错误
+- 方法名是destory（少r），不是destroy
+- 跟风覆盖时要按文档准确拼写

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

@@ -0,0 +1,69 @@
+# 引入引出插件
+
+## TL;DR
+- 适用：Excel 导入流程扩展，包括导入前校验、保存拦截、日志和结果加工。
+- 先抓：`BatchImportPlugin` 和导入生命周期，不要套用普通表单插件思路。
+- 跳转：普通 UI 插件或批量按钮逻辑不看本页；模板优先参考 `BatchImportPluginTemplate`。
+- 继续读全文：当你要确认导入事件、上下文对象或失败处理扩展点时。
+
+## 概述
+引入引出插件用于扩展 Excel 导入流程，包括批量策略、保存拦截、数据校验与日志记录。
+
+> **适用边界**
+> ✅ 本文档是原生兜底：引入引出场景直接使用，无封装层。
+> ❌ 普通表单插件的导入事件已在 `FormPluginTemplate` 中省略，因为有独立的 `BatchImportPluginTemplate`。
+
+## 核心基类
+
+
+- 基类：`kd.bos.form.plugin.impt.BatchImportPlugin`
+- 继承关系：`BatchImportPlugin implements Callable<Object>, IImportDataPlugin`
+
+## 核心事件
+
+- `save(List<ImportBillData> rowdatas, ImportLogger logger)`：每批导入数据保存时进入，是最核心的校验与过滤拦截点。
+- `getBatchImportSize()`：初始化批量导入策略时调用，用于确定批次大小。
+- `isForceBatch()`：初始化导入模式时调用，用于决定是否强制批处理。
+
+## 插件内上下文方法
+
+以下更适合作为导入插件的上下文/工具方法，不建议继续按“事件”理解：
+
+- `getContext()`：获取导入上下文。
+- `getLogger()`：获取导入日志对象。
+- `getBatchSize()`：读取当前批次大小。
+- `refreshHeartbeat()`：刷新任务心跳。
+- `call()`：导入任务执行入口包装。
+
+```java
+Map<String, Object> billData = data.getData();
+logger.log(data.getStartIndex(), "错误信息").fail();
+return super.save(rowdatas, logger);
+```
+
+## 其他扩展点
+
+- `beforeSave(...)`：保存前批次预校验。
+- `resolveExcel()`：Excel 解析扩展。
+- `importData()`：导入主流程扩展。
+- `getDefaultImportType()` / `getDefaultKeyFields()`：默认导入配置扩展。
+
+## 示例代码
+
+示例代码统一维护在模板文件中，直接参考：
+
+- [BatchImportPluginTemplate.java](../../../assets/BatchImportPluginTemplate.java)
+
+## 实践建议
+
+1. 导入校验优先集中在 `save(...)`。
+2. 大数据量场景要明确 `getBatchImportSize()` 和 `isForceBatch()`。
+3. 对失败行必须写 `ImportLogger`，方便用户回溯。
+4. 优先过滤非法数据后再复用 `super.save(...)`。
+
+## 常见坑位
+
+- 把 `call()`、`refreshHeartbeat()`、`getContext()` 这种上下文能力写成“事件说明”。
+- 直接抛异常中断整批导入，导致可导入数据也丢失。
+- 不记录失败日志，用户无法定位错误行。
+- 批次过大导致内存抖动或请求超时。

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

@@ -0,0 +1,227 @@
+# 标准单据列表插件
+
+## TL;DR
+- 适用：标准/基础资料/左树右表列表的原生兜底事件与取数控制。
+- 先抓：`AbstractListPlugin`、过滤容器、列定义、行点击和打开单据回调。
+- 跳转：若 Ext 基类够用先回 `adv/plugin-base.md`；树侧联动再补读 `plugin-tree-list.md`。
+- 继续读全文：当你要改过滤器、列表取数、超链接或行事件，并规避文末坑位时。
+
+## 概述
+单据列表插件用于控制列表的加载、显示、取数、过滤、行交互等全生命周期。列表支持标准的单据/基础资料列表、左树右表列表等多种布局。
+
+> **适用边界**
+> ✅ 本文档是原生兜底：当 `plugin-base.md`(封装层) 未覆盖你需要的列表事件时使用。
+> ❌ 如果封装层 `AbstractListPluginExt` 已满足需求，优先读 `references/adv/plugin-base.md`。
+
+- 适用场景：列表过滤定制、列表数据处理、行交互、超链接、单据打开回调
+
+术语说明：文档中的 `F7` 指过滤容器或字段上的基础资料/引用数据选择控件弹窗，不是键盘按键事件。
+
+## 核心基类
+
+
+- 基类：`kd.bos.list.plugin.AbstractListPlugin`
+- 继承关系：`AbstractListPlugin extends AbstractFormPlugin implements ListRowClickListener, IPCListPlugin`
+
+## 额外监听器
+
+- `IRegisterPropertyListener`：过滤/依赖字段事件
+- `BeforeF7SelectListener`：F7（基础资料/引用数据选择控件）选择前拦截（过滤容器场景）
+
+## 核心事件
+
+- `filterContainerInit`：// 过滤容器初始化，可添加/修改过滤字段定义
+- `beforeCreateListColumns`：// 创建列定义前，可添加/修改列信息
+- `beforeCreateListDataProvider`：// 创建取数器前，可自定义取数逻辑
+- `setFilter`：// 查询前调整过滤条件
+- `filterContainerSearchClick`：// 用户点击查询或修改快捷过滤时触发
+- `filterContainerAfterSearchClick`：// 过滤条件解析完毕后联动处理
+- `filterContainerBeforeF7Select`：// 过滤容器 F7（基础资料/引用数据选择控件）弹出前拦截
+- `filterColumnSetFilter`：// 基础资料过滤字段条件调整
+- `baseDataColumnDependFieldSet`：// 设置常用过滤依赖字段
+- `beforeItemClick`：// 菜单按钮点击前触发
+- `itemClick`：// 菜单按钮点击时触发
+- `billListHyperLinkClick`：// 点击超链接单元格时触发
+- `beforeShowBill`：// 打开单据维护界面前触发
+- `billClosedCallBack`：// 单据维护界面关闭返回时触发
+- `listRowClick`：// 列表行点击时触发
+- `listRowDoubleClick`：// 列表行双击时触发
+- `setCellFieldValue`：// 设置单元格指令时触发
+- `setPluginName`：// 界面显示前触发
+- `preOpenForm`：// 界面打开前触发
+- `loadCustomControlMetas`：// 自定义控件元数据加载时触发
+- `setView`：// 视图注入时触发
+- `initialize`：// 初始化时触发
+- `registerListener`：// 注册监听时触发
+- `beforeBindData`：// 绑定前触发
+- `afterBindData`：// 绑定后触发
+
+## 插件内上下文方法
+
+### 过滤容器操作
+```java
+// filterContainerInit 中添加自定义过滤字段
+FilterColumn filterColumn = new FilterColumn("datefield");
+filterColumn.setDefaultValues("2019-1-30", "2019-1-31");
+args.addFilterColumn(filterColumn);
+
+// filterContainerSearchClick 中获取过滤值
+String filterValue = args.getFilterValue("datefield");
+Map<String, Object> fastFilters = args.getFastFilterValues();
+
+// 动态添加过滤条件
+QFilter qfilter = new QFilter("datefield", CompareTypeEnum.EQUAL, "2020-01-01");
+args.addFilter("datefield", qfilter);
+
+// 添加快速过滤
+args.addFastFilter("textfield", "searchValue");
+
+// 获取过滤后的 QFilter
+QFilter filter = args.getQFilter("datefield");
+
+// 获取选中的主组织
+Set<String> mainOrgIds = args.getSelectMainOrgIds();
+```
+
+### 列定义操作
+```java
+// beforeCreateListColumns 中修改列定义
+ComboListColumn comboColumn = new ComboListColumn();
+comboColumn.setListFieldKey("combofield");
+
+MergeListColumn mergeColumn = new MergeListColumn();
+mergeColumn.setKey("mergecolumn");
+mergeColumn.getItems().add(comboColumn);
+
+beforecreatelistcolumnsargs.addListColumn(mergeColumn);
+```
+
+### 行点击操作
+```java
+// listRowClick 中获取行数据
+@Override
+public void listRowClick(RowClickEventArgs e) {
+    DynamicObject dataEntity = e.getDataEntity();
+    String billNo = (String) dataEntity.get("billno");
+    System.out.println("点击行：" + billNo);
+}
+
+// listRowDoubleClick 中处理双击
+@Override
+public void listRowDoubleClick(RowClickEventArgs e) {
+    DynamicObject dataEntity = e.getDataEntity();
+    String billId = (String) dataEntity.get("id");
+    // 打开单据或其他操作
+}
+```
+
+## 示例代码
+
+示例代码统一维护在模板文件中，直接参考：
+
+- [ListPluginTemplate.java](../../../assets/ListPluginTemplate.java)
+
+## 实践建议
+
+1. **过滤定制优先用 filterContainerInit + filterContainerAfterSearchClick**
+   - 在 init 中定义字段
+   - 在 afterSearchClick 中处理联动
+
+2. **避免在逐行处理链路中查库**
+   - 大数据量场景性能问题
+   - 应在 beforeCreateListDataProvider 或 setFilter 中提前准备数据
+
+3. **基础资料引用字段不要在 beforeCreateListDataProvider 里修改**
+   - 会破坏内置缓存
+   - 只适合修改非基础资料字段
+
+4. **行点击与菜单项点击分离**
+   - 行点击处理用 listRowClick
+   - 菜单按钮用 itemClick
+   - 避免混淆
+
+5. **单据打开回调用 billClosedCallBack**
+   - 不要在打开前后分散写逻辑
+   - 统一由 billClosedCallBack 处理返回
+
+## 常见坑位
+
+### ❌ 在 beforeCreateListDataProvider 修改基础资料引用属性
+```java
+// 错误：破坏缓存
+@Override
+public void beforeCreateListDataProvider(BeforeCreateListDataProviderArgs args) {
+    // 不要修改基础资料字段（如 orgname、deptname）
+    args.getQueryStatement().getSelectItems().add("org.name");  // 错误！
+}
+
+// 正确：只修改非基础资料字段
+args.getQueryStatement().getSelectItems().add("customfield");
+```
+
+### ❌ beforeItemClick 与 itemClick 逻辑混用
+```java
+// 错误：重复执行
+@Override
+public void beforeItemClick(ItemClickEvent e) {
+    // 在此修改单据状态  
+}
+
+@Override
+public void itemClick(ItemClickEvent e) {
+    // 在此又修改了同样的状态  → 重复！
+}
+
+// 正确：职责分离
+beforeItemClick → 检查权限、校验
+itemClick → 执行操作
+```
+
+### ❌ 逐行处理链路中循环查库
+```java
+// 错误：性能灾难
+for (每一行) {
+    queryDatabase();  // ❌ 10000 行数据 = 10000 次查询
+}
+
+// 正确：提前准备数据
+@Override
+public void beforeCreateListDataProvider(...) {
+    // 一次查询获取所有需要的数据
+    Map<String, Object> dataCache = queryAllDataOnce();
+    // 后续逐行逻辑直接从缓存取值
+}
+```
+
+### ❌ filterContainerSearchClick 中添加过滤后忘记调用 super
+```java
+// 错误
+@Override
+public void filterContainerSearchClick(FilterContainerSearchClickArgs args) {
+    args.addFilter(...);
+    // 忘记调用 super.filterContainerSearchClick(args);
+}
+
+// 正确
+@Override
+public void filterContainerSearchClick(FilterContainerSearchClickArgs args) {
+    args.addFilter(...);
+    super.filterContainerSearchClick(args);  // 必须调用
+}
+```
+
+### ❌ listRowClick 中修改列表数据
+- 行点击时不要直接修改数据源
+- 应该打开编辑界面或触发操作，而非在列表里直接改
+
+### ❌ 超链接点击不处理异常
+```java
+@Override
+public void billListHyperLinkClick(HyperLinkClickEvent e) {
+    try {
+        // 跳转或打开
+    } catch (Exception ex) {
+        // 必须捕获，否则列表可能崩溃
+    }
+}
+```

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

@@ -0,0 +1,112 @@
+# 开放平台自定义 API（注解模式）
+
+## TL;DR
+- 适用：注解模式自定义 OpenAPI 控制器，不再走旧版 `IBillWebApiPlugin`。
+- 先抓：`@ApiController`、`@ApiMapping`、方法路由与参数/返回注解。
+- 跳转：普通后台服务或插件不是本页；这里解决的是 HTTP 接口声明。
+- 继续读全文：当你要确认路径规则、异常返回、旧版差异或完整示例时。
+
+## 概述
+新版本自定义 API 已切换为注解驱动模式，不再使用旧版 `IBillWebApiPlugin` 接口扩展方式。
+
+> **适用边界**
+> ✅ 本文档直接使用：OpenAPI 控制器无封装层，注解模式直接参考本文档。
+
+- 推荐模式：`@ApiController` + `@ApiMapping` + `@ApiGetMapping/@ApiPostMapping`
+- 适用版本：文档基于 Cosmic V8.0.1（更新时间 2026-01）
+- 注解包：`kd.bos.openapi.common.custom.annotation`
+
+## 核心基类
+该模式不是“继承插件基类”，而是“声明式控制器”。
+
+### 1) 类级注解
+- `@ApiController(value = "应用编码", desc = "描述")`
+  - `value` 必填：应用编码（如 `bos`、`open`）
+- `@ApiMapping("/前缀")`
+  - 可选：类级路由前缀
+
+### 2) 方法级注解
+- `@ApiGetMapping("/path")`
+  - 适合基础类型参数场景
+- `@ApiPostMapping("/path")`
+  - 适合复杂对象、Map、集合等
+
+### 3) 参数与返回注解
+- `@ApiParam`：参数说明/必填/示例
+- `@ApiRequestBody`：POST 且单参数 Model 场景（请求体直解）
+- `@ApiResponseBody`：返回值说明（标在 `CustomApiResult<T>` 的 `T` 上）
+- `@ApiModel`：Model 标识
+
+## 核心事件
+
+注解模式没有传统插件回调接口，核心触发点是路由命中后的方法执行：
+
+- `@ApiGetMapping`：// GET 路由命中后执行方法，适合基础类型参数查询
+- `@ApiPostMapping`：// POST 路由命中后执行方法，适合复杂对象/集合/Map 入参
+- `@ApiParam`：// 参数描述与必填约束（可配 `required/example`）
+- `@ApiRequestBody`：// POST 单参数模型的请求体映射
+- `@ApiResponseBody`：// 返回泛型描述，增强 API 文档可读性
+
+## 常用 API/注解写法
+
+```java
+@ApiController(value = "open", desc = "用户API")
+@ApiMapping("/user")
+public class UserController implements java.io.Serializable {
+
+    @ApiGetMapping("/get")
+    public CustomApiResult<String> getUserNameById(
+        @ApiParam(value = "用户ID", required = true) Long id
+    ) {
+        // ...
+        return CustomApiResult.success("Tom");
+    }
+
+    @ApiPostMapping("/save")
+    public CustomApiResult<@ApiResponseBody("true-成功，false-失败") Boolean> saveUser(
+        @ApiParam(value = "用户数据", required = true) @jakarta.validation.Valid UserModel user
+    ) {
+        // ...
+        return CustomApiResult.success(Boolean.TRUE);
+    }
+}
+```
+
+## 示例代码
+
+示例代码统一维护在模板文件中，直接参考：
+
+- [OpenApiControllerTemplate.java](../../../assets/OpenApiControllerTemplate.java)
+
+## 请求路径规则
+
+自定义 API 请求地址：
+
+`/v2/{ISV}/{appId}/{api_number}`
+
+其中：
+- `{api_number}` = 类级 `@ApiMapping` + 方法级 `@ApiPostMapping/@ApiGetMapping`
+- 当开发商标识为 `kingdee` 时，`{ISV}` 在某些场景可不显示（以平台实际网关配置为准）
+
+## 实践建议
+
+1. 类级统一加 `@ApiMapping`，方法只写尾路径，便于维护。
+2. 参数必填优先用 `@ApiParam(required = true)` + JSR 校验注解（`@NotNull`、`@Min`）。
+3. 复杂入参优先 Model（`@ApiModel`），避免散装 `Map` 带来的类型风险。
+4. 返回值统一 `CustomApiResult<T>`，并补 `@ApiResponseBody` 说明。
+5. GET 仅用于基础类型参数查询；复杂对象统一 POST。
+
+## 常见坑位
+
+- 继续按旧版 `IBillWebApiPlugin` 写法开发，导致新版本无法按预期发布/治理。
+- 同一方法同时使用 `@ApiParam` 与 `@ApiRequestBody` 造成入参解析歧义。
+- 忘记 `implements Serializable`（控制器/模型）导致序列化与工具链问题。
+- Model 字段未标 `@ApiParam`，文档与参数解析表现不完整。
+- 返回非 `CustomApiResult<T>`，导致平台响应规范与错误码治理失效。
+
+## 与旧版模式对照
+
+- 旧版：`IBillWebApiPlugin#doCustomService(...)` 接口回调
+- 新版：`@ApiController` 注解声明式控制器
+
+结论：新项目与迁移改造均应优先采用注解模式。