weaver-work-cli 0.1.24 → 0.1.25

package/skills/weaver-e10-builder/references/hrm/guide-matrix.md

@@ -0,0 +1,245 @@
+# HRM 矩阵指南（条件矩阵 / 部门矩阵 / 分部矩阵）
+
+> 矩阵 = 「条件维度（行）→ 值维度（列）」的映射查询表。例如：部门 + 费用类型 → 审批人。用于流程中的矩阵对应操作者类型。
+
+## 命令参考
+
+### 矩阵管理
+
+| 命令 | 说明 |
+|------|------|
+| `e10-cli matrix create <name>` | 新建矩阵。`--type 0=分部/1=部门/2=自定义` `--desc` `--org-id` |
+| `e10-cli matrix update <id>` | 更新矩阵。`--name` `--desc` `--type` |
+| `e10-cli matrix list` | 查询矩阵列表。`--name` `--enable-status` `--org-id`。非 JSON 输出会标出「行随组织同步 / 行手工维护」「字段只读」 |
+| `e10-cli matrix config <id>` | 查看矩阵配置（条件字段 + 值字段） |
+| `e10-cli matrix config-edit <id>` | 编辑配置。`--value`（配合可选 `--condition`）或 `--config` 一次性提交。**`--condition` 可省略**，省略则沿用现有条件列 |
+| `e10-cli matrix enable <id>` | 启用矩阵 |
+| `e10-cli matrix disable <id>` | 停用矩阵 |
+| `e10-cli matrix delete <ids...>` | 删除矩阵。**矩阵里有数据行时平台会拒绝删除**（报"存在不能删除的矩阵"且不指出是哪个）——先 `matrix data delete <id> <rowIds...>` 清空数据行再删；批量删除时只要有**一条**不可删，整批都失败 |
+
+### 矩阵数据维护
+
+| 命令 | 说明 |
+|------|------|
+| `e10-cli matrix data list <matrixId>` | 分页查询矩阵数据行。`--condition` `--value` 过滤 |
+| `e10-cli matrix data save <matrixId> --rows @file` | 保存数据行（新增/修改）。简写: `[{rowId?, "字段configId":["实体ID"]}]` —— 带 `rowId` 为改该行，不带为新增 |
+| `e10-cli matrix data delete <matrixId> <ids...>` | 删除数据行 |
+| `e10-cli matrix data template <matrixId>` | 下载导入模板（Excel） |
+| `e10-cli matrix data import <matrixId> <file>` | 从 Excel 导入。`--mode add/cover` |
+
+---
+
+## 典型工作流
+
+```bash
+# 1. 创建矩阵（新建即启用；分权租户的所属机构自动取当前机构）
+e10-cli matrix create "审批人映射表" --type 2 --desc "部门→审批人"
+
+# 2. 查 ID
+e10-cli matrix list --name "审批人"
+
+# 3. 配字段（条件=部门，值=审批人）—— 直接可用，不需要先开设计器
+e10-cli matrix config-edit <matrixId> \
+  --condition '[{"type":"department","name":"所属部门"}]' \
+  --value '[{"type":"resource","name":"审批人","singleType":1}]'
+
+# 4. 启用
+e10-cli matrix enable <matrixId>
+
+# 5. 填数据
+echo '[{"<条件configId>":["<部门ID>"],"<值configId>":["<人员ID>"]}]' > rows.json
+e10-cli matrix data save <matrixId> --rows @rows.json
+
+# 6. 查数据
+e10-cli matrix data list <matrixId>
+
+# 7. 在流程中使用矩阵
+e10-cli workflow set-operator <wf> <nodeId> --type matrix \
+  --matrix-id <matrixId> --value-config-id <值configId> \
+  --matrix-rule "<条件configId>:1:1:1"
+```
+
+部门矩阵少一步 —— 条件列是平台建矩阵时自动给的，只配值列：
+
+```bash
+# 1. 建（--sync-depart = 界面上那个「从组织架构中同步部门」；行随组织同步，不可增删）
+e10-cli matrix create "部门负责人" --type 1 --sync-depart --desc "部门→负责人"
+
+# 2. 只配值列，--condition 省略（CLI 会沿用平台建好的「部门」条件列）
+e10-cli matrix config-edit <matrixId> \
+  --value '[{"type":"resource","name":"部门负责人","singleType":0}]'
+
+# 3. 看行 —— 同步型矩阵的行是组织架构带来的，行 id 就是部门 id
+e10-cli matrix data list <matrixId>
+
+# 4. 给某一行填值（带 rowId 才是改那一行，不带就是新增一行）
+echo '[{"rowId":"<部门id>","<值configId>":["<人员ID>"]}]' > rows.json
+e10-cli matrix data save <matrixId> --rows @rows.json
+```
+
+---
+
+## 行从哪来、字段能不能改：看 `syncType` 和 `permList`
+
+`matrix list --json` 每条记录带几个标记位。**不要拿 `sysType` 当判据** —— 它只说明是不是平台内置的，不决定能力：
+
+| 字段 | 取值 | 含义 |
+|---|---|---|
+| `type` | `0` / `1` / `2` | `0`=分部矩阵、`1`=部门矩阵、`2`=自定义矩阵 |
+| `syncType` | `1` / `0` | **行从哪来**。`1`=数据行随组织架构同步（**行不可增删，行 id 就是部门/分部 id**）；`0`=行手工维护（行 id 是平台发号的雪花） |
+| `permList` | 数组 | **含 `FIELD` 才能改字段配置**；不含就是字段只读（平台内置矩阵是这种） |
+| `sysType` | `1` / `0` | 是否平台内置。只影响名字语义，**不影响能做什么** |
+
+`matrix list` 的非 JSON 输出会直接把这两条标出来：`行随组织同步 / 行手工维护`、`字段只读`。
+
+同一租户里四个矩阵的对照，四个象限都出现过：
+
+| 矩阵 | type | sysType | syncType | permList 有 `FIELD` | 结果 |
+|---|---|---|---|---|---|
+| 平台内置的部门矩阵 | 1 | 1 | 1 | 否 | 行随组织同步、字段只读 |
+| 部门负责人矩阵 | 1 | 0 | 0 | 是 | 行手工维护、字段可改 |
+| 自建并勾了「同步部门」 | 1 | 0 | 1 | 是 | 行随组织同步、字段可改 |
+| 自建未勾同步 | 1 | 0 | 0 | 是 | 行手工维护、字段可改 |
+
+> **`type` 与 `syncType` 互相独立**：`type=1` 的部门矩阵既可以是同步的、也可以是手工维护的；创建时用 `--sync-depart` / `--sync-subcompany` 决定，事后也能用 `matrix update --sync-depart` 改。
+>
+> 不管哪种，**在流程里的用法完全一样**（都是 `workflow set-operator --type matrix`）。
+
+## 部门矩阵 / 分部矩阵：条件列是平台给的
+
+建部门矩阵（`matrix create <name> --type 1 --sync-depart`）时，平台会**自动把条件列建好**：
+
+```json
+"conditionConfigList": [
+  { "id": "<矩阵id + 1>", "name": "部门", "type": "department", "singleType": 1 }
+],
+"valueConfigList": []          ← 这才是你要配的
+```
+
+所以配列时**只给值列就行**，`--condition` 省略掉：
+
+```bash
+e10-cli matrix config-edit <matrixId> \
+  --value '[{"type":"resource","name":"部门负责人","singleType":0}]'
+```
+
+CLI 会把现有条件列原样带上（会打印一行 `ℹ 未指定条件列，已沿用现有的: 部门`）。
+
+> **别手写条件列。** 写一个不带 `id` 的 `{"type":"department","name":"部门"}` 进去，CLI 会当成新列去 `addField` 取号，结果矩阵里多出一条一模一样的「部门」列。
+>
+> 可用类型用 `GET /api/bs/hrm/matrix2/config/typeList?id=<matrixId>&matrixType=<0|1|2>` 查：部门矩阵返回 `conditionTypeList:[department]` / `valueTypeList:[resource]`。
+
+**所属机构与分权**：矩阵强制校验"所属机构"，而落到哪个字段由**分权状态**决定——分权开启时平台读 `belong_org_id`（归属机构），关闭时读 `targetId`。CLI 建矩阵前会自动查 `check-detach` 判断并选对字段，分权租户还会直接用返回的当前机构兜底，所以 `matrix create` 通常不用手写机构；只有"非分权租户"或"归属机构与目标机构必须不同"时才需要 `--org-id` / `--target-id`。
+
+**列表的状态过滤**：`matrix list` 走管理端点 `matrix2/list`，能看到**停用的矩阵**并显示真实状态；`--name`（模糊）、`--enable-status`、`--org-id` 都是服务端过滤。
+
+## 完整配置：条件列 → 人员列 → 数据映射 → 运行时读回
+
+```bash
+# ① 建矩阵（自定义矩阵。系统矩阵是平台内置的，用 matrix list 找现成的）
+#    新建即为「启用」状态，不需要再 enable；要停用才跑 matrix disable
+#    所属机构：分权租户自动取当前机构，非分权租户用 --org-id 显式指定（不加会有"所属机构不能为空"）
+e10-cli matrix create "部门审批人" --type 2 --desc "部门→审批人"
+
+# ② 配列：条件列 + 值列。值列 type=resource 就是"人员列"；singleType 0=多选 1=单选
+e10-cli matrix config-edit <matrixId> \
+  --condition '[{"type":"department","name":"所属部门"}]' \
+  --value '[{"type":"resource","name":"审批人","singleType":1}]'
+
+# ③ 取各列 configId（数据映射的键就是它），再填数据行
+e10-cli matrix config <matrixId>            # → conditionConfigList[].id / valueConfigList[].id
+e10-cli matrix data save <matrixId> --rows @rows.json
+e10-cli matrix data list <matrixId>         # 回读数据行
+
+# ④ 启用并挂到流程节点
+e10-cli matrix enable <matrixId>
+e10-cli workflow set-operator <wf> <nodeId> --type matrix \
+  --matrix-id <matrixId> --value-config-id <值列configId> \
+  --matrix-rule "<条件列configId>:1:1:1"
+
+# ⑤ 运行时读回：确认条件列/值列是否就是流程实际在读的那一组
+e10-cli matrix config <matrixId>
+```
+
+> **矩阵类型不用手填**：`--type matrix` 的 `sourceType` / 条件列中文名由 CLI 自动读 `GET /api/bs/hrm/matrix2/config?id=<matrixId>` 解析——`conditionConfigList[].type` 是 `department` 即部门矩阵、`subcompany` 即分部矩阵。条件列不在目标矩阵里时会直接报错并列出可选列，不会静默挂错。
+>
+> 排查"取不到人"时按这个顺序看：`matrix config`（列对不对）→ `matrix data list`（行有没有）→ 流程节点的矩阵规则是否引用了正确的 `条件configId`。
+
+## 字段类型枚举
+
+设计器「字段维护」里就这 **7 档**：
+
+| 中文 | API 值 |
+|------|--------|
+| 人员 | `resource` |
+| 部门 | `department` |
+| 分部 | `subcompany` |
+| 岗位 | `position` |
+| 客户 | `customer` |
+| 项目 | `project` |
+| 自定义浏览框 | `customBrowser` |
+
+## 自定义浏览框列
+
+条件列和值列都可以是**自定义浏览框**。它的读写形状**不一样**，这点最容易踩：
+
+| | 形状 |
+|---|---|
+| **写**（要发的） | `customBrowser:<浏览框富对象>` + `singleType` |
+| **读**（回来的） | `browserModule` + `browserType` + `configDetailDto{dataId,singleType}` + `showConfig` |
+
+平台**只认写的那个形状**：把读回来的三个键原样发回去，会被回「**自定义浏览框参数异常**」。所以：
+
+- **新建**一列时用浏览框**名字**指名即可，CLI 会去查回富对象：
+  ```json
+  { "type": "自定义浏览框", "name": "这里是显示名字", "browser": "测试自定义浏览框", "singleType": 0 }
+  ```
+  `browser` 也收完整对象（想直接贴 bean 就用 `customBrowser`）。名字**精确匹配**，同名多条或查不到都会报错并列候选。
+- **沿用**老列（省略 `--condition`）时，CLI 会按读回里的 `configDetailDto.dataId` **把富对象反查回来再发** —— 不需要你补；也不要手写 `browserType` / `configDetailDto`，发了会被拒。
+- `singleType`：`0` 多选 / `1` 单选（列底下那个「单选」勾选框）。自定义浏览框列默认 `0`。
+
+```bash
+e10-cli matrix config-edit <矩阵ID> \
+  --condition '[{"type":"部门","name":"所属门店"},{"type":"自定义浏览框","name":"合同","browser":"测试自定义浏览框"}]' \
+  --value '[{"type":"人员","name":"门店经理","singleType":1}]'
+```
+
+## config-edit 参数
+
+```json
+{
+  "id": "<矩阵ID>",
+  "conditionConfigList": [
+    { "id": "<现有条件列id>", "type": "department", "name": "显示名", "sort": 1 }
+  ],
+  "valueConfigList": [
+    { "id": "<现有值列id>", "type": "resource", "name": "显示名", "singleType": 1, "sort": 1 },
+    { "type": "resource", "name": "新加的列", "singleType": 0, "sort": 2 }
+  ],
+  "conditionDelList": [],
+  "valueDelList": []
+}
+```
+
+- `singleType`: 0=多选, 1=单选。值字段必传，条件字段可省（省了沿用现有的）。条件列在平台上**本身是必填的**，空着下发会被拒（「请至少维护一个条件字段」）。自定义浏览框列默认 0。
+- **自定义浏览框列**用 `"browser":"<浏览框名>"` 指名即可（CLI 查回富对象再发），详见上面「自定义浏览框列」一节。写 `browserType` / `configDetailDto` 这类**读回形状**会被平台拒。
+- **已有的列要带 `id`**（从 `matrix config` 拿）；不带 `id` 的会被当成新列去 `addField` 取号，**等于多建一列**。不带 id 但与现有列重名时 CLI 会告警。
+- **列 id 必须属于该矩阵**。传了别的矩阵的列 id，平台只回一句「系统内部错误」（NPE），CLI 会抢先报错并点名是哪一列。
+- ⚠ **保存是「按 id 合并」，不是整表替换**：没传的列**不会**被删（删列要走 `--value-del`）。所以「加一列」只传那一列就够了，不必把现有列全列一遍。
+- 保存后回读比对提交的列（在不在、名字对不对），平台回 200 但没按提交落库会直接报错。
+
+## data save 简写格式
+
+```json
+[
+  {"<条件configId>": ["<实体ID>"], "<值configId>": ["<实体ID>"]},
+  {"rowId": "<行id>", "<值configId>": ["<实体ID>"]}
+]
+```
+
+- 不带 `rowId` = 新增一行；带 `rowId`（或写作 `id`）= 改那一行。行 id 用 `matrix data list <matrixId>` 拿。
+- **改行只给要改的列就行**：平台是整行覆盖，CLI 会先读回该行、把没给的列补上再发。
+- 键不是该矩阵的列时直接报错并列出可用列，不会静默发出去。
+
+CLI 自动查 config 判断 `conditionAble` 标记并展开为完整格式；改过的行保存后会回读比对，平台回 200 但没按提交落库会直接报错。
+

