@lovrabet/rabetbase-cli 2.5.0 → 2.5.1-beta.2

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

@@ -0,0 +1,92 @@
+# rabetbase deployment sync
+
+将当前应用中指定数据库连接下的少量研发元数据同步到独立部署目标。命令只同步显式给出的业务编码，支持 `dataset`、`bff`、`sql`。
+
+## 使用前确认
+
+- 已完成 rabetbase 认证，并明确目标应用的 `appCode`。
+- 从可信事实中取得基础 dblink／环境连接组 ID 和业务编码，不猜测 ID 或编码。
+- `--target-env` 只选择服务端维护的环境连接映射；CLI 不保存数据库 URL、账号、密码或环境到连接 ID 的映射。
+- 服务端同步接口会检查目标 appCode 的一键部署开关；未开启时正常跳过，不属于异常或无权限。
+- 同一批最多 100 个编码；需要分批时逐批确认结果，不并发执行。
+
+## 先预览
+
+环境部署：
+
+```sh
+rabetbase deployment sync \
+  --appcode <appCode> \
+  --db-id <dbLinkId> \
+  --target-env test \
+  --type dataset \
+  --codes <code1,code2> \
+  --dry-run \
+  --format compress
+```
+
+直连部署：
+
+```sh
+rabetbase deployment sync \
+  --appcode <appCode> \
+  --db-id <dbLinkId> \
+  --direct \
+  --type bff \
+  --codes <code1> \
+  --dry-run \
+  --format compress
+```
+
+检查输出中的 `data.selector.targetMode`、`data.selector.targetEnv`、`data.selector.bizType`、`data.selector.bizCodes` 和 `data.selector.dbLinkId`。dry-run 不发起同步请求。
+
+## 正式执行
+
+复用已审阅的参数，移除 `--dry-run` 并追加 `--confirm`。CI 或非交互环境还需要全局 `--yes`：
+
+```sh
+rabetbase deployment sync \
+  --appcode <appCode> \
+  --db-id <dbLinkId> \
+  --target-env test \
+  --type dataset \
+  --codes <code1,code2> \
+  --confirm \
+  --yes \
+  --format compress
+```
+
+## 参数约束
+
+- `--db-id`：正整数基础 dblink／环境连接组 ID；不是某个环境的最终连接 ID。
+- `--target-env dev|test|pre|prod`：服务端环境连接映射选择器；与 `--direct` 必须且只能选择一个。
+- `--type dataset|bff|sql`：同步资源类型。
+- `--codes`：逗号分隔；命令 trim、过滤空项并按首次出现顺序去重，最多 100 个。
+- 全局 `--env production|daily` 只决定 CLI 服务域，不是部署目标；不要用它替代 `--target-env`。
+
+## 结果与失败处理
+
+- 退出码 `0`：服务端没有返回 `FAILED`；`SKIPPED`、`UNCHANGED` 等 no-op action 或空 items 均表示无需执行，不作为异常。
+- 退出码 `1`：至少一个条目为 `FAILED`。读取结构化输出的 `data.items[]`，保留成功项和失败项的完整事实，不要把整批误报为失败或成功，也不要自动重提整批。
+- 退出码 `2`：写请求响应丢失或响应无法证明结果。同步可能已经生效；先人工核对目标部署，再决定是否处理未完成项，禁止直接重试。
+
+Dataset 同步会先确保目标数据库连接存在，再逐项同步 Dataset，不是跨资源原子事务。命令当前不提供目标端只读回查；部署后的业务可用性仍需单独验收。
+
+## 日常 BFF / SQL push 自动同步
+
+只有用户明确要求将日常开发变更持续同步到独立部署测试环境时，才写入 app profile：
+
+```sh
+rabetbase workspace use --app <appName> --appcode <appCode> \
+  --deployment-db-id <dbLinkId> --deployment-target-env dev
+```
+
+- 自动目标仅允许 `dev`、`test`、`pre`；生产和直连仍用显式命令并要求确认。
+- 每个 app profile 只保存一个明确的自动目标，不根据 Git 分支、CLI 服务域或登录状态推断环境。
+- 存在实际变更且主 push 成功后调用一次同步接口，由服务端检查 appCode 开关并按 `(dbLinkId, targetEnv)` 解析真实连接；未开启时正常 no-op，环境映射缺失则是配置错误。
+- `bff push` 只同步本次上传成功且完成缓存清理的 function name。
+- `sql push` 只同步本次 pushed sqlCode；未变化项不触发同步。
+- Dataset 没有统一 push 入口，暂不自动同步。
+- dry-run 展示配置目标和精确 code，但不发请求。
+- 主 push 成功但后置同步失败时，不声称回滚主操作；只有同步请求已提交后才按 `data.deploymentSync.recoveryCommand` 人工处理。
+- `partial_failure`、`failed`、`outcome_unknown` 均不得自动重试。

