weaver-e10-builder 1.5.16 → 1.6.4

package/skill-docs/references/coding/guide-form-crud.md

@@ -1,262 +1,285 @@
 # 表单数据操作指南
 
-Ebuilder 项目没有后端，但可以通过读写 Ebuilder 的表单来实现数据交互。所有 CRUD 接口已实现在 `/api/formApi.js` 中。
+Ebuilder 项目没有后端，页面通过读写 Ebuilder 表单完成增删改查。所有表单数据操作都走 `api/formApi.js` 里的 `formClient`，页面不要再直接调用数据集接口，也不要自己拼 `mainTable` 或转换 ID / 名称。
 
-> 应用已注册的表单信息及字段用 `e10-cli form read <objId> --app-id <appId> --out fields.json` 导出（机器可读 JSON），为空说明还没注册。
+> 表单元数据用 `e10-cli form read <objId> --app-id <appId> --out fields.json` 导出。字段 ID 以导出结果为准，不要自己编。
 
 ---
 
-## 〇、非对称设计（读写分离）
+## 一、先准备字段常量
 
-**这是整份指南最核心的概念，每次写表单页面之前必须理解。**
+`formClient` 只认字段 ID。页面里先用短名映射，避免到处散落长数字：
 
-`getSimpleData` 对所有特殊类型（Select / RadioBox / CheckBox / Employee / Department / FileComponent）**统一返回 ID**（`fieldOptionId`）。好处是写入简单——直接拿 ID 原样写入，不用做任何转换。代价是展示麻烦——ID 是长数字，用户完全看不懂。
-
-```
-写入路径（简单）：getSimpleData → form 直接用 ID → saveFormData/updateFormData
-展示路径（复杂）：getSimpleData → ID → 映射为名称 → 表格渲染
+```js
+// app/fields.js
+export var F = {
+  name: '4765111450482898127',
+  status: '4765111450482898155',
+  owner: '4765111450482898160'
+};
 ```
 
-**不同字段类型，名称来源不同**：
+`F` 的 value 必须来自 `fields.json` 的 `fieldId`，不是字段名、不是选项 ID。
 
-| 字段类型 | getSimpleData 返回值 | 名称来源 |
-|---------|---------------------|---------|
-| 普通文本/数字/日期 | `"名称"` / `123` / `"2026-01-01"` | 直接展示 |
-| Select / RadioBox / CheckBox | `"1283421826353889337"`（ID） | `getFieldOptions` 映射 `valueKey → name` |
-| Employee / Department | `"5140559860850691459"`（用户ID） | `getAllData` 提取 `fieldOptionName` |
-| FileComponent | `"fileid1,fileid2"`（文件ID串） | 上传组件的 `name` 字段 |
+---
 
-> **铁律：表格里永远不要直接渲染 `row[字段ID]`。** 用户看到一列长数字 = 你漏掉了名称转换。
+## 二、创建客户端
 
----
+```js
+// 模块顶层调用一次
+import { formClient } from '../api/formApi.js';
+import { APP_ID, OBJ_ID } from '../app/config.js';
 
