@shundoo-ai/dsh-cosmic 1.0.21 → 1.0.22

package/skills/cosmic-build/skills/cosmic-meta-knowledge/domain-model/report-model.md

@@ -170,7 +170,7 @@ plugin query() → DataSet column name ← dateIndex ← ReportColumn
 | `enabled` | Enabled | 是否启用 |
 | `description` | Description | 描述文本 |
 | `displayname` | DisplayName | 显示名称 |
-| `type` | Type | 插件类型：`0` = Java，`3` = Script |
+| `type` | Type | 插件类型：`0` = Java，`1` = JS，`3` = KingScript |
 | `fpk` | FPK | 开发者门户注册 ID |
 | `bizappid` | BizAppId | 所属应用 |
 
@@ -182,12 +182,12 @@ plugin query() → DataSet column name ← dateIndex ← ReportColumn
 
 两层使用不同表示方式来标识插件类型：
 
-| 层 | Java 插件 | Script 插件 | KingScript 插件 |
+| 层 | Java 插件 | JS 插件 | KingScript 插件 |
 |-------|-------------|---------------|-------------------|
-| 平台元数据（设计器 entryentity，数值） | `type=0` | `type=3` | `type=3` |
+| 平台元数据（设计器 entryentity，数值） | `type=0` | `type=1` | `type=3` |
 | Artifact Schema / app-build 抽象层（字符串枚举） | `"Java"` | `"JS"` | `"KingScript"` |
 
-> 生成 Artifact JSON 时使用字符串枚举（`"Java"` / `"JS"` / `"KingScript"`）。`cosmic_api.py run` 流水线会将其转换为数值用于平台注册。
+> 生成 Artifact JSON 时使用字符串枚举（`"Java"` / `"JS"` / `"KingScript"`）。`cosmic_api.py run` 流水线会将其转换为数值用于平台注册。只有 Java 插件有 Java 源码需要交付，所以只有 Java 类会进入插件契约的 `pluginClasses` 和出卡门禁。
 
 ### 插件接口
 
