weaver-e10-builder 1.6.14 → 1.6.16

package/skill-docs/references/form/guide-form-physical-table.md

@@ -1,148 +1,148 @@
-# 多物理表（一个表单的字段分散到多张物理表）
-
-设计器里「表单 → 字段管理」有三个页签：**主表 | 明细表 | 其他**。本文说的是**「其他」** —— 同一个表单的字段分散在多张**物理表**上。
-
-## 什么时候用
-
-**字段数过多时的容量兜底**（单表字段超过 100 个左右）。正常表单用不到，属于偶尔一用的结构级能力。业务上要「一行对多行」请用**明细表**，那是另一回事（见 `guide-form-sub-detail.md`）。
-
-## ⚠ 和「明细表」是两根轴，别混
-
-| | 明细表 | **物理表（本文）** |
-|---|---|---|
-| 建表命令 | `form add-detail-table` | **`form add-physical-table`** |
-| 加字段命令 | `form add-field --sub-form-id` | **`form add-physical-field`** |
-| 建表端点 | `saveSubForm` | **`saveFormTable`** |
-| 标志 | `isSubForm: true` | **`isSubForm: false`** |
-| `tableType` | `MAIN` | **`SUBSIDIARY`** |
-| 布局里 | `DetailTable` 组件 | 无（不自动进布局，见下） |
-| 语义 | 一对多业务建模 | 一个表单自己的字段拆到多张表 |
-
-## 命令
-
-> **前置条件：主表至少要有一个业务字段。** 主表空着就建附属物理表，后续加字段/排布局会互相打架，命令会直接拦截并提示先 `form add-field`。
-
-```shell
-# 1) 列出表单的全部物理表（含主表）—— 忘掉 formTableId 时就用它
-e10-cli form physical-table list <objId> <appId>
-
-# 2) 建一张附属物理表 —— 输出 formTableId，后面都要用它
-e10-cli form add-physical-table <objId> <appId> \
-  --name 物理表A \
-  --table-name uf_ryxxb_6_1
-
-# 3) 往那张表里加字段（任意类型，能力同 form add-field）
-e10-cli form add-physical-field <objId> <appId> <formTableId> <字段名> <类型> [标题] [选项]
-
-# 4) 改名
-e10-cli form rename-physical-table <objId> <appId> <formTableId> \
-  --name 新名字 --table-name uf_ryxxb_6_1
-
-# 5) 删除（可一次删多张；表里的字段一并删除，不可逆）
-e10-cli form delete-physical-table <objId> <appId> <formTableId...>
-```
-
-`add-physical-field` 的选项与 `form add-field` 同名同义（`--precision` / `--format` / `--default` / `--data-key` / `--column-name` / `--multiple` / `--option-template` / `--browser-type` / `--sform-id` …）—— 两者**共用同一份字段构造器**，所以字段形状是同一套，不存在「这个命令能建那个命令不能建」的差异。
-
-| 参数 | 说明 |
-|---|---|
-| `--name <名>` | 物理表**显示名**，设计器里那排 chip 上的字 |
-| `--table-name <名>` | **数据库表名**（如 `uf_ryxxb_6_1`）。⚠ 平台的建议命名规则未抓到报文，**必填**；改名时也要原样回传 |
-
-## 表 id 从哪来
-
-建表输出里就带着：
-
-```
-物理表已建: 物理表A  formTableId=1323895867900731392  tableName=uf_ryxxb_6_1
-```
-
-事后想找回，用 `form physical-table list`（走 `getFormAGroupList`，就是设计器那排 chip 的数据源）：
-
-```
-$ e10-cli form physical-table list 1323898521989193728 1323897873591762945
-表单 1323898521989193728 共 3 张物理表:
-  多物理表测试表单  [主表]  formTableId=1323898521989193731  库表=uf_dwlbcsbd_5766  字段2
-  表1  [附属]  formTableId=1323898595055067136  库表=uf_dwlbcs_t1  字段3
-  表2  [附属]  formTableId=1323898612300947456  库表=uf_dwlbcs_t2  字段3
-```
-
-⚠ 注意这只列**物理表**。`form detail-table list`（走 `querySubForms`）是另一回事，只列**明细表**。
-
-字段**归属**也随时可读：`form read <objId> --app-id <appId>` 每个字段后面会带 `· 物理表: 表1`。
-
-> 读 `getFormAGroupList` 时别碰那条记录里的 `id` 键 —— 它是 **formId**，`formTableId` 才是表 id。这个子系统里 `id` 反复是这个陷阱。
-
-## ⚠ `add-physical-field` **不碰布局**
-
-字段建在这张物理表上，但**不会自动进表单布局**——它是否需要在布局里出现、怎么放，尚未抓到报文。别默认它已经挂在表单上了；要不要进布局请在设计器里确认。
-
-（`form add-field` 会做布局插入，是因为它落在主表/明细表这些**本来就在布局里**的落点上。）
-
-## 报文契约
-
-### 建表 / 改名 —— 同一个端点，带不带 `id` 决定是哪种
-
-```
-POST /api/ebuilder/form/form/field/manage/saveFormTable?apid=<appId>
-header ebbusinessid: <formId>
-```
-
-```json
-{"module":"ebuilderform",
- "formTable":{"id":"<表id：改名时带，新建时不带>",
-              "name":"物理表A",
-              "tableName":"uf_ryxxb_6_1",
-              "tableType":"SUBSIDIARY",
-              "form":{"id":"<formId>"},
-              "otherProperties":"{}"},
- "customParam":{"appId":"...","objId":"..."}}
-```
-
-响应：`{"code":200,"status":true,"data":{"formTableId":"..."}}` —— 新表的 id 在 `data.formTableId`。
-
-### 加字段 —— **不是**批量端点
-
-```
-POST /api/ebuilder/form/form/field/manage/saveFormFieldNew
-body {"formId":...,"module":"ebuilderform","jsonObj":"{... 带 \"formTableId\":\"<表id>\" ...}"}
-```
-
-字段落点由 **jsonObj 里的 `formTableId`** 决定。这条与「建表时连字段一起建」的 `batch/save/formField` + `formTableList` **不是同一条路**。
-
-### 删表
-
-```
-POST /api/ebuilder/form/form/field/manage/deleteFormTable?apid=<appId>
-body {"module":"ebuilderform","formId":"<formId>","ids":["<表id>"],"customParam":{...}}
-```
-
-### 列表（`form physical-table list`）
-
-```
-POST /api/ebuilder/form/form/field/manage/getFormAGroupList?apid=<appId>
-body {"module":"ebuilderform","formId":"<formId>","customParam":{...}}
-```
-
-响应 `data.formList[]` 每条：`name`（显示名）/ `tableName` / `tableType`（`MAIN` | `SUBSIDIARY`）/ `formTableId` / `systemTable` / `dataCount`；
-另外 `data.groupList[]` 是字段分组。**主表也在 `formList` 里**（`tableType: MAIN`）。
-
-⚠ 记录里的 `id` 键是 **formId**，不是表 id。
-
-## 踩过的两条坑（都别再走）
-
-**1. 不能把已有字段搬到另一张表。** 试过把字段的 `formTableId` 改成新表再整份写回，平台明确拒绝：
-
-```
-【备注】此字段不属于当前物理表，不能更改位置
-```
-
-所以**别指望「字段超 100 之后把老字段挪走」**——至少这条路径不行。能做的只有：**一开始就把新字段建到新表上**。这也解释了设计器的真实用法：先建附属表，后续新增的字段直接落在它上面。
-
-**2. 平台会对形状不认的字段回 `200` 但静默不落库。** 在 `batch/save/formField` 那条路上，`DateTime` / `Percent` / `Browser` 三种就是这样——接口回成功，字段根本没建出来。所以 `add-physical-field` **每次写完都回读确认**，「接口回 200」不等于「建上了」。带配置的类型（如 Select 的选项）建完再用对应命令补。
-
-## 注意事项
-
-1. **删除不可逆**，表里的字段一并删除。执行前先确认表 id。
-2. **`--table-name` 必填**。设计器用的是 `uf_<表单名拼音>_<n>_<m>` 这类命名，但规则没抓到报文，CLI 不替你猜 —— 重名/非法由平台报错（`此表的数据库表名称与数据库现有表存在冲突`）。
-3. **建完的空表照样存在**于「其他」页签里；要清掉用 `delete-physical-table`。
+# 多物理表（一个表单的字段分散到多张物理表）
+
+设计器里「表单 → 字段管理」有三个页签：**主表 | 明细表 | 其他**。本文说的是**「其他」** —— 同一个表单的字段分散在多张**物理表**上。
+
+## 什么时候用
+
+**字段数过多时的容量兜底**（单表字段超过 100 个左右）。正常表单用不到，属于偶尔一用的结构级能力。业务上要「一行对多行」请用**明细表**，那是另一回事（见 `guide-form-sub-detail.md`）。
+
+## ⚠ 和「明细表」是两根轴，别混
+
+| | 明细表 | **物理表（本文）** |
+|---|---|---|
+| 建表命令 | `form add-detail-table` | **`form add-physical-table`** |
+| 加字段命令 | `form add-field --sub-form-id` | **`form add-physical-field`** |
+| 建表端点 | `saveSubForm` | **`saveFormTable`** |
+| 标志 | `isSubForm: true` | **`isSubForm: false`** |
+| `tableType` | `MAIN` | **`SUBSIDIARY`** |
+| 布局里 | `DetailTable` 组件 | 无（不自动进布局，见下） |
+| 语义 | 一对多业务建模 | 一个表单自己的字段拆到多张表 |
+
+## 命令
+
+> **前置条件：主表至少要有一个业务字段。** 主表空着就建附属物理表，后续加字段/排布局会互相打架，命令会直接拦截并提示先 `form add-field`。
+
+```shell
+# 1) 列出表单的全部物理表（含主表）—— 忘掉 formTableId 时就用它
+e10-cli form physical-table list <objId> <appId>
+
+# 2) 建一张附属物理表 —— 输出 formTableId，后面都要用它
+e10-cli form add-physical-table <objId> <appId> \
+  --name 物理表A \
+  --table-name uf_ryxxb_6_1
+
+# 3) 往那张表里加字段（任意类型，能力同 form add-field）
+e10-cli form add-physical-field <objId> <appId> <formTableId> <字段名> <类型> [标题] [选项]
+
+# 4) 改名
+e10-cli form rename-physical-table <objId> <appId> <formTableId> \
+  --name 新名字 --table-name uf_ryxxb_6_1
+
+# 5) 删除（可一次删多张；表里的字段一并删除，不可逆）
+e10-cli form delete-physical-table <objId> <appId> <formTableId...>
+```
+
+`add-physical-field` 的选项与 `form add-field` 同名同义（`--precision` / `--format` / `--default` / `--data-key` / `--column-name` / `--multiple` / `--option-template` / `--browser-type` / `--sform-id` …）—— 两者**共用同一份字段构造器**，所以字段形状是同一套，不存在「这个命令能建那个命令不能建」的差异。
+
+| 参数 | 说明 |
+|---|---|
+| `--name <名>` | 物理表**显示名**，设计器里那排 chip 上的字 |
+| `--table-name <名>` | **数据库表名**（如 `uf_ryxxb_6_1`）。⚠ 平台的建议命名规则未抓到报文，**必填**；改名时也要原样回传 |
+
+## 表 id 从哪来
+
+建表输出里就带着：
+
+```
+物理表已建: 物理表A  formTableId=1323895867900731392  tableName=uf_ryxxb_6_1
+```
+
+事后想找回，用 `form physical-table list`（走 `getFormAGroupList`，就是设计器那排 chip 的数据源）：
+
+```
+$ e10-cli form physical-table list 1323898521989193728 1323897873591762945
+表单 1323898521989193728 共 3 张物理表:
+  多物理表测试表单  [主表]  formTableId=1323898521989193731  库表=uf_dwlbcsbd_5766  字段2
+  表1  [附属]  formTableId=1323898595055067136  库表=uf_dwlbcs_t1  字段3
+  表2  [附属]  formTableId=1323898612300947456  库表=uf_dwlbcs_t2  字段3
+```
+
+⚠ 注意这只列**物理表**。`form detail-table list`（走 `querySubForms`）是另一回事，只列**明细表**。
+
+字段**归属**也随时可读：`form read <objId> --app-id <appId>` 每个字段后面会带 `· 物理表: 表1`。
+
+> 读 `getFormAGroupList` 时别碰那条记录里的 `id` 键 —— 它是 **formId**，`formTableId` 才是表 id。这个子系统里 `id` 反复是这个陷阱。
+
+## ⚠ `add-physical-field` **不碰布局**
+
+字段建在这张物理表上，但**不会自动进表单布局**——它是否需要在布局里出现、怎么放，尚未抓到报文。别默认它已经挂在表单上了；要不要进布局请在设计器里确认。
+
+（`form add-field` 会做布局插入，是因为它落在主表/明细表这些**本来就在布局里**的落点上。）
+
+## 报文契约
+
+### 建表 / 改名 —— 同一个端点，带不带 `id` 决定是哪种
+
+```
+POST /api/ebuilder/form/form/field/manage/saveFormTable?apid=<appId>
+header ebbusinessid: <formId>
+```
+
+```json
+{"module":"ebuilderform",
+ "formTable":{"id":"<表id：改名时带，新建时不带>",
+              "name":"物理表A",
+              "tableName":"uf_ryxxb_6_1",
+              "tableType":"SUBSIDIARY",
+              "form":{"id":"<formId>"},
+              "otherProperties":"{}"},
+ "customParam":{"appId":"...","objId":"..."}}
+```
+
+响应：`{"code":200,"status":true,"data":{"formTableId":"..."}}` —— 新表的 id 在 `data.formTableId`。
+
+### 加字段 —— **不是**批量端点
+
+```
+POST /api/ebuilder/form/form/field/manage/saveFormFieldNew
+body {"formId":...,"module":"ebuilderform","jsonObj":"{... 带 \"formTableId\":\"<表id>\" ...}"}
+```
+
+字段落点由 **jsonObj 里的 `formTableId`** 决定。这条与「建表时连字段一起建」的 `batch/save/formField` + `formTableList` **不是同一条路**。
+
+### 删表
+
+```
+POST /api/ebuilder/form/form/field/manage/deleteFormTable?apid=<appId>
+body {"module":"ebuilderform","formId":"<formId>","ids":["<表id>"],"customParam":{...}}
+```
+
+### 列表（`form physical-table list`）
+
+```
+POST /api/ebuilder/form/form/field/manage/getFormAGroupList?apid=<appId>
+body {"module":"ebuilderform","formId":"<formId>","customParam":{...}}
+```
+
+响应 `data.formList[]` 每条：`name`（显示名）/ `tableName` / `tableType`（`MAIN` | `SUBSIDIARY`）/ `formTableId` / `systemTable` / `dataCount`；
+另外 `data.groupList[]` 是字段分组。**主表也在 `formList` 里**（`tableType: MAIN`）。
+
+⚠ 记录里的 `id` 键是 **formId**，不是表 id。
+
+## 踩过的两条坑（都别再走）
+
+**1. 不能把已有字段搬到另一张表。** 试过把字段的 `formTableId` 改成新表再整份写回，平台明确拒绝：
+
+```
+【备注】此字段不属于当前物理表，不能更改位置
+```
+
+所以**别指望「字段超 100 之后把老字段挪走」**——至少这条路径不行。能做的只有：**一开始就把新字段建到新表上**。这也解释了设计器的真实用法：先建附属表，后续新增的字段直接落在它上面。
+
+**2. 平台会对形状不认的字段回 `200` 但静默不落库。** 在 `batch/save/formField` 那条路上，`DateTime` / `Percent` / `Browser` 三种就是这样——接口回成功，字段根本没建出来。所以 `add-physical-field` **每次写完都回读确认**，「接口回 200」不等于「建上了」。带配置的类型（如 Select 的选项）建完再用对应命令补。
+
+## 注意事项
+
+1. **删除不可逆**，表里的字段一并删除。执行前先确认表 id。
+2. **`--table-name` 必填**。设计器用的是 `uf_<表单名拼音>_<n>_<m>` 这类命名，但规则没抓到报文，CLI 不替你猜 —— 重名/非法由平台报错（`此表的数据库表名称与数据库现有表存在冲突`）。
+3. **建完的空表照样存在**于「其他」页签里；要清掉用 `delete-physical-table`。