weaver-e10-builder 1.2.3 → 1.2.5

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

@@ -0,0 +1,127 @@
+# 页面组件自定义 CSS
+
+需求里出现「给这个组件调样式」「自定义 CSS」「改选择器」「样式不生效」「DOM 结构」时读本篇。组件 config 字段见 `guide-designer-components.md`，布局读写机制见 `guide-designer.md`。
+
+## 定位与职责边界
+
+自定义 CSS 写在**组件**上，形如：
+
+```
+comp.config.styles[N].customStyle.base.codeSource   ← 自由文本 CSS
+```
+
+- **页面级没有自由 CSS 槽位**。`layout.config.style` 里只有结构化的 `page.margin/padding/background`。想整页统一风格，只能往组件上写。
+- **CLI 只负责写**：写对、写稳、写后回读比对。样式在页面上如何渲染、样式缓存如何编译，是平台的事，命令不做判断也不承诺。
+- **一个页面有 PC/MOBILE 两套布局，每个终端各有一份组件**，靠互指 `refCompId` 配对。设计器本身就是双端同写，所以 `css write` 默认也双端。
+
+## `styles` 记录契约
+
+`comp.config.styles` 是数组，里面有**两种互不相干的记录**，标志位正好相反：
+
+| | 自由 CSS 记录 | 主题绑定记录 |
+|---|---|---|
+| 形态 | `{category, useCustom:true, useComStyle:false, styleVersion, customStyle:{…}}` | `{id, category, customType, useCustom:false, themeId, useComStyle:true}` |
+| 来源 | 用户/CLI 写的自定义样式 | 组件自带的外观主题（Picture、CountDown 的模板就带） |
+| CLI 行为 | 读它、写它 | **绝不碰**（写 CSS 时追加一条新记录，不动它） |
+
+干净组件的 `styles` 是**空数组 `[]`**。三种输入状态及对应行为：
+
+1. `styles` 为空 → 新建一条记录（只需 `category`/`useCustom`/`useComStyle`/`styleVersion` + `customStyle.base.codeSource` 四个键）。
+2. 已有自由记录 → **外科式**只换 `customStyle.base.codeSource`，`customStyle` 下的 `title`/`content`/`footer`/`container` 等图形化样式块与记录的其它字段原样保留。
+3. 只有主题绑定记录 → **追加**一条自由记录，第 0 条一字不动。
+
+## 命令
+
+```bash
+# 读（默认双端；compId 给 PC 或 MOBILE 任一端的都可以）
+e10-cli designer css read <pageId> <compId> [--terminal pc|mobile|both] [--json]
+
+# 写（默认双端、默认整段替换）
+e10-cli designer css write <pageId> <compId> --css "<CSS>"
+e10-cli designer css write <pageId> <compId> --css-file <路径>
+e10-cli designer css write <pageId> <compId> --css "<CSS>" --append
+e10-cli designer css write <pageId> <compId> --clear
+e10-cli designer css write <pageId> <compId> --css "<CSS>" --terminal pc
+```
+
+- **`--css` 与 `--css-file` 是两个选项，没有 `@file` 约定。** `@media` 开头的 CSS 是合法写法，用 `@文件` 会被当成路径。
+- `--append` **非幂等**：重复跑会重复追加。想改内容用整段替换。
+- `--clear` 清空内容但**保留记录**（不动 `customStyle` 其它块）。
+- 两端现有 CSS **都非空且不一致**时，双端写会覆盖其中一端 —— 命令会拦下并点名两端字节数，确认覆盖加 `--yes`，只想改一端用 `--terminal`。
+- 写完会**回读比对**；对不上直接报错（服务端可能没落库或改写了形状），用 `css read` 看实际值。
+
+## 写选择器：**不要写组件 id**
+
+**`customStyle.base.codeSource` 是组件级的** —— 每段 CSS 本来就只属于它所在的那个组件，平台在编译时会自己套上 `#<comId>` 限域。所以源码里**再写一遍 id 是错的**：
+
+```css
+/* ✅ 对：直接写类名 */
+.ebcoms-navPanel-wrapper-square { border-radius: 12px; }
+.content { background: #070d1a; }
+
+/* ❌ 错：多写了组件 id */
+#f3708b2387bd757a336ab0e176243801 .ebcoms-navPanel-wrapper-square { … }
+```
+
+写进去会怎样：轻则多余，重则**不生效** —— 一个页面 PC 与 MOBILE 是两份布局、两个不同的实例 id，同一段 CSS 双端同时写时（设计器自己就是双端同写、两端 `codeSource` 一模一样），写死哪一端的 id，另一端就必不匹配。
+
+> 组件 DOM 文档里说的「官方样式生成器一律以 `#<comId>` 限域」，讲的是**编译产物**（`sourceCode.cssCache`）长什么样，**不是叫你写在源码里**。
+
+组件 DOM 由三层拼出来，**类名前缀区分来源**：
+
+| 前缀 | 来源 |
+|---|---|
+| `ebcom-` | 引擎/框架层（源码里搜不到，由引擎外壳生成） |
+| `ebcoms-` | 组件自己写的 |
+| `ui-` | `@weapp/ui` 第三方组件追加的 |
+
+- 引擎外壳的 `id` 与挂在组件根上的 `data-id` 都是组件实例 id —— **它们是给平台编译用的，不要写进你的选择器**。
+- 页面层外壳是 `#ebpage_<pageId>`，同样**别拿它定位组件**。
+- 各组件的 `ebcom-*` 外壳类名不统一（如 NList → `ebcom-nlist`、CountDown → `ebcom-countdown`、CollapsePanel → `ebcom-collapsepanel`），以 DOM 结构文档为准，不要凭类型名拼。
+
+写样式时：**只写类名，不写 id**；**不要杜撰类名**（拼错就是静默不生效）；尽量不用 `!important` 去压默认样式。
+
+## 查 DOM 结构：`designer dom`
+
+内置 **27 个组件**的 DOM 结构索引，随 skill 资产分发，用来把「用户说的部位」翻成选择器。
+
+```bash
+e10-cli designer dom-list                    # 全表：类型 / 体量 / 组件名
+e10-cli designer dom NList --keys            # 先看骨架：usage / pickTree / legend / 各区块体量
+e10-cli designer dom NList --section shared.title        # 只取需要的子树
+e10-cli designer dom NList --section shared.title --refs # 就地展开 {"ref":"shared.x"}
+```
+
+**先 `--keys` 再 `--section`**：文档中位数 20 多 KB，整份打出来很占上下文，而 `usage`/`pickTree`/`legend` 三段散文才是找对树的关键。
+
+文档里的记号（各文件自己的 `legend` 也有解释）：
+
+| 记号 | 含义 |
+|---|---|
+| `[cls]` | 条件类名，满足业务条件才挂 |
+| `{a\|b}` | 同一个位置按配置二选一 |
+| `a > b` | 父子层级压缩写法 |
+| `<comId>` | 组件实例 id。**只出现在文档对编译产物的描述里**，写源码选择器时不要用（见上） |
+| `ref:shared.x` / `{"ref":"shared.x"}` | 引用同文件的复用片段，用 `--refs` 展开 |
+| `uncontrolled` | 第三方（`@weapp/ui` 等）渲染，只给挂载点 |
+
+覆盖的 27 个组件（命令按**平台组件 type** 取，也认下面的常见写法）：
+
+| 平台 type | 也认 | 平台 type | 也认 |
+|---|---|---|---|
+| `NavPanel` | nav-panel | `NList` | nlist、n-list |
+| `NavBar` | nav-bar | `DigitalPanel` | digitalpanel、digital-panel |
+| `ProgressChart` | progress-bar、progressbar | `PageHeader` | pageheader、page-header |
+| `EbButton` | eb-button | `CountDown` | count-down |
+| `FastCreate` | fast-create | `SearchGlobal` | search-global |
+| `CollapsePanel` | collapse-panel | `NewTab` | new-tab |
+| `Comment` / `Picture` / `Slide` / `Calendar` | — | `Bar`/`BarStack`/`Line`/`HBar`/`HBarStack`/`Pie`/`Circular`/`Nightingale`/`Gauge`/`Treemap`/`Bubble` | — |
+
+`NavMenu`、`InternalContainer` **暂无**文档，命令会直接说明并列出已覆盖清单。
+
+## 坑
+
+- **注释不会被编译进去**，但 CLI 写进去时**原样保存**，回读比对会按去掉注释后比 —— 所以带注释的原文是安全的。
+- **MOBILE 端的布局不返回样式缓存**，双端写完之后想确认效果，看 PC 端更省事。
+- **别手写 `sourceCode.cssCache`** —— 那是平台的编译产物，手写会和下次编译打架。
+- 改完布局记得收尾 `designer unlock`（多人协作防并发；`/layout/save` 本身不校验锁）。

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

