weaver-e10-builder 1.1.3 → 1.1.5

package/skill-docs/references/ebuilder-designer/guide-designer-version.md

@@ -0,0 +1,111 @@
+# 设计器版本层指南
+
+> 本文件为 `SKILL.md` 的子模块，在用户查看页面历史版本或还原版本时加载。覆盖：版本列表（version list）、版本还原（version revert）。
+>
+> **契约来源**：全部字段、参数、取值枚举来自 page/version/list 与 page/version/revert 两个 HTTP 接口规约。本指南几乎完全由接口契约推导。
+
+---
+
+## designer version list — 版本列表
+
+**接口契约**：GET `/api/bs/ebuilder/designer/page/version/list`，请求头 `ETEAMSID`，需 `ObjType.PAGE`+`OptType.READONLY` 权限。
+
+### Query 参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 取值范围/约束 | 说明 |
+|--------|------|------|--------|----------------|------|
+| pageId | Long | 是 | 无 | 正整数 | 目标页面 ID |
+| pageNo | Integer | 否 | 1 | 正整数 | 页码 |
+| pageSize | Integer | 否 | 10 | 1-200 | 每页条数 |
+| creator | Long | 否 | 无 | 正整数 | 创建人 ID 筛选 |
+| startTime | String | 否 | 无 | `yyyy-MM-dd` | 起始日期（系统时区，拼 `00:00:00`） |
+| endTime | String | 否 | 无 | `yyyy-MM-dd` | 结束日期（系统时区，拼 `23:59:59`） |
+| remark | String | 否 | 无 | - | 版本备注筛选 |
+| funcType | Enum | 否 | `contains` | 见下表 | remark 匹配方式 |
+
+### funcType 取值枚举（接口文档给全，可抄）
+
+| funcType | 含义 |
+|----------|------|
+| `contains` | 包含（默认） |
+| `uncontains` | 不包含 |
+| `empty` | 为空 |
+| `nempty` | 不为空 |
+| `startWith` | 开头包含 |
+| `endWith` | 结尾包含 |
+| `eq` | 等于 |
+| `neq` | 不等于 |
+
+> `funcType` 是服务端 switch-case 白名单（防 SQL 注入），传白名单外值会被拒绝。
+
+### 返回结构
+
+`data` = `Pagination<PageVersionEntity>`：`{ count, pageNo, pageSize, hitCache, records[] }`，按 `version` **降序**排列，只返 `deleteType=0`。
+
+**PageVersionEntity 字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | Long | 版本记录 ID（**版本还原用的 versionId 取此 `id`，不是 `version` 号**） |
+| version | Integer | 版本号，从 1 递增 |
+| pageId | Long | 所属页面 ID |
+| remark | String | 版本备注 |
+| remarkLabelId | Long | 备注多语言标签 ID（`!= -1` 时按用户语言自动翻译 remark） |
+| creator | Long | 创建人 ID |
+| creatorName | String | 创建人姓名（来自员工缓存，**可能为 null**） |
+| createTime | Long | 创建时间（Unix 毫秒） |
+| updateTime | Long | 更新时间 |
+| tenantKey | String | 租户标识 |
+| deleteType | Integer | 删除标识（只返 `0`） |
+
+> **坑**：
+> - `creatorName` 来自员工缓存，员工已删除时为 `null`——别当异常。
+> - `startTime` 系统自动拼 `00:00:00`、`endTime` 拼 `23:59:59`（系统时区）。
+> - 默认保留最近 **20** 个版本（可通过 `weaver.ebuilder.designer.version-reserve-count` 配置）；无备注的旧版本会被自动清理。
+> - 版本由 `designer save` 自动产生（每次 save 触发 `updatePageVersion` + 历史快照）。
+
+---
+
+## designer version revert — 版本还原
+
+**接口契约**：POST `/api/bs/ebuilder/designer/page/version/revert`，Query `pageId`（必填）、`versionId`（必填，取 version list 返回的 `records[].id`）、`pageName`（可选，用于日志），请求头 `ETEAMSID`，需 `ObjType.PAGE`+`OptType.EDIT` 权限。返回 `data: true`。
+
+### 校验
+
+- `versionId` 所属页面必须与 `pageId` 一致（跨页 versionId 被拒）。
+
+### 连锁操作
+
+还原会整体替换 PC + MOBILE 两端布局，并执行：更新布局（updateLayouts）→ 重新生成源码（createOrUpdateEcode）→ 更新页面版本（updatePageVersion）→ 记录操作日志（`revertPage`）。
+
+> **坑**：
+> - **非幂等**：重复调同一 `versionId` 会产生重复连锁操作，多次还原。别循环重试。
+> - **不可逆**：还原后未保存的当前编辑丢失。建议还原前先 `designer lock`。
+> - 还原**本身不自动产生新版本快照**（之前的 save 才触发快照）；还原后须重新 `designer layout <pageId>` 刷新看新状态。
+> - 兼容性：旧模块 id（`EB`→`EB_PAGE`、`PORTAL`→`PORTAL_PAGE`）与旧终端字段会被重映射。
+>
+> **⚠️ CLI 行为（非接口契约）**：`--yes` 非交互要求（非 TTY 自动化下不加 `--yes` 会"已取消"）属 CLI 行为，非接口契约——本骨架不展开。
+
+---
+
+## 版本管理速查
+
+调用顺序：
+
+```bash
+e10-cli designer info <pageId>                              # 看 allowEdit / isLock
+e10-cli designer version list <pageId> --size 20      # 列历史版本（--page/--size/--since/--until/--creator/--remark/--func，非 --page-no/--page-size）
+# （可选）e10-cli designer lock <pageId>                    # 还原前锁定防并发
+e10-cli designer version revert <pageId> <versionId> --yes  # 还原（versionId 取 list 返回的 id）
+e10-cli designer layout <pageId>                           # 还原后刷新看新状态
+e10-cli designer unlock <pageId>                           # 解锁
+```
+
+> **关键**：`versionId` 用 version list 返回的 `records[].id`（版本记录 ID），不是 `version` 号。
+
+---
+
+## 相关指南
+
+- 布局层（info/layout/save/lock）→ `guide-designer.md`
+- 命令速查 → `../common/ref-cli-commands.md`「designer」节

