@shundoo-ai/dsh-cosmic 1.0.21 → 1.0.22

package/skills/cosmic-build/knowledge/cosmic/platform/scenes/report/report-subtotal-total.md

@@ -0,0 +1,139 @@
+---
+version: "1.0.0"
+framework_version: "8.0.1"
+source_doc: "标品报表案例 05、08"
+last_updated: "2026-10-19"
+status: "approved"
+scene_name: "报表小计与合计行"
+related_apis: ["DataSet.addField", "DataSet.copy", "DataSet.groupBy", "DataSet.select", "DataSet.union", "DataSet.orderBy", "DataSet.removeFields", "GroupbyDataSet.sum", "GroupbyDataSet.avg", "GroupbyDataSet.finish", "PackageDataEvent.getRowData", "PackageDataEvent.setFormatValue", "PackageDataEvent.getNoMergeKey", "ReportColumn.getFieldKey", "DynamicObject.getInt", "QueryServiceHelper.queryDataSet"]
+topic: "报表数据查询"
+---
+
+# 场景：报表小计与合计行
+
+## 适用情况
+报表在数据中间显示小计行——比如每个组织的明细之后——并显示一行带标签的合计，如"小计""合计"。`reportlist` 插件在 `query()` 里构造这些行：每个汇总层级一次聚合，每一行带 `sumlevel` 标记，合计行没有值的列用占位补齐，最后一次 `union`、一次 `orderBy`。`reportform` 插件在 `packageData` 中给带标记的行打上标签，并把在这些行上没有意义的列置空。
+
+列的 `Summary` 属性是另一种机制：它给列表加上自带的底部合计行。同一列二者只用其一——列表自带的合计行会把它拿到的每一行都加进去，小计行也不例外。
+
+## 事件/方法说明
+
+- `DataSet.addField("0", "sumlevel")`：标记明细行；`select` 里的 `"1 as sumlevel"` / `"2 as sumlevel"` 标记小计行和合计行
+- `DataSet.groupBy(keys)` + `sum` / `avg` + `finish()`：每个汇总层级一次聚合；不带参数的 `groupBy()` 把所有行聚合成一行
+- `DataSet.select(exprs)`：把每个层级整理成同样的列名、同样的顺序，没有值的列用常量补齐（`"0 as sourcetype"`、`"'' as billno"`）
+- `DataSet.union(other)` 后接 `orderBy(keys)`：各层级按显示顺序交错排列
+- `packageData(PackageDataEvent)`（reportform）：每个单元格触发一次；`getRowData().getInt("sumlevel")` 给出行的层级，`setFormatValue(value)` 替换单元格的显示值，`getNoMergeKey().add(fieldKey)` 让该单元格不参与行融合
+
+## 方法签名
+```java
+// reportlist 插件
+@Override
+public DataSet query(ReportQueryParam queryParam, Object selectedObj) throws Throwable
+
+// reportform 插件
+@Override
+public void packageData(PackageDataEvent packageDataEvent)
+```
+
+## 代码示例
+`extracted` `needs-verification`
+
+取数插件：明细、每个组织一行小计、一行合计，按显示顺序排列：
+
+```java
+package kd.bos.plugin.sample.report.bizcase;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import kd.bos.algo.DataSet;
+import kd.bos.entity.report.AbstractReportListDataPlugin;
+import kd.bos.entity.report.ReportQueryParam;
+import kd.bos.orm.query.QFilter;
+import kd.bos.servicehelper.QueryServiceHelper;
+
+public class ReserveSumReportListDataPlugin extends AbstractReportListDataPlugin {
+
+    private static final String ALGO_NAME = "xxx.report.reservesum";
+    private static final String ENTITY_NUMBER = "xxx_baddebtreserve";
+
+    @Override
+    public DataSet query(ReportQueryParam queryParam, Object selectedObj) throws Throwable {
+        List<QFilter> filters = new ArrayList<>(queryParam.getFilter().getQFilters());
+        // ……过滤面板条件照常在这里追加
+
+        // 明细：层级 0，排序分组与小计同为 0
+        DataSet detail = QueryServiceHelper.queryDataSet(ALGO_NAME, ENTITY_NUMBER,
+                "org.id as org, sourcetype.id as sourcetype, accrualrate, baseamount, accruedamt",
+                filters.toArray(new QFilter[filters.size()]), null)
+                .addField("0", "sumlevel")
+                .addField("0", "sortgroup");
+
+        // 每个组织一行小计。比率不能求和：取平均值带上，界面上置空
+        DataSet subtotal = detail.copy().groupBy(new String[]{"org"})
+                .avg("accrualrate").sum("baseamount").sum("accruedamt").finish()
+                .select(new String[]{"org", "0 as sourcetype", "accrualrate", "baseamount", "accruedamt",
+                        "1 as sumlevel", "0 as sortgroup"});
+
+        // 全部行的合计；它的占位组织会让它排到最前面，所以排序分组为 1
+        DataSet total = detail.copy().groupBy()
+                .avg("accrualrate").sum("baseamount").sum("accruedamt").finish()
+                .select(new String[]{"0 as org", "0 as sourcetype", "accrualrate", "baseamount", "accruedamt",
+                        "2 as sumlevel", "1 as sortgroup"});
+
+        // 各部分的列相同、顺序相同；每行小计跟在它所属组织的明细之后。
+        // 排序键不是报表列，行排好序后就移除
+        return detail.union(subtotal).union(total)
+                .orderBy(new String[]{"sortgroup", "org", "sumlevel", "sourcetype"})
+                .removeFields(new String[]{"sortgroup"});
+    }
+}
+```
+
+表单插件：给带标记的行打标签，置空在这些行上没有意义的列：
+
+```java
+package kd.bos.plugin.sample.report.bizcase;
+
+import kd.bos.dataentity.resource.ResManager;
+import kd.bos.entity.datamodel.events.PackageDataEvent;
+import kd.bos.entity.report.ReportColumn;
+import kd.bos.report.plugin.AbstractReportFormPlugin;
+
+public class ReserveSumReportFormPlugin extends AbstractReportFormPlugin {
+
+    @Override
+    public void packageData(PackageDataEvent packageDataEvent) {
+        super.packageData(packageDataEvent);
+        if (!(packageDataEvent.getSource() instanceof ReportColumn)) {
+            return;
+        }
+        String fieldKey = ((ReportColumn) packageDataEvent.getSource()).getFieldKey();
+        int sumLevel = packageDataEvent.getRowData().getInt("sumlevel");
+        if (sumLevel == 0) {
+            return;
+        }
+        if (sumLevel == 1 && "sourcetype".equals(fieldKey)) {
+            packageDataEvent.setFormatValue(ResManager.loadKDString("小计", "ReserveSumReportFormPlugin_0", "xxx-report"));
+        } else if (sumLevel == 2 && "org".equals(fieldKey)) {
+            packageDataEvent.setFormatValue(ResManager.loadKDString("合计", "ReserveSumReportFormPlugin_1", "xxx-report"));
+        } else if ("accrualrate".equals(fieldKey)) {
+            // 平均出来的比率对合计行的读者没有意义
+            packageDataEvent.setFormatValue(null);
+        }
+        // 合计类的行永远不与周围的明细行融合
+        packageDataEvent.getNoMergeKey().add(fieldKey);
+    }
+}
+```
+
+## 注意事项
+- `union` 要求各部分的列名相同、顺序相同：给每个层级一个列出全部列的 `select`，没有值的列用常量补齐——数字或 id 用 `"0 as x"`，文本用 `"'' as x"`
+- 先按维度、再按 `sumlevel` 排序，每行小计才会跟在它那一组的明细之后。合计行的占位维度（`0`）会让它排到最前面，所以在维度之前给它一个专属排序键（上面的 `sortgroup`），排序后再移除：返回的列就是已声明的报表列
+- `''` 常量没有类型（`UnknownType`），在这样的列上排序会失败；不要把占位文本列放进 `orderBy`，或者先声明它的类型（`report-dataset-assembly.md`）
+- 每个层级都会消费它的输入：在第一次聚合之前，每多一个层级就 `copy()` 一次明细 DataSet
+- 比率取平均（`avg`），不要求和；平均值对读者没有意义时，像标品那样在合计类的行上置空
+- 把 `sumlevel` 也声明为报表列——隐藏（`hide: true`）、`integer`、`fieldKey` 等于它的 `dateIndex`——`packageData` 才能读到它：`reportform` 插件看到的行数据是按已声明的列打包的
+- 用数字标记层级，不要用标签文本：在另一个插件里比较翻译后的标签，翻译不一致就会失效，而 `sumlevel` 的 0 / 1 / 2 不会
+- 合计类行的标签是在 `packageData` 里设置的显示值；数据里仍是占位值。图表等其他消费方先用 `filter("sumlevel=0")` 去掉合计类的行
+- 大数据量下多次 union 和排序都会重新执行算子；给算法键起好名字，让耗时在性能监控里看得出来