@@ -17,15 +17,16 @@
 | `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 css read <pageId> <compId> [--terminal <pc\|mobile\|both>]` | 读组件自定义 CSS（默认双端；`<compId>` 给任一端都行） | GET `/layout/list` |
+| `e10-cli designer css write <pageId> <compId> (--css <文本> \| --css-file <路径>) [--append\|--clear] [--terminal] [--yes]` | 写组件自定义 CSS（默认**双端同写**、默认整段替换）。写后回读比对，对不上报错 | POST `/layout/save` |
+| `e10-cli designer dom-list` / `designer dom <type> [--keys] [--section <path>] [--refs]` | 查写 CSS 要用的**组件 DOM 结构索引**（27 个组件；先 `--keys` 看骨架，再 `--section` 取子树） | 读随包资产 |
 | `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`。
+> **页面主题（`/layout/refTheme`）、页面可用组件库（`/api/ebuilder/coms/component/list`）这两类接口目前没有 CLI 命令封装**，故不列在此表 —— 上表只列**实际可执行**的命令。
+
+> 组件 config 字段名与配置机制见 `guide-designer-components.md`；自定义 CSS 与 DOM 结构索引见 `guide-designer-css.md`；版本 list/revert 见 `guide-designer-version.md`。
 
 ---
 

