@lovrabet/rabetbase-cli 2.5.3-beta.3 → 2.5.3

package/skills/rabetbase/guides/backend-function.md

@@ -830,6 +830,8 @@ rabetbase notification config-list --type EMAIL --format compress
 
 ## 事务规则
 
+事务原子性只适用于已核验的运行时事务范围。跨连接模型操作或外部 API 不因位于同一个回调就成为原子操作；分库读取也不能假定共享一致性快照。涉及这些场景时，按 [跨库 BFF 查询与拼接](cross-database-bff.md)确认授权、一致性与写入边界。
+
 事务使用方式：
 
 ```javascript
@@ -860,6 +862,8 @@ await context.client.db.transaction(async (tx) => {
 
 编写 Backend Function 前，必须阅读 `data-api-guidelines.md` 中的性能优化部分。
 
+跨库关联须先区分展示补充与参与筛选、排序、统计的关联，执行顺序见 [跨库 BFF 查询与拼接](cross-database-bff.md)。批量调用仍需处理分页完整性和重复匹配；不能用单次 `$in` 或当前页拼接代替完整结果。
+
 重点避免：
 
 * 循环查询单条
@@ -868,7 +872,7 @@ await context.client.db.transaction(async (tx) => {
 
 性能要求：
 
-* 单次脚本数据库调用尽量控制在 `50` 次以内
+* 按接口限制与业务预算设定调用次数、读取量和超时上限；超限时明确报告，不能截断并冒充完整结果
 * 可批量查询时，用 `filter + $in`
 * 同一数据集批量新增优先使用 `batchCreate()`；相同字段值的批量更新优先使用 `update({ id: [...] })`
 * 只有 Instant API 无法表达的复杂写入才考虑已有且契约可信的 Custom SQL

package/skills/rabetbase/guides/bff-creation-workflow.md

@@ -41,7 +41,9 @@ rabetbase dataset detail --code <数据集编码> --format compress \
 写入前必须确认：
 * 业务必填字段：`data.fields[].required === true`，平台自动维护字段除外
 * 枚举/选择字段：写入 `options[].value`，不要写展示用 `label`
-* 外键字段：从 `data.relations[]` 或 `dataset relations` 确认真实关系
+* 外键字段：同库关系从 `data.relations[]` 或 `dataset relations` 确认；跨库关系使用 `dataset cross-relation-list`，不能用同库关系列表代替
+
+涉及跨连接读取或拼接时，先读 [跨库 BFF 查询与拼接](cross-database-bff.md)，确认完整键、基数、目标字段用途、各端授权和读取预算。业务关系说明与平台登记事实分别核对；冲突时报告差异，不能自动采用平台关系。复合键不能拆成独立的单字段 Relation。
 
 ### 3. 查平台（按需）
 * 新建 → 跳过

package/skills/rabetbase/guides/cross-database-bff.md

@@ -0,0 +1,70 @@
+# 跨库 Backend Function 查询与拼接
+
+用于编写或审查跨数据库连接的 BFF 查询：分别读取各数据源，在可信 BFF 中按完整关联键拼接，再输出业务结果。单表优先使用 InstantAPI；同一连接内的关联或聚合可使用已确认支持的关联查询或 Custom SQL。跨库 Relation 描述逻辑关联，不赋予自动 JOIN、访问授权或分布式事务能力。
+
+本文同库／跨库按平台数据库连接区分；不同 dblink 不因库名或表名相同而视为同库。默认关联关系指同库关联关系。
+
+## 先确认事实和业务合同
+
+1. 用 `rabetbase dataset detail --code <datasetCode> --format compress` 核对两端字段、类型、物理表和连接；模型访问方式遵循 [Backend Function](backend-function.md)，同名表必须消歧。连接身份以当前应用的真实 dblink 为准，不靠库名或表名推断。
+2. 用 [跨库关系命令](../references/rabetbase-dataset-cross-relations.md)的 `cross-relation-list` 查询平台已登记关系。业务文档中的关系说明不代表已经登记；平台配置也不能代替业务正确性确认。两者冲突时报告端点差异，由业务确认后再维护关系，不能自动照搬或修正。
+3. 在业务项目明确：完整关联键及顺序、基数、允许缺失与否、目标字段用途（展示、筛选、排序、统计）、各端访问范围、返回字段，以及读取预算和失败处理。具体映射留在业务项目，详细元数据按需查询；不在通用 Skill 中保存项目关系清单或元数据快照。
+
+依据按需查找：先读已有接口文档和当前元数据，确认调用能力与硬限制；再读项目业务合同和现有配置，确定关联语义、授权及读取预算。已有事实充分时直接采用，不重复要求用户确认。依据冲突或缺少影响正确性、授权、完整性的必要信息时，说明具体缺口后确认；不自行发明权限字段、运行时上限或项目级配置。
+
+当前 `cross-relation-create/update/delete` 每端只接收一个字段。复合键必须作为有序字段组整体理解，不能拆成多条单字段 Relation，也不能用逗号拼接字段来冒充复合关系支持。BFF 可依据已确认的业务合同实现完整键匹配，但不得宣称该复合关系已由这些命令登记。
+
+## 根据查询语义选择执行顺序
+
+| 外表的用途 | 执行方式 | 结果要求 |
+|---|---|---|
+| 仅补充展示字段 | 先对已授权主表筛选、稳定排序、计数和分页，再批量读取当前页所需外表数据 | 保留主记录、主表顺序和总数；一对多用约定的集合承载，不能展开后仍沿用原分页含义 |
+| 参与筛选 | 先分析完整筛选表达式；能够等价转成目标键条件时，在预算内完整取得所需键集合，再保留原布尔逻辑筛选、计数和分页主表 | 主表 total 对应最终筛选结果；不能等价表达时报告能力边界 |
+| 参与排序或统计 | 先确认能够覆盖完整相关结果集的执行方案 | 当前页拼接后的排序或统计不能冒充全局结果；预算不足时请求调整范围或由权威查询服务承接 |
+
+正向匹配可在确认等价后使用引用键 `IN` 条件。否定、无关联、空引用，以及主表条件与外表条件混合的 `OR` 必须分别保留语义，不能统一改成正向 `IN`。例如“主记录紧急 OR 目标启用”转换后仍须保留主记录紧急分支；“没有关联目标”不能用任意目标字段筛选的补集代替。授权过滤始终限制整个结果集，不能被业务 `OR` 绕过。
+
+不同连接分别读取，不用跨库 SQL JOIN、跨库子查询或视图绕过执行边界，也不把整个外库拉进 BFF。关系存在和 `sql validate` 通过都不能证明跨连接查询可执行。各库支持的过滤、投影、聚合可在所属库内完成；没有可验证的完整方案时停止，不能返回貌似完整的部分结果。
+
+## 完整键、批量读取与拼接
+
+以下步骤描述为已选定主记录补充展示字段的流程。参与筛选、排序或统计时先按上表确定读取顺序，再复用完整键与批量处理规则；不能把主表先分页当作所有跨库查询的前置步骤。
+
+1. 从已授权主记录提取有效引用键。空值定义遵循字段合同，不用真值过滤误删合法的 `0`；复合键任一必需部分缺失时按缺失关系处理。
+2. 保留 ID 精度及类型语义，不把大整数 ID 转成 `Number`。只有两端合同明确同一标识的不同编码方式时才做无损归一化；不擅自忽略大小写、前导零或空白。
+3. 对完整键去重并按字段值比较。复合键保留字段顺序和类型，使用嵌套 `Map` 或明确的无损键编码，避免分隔符拼接碰撞；不能直接用新建数组作为 `Map` 查询键，因为数组按对象身份而非内容比较。例如期望 `(A, 7)`、`(B, 9)` 时，`region IN (A,B) AND external_id IN (7,9)` 会额外选中 `(A,9)`、`(B,7)`；应使用配对条件，或按第一个键分组后查询对应第二键集合，最终仍按完整键匹配。更多字段同样逐一配对，不省略剩余字段；示例字段不替代真实字段合同。
+4. 键集合为空时跳过外表查询。非空时按目标接口的参数、分页和数量限制分批查询，投影只包含拼接和已授权输出所需字段。分批大小、最大页数、总读取量、并发和超时依据接口合同及业务预算确定，不复制其他项目的固定数值。
+5. 每批都按该接口的分页合同读取完整结果，再建立映射。已知仍有后续结果却只拿到一页、完成前达到预算上限、页码不推进或查询失败时，默认返回错误，不推断剩余键均不存在。分批循环用于有界读取，不退回逐条记录的 N+1 调用。
+6. 按已确认基数组装。1:1 或 N:1 的同一完整目标键出现多条记录时，报告重复匹配，不能用 `Map.set`、`Object.fromEntries` 或“取第一条”静默覆盖。一对多或多对多按合同保留集合，输出顺序须明确。
+
+区分以下结果，不用 `catch(() => [])` 将错误伪装为空数据：
+
+默认接口成功表示所需数据已完整读取。只有已有接口合同明确支持部分结果时，才使用其既定状态与字段输出；不能临时新增 `partial` 字段就返回成功，也不能把未完成计算的 `total`、排序或统计描述为准确结果。
+
+| 情况 | 处理 |
+|---|---|
+| 完整查询成功，允许缺失的展示关系未匹配 | 保留主记录；单目标返回 `null`，多目标集合按业务合同返回 |
+| 必需关系缺失或唯一关系重复匹配 | 按业务合同返回错误；不猜测替代记录 |
+| 权限不足或查询失败 | 返回错误，不能解释为“目标不存在” |
+| 分页结果不完整 | 默认返回错误；已有部分结果合同按上文处理，不能推断未读结果 |
+
+## 授权与数据所有权
+
+- BFF 从可信身份或已核验的服务端访问上下文确定权限。客户端提供的业务筛选值不能扩大授权范围；子记录需要沿已确认的父关系核验归属。
+- 每个数据源分别落实访问控制。不能把主库的租户字段、门店字段、软删除字段或状态枚举机械套到目标表；关联键本身不是访问凭证，已取得的目标 ID 也不等于有权读取它。
+- 核对 BFF 内部模型、SQL 或外部 API 的实际调用通道，不假设它必然经过 Dataset HTTP Hook。缺少授权合同则停止；复用公共授权函数前确认其输入、可信上下文和覆盖范围。
+- 查询投影和返回值使用已授权字段白名单，敏感字段不得通过拼接结果、错误、日志或参数回显泄漏。保留业务字段的精度和空值语义，不为展示默认补零或改变标识符类型。
+- 读写通道由数据所有权和接口合同决定。某个项目的外库只读、指定 OpenAPI 写入规则不能推广为所有外库的统一策略；确认关系或具备读取能力均不构成写入授权。
+
+## 一致性与写入边界
+
+分库读取不共享已证明的一致性快照。数据可能在两次读取之间变化；拼接结果不能作为库存、结算等关键写入的最终依据，关键校验应由权威写入服务在其一致性边界内完成。
+
+`context.client.db.transaction` 的原子性仅按已核验的运行时事务范围理解，不能通过把调用放进同一个回调就承诺跨连接或外部 API 原子性。涉及多系统写入时先明确操作顺序、幂等、部分成功与补偿合同；状态未知时先核对，不盲目重试或自动补偿。事务 API 用法见 [Backend Function 事务规则](backend-function.md#事务规则)。
+
+## 交付检查
+
+- 两端连接、完整键、基数、权限、投影和读取预算都有明确依据；历史关系和同名字段没有被自动当成有效关系。
+- 覆盖空键、复合键交叉组合与按值查找、重复匹配、允许/必需关系缺失、多页结果、读取中断及预算不足。
+- 展示补充保留主表分页含义；关联筛选包含正向、否定、无关联和混合 OR 的反例，全局排序和统计不会用当前页结果替代完整结果。
+- 用不同身份验证各端数据范围和字段输出；需要真实业务行数据或 BFF 执行验证时，按 [BFF 工作流](bff-creation-workflow.md)显式交接运行态验证。关系配置回读和 `bff push` 成功不能替代该验证。

package/skills/rabetbase/guides/data-api-guidelines.md

@@ -14,7 +14,7 @@
 | **分析主外键关系** | 理解表间关联，正确处理下拉框数据 |
 | **使用真实接口** | 不使用 mock 数据，直接调用数据集接口 |
 | **避免循环访问** | 批量查询替代循环单个查询 |
-| **性能优先** | 单次接口调用次数 < 50 次 |
+| **有界读取** | 按接口限制与业务预算设定调用和读取上限；超限不能截断结果并冒充完整数据 |
 
 ---
 
@@ -31,7 +31,7 @@
 
 **CLI 信封、`data.*` 键位、平台 `get-driven-data` 与 CLI 归一化对照**：单一权威见 [`references/rabetbase-dataset-detail.md`](../references/rabetbase-dataset-detail.md)。
 
-**不要复制示例字段名。** 本指南里的表名、字段名、枚举值只用于说明形态；真实代码必须从当前项目的 `rabetbase dataset detail` 输出中取 `data.fields[]`、`data.relations[]` 和 `data.dbtable`。
+**不要复制示例字段名。** 本指南里的表名、字段名、枚举值只用于说明形态；真实代码的字段与连接事实来自当前项目的 `rabetbase dataset detail` 输出。同库关系读取 `data.relations[]`，跨库登记事实单独使用 `dataset cross-relation-list` 核对。
 
 ---
 
@@ -56,7 +56,10 @@
 | 聚合列名 | `aggregate[].column` | SDK aggregate 定义使用 `column`，不要写旧别名 `field` |
 | 必填字段 | `data.fields[].required` | `true` 表示创建/写入时需处理，平台自动维护字段除外 |
 | 枚举/选择值 | `data.fields[].options[].value` | 写入持久化 `value`，不要写展示用的 `label` |
-| 外键关系 | `data.relations[]` / `dataset relations` | 只有确认存在关系后才写关联查询或校验 |
+| 同库关系 | `data.relations[]` / `dataset relations` | 确认端点、基数和查询能力，不按同名字段推断关系 |
+| 跨库登记关系 | `dataset cross-relation-list` | 与业务合同分别核对，不用同库关系列表替代 |
+
+复合键 BFF 可依据已确认的业务合同和两端字段事实实现，不要求先拆成单字段 Relation；平台登记关系不等于执行能力。完整键、查询顺序和授权边界见 [跨库 BFF 查询与拼接](cross-database-bff.md)。
 
 常用投影：
 
@@ -271,7 +274,7 @@ const result = await models[TABLES.primary].filter({
 
 ### 场景识别
 
-代码中出现**循环内调用接口**时，必须优化：
+代码中出现**按主记录逐条调用接口的 N+1 查询**时，必须优化；按接口合同执行的有界分批和分页循环属于批量读取：
 
 ```tsx
 // ❌ 性能灾难：N 次接口调用
