@shundoo-ai/dsh-cosmic 1.0.21 → 1.0.22

package/skills/cosmic-build/skills/cosmic-meta-modeling/modules/report/SKILL.md

@@ -40,10 +40,13 @@
 
 - `bos_rpttpl`：默认报表；
 - `bos_rptqingtpl`：轻分析；
-- `bos_grouprpttpl`：分组报表；
+- `bos_grouprpttpl`：分组报表，报表分组面板里放分组列表（它本身是带查询插件的报表列表），旁边是
+  报表数据面板及其报表列表。它不是左树报表；
 - `bos_commfilterrpttpl`：通用过滤查询报表。
 
-需求未指定其他模板时使用 `bos_rpttpl`。
+需求未指定其他模板时使用 `bos_rpttpl`。没有任何公共模板预置左树（`ReportTreeAp`）：只有用户在设计器里
+给报表新增「报表树」控件后报表才有左树，CLI 也没有发布添加该控件的命令。所以要求在左树上导航的需求，
+创建时不带 `reportProperties.tree`；`run` 之后的步骤见 `examples/golden-example-report-tree.md`。
 
 `entities[0].bizName` 不带 ISV 前缀。`entities[0].formNumber` 是最终装饰后的编码：非标准产品为
 `<isvNumber>_<bizName>`，标准产品为 `<bizName>`。`isvNumber` 来自 CLI 自有的 `getDevInfo` 身份，
@@ -67,7 +70,14 @@
   列和分组的 `fieldKey` 都不同：控件会把这个 key 当成自己的元素 key，复用列 key 会让报表在设计器
   里无法保存。要按某个展示列过滤，就用 `flt_<列>` 这样的独立 key，由插件在 `query()` 里把它作用
   到该列上；
-- 每个排序 `fieldKey` 引用已有报表列；
+- 每个排序 `fieldKey` 引用叶子报表列；默认排序要求恰好一个已启用的 Java 取数插件。
+  在 `reportContract.defaultSorts` 中保留规则顺序与区分大小写的 `dateIndex` 映射；仅绑定查询数据源
+  不构成已验证的排序通道。无可承接插件时，`REPORT_DEFAULT_SORT_PLUGIN_REQUIRED` 会在创建前拒绝；
+  禁止丢弃排序或未经授权新增/替换插件；
+- `reportPlugins` 是一个槽位，即报表列表的取数插件，所以只放一个条目；左树的插件是
+  `ReportTreeAp.ReportPlugin`，在报表有了「报表树」控件后由 `setReportProperties --target tree` 写入，
+  负责页面行为的 `reportform` 插件两者都不是：它单独走一次 Java 交付，
+  由 `register_plugins.py` 注册到报表表单的插件列表（`targetType` `BILL_FORM`）；
 - 插件注册只证明元数据注册，不等于业务取数语义已可执行。
 
 已有的完整示例，全部在 CI 中用下面这个校验器校验过：
@@ -76,9 +86,9 @@
 |---|---|
 | `examples/golden-example-report-plugin.md` | 常规场景：列、分组、过滤、排序、一个取数插件，以及列的 `presentation` |
 | `examples/golden-example-report-batch.md` | 大数据量报表：Artifact 里没有任何「分批」字样，该需求落在插件的 `queryBatchBy()` |
-| `examples/golden-example-report-tree.md` | 左树右表：注册两个插件，以及它与折叠式树形行的区别 |
+| `examples/golden-example-report-tree.md` | 左树右表：两个插件注册在两个槽位、用户在 `run` 之后新增的报表树控件，以及它与折叠式树形行的区别 |
 