package/skills/weaver-e10-builder/references/hrm/guide-org-employee.md

@@ -0,0 +1,155 @@
+# 组织架构 — 人员录入（Excel 批量导入）
+
+> **平台自己解析 Excel，CLI 只负责把文件送上去、把解析结果取回来** —— CLI 不解析单元格，
+> 也不想解析：字段映射、必填校验、主子表展开全在平台侧，CLI 自己解一遍只会跟平台不一致。
+
+## 命令
+
+| 命令 | 说明 |
+|------|------|
+| `e10-cli org employee template [--out <路径>]` | 导出人员导入模板（xlsx）。默认输出到当前目录的 `人员导入模板.xlsx` |
+| `e10-cli org employee import <file>` | 从 Excel 导入人员。`--dry-run` 只预览不导入；`--mode add\|update`（默认 `add`）；`--find-by <字段>`（更新时按哪个字段认人，默认 `username`）；`--review <n>` 预览行数（默认 100） |
+| `e10-cli org employee task <taskId>` | 查某个导入任务的结果（没等、或等超时了，用这个补看） |
+
+导入默认**等结果**：打完 `已导入 N 条 / 失败 M 条` 才结束，**有失败行时退出码非 0**，脚本可以直接判。
+
+| 选项 | 说明 |
+|---|---|
+| `--no-wait` | 提交后立刻返回。⚠ 不等就等于不校验 —— **「已提交」不代表导入成功**，要自己再用 `task` 查 |
+| `--wait-timeout <ms>` | 等结果的超时（默认 60000）。超时不编成功，如实报「仍在处理中」并给 taskId |
+| `--error-file <路径>` | 失败数据的保存路径。默认与源文件同目录、同名 + `.错误数据.xlsx` |
+| `--no-error-file` | 不保存失败数据文件（原因仍会打出来） |
+
+## 模板怎么填（三处最容易填错）
+
+模板第 2 个工作表「模板注意事项说明」里也写了这几条，这里挑出**填错代价最大**的三处：
+
+### 1. 「状态（必填）」列只认平台那几个词
+
+`试用` / `试用延期` / `正式` / `临时` / `实习` / `离职` / `退休` / `解聘` / `无效`，就这九个 ——
+填其它写法（比如 `1`、`在职`）**整行导入失败**。
+
+⚠ 别拿**动作流里「人员状态」**的 `1`（在职）/ `2`（离职）来填这一列，那是另一套取值，两者不通。
+
+### 2. 「密码」在第 35 列（AI 列）
+
+模板一共 63 列，密码夹在中间那段：
+`AH` 登录名 → **`AI` 密码** → `AJ` 解除账号 → `AK` 安全级别。
+填到隔壁的「安全级别」（第 37 列）**不会报错**，只是那人的密码没设上 —— 属于静默填错。
+
+### 3. 有上级/助理的人，拆两批导
+
+「上级」「其他上级」「助理」填的是**别人的姓名**，如果那个人也在这张表里，
+**同一批导入可能引用不到**。
+做法：**第一批只导没有任何上级/助理的人**，第二批再导引用他们的那些 ——
+不用改表结构，拆成两个文件依次导即可。
+
+- 「上级」列**只填一个人**；要挂多个上级用「其他上级」列，多个之间用 `,` 分隔。
+- 这几列按平台说明，必须是该上级/助理**「重复验证字段」**的值（编号、姓名选其一）。
+
+### 别忘了删示例行
+
+模板第 2~9 行是 `user001`~`user008` 的**演示数据**（平台自带的），**导入前整行删掉**，
+否则这几行会被当成真人建进组织里。
+
+## ⚠ 先 `--dry-run`，再真导
+
+批量写组织数据是**外部可见且不好撤销**的操作。导入前先干跑一次：
+
+```bash
+e10-cli org employee import 人员.xlsx --dry-run
+```
+
+干跑会打出**平台解析出来的**工作表名、列数、行数和前几行内容 —— 拿它跟你的原表对一遍，
+确认列没串、行数对得上（尤其是**模板自带的示例行要删掉**），再去掉 `--dry-run` 真导。
+
+`--dry-run` 停在「预览」这一步，**这一步之前不会往组织里写任何东西**。
+
+## 链路（七步，每步产出喂给下一步）
+
+| | 端点 | 产出 |
+|---|---|---|
+| ⓪ | `POST /api/bs/hrm/emp/edit/importParam` | `bizId` + moduleName / functionName / handlerName / serviceName / dataType |
+| ① | `POST /api/file/preUploadCheck`（multipart） | 预上传 id |
+| ② | `POST /api/file/module/upload`（multipart） | `fileId` |
+| ③ | `POST /api/ebatch/checkFilePassword` | — |
+| ④ | `POST /api/ebatch/uploadFileId` | `taskId` |
+| ⑤ | `POST /api/ebatch/getExcelData` | 预览行（**不落库**） |
+| ⑥ | `POST /api/ebatch/importExcelData` | 真正执行 |
+| ⑦ | `POST /api/ebatch/getByTaskId` | **导入结果**：条数 / 失败原因 / 错误文件 |
+
+- **⓪ 把 ④ 要的元数据全给了** —— moduleName / functionName / handlerName / serviceName / dataType
+  都不是 CLI 硬编码的，`bizId` 更是每次调用现生成。
+- **①② 的 multipart 字段逐字相同**，② 只多 `preUploadId` 与 `uploadType=common`。
+- ⑤⑥⑦ 的参数全在 **query string**，body 为空。
+
+## 导入结果（⑥ 只是「提交了」，结论在 ⑦）
+
+**⑥ 的响应体只有一个 `true`** —— 条数、失败原因、错误文件**全都不在里面**。只发 ⑥ 就报成功，
+会让**整批失败也显示成「导入已提交」**，所以命令发完 ⑥ 会去轮询 ⑦。
+
+```json
+{"status": -1,
+ "msg": "存在错误数据，下载错误文件查看",
+ "callbackData": "{\"msg\":\"导入失败\",\"errorFileId\":\"...\",\"module\":\"hrm\",\"successCount\":0,\"errorCount\":\"1\"}"}
+```
+
+- **`callbackData` 是一个 JSON 字符串**，要二次解析 —— 条数和错误文件 id 都在里面。
+- ⚠ **`successCount` 是数字、`errorCount` 是字符串**（`1` / `"0"`），同一段 JSON 里类型不一致，两边都得转一遍。
+- ⚠ **`status: 0` 不是「成功」** —— 它是个**中途值**：同一个任务先读到 `status: 0` + `msg: 成功`、
+  `callbackData` 还是空的，几秒后才落成 `-1` + 失败 1 条。**判完成的依据是 `callbackData` 能不能解出来，不是 `status`**；
+  按 `status` 收工就会把失败读成成功。
+- `status: -1` = 存在错误数据，可以直接当终态（命令也这么处理）。
+
+### 失败原因在**单元格批注**里，不在任何一列
+
+导出的失败数据文件里**只有出错的那几行，没有「原因」列** —— 用表格软件打开看值，看不出为什么失败。
+原因挂在**出错单元格的批注（Excel comment）**上，形态是：
+
+| 单元格 | 值 | 批注 |
+|---|---|---|
+| A2 | 人员A | **姓名 重复** |
+
+所以 `import` / `task` 会把批注读出来直接打给你：
+
+```
+导入结果: 人员A.xlsx
+  已导入     0 条
+  失败       1 条
+  平台说明   存在错误数据，下载错误文件查看
+  失败原因
+    第 2 行 · 姓名（人员A）: 姓名 重复
+  失败数据   1323916251655815168 → 人员A.错误数据.xlsx
+```
+
+### 失败数据怎么下来的
+
+```
+GET /api/file/remotedownload/<fileId>/token/true?authModule=ebatch
+  → 302 → 对象存储的签名地址（文件真身在这边，文件名也在这一步给）
+```
+
+下载按**两步**取：先带鉴权拿到 302，再**不带任何鉴权头**去对象存储取字节 ——
+会话凭证不跟着跳转发到第三方域名上。
+
+## 几个坑
+
+- **取 id 的层级三步三样**：① 在 `data.preUploadId`（**有的环境**是 `data.uploadModuleDto.fileid`）、
+  ② 在 `data.fileid`（**小写 d**）、④ 在 `data.data.taskId`（多一层）。照着别的接口的写法套会静默取到空。
+- **① 的返回形状随环境变**：有的环境 `preUploadCheck` 只回 `data.preUploadId`
+  （`data` 下就 `preUploadId` / `uploadType` / `permissionType` 三个键，**没有** `uploadModuleDto`）。
+  两种写法语义相同，命令都认；一个都没有才报错。只认其中一种的话，那条环境整条导入链**第①步就断**。
+- **⑤ 的参数是 `rerviewNum`** —— 平台把 review 拼错了，别"顺手改正"成 `reviewNum`。
+- **`weaTable[0].total` 是 `-1`**，不能拿来当行数；行数看 `data` 数组长度。
+- **`rerviewNum` 只是一次取多少行**，预览到的未必是全部 —— 行数刚好等于上限时命令会提示。
+- **⚠⚠ 分部名写错不会报错 —— 平台会静默新建一个分部，把人放进去。**
+  「分部（必填）」填一个机构里不存在的名字（例如把「泛微北京」写成「泛微北金」），导入**照样回成功**，
+  然后机构里会多出一个同名分部（父级 = 操作者所在组织），人落在里面。**没有报错、没有警告**，
+  `--dry-run` 的预览也看不出来 —— 预览只是把单元格原样回显，**不做任何校验**。
+  所以：**分部名必须是机构里已有的名字**，导之前自己核一遍 —— 一次手误就是一条脏组织数据 + 一个错位的人。
+- **`importType` 在 ④ 的报文里出现两次**：顶层是空串、真正生效的在 `uploadSet.customObj` 里。
+
+## 环境差异
+
+`emp/edit/importParam` 是判定「这个环境能不能导入人员」的探针 —— 返回里没有 `bizId` / `functionName`
+就说明该环境不支持，命令会直接报错，不会带着半截参数往下走。

