@shundoo-ai/dsh-cosmic 1.0.21 → 1.0.22

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

@@ -11,7 +11,7 @@ AbstractReportFormPlugin (kd.bos.report.plugin.AbstractReportFormPlugin)
         └── AbstractDataModelPlugin (kd.bos.entity.plugin.AbstractDataModelPlugin)
 ```
 
-报表表单插件继承自 AbstractFormPlugin，具备完整的表单插件生命周期和视图操作能力。其核心职责是控制报表界面行为，包括查询参数初始化、查询前后处理、行数据加工、列控制、过滤容器控制、导出数据加工等。
+报表表单插件继承自 AbstractFormPlugin，具备完整的表单插件生命周期和视图操作能力。其核心职责是控制报表界面行为，包括查询参数初始化、查询前后处理、行数据加工、列控制、过滤容器控制、钻取联查、图表和导出数据加工等。它从不取报表的数据行：数据行来自 `reportlist` 取数插件，二者之间唯一的约定是 DataSet 的列名。
 
 ## reportform 插件事件
 
@@ -20,27 +20,31 @@ AbstractReportFormPlugin (kd.bos.report.plugin.AbstractReportFormPlugin)
 | 方法名 | 触发时机 | 典型用途 |
 |--------|---------|---------|
 | `initialize()` | 初始化时 | 插件初始化 |
-| `registerListener(EventObject)` | 页面请求开始时 | 注册监听 |
+| `registerListener(EventObject)` | 页面请求开始时 | 注册工具栏、超链接、单元格点击与 F7 监听 |
 | `initDefaultQueryParam(ReportQueryParam)` | 报表打开时 | 设置过滤面板默认值 |
-| `filterContainerInit(FilterContainerInitEvent, ReportQueryParam)` | 过滤面板初始化 | 动态修改过滤条件控件 |
+| `filterContainerInit(FilterContainerInitEvent, ReportQueryParam)` | 过滤面板初始化 | 动态修改过滤条件控件；被钻取打开的报表在这里锁定过滤 |
 | `filterContainerSearchClick(FilterContainerSearchClickArgs)` | 查询按钮点击 | 自定义搜索逻辑 |
 | `filterContainerBeforeF7Select(BeforeFilterF7SelectEvent)` | 基础资料弹出前 | 添加过滤条件 |
 | `verifyQuery(ReportQueryParam)` | 查询前 | 条件验证，返回 false 阻止查询 |
-| `beforeQuery(ReportQueryParam)` | 查询取数前 | 修改查询参数 |
-| `afterQuery(ReportQueryParam)` | 查询取数后 | 后续处理 |
-| `afterCreateColumn(CreateColumnEvent)` | 列创建完成后 | 修改列属性 |
+| `beforeQuery(ReportQueryParam)` | 查询取数前 | 追加查询条件、切换列表开关 |
+| `afterQuery(ReportQueryParam)` | 查询取数后 | 后续处理、绘制图表 |
+| `afterCreateColumn(CreateColumnEvent)` | 列创建完成后 | 修改、隐藏或删除列 |
 | `resetColumns(List<AbstractReportColumn>)` | 列创建后 | 调整列显示顺序 |
 | `processRowData(String, DynamicObjectCollection, ReportQueryParam)` | 数据返回后 | 行数据加工 |
-| `packageData(PackageDataEvent)` | 发送前端前 | 最终数据加工 |
+| `packageData(PackageDataEvent)` | 发送前端前，每个单元格一次 | 最终数据加工、合计行标签、融合排除 |
+| `itemClick(ItemClickEvent)` | 工具栏按钮点击 | 自定义按钮 |
+| `hyperLinkClick(HyperLinkClickEvent)` | 超链接单元格点击（`HyperLinkClickListener`） | 钻取联查 |
 | `setTreeReportList(TreeReportListEvent)` | 树形报表设置 | 配置折叠树形展示 |
 | `setFlexProperty(FlexEvent)` | 弹性域设置 | 设置弹性域维度 |
 | `preProcessExportData(...)` | 导出前 | 导出数据加工 |
+| `exportInitialize(ReportExportInitializeEvent)` | 导出开始时 | 导出文件的合并单元格规则 |
 | `setFloatButtomData(List<SummaryEvent>)` | 合计行设置 | 设置合计行数据 |
 | `setCellStyleRules(List<CellStyleRule>)` | 样式设置 | 自定义单元格规则 |
 | `setMergeColums(List<String>)` | 融合列设置 | 指定融合列 |
 | `setExcelName(List<String>)` | 导出名称设置 | 自定义导出名称 |
 | `getComboItems(String, List<ValueMapItem>)` | 下拉值获取 | 提供下拉选项 |
 | `setSortAndFilter(List<SortAndFilterEvent>)` | 排序过滤设置 | 配置列排序过滤 |
+| `beforeCreateFilterInfo(CreateFilterInfoEvent)` | 构建表头过滤前 | 替换某列的表头过滤选项 |
 | `resetDataCount()` | 数据总数重设 | 修正前端展示总记录数 |
 
 ### reportform 插件事件执行顺序
@@ -50,15 +54,38 @@ initialize → registerListener → initDefaultQueryParam → filterContainerIni
   → [用户点击查询] → filterContainerSearchClick → verifyQuery → beforeQuery
   → [数据插件 query] → afterQuery → afterCreateColumn → resetColumns
   → processRowData → packageData → [前端展示]
+  → [用户点击] itemClick / hyperLinkClick
 ```
 
