@shundoo-ai/dsh-cosmic 1.0.21 → 1.0.22

package/skills/cosmic-build/knowledge/cosmic/platform/reportlistdata-plugin.md

@@ -41,6 +41,19 @@ getColumns → [用户点击查询] → query(queryParam, null)
 2. 左树右表场景优先使用 `selectedObj` 限定范围。
 3. 大数据量异步查询时使用 `setProgress(int)` 反馈执行进度。
 4. 列控制集中放在 `getColumns`，不要在 `query` 混入列逻辑。
+5. 插件在多次查询之间是无状态的：每次查询都由一个新实例服务，所以成员变量只在一次 `query` 调用内有效，绝不会带到下一次。
+6. 算法名按「模块.业务.方法」命名（例如 `er.checkingpay`）：性能监控里显示的就是这个名字。
+7. 用户需要处理的失败抛 `KDBizException` 并带可读文案。数据来自打开方的辅助视图（例如钻取明细弹窗）可以返回空 DataSet，而不是让整页报错。
+
+## 默认排序契约
+
+Java 交付消费 `reportContract.defaultSorts` 和 `defaultSortPolicy`。规则保留有序的 `fieldKey`、
+`dateIndex` 和方向，数据列名区分大小写。在 `query()` 中优先使用交互式
+`ReportQueryParam.getSortInfo()` 排序，仅把已验证的列 key 映射到 DataSet 列名。
+没有交互排序时才使用默认规则；作用于关联/合并/汇总完成后的最终 DataSet，在分页/导出之前执行，
+保持权限过滤。SortInfo 和 DataSet 排序签名以目标 SDK 为准，禁止拼接未经校验的排序 key 到 SQL。
+多键默认排序与交互覆盖分别验收；源码、编译和注册不证明运行排序。
+禁止用 `InitField` 或 `setReportSorts` 实现：该 API 会污染默认显示列配置。
 
 ## 常见坑位
 
@@ -48,6 +61,10 @@ getColumns → [用户点击查询] → query(queryParam, null)
 - 忽略 `selectedObj`，导致左树右表点击节点后仍返回全量数据。
 - `query` 返回空对象而不是合法 `DataSet`。
 - 在 `query` 里逐行远程调用，导致报表超时。
+- 开启了表头过滤（`ColFilter`，或 `reportform` 插件里的 `setSortAndFilter`）却没在 `query` 里应用 `getTableHeadFilterItems()`：表头过滤就不起任何作用。
+- 把同一个 DataSet 遍历两次。每次遍历都会消费它，所以还要再用时，必须在第一次遍历之前先 `copy()`。
+- 对列名或列顺序不同的两个 DataSet 做 `union`。
+- 按 `'' as pid` 这类常量字符串列排序：它的类型未知，把该列显式声明为 `DataType.StringType` 之前 `orderBy` 会失败。
 
 ## 生成策略选择
 
@@ -61,11 +78,23 @@ getColumns → [用户点击查询] → query(queryParam, null)
 | 是 | 否 | 分批查询（覆写 `queryBatchBy`） | `scenes/report/report-batch-query.md` |
 | 否 | 左树 | 用被点击节点的 `selectedObj` 收窄数据行；树本身是另一个 `reporttreelist` 插件 | `scenes/report/report-tree-data-query.md` |
 | 是 | 左树 | 分批查询 + `selectedObj` 收窄 | `report-batch-query.md` + `report-tree-data-query.md` |
+| 否 | 折叠式行 | 普通查询，数据行另带 `rowid` / `pid` / `isgroupnode`；由 `reportform` 插件开启树形 | `scenes/report/report-tree-list.md` |
+
+「左树」指左树右表导航，它是另一个插件（`AbstractReportTreeDataPlugin`，返回 `List<TreeNode>`），注册在
+左树上，不是本插件 DataSet 的某种形态。把同一批行折叠渲染由 `reportform` 插件开启
+（`setTreeReportList` / `setTreeExpandColId`），本插件随后把数据行组织成层级：`rowid` 是每行自己的 id，
+`pid` 是父行的 `rowid`，`isgroupnode` 标记分组行。不要用 `id` / `pid` 代替它们。
 
-这里的「树」指左树右表导航，它是另一个插件（`AbstractReportTreeDataPlugin`，返回
-`List<TreeNode>`），不是本插件 DataSet 的某种形态。把同一批行折叠渲染属于 `reportform` 的职责
-（`setTreeReportList` / `setTreeExpandColId`），在本插件里不需要任何特殊处理。两者都没有关于
-`id` / `pid` DataSet 列的文档约定。
+其他需求同样对应到场景。把适用的场景作为 intent 的 `scenes` 条目传给
+`prepare_plugin_handoff.py`，它会把场景的 SDK 引用展开成 import：
+
+| 需求 | 场景 |
+|---|---|
+| 报表列上的表头过滤或排序 | `report/report-head-filter` |
+| 小计与总计行 | `report/report-subtotal-total` |
+| 链式聚合、一张报表两个来源、手工构造数据行 | `report/report-dataset-assembly` |
+| 由钻取打开、通过自定义参数传值的明细报表 | `report/report-hyperlink-drill` |
+| 打印报表的数据行（另一个注册在打印模板上的 `printplugin` 类） | `report/report-print-data` |
 
 **所有策略的强制规则**：
 1. 必须定义 `private static final String ALGO_NAME` 用于可追溯性