-## 一、四个 API 的职责
+var items = formClient({ objId: OBJ_ID, appId: APP_ID });
+```
 
-| API | 职责 |
-|-----|------|
-| `getAllData` | 做源（含 `fieldOptionName`，用于提取名称信息） |
-| `getSimpleData` | 做读写（纯 ID，不含名称） |
-| `withDisplayNames` | 做展示（ID → 名称转换） |
-| `getFieldOptions` | 做下拉（拿 `valueKey` + `name`） |
+- `objId`：表单的 objId。
+- `appId`：当前 Ebuilder 应用 ID。写操作会带 `ebbusinessid` 请求头。
+- 同一个 `objId + appId` 只创建一次，字段和选项缓存会复用。
+- **不要放在组件 render 里反复调用。**
 
 ---
 
-## 二、核心规则：读取用 ID，展示用名称
+## 三、行数据形状
 
-**最容易出错的点，每次编码前务必理解：**
+`list` / `get` 返回的每一行固定是：
 
-`getSimpleData` 对所有特殊类型（Select/RadioBox/CheckBox/Employee/Department/FileComponent）**统一返回 ID**（`fieldOptionId`），读写一致。
+```js
+{
+  id: '数据ID',
+  values:  { 字段ID: '写入用的值/ID' },
+  display: { 字段ID: '展示用名称' },
+  items:   { 字段ID: [{ id, name }] },
+  details: { detail1: [...] },
+  raw: 平台原始行
+}
+```
 
-> 写完代码逐条自检，90% 的 bug 都是这几个：
-> 1. `if (row[roomField] === '101')` — Select 字段值是 `fieldOptionId`（长数字如 `"1283421826353889337"`），永远不等于选项名称
-> 2. `{row[empField]}` 直接渲染 — Employee/Department 返回的是长数字 ID，人名需从 `getAllData` 提取 `fieldOptionName`
-> 3. 表格里直接显示 `row[fieldId]` — 用户看到一列长数字。展示用 `withDisplayNames()`
+| 用途 | 用哪个 |
+|---|---|
+| 表单回填、保存、更新 | `values` |
+| 表格、详情展示 | `display` |
+| 人员 / 部门 / 附件选择器回显 | `items` |
+| 明细表 | `details` |
+| 平台原始报文 | `raw`（一般不用） |
 
-- **写入保存** → 直接用 `getSimpleData` 的返回值，所有字段都是 ID，无需转换
-- **表格展示** → 用 `withDisplayNames()` 把 ID 转成名称，否则用户看到的是数字
+旧的四函数（`getSimpleData` / `getAllData` / `withDisplayNames` / `getFieldOptions`）不再作为页面写法；`formClient` 已经把这些能力收进了统一入口。
 
 ---
 
-## 三、读取表单数据
-
-### 3.1 getSimpleData — 获取简单格式数据
+## 四、读取列表
 
 ```js
-import { getSimpleData } from '../api/formApi.js';
-const CONFIG = {
-  objId: '12556432068......',
-  userId: TEAMS.currentUser.id
-};
-const data = await getSimpleData(CONFIG.objId, CONFIG.userId);
-```
+var page = await items.list({ page: 1, size: 20 });
 
-返回格式：
-```js
-[
-  {
-    "4765111450482898127": "具体的数据内容",
-    "4765111450482898155": "具体的数据内容",
-    "id":"1259017552222814208"  // 表单数据固有的数据ID字段，fieldId固定为"id"
-  },
-  {.....}
-]
+page.rows;    // 行数组
+page.total;   // 总数；平台没返回时为 null
 ```
 
-`getSimpleData` 返回的是扁平对象，字段 ID 作为 key 直接挂载在行上，**没有 `_raw` 层**。直接用 `item[字段ID]` 访问。
-
-> 注意：Table 组件的 `onRowClick` 回调参数中会带 `_raw`（引用原始数据行），仅在编辑回显等场景通过回调参数访问，不要主动去构造 `_raw`。
-
-### 3.2 withDisplayNames — ID → 名称转换（表格展示用）
+带条件：
 
-用于在表格中把 Select/Employee/Department 等字段的 ID 转成可读名称。
-
-推荐写法：
 ```js
