weaver-e10-builder 1.6.16 → 1.7.1

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

@@ -1,151 +1,151 @@
-# 系统内置菜单 URL 参考
-
-通过 `savePublishMenu` API 挂载系统内置页面到应用菜单。menuUrl 格式固定，禁止瞎编。
-
-> **移动端菜单是另一套记录**：同一个 `savePublishMenu` 接口，只把 `terminalType` 换成 `H5`；页面绑定与 `menuUrl` 与 PC 相同。菜单命令统一用 `--terminal mobile` 指定移动端（缺省 PC），两端互不影响。
-> 移动端**内置系统页**的 URL 尚未整理，不要自行编造。
-
-## 别把对象页面加成外链
-
-`menu add` 写的是 LINK 菜单。平台自己的页面地址（`/sp/ebdfpage/viewport/<viewId>` 台账、`/sp/ebdfpage/card/1/<objId>/0` 表单新建页）当外链写进去只会存成一串 URL：设计器「链接地址」显示文本而不是「数据列表: 表单名」标签，移动端拿不到视图绑定，打开是空列表。
-
-- 台账（数据列表）入口 → `menu add-table <appId> <表单 objId>`
-- 表单发起入口 → `menu add-start <appId> <表单 objId>`
-
-`menu add` 遇到这两类地址会直接拒绝；确实要当外链才加 `--as-link`。
-
-## 把 PC 菜单同步到移动端
-
-```bash
-e10-cli menu sync <appId>
-```
-
-- 平台原生能力：「是否确认将PC端菜单同步至移动端？（此同步操作会覆盖已添加的菜单配置）」。
-- 同步会**整体覆盖**移动端菜单：移动端单独加过、PC 上没有的菜单会被清掉。
-- 同步范围是 PC 端的**业务菜单**（目录、外链、嵌套都带过去，顺序与层级照搬）；「设置」「回收站」这类系统菜单两端各管各的，不参与同步。
-- 命令保存后会回读移动端，与 PC 端逐条比对路径、层级与顺序；对不上会报错并点名缺失/多余项，不会把「没同步」说成成功。
-- PC 端一条业务菜单都没有时命令会拒跑（否则等于清空移动端）；确认要清空加 `--force`。
-
----
-
-## 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 / 可见范围」等字段一个都没动，才算成功。改名只动名字，不会顺带改掉已有的筛选条件或页签配置。
-
-**平台系统菜单（回收站、设置及其子项）不能改名** —— 它们由平台维护、指向内置页面，改名没有语义，命令会直接拒绝。
-
----
-
-## 菜单顺序
-
-平台按同级（同一个 `pid`）的 `showOrder` **升序**显示，同值再按菜单 id；系统菜单的 `showOrder` 是 `9999998/9999999`，所以总在最后。新建菜单默认 `showOrder=1`，因此会排到同级最后。
-
-- 创建时直接排第一：`menu add / add-dir / add-table / add-start`、`page publish-menu` 加 `--first`。
-- 创建时指定位置：`--show-order <n>`（整数，越小越靠前）。
-- 已建好的菜单调整：`e10-cli menu order <appId> <菜单ID或名称> --first`，或 `--show-order <n>`。
-
-命令在写完会回读：`showOrder` 必须落成请求值；`--first` 还会确认同级下标为 0。系统菜单不允许调整顺序。
-
----
-
-## 打开方式
-
-菜单点击后在哪儿打开，由 `navigation.openMode` 决定：
-
-| 界面选项 | 值 |
-|---|---|
-| 默认窗口（缺省） | `1` |
-| 新窗口 | `2` |
-
-- 新建时指定：`menu add / add-table / add-start`、`page publish-menu` 加 `--open-mode new-window`。
-- 已建好的菜单：`e10-cli menu open-mode <appId> <菜单ID或名称> new-window`（改回用 `default`）。
-- 上级目录（空链接）没有页面，设置打开方式没有意义，命令会拒绝。
-- 改完回读打开方式，并确认名字、页面、链接等其它字段一个都没动。
-
----
-
-## 可见范围（两栏）
-
-「可见范围」弹窗其实是**两栏**，各自一套授权对象：
-
-| 界面栏位 | 存储差异 |
-|---|---|
-| 可见 | `permissionType = 1` |
-| 可见范围内禁用 | `permissionType = -1` |
-
-两栏的写报文除这个字段外完全相同，所以命令必须显式分清栏位：
-
-```bash
-# 只让某部门可见（自动撤掉「所有人」）
-e10-cli menu permission add <appId> <menuId> 营销部 --type dept
-
-# 在可见人群里排除某人
-e10-cli menu permission add <appId> <menuId> 张三 --type user --scope disabled
-
-# 查看两栏
-e10-cli menu permission list <appId> <menuId>
-```
-
-授权对象五类：人员 `user` / 部门 `dept` / 角色 `role` / 岗位 `position` / 所有人 `all`。命令写完回读**同一栏**确认生效。
+# 系统内置菜单 URL 参考
+
+通过 `savePublishMenu` API 挂载系统内置页面到应用菜单。menuUrl 格式固定，禁止瞎编。
+
+> **移动端菜单是另一套记录**：同一个 `savePublishMenu` 接口，只把 `terminalType` 换成 `H5`；页面绑定与 `menuUrl` 与 PC 相同。菜单命令统一用 `--terminal mobile` 指定移动端（缺省 PC），两端互不影响。
+> 移动端**内置系统页**的 URL 尚未整理，不要自行编造。
+
+## 别把对象页面加成外链
+
+`menu add` 写的是 LINK 菜单。平台自己的页面地址（`/sp/ebdfpage/viewport/<viewId>` 台账、`/sp/ebdfpage/card/1/<objId>/0` 表单新建页）当外链写进去只会存成一串 URL：设计器「链接地址」显示文本而不是「数据列表: 表单名」标签，移动端拿不到视图绑定，打开是空列表。
+
+- 台账（数据列表）入口 → `menu add-table <appId> <表单 objId>`
+- 表单发起入口 → `menu add-start <appId> <表单 objId>`
+
+`menu add` 遇到这两类地址会直接拒绝；确实要当外链才加 `--as-link`。
+
+## 把 PC 菜单同步到移动端
+
+```bash
+e10-cli menu sync <appId>
+```
+
+- 平台原生能力：「是否确认将PC端菜单同步至移动端？（此同步操作会覆盖已添加的菜单配置）」。
+- 同步会**整体覆盖**移动端菜单：移动端单独加过、PC 上没有的菜单会被清掉。
+- 同步范围是 PC 端的**业务菜单**（目录、外链、嵌套都带过去，顺序与层级照搬）；「设置」「回收站」这类系统菜单两端各管各的，不参与同步。
+- 命令保存后会回读移动端，与 PC 端逐条比对路径、层级与顺序；对不上会报错并点名缺失/多余项，不会把「没同步」说成成功。
+- PC 端一条业务菜单都没有时命令会拒跑（否则等于清空移动端）；确认要清空加 `--force`。
+
+---
+
+## 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 / 可见范围」等字段一个都没动，才算成功。改名只动名字，不会顺带改掉已有的筛选条件或页签配置。
+
+**平台系统菜单（回收站、设置及其子项）不能改名** —— 它们由平台维护、指向内置页面，改名没有语义，命令会直接拒绝。
+
+---
+
+## 菜单顺序
+
+平台按同级（同一个 `pid`）的 `showOrder` **升序**显示，同值再按菜单 id；系统菜单的 `showOrder` 是 `9999998/9999999`，所以总在最后。新建菜单默认 `showOrder=1`，因此会排到同级最后。
+
+- 创建时直接排第一：`menu add / add-dir / add-table / add-start`、`page publish-menu` 加 `--first`。
+- 创建时指定位置：`--show-order <n>`（整数，越小越靠前）。
+- 已建好的菜单调整：`e10-cli menu order <appId> <菜单ID或名称> --first`，或 `--show-order <n>`。
+
+命令在写完会回读：`showOrder` 必须落成请求值；`--first` 还会确认同级下标为 0。系统菜单不允许调整顺序。
+
+---
+
+## 打开方式
+
+菜单点击后在哪儿打开，由 `navigation.openMode` 决定：
+
+| 界面选项 | 值 |
+|---|---|
+| 默认窗口（缺省） | `1` |
+| 新窗口 | `2` |
+
+- 新建时指定：`menu add / add-table / add-start`、`page publish-menu` 加 `--open-mode new-window`。
+- 已建好的菜单：`e10-cli menu open-mode <appId> <菜单ID或名称> new-window`（改回用 `default`）。
+- 上级目录（空链接）没有页面，设置打开方式没有意义，命令会拒绝。
+- 改完回读打开方式，并确认名字、页面、链接等其它字段一个都没动。
+
+---
+
+## 可见范围（两栏）
+
+「可见范围」弹窗其实是**两栏**，各自一套授权对象：
+
+| 界面栏位 | 存储差异 |
+|---|---|
+| 可见 | `permissionType = 1` |
+| 可见范围内禁用 | `permissionType = -1` |
+
+两栏的写报文除这个字段外完全相同，所以命令必须显式分清栏位：
+
+```bash
+# 只让某部门可见（自动撤掉「所有人」）
+e10-cli menu permission add <appId> <menuId> 营销部 --type dept
+
+# 在可见人群里排除某人
+e10-cli menu permission add <appId> <menuId> 张三 --type user --scope disabled
+
+# 查看两栏
+e10-cli menu permission list <appId> <menuId>
+```
+
+授权对象五类：人员 `user` / 部门 `dept` / 角色 `role` / 岗位 `position` / 所有人 `all`。命令写完回读**同一栏**确认生效。

