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

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

@@ -0,0 +1,126 @@
+# 生成、浏览器迭代与发布
+
+## 安装独立 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 的安装由使用方显式执行。
+
+## 确定应用与页面需求
+
+默认在正式环境（prod）的当前应用完成任务。先核对当前 CLI 路由、用户提供的应用链接、Dataset 和已有页面是否一致；用户明确指定 daily 或企业部署时沿用该目标，不因查不到应用而切换环境试写。命令示例沿用已核验的当前路由，daily 检查不是 prod 交付门禁，也不要求非技术用户选择环境参数。
+
+用户要求创建或重做页面后，按该任务范围完成页面创建、保存、串联、验收和发布，不要求用户逐个批准命令或每个页面。只有业务范围或目标应用不明确时做一次必要的简短确认，例如“我会做一个问卷列表，支持查看和新增，完成后给你入口”。用户只要方案或预览时尊重这个停止点；工具权限拦截时保留已完成成果，不绕过控制、不自行提高风险上限。
+
+先形成内部页面计划，记录需要的能力、入口、页面间跳转、菜单展示和旧页面处理：
+
+- `list / detail / create / update` 是可选基础模板。只读场景按需保留列表、详情；仅查看单条记录可以只有详情，仅录入可以只有新增。不可编辑时不创建更新页，也移除所有编辑入口和写入逻辑；“不可修改”与“允许新增”的边界若不明确，用业务语言简短确认。明确只读时同时移除新增、编辑、删除和批量写入能力。
+- 用户需要看板、审批或汇总时可以扩展页面。按实际业务需求决定入口，不强行补齐四页；未选择的页面不创建菜单，不留下链接或按钮。
+- 通过 Dataset 关联页、`menu list` 与对应页面详情识别已有 lowcode 和 CustomJSX 页面。内部记录旧页面到新页面的名称、类型、`pageId`、`menuId`、路径和用途对应关系；旧 lowcode 的 ID 不得用于 `custom-detail`、`custom-update` 或 `custom-publish`。
+- 用户给的链接可能只是定位应用的旧页面。新流程应使用计划内新页面的真实路径，不能把旧页面路径回填成新页面路径；交付时提供新的入口。重试前查已有创建回执和线上页面，不能仅凭同名判断同一页面或重复创建。
+
+## 菜单与旧页面安排
+
+新页面默认只显示业务入口，作为详情、录入、编辑等流程内部节点的页面设为隐藏；独立入口按用户需求显示。扩展或裁剪页面后同步调整菜单策略，不能固定假设永远有四个页面。
+
+新流程验收通过后，可以向用户建议隐藏旧 lowcode 页面，确认不再使用时也可以建议删除。已包含在用户替换要求中的隐藏安排直接执行；未明确要替换旧入口时先建议，不能悄悄隐藏仍在使用的旧页面。删除旧页面需有明确删除意图、核对影响范围和外部引用；保留页面不影响新流程交付。隐藏保留路由，删除不能用来代替隐藏。
+
+## 绑定真实 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。
+
+保持零值、枚举、空日期和主键类型正确；数字不加千分位，金额精度按字段定义。列表、详情和表单均区分加载、空数据、错误与重试。分页只使用已提交的筛选；搜索、重置和切换页大小回第一页，忽略过期响应。
+
+## 组装计划内页面目录
+
+确认宿主可解析已发布的 `@lovrabet/components` 版本，并且该版本从包根入口导出 `LrSmartFilter`。模板直接使用这个公共组件，不复制 JSX 或 CSS 源码，也不改写成本地筛选器；不要求 CLI 安装页面构建依赖。若宿主解析失败，停止页面发布，通知用户需要由 `app-platform` 更新依赖或构建模板，不修改该仓库。`build.mjs` 只组装当前目录的四页可读源码，不读取 Dataset、不选模板、不创建平台资源，也不生成 `page.js`。平台保存/发布时使用新的微应用构建模板完成 JSX 编译。
+
+```sh
+node build.mjs ./pages-v1
+```
+
+输出目录必须尚不存在，避免旧文件混入更新。结果为 `pages-v1/list`、`detail`、`create`、`update`；每页包含可读的 `src/app/index.jsx`、`src/shared` 源码，并通过 `import { LrSmartFilter } from "@lovrabet/components"` 使用公共组件，不包含 `page.js` 或其他预编译 bundle。基础脚本仍输出四个目录，不负责选择页面；只对计划中的目录执行创建、更新和发布，本地多出的目录不代表已创建平台资源。扩展页由 Agent 在工作目录按相同 `src/app/index.jsx` 与所需 `src/shared` 结构组织，不假设脚本自动发现新目录，也不为本次业务改写已安装的 Skill。每个上传页面都拥有完整源码，避免更新一个页面时依赖另一个页面的文件。删除未选页面对应的按钮、导航、字段动作和不可用操作；详情没有编辑页时不能保留“编辑”按钮。组装成功不等于平台编译成功。页面文案默认中文，按应用语言调整源码；需要多语言时使用宿主 `useI18n` 和页面自己的语言资源。
+
+构建脚本不复制组件源码或独立 CSS，也不把它改成简易输入框或预编译 bundle 来规避依赖问题。组件导出已经发布后，真实页面验收必须覆盖智能搜索和结构化筛选；若宿主仍不识别导出，按组件宿主阻断处理，通知用户由 `app-platform` 修复后再继续，不能用页面内副本冒充组件库复用。
+
+## 创建、回填与更新
+
+只对页面计划选中的页面执行已有命令，下面以列表为例：
+
+```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`、`menuId`、类型与真实路径，回填 `shared/model.js`，重新组装到新的输出目录。发布前逐条比对导航路径和新页面映射，特别检查新增按钮没有指向旧 lowcode 表单。先回读远端当前 `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 保存成功才发送按列表路径区分的刷新事件，父列表保留筛选和分页并重新读取数据；取消不写入数据、不发送刷新。
+
+上述导航按实际页面组合改写：没有列表时移除“返回列表”和列表刷新依赖，返回计划内的真实入口，或留在当前独立页面显示保存结果；没有详情时更新不能返回详情。独立详情入口必须有明确的记录选择或参数来源，不能让用户直接面对缺少主键的错误。增加看板等入口时一并调整返回目标和需要刷新的页面。
+
+## 页面与浏览器验收
+
+在当前任务工作目录中预览迭代；页面目录中的 `preview.png` 是随 Skill 分发的效果参考。使用当前可用的浏览器能力，不要求安装桌面客户端、浏览器扩展或切换到外部浏览器。若没有浏览器能力，继续完成可执行的源码、构建和状态检查，清楚记录交互尚未验证；不能把命令成功当成浏览器验收通过。以下检查只应用于计划内能力；被裁剪的能力应检查其按钮、导航和写入调用已移除。
+
+- 同 Dataset 对比旧标准页的字段、分组、智能搜索、表单密度与操作位置；覆盖空数据、有数据、无匹配结果和超过一页的数据。
+- 查询、重置、翻页、页大小、勾选和列设置；自然语言查询必须读取真实结果，失败不冒充空结果。
+- 列表打开详情/新增/更新，主键正确；详情上一条/下一条和编辑仍在当前 ONEPAGE 面板。
+- 必填错误、零值、枚举和日期；保存、重置、取消、保存后返回刷新；连续新增清空表单并聚焦首字段，快捷键不重复提交。
+- 桌面及手机窄屏，列表和子页无溢出，底部按钮可访问；父列表保持筛选/分页。实际设备软键盘、深色主题等未覆盖项需明确记录。
+- 仅操作授权的测试数据，写入前保留原值，验收后还原修改并清理本轮测试记录。旧页面只用于对比，不作为新流程的运行依赖。
+
+本地模拟不能证明真实 SDK、权限或 ONEPAGE 宿主正确。按页面计划验证真实数据流后再发布；若正式态暴露问题，修复后重新验收。能力缺失造成的未验证项与明确的验收失败分别记录；用户若接受未验证范围并要求先发布，按该范围继续，仍不得声称完整验收通过。
+
+## 发布与结果回查
+
+对每个计划内 CustomJSX 页面，发布前先 `custom-detail` 核对类型、应用、保存内容和版本：
+
+- `status=FORMAL` 且有效的 `draftVersion === formalVersion`：当前保存内容已发布，跳过重复发布并检查运行页面；编辑器或本地尚未保存的改动不算已发布。
+- 有新草稿或首次发布：确认已保存内容对应本轮验收源码，再发布。不能只因 `status=FORMAL` 就忽略较新的草稿。
+- 版本缺失、异常、状态矛盾或远端内容与预期不一致：先回读并核对，不能把两个缺失版本当作相等，也不能覆盖他人的新改动或猜测已发布。
+
+```sh
+rabetbase page custom-detail --id <pageId> --appcode <appCode> --format compress
+# 仅在确有待发布内容且已完成前述检查时执行
+rabetbase page custom-publish --id <pageId> --appcode <appCode> --remark "页面验收通过" --format compress
+rabetbase page custom-detail --id <pageId> --appcode <appCode> --format compress
+```
+
+发布后逐页检查 `FORMAL`、正式版本是否等于本轮待发布版本、源码和运行地址。用返回的运行 URL 复验入口、子页跳转和菜单展示；命令成功、页面发布和业务交互验收是不同事实。网络超时、响应丢失或 500 时先回读状态，不立即重复发布。
+
+## 失败分类与恢复
+
+内部保留失败发生在哪一步、页面、时间、已脱敏错误及请求标识（若工具提供）。按证据选择恢复动作：
+
+| 观察到的事实 | 判断与下一步 |
+| --- | --- |
+| 正式版本已等于预期版本，源码相符 | 目标已发布，停止重复调用并检查运行页；不能据此断言先前 500 的原因就是重复发布。 |
+| 平台编译结果指出源码或组件/依赖错误 | 按构建错误修复，再保存和验证；组件处理遵循组件基线，不把构建失败说成没有数据。 |
+| 页面事实是 lowcode，或 ID/应用与计划不同 | 回到新旧映射选择正确页面及对应命令；不要将旧页面当成新页面重复创建或发布。 |
+| 鉴权、权限或 CLI 风险限制拒绝 | 保留成果，不绕过检查；只说明具体未完成操作和用户能采取的必要动作。 |
+| 页面发布成功，但菜单设置失败 | 分别回查页面和菜单，恢复未完成的菜单步骤；不能把页面称为未发布或把菜单称为已隐藏。 |
+| 只有 HTTP 500、超时或未知错误，回读也未能确定结果 | 原因待确认，保留证据，通过可用且授权的排障入口继续定位；不编造重复发布、组件缺失等根因，不循环重试。 |
+
+用户反馈用业务语言，例如“页面已经发布，可以直接打开”“页面已发布，但侧边栏还没调整完成”“这次发布没有完成，我正在检查原因”。只有确实存在未保存修改时才建议重新保存，不能把“重新保存再发布”当成所有错误的通用解决办法。
+
+## 内部记录与用户交付
+
+内部记录页面计划、新旧映射、页面与菜单标识、源码对应版本、发布结果、菜单实况，以及本轮验收的步骤、结果和未覆盖项。有可写任务目录时和源码一起保存，临时夹具和回执不加入 CLI 仓库或上传到业务页面；没有持久位置时保留在当前任务上下文，不要求用户提供存储目录，不保证任务结束后仍可取回。不记录凭据或完整业务数据，也不把旧回执当成新版本证据。
+
+向非技术用户只交付创建了哪些页面、用途、可直接打开的入口，以及旧页面处理建议和确需人工完成的事项。需要修改页面时提供工具返回的编辑链接，并与访问链接区分；不要自行拼接或沿用旧链接。详情等需要记录参数的页面优先通过入口访问，不把无参数错误页作为正常体验交付。默认不展示 pageId、menuId、接口、版本号、命令和本地验收文件路径；用户明确要求技术细节时再提供相关内容。
+
+CLI beta 发布遵循 CLI 发布流程；页面验收不等于 npm 发布成功。安装 CLI beta 及独立 Skill 后，确认执行方能够发现该 Skill，并按页面计划执行生成和端到端验收。

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

@@ -0,0 +1,48 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Assemble uploadable page directories from readable JSX source. The platform
+// micro-app template performs the actual JSX build when the page is saved or
+// published; this script must not upload a precompiled page.js bundle.
+const root = path.dirname(fileURLToPath(import.meta.url));
+const [output] = process.argv.slice(2);
+if (!output) throw Error("Usage: node build.mjs <output directory>");
+
+const destination = path.resolve(output);
+await mkdir(destination, { recursive: false });
+
+const sharedFiles = [
+  "model.js",
+  "record-layout.jsx",
+  "responsive.jsx",
+  "editor.jsx",
+  "page.css",
+];
+const pageKinds = ["list", "detail", "create", "update"];
+
+for (const kind of pageKinds) {
+  const pageRoot = path.join(destination, kind);
+  await mkdir(path.join(pageRoot, "src", "app"), { recursive: true });
+  await mkdir(path.join(pageRoot, "src", "shared"), { recursive: true });
+
+  const pageSource = await readFile(
+    path.join(root, kind, "index.jsx"),
+    "utf8",
+  );
+  await writeFile(
+    path.join(pageRoot, "src", "app", "index.jsx"),
+    pageSource,
+  );
+
+  for (const file of sharedFiles) {
+    await writeFile(
+      path.join(pageRoot, "src", "shared", file),
+      await readFile(path.join(root, "shared", file)),
+    );
+  }
+}
+
+console.log(
+  `Assembled four readable 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)；应整体构建四页，而不是单独上传本目录。