package/skills/weaver-e10-builder/references/menu/system-menus.md

@@ -0,0 +1,75 @@
+# 系统内置菜单 URL 参考
+
+通过 `savePublishMenu` API 挂载系统内置页面到应用菜单。menuUrl 格式固定，禁止瞎编。
+
+> **暂不支持 H5/移动端菜单**。移动端是独立体系（不同 URL + 不同 pageId），目前尚未整理完整，禁止 AI 自行编造。
+
+---
+
+## PC 端菜单
+
+### 工作流页面 (pageType: WORKFLOW)
+
+| 菜单名 | pageId | menuUrl |
+|--------|--------|---------|
+| 待办流程 | todo | `/sp/ebdfpage/workflow/{appId}_todo` |
+| 已办流程 | done | `/sp/ebdfpage/workflow/{appId}_done` |
+| 我提交的流程 | mine | `/sp/ebdfpage/workflow/{appId}_mine` |
+| 共享给我的流程 | share | `/sp/ebdfpage/workflow/{appId}_share` |
+| 下属的待办流程 | subordinates | `/sp/ebdfpage/workflow/{appId}_subordinates` |
+| 全部流程 | all | `/sp/ebdfpage/workflow/{appId}_all` |
+| 草稿流程 | draft | `/sp/ebdfpage/workflow/{appId}_draft` |
+| 流程监控 | monitor | `/sp/ebdfpage/workflow/{appId}_monitor` |
+
+### 独立页面（不跟 appId）
+
+| 菜单名 | pageId | menuUrl |
+|--------|--------|---------|
+| 提交申请 | newflow | `/sp/ebdfpage/ebflowpage/create/` |
+
+### 其他系统页面
+
+| 菜单名 | pageId | pageType | menuUrl |
+|--------|--------|----------|---------|
+| 我的关注 | followList | BASE | `/sp/ebdfpage/followlist/{appId}` |
+| 共享给我的 | shareList | BASE | `/sp/ebdfpage/sharelist/{appId}` |
+
+---
+
+## 用法
+
+```json
+{
+  "content": "待办流程",
+  "menuType": "1",
+  "page": {
+    "pageId": "todo",
+    "pageName": "待办流程",
+    "pageType": "WORKFLOW",
+    "appid": "{appId}"
+  },
+  "menuUrl": "/sp/ebdfpage/workflow/{appId}_todo",
+  "shareMap": [{
+    "id": "0",
+    "content": "所有人",
+    "permissionId": "sys_view",
+    "targetType": 11,
+    "sourceType": 1,
+    "objIdList": ["所有人"]
+  }]
+}
+```
+
+> **只有包含工作流的应用**才能挂载工作流系统页面。表单台账会自动挂入菜单，无需手动操作。
+
+---
+
+## 菜单是一棵树
+
+应用菜单不止一层：顶层之外还有 `children` 嵌套（例如平台自带的「设置 → 个人设置 → 个人菜单设置」、系统设置下的「基本信息 / 菜单设置」）。
+
+- `menu list <appId>` **递归展开**整棵树，输出带缩进；末尾会注明含多少个嵌套菜单。**这份列表就是全量**，在它里面找不到某个菜单，才能下结论说「该应用没有这个菜单」。
+- `menu rename <appId> <菜单ID或名称> <新名>` 按 ID 或名称定位，**嵌套里的菜单一样能改**。同名多条时命令会报歧义并列出候选 ID，不会替你挑一条。
+- 改名的命令会**重建写报文**再回读比对：名称变了、且「页面绑定 / 菜单 URL / 可见范围」等字段一个都没动，才算成功。改名只动名字，不会顺带改掉已有的筛选条件或页签配置。
+
+**平台系统菜单（回收站、设置及其子项）不能改名** —— 它们由平台维护、指向内置页面，改名没有语义，命令会直接拒绝。

