@shundoo-ai/dsh-cosmic 1.0.21 → 1.0.22

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

@@ -1,8 +1,12 @@
 # 黄金示例：成本分析报表（左树右表）
 
-> 「树形报表」指的是两种不同的功能。本示例是左树右表那一种，它需要**两个**插件：一个
-> `reporttreelist` 插件构建左侧导航，一个 `reportlist` 插件产出所选节点的数据行。把同一批数据按
-> 层级折叠展示是另一种功能 —— 见最后一节。
+> 「树形报表」指的是两种不同的功能。本示例是左树右表那一种，它需要**两个**插件、注册在**两个**
+> 槽位：一个 `reporttreelist` 插件在左树上构建导航，一个 `reportlist` 插件在报表列表上产出所选
+> 节点的数据行。把同一批数据按层级折叠展示是另一种功能 —— 见最后一节。
+>
+> **当前写前拒绝**：`REPORT_PRECISION_REFERENCE_UNVERIFIED`。
+> 预算、实际及差异金额绑定隐藏 `currency_id: bigint`，其 Long 主键不是 DynamicObject 精度引用。
+> 此 Artifact 是保留左树和动态币别需求的历史反例，不是当前可写输入；不能用固定精度或删绑定代替完成。
 
 ## 用户需求
 
@@ -17,9 +21,16 @@
 - `reporttreelist` —— `AbstractReportTreeDataPlugin.query(ReportQueryParam, String nodeId)`
   返回 `List<TreeNode>`；只负责构建组织树
 - `reportlist` —— `AbstractReportListDataPlugin.query(ReportQueryParam, Object selectedObj)`；
-  被点击的节点作为 `selectedObj` 传入，用来收窄数据行
+  被点击节点的 id 作为 `selectedObj` 传入，用来收窄数据行
 
-元数据对这两者一无所知。Artifact 声明展现，两个插件都注册为报表插件。
+两者注册在不同的位置，而且创建时只注册其中一个。没有任何公共模板预置左树：`bos_grouprpttpl` 是
+分组报表 —— 报表分组面板里放分组列表，旁边是报表数据面板 —— 不是左树报表，`bos_rpttpl` 也没有左树。
+只有用户在设计器里给报表新增「报表树」控件后，报表才有左树（`ReportTreeAp`），CLI 也没有发布添加该
+控件的命令。所以报表由 `bos_rpttpl` 创建，取数插件放进 `reportPlugins`，即报表列表的
+`ReportQueryPlugin`；树插件等控件存在之后再放进 `ReportTreeAp.ReportPlugin`，即左树自己的槽位。
+在 Artifact 里声明 `reportProperties.tree` 会被 `R-property-tree` 拒绝：在本次 run 创建的页面上，
+该写入会在 `createPage` 之后失败。把树插件类当作第二个 `reportPlugins` 条目注册，会把它放到列表的
+取数槽位上，在那里它构建不出任何树 —— `R-plugin-slot` 正是针对这种写法给出警告。
 
 ## 预期 Artifact
 
