@lovrabet/rabetbase-cli 2.5.4 → 2.5.5-beta.1

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

@@ -0,0 +1,77 @@
+# 生成、浏览器迭代与发布
+
+## 安装独立 Skill
+
+CLI 包内包含 `skills/rabetbase-page-generation`。使用现有 Skill 安装工具从已安装 CLI 包目录安装：
+
+```sh
+npx skills add /path/to/rabetbase-cli/skills/rabetbase-page-generation -g -y
+```
+
+将路径替换为当前 CLI 包的真实位置，安装后确认 Agent 可发现 `rabetbase-page-generation`。CLI 既有 postinstall 安装的是 `rabetbase` Skill；此独立 Skill 的安装由使用方显式执行。
+
+## 绑定真实 Dataset
+
+1. 用 `rabetbase dataset detail --code <datasetCode> --format compress` 读取字段、类型、必填、枚举和操作。用 `rabetbase codegen sdk` 核验 SDK 签名；不要从原始接口元信息猜测请求或响应。
+2. 将 `templates/onepage` 整体复制到页面工作目录。先阅读对应页面目录的 `README.md` 和 `preview.png`，明确布局与交互；`shared/` 保存四页共用代码，复制时一起保留。它是供 Agent 改写的 JSX 模板，不是配置解释器：客户字段展示了分组、数字、枚举、日期、智能筛选和表单的完整写法。按真实 Dataset 改写 `shared/model.js` 的字段与查询、`shared/record-layout.jsx` 的分组说明、`list/index.jsx` 的筛选/标题/手机主字段、`shared/editor.jsx` 的控件/校验/写入字段及 `detail/index.jsx` 的标题/主键读取。不能只替换 Dataset code 就直接发布给其他业务。
+3. 替换 `shared/model.js` 中 `__APP_CODE__`、`__DATASET_CODE__`；创建前将尚无真实路径的 `__LIST_PATH__`、`__DETAIL_PATH__`、`__CREATE_PATH__`、`__UPDATE_PATH__` 设为空字符串，创建后回填服务端真实路径。四页使用相同绑定。示例以数字 `id` 为主键；其他类型需要同时改写校验、记录导航和 SDK 参数。
+4. 页面使用宿主 `useSdkClient()`：已核验的 Dataset 模型提供 `filter({where,currentPage,pageSize,orderBy})`、`getOne(id)`、`create(fields)`、`update(id,fields)`。列表读取 `tableData` 和 `paging.totalCount`；若实际 SDK 不同，按真实契约改写。只在已确认需要连接、聚合或业务规则时改用 Custom SQL / Backend Function。
+
+保持零值、枚举、空日期和主键类型正确；数字不加千分位，金额精度按字段定义。列表、详情和表单均区分加载、空数据、错误与重试。分页只使用已提交的筛选；搜索、重置和切换页大小回第一页，忽略过期响应。
+
+## 构建四个独立目录
+
+在页面工作目录安装页面构建工具 `esbuild`，准备已核验版本的智能搜索 JSX 入口及 CSS；不要求 CLI 安装这些页面开发依赖。`build.mjs` 只打包当前目录的四页源码，不读取 Dataset、不选模板、不创建平台资源。
+
+```sh
+npm install --save-dev esbuild
+node build.mjs ./pages-v1 /path/to/smart-filter/index.tsx /path/to/smart-filter/style.css
+```
+
+输出目录必须尚不存在，避免旧文件混入更新。结果为 `pages-v1/list`、`detail`、`create`、`update`；每页包含完整的 `src/app/index.jsx`、`page.js`、`page.css`，没有跨页源码依赖。四页共享相同 CSS 内容，避免打开子页时宿主更新资源导致父列表丢失样式。页面文案默认中文，按应用语言调整源码；需要多语言时使用宿主 `useI18n` 和页面自己的语言资源。
+
+构建脚本解析当前页面项目安装的 esbuild。若使用 npm 包形式的智能搜索入口，先检查实际 exports 并解析出具体文件路径；不要假设某版本存在 `smart-filter` 子入口。缺失组件或 CSS 时先解决依赖，不改成简易输入框宣称效果一致。
+
+## 创建、回填与更新
+
+对四页分别执行已有命令，下面以列表为例：
+
+```sh
+rabetbase page create --name "<页面名称>" --page-dir ./pages-v1/list --appcode <appCode> --dry-run --format compress
+rabetbase page create --name "<页面名称>" --page-dir ./pages-v1/list --appcode <appCode> --format compress
+rabetbase page custom-detail --id <pageId> --appcode <appCode> --format compress
+```
+
+复用 `page create` 的默认建菜单行为，需要父菜单时使用已有 `--parent-menu-id`。菜单展示通过既有 `rabetbase menu` 命令管理，先查看 `menu list` 和 `menu visibility-update --help` 并按要求预演，再执行授权的调整。隐藏菜单保留路由和资源，不等同于不创建菜单；不得删除页面绑定菜单来模拟隐藏。当前任务若允许四页菜单，按该策略验收；不要声称只有入口绑定菜单。菜单状态只根据真实返回和回查结果判断。
+
+记录四页 `pageId` 与真实路径，回填 `shared/model.js`，重新构建到新的输出目录。先回读远端当前 `codeContent`，再更新；`--page-dir` 是整目录替换，目录必须完整：
+
+```sh
+rabetbase page custom-update --id <pageId> --appcode <appCode> --page-dir ./pages-v2/list --format compress
+```
+
+ONEPAGE 子页读取 `onePageInfo.innerSearchParams.id`，直接访问时读取 `useLocation().search`。缺少或无效主键时不发数据请求。列表通过 `navigate(pathWithQuery, {onePage:true})` 打开子页；详情的上一条/下一条和详情切编辑使用当前面板替换，避免不断增加层级。更新保存后回原详情或父列表；直接访问返回真实入口。SDK 保存成功才发送按列表路径区分的刷新事件，父列表保留筛选和分页并重新读取数据；取消不写入数据、不发送刷新。
+
+## 本地与浏览器验收
+
+在非沙箱页面工作目录预览迭代；临时预览夹具、模拟数据和运行回执放任务验收目录，不加入 CLI 源码；页面目录中的 `preview.png` 是随 Skill 分发的效果参考。浏览器使用 Codex 内置浏览器。
+
+- 同 Dataset 对比旧标准页的字段、分组、智能搜索、表单密度与操作位置；覆盖空数据、有数据、无匹配结果和超过一页的数据。
+- 查询、重置、翻页、页大小、勾选和列设置；自然语言查询必须读取真实结果，失败不冒充空结果。
+- 列表打开详情/新增/更新，主键正确；详情上一条/下一条和编辑仍在当前 ONEPAGE 面板。
+- 必填错误、零值、枚举和日期；保存、重置、取消、保存后返回刷新；连续新增清空表单并聚焦首字段，快捷键不重复提交。
+- 桌面及手机窄屏，列表和子页无溢出，底部按钮可访问；父列表保持筛选/分页。实际设备软键盘、深色主题等未覆盖项需明确记录。
+- 仅操作授权的测试数据，写入前保留原值，验收后还原修改并清理本轮测试记录。旧页面只用于对比，不作为新流程的运行依赖。
+
+本地模拟不能证明真实 SDK、权限或 ONEPAGE 宿主正确。用四页预览验证真实数据流后再发布；若正式态暴露问题，修复后重新验收。
+
+## 发布与结果回查
+
+```sh
+rabetbase page custom-publish --id <pageId> --appcode <appCode> --remark "页面验收通过" --format compress
+rabetbase page custom-detail --id <pageId> --appcode <appCode> --format compress
+```
+
+四页分别检查发布状态 `FORMAL`、源码及版本，使用返回的运行 URL 打开正式态复验；报告实际菜单绑定情况。保留与最终提交/版本对应的复现步骤和结果，作为 MR 附件或外部验收材料；不把旧回执当成新版本证据。
+
+CLI beta 发布遵循 CLI 发布流程；页面验收不等于 npm 发布成功。Development Sandbox 中安装 CLI beta 及独立 Skill 后，验证 Agent 可发现该 Skill，并完整执行四页生成和浏览器 E2E；Runtime Sandbox 不安装该 Skill。