package/skill-docs/references/form/guide-create-form.md

@@ -219,7 +219,7 @@ e10-cli form field-lang set <objId> <appId> <fieldId> --zh "项目" --en "projec
 ```bash
 e10-cli form read <objId> --app-id <appId> --out fields-created.json
 e10-cli form list-view <objId> <appId>
-e10-cli form layout read <objId> <appId>
+e10-cli form layout read <objId>
 ```
 
 重点确认字段数量与类型、明细结构、分组和显示属性、布局类型、默认台账名称与 `listId`。需要菜单时再确认菜单入口。

package/skill-docs/references/form/guide-form-layout-planning.md

@@ -62,7 +62,7 @@
 
 ```bash
 e10-cli form create <appId> "<表单名>" --fields @fields.json --layout EXCEL
-e10-cli form layout read <objId> <appId>
+e10-cli form layout read <objId>
 ```
 
 创建后需要调整局部位置或显示属性时，使用 `form layout` 下的移动、只读和必填设置命令；具体参数通过 `form layout --help` 查询。

package/skill-docs/references/form/guide-form-linkage.md

@@ -29,7 +29,8 @@ e10-cli form linkage add <appId> <objId> <name> --config @<json文件>
           "fieldId": "目标字段ID",
           "name": "字段名称",
           "dataKey": "字段编码",
-          "fieldType": "Employee"
+          "fieldType": "Employee",
+          "isDetail": false
         }
       ]
     }