@@ -88,10 +117,88 @@ getColumns → [用户点击查询] → query(queryParam, null)
     `query` 与 `getColumns` 都声明了 `throws Throwable` —— 见
     `scenes/report/report-list-data-query.md` 的 Method Signatures 段。声明它总能编译；只有覆写不调用 `super` 时才能收窄掉，
     不要去「修」已经声明它的示例。API 页能确定的是 `abstract`，这也是 `query` 不带 `super` 调用的原因
+12. 开启了表头过滤就必须应用它：`getTableHeadFilterItems()` 返回原始条目（列 key、比较符、值），
+    `getHeadFilters()` 返回同样的条件转成的 `QFilter`，只有列 key 就是所查实体的字段 key 时才能直接用
+13. 每次遍历都会消费 DataSet；要读两次就在第一次遍历前 `copy()`，并关闭本插件自己持有的副本
+14. `union` 要求两边列名相同、顺序一致：缺少的列用常量补齐（`select` 里写 `"0 amount"`，
+    或 `addField("0", "amount")`）
+
+## 把过滤条件变成查询条件
+
+过滤面板条件以 `FilterItemInfo` 条目从 `getFilterItems()` 传入，每条有 `getPropName()`、
+`getCompareType()` 和 `getValue()`。面板 key 就是所查实体自己的字段 key 时，条目可以原样转发为
+`new QFilter(item.getPropName(), item.getCompareType(), item.getValue())`。不是时 —— app-build
+的 `flt_<列>` key、`q_` 前缀、`org.id` 这样带点的基础资料路径 —— 先映射到源字段，绝不转发没有任何
+源字段拥有的 key。
+
+按 key 读取单个条件时用强类型访问器：多选基础资料过滤用 `getDynamicObjectCollection(key)`，其余有
+`getDynamicObject(key)`、`getDate(key)`、`getBoolean(key)` 和 `getString(key)`。拆分的日期范围、F7
+身份与别名冲突以 `references/report-filter-contract.md` 为准。固定业务规则 —— 只取已审核单据、
+排除某类单据 —— 在 `query()` 里追加：插件是收口这些规则的唯一位置。
+
+表头过滤是另一个条件来源，在同一次查询里应用：
+
+```java
+List<QFilter> filters = new ArrayList<>(filter.getQFilters());
+List<FilterItemInfo> headItems = filter.getTableHeadFilterItems();
+if (headItems != null) {
+    for (FilterItemInfo item : headItems) {
+        // HEAD_FILTER_FIELDS 把报表列 key 映射到它被选出时的源字段。
+        String field = HEAD_FILTER_FIELDS.get(item.getPropName());
+        if (field != null && item.getValue() != null) {
+            filters.add(new QFilter(field, item.getCompareType(), item.getValue()));
+        }
+    }
+}
+```
+
+由 `query()` 计算出来的列没有源字段，要在计算之后再过滤。
+
+`queryParam.getCustomParam()` 承载的是面板条件之外的值：`reportform` 插件在 `verifyQuery` 里放进去的东西，
+或钻取打开方传进来的东西。读取时做空判断，并使用稳定的 key，例如参数对象的类全名。
+
+## 组装 DataSet
+
+一次查询带回报表要用的全部字段（包括 `currency.id` 这样的关联字段），再用 DataSet 算子加工结果，
+而不是回头再查库：
+
+- `select` 做投影、改名和计算：`"TO_CHAR(happenddate, 'yyyy.MM') as periodcol"` 把日期变成期间列；
+- `groupBy(keys)` 配 `sum`、`avg`、`min`、`max` 或 `count`，再 `finish()`，完成聚合；`orderBy` 放在
+  `finish()` 之后，只能引用聚合后仍存在的列。比率取平均，绝不求和；
+- `addField(expression, alias)` 派生新列，`filter(expression)` 剔除行，
+  `case when x is null then 0 else x end` 防止 null 参与运算；
+- 两个来源共享同一维度时，`union` 之后要再 `groupBy` 一次，让每个维度值只有一行。
+
+数据来自内存而不是查询时手工构造：`Algo.create(ALGO_NAME).createDataSet(rows, new RowMeta(fields))`，
+按行内顺序每列一个 `Field`，类型取自 `dataSetColumnTypes`。常量字符串列要显式声明
+`DataType.StringType`。长 id 列表按每次几百个值分批查询，而不是一个无上限的 `in`。完整写法见
+`{ROOT_DIR}/knowledge/cosmic/platform/scenes/report/report-dataset-assembly.md`。
+
+## 小计与合计行
+
+列的 `Summary` 属性给列表带来它自己的合计行；数据内部的小计行，以及夹在数据行中间、带标签的合计行，
+由 `query()` 构造。每个合计层级聚合一次，每行打上 `sumlevel` 标记列（0 明细、1 小计、2 总计），
+合计行没有值的列用占位补齐，然后把各层 `union` 起来，再按分组列、`sumlevel` 的顺序 `orderBy`，
+总计行用它专属的排序键排在最后。
+`reportform` 插件在 `packageData` 里给这些行打标签，并清空对它们无意义的列；只有 `sumlevel`
+是已声明的（隐藏）报表列时，它才读得到。见
+`{ROOT_DIR}/knowledge/cosmic/platform/scenes/report/report-subtotal-total.md`。
+
+## 分批查询规则
+
+- 分批依据列必须把数据分成均衡的批次；优先用必录过滤字段或排序字段。
+- `queryBatchBy` 的结果会全部缓存在内存里，所以只返回一两列分批依据。
+- 返回的分批依据要先排序，让每一批是一段连续范围。
+- `setCountPerBatch(n)` 设置每批的分批依据行数，`setMaxRowCountCached(n)` 设置内存最多缓存的行数，
+  默认 100,000。
+- `query` 从 `byBatchInfo().getCurrentBatchRows()` 读取当前批并据此收窄；`queryBatchBy` 返回 `null`
+  时执行一次普通查询。既不读当前批行也不读 `selectedObj` 的分批 `query` 会每批都返回全部行，编译边界
+  会拒绝它（`PLUGIN_SOURCE_BATCH_NOT_NARROWED`）。
+- 分批不是分页：一批数据可供几十到几百个列表分页。
 
 ## 骨架模板
 