@@ -283,22 +286,22 @@ for (const row of rows) {
 ### 优化方案选择
 
 ```
-循环访问接口（N 次调用）
+循环逐条访问接口（N 次调用）
+    │
+    ├─ 不同数据库连接 → BFF 分库批量读取，按完整键拼接
     │
-    ├─ 关联类型是 1:1 或 N:1？
-    │   │
-    │   ├─ 是 → 使用 filter 多表关联查询（推荐）
-    │   │        一次查询，自动 JOIN
-    │   │
-    │   └─ 否 → 使用批量查询（$in）
-    │        一次查询，手动映射
+    └─ 同一连接
+        ├─ 1:1/N:1 且已确认支持关联查询 → filter 多表关联查询
+        └─ 其他场景 → 有界批量查询，或已确认支持的库内 Custom SQL
 ```
 
+先核对数据源及查询能力，再选择方案；基数或平台存在 Relation 不能单独证明可自动 JOIN。跨库场景必须阅读 [跨库 BFF 查询与拼接](cross-database-bff.md)，分别处理展示补充、关联筛选、全局排序和统计。
+
 ### 方案 1：多表关联查询（推荐）
 
 <span style={{fontSize: '0.9em', color: '#888'}}>v1.2.0+</span>
 
-**适用于**：1:1 或 N:1 关联（主记录→关联记录、成员→组织等）
+**适用于**：同一数据库连接内、已确认支持关联查询的 1:1 或 N:1 关系（主记录→关联记录、成员→组织等）。以下示例不能用于推断跨连接 JOIN 能力。
 
 ```tsx
 // ✅ 一次查询，自动 JOIN
@@ -319,28 +322,27 @@ const result = await client.models.primary.filter({
 
 ### 方案 2：批量查询
 
-**适用于**：复杂场景或不支持多表关联时
+**适用于**：不支持多表关联或需要分开读取时；跨库拼接在可信 BFF 中完成。
 
-```tsx
-// ✅ 一次查询，$in 批量获取
-const relatedIds = [...new Set(rows.map(row => row.related_id))];
-const relatedRows = await client.models.related.filter({
-  where: { id: { $in: relatedIds } },
-  select: ['id', 'name']
-});
-const relatedMap = Object.fromEntries(
-  relatedRows.tableData?.map(row => [row.id, row.name]) || []
-);
-rows.forEach(row => row.relatedName = relatedMap[row.related_id]);
-```
+以下步骤用于向已选定主记录补充展示字段。外表参与筛选、排序或统计时，先按 [跨库 BFF 查询与拼接](cross-database-bff.md)确定完整查询顺序，不能先取主表当前页后套用本流程。
+
+1. 从已授权主记录提取有效完整键并去重；空键集合跳过查询，合法的 `0` 不用真值过滤排除。
+2. 单字段键可用 `$in` 批量过滤；复合键保留字段配对，不能用两个独立 `$in` 替代联合条件。
+3. 按目标接口限制分批并读取所有匹配页，只取拼接和输出必需的已授权字段。批量查询不保证一次调用返回完整数据；结果不完整或请求失败时默认返回错误。部分结果只按已有接口合同输出，规则见 [跨库 BFF 查询与拼接](cross-database-bff.md)。
+4. 完整结果按完整键和基数组装；单目标关系出现重复键时报告冲突，一对多按合同收集为集合，不能静默覆盖。
+5. 只有完整查询成功才判断未匹配；允许缺失的单目标展示关系保留主记录并返回 `null`，必需关系缺失按业务合同失败。
+
+具体执行顺序、复合键示例与失败语义见 [跨库 BFF 查询与拼接](cross-database-bff.md)。
 
 ### 性能对比
 
-| 方案 | 调用次数 | 耗时 |
-|------|---------|------|
-| 循环单条（100 条） | 100 次 | ~10 秒 |
-| 多表关联 | 1 次 | ~0.1 秒 |
-| 批量查询 | 1 次 | ~0.1 秒 |
+| 方案 | 调用量取决于 | 使用前提 |
+|------|-------------|----------|
+| 循环单条 | 主记录数量 | 容易产生 N+1，应优先批量化 |
+| 库内关联 | 接口分页与查询计划 | 同连接且查询能力已确认 |
+| 批量查询 | 去重键数量、批次和匹配结果页数 | 完整读取并在预算内组装 |
+
+调用次数不能直接换算为固定耗时；按真实查询计划、数据量和接口限制验证。
 
 ---
 
@@ -381,7 +383,7 @@ await context.client.sql.execute({
 - [ ] **外键字段已识别**：下拉框数据来自关联数据集接口
 - [ ] **枚举字段已处理**：展示使用 `options[].label`，写入使用 `options[].value`
 - [ ] **未使用 mock 数据**：所有下拉框数据来自真实接口
-- [ ] **无循环访问**：优先使用多表关联查询，或使用批量查询
+- [ ] **避免 N+1**：同连接且能力已确认时使用多表关联；跨连接交由 BFF 有界批量读取
 - [ ] **字段名正确**：使用 `data.fields[].name`（列名），区分大小写，与数据集定义一致
 - [ ] **系统字段已识别**：结合 `data.dbtable` 与 `backend-function.md`，创建/更新时间等按平台约定不传
 - [ ] **关联表使用表名**：多表关联时使用 `tableName.fieldName` 格式
@@ -394,7 +396,7 @@ await context.client.sql.execute({
 - [ ] **枚举字段写入正确**：写入 `options[].value`，不是展示 `label`
 - [ ] **外键校验已处理**：创建/更新前校验外键有效性
 - [ ] **系统字段未设置**：主键自增、系统时间等按平台约定不手工传入，详见 `backend-function.md`
-- [ ] **无循环访问**：使用 filter + $in 批量查询
+- [ ] **批量读取完整**：按完整键去重、分批和分页；查询失败、不完整或唯一关系重复匹配均明确报告
 - [ ] **批量操作已优化**：大量数据操作使用自定义 SQL
 
 ### SQL 开发

package/skills/rabetbase/guides/sql-creation-workflow.md

@@ -27,6 +27,8 @@ SQL 内容编写、参数绑定与 MyBatis 语法以 [`sql-mybatis.md`](sql-myba
 ### 3. 校验字段
 执行 `rabetbase dataset detail --code <数据集编码> --format json` 确认表名、字段名、字段类型。禁止凭经验猜。
 
+同时核对各表所属连接与该 SQL 的执行连接；同名表须按真实连接消歧。不同连接的逻辑关联由 [跨库 BFF 查询与拼接](cross-database-bff.md)编排分库读取，不能用跨库 JOIN、子查询或视图绕过边界。`sql validate` 的静态检查不证明跨连接可执行、权限完整或全局结果正确。
+
 ### 4. 先把 SQL 拉/落到同步目录
 
 #### 修改已有 SQL

package/skills/rabetbase/references/rabetbase-dataset-cross-relations.md

@@ -1,6 +1,8 @@
 # 跨库数据集关系
 
-使用 `dataset cross-relation-list/create/update/delete` 管理同一应用内、不同数据库连接的 DB_TABLE 逻辑关联。普通关系命令见 [数据集关系](rabetbase-dataset-relation-mutations.md)。跨库关系事实使用本页的 list 查询，不能用普通 `dataset relations` 或 `dataset detail` 的关系列表替代回读。
+使用 `dataset cross-relation-list/create/update/delete` 管理同一应用内、不同数据库连接的 DB_TABLE 逻辑关联。同库关系命令见 [数据集关系](rabetbase-dataset-relation-mutations.md)。跨库关系事实使用本页的 list 查询，不能用同库关系查询命令 `dataset relations` 或 `dataset detail` 的关系列表替代回读。
+
+需要实现跨库业务查询时，读取 [跨库 BFF 查询与拼接](../guides/cross-database-bff.md)，按目标字段用途确定查询顺序，并核对各端授权及结果完整性。业务关系清单不代表平台已登记；平台已有关系也需要与业务合同核对。
 
 ## 定位和查询
 
@@ -27,6 +29,8 @@ rabetbase dataset cross-relation-create \
 
 两端数据集与字段必填。`--to-label-column` 可选，省略时默认目标关联字段；`--cardinality` 可选，省略时不设置。合法基数：`ONE_TO_ONE`、`ONE_TO_MANY`、`MANY_TO_ONE`、`MANY_TO_MANY`。
 
+每端只接收一个字段；复合键不能拆成多条单字段关系，也不能用逗号拼接字段传入。依据完整复合键编写 BFF 不代表这些命令已经登记该关系。
+
 完全相同的端点不可重复创建。同一源字段可以关联不同目标；需要在创建前理解下述更新、删除的唯一匹配要求。
 
 ## 更新

package/skills/rabetbase.manifest.json

@@ -2,8 +2,8 @@
   "schemaVersion": 1,
   "name": "rabetbase",
   "packageName": "@lovrabet/rabetbase-cli",
-  "packageVersion": "2.5.3-beta.3",
-  "skillVersion": "2.5.3-beta.3",
+  "packageVersion": "2.5.3",
+  "skillVersion": "2.5.3",
   "files": [
     "SKILL.md",
     "guides/approval-flow-development-workflow.md",
@@ -11,6 +11,7 @@
     "guides/best-practices.md",
     "guides/bff-creation-workflow.md",
     "guides/conflict-detection.md",
+    "guides/cross-database-bff.md",
     "guides/custom-page-workflow.md",
     "guides/data-api-guidelines.md",
     "guides/database-connection-workflow.md",
@@ -147,5 +148,5 @@
     "references/rabetbase-user-account.md",
     "references/rabetbase-workspace.md"
   ],
-  "digest": "fb687c0d57936cfcba5e4f4d395e8695309e549ce848c5834befbade117e83e8"
+  "digest": "f2eb4c395b42ec83d9d10674a574182cc89015378268bb10bf3dd875441f1928"
 }

package/templates/README.md

@@ -49,27 +49,55 @@ node lib/cli.js project create template-verify --template-source templates/proje
 使用尚未发布的 CLI 时，先执行 `npm run build:dev`；
 使用已安装版本时，可把第二条命令换成 `rabetbase project create ...`。
 
-模板同步完成后，更新模板自身的 `package.json#version`，再生成待发布的 CDN 资产：
+模板源码确认后，可在开发阶段为单个通道生成快照；正式发布由 release 事务使用
+`deploy:verify` 已解析的精确版本自动生成，不要求开发者提前修改 `package.json#version`。
 
 ```bash
-# 正式模板：更新顶层 projectTemplate
-npm run sync:cdn
+# 开发阶段：更新顶层 projectTemplate 与正式本地快照
+npm run sync:cdn -- --version <stable-version>
 
-# beta 模板：只更新 beta.projectTemplate
-npm run sync:cdn:beta
+# 开发阶段：只更新 beta.projectTemplate 与 beta 本地快照
+npm run sync:cdn:beta -- --version <beta-version>
+
+# 上传前组装：校验仓内两个快照并原子生成完整 dist 目录，不推进任一通道
+npm run sync:cdn:all
 
 # 只读校验：发布门禁会按目标自动执行其中一条
 npm run check:cdn
 npm run check:cdn:beta
+npm run check:cdn:all
+```
+
+`sync:cdn` 与 `sync:cdn:beta` 从同一个模板真源重新生成所选通道；写入快照必须显式提供候选
+版本，正式与 beta 快照可以不同，两个命令都不会推进另一通道。发布门禁通过
+`--version <resolved-version>` 只读验证将要发布的
+描述，release 事务再使用同一版本落盘。`sync:cdn:all` 只验证仓内已有快照并组装完整 `dist/`。
+唯一配置索引写入
+`dist/rabetbase-cli/config/index.json`，并覆盖发布到
+`https://g.lovrabet.com/dist/rabetbase-cli/config/index.json`。正式模板使用顶层
+`projectTemplate`，beta 模板使用 `beta.projectTemplate`。仓内正式文件
+`sub-app-react-demo.zip` 与 beta 文件 `sub-app-react-demo-beta.zip` 只是固定本地快照名；远端新发布
+文件统一为 `sub-app-react-demo-<version>.zip`。beta 描述缺失时继续兼容读取顶层正式模板。
+每个模板描述包含 CLI `version`、文件 `name`、从 `/dist/...` 开始的完整相对 `url`、`sha256`
+和 `size`；`name` 与 `url` 指向同一版本化文件，旧 CLI 按 `name`、新版 CLI 按 `url` 下载并
+校验大小与摘要。线上已有固定文件名描述继续兼容读取。CLI 使用
+当前国家/地区或独立部署路由中的 `cdn.lovrabet` 作为 host。CLI 更新策略与项目模板共用这个
+固定配置索引，beta 同步只更新 `beta.projectTemplate`。
+`check:cdn` / `check:cdn:beta` 在系统临时目录重建 ZIP，只读比对所选通道的描述、当前 CLI 版本
+和仓内归档；`check:cdn:all` 只检查两个已提交快照各自自洽。三者都不会改动 `cdn/` 或 `dist/`。
+
+生成目录包含固定配置索引和所选通道当前描述指向的模板。正常发布不上传整个目录；release
+脚本先上传单个不可变版本 ZIP，再发布 npm，最后单独覆盖固定配置索引：
+
+```bash
+yt upload dist/rabetbase-cli/templates/projects/sub-app-react-demo-<version>.zip -r all -force
+yt upload dist/rabetbase-cli/config/index.json -r all -force
 ```
 
-两个命令都只从同一个正式模板真源生成产物，并写入同一个
-`dist/rabetbase-cli/config/index.json`。正式模板使用顶层 `projectTemplate` 和
-`sub-app-react-demo.zip`；beta 模板使用 `beta.projectTemplate` 和
-`sub-app-react-demo-beta.zip`，两条发布通道互不覆盖。旧 CLI 继续读取顶层字段；
-新版 beta CLI 在 beta 描述缺失时兼容回退到顶层正式模板。
-`check:cdn` / `check:cdn:beta` 在系统临时目录重建 ZIP，只读比对模板描述和仓内归档，
-不会改动 `cdn/` 或 `dist/`。
+以上顺序由 release 脚本执行，不作为日常手工步骤。必须向所有可用国家/地区发布并分别回读
+配置和 ZIP；新增节点由统一路由中的 `cdn.lovrabet` 提供 host，不在 CDN 配置里维护重复映射。
+release 脚本还会在 prepare 阶段记录两个 CDN 节点一致的共享配置摘要，并在归档上传和 config
+切换前重新校验；另一通道、CLI policy 或配置摘要发生变化时停止发布，不覆盖较新的线上事实。
 
 ### 模板结构
 
@@ -93,7 +121,7 @@ npm run check:cdn:beta
 ## 注意事项
 
 - `templates/projects/sub-app-react-demo/` 是项目模板真源，不是独立 Git 仓，也不是外部仓快照
-- `rabetbase project create` 从 CDN 下载 ZIP，然后更新 `package.json` 与 `.rabetbase.json`；正式 CLI 读取顶层模板，beta CLI 优先读取 `beta.projectTemplate`；此仓库模板不进入 npm 发布包
+- `rabetbase project create` 固定读取统一配置索引，再从描述中的正式或 beta URL 下载 ZIP，校验大小与 SHA-256 后更新 `package.json` 与 `.rabetbase.json`；正式 CLI 读取顶层模板，beta CLI 优先读取 `beta.projectTemplate`；此仓库模板不进入 npm 发布包
 - 模板文件名必须兼容 Windows、macOS 和 Linux；禁止符号链接、大小写冲突路径和 Windows 保留名称
 - 有 AppCode 时，CLI 会重新生成 `src/api/api.ts` 和 `src/api/client.ts`
 - 项目模板中不要保留真实 AppCode、真实数据集模型、`.git`、`node_modules`、`dist` 或个人配置