-先用 `{ROOT_DIR}/skills/cosmic-meta-modeling/scripts/report_validator.py` 校验 Artifact，再执行：
+先用 `{python} "{ROOT_DIR}/skills/cosmic-meta-modeling/scripts/report_validator.py" --artifact "{artifactPath}" --json` 校验 Artifact；该校验器不接收 `--app-root`。然后执行：
 
 ```bash
 {python} "{cosmic_api}" run --app-root "{appRoot}" --artifact "{artifactPath}"
@@ -90,13 +100,28 @@
 2. 绑定声明的查询数据源；
 3. 设置完整报表列树；
 4. 设置完整过滤条件；
-5. 设置默认排序；
+5. 保留默认排序到 Java 查询契约（不写元数据）；
 6. 注册声明的插件；
 7. 应用声明的报表属性。
 
 每条原子 CLI 自行完成目标校验和独立报表读回。失败时只报告对应业务区段；不要搜索源码、
 猜测载荷或切换到通用元数据写入。
 
+## 默认排序是查询要求
+
+`setReportSorts` 以 `REPORT_SORTS_API_UNSAFE` 被阻断，包括 dry-run 和通用回退路径。它的 API
+把排序条目混入默认显示列属性 `InitField`，缺少 `isvisible` 值会使表格设置抛出
+`NullPointerException`。禁止补 `isvisible: true` 掩盖问题或改写显示列配置。存量污染报表
+需要单独进行 API 侧修复；更新技能不会自动修复它们。
+
+Java 交付必须消费报表契约中的 `defaultSorts` 与 `defaultSortPolicy`。
+在 `query()` 中，先处理 `ReportQueryParam.getSortInfo()` 的交互排序，把校验后的 `fieldKey`
+映射到 `dateIndex`；仅在没有交互排序时，按声明顺序应用默认规则。
+在关联、合并、汇总完成后的最终 DataSet 上排序，时机在分页/导出之前，保留权限过滤。
+使用目标 SDK 已核验的排序 API，禁止拼接未经校验的 SQL 片段。契约存在、源码、编译或注册
+均不构成运行证据：默认排序和交互覆盖必须分别验收。run 的 `reportDefaultSorts`
+仍标记为等待 Java 实现，绝不宣称已写入排序元数据或已验证运行行为。
+
 ## 报表属性，一次声明到位
 
 `reportProperties` 承载那些原先需要创建后再调一次才能设的属性。它的成员就是修改期命令面对的那些
@@ -119,13 +144,15 @@
 
 - 列的键要拿本 artifact 自己的 `reportColumns` 去解析，判断它是叶子列还是列分组，因为两者接受的属性
   集不同，而平台对发错宿主的键照收却什么都不改。`R-property-column` 会拒绝它；
-- `tree` 作用于 `ReportTreeAp`，只有带左树的模板才有。普通报表上该写入会被拒绝、整次 run 失败，所以
-  `R-property-tree` 在还能避免建页时就先警告；
+- `tree` 作用于 `ReportTreeAp`，没有任何公共模板带它——`bos_grouprpttpl` 是分组报表，不是左树。本次 run
+  创建的报表没有左树，该写入会在 `createPage` 之后被拒绝，所以 `R-property-tree` 直接拒绝这一段。等用户
+  新增「报表树」控件后，再用 `setReportProperties --target tree` 写入；
 - 其余全部按修改期命令用的同一份白名单校验，于是本会被静默忽略的属性在这里变成 `R-property-target`。
 
-这个段**最后**应用，在过滤条件之后。这个顺序正是要点：`setReportFilters` 把 `ShowFilterFields` 写成
-运行时无法解析的逗号拼接串，因此在这里声明字段列表，才能让新建出来的报表带上 JSON 数组形态。不声明
-它的报表会一直带着那个坏值，直到有人去修。
+这个段**最后**应用，在过滤条件之后。这个顺序正是要点：在未安装类型化报表过滤补丁的平台上，
+`setReportFilters` 把 `ShowFilterFields` 写成运行时无法解析的逗号拼接串，因此在这里声明字段列表，
+才能让在那里新建出来的报表带上 JSON 数组形态；不声明它的报表会一直带着那个坏值，直到有人去修。
+已安装补丁的平台自己写数组，但会按过滤条件重置 `FilterMustInput` 和初始字段，最终值由本段确定。
 
 读路径观察不到的属性——`ColumnWidthStyle`、`MaxRowHeight`、`HeadHeight`、`ReportSumMeta` 以及行背景
 色——在 run 结果里记在 `unverifiable` 下而不是判为失败，并由流水线本来就会同步的设计态导出来结算。
@@ -163,12 +190,15 @@ id 和显示名由平台解析：调用方给的 id 无法证明存在，而存
 
 `setReportColumns` 只在创建时跑一次。平台是往报表实体上**追加**字段而不是替换，所以对同一张报表第二次
 调用会让每个字段 key 重名、保存被拒，而追加的字段已经留下——此后该表单任何保存都不会成功，CLI 会拒绝
-这第二次写入。后续要**加**列可以用 `addReportColumns` 增量追加，但删列、重排或改列类型仍然只能重建
-报表，由 `skills/cosmic-meta-modifier/modules/report-op` 用 `planReportRecreate` 规划——不可逆且会丢掉
-菜单绑定。所以现在把列定对，仍然是最省的路径。
+这第二次写入。后续要**加**列可以用 `addReportColumns` 增量追加。
+后端支持 `ReportColumns.remove` 时，用 `removeReportColumn` 删除一个叶子列；旧后端以
+`REPORT_COLUMN_DELETE_API_UNAVAILABLE` 安全停止，不隐藏或重建。
+删除分组、重排或改列类型仍需单独授权重建，由 `skills/cosmic-meta-modifier/modules/report-op`
+用 `planReportRecreate` 规划——不可逆且会丢掉菜单绑定。删列只更新元数据与本地需求，不会修改
+既有 Java；核对其列绑定后才能宣称运行完成。
 
 因此在调用 `run` 之前就要把完整列清单、标题和类型定好。特别要确认每一列都是取数插件真能产出的。
-注意分组最小值/最大值**是可以表达的** —— `DataSet.splitByGroup` + `topBy` + `union`，见
+注意分组最小值/最大值**是可以表达的** —— `DataSet.groupBy` + `min` / `max`，见
 `{ROOT_DIR}/knowledge/cosmic/platform/sdk/sdk-algo.md` —— 不要因为以为算不出来就把这类列去掉。
 
 ## 能力边界
@@ -186,12 +216,12 @@ Java 交接消费 filterValueContracts。优先已发布 CLI 和独立回读；
 
 剩余边界需明确：
 
-- 报表列展现仍通过插件契约和已核验的 ReportColumnFactory 完成。
-- `reportFilters[].source = {formNumber, fieldKey}` 使用 `ReportFilters.typed` 从准确来源字段创建原生控件。
-  CLI 读取来源类型、引用、枚举及数字/日期配置，保存后独立回读报表配置，并与重新读取的来源比较。
-  日期 `between` 使用 DateRangeField。此能力需要 `assets/platform-report-filters/` 中的平台扩展；
-  旧平台在类型化写入前拒绝，不静默回退成 TextField。未支持的专用类型、组织和条件引用依赖明确失败。
-  未声明 source 时，旧比较符驱动的控件行为仍按部署版本核验。控件类型不证明过滤生效，`compare` 仍是查询要求。
+- 报表列展现通过插件契约交接；已记录的 ReportColumnFactory 签名本身不能证明动态精度可运行。
+- 过滤的控件就是它的 `fieldType`（F7 选择、下拉框、日期范围等，共 25 种），连同该类型的参数，如
+  `basedataNumber` 或 `comboItems`，由平台的类型化报表过滤 API 创建。该 API 以平台补丁发布，而本技能
+  随客户端发布：未安装补丁的平台渲染旧控件（文本框，`between` 时为日期范围），run 在
+  `reportFilterEditors` 下把该过滤报告为降级，而不是失败。回复中要说明这一点；补丁安装后重新设置
+  过滤即可，不必重建报表。`compare` 仍是查询要求，控件本身不证明过滤生效。
 
 这两类需求都不会被丢弃：它们会被编译进一份插件契约
 `{appRoot}/_runtime/<formNumber>.report-plugin-contract.json`，由 `prepare_plugin_handoff` 以
@@ -201,12 +231,16 @@ Java 交接消费 filterValueContracts。优先已发布 CLI 和独立回读；
 `createDecimalColumn`），以及需要随后调用的 `javaFollowUp` setter —— 因为这些签名有文档，而多数
 `ReportColumn.TYPE_*` 常量名没有。
 
-`currencyField` / `measureUnitField` 绑定指向的是**另一个已声明列**的 `fieldKey`，所以那一列也要
-声明出来 —— `fieldType: bigint`、`hide: true`、`fieldKey` 等于它自己的 `dateIndex`。平台按列清单
-构建报表的运行期实体、并按 `fieldKey` 打包行数据，所以指向一个没有任何列拥有的名字什么都解析不到；
-`R-presentation-binding` 会直接拒绝该 Artifact，而不是交付一张没有币别的报表。让目标列的
-`fieldKey` 与 `dateIndex` 相等，可使同一份 Artifact 在该参数的两种读法下都成立 —— 这也是这件事
-不必等实测的原因。
+动态 `currencyField` / `measureUnitField` 绑定当前在所有写入前以
+`REPORT_PRECISION_REFERENCE_UNVERIFIED` 阻断。声明 `fieldType: bigint` 和 `hide: true`
+只会得到 Long，不是精度格式化器读取的 DynamicObject。`fieldKey` 与 `dateIndex` 相同
+不证明引用已物化。`R-presentation-binding` 检查名称；平台引用属性、旧标量迁移和格式化前
+批量物化验证前，`R-presentation-binding-target` 是错误。保留需求，不能通过取消绑定或固定精度
+来宣称完成。
+
+原始/历史插件契约保留 `precisionSource`，其中 `runtimeVerified` 为 false、
+`metadataWriteBlocked` 为 true。工厂调用和 `javaFollowUp` 是签名，不是完整引用实现。
+开放输入契约前须验证混合币别/单位、分组、合计、分页和导出，禁止猜测转换 API。
 
 只要报表有列，就一定有这份契约，因为最基本的那条要求就在里面：`dataSetColumnTypes` 给出每一列的
 `rowAccessor`、`javaType` 与 `algoDataType`。报表会把每个值 set 进一个元数据字段，因此返回错误的
@@ -215,18 +249,20 @@ Java 类型是在 set 阶段失败、报的是字段而不是查询 —— `date
 
 分批查询和导出行为没有元数据通道。在取数插件里实现 `queryBatchBy()` 和 `export()`；树形行为请先读
 `{ROOT_DIR}/references/plugin-runtime-routing.md`，因为左树导航和折叠式树形行是两种不同的插件类型。