-> 适用：`reportlist`。继承 `AbstractReportListDataPlugin`（`kd.bos.entity.report.AbstractReportListDataPlugin`），**不是**表单插件，不能调用 `getView()` / `getModel()`。`query` 为抽象方法必须实现。类名后缀按 `{PluginSuffix}` 命名。注册方式：在苍穹报表模板配置中注册数据插件类全限定名。
+> 适用：`reportlist`。继承 `AbstractReportListDataPlugin`（`kd.bos.entity.report.AbstractReportListDataPlugin`），**不是**表单插件，不能调用 `getView()` / `getModel()`。`query` 为抽象方法必须实现。类名后缀按 `{PluginSuffix}` 命名。注册方式：把类全限定名声明在报表 artifact 的 `reportPlugins` 里；报表流水线把它注册到报表列表的取数槽位（`ReportQueryPlugin`），`register_plugins.py` 不处理这种类型。
 
 ```java
 package kd.cd.common;
@@ -106,15 +213,15 @@ import java.util.ArrayList;
 import kd.bos.orm.query.QCP;
 
 /**
- * 报表取数插件骨架模板（原生 AbstractReportListDataPlugin）。
- * 该类仅用于示例写法，生成后请按实际业务删除无用事件并替换占位常量。
+ * Skeleton template for a report data plugin (native AbstractReportListDataPlugin).
+ * This class is for example purposes only; remove unused events and replace placeholder constants according to actual business needs after generation.
  */
 public class ReportListDataPluginTemplate extends AbstractReportListDataPlugin {
 
     /**
-     * 触发时机: 在需要了解当前插件可访问上下文能力时调用。
-     * 参数要点: 无入参；仅展示当前插件可通过 this. 访问的方法能力。
-     * 典型用途: 作为模板提示，指导在各事件内选择正确的上下文 API。
+     * Trigger timing: invoked when you need to learn what context capabilities the current plugin can access.
+     * Parameter notes: no input; only demonstrates methods accessible via this. in the current plugin.
+     * Typical use: as a template hint, guiding the selection of the correct context API in each event.
      */
     private void getContextSample() {
         // this.getQueryParam();
@@ -131,11 +238,11 @@ public class ReportListDataPluginTemplate extends AbstractReportListDataPlugin {
     // ===== 核心事件 =====
 
     /**
-     * 触发时机: 报表发起查询时。
-     * 参数要点:
-     * - queryParam.getFilter() 为过滤面板条件。
-     * - selectedObj 为左侧树或左表选中对象。
-     * 典型用途: 按查询条件与左侧选中对象组装 DataSet。
+     * Trigger timing: when the report initiates a query.
+     * Parameter notes:
+     * - queryParam.getFilter() is the condition from the filter panel.
+     * - selectedObj is the object selected in the left tree or left grid.
+     * Typical use: assemble the DataSet according to the query conditions and the object selected on the left.
      */
     @Override
     public DataSet query(ReportQueryParam queryParam, Object selectedObj) {
@@ -151,13 +258,13 @@ public class ReportListDataPluginTemplate extends AbstractReportListDataPlugin {
             if (billNo != null) filters.add(new QFilter(FIELD_BILL_NO, QCP.equals, billNo));
         }
         this.setProgress(20);
-        return QueryServiceHelper.queryDataSet(ALGO_NAME, ENTITY_NUMBER, SELECT_FIELDS, filters.toArray(new QFilter[0]), ORDER_BY);
+        return QueryServiceHelper.queryDataSet(ALGO_NAME, ENTITY_NUMBER, SELECT_FIELDS, filters.toArray(new QFilter[filters.size()]), ORDER_BY);
     }
 
     /**
-     * 触发时机: 报表初始化列定义后。
-     * 参数要点: columns 为系统生成的列集合，可调整显示列属性。
-     * 典型用途: 动态隐藏列、修改列宽、冻结列或调整显示顺序。
+     * Trigger timing: after the report initializes column definitions.
+     * Parameter notes: columns is the column collection generated by the system; display column attributes can be adjusted.
+     * Typical use: dynamically hide columns, modify column width, freeze columns, or adjust display order.
      */
     @Override
     public List<AbstractReportColumn> getColumns(List<AbstractReportColumn> columns) throws Throwable {
@@ -167,10 +274,10 @@ public class ReportListDataPluginTemplate extends AbstractReportListDataPlugin {
     }
 
     /**
-     * 触发时机: getColumns 的辅助方法。
-     * 参数要点: nodes 为列树的某一层。
-     * 典型用途: 命中分组内的列。ReportColumnGroup 不是 ReportColumn，因此带强转的扁平循环会在
-     * 第一个分组上抛异常，也永远到不了它 getChildren() 里的列。
+     * Trigger timing: helper for getColumns.
+     * Parameter notes: nodes is one level of the column tree.
+     * Typical use: reach a grouped column. A ReportColumnGroup is not a ReportColumn, so a flat
+     * loop with a cast throws on the first group and never reaches its getChildren() columns.
      */
     private void apply(List<AbstractReportColumn> nodes) {
         for (int i = 0; i < nodes.size(); i++) {

package/skills/cosmic-build/knowledge/cosmic/platform/reporttreedata-plugin.md

@@ -12,6 +12,11 @@ AbstractReportTreeDataPlugin (kd.bos.entity.report.AbstractReportTreeDataPlugin)
 
 报表树数据插件是独立的树数据构造插件，**不继承 AbstractFormPlugin**，不具备表单插件的生命周期和视图操作能力。其核心职责是构造报表左侧树形导航节点数据。当报表需要左树右表布局时，通过此插件提供树节点数据。
 
+它注册在左树自己身上：没有任何公共报表模板预置左树（`bos_grouprpttpl` 是分组报表），所以先由用户在设计器里
+给报表新增「报表树」控件（`ReportTreeAp`），再通过 `setReportProperties --target tree` 把类名写进
+`ReportTreeAp.ReportPlugin`。它绝不是 `reportPlugins` 条目 —— 那个槽位是报表列表的取数插件，树插件类放在那里
+构建不出任何树。右侧的数据行仍然来自那个 `reportlist` 插件。
+
 ## reporttreedata 插件事件
 
 ### reporttreedata 插件事件类型
@@ -26,9 +31,30 @@ AbstractReportTreeDataPlugin (kd.bos.entity.report.AbstractReportTreeDataPlugin)
 ```
 query(queryParam, null)  ← 首次加载，返回根节点列表
   → [用户展开节点] → query(queryParam, parentNodeId)  ← 返回子节点列表
