@shundoo-ai/dsh-cosmic 1.0.21 → 1.0.22

package/skills/cosmic-build/knowledge/cosmic/platform/scenes/report/report-dataset-assembly.md

@@ -0,0 +1,200 @@
+---
+version: "1.0.0"
+framework_version: "8.0.1"
+source_doc: "标品报表案例 01、02、08、11"
+last_updated: "2026-10-19"
+status: "approved"
+scene_name: "报表 DataSet 组装"
+related_apis: ["DataSet.select", "DataSet.groupBy", "DataSet.orderBy", "DataSet.union", "DataSet.addField", "DataSet.filter", "DataSet.copy", "DataSet.getRowMeta", "GroupbyDataSet.sum", "GroupbyDataSet.min", "GroupbyDataSet.finish", "RowMeta.getFieldNames", "RowMeta.getField", "Field.setDataType", "Algo.create", "Algo.createDataSet", "FilterInfo.getFilterItems", "FilterInfo.getQFilters", "FilterItemInfo.getPropName", "FilterItemInfo.getCompareType", "FilterItemInfo.getValue", "ReportQueryParam.getCustomParam", "QueryServiceHelper.queryDataSet"]
+topic: "报表数据查询"
+---
+
+# 场景：报表 DataSet 组装
+
+## 适用情况
+报表的行不是一次查询的原始行：要按期间聚合、要把两个列不同的来源合并、要用打开方传来的值在内存中构造。`reportlist` 插件用一次查询带回所需的全部字段，再用 DataSet 算子加工结果，而不是回头再查数据库。它返回的 DataSet 就是报表：列名就是报表列的 `dateIndex`，区分大小写。
+
+## 事件/方法说明
+
+- `QueryServiceHelper.queryDataSet(algoKey, entity, fields, filters, orderBy)`：一次查询；关联字段按路径带回（`currency.id as currency`）
+- `select(exprs)`：投影、改名（`server as servercol`）和表达式（`TO_CHAR(happenddate, 'yyyy.MM') as periodcol`）
+- `groupBy(keys)` + `sum` / `avg` / `min` / `max` + `finish()`：聚合；`finish()` 之前什么都不会执行
+- `orderBy(new String[]{"periodcol desc"})`：排序，用的必须是此时存在的列
+- `union(other)`：合并两个列相同、顺序相同的 DataSet 的行
+- `addField(expression, alias)`：派生列；`filter(expression)`：过滤行
+- `copy()`：得到第二份可消费的副本；每次遍历都会消费 DataSet
+- `Algo.create(algoKey).createDataSet(rows, rowMeta)`：由 `Object[]` 行和带类型 `Field` 的 `RowMeta` 构造 DataSet
+
+## 方法签名
+```java
+@Override
+public DataSet query(ReportQueryParam queryParam, Object selectedObj) throws Throwable
+```
+
+## 代码示例
+`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.FilterItemInfo;
+import kd.bos.entity.report.ReportQueryParam;
+import kd.bos.orm.query.QCP;
+import kd.bos.orm.query.QFilter;
+import kd.bos.servicehelper.QueryServiceHelper;
+
+public class CheckingPayReportListDataPlugin extends AbstractReportListDataPlugin {
+
+    private static final String ALGO_NAME = "xxx.report.checkingpay";
+    private static final String ENTITY_NUMBER = "xxx_orderbill";
+
+    @Override
+    public DataSet query(ReportQueryParam queryParam, Object selectedObj) throws Throwable {
+        List<QFilter> filters = new ArrayList<>(queryParam.getFilter().getQFilters());
+        for (FilterItemInfo item : queryParam.getFilter().getFilterItems()) {
+            if (item.getValue() != null && isForwarded(item.getPropName())) {
+                filters.add(new QFilter(item.getPropName(), item.getCompareType(), item.getValue()));
+            }
+        }
+        // 固定的业务规则写在这里，写在拥有这次查询的插件里
+        filters.add(new QFilter("producttype", QCP.not_equals, "2"));
+
+        // 一次查询带回全部字段，关联 id 也一起带回
+        DataSet bills = QueryServiceHelper.queryDataSet(ALGO_NAME, ENTITY_NUMBER,
+                "company.id as company, operationtype, happenddate, totalamount, payamount, currency.id as currency",
+                filters.toArray(new QFilter[filters.size()]), null);
+        // 投影并计算、聚合，再按聚合后仍存在的列排序
+        return bills.select(new String[]{"company as companycol", "operationtype as operationtypecol",
+                        "TO_CHAR(happenddate, 'yyyy.MM') as periodcol", "totalamount as totalamountcol",
+                        "payamount as payamountcol", "currency as currencycol"})
+                .groupBy(new String[]{"companycol", "operationtypecol", "periodcol"})
+                .sum("totalamountcol").sum("payamountcol").min("currencycol")
+                .finish()
+                .orderBy(new String[]{"periodcol desc"});
+    }
+
+    // 本身就是实体字段标识的面板键，可以原样转发.
+    // DCS 禁止静态集合字段（CVE-KD-0056），通过方法返回局部集合。
+    private static boolean isForwarded(String key) {
+        return "operationtype".equals(key) || "happenddate".equals(key);
+    }
+}
+```
+
+两个列不同的来源：对齐到同一列清单，union，再聚合一次：
+
+```java
+package kd.bos.plugin.sample.report.bizcase;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+
+import kd.bos.algo.DataSet;
+import kd.bos.algo.GroupbyDataSet;
+
+public final class PartnerBalanceMerger {
+
+    private static final String[] DIMENSIONS = {"org", "partner", "currency"};
+    private static final String[] AMOUNTS = {"receivableamt", "payableamt"};
+
+    private PartnerBalanceMerger() {
+    }
+
+    public static DataSet merge(DataSet arDataSet, DataSet apDataSet) {
+        // 两边列名相同、顺序相同；缺少的金额列补 0
+        DataSet ar = arDataSet.select(aligned(Arrays.asList(arDataSet.getRowMeta().getFieldNames())));
+        DataSet ap = apDataSet.select(aligned(Arrays.asList(apDataSet.getRowMeta().getFieldNames())));
+        // 两边都有的往来户现在是两行：再聚合一次
+        GroupbyDataSet grouped = ar.union(ap).groupBy(DIMENSIONS);
+        for (String amount : AMOUNTS) {
+            grouped = grouped.sum(amount);
+        }
+        // 轧差余额；空值兜底让缺失的一边不参与运算
+        grouped = grouped.sum("(case when payableamt is null then 0 else payableamt end)"
+                + " - (case when receivableamt is null then 0 else receivableamt end)", "netamt");
+        return grouped.finish();
+    }
+
+    private static String[] aligned(List<String> present) {
+        List<String> select = new ArrayList<>(Arrays.asList(DIMENSIONS));
+        for (String amount : AMOUNTS) {
+            select.add(present.contains(amount) ? amount : "0 " + amount);
+        }
+        return select.toArray(new String[select.size()]);
+    }
+}
+```
+
+用打开方传来的值在内存中构造行；结果为空时仍带有已声明的列：
+
+```java
+package kd.bos.plugin.sample.report.bizcase;
+
+import java.math.BigDecimal;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+
+import kd.bos.algo.Algo;
+import kd.bos.algo.DataSet;
+import kd.bos.algo.DataType;
+import kd.bos.algo.Field;
+import kd.bos.algo.RowMeta;
+import kd.bos.entity.report.AbstractReportListDataPlugin;
+import kd.bos.entity.report.ReportQueryParam;
+
+public class DrillDetailReportListDataPlugin extends AbstractReportListDataPlugin {
+
+    private static final String ALGO_NAME = "xxx.report.drilldetail";
+
+    @Override
+    public DataSet query(ReportQueryParam queryParam, Object selectedObj) throws Throwable {
+        // 每列一个 Field，按行内顺序排列，类型与列的声明一致
+        RowMeta rowMeta = new RowMeta(new Field[]{
+                new Field("itemname", DataType.StringType),
+                new Field("amount", DataType.BigDecimalType)});
+        List<Object[]> rows = new ArrayList<>(16);
+        Map<String, Object> custom = queryParam.getCustomParam();
+        Object passed = custom == null ? null : custom.get("rows");
+        if (passed instanceof List) {
+            for (Object value : (List<?>) passed) {
+                List<?> row = (List<?>) value;
+                rows.add(new Object[]{String.valueOf(row.get(0)), new BigDecimal(String.valueOf(row.get(1)))});
+            }
+        }
+        // 辅助性质的视图显示一张空表，而不是让整个页面报错
+        return Algo.create(ALGO_NAME).createDataSet(rows, rowMeta);
+    }
+}
+```
+
+常量文本列在声明类型之前没有类型，在此之前对它排序会失败：
+
+```java
+DataSet rows = QueryServiceHelper.queryDataSet(ALGO_NAME, ENTITY_NUMBER,
+        "'' as bizobject, billno, amount", filters.toArray(new QFilter[filters.size()]), null);
+rows.getRowMeta().getField("bizobject").setDataType(kd.bos.algo.DataType.StringType);
+rows = rows.orderBy(new String[]{"bizobject", "billno"});
+```
+
+## 注意事项
+- 返回的列名就是报表列的 `dateIndex`，区分大小写；`select` 别名（比如统一加 `col` 后缀）让列标识稳定，并与实体字段名区分开
+- 只有面板键本身就是实体字段标识时，才原样转发面板条件；其他键（app-build 的 `flt_<列>` 键、`q_` 前缀、带点的基础资料路径）先映射到源字段——见 `reportlistdata-plugin.md`
+- `groupBy` 及其聚合在 `finish()` 之前什么都不做；`finish()` 之后的 `orderBy` 用聚合后仍存在的列。比率取平均，不要求和
+- 两个共享某个维度的来源 `union` 之后，再聚合一次，让每个维度值只有一行。两边需要列名相同、顺序相同：缺少的列用常量补齐（`select` 里写 `"0 amount"`，或 `addField("0", "amount")`），任何一边加列，另一边都要同步补
+- 在表达式里用 `case when x is null then 0 else x end` 兜底空值：一边补过零的列，在另一边仍可能为空
+- `filter("...")` 和表达式字符串里的列名错误只会在运行期报错；用与 select 列表相同的常量拼接这些字符串
+- 每次遍历——`hasNext()` / `next()`、for-each、画图——都会消费 DataSet。需要再次读取时在第一次遍历之前 `copy()`，并关闭插件自己持有的副本和已遍历的 DataSet；不要关闭它返回的那个 DataSet
+- 手工构造的 `RowMeta` 每列一个 `Field`，按行内顺序排列，类型与声明一致（`DataType.StringType`、`LongType`、`BigDecimalType` 等），每个 `Object[]` 行都按这个顺序
+- `''` 常量列的类型是 `UnknownType`，在声明类型之前对它 `orderBy` 会失败，如最后一段代码所示
+- 很长的 id 列表按每次查询几百个值分批（标品用 400），再把各部分 `union` 起来，不要用一个不受限的 `in`
+- 某一层由其他层计算得出时（期末 = 累计 − 发出），在内存模型上汇集各层，一次性构造行，不要层层 union
+- 插件在两次查询之间不保留状态；算法键是这次查询在性能监控里的名字：用"模块.业务.方法"命名（`er.checkingpay`）