package/skills/rabetbase/references/rabetbase-init.md

@@ -19,21 +19,23 @@ rabetbase config init \
   --runtime-domain https://runtime.customer.example.com \
   --skill-domain https://skills.customer.example.com \
   --kb-domain https://kb.customer.example.com \
-  --app-domain https://app.customer.example.com
+  --app-domain https://app.customer.example.com \
+  --local-domain https://local.customer.example.com \
+  --certificate-domain https://cert.customer.example.com
 ```
 
 ## 交互与默认行为
 
 - 交互执行时选择 `Mainland China (cn)` 或 `Indonesia (id)`，默认选中 `cn`
 - 非交互执行时应显式传 `--region cn|id`；未传 region/Domain 时回退 `cn`
-- 当前只开放 `cn`、`id`；`global` 不可选择
+- 当前只开放 `cn`、`id`；尚未发布的 `global` 不可选择
 
 ## 写入行为
 
 - 固定写入全局 `~/.rabetbase.json`
 - 不使用也不需要 `--global`，不能写入项目配置
 - 默认中国节点 `cn` 不写冗余 `region` 字段
-- 官方节点模式会清除六个显式 Domain，以及遗留的 `agentDomain` / `platformDomain` / `skillHubDomain`
+- 官方节点模式会清除所有显式 Domain，以及遗留的 `agentDomain` / `platformDomain` / `skillHubDomain`
 - 独立部署模式会清除旧 `region`、显式 Domain 和遗留 Domain，再写入本次提供的 Domain
 - 保留 Cookie、AccessKey、format、locale、apps 等无关配置
 - 不负责登录，也不绑定当前项目应用
@@ -49,12 +51,16 @@ rabetbase config init \
   "runtimeDomain": "https://runtime.customer.example.com",
   "skillDomain": "https://skills.customer.example.com",
   "kbDomain": "https://kb.customer.example.com",
-  "appDomain": "https://app.customer.example.com"
+  "appDomain": "https://app.customer.example.com",
+  "localDomain": "https://local.customer.example.com",
+  "certificateDomain": "https://cert.customer.example.com"
 }
 ```
 
 - 每个值必须是 HTTPS origin，不能包含账号、密码、path、query 或 fragment
-- 文件至少提供一个受支持 Domain；企业完整独立部署建议显式提供全部六个
+- 文件至少提供一个受支持 Domain；完整独立部署应提供实际由客户部署的全部服务 Domain
+- 当前所有官方节点和独立部署统一使用中国大陆 CDN 配置；User/App/Runtime 等 Lovrabet 服务 Domain 仍按节点或客户配置分别解析
+- 未提供 `localDomain` / `certificateDomain` 时，本地回调使用 `http://localhost`；自定义 HTTPS 本地回调时两者必须同时提供
 - 同名 `--*-domain` flag 覆盖文件中的值
 - `--region` 与任意独立部署 Domain 互斥，不能混用
 - 未提供的 Domain 会按默认 `cn` 映射回退，因此完整独立部署不要遗漏实际由客户部署的服务入口

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

@@ -42,15 +42,16 @@ rabetbase project create my-project --appcode <code> --env production
 - 交互与非交互模式使用同一创建流程，都会安装依赖、格式化代码并写入项目配置
 - 项目模板从 CDN 下载并校验 SHA-256；CDN 不可用、模板不兼容或校验失败时命令停止，修复后重试
 - 新项目中的 `.rabetbase.json` **只继承**全局中的少量偏好及 `region` / Domain 路由配置，**不会**把全局的 `apps` / `defaultApp` 复制进新项目