-左树自身的元数据设置**确实**有通道——`setReportProperties --target tree`——但导航本身仍是插件的工作。
+左树自身的元数据设置**确实**有通道——`setReportProperties --target tree`，其 `ReportPlugin` 用来注册树插件——
+但导航本身仍是插件的工作。
 
 ## 读回证据
 
 `getReportSchema` 在 `readBackSource` 中说明本次写入由哪种来源证明：
 
-- `canonical`：后端暴露了 `data.reportSchema`，每个区段都被逐项精确校验。
+- `canonical`：后端暴露了 `data.reportSchema`，比较可观察元数据；尚未确认支持的原生排序契约，
+  所以 `reportSorts` 保持未核验。
 - `formLayout`：没有 canonical 投影（已在被测部署上确认不存在）。列和过滤条件从布局树反解，
   所以只能证明其结构，`undecidable*Properties` 给出它看不到的逐项属性。
-- `formLayout+dym`：流水线还同步了平台自身的设计态导出，它能证明布局树承载不了的两个区段：
-  `<InitField>` 证明 `reportSorts`，`<ReportQueryPlugin>` 证明 `reportPlugins`，
-  `unverifiableSections` 相应缩小。它还能证明每个过滤控件上的 `mustInput` 与 `visible` —— 因为
+- `formLayout+dym`：流水线同步了平台自身的设计态导出，`<ReportQueryPlugin>` 证明 `reportPlugins`，
+  `unverifiableSections` 相应缩小。`<InitField>` 是显示列配置，绝不证明 `reportSorts`。
+  它还能证明每个过滤控件上的 `mustInput` 与 `visible` —— 因为
   布局树已经证明了控件存在，所以这是按属性提升而不是按区段提升；这两个名字会离开
   `undecidableFilterProperties`，随后被真正逐项比较。该导出不含插件的 `type` / `bizAppId` / `fpk`，
   也没有 `<DefaultValue>`，这些仍保持不可判定，而不是拿去和缺失值比较。
