@lovrabet/rabetbase-cli 2.5.4-beta.4 → 2.5.4

package/skills/rabetbase/references/rabetbase-menu-subapp-assets-update.md

@@ -0,0 +1,27 @@
+# menu subapp-assets-update
+
+更新指定菜单宿主中一个已存在的前端子应用共享资源 URL。只替换该条目的 `resources`，保留读取到的加载方式、基础路径、其他条目以及 `extend` 中的其他配置（包括直连数据库设置）。通过 `--resources` 提供完整资源 URL 列表。
+
+正式写入需要目标宿主应用的应用管理员权限。系统管理员、所属租户管理员沿用平台现有权限规则。“宿主”只表示目标应用，不是独立权限角色；其他业务应用的权限不能替代目标宿主应用的权限。仅具有该应用的应用开发者权限时可以查询和预演，但不能更新；预演成功不代表具有写权限。遇到权限不足时说明所需权限，不通过逐菜单更新或切换业务 appCode 绕过。
+
+```bash
+rabetbase menu subapp-assets-update --app-name store --resources '["https://cdn.example.com/store/2/app.js","https://cdn.example.com/store/2/app.css"]' --dry-run --format json
+rabetbase menu subapp-assets-update --app-name store --resources '["https://cdn.example.com/store/2/app.js","https://cdn.example.com/store/2/app.css"]' --expected-hash <data.body.preview.expectedHash> --format json
+rabetbase menu subapp-assets-status --app-name store --format json
+```
+
+`--app-name` 必填，去除首尾空白后精确匹配宿主中已有的 `extend.assets[].appName`。标识沿用平台已有绑定，不随包名或版本变化；CLI 不自动从工程推导，来源与冲突处理见[宿主前端集成指南](../guides/host-frontend-integration.md)。菜单宿主沿用 CLI 的应用选择：可用 `--appcode` / `--app` 指定，否则使用工作区默认应用或唯一应用；多应用未选定目标时提示选择。`defaultApp` 是默认应用上下文，在本命令中作为菜单宿主。前端子应用访问哪些业务 appCode 是独立关系，不根据业务应用列表批量更新。默认应用与目标宿主不同时，用参数覆盖。
+
+本命令不创建子应用条目、不改名、不修改菜单绑定。已有菜单绑定但缺少共享条目时，保留原绑定和菜单资源，使用平台已有配置入口建立同名共享条目，再查询核对；不能因为共享配置缺失就自动改成逐菜单更新。
+
+用户要求更新“子应用版本／子应用资源”时使用本命令；只有明确要求修改菜单自身资源时才使用 `menu asset-update`。同名子应用在不同宿主下分别配置，本次只修改选中的宿主。预演与正式写入必须保持同一宿主、子应用和目标 URL 列表；修改其中任何一项后应重新预演。
+
+用户只给版本号或要求“从 A 升到 B”时，先按[资源版本核验](../guides/host-frontend-integration.md#子应用资源版本核验)确认完整资源 URL 和当前起点；不猜测目标 URL。起始版本不符或无法确认时先澄清，当前配置已匹配目标 URL 时不重复写入。预演指纹用于检测配置漂移，不证明当前配置对应用户指定的起始版本。
+
+`--resources` 必填，值为资源 URL 的 JSON 字符串数组。JSON/compress 预演结果位于 `data.body.preview`，返回 `preview.appCode`、`preview.appName`、`preview.before`、`preview.after`、`preview.expectedHash`，不写入。正式结果返回 `data.appCode` 与 `data.appName` 标明实际目标。指纹同时绑定宿主、子应用、目标 URL 列表和当前应用配置；正式执行要求 `--expected-hash` 与本次输入及写前回读配置匹配，写后再次读取管理端应用并核对资源和扩展字段；URL 未变化时不重复写入。命令要求目标子应用条目唯一、应用发布状态可读、资源 URL 为绝对 HTTPS 地址且至少包含一个 JS 入口。
+
+现有应用更新接口整列替换 `extend`，不提供原子并发比较；预演摘要只能阻止已发生的变化，不能消除写前检查与实际写入之间的竞争窗口。更新期间应避免并发修改同一宿主配置。
+
+CLI 的保留和回读校验范围是应用读取接口返回的配置，无法证明数据库中未被接口返回的字段得到保留。直接访问数据库不是日常更新的通用前置条件；若发现未知扩展字段或有具体证据表明接口遗漏字段，应单独协调有权限的维护人员进行只读核查，核清后再决定是否更新，不得据管理端回读声称所有数据库字段均已保留。
+
+服务端保存应用时可能触发独立部署自动同步，但命令仅确认管理端回读，`independentDeploymentVerified=false` 不表示目标已生效。本命令不上传文件，也不校验 CDN 文件字节；写入前需确认 CDN 资源已就绪。若写入结果或回读验证不确定，先用 `menu subapp-assets-status` 按相同宿主和子应用核查，不要直接重试。

package/skills/rabetbase/references/rabetbase-menu-sync.md

@@ -1,33 +1,56 @@
 # menu sync
 
-扫描本地 `src/pages/**/*.tsx`，把线上缺失的路由注册为平台 `procode` 菜单。
+将前端子应用工程中平台缺失的页面路由注册为 `procode` 菜单。优先读取 `src/features/routing/routes.json` 中声明的页面路由，包括 `visible: false`；没有该清单时沿用 `src/pages/**/*.tsx` 扫描。命令只注册菜单与资源引用，不上传页面源码或构建资源。
+
+数据列表页和自定义页面走各自的页面创建与发布流程，不使用本命令接入；操作入口见[宿主前端集成指南](../guides/host-frontend-integration.md)。
 
 > **风险等级：write** — 修改平台菜单配置。
 
-## 命令
+## 默认引导：Agent 按菜单树注册
+
+前端子应用优先由 Agent 按业务菜单树规划，再调用 `menu sync` 注册页面并引用子应用共享资源。`menu sync` 是新旧流程共用的注册命令；作为兼容兜底保留的是手动扫描、逐菜单填写资源及原有批量操作方式。交互向导、`--yes` 全量同步、`--paths` 精确选择及默认根级创建均保持兼容，不增加 CLI 参数门禁。
+
+1. 读取项目路由和 `menu list --verbose` 的 `id / parentId / type / path / extend.appName`，核实菜单宿主，按[宿主前端集成指南](../guides/host-frontend-integration.md) 确定本工程的绑定，优先复用现有分组。源码目录和 URL 层次不等于业务菜单层次。
+2. 展示拟创建的菜单树，注明新增分组、页面显隐和子应用绑定。只有业务归属不明确时才询问用户；已明确的根级页面可正常创建。
+3. 缺失分组用 `menu group-create` 按父子顺序创建并回读，取得真实 ID。分组重名时按父链定位，不猜测名称对应关系。
+4. 用 `menu subapp-assets-status` 核查共享资源。子应用页面优先传 `appName`，通常不传菜单 JS/CSS。查询失败或共享资源缺失不等于用户选择了旧路径，不自动改写成逐菜单资源。
+5. Agent 默认按明确 `--paths`、`parentId` 或路由清单里的 `group` 预演和创建。不同父节点分批处理，或复用清单中能唯一匹配的分组；不要给跨组页面统一覆盖一个父节点。用户明确采用原有全量或交互流程时，沿用其选择。
+6. 用 `menu list --verbose` 回读父节点、排序、显隐及 `extend.appName` 绑定，不只按创建数量报告成功。请求结果未知时先回读，不盲目重试。已有菜单默认保留层次，移动或重组是独立操作。
+
+子应用版本升级使用 `menu subapp-assets-update`，不批量更新菜单 URL。共享资源与菜单兜底 URL 不同，应分别报告，不能直接判断子应用版本不一致。
+
+```bash
+# 示例中的 42 应替换为已核实的目录 ID
+rabetbase menu list --appcode <host-appcode> --verbose --format compress
+rabetbase menu subapp-assets-status --appcode <host-appcode> --app-name store-app --format compress
+rabetbase menu sync --appcode <host-appcode> --paths "/record-detail" --params '{"appName":"store-app","parentId":42,"visible":false}' --dry-run --format compress
+rabetbase menu sync --appcode <host-appcode> --paths "/record-detail" --params '{"appName":"store-app","parentId":42,"visible":false}' --yes --format compress
+```
+
+## 兜底：原有终端与脚本路径
+
+这些用法保持兼容。没有分组信息的新页面按原行为创建到根级，不会把已有菜单打平或移动。涉及业务分组时先核对预演结果，避免误把新页面全部放到根级。
 
 ```bash
-# 交互模式（TTY）
+# 交互向导仍可使用
 rabetbase menu sync
 
-# 发现待同步页面的真实 path，不写入
+# 查看全部待同步页面，不写入
 rabetbase menu sync --dry-run --format json
 
-# 按 targetPages[].path 精确预览
-rabetbase menu sync --paths "<local-page-path>" --params '{"jsUrl":"https://cdn.example.com/app.js"}' --dry-run --format compress
-
-# 静默全量同步
+# 原有全量同步仍可使用
 rabetbase menu sync --yes
 
-# 静默部分同步（预填 URL 和精确 path）
-rabetbase menu sync --paths "<local-page-path-1>,<local-page-path-2>" --params '{"jsUrl":"https://...js","cssUrl":"https://...css"}' --yes
+# 原有指定路径、菜单资源用法仍可使用
+rabetbase menu sync --paths "<local-page-path>" --params '{"jsUrl":"https://cdn.example.com/app.js"}' --dry-run --format compress
+rabetbase menu sync --paths "<local-page-path>" --params '{"jsUrl":"https://cdn.example.com/app.js"}' --yes --format compress
 ```
 
 ## 参数
 
 | Flag | 类型 | 必填 | 默认 | 说明 |
 |------|------|------|------|------|
-| `--params <json>` | string | 否 | — | 预填 JS/CSS URL。JSON 格式：`{"jsUrl":"...","cssUrl":"..."}` |
+| `--params <json>` | string | 否 | — | 可填 `jsUrl`、`cssUrl`、`appName`、`visible`、`parentId`。`visible` 为布尔值，`parentId` 为非负整数 |
 | `--paths <csv>` | string | 否 | — | 按本地页面 path 精确选择；值来自 dry-run 的 `targetPages[].path` |
 | `--yes` | boolean | 否 | — | 确认非交互执行；未传 `--paths` 时创建全部本地未上线页面 |
 | `--dry-run` | boolean | 否 | `false` | 复用真实扫描、线上 diff 和 URL 校验，返回计划但不创建菜单 |
@@ -37,7 +60,7 @@ rabetbase menu sync --paths "<local-page-path-1>,<local-page-path-2>" --params '
 
 1. **`--yes`** — 非交互同步；未传 `--paths` 时创建全部本地未在平台上的页面
 2. **`--paths` + `--yes`** — 按本地 path 精确同步指定页面
-3. **TTY 交互式** — 展示名称、path 与线上状态 → checkbox 选择未注册页面 → 输入 JS/CSS URL → 确认 → 执行创建
+3. **TTY 交互式** — 展示名称、path 与线上状态 → checkbox 选择未注册页面 → 填写 JS/CSS URL 或使用已配置子应用 → 确认 → 执行创建
 
 ## 输出
 
@@ -47,12 +70,15 @@ rabetbase menu sync --paths "<local-page-path-1>,<local-page-path-2>" --params '
 
 ## 提示
 
-- 本地页面扫描 `src/pages` 目录
+- 有 `src/features/routing/routes.json` 时只同步清单中的有效页面；每项必须有存在的 `pageFile`、一致的 `path`、非空 `label` 和布尔 `visible`。隐藏页面也必须注册菜单，`visible: false` 只控制导航显隐
+- 清单可选 `group` 与 `order`。显式 `--params.parentId` 优先于清单 `group`：非零 ID 指向的节点不存在或不是当前宿主中的 folder 时拒绝，`0` 表示根节点。未指定 `parentId` 时，若提供了 `group`，则必须匹配宿主中唯一的 folder；两者均未提供时，保留原有根级创建行为
+- 无清单时扫描 `src/pages`，保持原有项目兼容
 - 同步前会获取线上菜单列表做 diff
 - path 是稳定选择器，名称只用于展示；多个 path 必须全部匹配
-- 已在平台存在的 path 不会重复创建
+- path 比较统一忽略首尾斜杠，重复选择同一路径只创建一次；已在平台存在的 path 不会重复创建
 - 交互模式下会展示 compare table（名称、path、本地与线上状态）
 - CLI 只注册菜单和资源引用，不构建、不上传源码或静态资源
+- `--params.appName` 将页面绑定到菜单宿主的同名前端子应用共享资源。菜单宿主使用 CLI 当前选中的应用，支持工作区默认应用或唯一应用，也可用 `--appcode` / `--app` 覆盖；子应用访问的业务 appCode 是独立关系。子应用资源在支持该机制的宿主中优先生效；不填 JS/CSS 时 CLI 会先确认同名共享资源非空，菜单资源留空。仍须核对目标宿主支持共享资源
 - 当前 React/Vite 模板使用 `loadScriptMode=import`；资源 URL 指向已部署的 CDN 构建产物
 
 ## 参考

package/skills/rabetbase/references/rabetbase-page-create.md

@@ -1,6 +1,6 @@
 # page create
 
-创建 JSX 自定义页面，并同时创建菜单入口。命令固定返回 `pageType=CUSTOM`。
+创建自定义页面，并同时创建菜单入口。命令固定返回 `pageType=CUSTOM`。
 
 该命令不接受 `--page-type`。工作台、看板、门户或复杂交互仍然属于 CUSTOM 页面；`rabetbase project` 管理独立子应用工程，不是页面类型或复杂页面的兜底入口。
 

package/skills/rabetbase/references/rabetbase-page-generate-start.md

@@ -2,10 +2,12 @@
 
 异步提交或复用数据列表页（Data List Page）生成任务。
 
+生成流程会在生成页面后自动创建菜单入口，无需额外绑定子应用 appName 或执行 `menu sync`。提交成功仅表示任务已受理；跟进原任务，并核对完整页面组及对应菜单事实后，再报告页面和菜单已就绪。
+
 ## 命令
 
 ```bash
-# 默认行为：仅预览，不调用平台 API
+# 默认行为：仅预览，会读取前置事实，不提交生成任务
 rabetbase page generate-start --datasetcode 097b7361b76c42bcb12b923fa5a08861 --format json
 rabetbase page generate-start --alias order --format json
 rabetbase page generate-start --datasetcode 097b7361b76c42bcb12b923fa5a08861 --dry-run --format json
@@ -22,8 +24,8 @@ rabetbase page generate-start --alias order --apply --format json
 - CLI 会先执行 `page data-list-status` 做前置判定；底层仍调用既有服务端 `standard-page-status` 接口。
 - 若允许生成且传入 `--apply`，CLI 会自动生成 `clientOperationId`，并调用 Java 侧 `generate-standard-pages/start`。
 - 提交结果固定返回 `pageType=DATA_LIST` 与 `pagePattern=CRUD_PAGE_SET`；命令不接受 `--page-type` 或 `--page-pattern`。
-- 返回结果里的 `operationId` 是服务端 job 主标识；`clientOperationId` 是调用方恢复 / 幂等锚点。
-- `query.command` 默认给出 `operationId` 查询；调用方若只保留了 `clientOperationId`，也可以用它恢复到同一条任务查询。
+- 返回结果里的 `taskId` 是首选查询标识；`operationId` 用于兼容旧响应，`clientOperationId` 是调用方恢复 / 幂等锚点。
+- `query.command` 优先使用 `taskId`，缺失时使用 `operationId`，再回退到 `clientOperationId`，查询时只携带其中一个标识。
 - Agent / 自动化编排优先直接复用返回值里的 `query.command`，不要自己重新拼接恢复查询命令。
 - Agent 自动化场景下，编排器应先跑一次默认预览校验候选数据集，再带 `--apply` 提交；不应直接对所有数据集跑 `--apply`。
 

package/skills/rabetbase/references/rabetbase-page-generate-status.md

@@ -21,6 +21,7 @@ rabetbase page generate-status --datasetcode 097b7361b76c42bcb12b923fa5a08861 --
 
 - 命令查询的是**任务状态**，不是页面事实。
 - 当任务进入成功终态时，CLI 会补查 `page data-list-status`，把页面事实一并附在结果里，方便你直接判断是否形成完整数据列表页组。
+- 生成流程自动创建菜单入口；成功终态仍需核对完整页面组及对应菜单事实。预期菜单入口缺失时如实报告并核查，不报告整体就绪，也不自动用 `menu sync` 补建。
 - 若任务仍在 `PENDING/PROCESSING/RUNNING`，结果会保持机器可读的 `status / nextAction / query`。
 - 提交生成后保存 `taskId`、`operationId` 与 `clientOperationId`；超时、未知状态或网络失败时复用原标识查询，不重新执行 `generate-start --apply`，不得自动重提。
 - 成功终态时，页面组锚点位于 `data.dataListPageStatus.pageSets[].versionTag`。存在多个完整组、残留页或冲突时交给用户确认，不猜测 `versionTag`。

package/skills/rabetbase.manifest.json

@@ -2,8 +2,8 @@
   "schemaVersion": 1,
   "name": "rabetbase",
   "packageName": "@lovrabet/rabetbase-cli",
-  "packageVersion": "2.5.4-beta.4",
-  "skillVersion": "2.5.4-beta.4",
+  "packageVersion": "2.5.4",
+  "skillVersion": "2.5.4",
   "files": [
     "SKILL.md",
     "guides/approval-flow-development-workflow.md",
@@ -18,6 +18,8 @@
     "guides/data-api-guidelines.md",
     "guides/database-connection-workflow.md",
     "guides/frontend-development.md",
+    "guides/host-frontend-integration.md",
+    "guides/independent-deployment.md",
     "guides/legacy-application-blueprint-workflow.md",
     "guides/menu-anomaly-manual-cleanup.md",
     "guides/page-development-workflow.md",
@@ -43,6 +45,7 @@
     "references/rabetbase-api-list.md",
     "references/rabetbase-api-pull.md",
     "references/rabetbase-app-config.md",
+    "references/rabetbase-app-detail.md",
     "references/rabetbase-app-list.md",
     "references/rabetbase-app-members-list.md",
     "references/rabetbase-auth-login.md",
@@ -109,6 +112,8 @@
     "references/rabetbase-menu-move.md",
     "references/rabetbase-menu-regroup-start.md",
     "references/rabetbase-menu-rename.md",
+    "references/rabetbase-menu-subapp-assets-status.md",
+    "references/rabetbase-menu-subapp-assets-update.md",
     "references/rabetbase-menu-sync.md",
     "references/rabetbase-menu-visibility-update.md",
     "references/rabetbase-notification-config-list.md",
@@ -150,5 +155,5 @@
     "references/rabetbase-user-account.md",
     "references/rabetbase-workspace.md"
   ],
-  "digest": "e1381f35f9285560710dd0866fe6a155b9c0fed7ed937c8da8f723eafd12eaa1"
+  "digest": "74a9c0d783a16c3b0881f4bfcbae651c32b3c540d5c9d1cbe24ecf80f0bda0b4"
 }