package/skills/cosmic-build/knowledge/cosmic/platform/scenes/report/report-tree-data-query.md

@@ -5,14 +5,16 @@ source_doc: "bos-runtime-plugin 报表示例"
 last_updated: "2026-04-03"
 status: "approved"
 scene_name: "报表树数据插件"
-related_apis: ["AbstractReportTreeDataPlugin", "TreeNode", "query", "ReportQueryParam", "addChild"]
+related_apis: ["AbstractReportTreeDataPlugin.query", "TreeNode.addChild", "TreeNode.setId", "TreeNode.setParentid", "TreeNode.setText", "TreeNode.setLeaf", "TreeNode.setIsOpened", "TreeNode.setChildren", "ReportQueryParam.getFilter", "FilterInfo.getDynamicObjectCollection", "QueryServiceHelper.queryDataSet"]
 topic: "报表树数据"
 ---
 
 # 场景：报表树数据插件
 
 ## 适用情况
-实现报表左侧树形导航的数据构造，用于左树右表布局的报表。通过重写 `query` 方法返回树节点列表，用户点击树节点后，节点数据会传递给右侧报表数据查询插件的 `query` 方法的 `selectedObj` 参数。适用于按组织、部门、分类等维度展示树形导航的报表场景。
+实现报表左侧树形导航的数据构造，用于左树右表布局的报表。通过重写 `query` 方法返回树节点列表，用户点击树节点后，节点 id 会传递给右侧报表数据查询插件的 `query` 方法的 `selectedObj` 参数。适用于按组织、部门、分类等维度展示树形导航的报表场景。
+
+没有任何公共报表模板预置左树（`bos_grouprpttpl` 是分组报表）：只有用户在设计器里新增「报表树」控件（`ReportTreeAp`）后报表才有左树。本插件通过 `setReportProperties --target tree` 注册在该左树自己的位置 `ReportTreeAp.ReportPlugin`——绝不作为 `reportPlugins` 条目，那是右侧列表的取数插件。
 
 ## 事件/方法说明
 