+## 注册
+
+`reportform` 插件是报表页面自己的表单插件，所以它属于报表表单的插件列表。它不是 `reportPlugins` 条目 ——
+那个槽位是报表列表的取数插件（`ReportQueryPlugin`），运行的是 `AbstractReportListDataPlugin` —— 也不是左树的
+`ReportTreeAp.ReportPlugin`。报表流水线只写前一个槽位，后一个只在用户新增「报表树」控件后才存在；
+这个插件像任何 Java 表单插件一样交付和注册
+（`{ROOT_DIR}/references/java-plugin-delivery.md`）：
+
+1. 用 `prepare_plugin_handoff.py` 以类型 `reportform`、报表的表单编码准备它，再用 `compile_plugin_source.py` 编译，
+   编译会把它登记进 `archive.json`。
+2. 注册并回读：
+   `{python} "{ROOT_DIR}/scripts/register_plugins.py" --app-root "{appRoot}" --class-name "{fqcn}" --verify`。
+   类型注册表把 `reportform` 映射到 `targetType` `BILL_FORM`，平台把类加到报表表单的根插件列表 ——
+   `queryEditablePlugins` 回读报表时把这个列表返回为 `location` `BILL_FORM`，与取数插件的
+   `REPORT_QUERY_PLUGIN` 行并列。结果的 `verification.status` 为 `pass` 才算已注册。
+3. 它的监听是它自己的代码：由 `registerListener` 添加；缺少对应 `add*` 调用的 `itemClick`、`cellClick` 或
+   `hyperLinkClick` 覆写会被编译边界拒绝（`PLUGIN_SOURCE_LISTENER_UNREGISTERED`）。
+
+重建报表会连同表单删掉这些注册：`planReportRecreate` 把它们列在 `current.formPlugins` 下，并用单独一步
+重新注册。
+
 ## 插件内上下文方法
 
 以下更适合作为界面插件中的上下文能力，不建议当成“自动触发事件”：
 
 - `getView()`：获取报表视图。
-- `getModel()`：获取报表数据模型。
+- `getModel()`：获取报表数据模型；过滤面板的字段就是它的属性，所以 `getModel().getValue(key)` / `setValue(key, value)` 读取和设置过滤值。
 - `getQueryParam()`：获取当前查询参数。
