@shundoo-ai/dsh-cosmic 1.0.21 → 1.0.22

package/skills/cosmic-build/knowledge/cosmic/platform/scenes/operation/operation-plugin-events.md

@@ -69,26 +69,31 @@ import kd.bos.entity.plugin.args.BeforeOperationArgs;
 import kd.bos.entity.plugin.args.BeginOperationTransactionArgs;
 import kd.bos.entity.plugin.args.EndOperationTransactionArgs;
 import kd.bos.entity.plugin.args.RollbackOperationArgs;
+import kd.bos.logging.Log;
+import kd.bos.logging.LogFactory;
 
 /**
- * 演示操作插件全部事件的捕获及触发时机
+ * Demonstrates capturing all events of an operation plugin and their trigger timing
  *
  * @remark
- * 本示例代码，捕捉的事件，由前往后触发
+ * The events captured in this sample code are triggered from first to last
  *
  */
 public class OperationEventSample extends AbstractOperationServicePlugIn {
 
+	private static final Log LOG = LogFactory.getLog(OperationEventSample.class);
+
 	/**
-	 * 操作执行，加载单据数据包之前，触发此事件；
+	 * This event is triggered before the operation executes and before the bill data package is loaded;
 	 *
 	 * @remark
-	 * 在单据列表上执行单据操作，传入的是单据内码；
-	 * 系统需要先根据传入的单据内码，加载单据数据包，其中只包含操作要用到的字段，然后再执行操作；
-	 * 在加载单据数据包之前，操作引擎触发此事件；
+	 * When executing bill operations on the bill list, bill internal codes are passed in;
+	 * The system first needs to load the bill data package based on the incoming bill internal codes,
+	 * which only contains the fields needed for the operation, before executing the operation;
+	 * Before loading the bill data package, the operation engine triggers this event;
 	 *
-	 * 插件需要在此事件，添加需要用到的字段；
-	 * 否则，系统加载的单据数据包，可能没有插件要用到的字段值，从而引发中断
+	 * The plugin must add the fields it needs in this event;
+	 * Otherwise, the system-loaded bill data package may not contain the field values required by the plugin, causing an interruption
 	 */
 	@Override
 	public void onPreparePropertys(PreparePropertysEventArgs e) {
@@ -96,10 +101,10 @@ public class OperationEventSample extends AbstractOperationServicePlugIn {
 	}
 
 	/**
-	 * 构建好操作校验器之后，执行校验之前，触发此事件；
+	 * This event is triggered after building the operation validators and before executing validation;
 	 *
 	 * @remark
-	 * 插件可以在此事件，增加自定义操作校验器，或者去掉内置的校验器
+	 * The plugin can add custom operation validators or remove built-in validators in this event
 	 */
 	@Override
 	public void onAddValidators(AddValidatorsEventArgs e) {
@@ -107,10 +112,10 @@ public class OperationEventSample extends AbstractOperationServicePlugIn {
 	}
 
 	/**
-	 * 操作校验通过之后，开启事务之前，触发此事件；
+	 * This event is triggered after operation validation passes and before the transaction begins;
 	 *
 	 * @remark
-	 * 插件可以在此事件，对通过校验的数据，进行整理
+	 * The plugin can organize the data that passed validation in this event
 	 */
 	@Override
 	public void beforeExecuteOperationTransaction(BeforeOperationArgs e) {
@@ -118,10 +123,11 @@ public class OperationEventSample extends AbstractOperationServicePlugIn {
 	}
 
 	/**
-	 * 操作校验通过，开启了事务，准备把数据提交到数据库之前触发此事件；
+	 * This event is triggered after operation validation passes, the transaction has begun,
+	 * and before data is ready to be committed to the database;
 	 *
 	 * @remark
-	 * 可以在此事件，进行数据同步处理
+	 * Data synchronization processing can be performed in this event
 	 */
 	@Override
 	public void beginOperationTransaction(BeginOperationTransactionArgs e) {
@@ -129,10 +135,11 @@ public class OperationEventSample extends AbstractOperationServicePlugIn {
 	}
 
 	/**
-	 * 单据数据已经提交到数据库之后，事务为提交之前，触发此事件；
+	 * This event is triggered after bill data has been committed to the database
+	 * and before the transaction is committed;
 	 *
 	 * @remark
-	 * 可以在此事件，进行数据同步处理；
+	 * Data synchronization processing can be performed in this event;
 	 */
 	@Override
 	public void endOperationTransaction(EndOperationTransactionArgs e) {
@@ -140,10 +147,11 @@ public class OperationEventSample extends AbstractOperationServicePlugIn {
 	}
 
 	/**
-	 * 操作事务提交失败，事务回滚之后触发此事件；
+	 * This event is triggered after operation transaction commit fails and the transaction has rolled back;
 	 *
 	 * @remark
-	 * 该方法在事务异常后执行，插件可以在此事件，对没有事务保护的数据更新进行补偿
+	 * This method executes after a transaction exception; the plugin can compensate
+	 * for data updates without transaction protection in this event
 	 */
 	@Override
 	public void rollbackOperation(RollbackOperationArgs e) {
@@ -151,10 +159,10 @@ public class OperationEventSample extends AbstractOperationServicePlugIn {
 	}
 
 	/**
-	 * 操作执行完毕，事务提交之后，触发此事件；
+	 * This event is triggered after the operation has completed and the transaction has been committed;
 	 *
 	 * @remark
-	 * 插件可以在此事件，处理操作后续事情，与操作事务无关
+	 * The plugin can handle post-operation tasks in this event, unrelated to the operation transaction
 	 */
 	@Override
 	public void afterExecuteOperationTransaction(AfterOperationArgs e) {
@@ -162,8 +170,8 @@ public class OperationEventSample extends AbstractOperationServicePlugIn {
 	}
 
 	private void printEventInfo(String eventName, String argString){
-		String msg = String.format("%s : %s", eventName, argString);
-		System.out.println(msg);
+		// 使用平台日志，避免 DCS 禁止的 System.out（CVE-KD-0209-1）
+		LOG.info(String.format("%s : %s", eventName, argString));
 	}
 }
 ```

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

@@ -0,0 +1,133 @@
+---
+version: "1.0.0"
+framework_version: "8.0.1"
+source_doc: "报表插件示例 示例6、示例10"
+last_updated: "2026-10-19"
+status: "approved"
+scene_name: "报表查询开关：异步合计、全选与自定义过滤"
+related_apis: ["AbstractReportFormPlugin.beforeQuery", "ReportList.setAsyncTotal", "ReportList.setSelectedAll", "ReportQueryParam.getCustomFilter", "ReportQueryParam.setCustomFilter", "FilterInfo.getQFilters", "QueryServiceHelper.queryDataSet"]
+topic: "报表表单插件"
+---
+
+# 场景：报表查询开关：异步合计、全选与自定义过滤
+
+## 适用情况
+大报表要尽快显示首页并保持可用：合计行不拖慢数据行，用户可以全选所有行，总行数在后台统计。这些是报表列表控件上的开关，在 `reportform` 插件的 `beforeQuery` 中为即将执行的查询设置。`beforeQuery` 也是表单插件追加自身条件的地方——它向查询参数追加，从不替换。
+
+## 事件/方法说明
+
+- `beforeQuery(ReportQueryParam)`：每次查询前执行；`this.getControl("reportlistap")` 返回 `ReportList`
+- `ReportList.setAsyncTotal(true)`：异步计算合计行，不拖慢数据行
+- `ReportList.setSelectedAll(true)`：允许用户全选结果中的所有行（读取方式见 `report-row-data-toolbar.md`）
+- `ReportList.setAsyncDataCount(true)`：异步统计总行数，首页先于总数显示。报表示例使用了它，但 8.0 SDK 没有这个方法：其 `lib/bos` 与 `lib/trd` jar 中没有任何类提到这个名字
+- `ReportQueryParam.getCustomFilter()` / `setCustomFilter(List<QFilter>)`：查询参数带给取数插件的一组额外 `QFilter` 条件
+
+三个列表开关默认都是关闭的。
+
+## 方法签名
+```java
+@Override
+public void beforeQuery(ReportQueryParam queryParam)
+```
+
+## 代码示例
+`extracted` `needs-verification`
+
+查询前打开列表选项：
+
+```java
+package kd.bos.plugin.sample.report.bizcase;
+
+import kd.bos.entity.report.ReportQueryParam;
+import kd.bos.report.ReportList;
+import kd.bos.report.plugin.AbstractReportFormPlugin;
+
+public class AsyncQueryReportFormPlugin extends AbstractReportFormPlugin {
+
+    @Override
+    public void beforeQuery(ReportQueryParam queryParam) {
+        super.beforeQuery(queryParam);
+        ReportList reportList = this.getControl("reportlistap");
+        // 合计行异步计算，不拖慢数据行
+        reportList.setAsyncTotal(true);
+        // 用户可以全选结果中的所有行
+        reportList.setSelectedAll(true);
+        // 总行数在首页之后异步到达需要 setAsyncDataCount，8.0 SDK 没有它：
+        // 只在 references/sdk-inspection.md 能找到它的更新目标版本上
+        // 启用。
+        // reportList.setAsyncDataCount(true);
+    }
+}
+```
+
+在表单插件中追加条件，在取数插件中应用它：
+
+```java
+package kd.bos.plugin.sample.report.bizcase;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import kd.bos.entity.report.ReportQueryParam;
+import kd.bos.orm.query.QCP;
+import kd.bos.orm.query.QFilter;
+import kd.bos.report.plugin.AbstractReportFormPlugin;
+
+public class AuditedOnlyReportFormPlugin extends AbstractReportFormPlugin {
+
+    @Override
+    public void beforeQuery(ReportQueryParam queryParam) {
+        super.beforeQuery(queryParam);
+        // 由表单侧决定的条件，这里来自过滤面板的一个选项
+        if (!Boolean.TRUE.equals(this.getModel().getValue("auditedonly"))) {
+            return;
+        }
+        List<QFilter> customFilters = queryParam.getCustomFilter();
+        if (customFilters == null) {
+            customFilters = new ArrayList<>(1);
+            queryParam.setCustomFilter(customFilters);
+        }
+        // 追加：用户自己的条件仍在 queryParam.getFilter() 中
+        customFilters.add(new QFilter("billstatus", QCP.equals, "C"));
+    }
+}
+```
+
+```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 AuditedOnlyReportListDataPlugin extends AbstractReportListDataPlugin {
+
+    private static final String ALGO_NAME = "xxx.report.auditedonly";
+    private static final String ENTITY_NUMBER = "xxx_salesorder";
+
+    @Override
+    public DataSet query(ReportQueryParam queryParam, Object selectedObj) throws Throwable {
+        List<QFilter> filters = new ArrayList<>(queryParam.getFilter().getQFilters());
+        // ……过滤面板条件照常在这里追加
+        // 取数插件自己执行查询，所以由它自己应用自定义过滤
+        if (queryParam.getCustomFilter() != null) {
+            filters.addAll(queryParam.getCustomFilter());
+        }
+        return QueryServiceHelper.queryDataSet(ALGO_NAME, ENTITY_NUMBER, "billno, billstatus, amount",
+                filters.toArray(new QFilter[filters.size()]), queryParam.getSortInfo());
+    }
+}
+```
+
+## 注意事项
+- 这些开关属于即将执行的查询，所以在 `beforeQuery` 中设置；大报表建议打开
+- `setAsyncDataCount` 来自报表示例，8.0 SDK 中不存在：在 8.0 上源码编译失败，跳过编译时则在加载时失败，编译时会给出警告（`PLUGIN_SOURCE_ABSENT_FROM_8_0_SDK`）。只在 `references/sdk-inspection.md` 能找到它的更新目标版本上使用
+- `beforeQuery` 只追加，从不替换：`queryParam.setFilter(new FilterInfo())`，或在已有列表上 `setCustomFilter(new ArrayList<>())`，都会丢掉已有的全部条件
+- 自定义过滤列表随查询参数到达取数插件，而取数插件自己构造查询：在 `beforeQuery` 里加的条件，要等 `query()` 把 `getCustomFilter()` 加进自己的过滤后才起作用。报表示例写的是 `queryParam.getFilter().getCustomFilter()`；8.0 SDK 把该方法声明在 `ReportQueryParam` 上，`FilterInfo` 上没有，所以调用 `queryParam.getCustomFilter()`
+- 报表每次查询都需要的规则放在 `query()` 里；自定义过滤列表适合由表单侧决定的条件——来自用户的面板选项，或来自表单插件已经算出的结果（比如它有权限的组织）
+- 结果非常大时，再考虑分批取数（`report-batch-query.md`）以及表头过滤 / 排序的行数上限（`report-total-type.md`）

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

@@ -5,7 +5,7 @@ source_doc: "bos-runtime-plugin 报表示例"
 last_updated: "2026-04-03"
 status: "approved"
 scene_name: "报表分批取数"
-related_apis: ["AbstractReportListDataPlugin", "queryBatchBy", "IReportBatchQueryInfo", "query", "ReportQueryParam", "ORM", "DataSet", "QFilter", "QCP"]
+related_apis: ["AbstractReportListDataPlugin.queryBatchBy", "AbstractReportListDataPlugin.query", "ReportQueryParam.byBatchInfo", "ReportQueryParam.getSortInfo", "FilterInfo.getHeadFilters", "IReportBatchQueryInfo", "QueryServiceHelper.queryDataSet", "DataSet", "QFilter", "QCP"]
 topic: "报表数据查询"
 ---
 
@@ -51,14 +51,17 @@ import kd.bos.algo.Row;
 import kd.bos.entity.report.AbstractReportListDataPlugin;
 import kd.bos.entity.report.IReportBatchQueryInfo;
 import kd.bos.entity.report.ReportQueryParam;
-import kd.bos.orm.ORM;
 import kd.bos.orm.query.QCP;
 import kd.bos.orm.query.QFilter;
+import kd.bos.servicehelper.QueryServiceHelper;
 
 public class ReportBatchQuerySample extends AbstractReportListDataPlugin {
 
-    private static final int COUNT_PER_BATCH = 10000;
+    private static final int COUNT_PER_BATCH = 100;
     private static final int MAX_ROW_COUNT_CACHED = 100000;
+    private static final String ENTITY_NUMBER = "kdtest_report001";
+    private static final String BILL_NO = "billno";
+    private static final String SELECTED_FIELDS = "billno,kdtest_integerfield,kdtest_decimalfield,kdtest_textfield";
 
     @Override
     public DataSet queryBatchBy(ReportQueryParam queryParam) {
@@ -73,12 +76,11 @@ public class ReportBatchQuerySample extends AbstractReportListDataPlugin {
             filters.addAll(queryParam.getFilter().getHeadFilters());
         }
 
-        // 查询分批依据字段（如单据编号）
-        ORM orm = ORM.create();
-        DataSet dataSet = orm.queryDataSet(getClass().getName(),
-                "kdtest_report001", "billno",
-                filters.toArray(new QFilter[0]),
-                queryParam.getSortInfo(), 100000000, null);
+        // 查询分批依据字段（如单据编号），排好序，每批才是连续的一段
+        DataSet dataSet = QueryServiceHelper.queryDataSet(getClass().getName(),
+                ENTITY_NUMBER, BILL_NO,
+                filters.toArray(new QFilter[filters.size()]),
+                BILL_NO, 100000000);
 
         // 设置分批参数
         IReportBatchQueryInfo batchInfo = queryParam.byBatchInfo();
@@ -113,13 +115,11 @@ public class ReportBatchQuerySample extends AbstractReportListDataPlugin {
         for (Row row : currentBatchRows) {
             billNos.add(row.getString(0));
         }
-        filters.add(new QFilter("billno", QCP.in, billNos));
+        filters.add(new QFilter(BILL_NO, QCP.in, billNos));
 
-        ORM orm = ORM.create();
-        String selectedField = "billno,kdtest_integerfield,kdtest_decimalfield,kdtest_textfield";
-        return orm.queryDataSet(getClass().getName(),
-                "kdtest_report001", selectedField,
-                filters.toArray(new QFilter[0]),
+        return QueryServiceHelper.queryDataSet(getClass().getName(),
+                ENTITY_NUMBER, SELECTED_FIELDS,
+                filters.toArray(new QFilter[filters.size()]),
                 queryParam.getSortInfo());
     }
 
@@ -129,20 +129,24 @@ public class ReportBatchQuerySample extends AbstractReportListDataPlugin {
             filters.addAll(queryParam.getFilter().getHeadFilters());
         }
 
-        ORM orm = ORM.create();
-        String selectedField = "billno,kdtest_integerfield,kdtest_decimalfield,kdtest_textfield";
-        return orm.queryDataSet(getClass().getName(),
-                "kdtest_report001", selectedField,
-                filters.toArray(new QFilter[0]),
+        return QueryServiceHelper.queryDataSet(getClass().getName(),
+                ENTITY_NUMBER, SELECTED_FIELDS,
+                filters.toArray(new QFilter[filters.size()]),
                 queryParam.getSortInfo());
     }
 }
 ```
 
 ## 注意事项
+- 按报表示例给出的原则选择分批依据：
+  1. 用来分批的字段，每批对应的报表数据要较为均衡，避免一批耗尽内存
+  2. 尽量采用必录条件或排序字段作为分批依据
+  3. 分批依据字段可以是一个或多个，但 `queryBatchBy` 返回的 DataSet 会全部缓存在内存中：只返回分批依据列，并控制数据量
+  4. 返回的分批依据集要先排序，交给 `query` 的每一批才是连续的一段
+- 分批不等于分页：分批是数据分批加载，分页是列表翻页，通常一批数据可供几十到几百个分页
 - `queryBatchBy` 返回 null 表示不启用分批取数，框架将直接调用 `query` 获取全量数据
 - `queryBatchBy` 返回的 DataSet 每行代表一个批次标识，框架按 `countPerBatch` 分批后逐批调用 `query`，每批数据作为 `query` 的 `selectedObj` 参数传入
-- 分批模式下 `query` 方法可通过 `selectedObj` 参数获取当前批次数据，也可通过 `queryParam.byBatchInfo().getCurrentBatchRows()` 获取当前批次的行数据
-- `setCountPerBatch` 控制每批数据条数，建议根据数据量和内存情况设置（如 10000）
+- 分批模式下 `query` 方法可通过 `selectedObj` 参数获取当前批次数据，也可通过 `queryParam.byBatchInfo().getCurrentBatchRows()` 获取当前批次的行数据——报表示例用的是 `getCurrentBatchRows()`。两者都不读的分批 `query` 每批都返回完整结果，报表会把每行重复显示批次数那么多遍；编译边界会拒绝它（`PLUGIN_SOURCE_BATCH_NOT_NARROWED`）
+- `setCountPerBatch` 设置多少行分批依据组成一批，一批中的每行分批依据都会成为 `query` 里 `in` 条件的一个值：按每个依据值带出的行数来定，并让 `in` 列表保持较短（报表示例每批 100 个物料）
 - `setMaxRowCountCached` 控制最大缓存行数，默认 10 万行
 - 此插件不继承 AbstractFormPlugin，不能调用 `getView()` 等表单方法

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

@@ -0,0 +1,112 @@
+---
+version: "1.0.0"
+framework_version: "8.0.1"
+source_doc: "标品报表案例 06"
+last_updated: "2026-10-19"
+status: "approved"
+scene_name: "报表查询后联动图表"
+related_apis: ["AbstractReportFormPlugin.afterQuery", "PieChart.clearData", "PieChart.createPieSeries", "PieChart.setTitlePropValue", "PieChart.setLegendPropValue", "PieChart.refresh", "PieSeries.setData", "PieSeries.setPropValue", "PieSeries.setRadius", "DataSet.copy", "DataSet.filter", "DataSet.groupBy", "DataSet.orderBy", "GroupbyDataSet.sum", "GroupbyDataSet.finish", "QueryServiceHelper.queryDataSet"]
+topic: "报表表单插件"
+---
+
+# 场景：报表查询后联动图表
+
+## 适用情况
+报表表单在列表旁边放了一个图表——逾期金额前五的客户、各账龄分组的占比——图表必须与列表使用同样的条件。`reportform` 插件在 `afterQuery` 中绘制它，此时查询已经执行：取出报表表单上布局好的图表控件，聚合数值，填充系列，刷新控件。
+
+## 事件/方法说明
+
+- `afterQuery(ReportQueryParam)`：在取数插件的查询之后执行；参数里是列表查询所用的同样条件
+- `this.getControl(key)`：报表表单上布局的图表控件，例如 `PieChart`
+- `PieChart.clearData()` → `createPieSeries(title)` → `PieSeries.setData(ItemValue[])` → `refresh()`：一次完整的绘制；`new ItemValue(name, value)` 是一块扇区
+- `setTitlePropValue(prop, value)`、`setLegendPropValue(prop, value)`、`PieSeries.setPropValue(prop, value)`、`PieSeries.setRadius(inside, outside)`：样式
+- `DataSet.groupBy(keys).sum(field).finish()` 与 `orderBy(new String[]{"field desc"})`：图表自己的聚合，因为列表的行通常比图表要细
+
+## 方法签名
+```java
+@Override
+public void afterQuery(ReportQueryParam queryParam)
+```
+
+## 代码示例
+`extracted` `needs-verification`
+
+逾期金额前五的客户加"其他"，取自列表的条件：
+
+```java
+package kd.bos.plugin.sample.report.bizcase;
+
+import java.math.BigDecimal;
+import java.util.ArrayList;
+import java.util.List;
+
+import kd.bos.algo.DataSet;
+import kd.bos.algo.Row;
+import kd.bos.dataentity.resource.ResManager;
+import kd.bos.entity.report.ReportQueryParam;
+import kd.bos.form.chart.ItemValue;
+import kd.bos.form.chart.PieChart;
+import kd.bos.form.chart.PieSeries;
+import kd.bos.orm.query.QFilter;
+import kd.bos.report.plugin.AbstractReportFormPlugin;
+import kd.bos.servicehelper.QueryServiceHelper;
+
+public class OverdueChartReportFormPlugin extends AbstractReportFormPlugin {
+
+    private static final String ALGO_NAME = "xxx.report.overduechart";
+    private static final String ENTITY_NUMBER = "xxx_arbill";
+    private static final int TOP = 5;
+
+    @Override
+    public void afterQuery(ReportQueryParam queryParam) {
+        super.afterQuery(queryParam);
+        List<QFilter> filters = new ArrayList<>(queryParam.getFilter().getQFilters());
+        // ……与取数插件相同的过滤面板条件，图表才与列表一致
+
+        // 每个客户一行：图表自己的聚合
+        DataSet amounts = QueryServiceHelper.queryDataSet(ALGO_NAME, ENTITY_NUMBER,
+                "customer.name as customer, overdueamt", filters.toArray(new QFilter[filters.size()]), null)
+                .groupBy(new String[]{"customer"}).sum("overdueamt").finish()
+                .orderBy(new String[]{"overdueamt desc"});
+        List<ItemValue> items = new ArrayList<>(TOP + 1);
+        BigDecimal others = BigDecimal.ZERO;
+        int index = 0;
+        try {
+            while (amounts.hasNext()) {
+                Row row = amounts.next();
+                BigDecimal amount = row.getBigDecimal("overdueamt") == null ? BigDecimal.ZERO : row.getBigDecimal("overdueamt");
+                // The first five are slices of their own; the rest add up to "其他"
+                if (index++ < TOP) {
+                    items.add(new ItemValue(row.getString("customer"), amount));
+                } else {
+                    others = others.add(amount);
+                }
+            }
+        } finally {
+            amounts.close();
+        }
+        if (others.signum() != 0) {
+            items.add(new ItemValue(ResManager.loadKDString("其他", "OverdueChartReportFormPlugin_0", "xxx-report"), others));
+        }
+        if (items.isEmpty()) {
+            // 空图表也需要一块占位
+            items.add(new ItemValue(ResManager.loadKDString("无数据", "OverdueChartReportFormPlugin_1", "xxx-report"), 1));
+        }
+        PieChart chart = this.getControl("overduechart");
+        chart.clearData();
+        PieSeries series = chart.createPieSeries(ResManager.loadKDString("逾期金额", "OverdueChartReportFormPlugin_2", "xxx-report"));
+        series.setData(items.toArray(new ItemValue[items.size()]));
+        chart.refresh();
+    }
+}
+```
+
+## 注意事项
+- 图表控件是元数据：在报表表单上布局，用它的标识调用 `getControl`；填充前 `clearData()` 清掉上一次查询的扇区，填充后 `refresh()` 绘制新的
+- 数值要么来自基于 `queryParam` 条件的单独查询（如上），要么来自取数插件共享的 DataSet。标品通过静态 `ThreadLocal` 持有者共享，豁免了平台 PMD 规则 `KdThreadLocalNotAllowedRule`，而且之所以安全，只是因为查询与 `afterQuery` 在同一个请求的同一个线程上执行；如果你也这样共享，读完就移除，否则池化的线程会把它带给下一个请求
+- 每次遍历都会消费 DataSet。两个图表读同一个 DataSet 时，在第一次遍历之前 `copy()`——`DataSet second = first.copy();`——并关闭插件自己持有的副本
+- 标记为合计的行（`sumlevel` 为 1 和 2，见 `report-subtotal-total.md`）会被重复计算；先用 `filter("sumlevel=0")` 去掉它们
+- 聚合之前可用 `DataSet.addField("balance-notdueamt", "overdueamt")` 以表达式派生一列
+- 扇区名称里的百分比：用 `NumberFormat.getPercentInstance()` 格式化占比，拼到名称后面，例如"客户 A(12.34%)"
+- 样式通过属性 map 设置：`setTitlePropValue("textStyle", map)`，`series.setPropValue("label", map)` 配合 `{"normal": {"show": false}}` 隐藏标签，`setLegendPropValue("right", 10)`，`series.setRadius("40%", "80%")` 画成环形
+- 其他图表类型套路相同：`getControl`、一个系列、数据、`refresh()`