-  → [用户点击节点] → 节点ID传递给 reportlistdata 插件的 query 方法
+  → [用户点击节点] → 节点ID作为 selectedObj 传递给 reportlistdata 插件的 query 方法
 ```
 
+## 构建树
+
+两种形态都可用：
+
+- **懒加载** —— `nodeId` 为 null 时返回根节点，为某节点 id 时返回该节点的子节点。`setLeaf(false)` 的节点
+  显示展开箭头；叶子节点使用 `setLeaf(true)`。
+- **一次构建** —— 返回一个合成的根节点（「全部」，`setParentid("")`、`setIsOpened(true)`），用
+  `setChildren(list)` 挂上全部节点。先约定根节点 id 对取数插件意味着什么 —— 不收窄，或子节点 id
+  集合 —— 并把它构造成确定值，而不是把子节点 id 拼接成字符串。
+
+无论哪种形态：
+
+- 每个 `setId` 的值都唯一，并在多次查询之间保持稳定；取数插件把它作为 `selectedObj` 接收，在两次查询
+  之间变化的 id 会让选中态与其数据行脱节；
+- 树跟随过滤面板：从 `queryParam.getFilter()` 读取与取数插件相同的条件
+  （`getDynamicObjectCollection(key)`、`getDate(key)`、`getString(key)`），由它们选定实体并限定节点范围；
+- 基础资料经个性化处理后，同一个逻辑记录可能有多个物理 id；按 `masterid` 去重，否则同一往来方会
+  出现两次，点击根节点时它的数据也会被重复计算；
+- 节点要批量查询：只有节点很少时才可以接受逐行 `loadSingle`；
+- 节点 DataSet 只遍历一次并关闭，就像骨架里那样。
+
 
 
 ### TreeNode 构建规范
@@ -40,17 +66,18 @@ node.setText(number + " " + name);        // 节点显示文本
 node.setParentid(parentId);               // 父节点ID（根节点设为固定值如 "0"）
 node.setLeaf(false);                      // 非叶子节点，因此显示展开箭头
 node.setIsOpened(false);                  // 是否默认展开
+root.setChildren(children);               // 一次构建的树：根节点挂上它的子节点
 ```
 
 
 
 ## 骨架模板
 