package/skills/weaver-e10-builder/references/report/add-dataset-registration-guide.md

@@ -0,0 +1,139 @@
+# addDataset 注册契约 · `field_` 前缀门禁（强制）
+
+> **事故（已验证 · 报表 `1312765120721813505`）**
+> 同一 `sourceId=972019393600233477`（轻资产信息）：
+> - **Agent/API 加的数据集** `1312765120721813506`：`type=form` + `sourceGroup=<appId>` → `fieldsKey.name` 业务字段为**裸雪花**（无 `field_`）
+> - **设计器手动「+」加的数据集** `1312794545670627330`：`type=logic` + `sourceGroup=weaver-ebuilder-form-service` → `fieldsKey.name` 业务字段为 **`field_{雪花}`**
+>
+> **遗漏点不在「写 Field 时忘加 field_」**，而在 **`addDataset` 注册参数与设计器不一致**，导致权威 `fieldsKey` 本身就没有 `field_`。
+> 后续若按设计器习惯臆造 `field_`，或绑错到「裸雪花」那份 dataset，会出现保存 500 / 取数失败 / 与用户手动数据集字段名对不齐。
+
+---
+
+## 一、两种注册形态（必须分清）
+
+| 形态 | 典型 `addDataset` | `dataset/list` 特征 | 业务字段 `fieldsKey.name` | `tableName` 后缀 | 何时用 |
+|------|-------------------|---------------------|---------------------------|------------------|--------|
+| **A. 设计器默认（LOGIC）** | `sourceType=LOGIC`（或 `logic`）+ `sourceGroup=weaver-ebuilder-form-service` + `appid=<appId>` | `type:"logic"`，`sourceGroup:"weaver-ebuilder-form-service"` | **`field_{雪花}`** | **`(业务模块)`** | **普通应用表单（默认强制）** |
+| **B. 共享表 / form 契约** | `sourceType=form` + `sourceGroup=<appId>` | `type:"form"`，`sourceGroup` 等于 appId | 常为**裸雪花** | **`(表单)`** | 仅「xxx-共享表」类应用且已验证必须用此契约时（见 MEMORY/共享表笔记） |
+
+**禁止**：在普通应用里误用形态 B，再抱怨「没有 field_」——那是注册错了，不是 fieldsKey 坏了。
+
+> ⚠️ **`tableName` 后缀必须与注册形态一致**：形态 A → `(业务模块)`，形态 B → `(表单)`。
+> 后缀缺失或写错会导致左侧数据源不显示模块类型。
+> 详见 **`dataset-table-field-contract-guide.md`**（含 `FieldCellType` 必需字段全表 + 落库门禁）。
+
+---
+
+## 二、设计器兼容的 addDataset（默认强制）
+
+```
+POST /api/bs/edc/report/addDataset
+Content-Type: multipart/form-data
+
+reportId = {reportId}
+sourceType = LOGIC
+sourceIds = {sourceId} // 表单/数据源 ID
+sourceName = {显示名} // **回显名强制**：`{表单名}(业务模块)`，如 `轻资产信息(业务模块)`；禁止只传裸表单名
+appid = {appId} // 注意小写 appid（与设计器一致）
+sourceGroup = weaver-ebuilder-form-service
+```
+> **回显名（已验证）**：`sourceName` 写入 `edc_dataset_dev.name`，左侧回显应为 **`xxx(业务模块)`**。
+> 只传 `轻资产信息` 会缺后缀；源合并后的 `tableText` 可能仍是 `轻资产信息(uf_xxx)`，与回显名不是同一字段——**以 `name`=sourceName 为准**。
+
+可选字段以设计器实际请求为准；**不得**把 `sourceGroup` 写成 appId，除非走 §一 形态 B。
+
+`addDataset` **不返回** datasetId → 短轮询：
+
+```
+GET /api/bs/edc/dataset/list?hasField=true&reportId={reportId}
+```
+
+按 **sourceId** 命中；若同 sourceId 多条，**优先选** `sourceGroup=weaver-ebuilder-form-service` / `type=logic` 那条。
+
+### 2.1 同源只挂一次（**强制 · 2026-09-11 事故**）
+
+`spec_lib.resolveDataset()` 在 `addDataset` **之前**先查 `dataset/list`：
+
+| 场景 | 行为 |
+|------|------|
+| 本报表已有同 `sourceId` 数据集 | **复用**（`datasetReused=true`），**不再 addDataset** |
+| 发现同源 ≥2 条 | 回传 `datasetDuplicates[]` + WARN（左侧会出现重复分组） |
+| 传了别的报表的 `datasetId` | 忽略 + WARN（禁止跨报表复用） |
+
+> 事故：同一表单被 `addDataset` 挂载两次（`type=LOGIC` 与 `type=logic` 各一条），
+> 且画布上两个单元格引用第二条 → 设计器左侧出现**两个同名数据源分组**。
+> 未先去重就继续绑字段，会让「绑到哪一份数据源」变得不可预测。
+> 清理顺序见 `dataset-sidebar-ops-guide.md §5.3`（**先改绑/清单元格 → 再 delDataset**）。
+
+---
+
+## 三、addDataset 后强制门禁（遗漏即本事故）
+
+`fieldsAndOriginFields?isFront=true` 拿到 `fieldsKey` 后立刻检查：
+
+```javascript
+const biz = fieldsKey.filter(
+ (f) => /^\d{15,}$/.test(f.name) || /^field_\d{15,}$/.test(f.name)
+);
+const withPrefix = biz.filter((f) => String(f.name).startsWith('field_')).length;
+const bare = biz.filter((f) => /^\d{15,}$/.test(f.name)).length;
+
+// 普通应用（非共享表 form 契约）：业务字段应多数带 field_
+if (!isSharedFormContract && biz.length > 0 && bare > withPrefix) {
+ throw new Error(
+ 'addDataset 注册错误：fieldsKey 业务字段为裸雪花（无 field_）。' +
+ '应使用 sourceType=LOGIC + sourceGroup=weaver-ebuilder-form-service；' +
+ 'delDataset 后重建，禁止在 Field 上凭记忆加 field_ 前缀凑数。'
+ );
+}
+```
+
+| 检查 | 通过标准 |
+|------|----------|
+| 普通应用 | 业务字段 `field_` 数量 **≥** 裸雪花数量（通常裸雪花应为 0） |
+| 共享表 form 契约 | 允许裸雪花；**禁止**再擅自加 `field_` |
+| 同 sourceId 已有手动 LOGIC 数据集 | **绑定/取 fieldsKey 必须用那条**；勿继续用旧的 form+appId 脏注册 |
+
+失败处理：
+
+1. `POST /api/bs/edc/report/delDataset` 删掉错误注册
+ - form：`reportId=<报表ID>` · **`sourceIds=<datasetId>`**（参数名历史遗留，**不是**表单 sourceId）
+ - 建议先 `GET /api/bs/edc/dataset/checkDataSetUsed?reportId=&datasetId=`；CLI：`e10-cli report dataset delete`
+ - 完整侧栏操作见 `dataset-sidebar-ops-guide.md`
+2. 按 §二 重新 `addDataset`
+3. 再拉 `fieldsKey`，确认出现 `field_*`
+4. 再写 Field / `saveReportDevInfo`
+
+---
+
+## 四、与「字段精确绑定」的关系
+
+| 步骤 | 规则 |
+|------|------|
+| 1 注册 | 本指南：让 `fieldsKey` **先**变成设计器同款（含 `field_`） |
+| 2 绑定 | `field-bind-exact-match-guide.md`：`name` **逐字等于** 当前 dataset 的 `fieldsKey.name` |
+| 3 禁止 | 注册错了却在 cell 上「手工补 `field_`」；或注册对了却去前缀 |
+
+**一句话**：`field_` 不是 Agent 写 Field 时发明的，是 **正确 addDataset 之后 fieldsKey 自带的**。
+
+---
+
+## 五、自检清单
+
+- [ ] `addDataset` 使用 `sourceType=LOGIC` + `sourceGroup=weaver-ebuilder-form-service`（除非共享表契约）
+- [ ] `dataset/list` 回读该条 `type/sourceGroup` 与设计器一致
+- [ ] `fieldsKey` 业务字段已出现 `field_*`（普通应用）
+- [ ] Field.`name` / fieldKey 末段 ∈ **该** dataset 的 fieldsKey（`verify_field_bind.js`）
+- [ ] 同 sourceId 多实例时，未误绑到旧的 form+appId 裸雪花数据集
+
+---
+
+## 六、相关文档
+
+| 文档 | 关系 |
+|------|------|
+| `field-bind-exact-match-guide.md` | 绑定名权威来源；前置依赖本指南的注册正确 |
+| `api-report-build-fast-path.md` | 建表流程步骤 2 / 2.1 门禁 |
+| `report-designer-feature-map.md` §六 | 设计器「+」对应 addDataset 参数 |
+| `e10-cli report verify bind` | 交付校验；并对「裸雪花 fieldsKey」给出注册错误提示 |