-- `src/api/sdk-config.ts` 只生成浏览器可公开的非默认 SDK 路由，不会写入 `cookie`、`accessKey` 等认证配置；后续执行 `rabetbase api pull` 会按当前有效配置刷新该文件。`api.ts` / `client.ts` 仅在缺失时由 CLI 写脚手架，已有文件按 [`sdk-client-generation.md`](../guides/sdk-client-generation.md) 更新
+- `src/api/sdk-config.ts` 与 `rabetbase.routing.json` 只生成浏览器可公开的最终路由，不会写入 `cookie`、`accessKey` 等认证配置；后续执行 `rabetbase api pull` 会按当前有效配置刷新。`api.ts` / `client.ts` 仅在缺失时由 CLI 写脚手架，已有文件按 [`sdk-client-generation.md`](../guides/sdk-client-generation.md) 更新
 
 | 当前有效路由 | `src/api/sdk-config.ts` |
 |--------------|-------------------------|
-| 默认 CN，且没有非默认 `runtimeDomain` | `{}`，由 SDK 使用默认 CN 映射 |
-| ID，且没有非默认 `runtimeDomain` | `{ region: "id" }`，由 SDK 结合项目 env 选择 ID Runtime |
-| 非默认企业 `runtimeDomain` | `{ runtimeDomain: "https://…" }`，不再冗余写 region |
+| 默认中国大陆节点 | `{}`，由 SDK 使用默认映射 |
+| ID | `{ region: "id" }`，由 SDK 1.5.3+ 选择 ID Runtime |
+| Global | `{ runtimeDomain: "https://runtime.lovrabet.ai" }`，兼容 SDK 1.5.3 |
+| 独立部署 | `{ runtimeDomain: "https://…" }` |
 
-如果显式 `runtimeDomain` 恰好等于当前 region/env 的 SDK 内置地址，CLI 会把它视为默认值：CN 不写路由，ID 仍只写 `region: "id"`。这样生成项目不会固定当前的具体公共 URL，后续仍可跟随 SDK 的内置映射升级。
+模板依赖 SDK 1.5.3+。CLI 从统一 Routing Profile 生成 `rabetbase.routing.json`，其中只包含最终 User/App/Runtime Domain、资源策略、本地地址和证书 URL，不复制节点注册表。当前所有官方节点和独立部署统一使用中国大陆 CDN 配置，Lovrabet 服务 Domain 仍分别解析。后续执行 `rabetbase api pull` 会刷新两个路由文件。
 
 ## 参考
 

package/skills/rabetbase.manifest.json

@@ -2,8 +2,8 @@
   "schemaVersion": 1,
   "name": "rabetbase",
   "packageName": "@lovrabet/rabetbase-cli",
-  "packageVersion": "2.5.0",
-  "skillVersion": "2.5.0",
+  "packageVersion": "2.5.1-beta.2",
+  "skillVersion": "2.5.1-beta.2",
   "files": [
     "SKILL.md",
     "guides/backend-function.md",
@@ -59,6 +59,7 @@
     "references/rabetbase-dataset-delete.md",
     "references/rabetbase-dataset-detail.md",
     "references/rabetbase-dataset-extend-update.md",
+    "references/rabetbase-dataset-field-restore.md",
     "references/rabetbase-dataset-field-update.md",
     "references/rabetbase-dataset-generate.md",
     "references/rabetbase-dataset-list.md",
@@ -68,6 +69,7 @@
     "references/rabetbase-dataset-relations.md",
     "references/rabetbase-dataset-rename.md",
     "references/rabetbase-dataset-restore.md",
+    "references/rabetbase-dataset-user-deleted-field-list.md",
     "references/rabetbase-db-analyze.md",
     "references/rabetbase-db-create.md",
     "references/rabetbase-db-delete.md",
@@ -78,6 +80,7 @@
     "references/rabetbase-db-tables.md",
     "references/rabetbase-db-test.md",
     "references/rabetbase-db-update.md",
+    "references/rabetbase-deployment-sync.md",
     "references/rabetbase-doctor.md",
     "references/rabetbase-file.md",
     "references/rabetbase-init.md",
@@ -132,5 +135,5 @@
     "references/rabetbase-user-account.md",
     "references/rabetbase-workspace.md"
   ],