-> 适用：`reporttreelist`。继承 `AbstractReportTreeDataPlugin`（`kd.bos.entity.report.AbstractReportTreeDataPlugin`），**不是**表单插件，不能调用 `getView()` / `getModel()`。`query` 为抽象方法必须实现。类名后缀按 `{PluginSuffix}` 命名。注册方式：在苍穹报表模板配置中注册树数据插件类全限定名。
+> 适用：`reporttreelist`。继承 `AbstractReportTreeDataPlugin`（`kd.bos.entity.report.AbstractReportTreeDataPlugin`），**不是**表单插件，不能调用 `getView()` / `getModel()`。`query` 为抽象方法必须实现。类名后缀按 `{PluginSuffix}` 命名。注册方式：左树自己的槽位，即用户给报表新增的报表树控件上的 `ReportTreeAp.ReportPlugin` —— 不是 `reportPlugins`。
 
 ```java
 /**
- * Kingdee Cosmic 报表树数据插件模板（自动生成）
+ * Kingdee Cosmic report tree data plugin template (auto-generated)
  * Author: [your-name] | Date: [yyyy-MM-dd]
  */
 package kd.{isv}.{module}.formplugin;
@@ -63,8 +90,9 @@ import kd.bos.algo.Row;
 import kd.bos.entity.report.AbstractReportTreeDataPlugin;
 import kd.bos.entity.report.ReportQueryParam;
 import kd.bos.entity.tree.TreeNode;
-import kd.bos.orm.ORM;
-// import kd.{isv}.{module}.business.XxxUtils;
+import kd.bos.orm.query.QCP;
+import kd.bos.orm.query.QFilter;
+import kd.bos.servicehelper.QueryServiceHelper;
 
 /** {功能描述} */
 public class Xxx{PluginSuffix} extends AbstractReportTreeDataPlugin {
@@ -76,30 +104,22 @@ public class Xxx{PluginSuffix} extends AbstractReportTreeDataPlugin {
     @Override
     public List<TreeNode> query(ReportQueryParam queryParam, String nodeId) {
         List<TreeNode> treeNodes = new ArrayList<>();
-
-        // 方式一：ORM 查询构建树节点
-        // DataSet ds = ORM.create().queryDataSet(this.getClass().getName(),
-        //         TREE_ENTITY_ID, TREE_SELECT_FIELDS, null, "number asc");
-        // while (ds.hasNext()) {
-        //     Row row = ds.next();
-        //     TreeNode node = new TreeNode();
-        //     node.setId(String.valueOf(row.get("id")));
-        //     node.setText(row.getString("number") + " " + row.getString("name"));
-        //     node.setParentid(row.get("parent") == null ? ROOT_NODE_ID : String.valueOf(row.get("parent")));
-        //     node.setLeaf(false);
-        //     treeNodes.add(node);
-        // }
-        // ds.close();
-
-        // 方式二：手动构建固定树节点
-        // TreeNode rootNode = new TreeNode();
-        // rootNode.setId("root"); rootNode.setText("全部");
-        // rootNode.setParentid(ROOT_NODE_ID); rootNode.setLeaf(false);
-        // treeNodes.add(rootNode);
-
+        // DCS 禁止 ORM/DB 访问；通过 QueryServiceHelper 查询并传入有效业务过滤条件
+        QFilter[] filters = {new QFilter("enable", QCP.equals, "1")};
+        try (DataSet ds = QueryServiceHelper.queryDataSet(this.getClass().getName(),
+                TREE_ENTITY_ID, TREE_SELECT_FIELDS, filters, "number asc")) {
+            while (ds.hasNext()) {
+                Row row = ds.next();
+                Object parent = row.get("parent");
+                TreeNode node = new TreeNode();
+                node.setId(String.valueOf(row.get("id")));
+                node.setText(row.getString("number") + " " + row.getString("name"));
+                node.setParentid(parent == null ? ROOT_NODE_ID : String.valueOf(parent));
+                node.setLeaf(false);
+                treeNodes.add(node);
+            }
+        }
         return treeNodes;
     }
-
-    // private void updateProgress(int progress) { this.setProgress(progress); }
 }
 ```

package/skills/cosmic-build/knowledge/cosmic/platform/scenes/_index.md

@@ -14,7 +14,7 @@
 | Container, 折叠, collapse, 展开, 收起 | Container 折叠控制 | `control/container/container-collapse.md` | approved | `afterBindData` | `Container` | `billform,mobform,mobbill,form,baseform` |
 | EntryGrid, 行绑定, beforeEntryBindRow, 行控件状态 | EntryGrid 数据绑定监听 | `control/entry-grid/entry-grid-bind-data.md` | approved | `beforeEntryBindRow` | `EntryGrid` | `billform,mobform,mobbill,form` |
 | EntryGrid, deleteEntryRow, 空行, 倒序删除 | 分录空行删除 | `control/entry-grid/entry-grid-delete-empty-row.md` | approved | — | `EntryGrid` | `billform,mobform,mobbill,form` |
