cloud-web-corejs 1.0.54-dev.72 → 1.0.54-dev.721

package/src/components/xform/XFormTabContainer//346/226/260/345/242/236/351/241/265/347/255/276/346/250/241/345/274/217-/350/220/275/345/234/260/345/256/236/346/226/275/346/226/207/346/241/243.md

@@ -0,0 +1,232 @@
+# xform 表单「新增页签模式」落地实施文档
+
+> 本文在 `新增页签模式实现方案.md`（方案设计）基础上，**逐条对照实代码核实**后形成的落地版。
+> 所有行号锚点均已在当前代码中验证；对方案中标为"风险待验证"的透传链路给出确认结论。
+> 目标：去掉固定「常规」页签承载新增 → 新增打开独立可关闭页签（标题"新增"）→ 保存后本页变编辑态（标题变单号）→ 提交（启动流程）后可配置「关闭页签回列表刷新」或「刷新本页」。
+
+---
+
+## 一、需求拆解
+
+| # | 需求 | 语义 |
+|---|------|------|
+| 1 | 去掉常规 | 启用本模式后，新增不再走固定「常规」页签（`name="first"`）；列表页签保留，新增走**动态可关闭页签** |
+| 2 | 新增打开页签（页签名"新增"） | 点「新增」→ 新开标题"新增"的可关闭页签，渲染新增表单（`addFormCode`） |
+| 3 | 保存后刷新本页变编辑态（页签名为单号） | 保存成功后：当前页签标题由"新增"改为返回单号（`res.objx`）；`dataId` 更新；`formCode` 切 `editFormCode`；表单重载进编辑态。**不新开页签、不切列表** |
+| 4 | 提交（启动流程）后可配置 | 新增 `submitBehavior` 枚举：`closeToList`（关闭当前页签→切列表→刷新列表）/ `refreshCurrent`（刷新当前页签，保持编辑态） |
+
+---
+
+## 二、代码锚点（均已核实，行号为当前代码）
+
+| 锚点 | 位置 | 核实结论 |
+|------|------|---------|
+| 「常规」页签定义 | `views/user/form/view/list.vue:10` | `<el-tab-pane :label="$t2('常规')" name="first">` ✅ |
+| `openEditDialog` | `views/user/form/view/list.vue:269` | 现有 `multiTabEnabled && dataId` 分支在 `:302`，新增(`!dataId`)走 else ✅ |
+| `reload` | `views/user/form/view/list.vue:346` | 存在，保存后经此回调 ✅ |
+| `formConfig` 默认值 | `components/xform/form-designer/designer.js`（含 `multiTabEnabled`/`multiTabLabelField`） | 在此加 3 个字段 |
+| 配置 UI 分组 | `components/xform/form-designer/setting-panel/form-setting.vue` | 加新 collapse 分组 |
+| `saveDefaultHandle` | `components/xform/mixins/defaultHandle.js:153` | success 里调 `reloadForm({updateParam:{dataId:res.objx, formCode:editFormCode}})`（`:190`）✅ |
+| `saveAndSubmitWfHandle` | `components/xform/mixins/defaultHandle.js:113` | `openStartWfDialog(formRef,{...})`（`:141`）当前**未传** `onStartSuccess` ✅ |
+| `switchToListTab` | `components/xform/form-render/indexMixin.js:2774` | 切列表页签并 `reloadForm()` 刷新 ✅ |
+| `getListPageRef` | `components/xform/form-render/indexMixin.js:2734` | 存在 ✅ |
+| `reloadForm` | `components/xform/form-render/indexMixin.js:2792` | 存在，透传 updateParam ✅ |
+| `openStartWfDialog` | `components/wf/wfUtil.js:242` | 把整个 `option` 塞进 wfStartDialog propsData（`:255`）✅ |
+| `startSubmitHanlde` | `components/wf/wf.js:1817` | `:1836-1839` 读 `this.option.onStartSuccess` 分支，无则 `$baseReload()` ✅ |
+| x-tabs API | `components/vb-tabs/x-tabs.vue` | `openEditTab`(`:49`)、`removeTab`(`:82`)、`activeName`/`tabName` ✅ |
+
+### ⭐ 关键修正（相对方案文档）
+
+方案文档把「`onStartSuccess` 是否从 `openStartWfDialog` 透传到 `startSubmitHanlde`」列为**最大风险、需先验证**。实代码追踪结论：**已透传、能跑通**：
+
+```
+defaultHandle → openStartWfDialog(formRef, option)
+  └─ wfUtil.js:255  propsData.option = option（整体传入 wfStartDialog）
+       └─ wf.js:1820 let option = this.option
+            └─ wf.js:1836-1839  option.onStartSuccess ? option.onStartSuccess() : $baseReload()
+```
+
+**因此：改造点 4 只需在 `saveAndSubmitWfHandle` 的 `openStartWfDialog` 调用里多传一个 `onStartSuccess`；方案里的"改造点 5 改 wf.js"不需要。**
+
+---
+
+## 三、配置项设计（新增 3 个 formConfig 字段）
+
+| 字段 | 类型 | 默认 | 含义 | 依赖 |
+|------|------|------|------|------|
+| `addTabEnabled` | Boolean | `false` | 本模式总开关。开启后新增打开独立页签，不走「常规」 | 无 |
+| `addTabLabel` | String | `"新增"` | 新增页签初始标题 | `addTabEnabled` |
+| `submitBehavior` | String | `"closeToList"` | 提交后行为：`closeToList` / `refreshCurrent` | `wfEnabled` |
+
+> 与现有 `multiTabEnabled`（控制**编辑**页签是否多开）互不干扰，可叠加。
+
+---
+
+## 四、改造点（代码骨架，落地时以实代码微调）
+
+### 改造点 1：`designer.js` — formConfig 默认值
+
+在 `multiTabEnabled` 附近新增：
+
+```js
+addTabEnabled: false,          // 新增打开独立页签
+addTabLabel: "新增",            // 新增页签初始标题
+submitBehavior: "closeToList",  // closeToList | refreshCurrent
+```
+
+### 改造点 2：`list.vue` `openEditDialog` — 新增页签分支
+
+在现有 `if (multiTabEnabled && dataId) {...} else {...}` 之间插入新增分支：
+
+```js
+// dataId 为空 = 新增；tabLabelField 取 multiTabLabelField
+let addTabEnabled = formConfig.addTabEnabled && !dataId && tabLabelField;
+
+if (multiTabEnabled && dataId) {
+  // —— 现有编辑页签分支，保持不变 ——
+  this.$refs.xTabs.openEditTab(row, param, {
+    tabParam: { formCode, tabLabelField, tabName: formCode + dataId },
+  });
+} else if (addTabEnabled) {
+  // ★ 新增页签分支：虚拟 row 让标题先显示"新增"
+  let addLabel = formConfig.addTabLabel || "新增";
+  let virtualRow = { ...row };
+  virtualRow[tabLabelField] = addLabel;
+  let tabName = "add_" + Date.now() + "_" + Math.random().toString(36).slice(2, 6);
+  this.$refs.xTabs.openEditTab(virtualRow, param, {
+    tabParam: { formCode, tabLabelField, tabName },
+  });
+} else {
+  // —— 现有「常规」页签分支，保持不变（向后兼容） ——
+}
+```
+
+> 依赖 `x-tabs` 的 `tabNameEnable=true`（`x-tabs:76`）才会用自定义 `tabName`，需确认列表页 x-tabs 已开启该 prop。
+
+### 改造点 3：`list.vue` `reload` — 保存后把标题改为单号
+
+`saveDefaultHandle` 成功 → `reloadForm({updateParam})` → emit `reload` → 此处：
+
+```js
+let updateParam = param?.updateParam;
+let newDataId = updateParam?.dataId;
+if (newDataId && this.$refs.xTabs) {
+  let activeName = this.$refs.xTabs.activeName;
+  let tab = this.$refs.xTabs.tabs.find(t => t.tabName === activeName);
+  if (tab && /^add_/.test(tab.tabName) && tab.tabLabelField) {
+    this.$set(tab.data, tab.tabLabelField, newDataId); // 标题响应式变单号
+    tab.dataId = newDataId;
+    if (updateParam.formCode) tab.formCode = updateParam.formCode;
+    // 待定：是否把 tab.tabName 改为 formCode+newDataId（见待定项 4）
+  }
+}
+```
+
+> `reloadForm` 已通过 `updateParam` 把 `dataId`/`formCode` 透传给 vFormRender，表单会自动重载进编辑态，无需额外处理。
+
+### 改造点 4：`defaultHandle.js` `saveAndSubmitWfHandle` — 注入 onStartSuccess
+
+```js
+let submitBehavior = formConfig.submitBehavior || "closeToList";
+// ... 在 success 回调里：
+openStartWfDialog(formRef, {
+  objId: res.objx,
+  wfCode: reportTemplate.objTypeCode,
+  formCode: reportTemplate.formCode,
+  serviceId: reportTemplate.serviceName,
+  skipStartConfirm: true,
+  onStartSuccess: () => {                 // ★ 新增
+    if (submitBehavior === "refreshCurrent") {
+      formRef.$baseReload();              // 刷新当前页签，保持编辑态
+    } else {
+      formRef.switchToListTab({ handleType: "reload" }); // 切列表 + 刷新
+      let xTabs = formRef.getListPageRef?.()?.$refs?.xTabs;
+      let currentName = xTabs?.activeName;
+      if (xTabs && currentName && /^add_|^edit_/.test(currentName)) {
+        xTabs.removeTab(currentName);      // 关闭当前动态页签
+      }
+    }
+  },
+});
+```
+
+### 改造点 5：`form-setting.vue` — 配置 UI
+
+新增 collapse 分组「页签交互模式」：`addTabEnabled` 开关、`addTabLabel` 输入、`submitBehavior` 单选（关闭页签回列表刷新 / 刷新当前页签）。
+
+---
+
+## 五、端到端流程
+
+**新增→保存→编辑态**
+```
+[新增] → openEditDialog(!dataId, addTabEnabled) → xTabs.openEditTab(标题"新增", tabName=add_xxx)
+→ 填写 → [保存] → saveDefaultHandle 成功(res.objx=单号)
+→ reloadForm({updateParam:{dataId:单号,formCode:editFormCode}}) → emit reload
+→ list.vue reload: $set(tab.data, tabLabelField, 单号) + tab.dataId=单号 + tab.formCode=editFormCode
+→ vFormRender 重载编辑表单 → 同页签、标题=单号、编辑态 ✅
+```
+
+**提交→closeToList**
+```
+[提交] → saveAndSubmitWfHandle → openStartWfDialog({onStartSuccess})
+→ wf.js startSubmitHanlde 成功 → option.onStartSuccess()
+→ switchToListTab({reload}) + xTabs.removeTab(currentName) → 回列表、刷新、关页签 ✅
+```
+
+**提交→refreshCurrent**
+```
+option.onStartSuccess() → $baseReload() → 当前页签刷新，保持编辑态 ✅
+```
+
+---
+
+## 六、待定项（需拍板，含推荐默认）
+
+| # | 决策点 | 推荐 |
+|---|--------|------|
+| 1 | `tabLabelField`(`multiTabLabelField`) 未配置时 | `addTabEnabled=true` 时**必填校验**；缺省用 `addTabLabel` 兜底显示，避免空标题 |
+| 2 | 「常规」pane 显隐 | `addTabEnabled=true` 时 `v-if` 隐藏，避免多一个空页签 |
+| 3 | `submitBehavior` 生效范围 | 仅 `wfEnabled=true` 生效；非流程表单不动 |
+| 4 | 保存后 `tabName` 是否改为 `formCode+单号` | **改**，否则同一单号从列表再打开会重复开页签（去重按 `formCode+dataId`） |
+| 5 | H5（`layoutType=="H5"`） | 不支持本模式，走原 `openEditH5Dialog`；UI 注明仅 PC |
+
+---
+
+## 七、兼容与回退
+
+- 3 个新字段默认值保证**旧表单零行为变化**，可灰度。
+- 改造均为**新增分支**，未删改现有逻辑（仅改造点 4 在 `openStartWfDialog` 多传一个参数）。
+- 回退：关掉 `addTabEnabled` 即恢复「常规」模式，无需改码。
+- **无需改动**：`x-tabs.vue`、`wf.js`、`indexMixin.js`、`wfUtil.js`（直接复用）。
+
+---
+
+## 八、实施步骤
+
+| Phase | 内容 | 验证 |
+|-------|------|------|
+| 1 | `designer.js` 加 3 字段 + `form-setting.vue` 配置 UI | 设计器能配并存入 formJson |
+| 2 | `list.vue openEditDialog` 新增分支 | 点新增开标题"新增"可关闭页签，渲染新增表单 |
+| 3 | `list.vue reload` 更新标题 | 保存后标题变单号、表单转编辑态、dataId 正确 |
+| 4 | `defaultHandle.saveAndSubmitWfHandle` 注入 onStartSuccess | closeToList 关页签回列表刷新；refreshCurrent 刷新本页 |
+| 5 | 边界：待定项 1/2/4/5 | 多次新增、再次编辑、提交后再开同单号、H5 |
+
+合计约 2.5 天。
+
+---
+
+## 九、测试清单
+
+| # | 场景 | 预期 |
+|---|------|------|
+| 1 | 旧表单（未启用）点新增 | 走「常规」，行为不变 |
+| 2 | 启用后点新增 | 开标题"新增"可关闭页签 |
+| 3 | 新增页签保存 | 标题变单号、转编辑态、不新开页签 |
+| 4 | 新增页签不保存直接关 | 正常关闭，不影响列表 |
+| 5 | 编辑页签(multiTabEnabled) | 不受影响 |
+| 6 | 提交 closeToList | 关当前页签、切列表、列表刷新 |
+| 7 | 提交 refreshCurrent | 当前页签刷新、保持编辑态 |
+| 8 | 同单号从列表再打开 | 不重复开（去重生效，依赖待定项 4） |
+| 9 | H5 端 | 走 openEditH5Dialog，不报错 |
+| 10 | `tabLabelField` 未配置 | 有提示或兜底，不崩 |