@lovrabet/rabetbase-cli 2.3.16-beta.7 → 2.4.1

package/skills/rabetbase/knowledge/page-schema/YtPage.md

@@ -0,0 +1,172 @@
+---
+name: YtPage
+description: YtPage 页面布局组件完整配置
+tags: [page, layout, page-schema]
+---
+
+# YtPage
+
+页面容器组件，支持磁贴布局和流式布局两种模式。
+
+---
+
+## 布局类型
+
+| 类型 | 判断条件 | 特点 | 场景 |
+|------|----------|------|------|
+| 磁贴布局 | 包含 `YtRglContainer` | 网格定位、支持并排 | 仪表盘、数据看板 |
+| 流式布局 | 无 `YtRglContainer` | 上下排列 | 表单页、详情页 |
+
+---
+
+## 磁贴布局（YtRglContainer）
+
+### 结构
+
+```json
+{
+  "componentName": "YtPage",
+  "children": [{
+    "componentName": "YtRglContainer",
+    "props": {
+      "RGLlayout": [
+        {"i": "node_filter", "w": 12, "h": 10, "x": 0, "y": 0, "autoHeight": true},
+        {"i": "node_table", "w": 12, "h": 30, "x": 0, "y": 10, "autoHeight": false}
+      ]
+    },
+    "children": [...]
+  }]
+}
+```
+
+### RGLlayout 参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| i | string | 组件 ID（对应 children 中的 id） |
+| w | number | 宽度（总列数 12） |
+| h | number | 高度（单位行数） |
+| x | number | X 起始位置（0-11） |
+| y | number | Y 起始位置 |
+| autoHeight | boolean | 自动高度（true 时 h 无效） |
+
+### 布局规则
+
+| 规则 | 说明 |
+|------|------|
+| 每行总宽度 | 必须为 12 |
+| Filter/Table | 必须独占一行（w: 12） |
+| 图表并排 | 两个图表各占 w: 6 |
+
+---
+
+## 流式布局
+
+### 结构
+
+```json
+{
+  "componentName": "YtPage",
+  "children": [
+    {"componentName": "LrSmartFilter"},
+    {"componentName": "LrSmartTable"}
+  ]
+}
+```
+
+### 布局规则
+
+- Filter 必须在 Table 前
+- 组件按 children 数组顺序排列
+
+---
+
+## 常见布局场景
+
+### 并排图表
+
+```json
+{
+  "RGLlayout": [
+    {"i": "chart1", "w": 6, "h": 20, "x": 0, "y": 0},
+    {"i": "chart2", "w": 6, "h": 20, "x": 6, "y": 0}
+  ]
+}
+```
+
+### 统计卡 + 图表
+
+```json
+{
+  "RGLlayout": [
+    {"i": "stat1", "w": 3, "h": 10, "x": 0, "y": 0},
+    {"i": "stat2", "w": 3, "h": 10, "x": 3, "y": 0},
+    {"i": "stat3", "w": 3, "h": 10, "x": 6, "y": 0},
+    {"i": "stat4", "w": 3, "h": 10, "x": 9, "y": 0},
+    {"i": "chart1", "w": 12, "h": 20, "x": 0, "y": 10}
+  ]
+}
+```
+
+### Filter + Table
+
+```json
+{
+  "RGLlayout": [
+    {"i": "filter", "w": 12, "h": 10, "x": 0, "y": 0, "autoHeight": true},
+    {"i": "table", "w": 12, "h": 30, "x": 0, "y": 10}
+  ]
+}
+```
+
+---
+
+## 禁止事项
+
+| 禁止 | 说明 |
+|------|------|
+| 添加/删除组件 | 只能调整布局 |
+| 更改组件类型 | 只能调整位置 |
+| 每行宽度不为 12 | 磁贴布局必须填满 12 列 |
+
+---
+
+## 常见问题
+
+| 问题 | 原因 | 解决方案 |
+|------|------|----------|
+| 布局空白 | 宽度不为 12 | 确保每行 w 总和为 12 |
+| 高度不一致 | autoHeight 设置错误 | 统一设置 autoHeight |
+| 组件重叠 | x/y 坐标冲突 | 检查坐标是否正确 |
+| Filter 不生效 | 在 Table 后 | 将 Filter 移到 Table 前 |
+
+---
+
+## 完整示例
+
+```json
+{
+  "componentName": "YtPage",
+  "children": [{
+    "componentName": "YtRglContainer",
+    "props": {
+      "RGLlayout": [
+        {"i": "node_stat1", "w": 3, "h": 8, "x": 0, "y": 0},
+        {"i": "node_stat2", "w": 3, "h": 8, "x": 3, "y": 0},
+        {"i": "node_stat3", "w": 3, "h": 8, "x": 6, "y": 0},
+        {"i": "node_stat4", "w": 3, "h": 8, "x": 9, "y": 0},
+        {"i": "node_filter", "w": 12, "h": 10, "x": 0, "y": 8, "autoHeight": true},
+        {"i": "node_table", "w": 12, "h": 30, "x": 0, "y": 18}
+      ]
+    },
+    "children": [
+      {"id": "node_stat1", "componentName": "LrSmartStatistic"},
+      {"id": "node_stat2", "componentName": "LrSmartStatistic"},
+      {"id": "node_stat3", "componentName": "LrSmartStatistic"},
+      {"id": "node_stat4", "componentName": "LrSmartStatistic"},
+      {"id": "node_filter", "componentName": "LrSmartFilter"},
+      {"id": "node_table", "componentName": "LrSmartTable"}
+    ]
+  }]
+}
+```