package/skills/cosmic-build/knowledge/cosmic/platform/scenes/report/report-head-filter.md

@@ -0,0 +1,177 @@
+---
+version: "1.0.0"
+framework_version: "8.0.1"
+source_doc: "报表插件示例 示例1；标品报表案例 09"
+last_updated: "2026-10-19"
+status: "approved"
+scene_name: "报表表头过滤与排序"
+related_apis: ["AbstractReportFormPlugin.setSortAndFilter", "AbstractReportFormPlugin.beforeCreateFilterInfo", "SortAndFilterEvent.getColumnName", "SortAndFilterEvent.setSort", "SortAndFilterEvent.setFilter", "CreateFilterInfoEvent.getFieldKey", "CreateFilterInfoEvent.getFilterInfo", "FilterInfo.getTableHeadFilterItems", "FilterInfo.getHeadFilters", "FilterInfo.getQFilters", "FilterItemInfo.getPropName", "FilterItemInfo.getCompareType", "FilterItemInfo.getValue"]
+topic: "报表表头过滤"
+---
+
+# 场景：报表表头过滤与排序
+
+## 适用情况
+用户在报表列头上过滤或排序（列头的漏斗与排序箭头）。这个功能分两半、落在两个插件里：`reportform` 插件按列开启，并可替换某列的过滤选项；`reportlist` 取数插件应用用户选的条件。只开启不应用，列头会出现漏斗，但一行数据也不会变。
+
+## 事件/方法说明
+
+- `setSortAndFilter(List<SortAndFilterEvent>)`（reportform）：列表渲染前每列一个事件；`getColumnName()` 是列标识，`setSort(true)` / `setFilter(true)` 开启该列的表头排序 / 表头过滤
+- `beforeCreateFilterInfo(CreateFilterInfoEvent)`（reportform）：构建某列的表头过滤之前触发；`getFieldKey()` 是列标识，`getFilterInfo().put("comboItems", items)` 替换它的选项——每个选项是含 `id`、`name`（`LocaleString`）、`value` 的 map
+- `FilterInfo.getTableHeadFilterItems()`（reportlist）：用户在列头输入的条件，类型为 `List<FilterItemInfo>`——`getPropName()` 是列标识，`getCompareType()` 是比较符，`getValue()` 是值
+- `FilterInfo.getHeadFilters()`（reportlist）：同样的条件，已转换成 `List<QFilter>`，以列标识为字段
+- `ReportList.setFilter2ndMaxRowCount(int)` / `setOrder2ndMaxRowCount(int)`：限制表头过滤 / 排序支持的行数，见 `report-total-type.md`
+
+## 方法签名
+```java
+// reportform 插件
+@Override
+public void setSortAndFilter(List<SortAndFilterEvent> allColumns)
+
+@Override
+public void beforeCreateFilterInfo(CreateFilterInfoEvent event)
+
+// reportlist 插件
+@Override
+public DataSet query(ReportQueryParam queryParam, Object selectedObj) throws Throwable
+```
+
+## 代码示例
+`extracted` `needs-verification`
+
+第 1 步——表单插件开启表头排序与过滤，并替换某一列的选项：
+
+```java
+package kd.bos.plugin.sample.report.bizcase;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import kd.bos.dataentity.entity.LocaleString;
+import kd.bos.dataentity.resource.ResManager;
+import kd.bos.report.events.CreateFilterInfoEvent;
+import kd.bos.report.events.SortAndFilterEvent;
+import kd.bos.report.plugin.AbstractReportFormPlugin;
+
+public class HeadFilterReportFormPlugin extends AbstractReportFormPlugin {
+
+    // 提供表头过滤的列；所有列都可排序.
+    // 使用 static final 数组，避免 DCS 禁止的静态集合（CVE-KD-0056）
+    private static final String[] FILTER_COLUMNS = {"org", "billstatus", "amount"};
+
+    @Override
+    public void setSortAndFilter(List<SortAndFilterEvent> allColumns) {
+        super.setSortAndFilter(allColumns);
+        for (SortAndFilterEvent column : allColumns) {
+            column.setSort(true);
+            if (Arrays.asList(FILTER_COLUMNS).contains(column.getColumnName())) {
+                column.setFilter(true);
+            }
+        }
+    }
+
+    @Override
+    public void beforeCreateFilterInfo(CreateFilterInfoEvent event) {
+        super.beforeCreateFilterInfo(event);
+        if (!"billstatus".equals(event.getFieldKey())) {
+            return;
+        }
+        // 这些选项替换平台按数据推导出的选项
+        List<Map<String, Object>> comboItems = new ArrayList<>(2);
+        comboItems.add(comboItem("C", ResManager.loadKDString("已审核", "HeadFilterReportFormPlugin_0", "xxx-report")));
+        comboItems.add(comboItem("B", ResManager.loadKDString("已提交", "HeadFilterReportFormPlugin_1", "xxx-report")));
+        event.getFilterInfo().put("comboItems", comboItems);
+    }
+
+    private static Map<String, Object> comboItem(String value, String caption) {
+        Map<String, Object> item = new HashMap<>(4);
+        item.put("id", value);
+        item.put("name", new LocaleString(caption));
+        // 取数插件用来比较的存储值
+        item.put("value", value);
+        return item;
+    }
+}
+```
+
+第 2 步——取数插件在同一次查询里应用表头条件与过滤面板条件：
+
+```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.FilterInfo;
+import kd.bos.entity.report.FilterItemInfo;
+import kd.bos.entity.report.ReportQueryParam;
+import kd.bos.orm.query.QFilter;
+import kd.bos.servicehelper.QueryServiceHelper;
+
+public class HeadFilterReportListDataPlugin extends AbstractReportListDataPlugin {
+
+    private static final String ALGO_NAME = "xxx.report.headfilter";
+    private static final String ENTITY_NUMBER = "xxx_salesorder";
+    private static final String SELECT_FIELDS = "org.id as org, billno, billstatus, amount";
+
+    @Override
+    public DataSet query(ReportQueryParam queryParam, Object selectedObj) throws Throwable {
+        FilterInfo filter = queryParam.getFilter();
+        List<QFilter> filters = new ArrayList<>(filter.getQFilters());
+        // ……过滤面板条件照常在这里追加
+
+        // 表头条件：把每个列标识映射回它的源字段
+        List<FilterItemInfo> headItems = filter.getTableHeadFilterItems();
+        if (headItems != null) {
+            for (FilterItemInfo item : headItems) {
+                String field = sourceField(item.getPropName());
+                if (field != null && item.getValue() != null) {
+                    filters.add(new QFilter(field, item.getCompareType(), item.getValue()));
+                }
+            }
+        }
+        return QueryServiceHelper.queryDataSet(ALGO_NAME, ENTITY_NUMBER, SELECT_FIELDS,
+                filters.toArray(new QFilter[filters.size()]), queryParam.getSortInfo());
+    }
+
+    // 报表列标识 -> 该列取自的源字段; null for any other key.
+    // 使用 switch，避免 DCS 禁止的静态 Map（CVE-KD-0056）
+    private static String sourceField(String columnKey) {
+        if (columnKey == null) {
+            return null;
+        }
+        switch (columnKey) {
+            case "org":
+                return "org.id";
+            case "billstatus":
+            case "amount":
+                return columnKey;
+            default:
+                return null;
+        }
+    }
+}
+```
+
+可过滤列的标识都正好是被查实体自己的字段标识时，可以直接追加转换好的条件：
+
+```java
+List<QFilter> headFilters = queryParam.getFilter().getHeadFilters();
+if (headFilters != null) {
+    filters.addAll(headFilters);
+}
+```
+
+## 注意事项
+- 两半缺一不可：`reportform` 插件里的 `setFilter(true)` 只负责显示漏斗；`reportlist` 插件的 `query()` 必须把表头条件加进查询，否则表头过滤不起任何作用。两个插件中后编译的那个会在缺一半时给出警告（`PLUGIN_REPORT_HEAD_FILTER_UNAPPLIED`）
+- `getHeadFilters()` 以报表列标识作为每个条件的字段，所以只有当列标识就是被查实体的字段标识时才能直接用（如 `report-batch-query.md`）。否则从 `getTableHeadFilterItems()` 取条目，把列标识映射到源字段；不要转发任何源字段都不拥有的标识——查询会在运行期失败
+- `query()` 计算出来的列（轧差金额、期间文本）没有源字段：先算出来，再用 `DataSet.filter(expression)` 过滤行
+- 选项 map 含 `id`、`name`（`LocaleString`）、`value`；`value` 是数据里用来比较的存储值，例如单据状态"已审核"的 `"C"`
+- 大报表可用 `setFilter2ndMaxRowCount` / `setOrder2ndMaxRowCount` 限制表头过滤 / 排序支持的行数（`report-total-type.md`）
+- 折叠树形报表列表上，表头过滤默认以树形返回结果。报表示例在 `setTreeReportList` 里用 `event.setCol2ndResultMode(TreeDataMode.FLAT)` 改为平铺；8.0 SDK 里这两个名字都不存在，所以在 8.0 上不要写；目标是更新的版本时，只有 `references/sdk-inspection.md` 在其 SDK 上找到它后才使用
+- 按标识（`getColumnName()` / `getFieldKey()`）匹配列，不要按标题匹配：标题随语言变化