@@ -253,12 +289,20 @@ Java 类型是在 set 阶段失败、报的是字段而不是查询 —— `date
 一次成功的 `run` —— 或空白路径上的 `createPage` —— 只是元数据边界，不是本轮的终点。
 把已验证的报表身份与 run 结果交还给 app-build，由它在同一轮内完成固定交付顺序：
 
-- 只要 Artifact 声明了插件（`reportPlugins` 或 `reportProperties.pluginExts`），app-build
-  就无需询问地进入 `references/java-plugin-delivery.md`：把报表 Artifact 与 run 结果交给
-  `prepare_plugin_handoff.py`，随后在回复结束前完成源码生成、窄编译、注册与插件读回。
-  编译器自己解析 Java 模块根；只有它返回 `PLUGIN_WORKSPACE_UNRESOLVED` 时才允许问一个
-  关于 Java 模块根的问题。禁止在 `run` 之后以「下一步：Java 源码」式的总结结束本轮，也
-  禁止凭自己对工作区的查看去询问 Java 项目或编译器位置；
+- 只要 Artifact 声明了插件（`reportPlugins` 或
+  `reportProperties.pluginExts`），app-build 就无需询问地进入 `references/java-plugin-delivery.md`：
+  把报表 Artifact 与 run 结果交给 `prepare_plugin_handoff.py`，随后在回复结束前完成源码生成、
+  窄编译、注册与插件读回。每个类按其槽位运行的类型交付 —— 契约的 `pluginTypes` 给出该类型 ——
+  并按该类型的 guide 及其列出的报表场景编码。编译器自己解析 Java 模块根；只有它返回
+  `PLUGIN_WORKSPACE_UNRESOLVED` 时才允许问一个关于 Java 模块根的问题。禁止在 `run` 之后以
+  「下一步：Java 源码」式的总结结束本轮，也禁止凭自己对工作区的查看去询问 Java 项目或编译器位置；
+- 左树的插件永远不在这次 run 里：用户新增「报表树」控件、`setReportProperties --target tree` 写入其
+  `ReportPlugin` 之后，该类按同一流程以 `reporttreelist` 类型针对已有表单编码交付；
+- 需求要求页面行为 —— 表头过滤、工具栏按钮、钻取联查、合计行标签、图表、折叠式树形行 —— 时，app-build
+  还要在同一个报表表单编码上按同一流程交付一个 `reportform` 类，按
+  `{ROOT_DIR}/knowledge/cosmic/platform/report-plugin.md` 及其列出的报表场景编码。
+  `register_plugins.py --verify` 以 `targetType` `BILL_FORM` 注册它，只有回读在 `location` `BILL_FORM`
+  找到它才算交付完成；
 - 未声明插件时，直接进入卡片收口。
 
 两种情况下 app-build 随后都会渲染唯一一组最终产物卡片；用户不需要另行要求输出卡片。

package/skills/cosmic-build/skills/cosmic-meta-modeling/modules/report/examples/golden-example-report-batch.md

@@ -1,7 +1,11 @@
 # 黄金示例：库存台账报表（分批查询）
 
 > 分批查询没有元数据通道。Artifact 里不会出现「分批」二字：这个判断来自需求，最终落在插件的
-> `queryBatchBy()` 覆写上。下面这份 Artifact 就是一份普通的报表 Artifact —— 这恰恰是重点。
+> `queryBatchBy()` 覆写上。下面保留的是历史报表需求，不是当前可写输入。
+>
+> **当前写前拒绝**：`REPORT_PRECISION_REFERENCE_UNVERIFIED`。
+> 三个数量列绑定的隐藏 `unit_id: bigint` 只提供 Long，不能证明格式化前存在 DynamicObject 单位引用。
+> 这是保留分批及动态单位精度要求的历史反例；验证平台引用字段、旧字段迁移和批量物化后才能开放写入。
 
 ## 用户需求
 
@@ -106,6 +110,8 @@
     {
       "fieldPath": "flt_warehouse",
       "displayName": "仓库",
+      "fieldType": "MulBasedataField",
+      "basedataNumber": "bd_warehouse",
       "compare": "in"
     },
     {
@@ -133,13 +139,16 @@
 ```
 
 注意过滤条件的 key：`flt_warehouse` 和 `flt_biz_date` 与每个列 key 都不同，所以生成的控件不会和