+- `getPageCache()`：页面级缓存，翻页不丢；同一页面不同事件之间传值用它。
 - `getControl("reportlistap")`：获取报表控件，返回 `Control` 基类或具体控件对象。
 
 ```java
@@ -69,7 +96,135 @@ reportList.setSelectedAll(true);
 
 说明：`this.getControl("reportlistap")` 的返回类型是 `<T extends kd.bos.form.control.Control>`，所有控件都继承自 `kd.bos.form.control.Control`，实际拿到的是具体控件对象，例如 `ReportList`、`BasedataEdit`、`EntryGrid` 等。
 
-
+用户可见文案一律经过 `ResManager.loadKDString(text, resourceKey, module)`，以便多语言翻译。
+
+## 工具栏、监听与行数据
+
+在 `registerListener` 里注册监听：`addItemClickListeners("toolbarap")` 把工具栏按钮路由到 `itemClick`，
+`ReportList.addHyperClickListener(this)` 把超链接单元格路由到 `implements HyperLinkClickListener` 的插件的
+`hyperLinkClick`。工具栏按钮本身是元数据 —— 报表工具栏上的一个按钮项，通常绑定一个 donothing 操作 ——
+`evt.getItemKey()` 就是它的标识。
+
+`itemClick` 拿不到当前行。在单元格点击时缓存行号（`ReportList.addCellClickListener`，把 `e.getRow()` 存进
+`getPageCache()`），按钮点击时再用 `reportList.getReportModel().getRowData(rowIndex)` 取回：取到的行是一个
+`DynamicObject`，按取数插件 DataSet 的列名取值，基础资料列取出来是 `DynamicObject`，它的 `getPkValue()` 就是 id。
+
+要取全部选中行，先在 `beforeQuery` 里用 `reportList.setSelectedAll(true)` 开启全选，再读
+`getRowData(0, reportList.getTotalRecords(), true)` —— 起始行、行数、是否仅取选中行。在 8.0 SDK 中，三参数重载是
+`IReportListModel` 的 default 方法，所以直接在 `getReportModel()` 返回的模型上调用，无需强转。
+作用于行的按钮必须用提示处理没有选中行的情况。见
+`{ROOT_DIR}/knowledge/cosmic/platform/scenes/report/report-row-data-toolbar.md`。
+
+## 过滤面板：默认值、F7 范围与校验
+
+- 默认值：在 `initDefaultQueryParam` 里，对仍为空的过滤字段用 `getModel().setValue(key, value)` 赋值 ——
+  用户有权使用当前组织时取当前组织，否则取第一个有权限的组织；日期范围取本月 1 日到今天。
+  `filterContainerInit` 是设默认值的另一个位置。
+- F7 范围：收窄用户能选的候选，而不只是查询能接受的值。在 `registerListener` 里，
+  `BasedataEdit.addBeforeF7SelectListener` 能拿到选择器的 `ListShowParameter`，其
+  `getListFilterParameter().setFilter(new QFilter("id", QCP.in, ids))` 限定候选；过滤容器自己的选择器用
+  `filterContainerBeforeF7Select` 配 `addCustomQFilter` 达到同样效果。
+- 校验：`verifyQuery` 从 `queryParam.getFilter()` 读取条件 —— 多选基础资料过滤用
+  `getDynamicObjectCollection(key)`，日期用 `getDate(key)` —— 不满足时
+  `getView().showTipNotification(message, 3000)` 并返回 `false` 阻断查询，否则返回 `super.verifyQuery(queryParam)`。
+  取数插件需要的结构化取值在这里放进 `queryParam.setCustomParam(map)`。
+- 按钮上的跨字段检查：`filterContainerSearchClick` 读取并调整 `args.getFilterValues()`，例如拒绝超过一年的
+  日期范围。
+
+## 运行时的列
+
+`afterCreateColumn` 在 `event.getColumns()` 里拿到列树：`ReportColumn` 用 `getFieldKey()` 识别，
+`ReportColumnGroup` 的列在它的 `getChildren()` 里。`setHide(...)` 显示或隐藏某列。删除列时倒序遍历，避免下标
+位移，并且要连同每个分组的子列一起遍历，否则会留下空的分组表头。按字段 key 匹配列，绝不按标题：标题随语言
+变化。列结构取决于查询出的数据而不是过滤选项时，应改在取数插件的 `getColumns` 里处理。
+
+## 单元格格式化、融合与合计行
+
+- `packageData(PackageDataEvent)` 每个单元格触发一次。`getSource()` 是当前列 —— 强转前先判断
+  `instanceof ReportColumn` —— `getRowData()` 是当前行，`setFormatValue(value)` 替换显示值。取数插件构造的合计行
+  带 `sumlevel` 标记（1 小计、2 总计）：在这里给它们打标签，并对合计行上无意义的列（例如比率）
+  `setFormatValue(null)`。
+- 行融合：`setMergeColums(List<String>)` 添加相邻值相同就融合的字段 key；在 `packageData` 里用
+  `getNoMergeKey().add(fieldKey)` 让某个单元格（例如小计行的）不参与融合。
+- 导出合并：`exportInitialize(ReportExportInitializeEvent)` 用 `setMergeColumnRules(rules)` 设置由
+  `new MergeColumnRule(groupColumns, mergeColumns)` 组成的规则。一个合并字段只能出现在一条规则里，合并跟随分组
+  字段：只要分组字段的值相同，合并字段就合并，不看合并字段自身相邻行的值是否相同。
+- `processRowData` 拿到的是一页数据行，导出时也会触发；不要在这里或 `preProcessExportData` 里逐行查库。
+
+见 `{ROOT_DIR}/knowledge/cosmic/platform/scenes/report/report-subtotal-total.md` 与
+`{ROOT_DIR}/knowledge/cosmic/platform/scenes/report/report-merge-column.md`。
+
+## 表头过滤与排序
+
+`setSortAndFilter(List<SortAndFilterEvent>)` 逐列开启表头排序与过滤：`event.getColumnName()` 是列名，
+`setSort(true)` 与 `setFilter(true)` 开启它们。`beforeCreateFilterInfo(CreateFilterInfoEvent)` 替换某一列的
+过滤选项 —— `event.getFieldKey()` 是该列，`event.getFilterInfo().put("comboItems", items)` 设置选项，每个选项是
+包含 `id`、`name`（`LocaleString`）和 `value` 的 map。这只是功能的一半：取数插件的 `query()` 必须应用
+`getTableHeadFilterItems()`，否则表头过滤不起任何作用。见
+`{ROOT_DIR}/knowledge/cosmic/platform/scenes/report/report-head-filter.md`。
+
+## 钻取联查
+
+超链接单元格需要该列在报表元数据里配置为超链接列，并注册上文的监听。在
+`hyperLinkClick(HyperLinkClickEvent)` 里，`evt.getFieldName()` 是被点击的列 —— 每个超链接列分发到一个方法 ——
+`reportList.getReportModel().getRowData(evt.getRowIndex())` 返回该行。三种目标：
+
+| 目标 | 打开参数 |
+|---|---|
+| 单据 | `BillShowParameter`：`setFormId(单据)`、`setPkId(id)`、`setStatus(OperationStatus.VIEW)`、`getOpenStyle().setShowType(ShowType.MainNewTabPage)` |
+| 列表 | `ListShowParameter`：`setFormId("bos_list")`、`setBillFormId(单据)`，以及带 `QFilter.of("company=? and bizdate>=?", ...)` 的 `ListFilterParameter` |
+| 另一张报表 | `ReportShowParameter`：`setFormId(报表)` 配 `setCustomParams(map)`，或 `setQueryParam(param)` 带一份克隆的 `FilterInfo` |
+
+被钻取打开的报表在 `filterContainerInit` 里读取打开参数：`(ReportShowParameter) getView().getFormShowParameter()`
+及其 `getCustomParams()`。要把某个过滤锁定为钻取值，从 `event.getCommonFilterColumns()` 取出
+`CommonFilterColumn`，清空其选项，把钻取值设为唯一选项并 `setDefaultValue(...)`，再 `setMustInput(true)`。见
+`{ROOT_DIR}/knowledge/cosmic/platform/scenes/report/report-hyperlink-drill.md`。
+
+## 树形报表列表
+
+`setTreeReportList(TreeReportListEvent)` 里调 `event.setTreeReportList(true)` 把报表列表渲染成可折叠的树，
+`event.setTreeExpandColId(column)` 指定承载展开控件的列；取数插件的数据行带 `rowid` / `pid` / `isgroupnode`。
+工具栏按钮可以用 `reportList.expandAllNode()` / `reportList.collapseAllNode()` 一键展开或收起全部节点（7.0.1 及
+以后）；工具栏监听在 `registerListener` 里注册。报表示例还在 `initialize` 里再注册一次，这不起作用 ——
+`Toolbar.addItemClickListener` 会忽略已持有的监听 —— 而且会被编译边界拒绝。报表示例还用
+`event.setCol2ndResultMode(TreeDataMode.FLAT)` 把树形列表的表头过滤结果改为平铺；8.0 SDK 里这两个名字都不存在，
+所以在 8.0 上不要写，目标是更新的版本时，只有 `{ROOT_DIR}/references/sdk-inspection.md` 在其 SDK 上找到它后才使用。见
+`{ROOT_DIR}/knowledge/cosmic/platform/scenes/report/report-tree-list.md`。
+
+## 查询开关
+
+在 `beforeQuery` 里，`ReportList.setAsyncTotal(true)` 异步计算合计行，不让合计拖住数据行的展示；
+`setSelectedAll(true)` 允许用户全选全部行。报表示例还加了 `setAsyncDataCount(true)`，异步查询总行数，首页先展示
+再取总数；8.0 SDK 没有这个方法，所以在 8.0 上不要写，目标是更新的版本时，只有
+`{ROOT_DIR}/references/sdk-inspection.md` 在其 SDK 上找到它后才使用。这些开关默认都关闭，大数据量报表建议开启。
+
+`beforeQuery` 是追加查询条件，绝不替换：在这里 `queryParam.setFilter(new FilterInfo())` 或
+`setCustomFilter(new ArrayList<>())` 会丢掉用户输入的全部条件。见
+`{ROOT_DIR}/knowledge/cosmic/platform/scenes/report/report-async-query.md`。
+
+## 查询后的图表
+
+报表表单上布局的图表控件在 `afterQuery` 里驱动：用 `getControl(key)` 取得它，`clearData()`，添加一个序列
+（`PieChart` 上的 `createPieSeries(title)`），给它 `ItemValue` 条目，再 `refresh()`。图表需要与列表相同的数据行：
+要么根据 `queryParam` 重新计算，要么取取数插件共享出来的 DataSet —— 两个图表都要消费时，在第一次遍历前先
+`copy()`，因为每次遍历都会消费 DataSet。见
+`{ROOT_DIR}/knowledge/cosmic/platform/scenes/report/report-chart.md`。
+
+## 选用场景
+
+把适用的场景作为 intent 的 `scenes` 条目传给 `prepare_plugin_handoff.py`，它会把场景的 SDK 引用展开成 import：
+
+| 需求 | 场景 |
+|---|---|
+| 工具栏按钮、当前行、全部选中行 | `report/report-row-data-toolbar` |
+| 钻取到单据、列表或报表，以及被钻取的报表 | `report/report-hyperlink-drill` |
+| 表头过滤与排序、自定义表头过滤选项 | `report/report-head-filter` |
+| 小计与合计行的标签和置空 | `report/report-subtotal-total` |
+| 界面与导出中的单元格融合 | `report/report-merge-column` |
+| 可折叠树形列表、一键展开与收起 | `report/report-tree-list` |
+| 异步合计、总数与全选 | `report/report-async-query` |
+| 查询后的图表 | `report/report-chart` |
+| 查询校验 | `report/report-verify-query` |
 
 ## 实践建议
 
@@ -77,6 +232,7 @@ reportList.setSelectedAll(true);
 2. 过滤容器初始化与默认参数初始化要配合使用。
 3. `processRowData(...)` 避免逐行查库，导出时会放大性能问题。
 4. 导出相关逻辑放在 `preProcessExportData(...)` 和 `setExcelName(...)`。
+5. 一族报表共享同一套交互规范时，把它放进抽象基类插件 —— 有权限的组织做成抽象方法，F7 范围、默认值、校验和删列放在基类 —— 各报表只覆写不同的部分。
 
 ## 常见坑位
 
@@ -84,43 +240,51 @@ reportList.setSelectedAll(true);
 - 在 `packageData(...)` 中实现导出逻辑。
 - `verifyQuery(...)` 不校验空条件导致全表扫描。
 - 把大量专项扩展点和核心查询事件混在一起，模板难以聚焦。
-
-
+- 在 `beforeQuery(...)` 里替换查询参数，而不是追加。
+- 没有 `instanceof` 判断就把 `packageData` 的来源强转成 `ReportColumn`。
+- 按标题匹配列，而标题随语言不同。
+- 漏注册监听：没有 `addItemClickListeners` 或 `addHyperClickListener` 时，按钮或超链接点了没反应。编译边界会拒绝没有注册的覆写（`PLUGIN_SOURCE_LISTENER_UNREGISTERED`）。
+- 开启了表头过滤，取数插件却没有应用它。两个插件中后编译的那个会给出警告（`PLUGIN_REPORT_HEAD_FILTER_UNAPPLIED`）。
+- 写了 8.0 SDK 没有的名字 —— `setAsyncDataCount`、`setCol2ndResultMode`、`TreeDataMode`、`FilterInfo.getCustomFilter` —— 编译时会报告 `PLUGIN_SOURCE_ABSENT_FROM_8_0_SDK`。
 
 ## 骨架模板
 
-> 适用：`reportform`。继承 `AbstractReportFormPlugin`（`kd.bos.report.plugin.AbstractReportFormPlugin`），具备完整表单插件生命周期。所有重写方法必须第一行调用 `super.xxx()`。类名后缀按 `{PluginSuffix}` 命名。注册方式：在苍穹报表模板配置中注册插件类全限定名。
+> 适用：`reportform`。继承 `AbstractReportFormPlugin`（`kd.bos.report.plugin.AbstractReportFormPlugin`），具备完整表单插件生命周期。所有重写方法必须第一行调用 `super.xxx()`。类名后缀按 `{PluginSuffix}` 命名。注册方式：`register_plugins.py --verify` 把插件类全限定名加到报表表单的插件列表（`targetType` `BILL_FORM`）—— 不要放进 `reportPlugins`，那是报表列表的取数槽位。
 
 ```java
 package kd.cd.common;
 