package/skills/rabetbase/knowledge/page-schema/dataset-relations.md

@@ -0,0 +1,126 @@
+---
+name: dataset-relations
+description: 数据集关系模型参考，包含关系方向、字段语义、关系基数、主子表语义与页面配置边界
+tags: [page-schema, dataset, relation]
+---
+
+# 数据集关系声明
+
+数据集关系是数据模型元数据，用于描述两个数据集的字段如何关联。它不是某个页面组件的专属配置，也不等同于数据库外键：关系既可以表示物理表之间的引用，也可以表示字典选项源、METADATA 自关联或主子表业务归属。
+
+页面中的 `relation.field`、关联字段展示和筛选，都依赖已定义且有效的数据集关系。
+
+## 关系事实字段
+
+服务端返回的关系事实嵌入在来源数据集的 `relations` 中。下面保留服务端原始字段名；来源数据集本身由外层数据集对象确定，因此关系对象内不重复提供 `fromDatasetCode`。
+
+数据集 `relations` 中的普通关联关系示例：
+
+```json
+{
+  "relationId": 9074,
+  "fromField": "create_by",
+  "toDatasetCode": "d7c1ad8525ce4823bf5f7e4f4edab30b",
+  "toDatasetId": 48426,
+  "toDatasetName": "员工",
+  "toField": "id",
+  "toFieldLabel": "user_name",
+  "toTableName": "crm_user",
+  "sourceType": "DB_TABLE",
+  "joinType": "MANY_TO_ONE",
+  "cardinality": "MANY_TO_ONE",
+  "bizRelationType": null,
+  "mainColumnName": null,
+  "subColumnName": null,
+  "subDatasetCode": null,
+  "subTableName": null
+}
+```
+
+示例将 `joinType` 和 `cardinality` 并列展示，便于说明字段对应关系；实际接口会按各自定义使用其中一个字段名，两者表示的关系基数必须一致。
+
+| 字段 | 含义 |
+|------|------|
+| `relationId` | 关系记录标识 |
+| `fromField` | 当前数据集中的关联字段 |
+| `sourceType` | 主表的数据源类型：`DB_TABLE` 表示数据库类型，`METADATA` 表示文生类型 |
+| `toDatasetCode` / `toDatasetId` / `toDatasetName` | 目标数据集的编码、标识和名称 |
+| `toField` | 目标数据集中的关联字段 |
+| `toFieldLabel` | 目标数据集的展示字段名，例如 `user_name`；不是中文标题 |
+| `toTableName` | 目标物理表名称；非物理表数据集时可为空 |
+| `joinType` | 关系对象中的关系基数字段，可选 `ONE_TO_ONE`、`ONE_TO_MANY`、`MANY_TO_ONE`、`MANY_TO_MANY` |
+| `cardinality` | 关系接口中的关系基数字段，与 `er-config` 中的 `joinType` 表示同一个内容；只是接口字段名不同，取值范围完全一致 |
+| `bizRelationType` | 业务关系类型；普通关联为 `null`，主子表为 `main_sub` |
+| `mainColumnName` / `subColumnName` | 主子表关联时使用的主表列和子表列 |
+| `subDatasetCode` / `subTableName` | 主子表关联时使用的子表数据集编码和子表名称 |
+
+一条关系从当前数据集的 `fromField` 指向 `toDatasetCode.toField`。目标数据集名称、物理表名和展示字段是关系的补充信息，不能代替数据集编码和真实字段名判断关系。
+
+## 关系方向
+
+关系方向始终从当前数据集指向目标数据集。方向决定字段含义、关系基数的观察视角，以及页面从哪个字段加载目标数据。
+
+| From | To | 是否支持 | 常见语义 |
+|------|----|:---:|----------|
+| `DB_TABLE` | `DB_TABLE` | 是 | 物理表数据集之间的引用或主子关系 |
+| `DB_TABLE` | `METADATA` | 是 | 业务字段消费 METADATA 字典或选项源 |
+| `METADATA` | `METADATA` | 是 | 配置数据集关系或自关联父子关系 |
+| `METADATA` | `DB_TABLE` | 否 | 当前关系模型不支持该方向 |
+
+当当前数据集编码与 `toDatasetCode` 相同时，该关系是自关联。自关联仍需明确 `fromField`、`toField` 和基数，不能仅凭数据集编码相同推断父子语义。
+
+## 关系基数
+
+服务端不同接口对同一关系基数使用了不同的字段表达：`er-config` 关系对象使用 `joinType`，其他关系接口使用 `cardinality`。两者本质上是同一个属性，不是两项需要分别维护的数据。CLI 调用的是使用 `cardinality` 的关系接口，因此对应的参数名为 `cardinality`（命令行参数为 `--cardinality`）。
+
+关系基数以当前数据集记录到目标数据集记录的方向解释：
+
+| 值 | 含义 |
+|----|------|
+| `ONE_TO_ONE` | 一条来源记录对应一条目标记录 |
+| `ONE_TO_MANY` | 一条来源记录对应多条目标记录 |
+| `MANY_TO_ONE` | 多条来源记录可以指向同一条目标记录 |
+| `MANY_TO_MANY` | 来源与目标两端都可以关联多条记录 |
+
+基数必须与真实数据约束一致。不能因为字段名看起来像外键，就直接判断为 `MANY_TO_ONE`；也不能因为页面要展示列表，就把普通引用关系改成 `ONE_TO_MANY`。
+
+## 普通关系与主子表
+
+普通关系表示两个相对独立的数据集之间存在引用，例如订单引用客户、项目引用负责人。主子表则表示明确的业务归属：一条主记录拥有一组随其维护的明细记录，例如订单与订单明细、合同与付款计划。
+
+| 业务关系 | `joinType` | `bizRelationType` |
+|----------|------------|-------------------|
+| 普通引用 | 按真实基数设置 | `null` |
+| 主子表 | `ONE_TO_MANY` | `main_sub` |
+
+判断是否属于主子表时，应同时确认：
+
+1. 打开一条主记录时，是否天然需要查看或维护它下面的一组明细。
+2. 明细是否独立归属于该主记录，而不是多个业务记录共享的独立对象。
+3. 两端字段能否真实关联到同一条主记录，字段类型和值域是否兼容。
+4. 子记录是否应随主记录的业务生命周期一起维护。
+
+普通引用、枚举映射、字典选项和只用于展示的 LOOKUP 都不应标记为 `main_sub`。元数据只能描述结构，不能证明业务归属；最终仍需结合真实记录验证。
+
+## 完整性规则
+
+有效的数据集关系应满足：
+
+- 当前和目标数据集都存在，且 `toDatasetCode` 指向真实数据集。
+- `fromField`、`toField` 都存在，字段类型和值域能够匹配。
+- `toFieldLabel` 是目标数据集的真实字段名，并适合向用户展示。
+- 关系方向处于支持范围内。
+- `joinType` 与真实数据约束和业务语义一致。
+- 同一组来源、目标和字段不存在重复关系。
+- `main_sub` 只用于真实的一对多业务归属关系。
+
+验收主子表时，应至少准备一条主记录和多条子记录：当前主记录只能读取归属于它的子记录，切换主记录后不能继续出现上一条记录的明细。
+
+## 与页面配置的边界
+
+- 数据集关系只定义数据模型语义；关系存在不代表页面已经生成关联区域、明细布局或新增编辑交互。
+- `LrSmartCreate`、`LrSmartUpdate` 和 `LrSmartDetail` 的 `props.sub_info` 是 PageSchema 展示与交互配置，不是数据集关系对象。
+- 标准页生成器使用的 `extend.subDatasetCode`、`extend.subTableName`、可选 `extend.subColumnName` 和 `relatedTablesJson` 属于页面生成协议；即使与关系元数据存在同名字段，它们也不是数据集 `relations` 对象本身。
+- 表单、筛选器和表格中的动态选项配置只负责加载候选数据，不能替代数据集关系声明。
+
+排查页面关联异常时，应先确认数据集关系本身的方向、字段、展示字段、基数和业务类型，再检查页面的数据源与组件绑定。