@@ -100,12 +111,6 @@
     { "fieldKey": "cost_item", "direction": "asc" }
   ],
   "reportPlugins": [
-    {
-      "type": "Java",
-      "className": "kd.kdtest.report.CostAnalysisTreePlugin",
-      "description": "左侧组织树导航",
-      "enabled": true
-    },
     {
       "type": "Java",
       "className": "kd.kdtest.report.CostAnalysisReportPlugin",
@@ -119,21 +124,45 @@
 ```
 
 这里没有 `org` 列：组织是导航维度，不是行的列。期间过滤 key 是 `flt_period`，与每个列 key 都不同。
+这里也没有 `reportProperties.tree`：本 Artifact 执行时左树还不存在。
 
 ## 执行流
 
-1. `createPage` → 由默认模板创建报表
+0. 当前在 `createPage` 前拒绝上述输入。先验证平台币别引用字段、旧 BigInt 迁移及格式化前批量
+   DynamicObject 物化，再开放技能契约。原始/历史契约的每个金额列保留 `precisionSource`：
+   `requiredRuntimeValueType=DynamicObject`、`runtimeVerified=false`、`rawIdIsReference=false`、
+   `metadataWriteBlocked=true`；`requiredEvidence` 还要求混合币别、分组、合计、分页和导出验收。
+   以下步骤仅是能力验证后的目标流程，未执行不代表已交付。
+
+1. `createPage` → 由 `bos_rpttpl` 创建报表；没有任何公共模板带左树
 2. `setReportColumns` → 5 个列，其中 3 个在「金额」之下、1 个隐藏：三个金额列都绑定
-   `currency_id`，所以那一列必须存在
+   `currency_id`，保留共享依赖。仅声明隐藏列、名称一致或调用 getColumns() 工厂不能证明引用已物化
 3. `setReportFilters` → 一个期间控件
-4. `setReportSorts` → `cost_item asc`
-5. `registerReportPlugin` × 2 → 树插件与取数插件。`registerReportPlugin` 按 `className` 幂等更新，
-   所以两次调用注册两个插件，而不是替换掉一个。
-6. Java 交付 → 两个类
+4. 保留 `reportSorts` → 将 `cost_item asc` 编译为 `defaultSorts`；不调用已阻断的 `setReportSorts`
+5. `registerReportPlugin` → 取数插件，写入报表列表的 `ReportQueryPlugin`
+6. Java 交付 → `CostAnalysisReportPlugin` 按类型 `reportlist` 交付。编译出的插件契约在
+   `pluginClasses` 里列出它、在 `pluginTypes` 里给出其类型；源码归档之前，出卡会以
+   `REPORT_PLUGIN_SOURCE_MISSING` 被拒绝。左树存在之前 `selectedObj` 为 null，报表显示不收窄的数据行。
+   在分页/导出前的最终 DataSet 中消费 `defaultSorts` 和 `defaultSortPolicy`，交互排序优先；
+   分别验证默认排序和交互排序。
+7. 用户在设计器里给报表新增「报表树」控件（`ReportTreeAp`）。下面的命令按这个类型定位它，
+   不论该控件的 key 是什么
+8. `setReportProperties --target tree` 把树插件类名写入 `ReportTreeAp.ReportPlugin`；报表没有该控件时
+   这一写入会以 `REPORT_PROPERTY_ELEMENT_MISMATCH` 被拒绝：
+
+   ```bash
+   {python} "{cosmic_api}" setReportProperties \
+     --app-root "{appRoot}" --formNumber kdtest_cost_analysis_rpt \
+     --target tree --input '{"ReportPlugin": "kd.kdtest.report.CostAnalysisTreePlugin"}'
+   ```
+
+9. Java 交付 → `CostAnalysisTreePlugin` 按类型 `reporttreelist` 交付，针对已有表单编码准备，而不是
+   针对 Artifact —— Artifact 里从未出现过它
 
 ## 插件形态
 
-树插件返回导航节点。首次加载时 `nodeId` 为 null，这种情况必须返回根节点列表：
+树插件返回导航节点。首次加载时 `nodeId` 为 null，这种情况必须返回根节点列表；`setLeaf(false)` 的
+节点会显示展开箭头，展开时框架会带着该节点的 id 再调一次 `query`：
 
 ```java
 public class CostAnalysisTreePlugin extends AbstractReportTreeDataPlugin {
@@ -145,7 +174,7 @@ public class CostAnalysisTreePlugin extends AbstractReportTreeDataPlugin {
         List<TreeNode> nodes = new ArrayList<>();
         QFilter parent = new QFilter("parent", QCP.equals,
                 nodeId == null || "0".equals(nodeId) ? 0L : Long.parseLong(nodeId));
-        DataSet ds = ORM.create().queryDataSet(ALGO_NAME, "bos_org",
+        DataSet ds = QueryServiceHelper.queryDataSet(ALGO_NAME, "bos_org",
                 "id,number,name,parent,isleaf", new QFilter[]{parent}, "number");
         try {
             while (ds.hasNext()) {
@@ -153,8 +182,8 @@ public class CostAnalysisTreePlugin extends AbstractReportTreeDataPlugin {
                 TreeNode node = new TreeNode();
                 node.setId(String.valueOf(row.getLong("id")));
                 node.setText(row.getString("number") + " " + row.getString("name"));
-                node.setpId(String.valueOf(row.getLong("parent")));
-                node.setIsParent(!row.getBoolean("isleaf"));
+                node.setParentid(String.valueOf(row.getLong("parent")));
+                node.setLeaf(row.getBoolean("isleaf"));
                 nodes.add(node);
             }
         } finally {
@@ -165,8 +194,12 @@ public class CostAnalysisTreePlugin extends AbstractReportTreeDataPlugin {
 }
 ```
 
-取数插件按拿到的节点收窄。这里最经典的 bug 就是忽略 `selectedObj`：那样无论用户怎么导航，报表都会
-显示所有组织的数据行。
+取数插件按拿到的节点收窄：`selectedObj` 是被点击节点的 id，即树插件用 `setId` 设置的那个字符串。
+这里最经典的 bug 就是忽略它：那样无论用户怎么导航，报表都会显示所有组织的数据行。`selectedObj`
+为 null（还没有点击节点）时返回不收窄的数据行。
+
+以下 Java 片段只展示导航条件和 DataSet 别名。`currency as currency_id` 返回 Long 主键，
+尚未实现格式化前批量引用物化，不能作为动态精度根治交付；期间必录还须使用共用空值规则并在取数前验证。
 
 ```java
 public class CostAnalysisReportPlugin extends AbstractReportListDataPlugin {
@@ -178,7 +211,7 @@ public class CostAnalysisReportPlugin extends AbstractReportListDataPlugin {
     public DataSet query(ReportQueryParam queryParam, Object selectedObj) throws Throwable {
         FilterInfo filter = queryParam.getFilter();
         List<QFilter> filters = new ArrayList<>(filter.getQFilters());
-        // 期间过滤的必填不会被元数据落地，所以在这里强制。
+        // 配置必录与查询校验不同；取数前必须再次校验。
         FilterItemInfo period = filter.getFilterItem("flt_period");
         if (period == null || period.getValue() == null) {
             throw new KDBizException("期间必填。");
@@ -188,20 +221,25 @@ public class CostAnalysisReportPlugin extends AbstractReportListDataPlugin {
             filters.add(new QFilter("org", QCP.equals, Long.parseLong(selectedObj.toString())));
         }
         // 列名必须与每个 dateIndex 相等，包括 currency_id。
-        return ORM.create().queryDataSet(ALGO_NAME, ENTITY_NUMBER,
+        return QueryServiceHelper.queryDataSet(ALGO_NAME, ENTITY_NUMBER,
                 "costitem.name as cost_item, budget_amt, actual_amt,"
                         + " actual_amt - budget_amt as variance_amt, currency as currency_id",
-                filters.toArray(new QFilter[0]), "cost_item");
+                filters.toArray(new QFilter[filters.size()]), "cost_item");
     }
 }
 ```
 
-参考：`{ROOT_DIR}/knowledge/cosmic/platform/scenes/report/report-tree-data-query.md` 与
+如果改为一次性构建整棵树 —— 一个合成的「全部」根节点，通过 `setChildren` 挂上全部节点 —— 根节点
+的 id 也要同样处理：先约定根 id 对取数插件意味着什么（不收窄，或子节点 id 集合），并让每个 id
+在多次查询之间唯一且稳定，否则选中节点与其缓存的数据行会对不上。
+
+参考：`{ROOT_DIR}/knowledge/cosmic/platform/reporttreedata-plugin.md`、
+`{ROOT_DIR}/knowledge/cosmic/platform/scenes/report/report-tree-data-query.md` 与
 `{ROOT_DIR}/knowledge/cosmic/platform/reportlistdata-plugin.md`。
 
 ## 如果需求其实是折叠式的行
 
-把同一批数据按层级折叠展示是另一种功能，不需要树插件。它属于 `reportform` 插件的职责：
+把同一批数据按层级折叠展示是另一种功能，既不需要树插件，也不需要报表树控件。由 `reportform` 插件开启：
 
 ```java
 @Override
@@ -211,13 +249,22 @@ public void setTreeReportList(TreeReportListEvent event) {
 }
 ```
 
-在 `beforeQuery` 里调 `ReportQueryParam.setTreeReportList(true)` 等价。取数插件照常返回普通行；
-关于 `id` / `pid` 作为 DataSet 列没有任何文档约定，不要臆造。
+在 `beforeQuery` 里调 `ReportQueryParam.setTreeReportList(true)` 等价。取数插件随后以数据行的形式
+返回层级：每一行都带 `rowid`（本行唯一 id，String）、`pid`（父行的 `rowid`，顶层行为 `"0"`）和
+`isgroupnode`（分组行为 1，明细行为 0），这与标准产品树形报表的构造方式一致。不要用 `id` / `pid`
+代替它们。`reportform` 插件不是 `reportPlugins` 条目：那个槽位是报表列表的取数插件。它在同一个表单编码上
+单独走一次 Java 交付，由 `register_plugins.py --verify` 以 `targetType` `BILL_FORM` 注册，工具栏监听写在
+`registerListener` 里。见
+`{ROOT_DIR}/knowledge/cosmic/platform/scenes/report/report-tree-list.md`。
 
 ## 预期结果
 
+当前输入被写前拒绝，不创建报表、不写元数据。以下仅为引用链路和技能契约开放后的待验收目标；
+源码、编译或保存回执不代表左树交互及混合币别精度已验收。
+
 - 报表表单 `kdtest_cost_analysis_rpt` 由 `bos_rpttpl` 创建
 - 5 个列，3 个分组在「金额」之下，1 个隐藏币别列，组织有意不作为列
 - 一个期间过滤，由插件强制必填
 - 默认排序 `cost_item asc`
-- `CostAnalysisTreePlugin` 与 `CostAnalysisReportPlugin` 均已注册
+- `CostAnalysisReportPlugin` 位于报表取数插件槽位；用户新增报表树控件之后，`CostAnalysisTreePlugin`
+  位于左树。两者都作为 Java 源码交付

package/skills/cosmic-build/skills/cosmic-meta-modeling/modules/report/report-artifact-schema.json

@@ -12,7 +12,8 @@
     },
     "templateNumber": {
       "enum": ["bos_rpttpl", "bos_rptqingtpl", "bos_grouprpttpl", "bos_commfilterrpttpl"],
-      "default": "bos_rpttpl"
+      "default": "bos_rpttpl",
+      "description": "bos_rpttpl is the default report. bos_grouprpttpl is the grouped report: a report group panel holding a group list (itself a report list with its own query plugin) beside the report data panel and its report list. No public template presets a left tree (ReportTreeAp): one exists only after a user adds the report tree control to the report in the designer, so a creation Artifact never declares reportProperties.tree (R-property-tree)."
     },
     "entities": {
       "type": "array",

package/skills/cosmic-build/skills/cosmic-meta-modeling/references/authoring-companion-fields.md

@@ -7,6 +7,9 @@
 
 `QtyField.unitFieldRef` 使用同一实体内 `UnitField` 的 authoring `bizWord`：
 
+保留需求中的配对关系：各自独立的数量/单位需要分别定义 `UnitField` 并对应引用；业务明确共用
+单位时才复用一个单位字段。引用合法不代表这种业务选择正确。
+
 ```json
 [
   {"bizWord": "unit", "displayName": "单位", "dataType": "UnitField"},

package/skills/cosmic-build/skills/cosmic-meta-modeling/references/authoring-list-configuration.md

@@ -29,3 +29,5 @@ emitter 会把自建字段引用解析为最终持久化编码，并依据 `getE
 
 只写需求明确提出的行为；未指定时省略 `order` 和 `hyperlink`。不得手写
 `listcol_*`、控件类型、父容器或 MetaOps；`runBatch` 会在一个列表配置步骤中完成编译和回读。
+
+列也接受 `properties`，从 fieldRef 绑定到真实 fieldKey 时完整保留，再由 configureList 按实际列类型校验。整数汇总示例：`{"fieldRef":"count","properties":{"Summary":"合计","ZeroShow":true}}`。未要求的属性一律省略。

package/skills/cosmic-build/skills/cosmic-meta-modeling/scripts/data_model_contract.py

@@ -1085,7 +1085,9 @@ def validate_authoring_contract(
                             for boolean_key in ("hyperlink",):
                                 if boolean_key in column and not isinstance(column[boolean_key], bool):
                                     _issue(issues, "DM_SCHEMA_TYPE", f"{column_path}.{boolean_key}", "must be a boolean")
-                            for key in sorted(set(column) - {"fieldRef", "order", "hyperlink"}):
+                            if "properties" in column and (not isinstance(column["properties"], dict) or not column["properties"]):
+                                _issue(issues, "DM_SCHEMA_TYPE", f"{column_path}.properties", "must be a non-empty property map")
+                            for key in sorted(set(column) - {"fieldRef", "order", "hyperlink", "properties"}):
                                 _issue(issues, "DM_SCHEMA_FORBIDDEN", f"{column_path}.{key}", "unknown list column configuration key")
                 for collection_key in ("quickSearch", "commonFilters"):
                     values = list_config.get(collection_key)

package/skills/cosmic-build/skills/cosmic-meta-modeling/scripts/data_model_emit.py

@@ -193,7 +193,7 @@ def _run_cosmic_api(
         if proc.returncode != 0:
             detail = (proc.stdout or proc.stderr or "").strip()
             print(f"[cosmic-api] {command} failed (exit={proc.returncode}): {detail}", file=sys.stderr)
-            return None
+            return json.loads(proc.stdout) if proc.stdout.strip() else None
         output = (proc.stdout or "").strip()
         if not output:
             return None
@@ -1897,6 +1897,10 @@ def _merge_template_fields(
         etype = str(ent.get("type") or "")
         template_key = str(ent.get("templateKey") or "").strip()
 
+        if etype == "BillEntity" and template_key.casefold() in {"blank", "blankpage"}:
+            # The platform's blank bill has no preset fields to merge.
+            continue
+
         if not template_key:
             if etype in _CHILD_ENTITY_TYPES:
                 # EntryEntity does not need its own templateKey; inherits parent entity template via parentEntityRef
@@ -1912,6 +1916,9 @@ def _merge_template_fields(
             if not parent_ent:
                 continue
             parent_tk = str(parent_ent.get("templateKey") or "").strip()
+            if (str(parent_ent.get("type") or "") == "BillEntity"
+                    and parent_tk.casefold() in {"blank", "blankpage"}):
+                continue
             if not parent_tk:
                 continue
             if parent_tk not in api_cache:
@@ -2211,6 +2218,10 @@ def _validate_template_keys(
             result = _run_cosmic_api(
                 cosmic_api_path, command, arguments, app_root=bound_root,
             )
+            if isinstance(result, dict) and result.get("errorCategory") in {"environment", "authentication"}:
+                logs.err(result.get("errorCode") or "TEMPLATE-LOOKUP-UNAVAILABLE",
+                         result.get("message") or "Template lookup environment is unavailable")
+                return False
             data = result.get("data") if isinstance(result, dict) else None
             templates = data.get("templates") if isinstance(data, dict) else None
             if (not isinstance(result, dict) or result.get("status") is not True
@@ -2240,6 +2251,8 @@ def _validate_template_keys(
                      en=f"Entity '{ent.get('bizName')}' (type={etype}) missing templateKey, please specify")
             ok = False
             continue
+        if etype == "BillEntity" and tk.casefold() in {"blank", "blankpage"}:
+            tk = "blankPage"
         expected_model = model_type_by_entity.get(etype)
         if not expected_model:
             continue
@@ -2943,9 +2956,9 @@ def _compile_list_configuration(
         if not isinstance(column, dict):
             continue
         item: dict[str, Any] = {"fieldKey": resolve(column.get("fieldRef"))}
-        for key in ("order", "hyperlink"):
+        for key in ("order", "hyperlink", "properties"):
             if key in column:
-                item[key] = column[key]
+                item[key] = copy.deepcopy(column[key])
         columns.append(item)
     if columns:
         compiled["columns"] = columns
@@ -4894,6 +4907,16 @@ def main(argv: list[str] | None = None) -> int:
         else:
             print(f"DATAMODEL_SECTION_NOT_FOUND: app-root does not exist {app_root}", file=sys.stderr)
         return EXIT_DATAMODEL_SECTION_NOT_FOUND
+    from execution_binding import bound_entrypoint, validate_execution_binding
+    try:
+        selected = bound_entrypoint(app_root, "skills/cosmic-meta-modeling/scripts/data_model_emit.py")
+        if selected:
+            return subprocess.call([sys.executable, str(selected), *arguments])
+        validate_execution_binding(app_root)
+    except ValueError as error:
+        print(json.dumps({"status": False, "errorCode": str(error).split(":", 1)[0],
+                          "message": str(error), "writeAttempted": False}), file=sys.stderr)
+        return EXIT_EMIT_IO_FAILED
     ensure_app_runtime_ignore(app_root)
 
     authoring_path_override = Path(args.authoring_file).resolve()
@@ -5152,7 +5175,7 @@ def main(argv: list[str] | None = None) -> int:
     # filesystem read or model-authored command reconstruction.
     root = Path(__file__).resolve().parents[3]
     next_argv = [sys.executable, str(root / "skills" / "cosmic-meta-api" / "scripts" / "cosmic_api.py"),
-                 "runBatch", "--app-root", str(app_root), "--emit-manifest", str(output_dir / "_emit_manifest.json"), "--verify"]
+                 "--stdout", "runBatch", "--compact", "--app-root", str(app_root), "--emit-manifest", str(output_dir / "_emit_manifest.json"), "--verify"]
     print("NEXT_COMMAND=" + json.dumps(next_argv, ensure_ascii=False))
     print(f"EMIT_SUCCESS: {len(written)} artifact written to {output_dir}")
     return EXIT_SUCCESS

package/skills/cosmic-build/skills/cosmic-meta-modeling/scripts/report_validator.py

@@ -37,12 +37,15 @@ if str(API_SCRIPTS) not in sys.path:
 
 from _core.report_ops import (  # noqa: E402
     _PRESENTATION_BINDING_KEY,
+    _REPORT_FILTER_TYPE_ALIASES,
+    REPORT_FILTER_MULTI_VALUE_TYPES,
     normalize_report_columns_input,
     normalize_report_filters_input,
     normalize_report_plugin_input,
     normalize_report_properties_artifact,
     normalize_report_query_data_source_input,
     normalize_report_sorts_input,
+    compile_report_default_sorts,
 )
 
 
@@ -80,11 +83,13 @@ def _requests_unpersisted(filt, key):
 
 # Java fully-qualified class name pattern
 # e.g. kd.custom.report.SalesReportPlugin
+# The simple name admits no underscore because the plugin handoff resolves a registered class by
+# that exact shape (prepare_plugin_handoff CLASS_RE): a wider pattern here let an artifact pass
+# validation, register its class, and then fail Java delivery with PLUGIN_CLASS_NOT_QUALIFIED.
 JAVA_CLASS_PATTERN = re.compile(
-    r'^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*\.[A-Z][A-Za-z0-9_]*$'
+    r'^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*\.[A-Z][A-Za-z0-9]*$'
 )
 
-
 # ═══════════════════════════════════════════════════════════════════════════════
 # Data Structures
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -200,6 +205,7 @@ def validate_report_artifact(artifact):
             normalize_report_sorts_input(report_sorts)
         for item in report_plugins:
             normalize_report_plugin_input(item)
+        compile_report_default_sorts(artifact)
         if query_data_source:
             normalize_report_query_data_source_input(query_data_source)
         if artifact.get("reportBehavior"):
@@ -312,19 +318,25 @@ def validate_report_artifact(artifact):
                     path="reportProperties",
                 ))
 
-        # ── R-property-tree: left-tree properties need a template that has a left tree ──
-        # ReportTreeAp exists only on a tree-report template. The write is refused before it is
-        # sent, so the run fails rather than silently doing nothing — but saying so here saves
-        # the createPage.
+        # ── R-property-tree: a report this run creates has no left tree ──
+        # No public report template presets a ReportTreeAp — bos_grouprpttpl is the grouped
+        # report (a report group panel with its group list beside the report data panel), not a
+        # left tree. A left tree exists only after a user adds the report tree control to the
+        # report in the designer, so on the page this run creates the write is refused with
+        # REPORT_PROPERTY_ELEMENT_MISMATCH after createPage. Refusing here keeps the page from
+        # being created for a run that cannot finish.
         if isinstance(report_properties, dict) and report_properties.get("tree"):
-            warnings.append(Issue(
+            errors.append(Issue(
                 rule="R-property-tree",
-                severity="warning",
+                severity="error",
                 message=(
-                    "reportProperties.tree applies to ReportTreeAp, which only a left-tree "
-                    "report template carries. On a plain report the write is refused with "
-                    "REPORT_PROPERTY_ELEMENT_MISMATCH and the run fails; confirm the selected "
-                    "templateNumber builds a report with a left tree."
+                    "reportProperties.tree applies to ReportTreeAp, which no public report "
+                    "template carries (bos_grouprpttpl is the grouped report, not a left tree): "
+                    "a report exists with a left tree only after a user adds the report tree "
+                    "control in the designer. On the report this run creates the write is refused "
+                    "with REPORT_PROPERTY_ELEMENT_MISMATCH after createPage. Omit it here; once "
+                    "the report carries a ReportTreeAp, write it with setReportProperties "
+                    "--target tree."
                 ),
                 path="reportProperties.tree",
             ))
@@ -386,6 +398,36 @@ def validate_report_artifact(artifact):
     # setReportFilters says it once per write, the plugin contract carries each comparison under
     # filterEnforcement, and the module SKILL states it as a capability boundary.
 
+    # ── R-filter-type-compare: a typed editor whose arity disagrees with its comparison ──
+    # Both readings still run, so it warns: `in` on a single-select editor lets the user pick one
+    # value only, and `=` on a multi-select editor hands query() several values to compare.
+    # (between against a single-value editor is refused outright by the input contract.)
+    for i, filt in enumerate(report_filters):
+        editor = _REPORT_FILTER_TYPE_ALIASES.get(str(filt.get("fieldType") or "").strip().lower())
+        compare = str(filt.get("compare") or "").strip().lower()
+        if not editor or compare == "between":
+            continue
+        multi = editor in REPORT_FILTER_MULTI_VALUE_TYPES
+        if compare == "in" and not multi:
+            message = (
+                f"Filter '{filt.get('fieldPath', '?')}' compares with in but its {editor} editor "
+                "takes one value. Use MulBasedataField, MulComboField or CheckBoxGroupField when "
+                "the user should pick several."
+            )
+        elif compare == "=" and multi:
+            message = (
+                f"Filter '{filt.get('fieldPath', '?')}' compares with = but its {editor} editor "
+                "returns several values; query() has to apply them as in."
+            )
+        else:
+            continue
+        warnings.append(Issue(
+            rule="R-filter-type-compare",
+            severity="warning",
+            message=message,
+            path=f"reportFilters[{i}].fieldType",
+        ))
+
     # ── R-presentation-fetch: a declared presentation is a job for the plugin ──
     # presentation and the non-persisted filter properties are compiled into the plugin
     # contract, so declaring either without registering a plugin means the requirement has
@@ -401,7 +443,7 @@ def validate_report_artifact(artifact):
             message=(
                 "A column declares presentation (currency / measure unit / base data / "
                 "scale), which only the data-fetch plugin can bind, but the artifact "
-                "registers no reportPlugins. Register the plugin or drop the presentation."
+                "registers no reportPlugins. 注册所需插件并保留呈现要求，不能删除需求来通过校验。"
             ),
             path="reportPlugins",
         ))
@@ -435,10 +477,8 @@ def validate_report_artifact(artifact):
                     severity="error",
                     message=(
                         f"presentation.{key}='{bound}' is not the fieldKey of any declared "
-                        "report column. It names the column carrying that id, not a loose "
-                        f"DataSet column: declare it, normally as {{\"kind\": \"column\", "
-                        f"\"fieldKey\": \"{bound}\", \"dateIndex\": \"{bound}\", \"fieldType\": "
-                        "\"bigint\", \"hide\": true}, and have query() return it."
+                        "report column. 必须先确认平台引用字段和格式化前批量物化能力；"
+                        "补一列隐藏 bigint 只会得到 Long，不能修复 DynamicObject 精度引用。"
                     ),
                     path=f"{col_path}.presentation.{key}",
                 ))
@@ -457,33 +497,18 @@ def validate_report_artifact(artifact):
                     path=f"{col_path}.presentation.{key}",
                 ))
                 continue
-            # Both remaining checks are about the shape of a healthy target, not about whether
-            # the binding resolves, so they warn. The type one matters more than it looks: the
-            # target's declared fieldType is what the plugin contract turns into a Row accessor,
-            # so a text target tells the plugin to read the id with getString — which is how
-            # "operator does not exist: bigint = character varying" happened in the first place.
-            if not target.get("hide"):
-                warnings.append(Issue(
-                    rule="R-presentation-binding-target",
-                    severity="warning",
-                    message=(
-                        f"presentation.{key}='{bound}' binds a visible column, so the report "
-                        "shows the raw id next to the formatted value. Set hide: true on it "
-                        "unless the id is wanted as its own column."
-                    ),
-                    path=f"{col_path}.presentation.{key}",
-                ))
-            if str(target.get("fieldType") or "").strip().lower() != "bigint":
-                warnings.append(Issue(
-                    rule="R-presentation-binding-target",
-                    severity="warning",
-                    message=(
-                        f"presentation.{key}='{bound}' binds a column declared as "
-                        f"'{target.get('fieldType')}', but it carries a record id. Declare it "
-                        "bigint so the plugin contract asks for a Long."
-                    ),
-                    path=f"{col_path}.presentation.{key}",
-                ))
+            # 名称相同和隐藏都不能将标量升级成引用；当前列契约未开放已验证引用类型。
+            errors.append(Issue(
+                rule="R-presentation-binding-target",
+                severity="error",
+                message=(
+                    f"presentation.{key}='{bound}' 的目标 fieldType={target.get('fieldType')!r} "
+                    "尚无 DynamicObject 精度引用证据。隐藏 bigint 的 Long 主键及 getColumns() "
+                    "工厂不能改变既有 BigInt 属性；平台引用字段、迁移和批量物化验证前拒绝写入。"
+                    "保留动态精度要求，不能以固定精度或取消绑定代替完成。"
+                ),
+                path=f"{col_path}.presentation.{key}",
+            ))
 
     # ── R-plugin-class: Plugin className must follow Java fully-qualified naming ──
     for i, plugin in enumerate(report_plugins):
@@ -495,6 +520,36 @@ def validate_report_artifact(artifact):
                 message=f"Plugin className '{class_name}' does not match Java fully-qualified class name pattern (e.g. 'kd.custom.report.MyPlugin')",
                 path=f"reportPlugins[{i}].className",
             ))
+    # The left tree's own data plugin is a Java class name too, written as a string property.
+    _tree = (report_properties or {}).get("tree") if isinstance(report_properties, dict) else None
+    _tree_plugin = str(_tree.get("ReportPlugin") or "").strip() if isinstance(_tree, dict) else ""
+    if _tree_plugin and not JAVA_CLASS_PATTERN.match(_tree_plugin):
+        errors.append(Issue(
+            rule="R-plugin-class",
+            severity="error",
+            message=f"Left-tree plugin className '{_tree_plugin}' does not match Java fully-qualified class name pattern (e.g. 'kd.custom.report.MyTreePlugin')",
+            path="reportProperties.tree.ReportPlugin",
+        ))
+
+    # ── R-plugin-slot: reportPlugins is one slot, the report list's data-fetch plugin ──
+    # Every reportPlugins entry is written into ReportListAp.ReportQueryPlugin, which runs an
+    # AbstractReportListDataPlugin. Two entries there was the shape the left-tree example used to
+    # teach: the tree class registered as a second data plugin, where it builds no tree. The tree's
+    # own slot is ReportTreeAp.ReportPlugin, and a reportform plugin belongs to neither.
+    if len(report_plugins) > 1:
+        warnings.append(Issue(
+            rule="R-plugin-slot",
+            severity="warning",
+            message=(
+                f"reportPlugins registers {len(report_plugins)} classes into the report list's "
+                "data-fetch slot (ReportQueryPlugin), which takes one "
+                "AbstractReportListDataPlugin. A left-tree plugin (AbstractReportTreeDataPlugin) "
+                "belongs in ReportTreeAp.ReportPlugin, written by setReportProperties --target "
+                "tree once the report carries a report tree control, and a reportform plugin is "
+                "not a reportPlugins entry at all."
+            ),
+            path="reportPlugins",
+        ))
 
     # ── Build result ──
     valid = len(errors) == 0

package/skills/cosmic-build/skills/cosmic-meta-modeling/scripts/test_report_examples.py

@@ -1,13 +1,14 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
-"""Every report golden example must pass the validator the module tells callers to run.
+"""可执行示例必须通过校验，明确标记的历史精度反例必须被真实门禁拒绝。
 
 The examples are the shape a model copies before it has read the schema, so an example
 that the validator rejects guarantees a failed first attempt. Four examples shipped in a
 state that failed every rule they were meant to demonstrate (data-source sections after
 dataSources was removed, column fieldType outside the verified enum, and
 scale/format/currencyField/enableFuzzy/generateCode/reportBehavior keys that the input
-contracts reject). This test keeps documentation and contract in the same generation.
+contracts reject). 三个历史动态精度反例保留需求，但不得被当作可写黄金输入；
+本测试精确检查拒绝码和每个绑定错误，其余示例仍必须通过。
 
 Usage:
     python test_report_examples.py
@@ -61,18 +62,44 @@ class TestReportGoldenExamples(unittest.TestCase):
     def test_examples_exist(self):
         self.assertTrue(_example_files(), "no report golden example found")
 
-    def test_every_example_artifact_is_valid(self):
+    def test_executable_examples_pass_and_historical_precision_examples_are_refused(self):
+        refused = {
+            "golden-example-report-plugin.md": ["reportColumns[2].presentation.currencyField"],
+            "golden-example-report-batch.md": [
+                f"reportColumns[3].children[{index}].presentation.measureUnitField" for index in range(3)
+            ],
+            "golden-example-report-tree.md": [
+                f"reportColumns[1].children[{index}].presentation.currencyField" for index in range(3)
+            ],
+        }
         checked = 0
+        historical = set()
         for path in _example_files():
             for artifact in _report_artifacts(path):
                 checked += 1
                 result = validate_report_artifact(artifact)
+                if os.path.basename(path) in refused:
+                    # 仅允许这三个已明确标记的历史反例；每个绑定必须真实被拒绝。
+                    historical.add(os.path.basename(path))
+                    with open(path, encoding="utf-8") as handle:
+                        self.assertIn("REPORT_PRECISION_REFERENCE_UNVERIFIED", handle.read())
+                    self.assertFalse(result["valid"])
+                    self.assertEqual({row["rule"] for row in result["errors"]},
+                                     {"R-report-contract", "R-presentation-binding-target"})
+                    self.assertTrue(any("REPORT_PRECISION_REFERENCE_UNVERIFIED" in row["message"]
+                                        for row in result["errors"]))
+                    self.assertEqual(sorted(row["path"] for row in result["errors"]
+                                            if row["rule"] == "R-presentation-binding-target"),
+                                     refused[os.path.basename(path)])
+                    self.assertEqual(len(result["errors"]), 1 + len(refused[os.path.basename(path)]))
+                    continue
                 self.assertTrue(
                     result["valid"],
                     f"{os.path.basename(path)} fails report_validator: "
                     f"{json.dumps(result['errors'], ensure_ascii=False, indent=2)}",
                 )
-        self.assertGreater(checked, 0, "no report Artifact found in the examples")
+        self.assertGreaterEqual(checked, len(refused), "missing historical report Artifact")
+        self.assertEqual(historical, set(refused))
 
     def test_no_example_declares_data_sources(self):
         for path in _example_files():