package/skills/rabetbase-page-generation/templates/onepage/build.mjs

@@ -0,0 +1,63 @@
+import { createRequire } from "node:module";
+import { mkdir, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// 页面项目自行安装构建依赖；此脚本不参与 CLI 命令或宿主构建。
+const require = createRequire(path.resolve("package.json"));
+const { build } = require("esbuild");
+const root = path.dirname(fileURLToPath(import.meta.url));
+const [output, componentEntry, componentCss] = process.argv.slice(2);
+if (!output || !componentEntry || !componentCss)
+  throw Error(
+    "Usage: node build.mjs <output directory> <smart-filter JSX entry> <smart-filter CSS>",
+  );
+const entry = path.resolve(componentEntry);
+const css = path.resolve(componentCss);
+for (const file of [entry, css]) {
+  if (!(await stat(file)).isFile()) throw Error(`Not a file: ${file}`);
+}
+// 输出必须是新目录，避免旧文件进入 custom-update 的完整替换范围。
+const destination = path.resolve(output);
+const external = [
+  "react",
+  "react/jsx-runtime",
+  "antd",
+  "@ant-design/icons",
+  "dayjs",
+  "@/context/app-context",
+];
+const outputs = [];
+for (const kind of ["list", "detail", "create", "update"]) {
+  const result = await build({
+    stdin: {
+      contents: `import ${JSON.stringify(css)};\nexport { default } from "./${kind}/index.jsx";`,
+      resolveDir: root,
+      sourcefile: "page-entry.jsx",
+      loader: "jsx",
+    },
+    bundle: true,
+    format: "esm",
+    platform: "browser",
+    jsx: "automatic",
+    outfile: path.join(destination, kind, "src/app/page.js"),
+    write: false,
+    external,
+    alias: { "@lovrabet/components/smart-filter": entry },
+  });
+  outputs.push(...result.outputFiles);
+}
+// 四页都引入相同的筛选 CSS 和页面 CSS，避免宿主资源替换破坏父列表。
+await mkdir(path.dirname(destination), { recursive: true });
+await mkdir(destination);
+for (const file of outputs) {
+  await mkdir(path.dirname(file.path), { recursive: true });
+  await writeFile(file.path, file.contents);
+}
+for (const kind of ["list", "detail", "create", "update"]) {
+  await writeFile(
+    path.join(destination, kind, "src/app/index.jsx"),
+    'import "./page.css";\nexport { default } from "./page.js";\n',
+  );
+}
+console.log(`Built four CustomJSX page directories in ${destination}`);

package/skills/rabetbase-page-generation/templates/onepage/create/README.md

@@ -0,0 +1,20 @@
+# 新增页
+
+入口是 `index.jsx`，以 `mode="create"` 使用 `../shared/editor.jsx`。新增与更新共享控件及校验，分别构建成独立 CustomJSX 页面。
+
+![新增页效果示例](preview.png)
+
+图中为本模板空表单的桌面效果，供字段分组与操作位置参考；外层“关闭子页”是本地预览容器，真实运行使用 ONEPAGE 宿主。
+
+## 保留的交互
+
+- 按 Dataset 分组展示字段、说明、必填提示；隐藏自动生成的主键。
+- 顶部和底部都可保存，支持 Ctrl/⌘+Enter；必填校验失败时定位字段，提交中阻止重复保存。
+- “保存并返回”关闭子页并刷新列表；“保存并继续新增”保留新增页，清空表单并聚焦首字段。
+- 保存失败保留输入，重置恢复初始表单；手机日期使用适合触控的输入方式。
+
+## 生成时修改
+
+在 `shared/editor.jsx` 中按真实字段调整控件、校验、默认值与写入白名单，在 `shared/record-layout.jsx` 调整分组、说明和必填。需要同步首字段聚焦引用。不要把主键或只读字段提交给创建接口。
+
+零值、枚举及空日期必须正确转换。只有 SDK 创建成功才通知列表刷新；取消不创建记录。完整构建及发布见 [生成流程](../../../references/generation.md)。

package/skills/rabetbase-page-generation/templates/onepage/create/index.jsx

@@ -0,0 +1,4 @@
+import EditorPage from "../shared/editor";
+export default function CreatePage() {
+  return <EditorPage mode="create" />;
+}

package/skills/rabetbase-page-generation/templates/onepage/detail/README.md

@@ -0,0 +1,20 @@
+# 详情页
+
+入口是 `index.jsx`，是独立的只读页面。通过 `shared/record-layout.jsx` 与表单保持字段分组一致，不使用抽屉。
+
+![详情页效果示例](preview.png)
+
+图中为本模板使用本地示例数据的桌面效果，供布局与组件参考；外层“关闭子页”是本地预览容器，真实运行使用 ONEPAGE 宿主。
+
+## 保留的交互
+
+- 顶部显示记录名称和可复制的主键；提供编辑、当前列表页内上一条/下一条，首尾按钮禁用。
+- 按分组显示标签、说明和只读值；枚举显示标签，空值显示 `--`，数字不加千分位。
+- 编辑替换当前 ONEPAGE 面板，保存后回到更新后的详情；关闭返回原列表。
+- 重新读取真实 SDK 记录，区分加载失败、记录不存在与正常数据。
+
+## 生成时修改
+
+根据 Dataset 修改标题字段、主键校验、SDK 模型和分组。ONEPAGE 优先读取 `onePageInfo.innerSearchParams.id`，直接访问再读 URL 查询参数。缺失或无效主键时不发请求。
+
+详情与更新应保持不同的页面 ID/路径，不能用一个页面切换只读状态替代两页。完整构建及发布见 [生成流程](../../../references/generation.md)。

package/skills/rabetbase-page-generation/templates/onepage/detail/index.jsx

@@ -0,0 +1,194 @@
+import { useEffect, useState } from "react";
+import {
+  Alert,
+  Button,
+  ConfigProvider,
+  Form,
+  Empty,
+  Spin,
+  Space,
+  Typography,
+  theme,
+} from "antd";
+import {
+  useAppContext,
+  useAppTheme,
+  useLocation,
+  useNavigate,
+  useSdkClient,
+} from "@/context/app-context";
+import { DATASET_CODE, LIST_PATH, childPaths, formatField } from "../shared/model";
+import { RecordGroups, RecordItem, recordTheme } from "../shared/record-layout";
+import "../shared/page.css";
+
+function CustomerDetail() {
+  const client = useSdkClient();
+  const { onePageInfo } = useAppContext();
+  const location = useLocation();
+  const navigate = useNavigate();
+  const rawId =
+    onePageInfo?.innerSearchParams?.id ??
+    new URLSearchParams(location.search).get("id");
+  const recordId = rawId == null ? "" : String(rawId).trim();
+  const [state, setState] = useState({
+    loading: true,
+    record: null,
+    error: "",
+  });
+  const [retry, setRetry] = useState(0);
+  const params =
+    onePageInfo?.innerSearchParams ??
+    Object.fromEntries(new URLSearchParams(location.search));
+  const ids = [
+    ...new Set(
+      String(params.ids || "")
+        .split(",")
+        .filter((id) => /^\d+$/.test(id)),
+    ),
+  ].slice(0, 100);
+  const position = ids.indexOf(recordId);
+  function moveRecord(index) {
+    navigate(
+      `${childPaths.detail}?${new URLSearchParams({ id: ids[index], ids: ids.join(",") })}`,
+      { replace: true },
+    );
+  }
+  useEffect(() => {
+    const changed = (event) => {
+      if (event.detail === LIST_PATH) setRetry((value) => value + 1);
+    };
+    window.addEventListener("lovrabet:page-generation:changed", changed);
+    return () =>
+      window.removeEventListener("lovrabet:page-generation:changed", changed);
+  }, []);
+
+  useEffect(() => {
+    let active = true;
+    setState({ loading: true, record: null, error: "" });
+    (async () => {
+      try {
+        if (!/^\d+$/.test(recordId))
+          throw Error("缺少或无效的客户主键，请从列表重新打开详情");
+        const record =
+          await client.models[`dataset_${DATASET_CODE}`].getOne(recordId);
+        if (
+          record != null &&
+          (typeof record !== "object" || Array.isArray(record))
+        )
+          throw Error("详情响应无效，请重试");
+        if (active) setState({ loading: false, record, error: "" });
+      } catch (cause) {
+        if (active)
+          setState({
+            loading: false,
+            record: null,
+            error: cause.message || "加载失败，请重试",
+          });
+      }
+    })();
+    return () => {
+      active = false;
+    };
+  }, [client, recordId, retry]);
+
+  return (
+    <main className="customer-record customer-detail">
+      {!onePageInfo && (
+        <Button className="record-back" onClick={() => navigate(LIST_PATH)}>
+          返回列表
+        </Button>
+      )}
+      <header className="record-heading">
+        <div className="record-heading-title">
+          <h1>{state.record?.customer_name || "客户详情"}</h1>
+          <Typography.Text
+            type="secondary"
+            copyable={
+              recordId
+                ? { text: recordId, tooltips: ["复制主键", "已复制"] }
+                : false
+            }
+          >
+            主键 {recordId || "—"}
+          </Typography.Text>
+        </div>
+        <Space wrap>
+          <Button
+            type="primary"
+            disabled={!state.record || state.loading}
+            onClick={() =>
+              navigate(
+                `${childPaths.update}?${new URLSearchParams({ id: recordId, returnDetail: "1", ids: ids.join(",") })}`,
+                { replace: true },
+              )
+            }
+          >
+            编辑客户
+          </Button>
+          {position >= 0 && (
+            <span className="record-sequence" aria-label="当前页记录导航">
+              <Button
+                disabled={position === 0 || state.loading}
+                onClick={() => moveRecord(position - 1)}
+              >
+                上一条
+              </Button>
+              <span>
+                本页 {position + 1}/{ids.length}
+              </span>
+              <Button
+                disabled={position === ids.length - 1 || state.loading}
+                onClick={() => moveRecord(position + 1)}
+              >
+                下一条
+              </Button>
+            </span>
+          )}
+        </Space>
+      </header>
+      {state.loading ? (
+        <Spin aria-label="正在加载客户详情" />
+      ) : state.error ? (
+        <Alert
+          type="error"
+          showIcon
+          message="详情加载失败"
+          description={state.error}
+          action={
+            <Button onClick={() => setRetry((value) => value + 1)}>重试</Button>
+          }
+        />
+      ) : state.record ? (
+        <Form layout="vertical" className="record-readonly" component="div">
+          <RecordGroups>
+            {(field) => (
+              <RecordItem key={field.key} field={field}>
+                <div className="record-value">
+                  {formatField(state.record[field.key], field)}
+                </div>
+              </RecordItem>
+            )}
+          </RecordGroups>
+        </Form>
+      ) : (
+        <Empty description="客户不存在或已被删除" />
+      )}
+    </main>
+  );
+}
+
+export default function DetailPage() {
+  const hostTheme = useAppTheme();
+  return (
+    <ConfigProvider
+      theme={recordTheme(
+        hostTheme,
+        hostTheme?.mode === "dark"
+          ? theme.darkAlgorithm
+          : theme.defaultAlgorithm,
+      )}
+    >
+      <CustomerDetail />
+    </ConfigProvider>
+  );
+}

package/skills/rabetbase-page-generation/templates/onepage/list/README.md

@@ -0,0 +1,20 @@
+# 列表页
+
+入口是 `index.jsx`，数据绑定、查询和格式化来自 `../shared/model.js`。列表是四页包的入口，通过 ONEPAGE 打开详情、新增与更新。
+
+![列表页效果示例](preview.png)
+
+图中为本模板使用本地示例数据的桌面效果，供布局与组件参考；不是业务数据或真实环境验收凭证。
+
+## 保留的交互
+
+- 顶部使用 LrSmartFilter 智能搜索组合，支持自然语言与结构化筛选；查询结果交给真实 SDK。
+- 工具栏包含勾选摘要、导出、刷新、列设置和新增；列偏好按应用与 Dataset 区分。
+- AntD 表格使用服务端总数分页，查询及页大小变更回到第一页；错误、空数据、无匹配结果分别反馈。
+- 名称点击打开详情；操作列提供更新、详情和删除确认。手机使用卡片，保留勾选、分页及主要操作。
+
+## 生成时修改
+
+按 Dataset 改写 `shared/model.js` 中字段、枚举、排序、查询和页面路径；同步修改本页筛选控件、主显示字段、手机卡片字段、标题及导出名称。数字不加千分位，金额精度遵循字段定义。不要把图中的客户字段或测试数据写入其他业务。
+
+保存后的刷新通知以真实列表路径区分。返回列表应保留已提交的筛选和分页，并读取最新数据。完整构建及发布见 [生成流程](../../../references/generation.md)；应整体构建四页，而不是单独上传本目录。