-| FilterGrid, 过滤条件, 反序列化, 注入 | FilterGrid 动态过滤条件设置 | `control/filter-grid/filter-grid-set-value.md` | approved | — | `FilterGrid` | `listform,moblist` |
+| FilterGrid, 过滤条件, 反序列化, 注入 | FilterGrid 动态过滤条件设置 | `control/filter-grid/filter-grid-set-value.md` | approved | — | `FilterGrid` | `form,billform,baseform,listform,moblist` |
 | Tab, 标签页, 切换, 懒加载, tabSelected | Tab 标签页选择监听 | `control/tab/tab-selected.md` | approved | `tabSelected` | `Tab` | `billform,mobform,mobbill,form,baseform` |
 | BillList, 列表弹窗, getSelectedRows, ListShowParameter | 列表插件打开表单 | `control/list/list-show-form.md` | approved | `itemClick` | `BillList` | `listform,moblist` |
 | BillList, 列隐藏, getShowListColumns, IListColumn | 列表列动态隐藏 | `control/list/list-column-hide.md` | approved | — | `BillList` | `listform,moblist` |
@@ -274,12 +274,21 @@
 | 关键词 | 场景名 | 文件 | 状态 | pluginType |
 |-------|-------|------|------|------------|
 | AbstractReportListDataPlugin, 报表数据查询, query, DataSet, ORM, Algo | 报表数据查询插件 | `report/report-list-data-query.md` | approved | `reportlist` |
-| AbstractReportTreeDataPlugin, 报表树数据, TreeNode, 树节点, 左树右表 | 报表树数据插件 | `report/report-tree-data-query.md` | approved | `reporttreelist` |
+| AbstractReportTreeDataPlugin, 报表树数据, TreeNode, 树节点, 左树右表, ReportTreeAp | 报表树数据插件 | `report/report-tree-data-query.md` | approved | `reporttreelist` |
 | ReportQueryParam, 报表参数, 查询条件, 过滤 | 报表查询参数 | `report/report-verify-query.md` | approved | `reportform,reportlist,reporttreelist` |
 | ReportColumn, 报表列, 动态列, setFieldKey, setCaption, setFieldType | 报表动态列属性 | `report/report-flex-property.md` | approved | `reportform,reportlist,reporttreelist` |
 | 报表合并列, 合并列, ReportColumn, 报表 | 报表合并列 | `report/report-merge-column.md` | approved | `reportform,reportlist,reporttreelist` |
 | 报表汇总, 总计, 小计, 分组汇总, 报表 | 报表汇总类型 | `report/report-total-type.md` | approved | `reportform,reportlist,reporttreelist` |
-| 报表批量查询, 批量数据, 分页查询, 大数据量 | 报表批量查询 | `report/report-batch-query.md` | approved | `reportlist,reporttreelist` |
+| queryBatchBy, 报表分批取数, 分批依据, IReportBatchQueryInfo, 大数据量 | 报表分批取数 | `report/report-batch-query.md` | approved | `reportlist,reporttreelist` |
+| setSortAndFilter, beforeCreateFilterInfo, getTableHeadFilterItems, getHeadFilters, 表头过滤, 表头排序 | 报表表头过滤与排序 | `report/report-head-filter.md` | approved | `reportform,reportlist` |
+| itemClick, 工具栏按钮, addCellClickListener, getRowData, setSelectedAll, 选中行 | 报表工具栏按钮与行数据 | `report/report-row-data-toolbar.md` | approved | `reportform` |
+| hyperLinkClick, 钻取联查, BillShowParameter, ReportShowParameter, filterContainerInit, CommonFilterColumn, 过滤锁定 | 报表超链接钻取与过滤锁定 | `report/report-hyperlink-drill.md` | approved | `reportform,reportlist` |
+| 小计, 合计, sumlevel, union, groupBy, packageData, 合计行标签 | 报表小计与合计行 | `report/report-subtotal-total.md` | approved | `reportlist,reportform` |
+| setTreeReportList, 折叠树形行, rowid, pid, isgroupnode, expandAllNode, collapseAllNode | 折叠树形报表列表 | `report/report-tree-list.md` | approved | `reportform,reportlist` |
+| beforeQuery, setAsyncTotal, setSelectedAll, setAsyncDataCount, getCustomFilter, 大报表 | 报表查询开关 | `report/report-async-query.md` | approved | `reportform,reportlist` |
+| afterQuery, PieChart, PieSeries, ItemValue, 报表图表, 前 N 名 | 报表查询后联动图表 | `report/report-chart.md` | approved | `reportform` |
+| select, groupBy, union, addField, copy, RowMeta, createDataSet, 双数据源, UnknownType | 报表 DataSet 组装 | `report/report-dataset-assembly.md` | approved | `reportlist` |
+| AbstractPrintPlugin, afterLoadData, loadCustomData, ReportListModel, DataRowSet, 报表打印 | 报表打印数据 | `report/report-print-data.md` | approved | `printplugin` |
 
 ## ①① KWC 控制器场景（kwc/）
 