+import kd.bos.bill.BillShowParameter;
+import kd.bos.bill.OperationStatus;
 import kd.bos.context.RequestContext;
 import kd.bos.dataentity.entity.DynamicObject;
 import kd.bos.dataentity.entity.DynamicObjectCollection;
 import kd.bos.entity.NumberFormatProvider;
 import kd.bos.entity.datamodel.events.PackageDataEvent;
+import kd.bos.entity.report.AbstractReportColumn;
 import kd.bos.entity.report.FilterInfo;
 import kd.bos.entity.report.ReportColumn;
 import kd.bos.entity.report.ReportQueryParam;
-import kd.bos.entity.report.queryds.ReportFilterFieldConfig;
+import kd.bos.form.ShowType;
 import kd.bos.form.control.events.FilterContainerInitEvent;
+import kd.bos.form.control.events.ItemClickEvent;
 import kd.bos.form.events.FilterContainerSearchClickArgs;
+import kd.bos.form.events.HyperLinkClickEvent;
+import kd.bos.form.events.HyperLinkClickListener;
 import kd.bos.form.field.events.BeforeFilterF7SelectEvent;
-import kd.bos.lang.Lang;
-import kd.bos.list.column.ListOperationColumnDesc;
 import kd.bos.report.ReportList;
 import kd.bos.report.events.CreateColumnEvent;