package/skill-docs/references/ebuilder-designer/guide-designer.md

@@ -0,0 +1,287 @@
+# 设计器布局层指南
+
+> 本文件为 `SKILL.md` 的子模块，在用户于 Ebuilder 设计器中读/改/存页面布局时加载。覆盖：页面元信息（info）、布局树（layout）、保存（save）、锁定/解锁（lock）、主题（theme）、栅格位置（position）、加组件（comp-add，factory 模板自带打包）。
+>
+> **契约来源**：本指南全部字段、参数、取值枚举来自 ebuilder-designer 的 7 个 HTTP 接口规约（layout/page-info、layout/list、layout/save、layout/lock、layout/refTheme、page/version/list、page/version/revert）。凡接口未给出、须运行时 inspect 真实页面才能确定的具体取值（组件 config 子字段集、取值枚举、header 抓包集等），一律标 **「需 inspect 真实页面查原始值」**，不凭空构造——盲造组件 config 会触发 ERR-007/008 崩页。
+>
+> 本 skill 自包含分发，不依赖任何本机文件；"inspect 真实页面"指用户对自己的页面运行 `designer layout <pageId> --json` 查看实际数据，是运行时操作。
+
+---
+
+## 命令总览
+
+| 命令 | 说明 | 对应接口 |
+|------|------|----------|
+| `e10-cli designer info <pageId>` | 获取页面元信息（权限/变量/数据集/主题/锁定态） | GET `/layout/page/info` |
+| `e10-cli designer layout <pageId> [--no-cuscomp]` | 获取 PC/MOBILE 两端完整组件树（默认 `returnCusComp=true`；`--no-cuscomp` 切 false 需 READONLY 权限） | GET `/layout/list` |
+| `e10-cli designer layout <pageId> --json` | 导出布局 JSON 文件，供 save/comp-add 复用（`--json` 是全局选项，非 layout 专属隐藏） | GET `/layout/list`（落地为文件） |
+| `e10-cli designer save <pageId> --layouts <json\|@file> [--page-name] [--sync-outdate]` | 保存布局（CLI 内部 LZ 压缩后 POST）。`--layouts` 必填（**不是位置参数**） | POST `/layout/save` |
+| `e10-cli designer lock <pageId>` / `designer unlock <pageId>` | 锁定/解锁页面 | POST `/layout/lock` |
+| `e10-cli designer theme <pageId> <themeId> [--terminal <PC\|MOBILE>]` | 给页面设置主题（`--terminal` 默认 PC） | POST `/layout/refTheme` |
+| `e10-cli designer theme-list <pageId>` / `designer theme-info <pageId>` | 查可选主题列表 / 当前主题详情 | 契约外 `/theme/list`、`/theme/info` |
+| `e10-cli designer position <pageId> <compId> --x --y --w --h` | 调组件栅格位置（PC，封装 `/layout/save`：改 `config.layout.x/y/w/h` 后 save） | POST `/layout/save` |
+| `e10-cli designer comp-add <pageId> --type <Type> [--template @<file>] [--from <srcPage> --comp <id>] [--x --y --w --h]` | 加组件（封装 `/layout/save`）。**`--type` 是选项不是位置参数**。两种取源：`--type --template @<file>`（factory 模板，见 `guide-designer-factory.md`）/ `--from <srcPage> --comp <id>`（从活页克隆）。`--h` 按该指南「组件高度判断」自行算 | POST `/layout/save` |
+| `e10-cli designer comp-remove <pageId> <compId>` | 移除组件（含 PC/MOBILE refCompId 两端） | POST `/layout/save` |
+| `e10-cli designer comp-library <pageId> [--custom] [--json]` | 查页面可用组件库（只读目录，不含 config 模板；加组件仍走 `comp-add --template`） | 契约外 `/api/ebuilder/coms/component/list` |
+| `e10-cli designer style <pageId> <compId>` / `designer style-set <pageId> <compId> --var <name> --value <val>` | 查/改组件视觉样式（CSS 变量；style-set best-effort、非持久） | 改 `sourceCode.cssCache.ebd_style_lib` + `/layout/save` |
+
+> 组件 config 字段名与配置机制见 `guide-designer-components.md`；版本 list/revert 见 `guide-designer-version.md`。
+
+---
+
+## designer info — 获取页面布局信息
+
+**接口契约**：GET `/api/bs/ebuilder/designer/layout/page/info`，Query `pageId`（Long，必填），请求头 `ETEAMSID`。
+
+**返回字段**（`Map<String,Object>`，随 `BelongModule` 不同字段集不同）：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id / pageId | String | 页面 ID |
+| module | Enum | 所属模块，如 `EB_PAGE` / `EB_FORM_VIEW` / `PORTAL_PAGE` |
+| moduleName | String | 模块中文名 |
+| layoutType | Enum | `GRID` / `ABSOLUTE` / `FLEX` |
+| isLock | Integer | `0` 未锁 / `1` 已锁 |
+| allowEdit | Boolean | 当前用户是否可编辑（仅 EB 页面模块返回） |
+| terminalScopes | String | 终端范围，如 `"PC,MOBILE"` |
+| appid / appName / appLabelId | - | 所属应用信息（仅 EB 页面模块） |
+| dataset | Array | 页面数据集 |
+| pageVar / appVar / pageModel | Array | 页面变量 / 全局变量 / 变量模型 |
+| refTheme | String | 关联主题 ID |
+| isIntro | Boolean | 是否需新手引导 |
+| pageAnonymousEnable | Boolean | 是否免登录访问 |
+| compPermit / compStylePermit | Boolean | 组件库/样式库创建权限（仅 `PORTAL_PAGE`） |
+
+> **坑**：
+> - 本接口**无 `@Permission` 注解**，只校验登录态；可编辑性通过 `allowEdit` 字段返回，前端据此控制——`allowEdit=false` 不要调 save。
+> - `isLock=1` 须先 `designer unlock` 再 save。
+> - `isIntro=true` 首次使用需引导，完成后调 `/finishIntro`（本 skill 未封装，需界面）。
+
+---
+
+## designer layout — 获取页面布局列表
+
+**接口契约**：GET `/api/bs/ebuilder/designer/layout/list`，Query `pageId`（必填）、`returnCusComp`（Boolean，默认 `true`），请求头 `ETEAMSID`。
+
+**权限分层**：`returnCusComp=true` 校验 `ObjType.PAGE`+`OptType.VIEW`，返回完整组件（含权限过滤）；`returnCusComp=false` 校验 `READONLY`，不返回自定义组件（`/api/bs` 路径下自动置 `false`）。
+
+**返回**：`Array<PageLayoutEntity>`，通常 2 元素（PC + MOBILE），按 `terminalType` 区分。
+
+**PageLayoutEntity 核心字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | Long | 布局唯一标识 |
+| pageId | Long | 所属页面 ID |
+| layoutType | Enum | `GRID` / `ABSOLUTE` / `FLEX` |
+| terminalType | Enum | `PC` / `MOBILE` |
+| module | Enum | `EB_PAGE` / `PORTAL_PAGE` 等 |
+| config | Map | 布局配置（页面样式/背景/缩放等） |
+| comps | Array<LayoutComponentEntity> | 组件列表 |
+| sourceCode | Map | 页面源码 |
+| ecodeVersion | Integer | ecode 版本标识 `1`~`4` |
+| rightCompIds | Array<String> | 当前用户有权限查看的组件 ID |
+| appId | Long | 所属应用 ID |
+| thumbnail | String | 缩略图文件 ID |
+| sysVariable / cssCache* | - | 组件变量 / 样式缓存相关 |
+
+**LayoutComponentEntity 核心字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | String | 组件唯一标识（32 位无连字符 UUID） |
+| type | String | 组件类型名，如 `Slide` / `NList` / `NText` |
+| package | String | 组件 npm 包路径 |
+| category | String | 组件分类编号 |
+| pid | String | 父组件 ID |
+| refCompId | String | 关联组件 ID（PC/MOBILE 同名组件互指） |
+| config | Map | 组件配置（含 `layout`、样式、属性、事件等） |
+| isCustom / isLock | Boolean | 是否自定义 / 是否锁定 |
+| applyStyle | String | 应用样式 ID 列表（逗号分隔） |
+| prop | String | 组件属性标识 |
+| styleCategoryCompKey / styleCategoryPackage | String | 样式分类 key / 包路径 |
+
+> **坑**：
+> - `returnCusComp=true` 时 comps 经权限过滤，只返有权查看的组件；`rightCompIds` 列出有权组件 ID。
+> - PC 与 MOBILE 同名组件经 `refCompId` 互连——改一端时注意另一端是否需同步。
+> - 跨租户页面走 `/api/{module}/designer/layout/list` 路径会额外查 `isNoTenantPage`。
+
+---
+
+## designer save — 保存页面布局（核心）
+
+**接口契约**：POST `/api/bs/ebuilder/designer/layout/save`，Query `pageId`（必填）、`pageName`（可选，1-200）、`isSyncOutDateComps`（可选，默认 `false`）；**Body = `layouts` 字符串，是 LZ 压缩后的 JSON**。请求头 `ETEAMSID`。需 `ObjType.PAGE`+`OptType.EDIT` 权限。
+
+### 入参数据来源铁律
+
+> **layouts 直接取自 `/layout/list` 返回值作为基础，调用方只需完整构造 `comps` 属性**——`pageId`、`terminalType`、`module`、`layoutType`、`ecodeVersion`、`appId`、`config`、`sourceCode`、`rightCompIds` 等元数据保持 `/list` 原值不动。CLI 的 `designer save` 也遵循此模式：先 `layout --json` 导出，改 `comps`，再 save。
+
+### PageLayoutEntity 入参字段（解密后 JSON 数组每元素）
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | Long | 是 | 布局 ID |
+| pageId | Long | 是 | 所属页面 ID |
+| terminalType | Enum | 是 | `PC` / `MOBILE` |
+| module | Enum | 是 | `EB_PAGE` / `PORTAL_PAGE` 等 |
+| comps | Array<LayoutComponentEntity> | 是 | 组件列表（**唯一需完整构造**） |
+| layoutType | Enum | 否 | `GRID` / `ABSOLUTE` / `FLEX` |
+| config | Map | 否 | 布局配置 |
+| compStyles / dataset / pageVar / pageModel / appVar | Array | 否 | 样式/数据集/变量/模型 |
+| sourceCode | Map | 否 | 页面源码 |
+| ecodeId / ecodeVersion / appId | - | 否 | ecode/应用标识 |
+| thumbnail / refTheme / themeData | - | 否 | 缩略图/主题 |
+| sysVariable | Map<String,String> | 否 | 组件变量 |
+
+### LayoutComponentEntity 入参字段（comps 子元素）
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | String | 是 | 32 位无连字符 UUID（前端生成） |
+| type | String | 是 | 组件类型名 |
+| config | Map | 是 | 组件配置（含 `layout`/样式/属性/事件等） |
+| package | String | 否 | npm 包路径（序列化时映射为 `compPackage`） |
+| category / pid / refCompId | String | 否 | 分类 / 父组件 / 关联组件 |
+| refPluginPackageId / refPluginPackage | - | 否 | 插件包 |
+| refModule / refBusinessId | - | 否 | 关联模块/业务 |
+| prop / applyStyle | String | 否 | 属性标识 / 样式 ID 列表 |
+| styleCategoryCompKey / styleCategoryPackage | String | 否 | 样式分类 |
+| styles / customConfig | - | 否 | 自定义样式/配置 |
+| ecodeId / ecodeVersion | - | 否 | ecode 标识 |
+| isCustom / isLock | Boolean | 否 | 是否自定义/锁定 |
+| masterComponent / master | - | 否 | 母版 |
+| visibleScope | Enum | 否 | `ALL` / `OWNER` / `CUSTOM` |
+| isCover | int | 否 | `0`/`1` 是否覆盖母版 |
+| formComponent | Object | 否 | 表单组件 DTO（表单页才用） |
+
+### config 内部结构（以 Slide 为例——接口文档唯一给出的完整样例）
+
+| 子字段 | 类型 | 说明 |
+|------|------|------|
+| name | String | 组件显示名 |
+| title / titleEnabled | String / Boolean | 标题文本 / 是否启用 |
+| footerEnabled | Boolean | 是否启用页脚 |
+| pics | Array | 图片列表 |
+| imageMode | String | 图片填充模式 |
+| switchEffect | String | 切换效果 |
+| intervalTime | Object | 轮播间隔 `{type, value}` |
+| speed | Integer | 切换速度（ms） |
+| lazyLoad | Boolean | 是否懒加载 |
+| imgSourceType | String | 图片来源类型 |
+| eventGroup | Array | 事件配置列表 |
+| **filter** | **Object** | **数据过滤条件（HTTP 契约：filter 类型为 Object，传 `[]` 与契约不符）** |
+| showNum | Integer | 展示数量 |
+| layout | Object | 栅格布局 `{i, x, y, w, h, scope, moved, selected, offsetTop, hidden}` |
+| flow / disabled | Object | 流程 / 禁用配置 |
+
+> **⚠️ 需 inspect 真实页面查原始值**：上表是 Slide 一例。**其他组件类型（NList / NText / NButton / Calendar / Pie / Bar / Line / NavPanel / DigitalPanel 等）的 config 子字段集，接口文档未给出**——必须 `designer layout <pageId> --json` 导出真实已配置页面，查 `comps[].config` 字段名与取值，**勿凭空构造**（盲造触发 ERR-007/008）。具体 setter 取值枚举见 `guide-designer-components.md`。
+
+### LZ 压缩算法（CLI 内部使用，直接调 `designer save` 无需手压）
+
+`layouts` Body 是 LZW（Lempel-Ziv-Welch）压缩后的**逗号分隔数字串**，服务端 `EbuilderCommonUtil.decryptByLZ()` 解密。算法要点：
+1. 字典初始大小 **65536**（`2^16`，Unicode 字符最大值 +1）。
+2. 字典**不预初始化**单字符映射，运行时按需添加。
+3. `w` 为单字符且不在字典时，将其 Unicode 码点加入字典作为 code。
+4. 输出逗号分隔数字序列，每个数字为字典 code 或 Unicode 码点。
+
+> CLI `designer save` 内置该算法（JS/Java/Python 三语言实现见 layout-save 接口文档 §4.4），调用方传 `@layouts.json` 文件即可，**不要自己压**。
+>
+> **坑**：Body 直接传压缩后的数字串（`Content-Type: application/json`），**不要**再用 `JSON.stringify()` 包裹；保存前若 `isLock=1` 须先 unlock。
+>
+> **⚠️ 需 inspect 真实页面/抓包**：接口文档 §4.4 仅明示 `ebbusinessid` 请求头（=pageId）+ Cookie（`ETEAMSID`/`LOGIN_TYPE`/`langType`）。真实浏览器调用还带 `referer`、`timezoneoffset` 等头——**完整 header 集需抓包确认，本骨架只列文档明示项**。CLI 已封装常用头，手调原始接口时按需补。
+
+### 返回与内部流程
+
+**返回**：`data.refreshComps`（Map<layoutId, Array<comp>>，仅 NList + 插件包 `933846626099339271` 时返，需前端刷新的组件）、`data.ecodeIds`（Map<layoutId, {ecodeId, ecodeVersion}>；`ecodeVersion` 为 2/3 时 `ecodeId` 取应用的而非布局自身的）。
+
+**保存内部流程**：解密 → updateLayouts → saveSourceCode → updatePageVersion →（异步）createPageVersionBySavingLayout →（异步）syncMultilingual。历史记录与多语言同步不阻塞保存成功。
+
+---
+
+## designer lock / unlock — 锁定/解锁
+
+**接口契约**：POST `/api/bs/ebuilder/designer/layout/lock`，Query `pageId`（必填）、`isLock`（Boolean 必填，`true` 锁 / `false` 解锁），请求头 `ETEAMSID`，需 EDIT 权限。返回 `data: true`。
+
+> **坑**：
+> - 锁是**软约束**——`/save` 本身**不校验** `isLock`；实际编辑权由 `@Permission` 强制。锁主要用于多人协作防并发。
+> - 每次 lock/unlock 都触发 `updatePageVersion`，**版本号会递增**（即使幂等调用）。
+> - `isLock` 存储为 int（`lockType` 1/0）。
+
+---
+
+## designer theme — 设置主题
+
+**接口契约**：POST `/api/bs/ebuilder/designer/layout/refTheme`，**Query 参数** `themeId`（Long 必填）、`pageId`（Long 必填）、`terminalType`（`PC`/`MOBILE`，默认 `PC`；契约只列 themeId+pageId，CLI 抓包发现带 terminalType），请求头 `ETEAMSID`，需 EDIT 权限。
+
+**返回**：`{ themeCss, styleConfig, themeId, themeVersion, refTheme, defTheme, refStyles[] }`。
+
+> **坑**：
+> - `themeId` 与当前一致且版本缓存一致时 `themeCss` 可为 `null` → 用缓存，不再注入 CSS。
+> - 主题已删除时不报错但 CSS 空，回落默认。
+> - 设置主题后**须再调 `designer save` 持久化** `refTheme` 到布局。
+> - 异步同步到发布端（`asyncTheme`）。
+>
+> **⚠️ 需 inspect 真实页面**：`themeId` 取值（可用主题清单）接口文档未给获取主题列表的接口——先用 `designer theme-list <pageId>` 查可选 themeId 清单，再 inspect 设计器主题面板核对；当前主题详情用 `designer theme-info <pageId>`。
+
+---
+
+## designer position — 调整栅格位置（PC）
+
+`designer position <pageId> <compId> --x --y --w --h` 是 save 的封装：`designer layout <pageId> --json` → 改目标 comp 的 `config.layout.x/y/w/h` → `designer save`。
+
+PC 端 12 列栅格（`config.style.layout.column=12`）；`--x` 列起点、`--y` 行起点、`--w` 宽（≤12）、`--h` 高（栅格行数）。
+
+> **⚠️ 需 inspect 真实页面**：Mobile 端 `config.layout` 字段（`adaptive`/`h` 等，见 layout-list 示例）与 PC 差异——接口文档示例可见但不完整，**需 inspect 两端真实布局对比**。`designer position` 默认只改 PC 端栅格。
+
+---
+
+## designer comp-add — 加组件
+
+加组件 = 读 `/layout/list` → 向对应 `terminalType` 的 `comps[]` push 一个新 `LayoutComponentEntity` → `designer save`。
+
+- **comp id**：前端生成的 32 位无连字符 UUID（接口文档 §4.3 comps id 字段约束）。
+- **config 完整性**：`config` 字段必须完整，缺失字段会崩页（ERR-007/008）。
+- **factory 模式（首选）**：`designer comp-add <pageId> --type <Type> --template @<file>`（**`--type` 是选项不是位置参数**）从本 skill 自带的 `assets/factory/factory-<name>.json`（28 组件均有，原8源 2ganjing/新增20源 0805yuanshi 平台初始态，见 `guide-designer-factory.md`）复制完整 comp（仅换 id/refCompId）。模板是平台拖拽初始态、绑定空——**greenfield 用户无任何已配页面也能开箱即用**，克隆后用组件子命令把数据绑到自己的表单（图表/列表/日历/导航/幻灯/数字面板有 setter；其余组件见 factory 指南"克隆后必做"节）。
+- **活页克隆模式**：`designer comp-add <pageId> --from <srcPage> --comp <srcCompId>` 从一个已配好的真实页面逐字克隆某 comp（连配置一起搬）。用于搬运已配好的复杂数据；会带入源页表单绑定，须逐个 remove+add 重指到自己的表单，不如 factory 干净。
+- **无模板凭空构造**：除 Slide 外的组件 config 字段集接口未给，**勿凭空拼装**（盲造 ERR-007/008）；始终走 factory 模式。
+
+> **新建 comp 对 PC/MOBILE `refCompId` 互连**：接口示例可见互指，factory 模板已内置两端互连规则，`comp-add --template` 自动生成新对并重连，无需手动处理。
+
+---
+
+## 版本与还原（速查）
+
+版本列表 / 版本还原见 `guide-designer-version.md`（GET `/page/version/list` + POST `/page/version/revert`）。
+
+---
+
+## 典型工作流
+
+```bash
+# 1. 拿 pageId（应用已建、页面已建；见 ref-cli-commands.md 页面管理节）
+e10-cli app list                       # 拿 appId
+e10-cli page list --app-id <appId>     # 拿 pageId
+e10-cli page create <页面名> <appId> --scope PC,MOBILE --layout-type GRID   # 建空页（参数顺序：名称在前、appId 在后）
+
+# 2. 进设计器前先看元信息
+e10-cli designer info <pageId>         # 看 allowEdit / isLock / module
+
+# 3. 读布局（作为编辑基础）—— --json 输出完整 PC+MOBILE 两端（save 必须两端，否则覆盖丢 MOBILE；CLI save 强校验）
+e10-cli designer layout <pageId> --json > layouts.json   # 导出 PC+MOBILE 组件树
+
+# 4. 锁定（多人协作防并发）
+e10-cli designer lock <pageId>
+
+# 5. 改 comps（加组件/改 config/调位置）→ 保存
+e10-cli designer comp-add <pageId> --template slide --x 0 --y 0 --w 12 --h 25   # 模板名直传（28 个内置），--h 按组件高度判断自行算，见 guide-designer-factory.md
+e10-cli designer position <pageId> <compId> --x 0 --y 0 --w 12 --h 25
+e10-cli designer auto-height <pageId>                    # 单列纵堆模式：按内容定高+重排 y（多列栅格勿用，手调 position）
+e10-cli designer save <pageId> --layouts @layouts.json   # 收尾显式保存
+
+# 6. 解锁
+e10-cli designer unlock <pageId>
+```
+
+> **关键**：save 入参直接取自 `/list` 导出值，只改 `comps`；元数据不动。组件具体 config 取值需 inspect 真实页面，不凭空造。
+
+> **⚠️ 收尾必做显式 save + unlock（否则"布局未保存"）**：`comp-add`/`position`/各组件 setter（chart dataset-set/measure-add 等）虽各自**封装 `/layout/save` 自动存盘**，但全部改完后**必须再跑一次显式 `designer save <pageId> --layouts @<fresh-layout.json>` + `designer unlock <pageId>`**（fresh layout 用 `designer layout <pageId> --terminal all --json` 现导）。否则页面留 `isLock=true`（浏览器开了设计器会自动上锁）或 draft 标志未清，**设计器/预览打开会弹"布局未保存"提示**（实测：未 unlock 的页 `isLock=true`，预览必弹）。`designer unlock` 是软锁释放，多人协作场景防并发；单人编辑也必须收尾 unlock 清态。`publish-menu` 前务必先 save+unlock。