@@ -37,6 +38,30 @@ e10-cli form linkage add <appId> <objId> <name> --config @<json文件>
 }
 ```
 
+### actions[].fields[]（联动目标字段）
+
+| 键 | 说明 |
+|------|------|
+| fieldId | 目标字段的 fieldId（从 `form read --app-id` 获取） |
+| name | 字段名（显示用） |
+| dataKey | 字段编码；`form read` 不返回它，**留空即可**（用 fieldId 代替可行） |
+| fieldType | 字段类型，如 `Text` / `Employee` / `Date` |
+| **`isDetail`** | **目标落在明细表里时必须为 `true`**。不传 = 主表字段 |
+
+**目标字段在明细表里，就加 `"isDetail": true`** —— 这是「主表字段控制明细列显隐」的写法，两个方向都支持（实测 `hide` / `required` 均可）：
+
+```json
+{
+  "conditions": [{ "fieldId": "<主表字段ID>", "operator": "EQUAL", "value": "Y" }],
+  "actions": [{
+    "prop": "hide",
+    "fields": [{ "fieldId": "<明细列ID>", "name": "明细列A", "dataKey": "", "fieldType": "Text", "isDetail": true }]
+  }]
+}
+```
+
+**怎么认出明细字段**：`form read` 的输出里，明细字段会标注所属明细表 —— 带 `明细表: xxx` 那些就是，照它填 `isDetail: true`。
+
 ### conditions（触发条件）
 
 多个条件之间是 **AND** 关系（全部满足才触发）。
@@ -121,7 +146,8 @@ e10-cli form linkage add <appId> <objId> <name> --config @<json文件>
 
 ## 注意事项
 
-1. **主表 vs 明细表**：主表触发字段可修改主表或明细字段；明细表触发字段只能修改本行字段
+1. **主表 vs 明细表**：主表触发字段可修改主表或明细字段；明细表触发字段只能修改本行字段。
+   目标落在明细表里时，`actions[].fields[]` 那个条目**必须带 `isDetail: true`**；不带的话这个目标会被当作主表字段提交
 2. **表格布局限制**：通过隐藏行/列/单元格自定义属性隐藏的字段，无法通过联动显示出来
 3. **明细表字段列隐藏**：需在明细表第一行配置操作按钮元素
 4. **多规则冲突**：避免同一个触发字段或同一个目标字段出现在多个规则里

package/skill-docs/references/menu/system-menus.md

@@ -61,3 +61,15 @@
 ```
 
 > **只有包含工作流的应用**才能挂载工作流系统页面。表单台账会自动挂入菜单，无需手动操作。
+
+---
+
+## 菜单是一棵树
+
+应用菜单不止一层：顶层之外还有 `children` 嵌套（例如平台自带的「设置 → 个人设置 → 个人菜单设置」、系统设置下的「基本信息 / 菜单设置」）。
+
+- `menu list <appId>` **递归展开**整棵树，输出带缩进；末尾会注明含多少个嵌套菜单。**这份列表就是全量**，在它里面找不到某个菜单，才能下结论说「该应用没有这个菜单」。
+- `menu rename <appId> <菜单ID或名称> <新名>` 按 ID 或名称定位，**嵌套里的菜单一样能改**。同名多条时命令会报歧义并列出候选 ID，不会替你挑一条。
+- 改名的命令会**重建写报文**再回读比对：名称变了、且「页面绑定 / 菜单 URL / 可见范围」等字段一个都没动，才算成功。改名只动名字，不会顺带改掉已有的筛选条件或页签配置。
+
+**平台系统菜单（回收站、设置及其子项）不能改名** —— 它们由平台维护、指向内置页面，改名没有语义，命令会直接拒绝。

package/skill-docs/references/workflow/guide-workflow-odoc.md

@@ -58,10 +58,17 @@ e10-cli workflow odoc setting set <workflowId> \
   --request-title-field "公文标题" \
   --upload-word 1 --upload-pdf 1 --upload-ofd 1 \
   --text-in-form 1 --column-position 1 \