-列元素撞 key。日期过滤还声明了 `mustInput: true`，而被测部署不落地这一项 —— 见下面编译出的契约。
+列元素撞 key。仓库过滤声明了自己的控件 —— 基于 `bd_warehouse` 的仓库选择，用户选仓库而不是手输；
+未安装类型化报表过滤补丁的平台会改为渲染文本框，run 把该过滤报告为降级而不是失败。日期过滤还声明了
+`mustInput: true`，只有已安装补丁的平台才会落地这一项 —— 见下面编译出的契约。
 
 ## 编译出的插件契约
 
-`run` 会写出 `{appRoot}/_runtime/kdtest_inv_ledger_rpt.report-plugin-contract.json`，再由
-`prepare_plugin_handoff` 以 `handoff.reportContract` 转交。以下为节选 —— 每种 kind 只留一条展现
-条目，类型条目只留下文要讨论的那一条：
+当前 `run` 在创建报表和写元数据之前拒绝上述输入，不生成成功交付回执。
+以下为原始/历史需求编译结果的节选，不代表输入可写；能力验证后才可进入
+`run` → `{appRoot}/_runtime/kdtest_inv_ledger_rpt.report-plugin-contract.json` →
+`prepare_plugin_handoff` 的目标流程。每种 kind 只展示一条呈现要求：
 
 ```json
 {
@@ -161,7 +170,30 @@
     {
       "fieldKey": "in_qty",
       "kind": "qty",
-      "java": "ReportColumnFactory.createQtyColumn(new LocaleString(\"入库\"), \"in_qty\", \"unit_id\")"
+      "java": "ReportColumnFactory.createQtyColumn(new LocaleString(\"入库\"), \"in_qty\", \"unit_id\")",
+      "precisionSource": {
+        "fieldKey": "unit_id",
+        "requiredRuntimeValueType": "DynamicObject",
+        "runtimeVerified": false,
+        "rawIdIsReference": false,
+        "metadataWriteBlocked": true
+      }
+    }
+  ],
+  "filterValueContracts": [
+    {
+      "filterKey": "flt_warehouse",
+      "compare": "in",
+      "editorFieldType": "MulBasedataField",
+      "valueAccessor": "ReportQueryParam.getFilter().getDynamicObjectCollection(\"flt_warehouse\")",
+      "valueJavaType": "DynamicObjectCollection",
+      "legacyEditor": {
+        "fieldType": "TextField",
+        "valueAccessor": "ReportQueryParam.getFilter().getString(\"flt_warehouse\")",
+        "valueJavaType": "String"
+      },
+      "basedataNumber": "bd_warehouse",
+      "multiValue": true
     }
   ],
   "filterEnforcement": [
@@ -175,10 +207,15 @@
 }
 ```
 