package/skills/cosmic-build/knowledge/cosmic/platform/scenes/common/attachment-name-process.md

@@ -42,45 +42,49 @@ import kd.bos.entity.datamodel.events.PropertyChangedArgs;
 import java.util.stream.Collectors;
 
 public class AllContractFileBillPlugin extends AbstractBillPlugIn {
+    private static final String ATTACHMENT = "attachment";
+
     @Override
     public void propertyChanged(PropertyChangedArgs e) {
         super.propertyChanged(e);
         String formId = this.getView().getEntityId();
         String fileEntry = "cngc_entryentity";
-        String fileFiled = "attachment";
+        String fileField = ATTACHMENT;
         String fileName = "attachname";
 
         // 根据表单ID映射不同的字段名
         switch (formId) {
             case "mscon_contract":
                 fileEntry = "attentry";
-                fileFiled = "attachment";
-                fileName = "attachment";
+                fileField = ATTACHMENT;
+                fileName = ATTACHMENT;
                 break;
             case "mscon_reviewtask":
                 fileEntry = "attentry";
-                fileFiled = "attachment";
+                fileField = ATTACHMENT;
                 fileName = "attachmentname";
                 break;
             case "cngc_signoff_cancel":
                 fileEntry = "entryentity";
-                fileFiled = "cngc_fj";
+                fileField = "cngc_fj";
                 fileName = "cngc_attachmentname";
                 break;
-            // 其他表单类型映射...
+            default:
+                // 未列出的表单沿用默认字段映射。
+                break;
         }
 
-        if (fileFiled.equalsIgnoreCase(e.getProperty().getName())) {
-            setFileName(fileEntry, fileFiled, fileName);
+        if (fileField.equalsIgnoreCase(e.getProperty().getName())) {
+            setFileName(fileEntry, fileField, fileName);
         }
     }
 
-    private void setFileName(String fileEntry, String fileFiled, String fileName) {
-        DynamicObject this_model = this.getModel().getDataEntity(true);
-        DynamicObjectCollection this_model_col = this_model.getDynamicObjectCollection(fileEntry);
-        this_model_col.stream().forEach(item -> {
+    private void setFileName(String fileEntry, String fileField, String fileName) {
+        DynamicObject dataEntity = this.getModel().getDataEntity(true);
+        DynamicObjectCollection entries = dataEntity.getDynamicObjectCollection(fileEntry);
+        entries.stream().forEach(item -> {
             MulBasedataDynamicObjectCollection attachment =
-                (MulBasedataDynamicObjectCollection) item.get(fileFiled);
+                (MulBasedataDynamicObjectCollection) item.get(fileField);
             String fileNames = attachment.stream()
                 .map(i -> ((DynamicObject) i.get("fbasedataid")).get("name").toString())
                 .collect(Collectors.joining("；"));

package/skills/cosmic-build/knowledge/cosmic/platform/scenes/common/dynamic-update-field.md

@@ -44,9 +44,9 @@ import kd.bos.url.UrlService;
 import java.util.Arrays;
 
 public class WhPictureSaveSubmitAuditFormPlugin extends AbstractBillPlugIn {
-    private static final String save = "bar_save";
-    private static final String submit = "bar_submit";
-    private static final String audit = "bar_audit";
+    private static final String SAVE = "bar_save";
+    private static final String SUBMIT = "bar_submit";
+    private static final String AUDIT = "bar_audit";
     private static final String PICTURE = "cngc_picture";
 
     @Override
@@ -55,7 +55,7 @@ public class WhPictureSaveSubmitAuditFormPlugin extends AbstractBillPlugIn {
         String itemKey = evt.getItemKey();
         DynamicObject dataEntity = this.getView().getModel().getDataEntity();
 
-        if (Arrays.asList(save, submit, audit).contains(itemKey)) {
+        if (Arrays.asList(SAVE, SUBMIT, AUDIT).contains(itemKey)) {
             // 从基础资料查询图片
             DynamicObject[] picturesIds = BusinessDataServiceHelper.load(
                 "ide_pictureresediter", "id,fnumber,fname",

package/skills/cosmic-build/knowledge/cosmic/platform/scenes/control/filter-grid/filter-grid-set-value.md

@@ -21,7 +21,7 @@ related_apis: ["FilterGrid.SetValue", "FilterCondition", "SerializationUtils.fro
 ## 涉及的核心对象（必读）
 | 对象 | 用途 | 文档路径 |
 |------|------|---------|
-| FilterGrid | 通用过滤控件，接收 FilterCondition 对象 | output/platform/form/core/view.md |
+| FilterGrid | 通用过滤控件，接收 FilterCondition 对象 | knowledge/cosmic/platform/core/view.md |
 | FilterCondition | 过滤条件数据对象 | — |
 | SerializationUtils | JSON 反序列化工具 | — |
 

package/skills/cosmic-build/knowledge/cosmic/platform/scenes/control/list/filter-basedatafield.md

@@ -42,13 +42,12 @@ import kd.bos.orm.query.QFilter;
 
 @Override
 public void filterColumnSetFilter(SetFilterEvent args) {
-    System.err.println("filterColumnSetFilter");
     if ("basedatafield2.name".equals(args.getFieldName()))
     {
-        sargs.addCustomQFilter(new QFilter("name", QFilter.equals, "test123"));
+        args.addCustomQFilter(new QFilter("name", QFilter.equals, "test123"));
     }
 
-// 基础资料依赖于上面的选择字段orgfield1,将orgfield1的已选中值添加到basedatafield2
+    // 基础资料依赖于上面的选择字段orgfield1,将orgfield1的已选中值添加到basedatafield2
     if ("basedatafield2.name".equals(args.getFieldName())) {
         FilterColumnSetFilterEvent args2 = (FilterColumnSetFilterEvent) args;
         args.addCustomQFilter(new QFilter("name", QFilter.equals, args2.getCommonFilterValue("orgfield1.number")));

package/skills/cosmic-build/knowledge/cosmic/platform/scenes/control/list/filter-container-init.md

@@ -43,7 +43,6 @@ import kd.bos.form.events.FilterContainerInitArgs;
 
 @Override
 public void filterContainerInit(FilterContainerInitArgs args) {
-    System.err.println("filterContainerInit");
     FilterColumn filterColumn = args.getFilterColumn("datefield");
     filterColumn.setDefaultValues("2019-1-30", "2019-1-31");
     FilterColumn filterColumn2 = new FilterColumn("textfield");

package/skills/cosmic-build/knowledge/cosmic/platform/scenes/control/list/filter-popup.md

@@ -41,7 +41,6 @@ import kd.bos.orm.query.QFilter;
 
 @Override
 public void filterContainerBeforeF7Select(BeforeFilterF7SelectEvent args) {
-    System.err.println("filterContainerBeforeF7Select");
     if ("basedatafield2.name".equals(args.getFieldName()))
         args.addCustomQFilter(new QFilter("name", QFilter.equals, "test123"));
 

package/skills/cosmic-build/knowledge/cosmic/platform/scenes/control/list/filter-value-parse.md

@@ -53,12 +53,11 @@ import kd.bos.form.events.FilterContainerSearchClickArgs;
 
 @Override
 public void filterContainerSearchClick(FilterContainerSearchClickArgs args) {
-    System.err.println("filterContainerSearchClick");
-    System.err.println(args.getFilterValue("datefield"));
-    System.err.println(args.getFastFilterValues());
-    System.err.println(args.getQFilter("datefield"));
-    System.err.println(args.getSelectMainOrgIds());
-    args.addConstFilter("datefield", CompareTypeEnum.TODAY);
+    // 通过 getFilterValue / getFastFilterValues / getQFilter / getSelectMainOrgIds 读取值；
+    // 不通过 System.out/err 打印，DCS 不允许这种写法（CVE-KD-0209-1）
+    if (args.getFilterValue("datefield") == null) {
+        args.addConstFilter("datefield", CompareTypeEnum.TODAY);
+    }
     args.addFastFilter("textfield", "test");
     args.addFilter("textfield", CompareTypeEnum.EQUAL, "123");
     super.filterContainerSearchClick(args);

package/skills/cosmic-build/knowledge/cosmic/platform/scenes/control/list/list-show-form.md

@@ -46,7 +46,7 @@ public class OpenBillFromListPlugin extends AbstractListPlugin {
         super.itemClick(evt);
         if ("btn_open".equals(evt.getItemKey())) {
             ListSelectedRowCollection selectedRows = this.getSelectedRows();
-            if (selectedRows.size() == 0) {
+            if (selectedRows.isEmpty()) {
                 this.getView().showMessage("请选择数据");
                 return;
             }

package/skills/cosmic-build/knowledge/cosmic/platform/scenes/control/list/query-field-dynamic.md

@@ -44,7 +44,6 @@ beforecreatelistcolumnsargs.getDynamicTextListColumns()
 ```java
 import kd.bos.form.events.BeforeCreateListColumnsArgs;
 import kd.bos.list.ComboListColumn;
-import kd.bos.list.IListColumn;
 import kd.bos.list.MergeListColumn;
 
 @Override
@@ -55,12 +54,6 @@ public void beforeCreateListColumns(BeforeCreateListColumnsArgs beforecreatelist
     mergeListColumn.setKey("mergelistcolumn");
     mergeListColumn.getItems().add(comboListColumn);
     beforecreatelistcolumnsargs.addListColumn(mergeListColumn);
-    IListColumn listColumn = beforecreatelistcolumnsargs.getListColumn("textfield");
-    System.err.println("beforeCreateListColumns");
-    System.err.println(listColumn);
-    System.err.println(beforecreatelistcolumnsargs.getDynamicTextListColumns());
-    System.err.println(beforecreatelistcolumnsargs.getMergeListColumns());
-    System.err.println(beforecreatelistcolumnsargs.getListGroupColumns());
     super.beforeCreateListColumns(beforecreatelistcolumnsargs);
 }
 ```