-  --attach-area 1 --archive-node "归档"
+  --attach-area 1 --archive-node "归档" \
+  --open-text-select 2 \
+  --edit-text-node "发起节点" \
+  --ai-odoc 1 --ai-abstract 1 --ai-format 1
 ```
 
-字段参数支持字段名称或字段 ID，节点参数支持节点名称或节点 ID。平台开关值使用 `0` 和 `1`。
+字段参数支持字段名称或字段 ID，节点参数支持节点名称或节点 ID（名称在流程内重复时报错并给出候选 ID，不擅自挑一个）。平台开关值使用 `0` 和 `1`。
+
+- `--open-text-select` 默认打开正文节点的范围编码；`--open-text-node` 配合它指定具体节点（可多个，逗号或空格分隔）。
+- `--edit-text-node` 可编辑正文的节点，可多个。
+- `--ai-odoc` 公文助手总开关；`--ai-abstract` 智能摘要、`--ai-format` 智能排版 是它下面的两项，单独打开它们不会自动把总开关带上，需要一并给。
 
 ### 配置结构
 
@@ -74,3 +81,16 @@ e10-cli workflow odoc setting set <workflowId> \
 - AI 与格式：`openAiAbstract`、`openAiFormat`、`defaultFormatTemplate`、`showAiAssistant`、`showOfficialDoc`。
 
 保存请求携带完整公文设置，其中字段选择值为字段 ID、节点选择值为节点 ID，`signNodeList` 保存节点及其启用、必填状态。
+
+**回读的值不能直接写回去。** 平台读回来的形状和保存要的形状不一样，混用会直接被服务端拒掉（`400 Bad Request`）：
+
+| | 读取 | 保存 |
+|---|---|---|
+| 开关 | 布尔 `true` / `false` | 字符串 `"1"` / `"0"` |
+| 基本类型清单 | 数组 `["id1"]` / `[]` | 逗号串 `"id1"` / 空串 `""` |
+| 签章节点表 | 对象数组 | 对象数组，但**每个对象里的布尔同样要转成串** |
+| 节点清单字段（`editTextNode` 等） | 对象数组 `[{name,id}]` | 逗号串 `"id1,id2"` |
+
+分组的落法也分三种：`odocNumber` / `odocAttachArea` **整组保持嵌套**，`signNode` 组以 `signNodeList` 发出，其余分组的键**平铺**到顶层。这些转换由 CLI 自动完成，`--config` 里也按同样规则给值即可。
+
+`setting set` 保存后会**回读比对**，对不上会点名是哪个键没落库 —— 平台对报文形状不合法一律报 400，但对语义问题可能静默收下，读回来才算数。

package/skill-docs/references/workflow/guide-workflow.md

@@ -297,13 +297,28 @@ e10-cli workflow add-link <workflowId> <fromNodeId> <toNodeId> "退回" --reject
 e10-cli workflow add-link <workflowId> <fromNodeId> <toNodeId> "主线路" --default
 ```
 
-批量添加连线：
+批量添加连线（出口表混着退回线和默认出口时用这个）：
 ```bash
 e10-cli workflow add-links <workflowId> @links.json
-# links.json: [{"from":"nodeId","to":"nodeId","label":"发起→审批","reject":true,"default":false}]
+# links.json:
+# [
+#   {"from":"拟稿","to":"套红",       "label":"拟稿 至 套红",       "default":true},
+#   {"from":"部门经理审稿","to":"拟稿", "label":"部门经理审稿 退回 拟稿","reject":true}
+# ]
 ```
 
-> **多条连线用 `add-links`**：`add-link` 内部 fetch→修改→save，并行的会覆盖。`add-links` 按顺序逐条执行，每条都从服务端拉最新 XML 再改，不会丢数据。不要用 `&` 或 `parallel` 并跑 add-link。
+> **退回 / 默认出口逐条给**：`reject` / `default` 写在每条连线上；命令行上的 `--reject` / `--default`
+> 是给整批兜底的默认值，逐条给的值优先于它。
+>
+> **默认出口会自动让位**：指定某条为默认出口时，同一源节点上原有的默认出口会被自动取消，
+> 保证一个源节点只有一条默认出口。同一批里给同一源节点指定了两条默认出口会直接报错，
+> 不会静默留下两条。
+>
+> **多条连线用 `add-links`**：`add-link` 内部 read→改→save，并行的会互相覆盖。`add-links` 一次把整批
+> 拼好、一次保存，不会丢数据。不要用 `&` 或 `parallel` 并跑 add-link。
+>
+> 保存后 CLI 会**回读比对**：新连线的退回/默认标志与让位结果都对得上才算成功，
+> 对不上会直接报错退出，不会因为服务端回了「保存成功」就放过。
 
 ### 删除连线