package/skills/rabetbase/knowledge/page-schema/external-resources-usage.md

@@ -0,0 +1,232 @@
+---
+name: PageSchema-external-resources-usage
+description: 外部资源（自定义SQL、BFF脚本、权限点）在PageSchema中的消费规范，Skill只引用不生成。先验知识：低代码引擎搭建协议、Ant Design 5 组件知识。
+tags: [page-schema, external-resources, custom-sql, bff, permission]
+---
+
+# 外部资源使用规范
+
+> **先验知识**：默认已具备低代码引擎搭建协议和 Ant Design 5 组件知识。
+
+## 1. 核心原则
+
+**Skill 职责边界**：
+
+- ✅ **只消费**：引用已生成的自定义 SQL、BFF 脚本、权限点
+- ❌ **不生成**：不负责创建新的自定义 SQL、BFF 脚本、权限点
+
+## 2. 自定义 SQL 使用规范
+
+### 2.1 两种聚合查询方式对比
+
+| 维度 | aggregate API | custom SQL |
+|------|--------------|------------|
+| API 路径 | `POST /api/{appCode}/{datasetCode}/aggregate` | `POST /api/custom/executeSql` |
+| 跨表支持 | **单表**（基于 datasetCode 对应的一张表） | **任意跨表**（自定义 SELECT + JOIN） |
+| SQL 编写者 | 平台自动生成 SQL | 开发者手写 SQL（MyBatis 语法） |
+
+**选择策略**：
+
+- **单表聚合**：优先使用 aggregate API（平台自动生成 SQL）
+- **跨表聚合**：必须使用 custom SQL（支持 JOIN、复杂条件）
+
+### 2.2 aggregate API 接口
+
+**接口路径**：`POST /api/{appCode}/{datasetCode}/aggregate`
+
+**请求参数**：
+
+```json
+{
+  "where": { "status": { "$eq": "ACTIVE" } },
+  "aggregate": [
+    { "type": "SUM", "column": "amount", "alias": "totalAmount" },
+    { "type": "COUNT", "column": "id", "alias": "recordCount", "distinct": true }
+  ],
+  "groupBy": ["company_id"],
+  "having": { "company_id": { "$notNull": true } },
+  "orderBy": [{ "totalAmount": "desc" }],
+  "currentPage": 1,
+  "pageSize": 20
+}
+```
+
+`having` 与 `where` 使用相同的对象结构，字段名必须是数据集真实字段；聚合结果别名可用于 `orderBy`。
+
+**聚合函数类型**：`SUM` / `AVG` / `COUNT` / `MAX` / `MIN`
+
+**在 PageSchema 中的配置方式**：
+
+```json
+{
+  "dataSource": {
+    "type": "aggregate",
+    "datasetCode": "customer_dataset_code",
+    "aggregate": [{ "type": "SUM", "column": "amount", "alias": "totalAmount" }],
+    "groupBy": ["status"]
+  }
+}
+```
+
+### 2.3 custom SQL 接口
+
+**接口路径**：`POST /api/custom/executeSql`
+
+**请求参数**：
+
+```json
+{
+  "sqlCode": "xxxx-xxxxx",
+  "params": { "customerId": "123", "startDate": "2025-01-01" }
+}
+```
+
+**在 PageSchema 中的配置方式**：
+
+```json
+{
+  "dataSource": {
+    "type": "customSql",
+    "sqlCode": "query_customer_with_level",
+    "params": { "customerId": "123" }
+  }
+}
+```
+
+- `type: "customSql"` 表示使用自定义 SQL 数据源
+- `sqlCode` 是在平台创建的自定义 SQL 的唯一标识
+- `params` 是传递给 SQL 的参数（对应 SQL 中的 `#{paramName}` 占位符）
+
+### 2.4 禁止的操作
+
+- ❌ 生成新的自定义 SQL 语句
+- ❌ 创建新的 sqlCode
+- ❌ 修改已有的自定义 SQL 内容
+
+---
+
+## 3. BFF 脚本使用规范
+
+### 3.1 BFF 脚本类型
+
+| 类型 | 说明 | 消费方式 | PageSchema 是否需要配置 |
+|------|------|---------|---------------------|
+| **HOOK 脚本** | 绑定到数据集 API（Before/After） | 平台自动执行 | ❌ 否（平台配置） |
+| **ENDPOINT 脚本** | 独立业务端点 | 通过 dataSource 配置 | ✅ 是（需要配置 dataSource） |
+
+**职责边界**：
+
+- `skill_edit_smart_page_dov2` 只消费 ENDPOINT 类型的 BFF 脚本
+- HOOK 类型的 BFF 脚本由平台自动执行，不需要在 PageSchema 中引用
+
+### 3.2 ENDPOINT 脚本消费方式
+
+**API 路径**：`POST /api/endpoint/{appCode}/{scriptName}`
+
+**步骤 1：在 dataSource 中配置 ENDPOINT API**：
+
+```json
+{
+  "dataSource": {
+    "list": [{
+      "id": "convertToCustomer",
+      "type": "fetch",
+      "options": {
+        "uri": "/api/endpoint/<appCode>/convertToCustomer",
+        "params": {}
+      }
+    }]
+  }
+}
+```
+
+**步骤 2：在按钮配置中调用**：
+
+```json
+{
+  "title": "转化为客户",
+  "optType": "flowAction",
+  "options": {
+    "flowList": [{
+      "active": true,
+      "optType": "request",
+      "options": {
+        "_bindDataSource": "convertToCustomer",
+        "_bindDataSourceParams": {
+          "type": "JSFunction",
+          "value": "function(extraParams) {\n  return { id: extraParams.rowKey };\n}"
+        }
+      }
+    }]
+  }
+}
+```
+
+### 3.3 HOOK 脚本说明
+
+HOOK 脚本绑定到数据集 API 上，在 API 执行前或执行后自动触发。Skill 不需要处理 HOOK 脚本，PageSchema 中无需引用。
+
+### 3.4 禁止的操作
+
+- ❌ 生成新的 BFF 脚本代码（HOOK 或 ENDPOINT）
+- ❌ 创建新的 scriptName
+- ❌ 在 PageSchema 中引用 HOOK 类型的 BFF 脚本
+
+---
+
+## 4. 权限点使用规范
+
+当前标准页面权限由 `LrSmartTable` 运行时内置逻辑处理，Agent 只维护 `LrSmartTable` schema，不生成权限字段。
+
+### 4.1 当前实现
+
+表格会在运行时过滤无权限按钮：
+
+- `toolbar.globalButtons`：按新增动作 `create` 校验。
+- `toolbar.exportButtons.buttons`：按按钮上的 `actionType` 校验，常见值为 `export` / `delete`。
+- `operateButtons`：按数组下标映射为 `update` / `detail` / `delete` 校验。
+
+hard rule：`operateButtons` 当前按数组下标硬编码权限动作，顺序必须严格保持 `[update, detail, delete]`。不要调换、插入额外按钮或省略中间位置；第 4 个及之后按钮不会进入当前权限过滤。
+
+### 4.2 当前权限链路
+
+运行时读取 `_context.appHelper.yt.pointPermitMap`：
+
+```text
+datasetCode -> {
+  DATA_CREATE?: boolean,
+  DATA_UPDATE?: boolean,
+  DATA_DELETE?: boolean,
+  DATA_DETAIL?: boolean,
+  DATA_EXPORT?: boolean
+}
+```
+
+当表格配置了 `datasetCode` 时，使用该数据集对应权限；未配置 `datasetCode` 时，使用 `pointPermitMap` 中第一组权限。
+
+动作映射：
+
+| actionType | 权限 key |
+|------------|----------|
+| `create` | `DATA_CREATE` |
+| `update` | `DATA_UPDATE` |
+| `delete` | `DATA_DELETE` |
+| `detail` | `DATA_DETAIL` |
+| `export` | `DATA_EXPORT` |
+
+### 4.3 Agent 规则
+
+- 不生成任何权限字段。
+- 批量导出 / 批量删除等 `exportButtons.buttons[]` 需要明确动作语义时，可配置 `actionType`。
+
+---
+
+## 5. 总结
+
+| 资源类型 | 允许操作 | 禁止操作 |
+|---------|---------|---------|
+| 自定义 SQL | 引用 sqlCode | 生成 SQL 语句 |
+| BFF 脚本 | 调用 scriptName | 生成脚本代码 |
+| 权限点 | 使用当前表格内置权限过滤 | 生成权限字段或创建权限点 |
+
+**用户需要新建资源时**：引导用户到平台手动配置，获取 code/name 后帮助配置到 Schema。