-`unit_id` 是一个隐藏列，被三个数量列共同绑定，所以它的类型条目会把三者都列在 `requiredBy` 里。一个
-绑定目标可以服务任意多个格式化列，所以没有理由声明三次 —— 但也没有办法省掉它：绑定指向的是某个已声明
-列的 `fieldKey`，而平台是按列清单构建运行期实体的。插件必须自己拒绝空的 `flt_biz_date`，因为元数据的
-`mustInput` 没有落地。
+`unit_id` 的 `requiredBy` 只记录三个数量列的共享依赖；隐藏 bigint 的 Long 值不是
+DynamicObject 引用。声明列、名称一致及 `createQtyColumn` 工厂签名均不证明已有 BigInt
+属性已迁移或运行行已物化。三个数量列都必须保留 `precisionSource` 未验证状态；平台能力
+验证前整体拒绝，不能删除绑定或改成固定精度来完成。插件仍须在取数前拒绝空的
+`flt_biz_date`，配置必录不能代替查询必录校验。
+
+`flt_warehouse` 给出了 `query()` 可能收到的两种值：选中的仓库是 `DynamicObjectCollection`，未安装
+补丁的平台渲染的文本框则给出用户输入的 `String`。选中记录必须经业务引用提取真实编码，不能读取包装行身份。
+文本形态只是旧部署兼容边界，不代表仓库选择/F7 多选体验完成；所需补丁安装、过滤重新设置并运行验收后才能交付。
 
 物料列这一条要看仔细。它的 `fieldKey` 是 `material_ref`，`dateIndex` 是 `material_id`，而没有任何
 `ReportColumnFactory` 签名接受 `dateIndex` —— 所以工厂造出来的列只带 fieldKey，会渲染成空。这就是
@@ -188,22 +225,27 @@
 
 ## 插件形态
 
-`queryBatchBy` 返回分批键并配置批量大小；随后 `query` 会被逐批调用，并用当前批次的行收窄自己的
+`queryBatchBy` 返回按分批键自身排序的分批键，让每一批是一段连续范围，并配置批量大小：每批 100 个键，让每批的
+`in` 列表保持较短。随后 `query` 会被逐批调用，并用当前批次的行收窄自己的
 查询。`queryBatchBy` 返回 `null` 表示让框架走单次查询 —— 用户选的日期区间很小时正是这样处理。
 
+以下 Java 片段仅展示分批和 DataSet 别名形状，省略的过滤 helper 必须落实身份、compare、必录及权限。
+`unit as unit_id` 返回 Long 主键，尚无格式化前批量 DynamicObject 物化实现；该片段不能作为动态精度根治交付。
+
 ```java
 public class InvLedgerReportPlugin extends AbstractReportListDataPlugin {
 
     private static final String ALGO_NAME = InvLedgerReportPlugin.class.getName();
     private static final String ENTITY_NUMBER = "im_stock_trans_detail";
-    private static final int COUNT_PER_BATCH = 10000;
+    private static final String BILL_NO = "billno";
+    private static final int COUNT_PER_BATCH = 100;
     private static final int MAX_ROW_COUNT_CACHED = 100000;
 
     @Override
     public DataSet queryBatchBy(ReportQueryParam queryParam) {
-        ORM orm = ORM.create();
-        DataSet keys = orm.queryDataSet(ALGO_NAME, ENTITY_NUMBER, "billno",
-                filtersOf(queryParam), queryParam.getSortInfo(), 100000000, null);
+        // 按分批键自身排序，让每一批是一段连续范围
+        DataSet keys = QueryServiceHelper.queryDataSet(ALGO_NAME, ENTITY_NUMBER, BILL_NO,
+                filtersOf(queryParam), BILL_NO, 100000000);
         IReportBatchQueryInfo batchInfo = queryParam.byBatchInfo();
         batchInfo.setCountPerBatch(COUNT_PER_BATCH);
         batchInfo.setMaxRowCountCached(MAX_ROW_COUNT_CACHED);
@@ -219,13 +261,13 @@ public class InvLedgerReportPlugin extends AbstractReportListDataPlugin {
             for (Row row : batchInfo.getCurrentBatchRows()) {
                 billNos.add(row.getString(0));
             }
-            filters.add(new QFilter("billno", QCP.in, billNos));
+            filters.add(new QFilter(BILL_NO, QCP.in, billNos));
         }
         // DataSet 列名必须与每个 dateIndex 相等，包括 unit_id。
-        return ORM.create().queryDataSet(ALGO_NAME, ENTITY_NUMBER,
+        return QueryServiceHelper.queryDataSet(ALGO_NAME, ENTITY_NUMBER,
                 "warehouse.name as warehouse_name, material as material_id, biz_date,"
                         + " in_qty, out_qty, closing_qty, unit as unit_id",
-                filters.toArray(new QFilter[0]), queryParam.getSortInfo());
+                filters.toArray(new QFilter[filters.size()]), queryParam.getSortInfo());
     }
 }
 ```