+import kd.bos.report.events.SortAndFilterEvent;
 import kd.bos.report.plugin.AbstractReportFormPlugin;
 
-import java.util.ArrayList;
-import java.util.HashMap;
+import java.util.EventObject;
 import java.util.List;
 
 /**
  * 报表界面插件骨架模板（原生 AbstractReportFormPlugin）。
  * 该类仅用于示例写法，生成后请按实际业务删除无用事件并替换占位常量。
  */
-public class ReportFormPluginTemplate extends AbstractReportFormPlugin {
+public class ReportFormPluginTemplate extends AbstractReportFormPlugin implements HyperLinkClickListener {
 
     /**
      * 触发时机: 在需要了解当前插件可访问上下文能力时调用。
@@ -136,9 +300,61 @@ public class ReportFormPluginTemplate extends AbstractReportFormPlugin {
     }
 
     private static final String GRID_KEY = "reportlistap";
+    private static final String TOOLBAR_KEY = "toolbarap";
     private static final String FILTER_ORG = "org";
     private static final String FILTER_BILL_STATUS = "billstatus";
 
+    // ===== 监听 =====
+
+    /**
+     * 触发时机: 页面请求开始时。
+     * 参数要点: e 为本次请求事件。
+     * 典型用途: 把工具栏点击路由到 itemClick，把超链接单元格路由到 hyperLinkClick。
+     */
+    @Override
+    public void registerListener(EventObject e) {
+        super.registerListener(e);
+        this.addItemClickListeners(TOOLBAR_KEY);
+        ReportList reportList = this.getControl(GRID_KEY);
+        reportList.addHyperClickListener(this);
+    }
+
+    /**
+     * 触发时机: 工具栏按钮点击时。
+     * 参数要点: evt.getItemKey() 是报表元数据里工具栏按钮的标识。
+     * 典型用途: 执行自定义按钮逻辑；处理没有选中行的情况。
+     */
+    @Override
+    public void itemClick(ItemClickEvent evt) {
+        super.itemClick(evt);
+        if ("btn_refresh_hint".equals(evt.getItemKey())) {
+            this.getView().showTipNotification("修改过滤条件后请重新查询。");
+        }
+    }
+
+    /**
+     * 触发时机: 超链接单元格点击时（HyperLinkClickListener 接口方法，不调 super）。
+     * 参数要点: getFieldName() 是被点击的列，getRowIndex() 是所在行。
+     * 典型用途: 钻取到被点击行的源单。
+     */
+    @Override
+    public void hyperLinkClick(HyperLinkClickEvent evt) {
+        if (!"billno".equals(evt.getFieldName())) {
+            return;
+        }
+        ReportList reportList = this.getControl(GRID_KEY);
+        DynamicObject row = reportList.getReportModel().getRowData(evt.getRowIndex());
+        if (row == null) {
+            return;
+        }
+        BillShowParameter parameter = new BillShowParameter();
+        parameter.setFormId(row.getString("billformid"));
+        parameter.setPkId(row.getLong("billid"));
+        parameter.setStatus(OperationStatus.VIEW);
+        parameter.getOpenStyle().setShowType(ShowType.MainNewTabPage);
+        this.getView().showForm(parameter);
+    }
+
     // ===== 核心事件 =====
 
     /**
@@ -154,7 +370,7 @@ public class ReportFormPluginTemplate extends AbstractReportFormPlugin {
             filter = new FilterInfo();
             queryParam.setFilter(filter);
         }
-        filter.addFilterItem("fieldKey", RequestContext.get().getOrgId());
+        filter.addFilterItem(FILTER_ORG, RequestContext.get().getOrgId());
     }
 
     /**
@@ -200,34 +416,26 @@ public class ReportFormPluginTemplate extends AbstractReportFormPlugin {
      */
     @Override
     public boolean verifyQuery(ReportQueryParam queryParam) {
-        super.verifyQuery(queryParam);
-        return queryParam.getFilter() != null;
+        FilterInfo filter = queryParam.getFilter();
+        if (filter == null || filter.getValue(FILTER_ORG) == null) {
+            this.getView().showTipNotification("请先选择组织再查询。");
+            return false;
+        }
+        return super.verifyQuery(queryParam);
     }
 
     /**
      * 触发时机: 报表查询执行前。
      * 参数要点: queryParam 含过滤、分页、排序等上下文。
-     * 典型用途: 追加查询过滤条件、设置报表控件状态或修正参数。
+     * 典型用途: 追加查询条件或切换列表开关；绝不替换用户的条件。
      */
     @Override
     public void beforeQuery(ReportQueryParam queryParam) {
         super.beforeQuery(queryParam);
-        // 设置取数排序规则
-        queryParam.setSortInfo("xxx");
-        // 设置自定义参数到取数插件
-        queryParam.setCustomParam(new HashMap<>());
-        // 设置是否树形报表
-        queryParam.setTreeReportList(false);
-        // 设置报表过滤条件配置
-        queryParam.setReportFilterFieldConfig(new ReportFilterFieldConfig());
-        // 设置通用过滤条件
-        queryParam.setFilter(new FilterInfo());
-        // 设置多语言
-        queryParam.setMulLang(Lang.zh_CN);
-        // 设置报表自定义过滤条件
-        queryParam.setCustomFilter(new ArrayList<>());
-        // 设置提示信息
-        queryParam.setMessage("查询完成");
+        // 只追加，不替换：在这里 setFilter(new FilterInfo()) 或 setCustomFilter(new ArrayList<>())
+        // 会丢掉用户输入的全部条件。
+        ReportList reportList = this.getControl(GRID_KEY);
+        reportList.setAsyncTotal(true);
     }
 
     /**
@@ -243,33 +451,34 @@ public class ReportFormPluginTemplate extends AbstractReportFormPlugin {
 
     /**
      * 触发时机: 报表列创建后。
-     * 参数要点: event 可调整列标题、宽度、隐藏状态等。
-     * 典型用途: 动态调整列显示方式或列元数据。
+     * 参数要点: event.getColumns() 是列树；ReportColumnGroup 的列在它的 getChildren() 里。
+     * 典型用途: 按字段 key 显示、隐藏或删除列。
      */
     @Override
     public void afterCreateColumn(CreateColumnEvent event) {
         super.afterCreateColumn(event);
-        this.getView().showTipNotification("报表列初始化完成");
+        for (AbstractReportColumn column : event.getColumns()) {
+            if (column instanceof ReportColumn && "textareafield1".equals(((ReportColumn) column).getFieldKey())) {
+                ((ReportColumn) column).setHide(false);
+            }
+        }
     }
 
     /**
-     * 触发时机: 打包单元格数据时。
+     * 触发时机: 打包单元格数据时，每个单元格一次。
      * 参数要点: packageDataEvent 含当前行列数据上下文。
      * 典型用途: 对界面展示值做格式化；该事件通常不用于导出逻辑。
      */
     @Override
     public void packageData(PackageDataEvent packageDataEvent) {
         super.packageData(packageDataEvent);
-        if (packageDataEvent.getSource() instanceof ReportColumn) {
-            DynamicObject dObject = packageDataEvent.getRowData();
-            String applyType = dObject.getString("kdec_applytype");
-            if(applyType.equals("A")) {
-                ReportColumn column = (ReportColumn) packageDataEvent.getSource();
-                System.out.println(column.getFieldKey());
-                if ("kdec_totalday".equals(column.getFieldKey())) {
-                    packageDataEvent.setFormatValue(100);
-                }
-            }
+        if (!(packageDataEvent.getSource() instanceof ReportColumn)) {
+            return;
+        }
+        ReportColumn column = (ReportColumn) packageDataEvent.getSource();
+        DynamicObject row = packageDataEvent.getRowData();
+        if ("kdec_totalday".equals(column.getFieldKey()) && "A".equals(row.getString("kdec_applytype"))) {
+            packageDataEvent.setFormatValue(100);
         }
     }
 
@@ -313,7 +522,7 @@ public class ReportFormPluginTemplate extends AbstractReportFormPlugin {
 
     /**
      * 触发时机: 设置导出 Excel 文件名时。
-     * 参数要点: list 为导出文件名片段集合。
+     * 参数要点: list 为导出文件名片段集合；只使用第一个元素。
      * 典型用途: 自定义导出文件名，便于区分组织、期间或报表类型。
      */
     @Override
@@ -324,13 +533,16 @@ public class ReportFormPluginTemplate extends AbstractReportFormPlugin {
 
     /**
      * 触发时机: 初始化列排序和过滤能力时。
-     * 参数要点: allColumns 为全部列定义。
-     * 典型用途: 控制列是否支持排序、列头过滤等交互行为。
+     * 参数要点: allColumns 每列一个事件；getColumnName() 是列名。
+     * 典型用途: 开启表头排序与过滤；取数插件必须应用表头过滤条件。
      */
     @Override
-    public void setSortAndFilter(List allColumns) {
+    public void setSortAndFilter(List<SortAndFilterEvent> allColumns) {
         super.setSortAndFilter(allColumns);
-        this.getView().showTipNotification("初始化排序与过滤能力");
+        for (SortAndFilterEvent column : allColumns) {
+            column.setSort(true);
+            column.setFilter(true);
+        }
     }
 }