package/skill-docs/references/report/add-dataset-registration-guide.md

@@ -1,161 +1,161 @@
-# 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` 会让报表复制 500）+ `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/共享表笔记） |
-| **C. 数据加工 SQL 视图** | `sourceType=eteams`（**必须小写**）+ `sourceGroup=sql` + `appid=<appId>` | `type:"eteams"`，`sourceGroup:"sql"` | 视图原字段名（如 `title`/`zymc`/`major_no`，**无 `field_` 前缀**） | **`(数据加工)`** | 数据集来自「数据加工」SQL 视图 |
-
-**禁止**：在普通应用里误用形态 B，再抱怨「没有 field_」——那是注册错了，不是 fieldsKey 坏了。
-
-> ⚠️ **形态 C 大小写门禁（2026-10-09 实证 · 应用 `1323883777452843010`）**：
-> `sourceType` **必须小写 `eteams`** + `sourceGroup=sql`，落库 `type="eteams"` → 面板/单元格显示 **`X(数据加工)`** ✅。
-> 若传大写 `ETEAMS`（或 sourceGroup 用 `-98`）→ 落库 `type="ETEAMS"`/`sourceGroup:"-98"` → 被当成 **`X(业务模块)`** ❌。
-> 同应用验证：`eteams`/`sql` 的 5 张表单元格全为 `X(数据加工)`；`ETEAMS`/`-98` 的 2 张表全为 `X(业务模块)`。
-
-> ⚠️ **`tableName` 后缀必须与注册形态一致**：形态 A → `(业务模块)`，形态 B → `(表单)`，形态 C → `(数据加工)`。
-> 后缀缺失或写错会导致左侧数据源不显示模块类型。
-> 详见 **`dataset-table-field-contract-guide.md`**（含 `FieldCellType` 必需字段全表 + 落库门禁）。
-
----
-
-## 二、设计器兼容的 addDataset（默认强制）
-
-```
-POST /api/bs/edc/report/addDataset
-Content-Type: multipart/form-data
-
-reportId     = {reportId}
-sourceType   = logic              // ★★ 必须小写！大写 LOGIC 会让报表「复制」500（见下方红框）
-sourceIds    = {sourceId}          // 表单/数据源 ID
-sourceName   = {裸名}              // ★ 传**裸名** `轻资产信息`（不带后缀）
-                                  //   面板显示名 = sourceName + (添加类型标签)，标签由平台按添加类型自动拼
-                                  //   旧口径「必须传 {表单名}(业务模块)」已于 2026-09-16 推翻（注意点 BUILD-36）
-appid        = {appId}             // 注意小写 appid（与设计器一致）
-sourceGroup  = weaver-ebuilder-form-service
-```
-> ★★ **`sourceType` 必须小写 `logic`（2026-09-15 实证 · 注意点 BUILD-29）**
-> 服务端会把入参**原样**写进 `edc_dataset_dev.type`：
-> - `sourceType=logic` → `type="logic"`（= 设计器口径）→ 报表「复制」**200**
-> - `sourceType=LOGIC` → `type="LOGIC"`（大写）→ 报表「复制」**500「报表内部错误」**（HTTP 仍 200）
->
-> 决定性实验：同应用同表单两张空壳，唯一差别就是这里的大小写 → 200 / 500。
-> CLI 侧已把默认值统一为小写（`dataset add --source-type` 默认 `logic`），**不要显式传大写**。
-> 存量注意报表：`e10-cli report copy-health`（诊断）→ `e10-cli report dataset heal --purge --apply`（原地换型修复）。
-
-> **回显名（2026-09-16 更正 · 注意点 BUILD-36）**：`sourceName` 写入 `edc_dataset_dev.name`，面板显示时为
-> **`{sourceName} + (添加类型标签)`** —— 所以 `sourceName` 要传**裸名** `轻资产信息`，面板才会显示 `轻资产信息(业务模块)`。
-> **旧说法「只传裸表单名会缺后缀、必须传 `轻资产信息(业务模块)`」已推翻**：那样写会让面板显示 **`轻资产信息(业务模块)(业务模块)`**。
-> 决定性对照（报表 `1315265856934289408`，同 sourceId 两条）：脚本建那条 `name="采购入库(业务模块)"` → 双后缀 ❌；
-> 设计器「+」那条 `name="采购入库"` → `采购入库(业务模块)` ✅。
-> 源合并后的 `tableText` 可能仍是 `轻资产信息(uf_xxx)`，与回显名不是同一字段——**以 `name` 为准**。
-> 存量脏值清理：`e10-cli report fix dataset-name --report-id <rid> --app-id <appId> [--apply]`。
-
-可选字段以设计器接口返回为准；**不得**把 `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 事故**）
-
-构建层 在 `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（`e10-cli report verify bind`）
-- [ ] 同 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」给出注册错误提示 |
+# 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` 会让报表复制 500）+ `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/共享表笔记） |
+| **C. 数据加工 SQL 视图** | `sourceType=eteams`（**必须小写**）+ `sourceGroup=sql` + `appid=<appId>` | `type:"eteams"`，`sourceGroup:"sql"` | 视图原字段名（如 `title`/`zymc`/`major_no`，**无 `field_` 前缀**） | **`(数据加工)`** | 数据集来自「数据加工」SQL 视图 |
+
+**禁止**：在普通应用里误用形态 B，再抱怨「没有 field_」——那是注册错了，不是 fieldsKey 坏了。
+
+> ⚠️ **形态 C 大小写门禁（2026-10-09 实证 · 应用 `1323883777452843010`）**：
+> `sourceType` **必须小写 `eteams`** + `sourceGroup=sql`，落库 `type="eteams"` → 面板/单元格显示 **`X(数据加工)`** ✅。
+> 若传大写 `ETEAMS`（或 sourceGroup 用 `-98`）→ 落库 `type="ETEAMS"`/`sourceGroup:"-98"` → 被当成 **`X(业务模块)`** ❌。
+> 同应用验证：`eteams`/`sql` 的 5 张表单元格全为 `X(数据加工)`；`ETEAMS`/`-98` 的 2 张表全为 `X(业务模块)`。
+
+> ⚠️ **`tableName` 后缀必须与注册形态一致**：形态 A → `(业务模块)`，形态 B → `(表单)`，形态 C → `(数据加工)`。
+> 后缀缺失或写错会导致左侧数据源不显示模块类型。
+> 详见 **`dataset-table-field-contract-guide.md`**（含 `FieldCellType` 必需字段全表 + 落库门禁）。
+
+---
+
+## 二、设计器兼容的 addDataset（默认强制）
+
+```
+POST /api/bs/edc/report/addDataset
+Content-Type: multipart/form-data
+
+reportId     = {reportId}
+sourceType   = logic              // ★★ 必须小写！大写 LOGIC 会让报表「复制」500（见下方红框）
+sourceIds    = {sourceId}          // 表单/数据源 ID
+sourceName   = {裸名}              // ★ 传**裸名** `轻资产信息`（不带后缀）
+                                  //   面板显示名 = sourceName + (添加类型标签)，标签由平台按添加类型自动拼
+                                  //   旧口径「必须传 {表单名}(业务模块)」已于 2026-09-16 推翻（注意点 BUILD-36）
+appid        = {appId}             // 注意小写 appid（与设计器一致）
+sourceGroup  = weaver-ebuilder-form-service
+```
+> ★★ **`sourceType` 必须小写 `logic`（2026-09-15 实证 · 注意点 BUILD-29）**
+> 服务端会把入参**原样**写进 `edc_dataset_dev.type`：
+> - `sourceType=logic` → `type="logic"`（= 设计器口径）→ 报表「复制」**200**
+> - `sourceType=LOGIC` → `type="LOGIC"`（大写）→ 报表「复制」**500「报表内部错误」**（HTTP 仍 200）
+>
+> 决定性实验：同应用同表单两张空壳，唯一差别就是这里的大小写 → 200 / 500。
+> CLI 侧已把默认值统一为小写（`dataset add --source-type` 默认 `logic`），**不要显式传大写**。
+> 存量注意报表：`e10-cli report copy-health`（诊断）→ `e10-cli report dataset heal --purge --apply`（原地换型修复）。
+
+> **回显名（2026-09-16 更正 · 注意点 BUILD-36）**：`sourceName` 写入 `edc_dataset_dev.name`，面板显示时为
+> **`{sourceName} + (添加类型标签)`** —— 所以 `sourceName` 要传**裸名** `轻资产信息`，面板才会显示 `轻资产信息(业务模块)`。
+> **旧说法「只传裸表单名会缺后缀、必须传 `轻资产信息(业务模块)`」已推翻**：那样写会让面板显示 **`轻资产信息(业务模块)(业务模块)`**。
+> 决定性对照（报表 `1315265856934289408`，同 sourceId 两条）：脚本建那条 `name="采购入库(业务模块)"` → 双后缀 ❌；
+> 设计器「+」那条 `name="采购入库"` → `采购入库(业务模块)` ✅。
+> 源合并后的 `tableText` 可能仍是 `轻资产信息(uf_xxx)`，与回显名不是同一字段——**以 `name` 为准**。
+> 存量脏值清理：`e10-cli report fix dataset-name --report-id <rid> --app-id <appId> [--apply]`。
+
+可选字段以设计器接口返回为准；**不得**把 `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 事故**）
+
+构建层 在 `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（`e10-cli report verify bind`）
+- [ ] 同 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」给出注册错误提示 |