@@ -213,18 +213,25 @@ public interface IReportListDataPlugin {
 ### 只有插件能提供的行为
 
 报表行为没有元数据通道 —— Artifact 不接受 `reportBehavior`，也不接受插件 `codeSpec`。每项能力都是
-取数插件上的一次方法覆写：
+某个插件上的一次方法覆写：数据行归取数插件，页面行为归 `reportform` 插件：
 
 | 需求 | 插件实现 |
 |-------------|----------------------|
-| 大数据量分批查询 | 覆写 `queryBatchBy(ReportQueryParam)`，再在 `query` 中读取 `queryParam.byBatchInfo().getCurrentBatchRows()` |
+| 大数据量分批查询 | 覆写 `queryBatchBy(ReportQueryParam)`，再在 `query` 中读取 `queryParam.byBatchInfo().getCurrentBatchRows()`；既不读它也不读 `selectedObj` 的分批 `query` 会每批都返回全部行，编译边界会拒绝它（`PLUGIN_SOURCE_BATCH_NOT_NARROWED`） |
 | 导出 | 覆写 `export(...)` / `exportWithSheet(...)` |
-| 左树右表导航 | 另一个 `reporttreelist` 插件，实现 `query(ReportQueryParam, String nodeId)` -> `List<TreeNode>`；行插件用收到的 `selectedObj` 收窄 |
-| 折叠式树形行 | `reportform`：`AbstractReportFormPlugin.setTreeReportList(TreeReportListEvent)` 里调 `setTreeReportList(true)` + `setTreeExpandColId(<列>)`，或在 `beforeQuery` 里调 `ReportQueryParam.setTreeReportList(true)` |
+| 左树右表导航 | 另一个 `reporttreelist` 插件，实现 `query(ReportQueryParam, String nodeId)` -> `List<TreeNode>`，在用户新增「报表树」控件后由 `setReportProperties --target tree` 声明为 `ReportTreeAp.ReportPlugin`（没有任何公共模板预置该控件，`bos_grouprpttpl` 也不例外）；行插件用收到的节点 id（`selectedObj`）收窄 |
+| 折叠式树形行 | `reportform`：`AbstractReportFormPlugin.setTreeReportList(TreeReportListEvent)` 里调 `setTreeReportList(true)` + `setTreeExpandColId(<列>)`，或在 `beforeQuery` 里调 `ReportQueryParam.setTreeReportList(true)`；行插件返回 `rowid` / `pid` / `isgroupnode` 列 |
+| 表头过滤与排序 | `reportform`：`setSortAndFilter` 按列开启；`query()` 必须应用 `getTableHeadFilterItems()`，否则表头过滤不起作用 |
+| 小计 / 合计行 | `query()` 把带 `sumlevel` 标记的合计行 union 进来；`reportform` 的 `packageData` 给它们打标签 |
+| 钻取联查 | `reportform`：`hyperLinkClick` 打开单据、列表或另一张报表，对方通过自定义参数拿到取值 |
 | 金额 / 数量 / 基础资料展现 | 在列上声明 `presentation`；编译出的插件契约会给出 `getColumns()` 里该用的确切 `ReportColumnFactory` 调用 |
 | 过滤条件的 `mustInput` / `defaultValue` | 在过滤条件上声明；编译出的插件契约会把它变成 `query()` 需从 `ReportQueryParam.getFilter()` 强制执行的要求 |
 | 必填或默认的过滤取值 | 从 `ReportQueryParam.getFilter()` 读取并强制执行 |
 
+两个插件的注册方式不同。取数插件声明在 `reportPlugins` 里，由报表流水线注册。`reportform` 插件在
+Java 交付后由 `register_plugins.py --verify` 注册到报表表单自己的插件列表（`targetType`
+`BILL_FORM`），并以 `location` `BILL_FORM` 回读。
+
 ---
 
 ## 六、术语对照表
@@ -245,8 +252,12 @@ public interface IReportListDataPlugin {
 | 分组列 | ReportColumnGroup | 多级表头分组 |
 | 取数插件 | IReportListDataPlugin | 取数插件接口 |
 | 分批查询 | queryBatchBy / IReportBatchQueryInfo | 分批查询机制，只在插件侧 |
-| 左树右表 | AbstractReportTreeDataPlugin | 左树导航，是第二个插件 |
+| 左树右表 | AbstractReportTreeDataPlugin | 左树导航，是注册在左树自己槽位上的第二个插件 |
 | 树形展开行 | isTreeReportList / setTreeExpandColId | 可折叠行，属于 `reportform` 职责 |
+| 树形行列 | rowid / pid / isgroupnode | 承载可折叠行层级的 DataSet 列 |
+| 表头过滤 | setSortAndFilter / getTableHeadFilterItems | 由 `reportform` 按列开启，由 `query()` 应用 |
+| 小计合计 | sumlevel | `query()` union 进来的合计行的标记列 |
+| 钻取联查 | hyperLinkClick / ReportShowParameter | 从超链接列打开单据、列表或另一张报表 |
 | 过滤条件 | FilterInfo | 运行时过滤容器 |
 | 过滤项 | FilterItemInfo | 单个过滤项 |
 | 查询参数 | ReportQueryParam | 查询参数封装 |

package/skills/cosmic-build/skills/cosmic-meta-knowledge/generation/report-modeling-guide.md

@@ -16,8 +16,8 @@
 没有这种绑定时，报表建模拆成两次交付，二者必须就一件事达成一致：
 
 ```
-metadata:  reportColumns / reportFilters / reportSorts / reportPlugins
-plugin:    query(ReportQueryParam, Object) -> DataSet
+metadata:  reportColumns / reportFilters / reportPlugins
+plugin:    query(ReportQueryParam, Object) -> DataSet; reportSorts -> defaultSorts (not metadata)
 agreement: DataSet column name == reportColumns[].dateIndex   (case-sensitive)
 ```
 
@@ -26,12 +26,15 @@ agreement: DataSet column name == reportColumns[].dateIndex   (case-sensitive)
 
 | 需求模式 | 插件实现 |
 |---|---|
-| 从单个实体查询字段 | `ORM.queryDataSet(algo, entityNumber, "a,b,c", filters, orderBy)` |
+| 从单个实体查询字段 | `QueryServiceHelper.queryDataSet(algo, entityNumber, "a,b,c", filters, orderBy)` —— DCS 禁止 `ORM` / `DB` 访问，见 `{ROOT_DIR}/references/dcs-code-rules.md` |
 | 跨实体关联（"关联/join"） | `DataSet.join(other).on(left, right).select(...).finish()` |
 | 多来源合并（"合并/union"） | `DataSet.union(other)` |
 | 汇总（"汇总/统计"） | `DataSet.groupBy(keys).sum(field)...finish()` |
-| 分组极值（"最早/最新/首单/末单"） | `DataSet.splitByGroup(keys)` + `topBy(1, {"f desc"})` + `union` —— 不要用 `groupBy().max()`，见 `{ROOT_DIR}/knowledge/cosmic/platform/sdk/sdk-algo.md` |
-| 去重计数（"笔数/去重计数"） | 先归约到每个被计数对象一行，`addField("1","one")`，再 `sum("one", alias)` |
+| 分组最早/最晚值（"最早/最新"） | `DataSet.groupBy(keys).min("f", alias)` / `.max("f", alias)` —— 即已验证的 `GroupbyDataSet` 聚合，见 `{ROOT_DIR}/knowledge/cosmic/platform/sdk/sdk-algo.md` |
+| 分组首单/末单整行（"首单/末单"，且要该单的其他字段） | `DataSet.splitByGroup(keys)` + `topBy(1, {"f desc"})` + `union` —— 仅在需要这些其他字段时使用，因为它会把每个分组物化并排序；只要最早/最晚值时用 `min` / `max` |
+| 去重计数（"笔数/去重计数"） | `DataSet.groupBy(keys).countDistinct(new String[]{"id"}, alias)`，见 `{ROOT_DIR}/knowledge/cosmic/platform/sdk/sdk-algo.md` |
+| 小计 / 合计行（"小计/合计"） | 每个合计层级一次 `groupBy`，用 `addField` 加一个 `sumlevel` 标记列（0 明细、1 小计、2 合计），合计行没有值的列用占位补齐，然后 `union`，再按维度列、`sumlevel` 的顺序 `orderBy`，合计行用它专属的排序键排在最后；把 `sumlevel` 声明为隐藏列，`packageData` 才能读到它 —— 见 `{ROOT_DIR}/knowledge/cosmic/platform/scenes/report/report-subtotal-total.md` |
+| 列不同的两个来源（"应收+应付"） | 两边各自 `select` 成同名、同序的列，缺少的列用 `"0 amount"` 这样的常量补齐，然后 `union`，再重新 `groupBy` —— 见 `{ROOT_DIR}/knowledge/cosmic/platform/scenes/report/report-dataset-assembly.md` |
 | 自定义排序 | `orderBy` 入参，或 `DataSet.orderBy(...)` |
 | 始终生效的固定过滤 | 追加到查询过滤列表的 `QFilter` |
 
@@ -98,17 +101,24 @@ DataSet 关联的类型由 DataSet 决定，所以设计器时代对关联键类
 
 左树导航：
 
+- 没有任何公共模板预置左树（`ReportTreeAp`）；`bos_grouprpttpl` 是分组报表（报表分组面板及其分组列表），
+  不是左树。只有用户在设计器里给报表新增「报表树」控件后报表才有左树，所以报表由 `bos_rpttpl`
+  不带树创建，控件在 `run` 之后再加
 - `reporttreelist` 实现 `query(ReportQueryParam, String nodeId)` 返回 `List<TreeNode>`；首次加载
   时 `nodeId` 为 null，这时要返回根节点列表
-- `TreeNode` 的 id 必须唯一；叶子节点要 `setIsParent(false)`
-- 配套的 `reportlist` 插件用拿到的 `selectedObj` 收窄数据行
+- 它在该控件存在之后由 `setReportProperties --target tree` 注册为 `ReportTreeAp.ReportPlugin`，
+  即左树自己的槽位，绝不作为第二个 `reportPlugins` 条目 —— 那个槽位是报表列表的取数插件
+- `TreeNode` 的 id 必须唯一，并在多次查询之间保持稳定；叶子节点使用 `setLeaf(true)`
+- 配套的 `reportlist` 插件用拿到的 `selectedObj`（被点击节点的 id）收窄数据行
 
 折叠式树形行：
 
 - `AbstractReportFormPlugin.setTreeReportList(TreeReportListEvent)` 里调
   `event.setTreeReportList(true)` 与 `event.setTreeExpandColId(<列 key>)`，或在 `beforeQuery` 里调
   `ReportQueryParam.setTreeReportList(true)`
-- 这件事没有任何关于 `id` / `pid` DataSet 列的文档约定，不要臆造
+- `reportlist` 插件以数据行返回层级，每行携带 `rowid`、`pid`（父行的 `rowid`，顶层行为
+  `"0"`）与 `isgroupnode`；不要用 `id` / `pid` 代替它们 —— 见
+  `{ROOT_DIR}/knowledge/cosmic/platform/scenes/report/report-tree-list.md`
 
 ---
 
@@ -134,11 +144,11 @@ DataSet 关联的类型由 DataSet 决定，所以设计器时代对关联键类
 | 计算值 | `formula` | — |
 | 图片 | `picture` | — |
 
-`currencyField` 与 `measureUnitField` 指向的是**另一个已声明列**的 `fieldKey`，不是游离的 DataSet
-列。请把那一列也声明出来 —— `fieldType: bigint`、`hide: true`，且 `fieldKey` 等于它自己的
-`dateIndex` —— 因为平台按列清单构建报表的运行期实体、并按 `fieldKey` 打包行数据，所以指向一个没有
-任何列拥有的名字什么都解析不到。这样一列可以服务任意多个格式化列，缺失时
-`R-presentation-binding` 会直接拒绝该 Artifact。
+上表 amount/qty/price 只保留业务需求形状，不是当前可写输入。动态 `currencyField` 与
+`measureUnitField` 要求格式化前的 DynamicObject 引用；`fieldType: bigint` 和 `hide: true`
+只得到 Long。`fieldKey` 与 `dateIndex` 相同也不证明物化。`R-presentation-binding` 检查名称，
+`REPORT_PRECISION_REFERENCE_UNVERIFIED` 在平台引用字段、旧标量迁移和批量物化验证前拒绝写入。
+原始/历史契约保留 `precisionSource`；不能删除需求或换成固定精度。
 
 不要写 `ReportColumn.setFieldType(ReportColumn.TYPE_AMOUNT)`：只有 `TYPE_BASEDATA` 有经验证的
 用例，而 `ReportColumnFactory.createAmountColumn` / `createQtyColumn` / `createPriceColumn` /
@@ -162,15 +172,22 @@ DataSet 关联的类型由 DataSet 决定，所以设计器时代对关联键类
 
 步骤 3: 定义过滤条件
   ├─ 识别用户输入条件（组织、日期范围、状态）
-  ├─ 选择 compare：=、in 或 between
-  └─ 把 mustInput / defaultValue 记为插件需求（元数据会丢弃）
+  ├─ 为每个过滤选择控件类（fieldType）及其参数，如 basedataNumber；
+  │  对照表见 {ROOT_DIR}/references/report-filter-contract.md
+  ├─ 选择 compare：=、in 或 between（in 配多选控件）
+  └─ 把 mustInput / defaultValue 记为插件需求（未装补丁的平台会丢弃）
 
 步骤 4: 定义默认排序
-  └─ fieldKey 必须引用已有报表列
+  ├─ fieldKey 引用叶子列；保留规则顺序与 dateIndex 映射
+  ├─ 创建前要求一个已启用的 Java 取数插件；禁止静默丢弃 reportSorts
+  └─ defaultSorts 是 Java 查询契约，不是 InitField 写入
 
 步骤 5: 注册取数插件
   ├─ className 全限定；其包名成为运行时契约
-  └─ 插件类型：reportlist，树形报表用 reporttreelist
+  ├─ reportPlugins 只放 reportlist 取数插件，一个条目
+  ├─ 左树的 reporttreelist 插件不在 Artifact 里：用户新增「报表树」控件后，
+  │  再把它写为 ReportTreeAp.ReportPlugin
+  └─ reportform 插件（页面行为）永远不是 reportPlugins 条目
 
 步骤 6: 组装 Artifact
   └─ entities、reportColumns、reportFilters、reportSorts、reportPlugins
@@ -196,10 +213,12 @@ DataSet 关联的类型由 DataSet 决定，所以设计器时代对关联键类
 | R-presentation-binding | error | `presentation.currencyField` / `measureUnitField` 必须是某个已声明列的 `fieldKey`，且该列的 `fieldKey` 必须等于 `dateIndex` |
 | R-property-target | error | `reportProperties` 中 `columns` 之外的每个成员都必须是已知目标，且只能携带该目标可写的属性 |
 | R-property-column | error | `reportProperties.columns` 的每个键都必须是已声明的列或分组 `fieldKey`，且属性必须是其宿主能解析的那些 |
+| R-property-tree | error | `reportProperties.tree` 会被拒绝：没有任何公共模板带 `ReportTreeAp`（`bos_grouprpttpl` 是分组报表），本次 run 创建的报表没有左树；用户新增「报表树」控件后，用 `setReportProperties --target tree` 写入 |
 | R-fetch-source | warning | 既没有 `reportPlugins` 也没有 `queryDataSource` 的报表查不出任何数据行 |
-| R-property-tree | warning | `reportProperties.tree` 需要模板带 `ReportTreeAp`；普通报表上该写入会被拒绝 |
-| R-filter-unpersisted | warning | `mustInput` / `visible: false` / `defaultValue` 不落地；已编译进插件契约 |
-| R-presentation-binding-target | warning | 被绑定的币别 / 单位列可见，或它承载的是记录 id 却没声明为 `bigint` |
+| R-plugin-slot | warning | `reportPlugins` 声明了不止一个插件；它是报表列表唯一的取数槽位，左树插件应放在 `ReportTreeAp.ReportPlugin` |
+| R-filter-unpersisted | warning | 未安装类型化过滤补丁的平台不落地 `mustInput` / `visible: false` / `defaultValue`；已编译进插件契约 |
+| R-filter-type-compare | warning | 单值 `fieldType` 却用 `in` 比较，或多选控件却用 `=` 比较，使 `query()` 与用户能选的值不一致 |
+| R-presentation-binding-target | error | 包括隐藏 `bigint` 在内的币别 / 单位标量目标，没有 DynamicObject 引用证据；开放写入前须验证平台迁移与批量物化 |
 
 ---
 
@@ -213,18 +232,22 @@ DataSet 关联的类型由 DataSet 决定，所以设计器时代对关联键类
 {
   "entities": [{ "type": "ReportEntity", "bizName": "so_query_rpt", "displayName": "销售订单查询", "formNumber": "kdtest_so_query_rpt" }],
   "reportColumns": [{ "kind": "column", "fieldKey": "billno", "dateIndex": "billno", "fieldType": "text", "caption": "单据编号" }],
-  "reportFilters": [{ "fieldPath": "bizdate", "displayName": "业务日期", "compare": "between" }],
+  "reportFilters": [
+    { "fieldPath": "flt_org", "displayName": "组织", "fieldType": "OrgField", "compare": "=" },
+    { "fieldPath": "bizdate", "displayName": "业务日期", "compare": "between" }
+  ],
   "reportPlugins": [{ "className": "kd.kdtest.report.SoQueryReportPlugin", "type": "Java" }]
 }
 ```
-插件：`ORM.queryDataSet(algo, "sm_saleorder", "billno,...", filters, orderBy)`。
+插件：`QueryServiceHelper.queryDataSet(algo, "sm_saleorder", "billno,...", filters, orderBy)`。
 
 **场景 2：多实体关联**
 触发："关联物料主数据和仓库库存"
 Artifact：只有报表列。插件：
 ```java
-DataSet material = orm.queryDataSet(algo, "bd_material", "id as mat_id,number as mat_code", null, null);
-DataSet stock = orm.queryDataSet(algo, "im_inventory", "material as mat_id2,qty as inv_qty", filters, null);
+QFilter[] enabled = {new QFilter("enable", QCP.equals, "1")};
+DataSet material = QueryServiceHelper.queryDataSet(algo, "bd_material", "id as mat_id,number as mat_code", enabled, null);
+DataSet stock = QueryServiceHelper.queryDataSet(algo, "im_inventory", "material as mat_id2,qty as inv_qty", filters, null);
 return material.join(stock).on("mat_id", "mat_id2").select("mat_code", "inv_qty").finish();
 ```
 
@@ -256,6 +279,13 @@ Artifact：只有报表列。插件：覆写 `queryBatchBy()` 返回分批键，
 - [ ] 金额 / 数量 / 基础资料列都声明了 `presentation` 对象
 - [ ] 每个 `currencyField` / `measureUnitField` 绑定都有各自已声明的隐藏列
 - [ ] `mustInput` / `defaultValue` 已声明，由契约带给插件
-- [ ] 排序 `fieldKey` 引用已有报表列
+- [ ] 每个选择型或下拉型过滤都声明了 `fieldType` 及该类型的必填参数
+- [ ] 排序 `fieldKey` 引用叶子列，保留规则顺序与 `dateIndex` 映射
+- [ ] `reportSorts` 要求一个已启用的 Java 取数插件；`setReportSorts` 保持阻断
+- [ ] `query()` 消费 `defaultSorts` 和 `defaultSortPolicy`：交互排序优先，仅无交互排序时应用默认值，
+      在最终 DataSet 组装后、分页/导出前执行，保留权限并分别测试两种行为，不从元数据宣称运行通过
 - [ ] 插件 className 全限定，注册后保持稳定
+- [ ] `reportPlugins` 只放一个取数插件；左树插件是 `ReportTreeAp.ReportPlugin`，在新增报表树控件后写入，
+      绝不是 Artifact 里的 `reportProperties.tree`
+- [ ] 开启了表头过滤的，`query()` 里按 `getTableHeadFilterItems()` 应用表头过滤条件
 - [ ] 插件 DataSet 的列名逐字（含大小写）匹配每个 `dateIndex`

package/skills/cosmic-build/skills/cosmic-meta-knowledge/property-guides/report-column-properties.md

@@ -158,49 +158,25 @@
 
 插件契约给出的一律是 `ReportColumnFactory` 那一组，因为它们接受标题，而且每种展现 kind 都对应一个
 签名。`ReportColumn` 上那三个静态方法是不带标题的简写；`createCurrencyColumn` 只存在于那里，也正是
-运行期构造币别列的办法 —— 元数据没有 `currency` 这种字段类型。
+运行期构造币别列描述符的办法 —— 元数据没有 `currency` 这种字段类型。这不能迁移已有 BigInt 属性或物化运行行引用。
 
 ---
 
 ## 5. 币别与计量单位绑定
 
-`presentation.currencyField` 与 `presentation.measureUnitField` 指向的是**另一个已声明报表列的
-`fieldKey`** —— 那个承载币别或单位 id 的隐藏列。把它声明出来：
+`presentation.currencyField` 和 `presentation.measureUnitField` 保留动态引用需求，当前在元数据
+写入前以 `REPORT_PRECISION_REFERENCE_UNVERIFIED` 阻断。不能声明隐藏 `bigint` 并将 Long 当作
+引用：`NumberFormatProvider` 读取 DynamicObject，`ReportPropUtil.registerMissingProperty`
+复用已有标量属性。`hide` 或在 `getColumns()` 替换描述符都不会改变该属性。
 
-```json
-{ "kind": "column", "fieldKey": "currency_id", "dateIndex": "currency_id",
-  "fieldType": "bigint", "caption": "币别", "hide": true }
-```
-
-有三条证据说明被绑定的名字是列 key、而不是游离的 DataSet 列：
-`ReportColumn.setCurrencyField(String)` 把它的参数记作 *currency field identifier*（币别字段标识）；
-`ReportPropUtil.createReportType(DynamicObjectType, List<ReportColumn>)` 是按列清单构建运行期实体的，
-所以一个不在任何列之下抵达的值没有属性可以挂靠；而 `report-model.md` §3.2 记录 `fieldKey` 是前端数据
-索引，也就是说行数据到客户端时是以 `fieldKey` 为键的，从不以 `dateIndex` 为键。
-
-`R-presentation-binding` 强制两件事，而第二件正是这件事不必先做实测的原因：
-
-- 被绑定的名字是某个已声明列的 `fieldKey`；
-- 该列保持 `fieldKey` == `dateIndex`。两者相等时，无论平台把 `currencyField` 读作列 key 还是读作
-  DataSet 列名，这份 Artifact 都成立，两种读法不可能产出不同的元数据。等到这个绑定在真实部署上被
-  实测过，第二条可以放宽 —— 其余一切不变。
+`R-presentation-binding` 检查目标的 `fieldKey` 和 `dateIndex`；名称相同不是运行证据。
+当前开放的所有标量目标触发 `R-presentation-binding-target` 错误。`dataSetColumnTypes`
+描述 DataSet 值，不是格式化器引用。原始/历史契约用 `bindsTo` 与 `requiredBy` 保留依赖；
+`precisionSource` 将 `requiredRuntimeValueType` 标记为 DynamicObject、`runtimeVerified` 为 false、
+`rawIdIsReference` 为 false、`metadataWriteBlocked` 为 true。
 
-两个值得直说的推论：
-
-- `query()` 必须像返回任何其他列一样返回它。它在 `dataSetColumnTypes` 里被定型为 `Long`，因为承载的是
-  被引用记录的 id；它的类型条目会把每个格式化列列在 `requiredBy` 下。把它当 String 读出再放进
-  `QFilter`，会在数据库层报 `操作符不存在: bigint = character varying`。
-- 一个隐藏列可以服务任意多个共用同一币别或单位的格式化列。
-
-声明出来的这一列是 `bigint`，不是币别类型的属性，因为 `fieldType` 没有 `currency`、列级 `entityId`
-又被拒绝。如果渲染结果没有币别符号，请在 `getColumns()` 里升级这个已存在的列，而不是新增一列：
-
-```java
-ReportColumn currency = ReportColumn.createCurrencyColumn("currency_id");
-currency.setDateIndex("currency_id");
-currency.setHide(true);
-nodes.set(index, currency);
-```
+开放契约前须验证单位/币别持久化引用属性、旧标量字段和依赖控件的事务迁移、格式化前批量引用物化，
+以及混合精度、分组、合计、分页和导出。禁止猜转换 API、只包装 id、逐行补查、取消绑定或固定精度降级。
 
 ---
 
@@ -233,15 +209,15 @@ amountColumn.setStyle(negative);
 
 | 错误 | 后果 | 修正 |
 |---|---|---|
-| Artifact 里写 `fieldType: "amount"` | 被拒绝：不属于已验证的十种类型 | `decimal` 加上 `presentation.kind = "amount"` |
-| 列上写 `currencyField` / `scale` / `style` | 在输入归一化阶段被拒绝 | 移进 `presentation`，或在 `getColumns()` 里设置 |
+| Artifact 里写 `fieldType: "amount"` | 被拒绝：不属于已验证的十种类型 | 保留金额需求；引用能力验证前，`decimal` 加 `presentation.kind = "amount"` 也会被阻断 |
+| 列上写 `currencyField` / `scale` / `style` | 在输入归一化阶段被拒绝 | 支持的要求使用 `presentation`；`getColumns()` 不是未验证动态引用的旁路 |
 | Artifact 里写 `isHide` / `isFreeze` | 被拒绝：那是 Java getter 的名字 | 用 `hide` / `freeze` |
 | `dateIndex` 匹配不到任何 DataSet 列 | 列渲染成空，任何环节都不报错 | 列与 `query()` 必须一起改；元数据无法校验这一点 |
 | `dateIndex` 与 DataSet 列大小写不一致 | 同样是静默的空列 | 匹配是精确且大小写敏感的 |
 | `date` 列按文本返回 | `setvalue fail, name: <column>, Unparseable date` | 返回 `java.util.Date`；访问器取自 `dataSetColumnTypes` |
 | 在 `getColumns()` 里重建列却不调 `setDateIndex` | `fieldKey` 与 `dateIndex` 不同时列渲染成空 | 契约给出的每个 `javaFollowUp` 都要执行 |
 | `getColumns()` 用扁平循环强转 `ReportColumn` | 第一个分组就抛 `ClassCastException`，且分组内列永远命中不到 | 递归进 `ReportColumnGroup.getChildren()` |
-| `presentation.currencyField` 指向的名字不是任何已声明列 | `R-presentation-binding` 拒绝该 Artifact | 声明承载该 id 的隐藏 `bigint` 列 |
+| `presentation.currencyField` 指向的名字不是任何已声明列 | `R-presentation-binding` 拒绝该 Artifact | 验证平台引用字段及批量物化；隐藏 `bigint` 不能修复引用 |
 | 绑定目标列的 `fieldKey` 与 `dateIndex` 不一致 | 同样被拒绝 | 绑定目标上保持两者相等 |
 | 过滤 key 等于某个列的 `fieldKey` | 写入前即被拒绝；设计器会因标识重复而拒绝保存 | 使用独立的 key，例如 `flt_<column>` |
 | 为了加宽一列而重建报表 | 为一次展现调整丢掉表单 id、菜单绑定和权限 | `setReportProperties --target column --element <key> --input '{"Width": "200px"}'` |

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

@@ -46,7 +46,7 @@ appMapping.tsv、目录内容、archive、最近使用记录或本地仅有一
 | 公共模板 | `queryPublicTemplates` |
 | 已验证应用的模板 | `queryBizTemplates` |
 | 合并列表 | `getTemplateList` |
-| 准确模板预置字段 | `getEntityFields` |
+| 准确模板预置字段 | `getEntityFields --formNumber <模板编码>`（不支持 `--compact`） |
 
 `MENU_MANAGE` 必须有明确的应用菜单请求；表单创建不会隐式进入本分支。只读取一次
 `{ROOT_DIR}/skills/cosmic-meta-modeling/modules/app-menu/SKILL.md`。紧接新建表单时复用已验证
@@ -55,7 +55,9 @@ appMapping.tsv、目录内容、archive、最近使用记录或本地仅有一
 ## ENTITY_CREATE
 
 用户未指定单据/基础资料模板时，省略 `templateKey`，由 emitter 补齐标准模板。
-列表中的 `blankPage` 是虚拟空白选项，不能用它修复模板查询失败。
+用户明确要求单据不继承任何模板时，将 `templateKey` 设为 `blankPage`，并在实时
+BillFormModel 模板清单中验证。空白单据没有预置字段，应按要求建模全部字段。
+不得用 `blankPage` 代替失败的模板查询。
 
 用于一个依赖完整的 Bill/Base 请求。本地引用需要同批创建时，可一次 author 多个根实体与分录。
 
@@ -112,12 +114,12 @@ appMapping.tsv、目录内容、archive、最近使用记录或本地仅有一
 按已声明映射补齐平台引用；显式 reference 保持原样并校验。通用 `BasedataField`/`MulBasedataField` 必须声明目标，使用顶层
 `prdRef` 或结构化引用，禁止从泛化名称推断。
 
-只询问影响正确结果且尚未解决的业务选择，例如引用目标歧义，或用户未委托的必需候选值。
-已委托的设计在请求范围内自行决定并记录假设；委托不允许虚构平台身份。
-未请求的可选默认值与提示信息省略。选择字段使用专题中完整的 `comboOptions` 契约，
-该已发布 authoring 形状无需额外读取实时 Schema。
+写入受影响字段前，先与用户解决涉及字段数量、关联关系或存储值的未决业务选择，包括引用目标歧义和
+用户未委托的必需候选值；独立的已确认工作可继续。委托范围内自行决定并记录假设，
+但委托不允许虚构平台身份，发现平台类型也不能代替待决业务决定。省略未请求的可选默认值与提示。
+选择字段使用专题中完整的 `comboOptions` 契约，不额外读取实时 Schema。
 
-已从发布契约确定所需 `FieldDataType` 及伴随参数时，不再执行字段类型目录。
+已从发布契约确定所需 `FieldDataType` 及伴随参数时，跳过字段类型目录。
 布尔复选框的 authoring 类型是 `CheckBoxField`；`CheckBox` 只是界面简称，
 不能作为元数据 `dataType`。
 类型或伴随参数未知时查询目录：
@@ -126,7 +128,7 @@ appMapping.tsv、目录内容、archive、最近使用记录或本地仅有一
 {python} {ROOT_DIR}/skills/cosmic-meta-modeling/scripts/field_type_registry.py --catalog --compact
 ```
 
-已选类型用 `--catalog --types <准确类型> ...` 返回完整约束。模型做语义选择；命令不按关键词替换类型。
+需要补充已选类型的约束时，用 `--catalog --types <准确类型> ...`，不读取完整目录。模型做语义选择；命令不按关键词替换类型。
 
 ### 编译与执行
 
@@ -139,6 +141,9 @@ appMapping.tsv、目录内容、archive、最近使用记录或本地仅有一
 只有用户明确给出根表单编码且 authoring 仅含一个根实体时才传 `--root-form-number`，模型生成的
 `bizName` 不使用该参数。多个用户给定编码的根实体应一起 author，各自写入 `logicalName` 并
 省略该参数；一个 manifest 和一次 `runBatch` 会处理全部根实体。
+
+`runBatch` 负责创建前的线上目标冲突检查；不要在外层重复查询模板或字段来证明目标不存在。冲突阻断对应目标的创建，不接管、覆盖或删除已有表单；未知写入状态仍按恢复契约对账。
+
 明确功能分组必须在初始 batch 完成，不得之后用 `moveForm` 修补。首次 `runBatch` 前，
 按需求中的准确名称通过[功能分组入口](../cosmic-meta-modifier/modules/unit/SKILL.md)解析；
 不存在且已授权创建时，使用准确名称/编码及已绑定 `appRoot` 调用 `addUnit`。省略 `--seq`
@@ -148,7 +153,7 @@ appMapping.tsv、目录内容、archive、最近使用记录或本地仅有一
 直接执行 stdout 返回的 `NEXT_COMMAND` argv；旧版 emitter 才按 `manifest:` 路径组装批次：
 
 ```text
-{python} {ROOT_DIR}/skills/cosmic-meta-api/scripts/cosmic_api.py runBatch --app-root "{appRoot}" --app-code "{appCode}" --emit-manifest "{manifestPath}" --verify
+{python} {ROOT_DIR}/skills/cosmic-meta-api/scripts/cosmic_api.py --stdout runBatch --compact --app-root "{appRoot}" --app-code "{appCode}" --emit-manifest "{manifestPath}" --verify
 ```
 
 保留返回的结果文件供 Java 准备使用，其中包含 `resultPath`、完整 `artifactPaths` 和原始验证回执；
@@ -178,7 +183,7 @@ app-build；默认值、长度、精度、小数位、显隐和其他属性都
 
 | 类型 | `skills/cosmic-meta-modeling/modules/` 下模块 |
 |---|---|
-| 动态/空白 | `formtemplate/SKILL.md` |
+| 动态/空白 | `formtemplate/SKILL.md`（`DynamicFormModel` 字段用路径 A） |
 | 报表 | `report/SKILL.md` |
 | 参数 | `parameter/SKILL.md` |
 | 卡片 | `widget/SKILL.md` |
@@ -189,16 +194,13 @@ app-build；默认值、长度、精度、小数位、显隐和其他属性都
 | 布局/打印 | `layout/SKILL.md` |
 | 移动 | `mobile/SKILL.md` |
 
-使用模块声明的 model type 与 CLI。Bill/Base 字段留在 `ENTITY_CREATE`；明确的
-`DynamicFormModel` 字段使用 formtemplate 路径 A。
+使用所选模块声明的 model type 与 CLI。
 
 ## 元数据完成边界
 
-创建只是第一次元数据写入。Java 前必须完成全部明确且元数据可表达的事项：结构、引用/带出、
-UI、属性/默认值、规则/操作和列表配置。剩余事项把已验证表单身份交给所属 modifier/UI 命令；
-不得把元数据事项改称插件工作。
-
-还有明确的元数据、Java 或菜单工作时，继续完成后再交付卡片。
+Java 前完成全部明确且元数据可表达的事项：结构、引用/带出、UI、属性/默认值、规则/操作和列表。
+把已验证表单身份交给所属 modifier/UI 命令；不得把元数据事项改称插件工作。
+剩余明确要求的 Java 和菜单工作完成后再交付卡片。
 
 只有写后状态未知时才执行 CLI 给出的单次对账命令，确认不存在后才重试。
 `ENTITY_CREATE` 不隐含菜单请求。