package/skills/cosmic-build/knowledge/cosmic/platform/scenes/report/report-hyperlink-drill.md

@@ -0,0 +1,216 @@
+---
+version: "1.0.0"
+framework_version: "8.0.1"
+source_doc: "标品报表案例 03、05、08、09、11"
+last_updated: "2026-10-19"
+status: "approved"
+scene_name: "报表超链接钻取与过滤锁定"
+related_apis: ["HyperLinkClickEvent.getFieldName", "HyperLinkClickEvent.getRowData", "HyperLinkClickEvent.getRowIndex", "BillShowParameter.setPkId", "BillShowParameter.setStatus", "FormShowParameter.setFormId", "FormShowParameter.getOpenStyle", "FormShowParameter.setCustomParams", "FormShowParameter.getCustomParams", "FormShowParameter.setHasRight", "OpenStyle.setShowType", "ReportShowParameter.setQueryParam", "IReportView.getQueryParam", "FilterInfo.clone", "FilterInfo.getFilterItem", "FilterItemInfo.setValue", "ReportQueryParam.setFilter", "FilterContainerInitEvent.getCommonFilterColumns", "CommonFilterColumn.setComboItems", "CommonFilterColumn.setMustInput", "FilterColumn.getFieldName", "FilterColumn.setDefaultValue", "BusinessDataServiceHelper.loadSingle"]
+topic: "报表钻取联查"
+---
+
+# 场景：报表超链接钻取与过滤锁定
+
+## 适用情况
+报表单元格是一个链接：点单据编号打开单据，点往来户打开该往来户的明细报表，点物料按该物料重新打开报表。发送端报表的 `reportform` 插件监听超链接点击，用打开参数打开目标；接收端报表读取自己被打开时带来的参数，把过滤面板锁定为钻取值，让用户只看到钻取限定的范围。
+
+## 事件/方法说明
+
+- 在 `registerListener` 中调用 `ReportList.addHyperClickListener(this)`，插件 `implements HyperLinkClickListener`：把超链接单元格路由到 `hyperLinkClick`。列本身必须在报表元数据里配置为超链接列（代码里构建的列用 `ReportColumn.setHyperlink(true)`）
+- `hyperLinkClick(HyperLinkClickEvent)`：`getFieldName()` 是被点击的列，`getRowData()` 返回被点击的行，`getRowIndex()` 是它的行号
+- 三种目标，三种打开参数：
+
+| 目标 | 打开参数 |
+|---|---|
+| 单据 | `BillShowParameter`：`setFormId(单据表单)`、`setPkId(id)`、`setStatus(OperationStatus.VIEW)` |
+| 列表 | `ListShowParameter`：`setFormId("bos_list")`、`setBillFormId(单据表单)`、携带过滤的 `ListFilterParameter`——见 `report-row-data-toolbar.md` |
+| 报表 | `ReportShowParameter`：`setFormId(报表)` 加 `setCustomParams(map)`，或 `setQueryParam(param)` 携带现成的 `FilterInfo` |
+
+- 接收端报表的 `filterContainerInit(FilterContainerInitEvent, ReportQueryParam)`：`getView().getFormShowParameter().getCustomParams()` 是发送端传来的参数，`event.getCommonFilterColumns()` 是过滤面板的常用过滤列
+- `CommonFilterColumn`：`getFieldName()`、`setComboItems(items)`、`setDefaultValue(value)`、`setMustInput(true)` 把一个过滤锁定为钻取值
+
+## 方法签名
+```java
+public class MyReportPlugin extends AbstractReportFormPlugin implements HyperLinkClickListener
+
+@Override
+public void registerListener(EventObject e)
+
+@Override
+public void hyperLinkClick(HyperLinkClickEvent evt)
+
+// 接收端报表
+@Override
+protected void filterContainerInit(FilterContainerInitEvent event, ReportQueryParam queryParam)
+```
+
+## 代码示例
+`extracted` `needs-verification`
+
+发送端报表：每个超链接列一个方法、各自一个目标：
+
+```java
+package kd.bos.plugin.sample.report.bizcase;
+
+import java.util.EventObject;
+import java.util.HashMap;
+import java.util.Map;
+
+import kd.bos.bill.BillShowParameter;
+import kd.bos.bill.OperationStatus;
+import kd.bos.dataentity.entity.DynamicObject;
+import kd.bos.entity.report.FilterInfo;
+import kd.bos.entity.report.FilterItemInfo;
+import kd.bos.entity.report.ReportQueryParam;
+import kd.bos.form.ShowType;
+import kd.bos.form.events.HyperLinkClickEvent;
+import kd.bos.form.events.HyperLinkClickListener;
+import kd.bos.report.IReportView;
+import kd.bos.report.ReportList;
+import kd.bos.report.ReportShowParameter;
+import kd.bos.report.plugin.AbstractReportFormPlugin;
+
+public class DrillReportFormPlugin extends AbstractReportFormPlugin implements HyperLinkClickListener {
+
+    private static final String DETAIL_REPORT = "xxx_partner_detail_rpt";
+    private static final String THIS_REPORT = "xxx_partner_sum_rpt";
+
+    @Override
+    public void registerListener(EventObject e) {
+        super.registerListener(e);
+        ReportList reportList = this.getControl("reportlistap");
+        reportList.addHyperClickListener(this);
+    }
+
+    @Override
+    public void hyperLinkClick(HyperLinkClickEvent evt) {
+        String fieldName = evt.getFieldName();
+        if ("billno".equals(fieldName)) {
+            openBill(evt.getRowData());
+        } else if ("partner".equals(fieldName)) {
+            openDetailReport(evt.getRowData());
+        } else if ("material".equals(fieldName)) {
+            reopenForMaterial(evt.getRowData());
+        }
+    }
+
+    // 单据：只读，新页签打开
+    private void openBill(DynamicObject row) {
+        long billId = row.getLong("billid");
+        if (billId == 0L) {
+            return;
+        }
+        BillShowParameter parameter = new BillShowParameter();
+        parameter.setFormId(row.getString("billformid"));
+        parameter.setPkId(billId);
+        parameter.setStatus(OperationStatus.VIEW);
+        parameter.getOpenStyle().setShowType(ShowType.MainNewTabPage);
+        this.getView().showForm(parameter);
+    }
+
+    // 另一张报表：用自定义参数告诉它是为什么被打开的
+    private void openDetailReport(DynamicObject row) {
+        Map<String, Object> params = new HashMap<>(4);
+        params.put("isopenbyhyperlink", Boolean.TRUE);
+        // 每个值都以接收端报表的过滤字段为键
+        params.put("q_partner", row.getDynamicObject("partner").getPkValue());
+        params.put("q_org", row.getDynamicObject("org").getPkValue());
+        ReportShowParameter parameter = new ReportShowParameter();
+        parameter.setFormId(DETAIL_REPORT);
+        parameter.setCustomParams(params);
+        parameter.getOpenStyle().setShowType(ShowType.MainNewTabPage);
+        this.getView().showForm(parameter);
+    }
+
+    // 带现成查询打开报表：沿用当前条件，只替换其中一个
+    private void reopenForMaterial(DynamicObject row) {
+        IReportView view = this.getView();
+        FilterInfo filter = view.getQueryParam().getFilter().clone();
+        FilterItemInfo material = filter.getFilterItem("material");
+        if (material == null) {
+            return;
+        }
+        material.setValue(row.getDynamicObject("material"));
+        ReportQueryParam queryParam = new ReportQueryParam();
+        queryParam.setFilter(filter);
+        ReportShowParameter parameter = new ReportShowParameter();
+        parameter.setFormId(THIS_REPORT);
+        parameter.setQueryParam(queryParam);
+        parameter.getOpenStyle().setShowType(ShowType.MainNewTabPage);
+        this.getView().showForm(parameter);
+    }
+}
+```
+
+接收端报表：识别钻取打开，把每个被钻取的过滤锁定为钻取值：
+
+```java
+package kd.bos.plugin.sample.report.bizcase;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+
+import kd.bos.dataentity.entity.DynamicObject;
+import kd.bos.dataentity.entity.LocaleString;
+import kd.bos.entity.report.ReportQueryParam;
+import kd.bos.filter.CommonFilterColumn;
+import kd.bos.filter.FilterColumn;
+import kd.bos.form.FormShowParameter;
+import kd.bos.form.control.events.FilterContainerInitEvent;
+import kd.bos.form.field.ComboItem;
+import kd.bos.report.plugin.AbstractReportFormPlugin;
+import kd.bos.servicehelper.BusinessDataServiceHelper;
+
+public class DrilledDetailReportFormPlugin extends AbstractReportFormPlugin {
+
+    @Override
+    protected void filterContainerInit(FilterContainerInitEvent event, ReportQueryParam queryParam) {
+        super.filterContainerInit(event, queryParam);
+        FormShowParameter showParameter = this.getView().getFormShowParameter();
+        Map<String, Object> params = showParameter.getCustomParams();
+        if (!Boolean.TRUE.equals(params.get("isopenbyhyperlink"))) {
+            return;
+        }
+        for (FilterColumn column : event.getCommonFilterColumns()) {
+            if (!(column instanceof CommonFilterColumn)) {
+                continue;
+            }
+            CommonFilterColumn filterColumn = (CommonFilterColumn) column;
+            Object pk = params.get(filterColumn.getFieldName());
+            if (pk == null) {
+                // 没有被钻取：这个过滤保持可选
+                continue;
+            }
+            DynamicObject record = BusinessDataServiceHelper.loadSingle(pk, entityOf(filterColumn.getFieldName()), "name");
+            if (record == null) {
+                continue;
+            }
+            // 钻取值成为唯一选项和默认值，并且该过滤必录
+            List<ComboItem> items = new ArrayList<>(1);
+            items.add(new ComboItem(new LocaleString(record.getString("name")), pk.toString()));
+            filterColumn.setComboItems(items);
+            filterColumn.setDefaultValue(pk.toString());
+            filterColumn.setMustInput(true);
+        }
+    }
+
+    // 每个可锁定的过滤字段背后的基础资料实体
+    private static String entityOf(String fieldName) {
+        return "q_org".equals(fieldName) ? "bos_org" : "bd_customer";
+    }
+}
+```
+
+## 注意事项
+- 不注册监听，超链接点了没反应；元数据里没有超链接列，就没有可点的东西。类里从不调用 `addHyperClickListener` 却覆写了 `hyperLinkClick` 时，编译边界会拒绝它（`PLUGIN_SOURCE_LISTENER_UNREGISTERED`）
+- 一张报表有多个超链接列时，按 `evt.getFieldName()` 分发到每列一个方法，不要写成一个长 `if` 块
+- 点击时从行里读取的每个值——单据 id、单据表单标识、维度——都必须是已声明的报表列，不用于展示时设为隐藏：行数据按已声明的列打包，没有对应列的 DataSet 列读出来什么都没有
+- `setStatus(OperationStatus.VIEW)` 以只读方式打开单据。`setHasRight(true)` 跳过目标的功能权限校验；只有在报表本身已经控制了谁能看到这一行时才使用
+- 中转记录（行上指向真正源单的单据）可能需要在 `hyperLinkClick` 里再查一次：只查一次、只取需要的字段
+- 自定义参数的键是精确匹配的，区分大小写：发送端和接收端对标志和每个维度键的拼写必须完全一致——把它们定义为两个插件共用的常量。结构化的值以 JSON 字符串传递；标品在 `setCustomParam` 之前先把参数对象序列化
+- `setQueryParam(param)` 把一个现成的查询交给接收端。克隆当前的 `FilterInfo`（`getView().getQueryParam().getFilter().clone()`），只改不同的条目，用户的其他条件随之带过去
+- 接收端的 `reportform` 插件读取打开参数；它的 `reportlist` 插件只看得到 `ReportQueryParam`。把钻取值锁定到过滤面板的过滤上（如上），它对取数插件来说就是一个普通条件；其他值在 `verifyQuery` 中复制进 `queryParam.getCustomParam()`
+- 锁定循环里，没有钻取值的过滤列用 `continue` 跳过：在那里 `return` 会让之后所有的列都没被锁定
+- 锁定依赖于该列是常用过滤列（`CommonFilterColumn`，下拉形态）；文本和日期过滤的锁定方式不同
+- 标品代码通过给单元格值加 `<nolink>` 前缀来关闭单个单元格的链接；依赖这个约定之前先在目标 SDK 上确认