-  "digest": "dca9ab8c944c37266a62b08c870f666f5a3646bcc01098f2750f9b318456a477"
+  "digest": "11bce5b48dd571defc4c17a16fe89045ec5d55e8988f91220676c8bcb3efd2c0"
 }

package/templates/README.md

@@ -9,7 +9,7 @@ templates/
 ├── README.md           # 本说明文档
 ├── generate-api/       # API 生成模板
 └── projects/           # 项目模板，用于 `rabetbase project create` 命令
-    └── sub-app-react-demo/  # React 微前端项目模板快照
+    └── sub-app-react-demo/  # React 微前端项目模板真源
 ```
 
 ## API 生成模板
@@ -18,33 +18,29 @@ templates/
 
 ## 项目模板
 
-### 远程模板同步
+### 模板真源与 CDN 资产
 
-`projects/sub-app-react-demo/` 目录是从模板真源仓同步来的 CDN 构建源：
-**仓库地址**: https://github.com/lovrabet/sub-app-react-demo
+`projects/sub-app-react-demo/` 是 Rabetbase React 项目的仓内模板真源，也是 CDN ZIP 的唯一构建输入。
+模板能力最终沉淀到该目录；不维护额外的外部 `sub-app-react-demo` 真源或同步链路。
 
-#### 开发者：同步模板
+#### 开发者：维护与验证模板
 
-更新项目模板到最新版本：
+需要新增页面、组件或示例能力时，先从当前正式模板创建一个临时实例：
 
 ```bash
-npm run sync-template
+npm run build:dev
+node lib/cli.js project create template-test --template-source templates/projects/sub-app-react-demo
 ```
 
-在提交、推送和生成 CDN ZIP 前，可先把本地工作区（包含未提交修改）转换到独立目录：
+在实例中完成开发、运行和构建验证后，明确告诉 AI 要沉淀的页面、组件、样式、依赖或配置范围。AI 仅提取这些经过确认的变更，过滤具体 AppCode、应用模型、认证信息、项目路由和本地状态，再合入正式模板。
 
-```bash
-npm run sync-template -- --source ../sub-app-react-demo --output /tmp/sub-app-react-template
-```
-
-再使用已经准备好的模板创建调试项目：
+正式模板更新后，必须重新创建一个干净实例复验，不能把原开发实例整体覆盖回模板：
 
 ```bash
-node lib/cli.js project create template-test --template-source /tmp/sub-app-react-template
+node lib/cli.js project create template-verify --template-source templates/projects/sub-app-react-demo
 ```
 
-`sync-template` 负责“原始项目 → 标准模板”，`project create --template-source` 负责
-“标准模板 → 新项目”，并保留普通创建的认证、AppCode、依赖安装和格式化流程。
+`project create --template-source` 保留普通创建的认证、AppCode、依赖安装、格式化和项目配置流程。
 使用尚未发布的 CLI 时，先执行 `npm run build:dev`；
 使用已安装版本时，可把第二条命令换成 `rabetbase project create ...`。
 
@@ -78,7 +74,7 @@ npm run sync:cdn
 
 ## 注意事项
 
-- `templates/projects/sub-app-react-demo/` 是项目模板快照，不是独立 Git 仓
+- `templates/projects/sub-app-react-demo/` 是项目模板真源，不是独立 Git 仓，也不是外部仓快照
 - `rabetbase project create` 从 CDN 下载 ZIP，然后更新 `package.json` 与 `.rabetbase.json`；此仓库模板不进入 npm 发布包
 - 模板文件名必须兼容 Windows、macOS 和 Linux；禁止符号链接、大小写冲突路径和 Windows 保留名称
 - 有 AppCode 时，CLI 会重新生成 `src/api/api.ts` 和 `src/api/client.ts`