@@ -77,12 +79,14 @@ 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.bos.orm.query.QCP;
 import kd.bos.orm.query.QFilter;
+import kd.bos.servicehelper.QueryServiceHelper;
 
 public class ReportTreeDataDynamicSample extends AbstractReportTreeDataPlugin {
 
+    private static final String PARENT = "parent";
+
     @Override
     public List<TreeNode> query(ReportQueryParam queryParam, String nodeId) throws Throwable {
         List<TreeNode> nodes = new ArrayList<>();
@@ -90,22 +94,21 @@ public class ReportTreeDataDynamicSample extends AbstractReportTreeDataPlugin {
         // 构建查询条件：首次加载查根节点，展开时查子节点
         List<QFilter> filters = new ArrayList<>();
         if (nodeId == null || "0".equals(nodeId)) {
-            filters.add(new QFilter("parent", QCP.equals, 0L));
+            filters.add(new QFilter(PARENT, QCP.equals, 0L));
         } else {
-            filters.add(new QFilter("parent", QCP.equals, Long.parseLong(nodeId)));
+            filters.add(new QFilter(PARENT, QCP.equals, Long.parseLong(nodeId)));
         }
 
-        ORM orm = ORM.create();
-        DataSet ds = orm.queryDataSet(getClass().getName(),
+        DataSet ds = QueryServiceHelper.queryDataSet(getClass().getName(),
                 "bos_org", "id,number,name,parent,isleaf",
-                filters.toArray(new QFilter[0]), "number");
+                filters.toArray(new QFilter[filters.size()]), "number");
         try {
             while (ds.hasNext()) {
                 Row row = ds.next();
                 TreeNode node = new TreeNode();
                 node.setId(String.valueOf(row.getLong("id")));
                 node.setText(row.getString("number") + " " + row.getString("name"));
-                node.setParentid(String.valueOf(row.getLong("parent")));
+                node.setParentid(String.valueOf(row.getLong(PARENT)));
                 node.setLeaf(row.getBoolean("isleaf"));
                 node.setIsOpened(false);
                 nodes.add(node);
@@ -119,11 +122,104 @@ public class ReportTreeDataDynamicSample extends AbstractReportTreeDataPlugin {
 }
 ```
 
+一次构建整棵树，跟随过滤面板，挂在一个固定的根节点下：
+
+```java
+package kd.bos.plugin.sample.report.bizcase;
+
+import java.util.ArrayList;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Set;
+
+import kd.bos.algo.DataSet;
+import kd.bos.algo.Row;
+import kd.bos.dataentity.entity.DynamicObject;
+import kd.bos.dataentity.entity.DynamicObjectCollection;
+import kd.bos.dataentity.resource.ResManager;
+import kd.bos.entity.report.AbstractReportTreeDataPlugin;
+import kd.bos.entity.report.FilterInfo;
+import kd.bos.entity.report.ReportQueryParam;
+import kd.bos.entity.tree.TreeNode;
+import kd.bos.orm.query.QCP;
+import kd.bos.orm.query.QFilter;
+import kd.bos.servicehelper.QueryServiceHelper;
+
+public class CustomerTreeReportPlugin extends AbstractReportTreeDataPlugin {
+
+    private static final String ALGO_NAME = "xxx.report.customertree";
+    // 取数插件把这个 id 理解为"不收窄"
+    private static final String ROOT_ID = "all";
+
+    @Override
+    public List<TreeNode> query(ReportQueryParam queryParam, String nodeId) throws Throwable {
+        // 树与右侧的行使用同样的面板条件
+        FilterInfo filter = queryParam.getFilter();
+        List<QFilter> filters = new ArrayList<>(2);
+        filters.add(new QFilter("billstatus", QCP.equals, "C"));
+        DynamicObjectCollection orgs = filter.getDynamicObjectCollection("org");
+        if (orgs != null && !orgs.isEmpty()) {
+            List<Object> orgIds = new ArrayList<>(orgs.size());
+            for (DynamicObject org : orgs) {
+                orgIds.add(org.getPkValue());
+            }
+            filters.add(new QFilter("org", QCP.in, orgIds));
+        }
+        // 一次查出所有节点，每个客户一行
+        DataSet customers = QueryServiceHelper.queryDataSet(ALGO_NAME, "xxx_salesorder",
+                "customer.id as customer, customer.name as name, customer.masterid as masterid",
+                filters.toArray(new QFilter[filters.size()]), null)
+                .groupBy(new String[]{"customer", "name", "masterid"}).finish();
+        List<TreeNode> children = new ArrayList<>(16);
+        Set<Long> seenMasters = new HashSet<>(16);
+        try {
+            while (customers.hasNext()) {
+                Row row = customers.next();
+                Long masterId = row.getLong("masterid");
+                // 同一个逻辑客户可能有多个 id：每个 masterid 只保留一个节点
+                if (masterId != null && masterId != 0L && !seenMasters.add(masterId)) {
+                    continue;
+                }
+                TreeNode node = new TreeNode();
+                node.setId(String.valueOf(row.getLong("customer")));
+                node.setParentid(ROOT_ID);
+                node.setText(row.getString("name"));
+                node.setLeaf(true);
+                children.add(node);
+            }
+        } finally {
+            customers.close();
+        }
+        TreeNode root = new TreeNode();
+        root.setId(ROOT_ID);
+        root.setParentid("");
+        root.setText(ResManager.loadKDString("全部", "CustomerTreeReportPlugin_0", "xxx-report"));
+        root.setIsOpened(true);
+        root.setChildren(children);
+        List<TreeNode> nodes = new ArrayList<>(1);
+        nodes.add(root);
+        return nodes;
+    }
+}
+```
+
+右侧的 `reportlist` 插件按被点击节点的 id 收窄它的行：
+
+```java
+// selectedObj 是被点击节点的 id；根节点表示所有客户
+if (selectedObj != null && !"all".equals(String.valueOf(selectedObj))) {
+    filters.add(new QFilter("customer", QCP.equals, Long.valueOf(String.valueOf(selectedObj))));
+}
+```
+
 ## 注意事项
 - `query` 为抽象方法，必须实现，返回 `List<TreeNode>` 不可为 null
 - 此插件不继承 AbstractFormPlugin，不能调用 `getView()`、`getModel()` 等表单方法
 - 首次加载时 `nodeId` 为 null，必须处理此情况并返回根节点列表
-- `TreeNode` 的 ID 必须唯一，否则树节点展示异常
-- 用户点击树节点后，节点对应的数据对象会传递给 reportlistdata 插件的 `query` 方法的 `selectedObj` 参数
-- 使用 ORM 查询构建树节点时，DataSet 必须在遍历完成后关闭
+- `TreeNode` 的 ID 必须唯一，否则树节点展示异常——并且跨次查询保持稳定，否则选中态与它的行会脱钩
+- 用户点击树节点后，节点的 id（`TreeNode.getId()`，`String`）会传递给 reportlistdata 插件的 `query` 方法的 `selectedObj` 参数；想清楚根节点的 id 对取数插件意味着什么（这里的 "all"：不收窄），把它构造成固定值，不要拼接子节点 id
+- 树跟随过滤面板：从 `queryParam.getFilter()` 读取取数插件同样读取的条件，用它们限定节点范围或选择实体（标品按往来方向过滤在应付单与应收单之间切换）
+- 基础资料做过个性化处理后，同一个逻辑记录可能有多个物理 id；按 `masterid` 去重，否则同一个客户会出现两次，它的行在根节点下会被重复计算
+- 一次批量查出节点；逐行加载记录（循环里 `loadSingle`）只适合少量节点
+- 使用 `QueryServiceHelper` 查询构建树节点时，DataSet 必须在遍历完成后关闭
 - `TreeNode.setLeaf(false)` 使节点显示展开箭头，叶子节点使用 `setLeaf(true)`。不存在 `setIsParent` 设置方法 —— 惰加载场景用 `setChildren(new ArrayList<>())` 表示子节点尚未加载

package/skills/cosmic-build/knowledge/cosmic/platform/scenes/report/report-tree-list.md

@@ -0,0 +1,181 @@
+---
+version: "1.0.0"
+framework_version: "8.0.1"
+source_doc: "报表插件示例 示例5、示例8；标品报表案例 11"
+last_updated: "2026-10-19"
+status: "approved"
+scene_name: "折叠树形报表列表"
+related_apis: ["AbstractReportFormPlugin.setTreeReportList", "TreeReportListEvent.setTreeReportList", "TreeReportListEvent.setTreeExpandColId", "ReportQueryParam.setTreeReportList", "ReportList.expandAllNode", "ReportList.collapseAllNode", "Algo.create", "Algo.createDataSet", "RowMeta.getField", "Field.setDataType", "DataSet.getRowMeta", "QueryServiceHelper.queryDataSet"]
+topic: "报表树数据"
+---
+
+# 场景：折叠树形报表列表
+
+## 适用情况
+同一个报表行集以可折叠的树形展示：分组行可以展开成它的明细行，可能有多层——成本项下挂单据、期间下挂单据。这里不涉及树插件，也不涉及报表树控件。由 `reportform` 插件开启树形展示，`reportlist` 取数插件把层级关系作为普通行返回，每行带三列：`rowid`、`pid`、`isgroupnode`。
+
+这不是左树导航。列表旁边的左树是另一个 `reporttreelist` 插件，用在用户给报表新增的报表树控件上，注册在 `ReportTreeAp.ReportPlugin`——见 `report-tree-data-query.md`。
+
+## 事件/方法说明
+
+- `setTreeReportList(TreeReportListEvent)`（reportform）：`event.setTreeReportList(true)` 让列表以树形渲染，`event.setTreeExpandColId(columnKey)` 把展开控件放在该列上。在 `beforeQuery` 中调用 `ReportQueryParam.setTreeReportList(true)` 效果相同
+- `ReportList.expandAllNode()` / `collapseAllNode()`（7.0.1 及以后）：一键展开或收起所有节点，通常由两个工具栏按钮触发
+- 取数插件返回的行列：
+
+| 列 | 类型 | 值 |
+|---|---|---|
+| `rowid` | 文本 | 行自身的 id，在结果中唯一 |
+| `pid` | 文本 | 父行的 `rowid`；顶层行为 `"0"` |
+| `isgroupnode` | 整数 | 可折叠的分组行为 `1`，明细行为 `0` |
+
+## 方法签名
+```java
+// reportform 插件
+@Override
+public void setTreeReportList(TreeReportListEvent event)
+
+// reportlist 插件
+@Override
+public DataSet query(ReportQueryParam queryParam, Object selectedObj) throws Throwable
+```
+
+## 代码示例
+`extracted` `needs-verification`
+
+表单插件：开启树形展示，并从工具栏一键展开 / 收起：
+
+```java
+package kd.bos.plugin.sample.report.bizcase;
+
+import java.util.EventObject;
+
+import kd.bos.form.control.events.ItemClickEvent;
+import kd.bos.report.ReportList;
+import kd.bos.report.events.TreeReportListEvent;
+import kd.bos.report.plugin.AbstractReportFormPlugin;
+
+public class CostTreeReportFormPlugin extends AbstractReportFormPlugin {
+
+    @Override
+    public void registerListener(EventObject e) {
+        super.registerListener(e);
+        this.addItemClickListeners("toolbarap");
+    }
+
+    @Override
+    public void setTreeReportList(TreeReportListEvent event) {
+        super.setTreeReportList(event);
+        event.setTreeReportList(true);
+        // 承载展开控件的列
+        event.setTreeExpandColId("itemname");
+    }
+
+    @Override
+    public void itemClick(ItemClickEvent evt) {
+        super.itemClick(evt);
+        ReportList reportList = this.getControl("reportlistap");
+        if (reportList == null) {
+            return;
+        }
+        // 两个工具栏项，各自绑定一个 donothing 操作
+        if ("expand".equals(evt.getItemKey())) {
+            reportList.expandAllNode();
+        } else if ("collapse".equals(evt.getItemKey())) {
+            reportList.collapseAllNode();
+        }
+    }
+}
+```
+
+取数插件：每个成本项一行分组行，后面跟着它的明细行：
+
+```java
+package kd.bos.plugin.sample.report.bizcase;
+
+import java.math.BigDecimal;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Objects;
+
+import kd.bos.algo.Algo;
+import kd.bos.algo.DataSet;
+import kd.bos.algo.DataType;
+import kd.bos.algo.Field;
+import kd.bos.algo.Row;
+import kd.bos.algo.RowMeta;
+import kd.bos.entity.report.AbstractReportListDataPlugin;
+import kd.bos.entity.report.ReportQueryParam;
+import kd.bos.orm.query.QFilter;
+import kd.bos.servicehelper.QueryServiceHelper;
+
+public class CostTreeReportListDataPlugin extends AbstractReportListDataPlugin {
+
+    private static final String ALGO_NAME = "xxx.report.costtree";
+    private static final String ENTITY_NUMBER = "xxx_costrecord";
+    private static final String TOP_PID = "0";
+    private static final int AMOUNT = 5;
+
+    @Override
+    public DataSet query(ReportQueryParam queryParam, Object selectedObj) throws Throwable {
+        List<QFilter> filters = new ArrayList<>(queryParam.getFilter().getQFilters());
+        // ……过滤面板条件照常在这里追加
+
+        // 按分组键排序，同一组的明细才会相邻
+        DataSet detail = QueryServiceHelper.queryDataSet(ALGO_NAME, ENTITY_NUMBER,
+                "costitem.name as itemname, billno, amount",
+                filters.toArray(new QFilter[filters.size()]), "costitem.name, billno");
+
+        RowMeta rowMeta = new RowMeta(new Field[]{
+                new Field("rowid", DataType.StringType),
+                new Field("pid", DataType.StringType),
+                new Field("isgroupnode", DataType.IntegerType),
+                new Field("itemname", DataType.StringType),
+                new Field("billno", DataType.StringType),
+                new Field("amount", DataType.BigDecimalType)});
+        List<Object[]> rows = new ArrayList<>(16);
+        Object[] group = null;
+        int groupNo = 0;
+        int detailNo = 0;
+        try {
+            while (detail.hasNext()) {
+                Row row = detail.next();
+                String item = row.getString("itemname");
+                BigDecimal amount = row.getBigDecimal("amount") == null ? BigDecimal.ZERO : row.getBigDecimal("amount");
+                if (group == null || !Objects.equals(item, group[3])) {
+                    // 分组行排在它的明细行之前；它的金额是明细金额之和
+                    groupNo++;
+                    detailNo = 0;
+                    group = new Object[]{"g" + groupNo, TOP_PID, 1, item, "", BigDecimal.ZERO};
+                    rows.add(group);
+                }
+                detailNo++;
+                group[AMOUNT] = ((BigDecimal) group[AMOUNT]).add(amount);
+                // 明细行的 pid 是它所属分组行的 rowid
+                rows.add(new Object[]{"g" + groupNo + "-" + detailNo, group[0], 0, item, row.getString("billno"), amount});
+            }
+        } finally {
+            detail.close();
+        }
+        return Algo.create(ALGO_NAME).createDataSet(rows, rowMeta);
+    }
+}
+```
+
+如果这几列来自查询（`"'' as rowid, '' as pid, 0 as isgroupnode"`），`''` 常量没有类型；像标品那样，在任何 `orderBy` 之前先声明类型：
+
+```java
+for (String name : new String[]{"rowid", "pid"}) {
+    dataSet.getRowMeta().getField(name).setDataType(kd.bos.algo.DataType.StringType);
+}
+```
+
+## 注意事项
+- 这三列是 `rowid`、`pid`、`isgroupnode`，与标品树形报表的构造方式一致。行自身的 id 用 `rowid`，不是 `id`：不要用 `id` / `pid` 代替这三列
+- `rowid` 在结果中唯一，对同样的数据保持稳定；用分组的位置或键来构造（`g1`、`g1-1`）。明细行的 `pid` 是它所属分组行的 `rowid`，顶层行的 `pid` 为 `"0"`
+- 每个分组行先于它的子行输出，与标品一致：标品深度优先遍历行组，先写父行，再写子分组或明细行
+- 分组行的数值来自取数插件——读明细时累加，或用 `groupBy` 聚合——标品也是自己计算每组的汇总行
+- 把 `rowid`、`pid`、`isgroupnode` 像插件读取的其他列一样声明为隐藏报表列（`hide: true`）：行数据按已声明的列打包
+- 某一层由其他层计算得出时（期末 = 累计 − 发出），用内存中的分组模型比用 union 更容易：先收集每组的汇总行和子项，再一次性写出所有行，标品的成本报表就是这样做的
+- 一键展开 / 收起需要两个绑定 donothing 操作的工具栏项，并在 `registerListener` 中注册工具栏监听。报表示例还在 `initialize` 中再注册了一次；这第二次调用不起作用——`Toolbar.addItemClickListener` 会忽略已持有的监听——而且编译边界会拒绝在 `initialize` 中添加的监听（`PLUGIN_SOURCE_LIFECYCLE_MISUSE`），所以只在 `registerListener` 中注册
+- 树形列表上表头过滤默认返回树形结果；报表示例在 `setTreeReportList` 中用 `event.setCol2ndResultMode(TreeDataMode.FLAT)` 设为平铺。该方法和 `TreeDataMode` 在 8.0 SDK 中都不存在——其 `lib/bos` 与 `lib/trd` 的任何类都没有提到这两个名字——所以在 8.0 上不要写；目标是更新的版本时，只有 `references/sdk-inspection.md` 在其 SDK 上找到它后才使用
+- 遍历过的 DataSet 已被消费：需要再次读取时，在第一次遍历之前 `copy()`，并像上面那样关闭插件自己持有的 DataSet

package/skills/cosmic-build/knowledge/cosmic/platform/scenes/system-service/report-plugin-interface.md

@@ -154,3 +154,6 @@ public class ReportFormPluginSample extends AbstractReportFormPlugin {
 - `processRowData` 和 `preProcessExportData` 中不要循环取数，导出时可能有性能问题
 - `packageData` 在数据发送到前端时触发，每个单元格进入一次
 - `setExcelName` 只取 list 的第一个元素作为文件名
+- `setSortAndFilter` 只负责开启表头过滤：报表数据查询插件必须在 `query` 中应用 `getFilter().getTableHeadFilterItems()`（或 `getHeadFilters()`），否则表头过滤不起任何作用——见 `report/report-head-filter.md`
+- `MergeColumnRule`：一个合并字段只能属于一条规则，合并跟随分组字段——只要分组字段的值相同，合并字段就合并，不会比较合并字段自己相邻行的值（`report/report-merge-column.md`）
+- `report/` 下的其他报表场景覆盖了工具栏按钮与行数据、钻取联查、小计合计行、折叠树形列表、查询开关、图表以及报表打印

package/skills/cosmic-build/knowledge/cosmic/platform/scenes/tree/tree-basedata-cascade-confirm.md

@@ -7,7 +7,7 @@ status: "approved"
 scene_name: "树形基础资料级联操作确认"
 trigger_event: "beforeItemClick → confirmCallBack"
 scene_keywords: ["beforeItemClick", "confirmCallBack", "MessageBoxResult", "树形基础资料", "级联删除", "级联禁用", "ConfirmCallBackListener", "invokeOperation"]
-related_apis: ["BeforeItemClickEvent.setCancel", "IFormView.showConfirm", "ConfirmCallBackListener", "MessageBoxClosedEvent", "MessageBoxResult", "IFormView.invokeOperation", "ORM.exists"]
+related_apis: ["BeforeItemClickEvent.setCancel", "IFormView.showConfirm", "ConfirmCallBackListener", "MessageBoxClosedEvent", "MessageBoxResult", "IFormView.invokeOperation", "QueryServiceHelper.query", "QueryServiceHelper.exists"]
 ---
 
 # 场景：树形基础资料级联操作确认
@@ -25,7 +25,7 @@ related_apis: ["BeforeItemClickEvent.setCancel", "IFormView.showConfirm", "Confi
 | ConfirmCallBackListener | 确认框回调监听器 | — |
 | MessageBoxClosedEvent | 确认框关闭事件，获取用户选择结果 | — |
 | MessageBoxResult | 用户选择结果枚举（Yes/No/Cancel） | — |
-| ORM | 查询子节点是否存在 | — |
+| QueryServiceHelper | 查询子节点是否存在 | — |
 
 ## 方法签名
 ```java
@@ -57,35 +57,38 @@ import kd.bos.form.MessageBoxOptions;
 import kd.bos.form.MessageBoxResult;
 import kd.bos.form.control.events.BeforeItemClickEvent;
 import kd.bos.form.events.MessageBoxClosedEvent;
-import kd.bos.orm.ORM;
 import kd.bos.orm.query.QCP;
 import kd.bos.orm.query.QFilter;
+import kd.bos.servicehelper.QueryServiceHelper;
 
 public class XxxTreeBaseDataPlugin extends AbstractBasePlugIn {
 
+    private static final String ENTITY_NUMBER = "target_entity";
+    private static final String LONG_NUMBER = "longnumber";
+    private static final String BAR_DISABLE = "bar_disable";
+
     @Override
     public void beforeItemClick(BeforeItemClickEvent evt) {
         super.beforeItemClick(evt);
-        if ("bar_disable".equals(evt.getItemKey())
+        if (BAR_DISABLE.equals(evt.getItemKey())
                 || "bar_delete".equals(evt.getItemKey())) {
             // 查询当前节点的长编码
-            ORM orm = ORM.create();
             Object pkValue = this.getModel().getDataEntity().getPkValue();
             QFilter q = new QFilter("id", QCP.equals, pkValue);
-            DynamicObjectCollection col = orm.query(
-                    "target_entity", "id,longnumber", new QFilter[]{q});
+            DynamicObjectCollection col = QueryServiceHelper.query(
+                    ENTITY_NUMBER, "id,longnumber", new QFilter[]{q});
 
             if (col.isEmpty()) {
                 return;
             }
             // 检查是否存在以当前长编码为前缀的子节点
-            String longNumber = col.get(0).getString("longnumber");
-            QFilter childFilter = new QFilter("longnumber", QCP.like,
+            String longNumber = col.get(0).getString(LONG_NUMBER);
+            QFilter childFilter = new QFilter(LONG_NUMBER, QCP.like,
                     longNumber + ".%");
-            if (orm.exists("target_entity", new QFilter[]{childFilter})) {
+            if (QueryServiceHelper.exists(ENTITY_NUMBER, new QFilter[]{childFilter})) {
                 // 存在子节点，拦截操作并弹出确认框
                 evt.setCancel(true);
-                if ("bar_disable".equals(evt.getItemKey())) {
+                if (BAR_DISABLE.equals(evt.getItemKey())) {
                     this.getView().showConfirm("禁用提示",
                             "当前节点有下级，此次禁用将禁用所有下级，是否继续？",
                             MessageBoxOptions.YesNo, null,

package/skills/cosmic-build/knowledge/cosmic/platform/scenes/tree/tree-list-before-item-validate.md

@@ -96,7 +96,7 @@ public class XxxTreeListPlugin extends StandardTreeListPlugin {
         super.beforeItemClick(evt);
         if ("tbldel".equals(evt.getItemKey())) {
             // 校验是否选中了数据
-            if (((IListView) getView()).getSelectedRows().size() > 0) {
+            if (!((IListView) getView()).getSelectedRows().isEmpty()) {
                 // 弹出二次确认框
                 ConfirmCallBackListener listener =
                         new ConfirmCallBackListener(DELETE_CONFIRM, this);

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

@@ -99,7 +99,7 @@ public class XxxTreeListPlugin extends AbstractTreeListPlugin {
         } else if (matchIds.size() == 1) {
             return new QFilter(fieldKey, QCP.equals, matchIds.get(0));
         } else {
-            return new QFilter(fieldKey, QCP.in, matchIds.toArray(new String[0]));
+            return new QFilter(fieldKey, QCP.in, matchIds.toArray(new String[matchIds.size()]));
         }
     }
 }