@@ -234,9 +276,12 @@ public class InvLedgerReportPlugin extends AbstractReportListDataPlugin {
 
 ## 预期结果
 
+当前输入被写前拒绝，不创建报表、不写元数据。以下仅是平台引用链路与技能契约开放后的待验收目标，
+包括混合单位精度、分组、合计、分页和导出；保存回执或分批源码不构成运行验收。
+
 - 报表表单 `kdtest_inv_ledger_rpt` 由 `bos_rpttpl` 创建
 - 7 个列，其中 3 个分组在「数量」之下，1 个隐藏计量单位列
-- 过滤面板含仓库多选和一个由插件强制必填的日期区间
+- 过滤面板含仓库选择（平台安装类型化过滤补丁之前是文本框）和一个由插件强制必填的日期区间
 - 默认排序 `warehouse_name asc`、`material_ref asc`
 - `kd.kdtest.report.InvLedgerReportPlugin` 已注册到报表取数插件位
 - 插件契约携带 4 条展现绑定和 1 条过滤要求

package/skills/cosmic-build/skills/cosmic-meta-modeling/modules/report/examples/golden-example-report-plugin.md

@@ -1,7 +1,8 @@
 # 黄金示例：KPI 分析报表（取数插件）
 
-> 每张报表都由插件驱动：报表元数据声明展现，取数插件返回数据行。本示例展示完整 Artifact，以及
-> 它的列标识如何与插件构建的 DataSet 挂接。
+> 每张报表都由插件驱动：报表元数据声明展现，取数插件返回数据行。本历史示例现为拒绝用例：
+> `REPORT_PRECISION_REFERENCE_UNVERIFIED` 在创建前阻断。隐藏 bigint 币别列不能满足动态精度。
+> 保留需求至平台引用和批量物化验证完成；禁止把它复制为可运行的黄金输入。
 
 ## 用户需求
 
@@ -86,6 +87,8 @@
     {
       "fieldPath": "org_id",
       "displayName": "Sales Org",
+      "fieldType": "MulBasedataField",
+      "basedataNumber": "bos_org",
       "compare": "in"
     },
     {
@@ -113,17 +116,19 @@
 
 ## 执行流程
 
+0. 写前校验 → 拒绝本历史 Artifact，不发送写入。以下仅描述平台引用能力和技能契约验证后的目标流程。
 1. `createPage` → 用默认模板创建报表；获取 `formId`
 2. `setReportColumns` → 6 个列，其中 2 个在 "Growth Indicators" 分组下、1 个隐藏：
    `currency_id` 存在的原因是收入列绑定了它
-3. `setReportFilters` → 销售组织（`in`）和期间（`between`）两个控件。期间过滤的 key 是
-   `flt_period` 而不是 `period`：控件以自己的 key 作为元素 key，而展示列已经占用了 `period`。
-   插件从 `ReportQueryParam.getFilter()` 读 `flt_period`，再作用到该列。
-4. `setReportSorts` → 先 `period desc`，再 `org_name asc`
+3. `setReportFilters` → 销售组织选择（基于 `bos_org` 的 `MulBasedataField`，所以用 `in`）和期间区间
+   （`between`）。期间过滤的 key 是 `flt_period` 而不是 `period`：控件以自己的 key 作为元素 key，而展示列
+   已经占用了 `period`。插件从 `ReportQueryParam.getFilter()` 读 `flt_period`，再作用到该列。
+4. 保留 `reportSorts` → 将先 `period desc`、再 `org_name asc` 编译为 `defaultSorts`；不调用已阻断的 `setReportSorts`
 5. `registerReportPlugin` → 注册 `kd.kdtest.report.KpiAnalysisReportPlugin`
 6. Java 交付 → 实现 `query()`，返回列名恰好为 `org_name`、`period`、`revenue`、`currency_id`、
    `yoy_rate`、`mom_rate` 的 DataSet。`currency_id` 之所以在列里，是因为 revenue 列声明了币别
-   绑定；编译出的插件契约会把它列进 `dataSetColumns`。
+   绑定；编译出的插件契约会把它列进 `dataSetColumns`。在分页/导出前的最终 DataSet 中消费
+   `defaultSorts` 和 `defaultSortPolicy`，交互排序优先；分别验证默认排序和交互排序。
 
 ## 为什么没有 `dataSources` 区段
 
@@ -150,7 +155,7 @@
 }
 ```
 
-它永远不会发往平台。流水线把它编译成
+它永远不会发往平台。创建流水线拒绝该输入；只有原始/历史需求编译可将它保留到
 `{appRoot}/_runtime/kdtest_kpi_analysis_rpt.report-plugin-contract.json`，再由
 `prepare_plugin_handoff` 以 `handoff.reportContract` 转交：
 
@@ -173,26 +178,31 @@
       "bindsTo": "currency_id",
       "scale": 2,
       "java": "ReportColumnFactory.createAmountColumn(new LocaleString(\"Revenue\"), \"revenue\", \"currency_id\")",
-      "javaFollowUp": ["setScale(2)"]
+      "javaFollowUp": ["setScale(2)"],
+      "precisionSource": {
+        "fieldKey": "currency_id",
+        "requiredRuntimeValueType": "DynamicObject",
+        "runtimeVerified": false,
+        "rawIdIsReference": false,
+        "metadataWriteBlocked": true
+      }
     }
   ]
 }
 ```
 
-`currency_id` 是一个已声明的列，不是游离的 DataSet 列。币别绑定指向的是另一个报表列的
-`fieldKey`：平台按列清单构建运行期实体、并按 `fieldKey` 打包行数据，所以指向一个没有任何列拥有的
-名字什么都解析不到。这就是它被声明为 `bigint` + `hide: true` 的原因 —— 对平台可见，对用户不可见 ——
-也是契约把它标为 `requiredBy: ["revenue"]` 的原因。它看起来可以删，其实不能。
-
-绑定目标列保持 `fieldKey` 等于 `dateIndex` 是刻意的：这样无论平台把 `currencyField` 读作列 key 还是
-读作 DataSet 列名，同一份 Artifact 都成立。`R-presentation-binding` 会同时拒绝「目标不存在」和
-「目标的两者不一致」。
+`currency_id` 是已声明的 `bigint` + `hide: true` 列，值仍为 Long，不是格式化器所需的
+DynamicObject。`requiredBy: ["revenue"]` 保留依赖，不证明成功。`fieldKey` 与 `dateIndex`
+相同只满足 `R-presentation-binding` 的名称校验；`currencyField` 仍缺引用物化。
+`precisionSource` 明确保持未验证和写入阻断。重新开放写入前须验证持久化引用、旧 BigInt 迁移和
+批量运行行物化；不能取消绑定或把固定精度称作完成。
 
 `period` 展示的是同一份契约的另一面：`date` 列必须是 `java.util.Date`，返回格式化后的字符串会在
 渲染时抛 `setvalue fail, name: period, Unparseable date`。
 
-在 `getColumns()` 里用契约给出的工厂调用绑定展现 —— 这些签名有文档，而多数
-`ReportColumn.TYPE_*` 常量名没有。注意递归：`ReportColumnGroup` 是 `AbstractReportColumn` 但不是
+以下 `getColumns()` 片段仅展示已记录签名及递归，不是可运行的动态精度修复；它不能升级已有
+BigInt 属性或物化运行行引用。引用要求满足前禁止复制到交付中；多数 `ReportColumn.TYPE_*`
+常量名缺少证据。`ReportColumnGroup` 是 `AbstractReportColumn` 但不是
 `ReportColumn`，分组内的列在它的 `getChildren()` 里、从不出现在顶层列表中，因此带强转的扁平循环
 既命中不到它们、又会抛异常：
 
@@ -227,8 +237,10 @@ private void bindPresentation(List<AbstractReportColumn> nodes) {
 
 ## 预期结果
 
+当前结果是写前拒绝，不创建报表或写入元数据。以下只是将来验收目标，不是已达成结果：
+
 - 报表表单 `kdtest_kpi_analysis_rpt` 由 `bos_rpttpl` 创建
 - 6 个列，其中 2 个分组在 "Growth Indicators" 之下，1 个隐藏币别列
-- 过滤面板包含销售组织和期间区间
+- 过滤面板包含销售组织选择和期间区间
 - 默认排序 `period desc`、`org_name asc`
 - `kd.kdtest.report.KpiAnalysisReportPlugin` 已注册到报表取数插件位