-import { getSimpleData, withDisplayNames, getFieldOptions } from '../api/formApi.js';
-
-function TemplatePage() {
-  const [data, setData] = useState([]);
-  const [loading, setLoading] = useState(true);
-
-  useEffect(function () {
-    Promise.all([
-      getSimpleData(CONFIG.objId, CONFIG.userId),
-      // 为每个需要展示名称的 Select 字段调用 getFieldOptions
-      getFieldOptions(F.status, OBJ_ID),
-    ]).then(function ([rows, statusOpts]) {
-      setData(withDisplayNames(rows, { [F.status]: statusOpts }));
-    }).catch(function () {})
-      .finally(function () { setLoading(false); });
-  }, []);
-  // ......
+var page = await items.list({
+  page: 1,
+  size: 20,
+  filter: { [F.status]: statusOptionId }   // 多个条件之间是 AND
+});
 ```
 
-### 3.3 getFieldOptions — 获取选项列表
-
-动态获取 Select/RadioBox/CheckBox 字段的可选值：
+带明细：
 
 ```js
-import { getFieldOptions } from './api/formApi.js';
+var page = await items.list({ page: 1, size: 20, withDetail: true });
+page.rows[0].details;   // 原始明细行，按平台 detail1/detail2 分组
 ```
 
-返回结构：
-```js
-[
-    {
-        "valueKey": "1263421826353889337",
-        "name": "已入职"
-    },{
-        "valueKey": "1263421826353889338",
-        "name": "已离职"
-    }
-]
-```
+> `filter` 的值必须是写入值（Select 用选项 ID，Employee 用人员 ID）。如果某个字段过滤不生效，先用 `items.list()` 拉一页确认该字段的 `values` 实际值，再对照平台接口确认过滤格式。
 
 ---
 
-## 四、字段类型对应组件
+## 五、读一条
 
-`form read --out fields.json` 导出的字段列表会告诉你每个字段的类型和 ID，有一些特殊的类型你必须选用对应的组件进行输入：
+```js
+var row = await items.get(dataId);
+var rowWithDetail = await items.get(dataId, { withDetail: true });
+
+if (!row) {
+  // 数据不存在或已被删除
+}
+```
 
-| 字段类型 | 对应组件 |
-|---------|---------|
-| Employee | `Browser` — 人员选择框（`module="hrm" type="resource"`） |
-| Department | `Browser` — 部门选择框（`module="hrm" type="department"`） |
-| FileComponent | `Upload` — 文件上传（参考 `references/components/form-Upload.md`） |
+列表已经拿到行时，优先直接复用该行，不要为了编辑再请求一次。
 
 ---
 
-## 五、数据写入
+## 六、新增、修改、删除
 
-### 5.1 formData 格式
+> `formClient` 写入时会先读一次 `ds/fields`，把字段 ID 转成平台 request key（自定义字段用 `config.dataKey`），再发 `v2/saveFormData` / `v2/updateFormData`。页面仍然只用字段 ID，不需要自己拼 request key。
 
-**一定是字段 ID 作为 key 的格式**，字段 ID 是纯数字组成的字符串，不包含任何其他符号。必须对照 `form read --out fields.json` 导出的字段来写，不要自己编造。
+### 新增
 
-```
-{
-  "4765111450482898127": "数据内容1",
-  "4765111450482898155": "数据内容2"
-}
+```js
+var newId = await items.save({
+  [F.name]: '测试物品',
+  [F.status]: statusOptionId
+});
 ```
 
-### 5.2 三个写接口
+`save` 返回平台生成的数据 ID；没有返回时为空字符串，可重新 `list` 确认。
+
+### 修改
 
-**新增：**
 ```js
-export async function saveFormData(objId, formData, userId)
+await items.update(row.id, {
+  [F.name]: '新名称'
+});
 ```
 
-**更新（多一个 dataId 参数）：**
+只传需要修改的字段。字段联动依赖完整值时，传整行 `row.values`。
+
+### 删除
+
 ```js
-export async function updateFormData(objId, formData, dataId, userId)
+await items.remove(row.id);
 ```
 
-**删除：**
+### 明细表
+
+读取时加 `withDetail: true`：
+
 ```js
-export async function deleteFormData(objId, dataId, userId)
+var page = await items.list({ page: 1, size: 20, withDetail: true });
+var row = await items.get(dataId, { withDetail: true });
+
+row.details;      // 平台原始明细行，按 detail1 / detail2 分组
+row.detailRows;   // 已解析：detail1: [{ id, values, display, items, raw }]
 ```
 
-### 5.3 调用方式
+写入：
 
 ```js
-if (editingId) {
-  promise = updateFormData(OBJ_ID, formToSave, editingId, USER_ID);
-} else {
-  promise = saveFormData(OBJ_ID, formToSave, USER_ID);
-}
+await items.save(values, {
+  details: {
+    [DETAIL_SUB_FORM_ID]: [
+      { [D.name]: '明细一', [D.quantity]: 2 }
+    ]
+  }
+});
+
+await items.update(dataId, values, {
+  details: { [DETAIL_SUB_FORM_ID]: detailRows },
+  detailMode: 'cover'   // cover=整表覆盖；不传=平台默认追加
+});
 ```
 
-### 5.4 写入时直接使用 form 的值（已全部为 ID）
+- 明细键用 **`subFormId`**（稳定），不要硬编码 `detail1` / `detail2`；平台节点名可能随布局顺序变化。
+- `formClient` 内部会按 `getTableMapping` 解析节点，并把明细字段 ID 转成 request key；页面不用自己拼。
+- 编辑回显用 `row.detailRows[DETAIL_SUB_FORM_ID]` 的 `values`；`row.details` 只保留平台原始节点数据。
+- 不传 `detailMode` 时平台按追加处理；编辑整表通常用 `cover`。
+
+---
 
-`getSimpleData` 对所有特殊类型（Select/Employee/Department/FileComponent）统一返回 ID。编辑保存时无需跳过任何字段，`form` 中的值可直接写入。
+## 七、字段选项
 
-```js
-var formToSave = {};
+Select / RadioBox / CheckBox 的下拉选项：
 
-// 所有字段统一处理，getSimpleData 已返回 ID
-Object.keys(form).forEach(function (key) {
-  var val = form[key];
-  if (val !== '' && val !== null && val !== undefined) {
-    formToSave[key] = val;
-  }
-});
+```js
+var opts = await items.options(F.status);
+// [{ id, valueKey, name }]
 
-// 用户操作选择器时用新值覆盖
-if (selectedPerson.length > 0) {
-  formToSave[F.person] = selectedPerson[0].id;
-}
-if (selectedDept.length > 0) {
-  formToSave[F.dept] = selectedDept[0].id;
-}
-if (uploadedFiles.length > 0) {
-  formToSave[F.attachment] = uploadedFiles.map(function (f) { return f.fileid; }).join(',');
-}
+var statusId = await items.optionId(F.status, '已完成');
+var statusIds = await items.optionIds(F.status, ['待处理', '已完成']);
+var nameToId = await items.optionMap(F.status);
 ```
 
+- 写入用 `valueKey`（与 `id` 同值）。
+- 有中文名时用 `optionId` / `optionIds`，不要在页面里自己维护「选项名 → ID」映射。
+- 找不到选项会直接报错并列出可选名称，不会静默写入。
+- 展示优先用行里的 `display`，不需要为了展示再拉一次选项。
+- `options` / `optionMap` 按字段缓存，页面里重复调用不会重复请求。
+
 ---
 
-## 六、三个高频编码错误
+## 八、字段类型与值
 
-编写 Ebuilder 页面时，以下三个错误非常高发，生成代码前务必检查：
+| 字段类型 | `values` | `display` | `items` |
+|---|---|---|---|
+| Text / TextArea / Number / Date | 字符串/数字 | 原值 | 无 |
+| Select / RadioBox / CheckBox | 选项 ID；多选用逗号串 | 选项名称；多选用逗号分隔 | `[{id,name}]` |
+| Employee / Department | 人员/部门 ID；多值逗号串 | 姓名/部门名 | `[{id,name}]` |
+| FileComponent | 文件 ID 串 | 文件名 | `[{id,name}]`（`id` 即 fileid） |
+| Ebuilder / Browser / RelateBrowser | 关联数据 ID | 显示名 | `[{id,name}]` |
 
-### 错误 1：数据访问用错层级
+**铁律：**
 
-`getSimpleData` 返回的每一行直接用 `item[字段ID]`，**没有 `_raw` 层**。
+1. 写入只认 `values`，不要拿 `display` 里的中文名回写。
+2. 表格里只渲染 `display`，不要直接渲染 `values`，否则用户看到长数字。
+3. 人员 / 部门 / 附件组件回显用 `items`，不要自己拆 `raw`。
+4. 多选值统一是逗号串。`formClient` 会把数组自动归一化成逗号串，但不要依赖它掩盖错误；页面状态里也直接用逗号串。
+5. **同名字段在不同表单可能不是同一种类型**。例如“拍卖范围”在登记表是组织多选（逗号 ID），在台账是文本（顿号中文名）。跨表复用常量前逐表 `form read`，不要按字段名推断。
+6. 写日期/时间不要统一一种格式；平台按字段自身的 `format` 校验，同一表单可能同时存在 `yyyy-MM-dd`、`yyyy-MM-dd HH:mm`、`yyyy-MM-dd HH:mm:ss`。
 
-```js
-// 错误
-var title = item._raw[F.title];
+---
 
-// 正确
-var title = item[F.title];
-```
+## 九、写完回读
 
-### 错误 2：Select 字段用名称做判断
+平台有三类静默失败：选项写名字、字段类型/格式不匹配、字段有数据不允许删除。**接口 200 不等于写对**。
 
-`getSimpleData` 对 Select/RadioBox/CheckBox 字段返回的是**选项 ID**（`fieldOptionId`，即 `valueKey`），如 `"1283421826353889337"`，不是显示名称。
+新增后读回：
 
 ```js
-// 错误
-if (item[F.status] === '已完成') { ... }  // 显示名称永远不匹配
+var newId = await items.save(values);
+var saved = await items.get(newId);
 
-// 正确
-if (item[F.status] === '1283421826353889337') { ... }  // 用选项 ID
+if (!saved) {
+  throw new Error('保存成功但没有读到记录');
+}
+if (saved.values[F.status] !== values[F.status]) {
+  throw new Error('状态回读不一致：写入 ' + values[F.status] + '，读回 ' + saved.values[F.status]);
+}
 ```
 
-**表格中显示名称**请使用 `withDisplayNames()`，不要在表格列渲染时逐行查 ID。
+修改后同样用 `items.get(id)` 比对关键字段；有明细时加 `withDetail: true`，检查 `row.detailRows[DETAIL_SUB_FORM_ID]` 的行数和值。
 
-### 错误 3：React state 直接修改
+页面至少要把不一致显示出来，不要只提示“保存成功”。
 
-直接修改对象属性再 `setForm` 不会触发 React 重新渲染。
+---
+
+## 十、错误处理
+
+`formClient` 的读写失败都会抛 `Error`，`message` 是平台返回的可读原因：
 
 ```js
-// 错误
-form[F.name] = value;
-setForm(form);
-
-// 正确
-var newForm = {};
-Object.keys(form).forEach(function (k) { newForm[k] = form[k]; });
-newForm[F.name] = value;
-setForm(newForm);
+items.save(values).then(function () {
+  // 成功
+}).catch(function (err) {
+  setError(err.message);
+});
 ```
+
+页面不要吞掉错误；至少展示给用户或写进页面状态。
+
+---
+
+## 十一、高级项
+
+- `save(values, { triggerAction: true })` / `update(id, values, { triggerAction: true })`：让平台执行数据动作。默认不触发；这个开关的取值要先在当前环境确认，再用于生产。
+- `items.fields()`：读取字段定义，返回按 `number` 排序的 `mainFields`。一般用 `fields.js` 常量即可，动态表单才需要。
+- `items.get(id, { withDetail: true })`：详情页直接按 ID 读，不用先拉整张表。
+
+---
+
+## 十二、页面自检
+
+- [ ] `formClient` 在模块顶层创建，没有放进 render
+- [ ] 字段 ID 来自 `fields.json`，没有手写短数字
+- [ ] 列表只渲染 `display`，写入只用 `values`
+- [ ] Select 写入用 `optionId` / `valueKey`，不是中文名
+- [ ] 多选写入是逗号串，没有把数组原样发出去
+- [ ] 日期/时间按字段自身格式写，没有统一套一种格式
+- [ ] 人员/部门/附件回显用 `items`
+- [ ] 列表带 `page/size`，没有默认 10 条就以为没数据
+- [ ] 写操作有 `.catch`，错误能显示出来
+- [ ] 写完用 `get` 回读并比对关键字段
+- [ ] 明细用 `subFormId`，没有硬编码 `detail1`
+- [ ] 明细写入前先用 `withDetail: true` 看过真实行形状