cloud-web-corejs 1.0.280 → 1.1.0-dev.10

package/src/components/xform/docs/2026-08 xform H5 P2 /345/256/236/347/216/260/350/247/204/346/240/274.md"

@@ -0,0 +1,287 @@
+# xform H5 —— P2 实现规格
+
+> 日期：2026-08-25
+> 上位文档：`2026-08 xform 移动端布局对齐 bill_setting 方案.md`（决策 7 / 9 / 10）
+> 前置：P0（根类 + 样式基线）、P1（骨架 + 底栏 + 明细卡片）**已编码完成**
+> 状态：**wf 移动化 + 附件统一已编码完成**（2026-08-25，lint 无新增错误 + 601 单测全过 +
+> 生产构建通过），待真机联调；**页签一项按拍板跳过**。
+> P2 边界：全链路对齐的最后一段 —— 审批 UI、附件口径、页签皮肤。
+
+P2 交付 3 件事：
+
+1. 审批（wf）移动化（决策 9，**本文修正该决策**）—— 已编码
+2. 附件缩略图口径统一为 74px（决策 7）—— 已编码（`styles/h5.scss` 块 J）
+3. ~~页签 H5 皮肤（决策 10）~~ —— **跳过**（目标侧 bill_setting 自己把页签关掉了，没有对照基准）
+
+## 编码后的补充发现（实施时才暴露，规格里没有）
+
+1. **`components/mobile/wf/content.vue` 的 `_wfInfo` / `_taskParam` 是死 props** ——
+   `created` 里那行赋值是注释掉的，组件在 `mounted` 里调 `init()` 自己取数，是自给自足的。
+   因此 §1.4 设想的「detail-h5 取数后传给面板」行不通：**面板会自己再取一次**。
+   最终实现是 detail-h5-item 取一次（算底栏按钮显隐）+ 面板自己取一次，
+   与手写移动页现状一致（那边也是 mixin 取一次、content 取一次）。
+   没有为省一次请求去改这个公共组件。
+2. **`content.vue` 的根节点 `<h5-card-pane>` 此前没在它自己的 `components` 里注册** ——
+   手写移动页是靠 `mixins/mobile/common` 在**宿主**上局部注册才碰巧能渲染。
+   Vue 2 解析组件只查自身 `components` 与全局注册、**不查父组件的局部注册**，
+   所以被 xform 引用时会渲染不出来。已在 `content.vue` 补上自注册（补它自己的依赖声明）。
+3. **移动版 `wfStartDialog` 不支持 `startConfirmText`** —— 它的 props 只有
+   `{dataId, code, serviceId, startParam, visible, parentVue, wfName}`，没有 `option` 通道。
+   H5 下该配置此前也从未生效（按钮本就没挂上），故不算能力回退；`wfOption` 里保留该字段。
+   同理没有复用 `wfUtil.openStartWfDialog` —— 那个函数把组件来源写死在 `components/wf/` 下，
+   拿到的是 PC 弹框。
+4. **卡片外壳没有重复搬** —— `h5CardPane` 的 `.c-item` / `.tit` 直接并进了块 B 的选择器，
+   wf 面板复用 xform 已有的卡片视觉，避免维护两套卡片皮肤。
+5. **`.pop-tipsBox` 的 `.icon` 依赖 `resources/images` 下的图标**，而该目录与
+   `resources/css` 一样**不在 `package.json` 的 `files` 里** —— 属隐式依赖
+   （消费应用现有的 h5.scss 已引用同一批图，风险可控）。已在 scss 里注释标注。
+   本项目构建时 webpack 把它内联成 base64，消费应用构建时则解析到它自己的同名文件。
+
+---
+
+## 一、审批（wf）移动化
+
+### 1.1 现状纠正：不是「用了 PC 的 UI」，而是 UI 一概没挂上
+
+总方案 §4.8 与 P1 规格都写成「H5 下跑的是 PC 审批 UI」。读完 `components/wf/wfUtil.js` 后确认这个描述是错的，实际情况更严重：
+
+`detail-h5-item.createWf` 调 `initWf.call(formTarget.$parent, option)`，而 `initWf` 的 `done()` 是这样找挂载点的：
+
+```js
+let wfBtnRegion  = $wfBtnRegion  ? $wfBtnRegion.$el  : that.$el.querySelector(".el-form .d-header >.fr");
+let wfViewRegion = $wfViewRegion ? $wfViewRegion.$el : that.$el.querySelector(".el-form .d-cont");
+let slideWrap    = $wfViewRegion ? $wfViewRegion.$el : that.$el.querySelector(".el-form .slide-wrap");
+```
+
+这三个选择器全部来自 **PC 详情容器** `detail-item.vue`（它有 `.d-header`）。
+`detail-h5-item.vue` 的 DOM 里**没有** `.d-header` / `.d-cont` / `.slide-wrap`
+（只有 `.h5-detail-wrap` / `.h5-header` / `.h5-detail-body` / `.h5-fixed-bottom-btns`），
+且 `detail-h5-item` 没有传 `option.wfBtnRegion` / `wfViewRegion`，`$refs` 也取不到。
+
+于是在 H5 下：
+
+| 环节 | 实际结果 |
+|---|---|
+| `wfViewRegion && wfViewRegion.append(instance.$mount().$el)` | 短路，**流程面板既没 mount 也没进 DOM** |
+| 「修改单据」按钮 | 需要 `wfBtnRegion`，不挂 |
+| 「流程启动」按钮 | 需要 `wfBtnRegion`，不挂 |
+| `shouldMountHeaderActions` | 需要 `wfBtnRegion`，恒 false |
+| `option.callback({wfInfo})` | 唯一生效的一环 |
+
+`detail-h5-item` 把 callback 里的 `wfInfo` 存进 `data`，**但模板里从未使用** —— 也是死的。
+
+**结论：H5 表单的审批能力目前等于零。** P2 不是「换一套皮」，是「从没有到有」。
+
+### 1.2 两种范式，别硬套
+
+| | PC（`components/wf/wfUtil.js`） | 移动（`mixins/mobile/wf/index.js` + `components/mobile/wf/*`） |
+|---|---|---|
+| 范式 | **注入式**：自己发请求、自己 `querySelector` 找宿主 DOM、`new` 出实例 `append` 进去 | **声明式**：mixin 只提供数据与开关（`wfInfo` / `taskParam` / `hasWf` / `showWfStartBtn` / `showWfModifyBtn` / `wfOption`）和两个方法（`openStartWfDialog` / `openWfModifyDialog`），**UI 由宿主页面自己在模板里摆** |
+| 组件来源 | `require('../../components/wf' + path)` | `require('../../../components/mobile/wf' + path)` |
+| content.vue props | `objId, wfCode, serviceId, _wfInfo, _taskParam, parentVue, defaultShowWfContent, wfConfig` | `_wfInfo, _taskParam, wfOption, defaultShowWfContent`（无 objId/wfCode/serviceId/parentVue，用 `getTarget(this)` 找宿主） |
+
+两套 content.vue 的 props **不兼容**（`wfConfig` vs `wfOption`），不能简单换个 require 路径了事。
+
+### 1.3 决策修正
+
+> **总方案决策 9 原文**：「`wfUtil.initWf` 增加 H5 分支，按 layoutType 选 `components/mobile/wf/*`」。
+> **本文修正为**：**不改 `wfUtil.js`**，`detail-h5-item` 改走声明式，自行取数 + 在模板里渲染移动审批 UI。
+
+修正理由：
+
+1. 给 `initWf` 加 H5 分支，等于要在 H5 容器里造一批 `.d-header > .fr` / `.d-cont` 假节点去迎合注入式的 `querySelector` —— 为了复用一个本来就不适配的编排，反过来污染 H5 的 DOM 结构；
+2. 两套 content.vue 的 props 不兼容，分支要同时兼容两种 propsData，`wfUtil` 会更难维护，而它是 PC 全线在用的公共文件，**改它的回归面远大于改 detail-h5-item**；
+3. `detail-h5-item` 本身就是个 Vue 组件，模板里直接渲染即可，根本不需要 DOM 注入；
+4. 移动那套声明式编排已经在手写移动页上跑通了，是现成的、验证过的范式。
+
+### 1.4 取数
+
+`mixins/mobile/wf/index.js` 的取数入口是 `_getBillInfo(option)` —— 它耦合了「先查单据再查流程」的手写页流程（`opt.url` 打业务接口、从 url 里切 `serviceId`）。
+xform 的单据数据是表单自己取的，**不需要那一层**，只需要它内部那两个流程接口：
+
+```js
+// wf_prefix = '/' + serviceId
+POST {wf_prefix}/wf/getWfInfo        { objTypeCode: wfCode, objId }
+POST {wf_prefix}/wf/getTaskVariables { stringOne: taskId }
+```
+
+两个接口 PC/移动完全一致（`wfUtil.js` 的 `initWfInfo` / `getTaskParams` 与 mobile mixin 里的同名方法参数相同）。
+
+**做法**：在 `detail-h5-item.vue` 里写一个小的 `loadWfInfo()`，直接打这两个接口，得到
+`hasWf / wfInfo / taskParam`，再按 mobile mixin 的口径算出两个开关：
+
+```js
+showWfStartBtn  = !hasWf && (option.showStartBtn  !== false)
+showWfModifyBtn = hasWf && !!taskParam && !!taskParam.mobileurl && !!wfInfo.toSubmit
+                        && (option.showModifyBtn !== false)
+```
+
+> ★ 注意 `taskParam.mobileurl`：移动版判修改按钮用的是 **`mobileurl`**，PC 版用的是 `url`
+> （`wfUtil.js` 里是 `taskParam.url`）。这是后端给的两个不同字段，别混用 ——
+> 用错会导致「移动端点修改单据打开的是 PC 页面」。
+
+### 1.5 模板与选项
+
+`detail-h5-item.vue` 模板增加两处：
+
+**① 流程面板**，放在 `.h5-detail-body` 内、`panes` 之后：
+
+```html
+<component
+  v-if="wfEnabled && hasWf"
+  :is="mobileWfContent"
+  :_wfInfo="wfInfo"
+  :_taskParam="taskParam"
+  :wfOption="wfOption"
+  :defaultShowWfContent="defaultShowWfContent"
+/>
+```
+
+`mobileWfContent` 用异步组件，避免 PC 表单也把移动 wf 那坨打进主包：
+
+```js
+    mobileWfContent() {
+      return () => import("@base/components/mobile/wf/content.vue");
+    },
+```
+
+**② 启动 / 修改按钮**，进**底部动作栏**（不是标题栏，见 1.6），与 P1 的按钮分流合流 ——
+即把这两个内建按钮拼进 `bottomButtons` 的计算结果里，让它们同样受
+`maxVisibleButtons` 管辖，不然按钮一多底栏还是会挤。
+
+`detail-h5.options` 已有 `wfEnabled`，无需新增开关。
+
+### 1.6 与既有 wf 方案的关系
+
+- **「审批按钮进详情标题栏」（`wfActionInHeaderEnabled` / `wfActionDropdown.vue`）是 PC 口径**，
+  H5 不启用：H5 的标题栏只有 38px、放不下，且底部动作栏本来就是移动端的动作区。
+  `shouldMountHeaderActions` 在 H5 下本来也恒 false（1.1），保持现状即可，**不要**去改它。
+- **「流程确认框自动确认 param19」「保存并提交收敛为表单设置」是数据/流程口径**，与布局无关，
+  H5 直接继承，无需改动。
+- `detail-h5-item.createWf` 里现有的 `startConfirmText: () => formTarget.getWfStartConfirmText()`
+  要保留，接进新的启动流程。
+
+### 1.7 风险
+
+1. `components/mobile/wf/content.vue` 用 `getTarget(this)` 找宿主，取的是 `_hideWf` 等属性 ——
+   需要确认它在 xform 的组件树下能正确找到宿主（手写移动页的树形与 xform 不同）。**编码时先验证这一条**，
+   不通就给它显式传 props。
+2. `components/mobile/wf/content.vue` 内部 import 了
+   `views/mobile/user/user/dialog.vue`（用户选择弹框）——该路径在 `package.json` 的 `files`
+   里（`src/views/mobile/user`），随包发布没问题，但消费应用要确认存在。
+3. 移动 wf 的样式依赖 `resources/css/h5.scss`（`.h5-process-info` 等），而那份**不随包发布**
+   且 xform 引不到。P2 落地时需把移动 wf 面板用到的样式一并搬进 `xform/styles/h5.scss`，
+   或确认 `.mobileApp` 场景下由消费应用自带的 h5.scss 兜住 —— **这是本项最大的不确定点**，
+   见 五、待确认 1。
+
+---
+
+## 二、附件缩略图口径统一
+
+### 2.1 现状：两套并存且互不相通
+
+| | 位置 | 尺寸 | 谁在用 |
+|---|---|---|---|
+| A（bill_setting 口径） | `resources/css/h5.scss` 的 `.h5-upload-box` / `.h5-upload-list` | 74px | 只被 `components/mobile/buttonGroup` 与 `views/mobile/user/*/dialog.vue` 三处 `@import`，**xform 引不到** |
+| B（xform 现用） | `resources/css/style.scss:13818` 起 `.h5-form-box .el-upload-list__item` | 102px | xform H5 表单 |
+
+### 2.2 做法
+
+把 A 的规则搬进 `xform/styles/h5.scss`（作用域 `.xform-h5`，新增块 J），
+覆盖 B。对手是 `.h5-detail-wrap .h5-item .h5-form-box .el-upload-list__item`（0,4,0），
+本方写到 (0,5,0) 以上，遵守 P0 §2.2 的特异度约束。
+
+要点：缩略图 74×74 + `border-radius:6px`；上传格子用 `el-icon-camera`；
+删除角标红圆点右上角外挂（`right:-10px; top:-10px`）。
+
+**style.scss 的 B 段本次不删**（`components/mobile/*` 手写页可能用到），P3 统一评估。
+
+### 2.3 顺带清理：两处 isH5 死代码
+
+`isH5` 在四个上传组件里都赋了值，但只有两个真正用了：
+
+| 组件 | 用途 | 结论 |
+|---|---|---|
+| `vabUpload-widget.vue:27-28` | `:hidePasteArea.sync="isH5"` + `uploadDialogCustomClass='dialog-upload-h5'` | 有效，保留 |
+| `singleUpload-widget.vue:13-14` | 同上 | 有效，保留 |
+| `baseAttachment-widget.vue:68,145` | 只在 data 声明并赋值，**模板中从未引用** | 死代码 |
+| `vabUpload2-widget.vue:191,223` | 同上，**模板中从未引用** | 死代码 |
+
+两处死代码有两条路：删掉，或者补上 `hidePasteArea` / `dialog-upload-h5`
+让它们与另外两个上传组件行为一致。**倾向后者** —— 从命名看当初就是想这么做只是没写完，
+且移动端粘贴区确实该隐藏。见 五、待确认 2。
+
+---
+
+## 三、页签 H5 皮肤
+
+### 3.1 现状
+
+`style.scss:13892` 对 `.h5-detail-wrap .el-tabs.tab-box` 只做了两件事：
+
+```scss
+  .el-tabs.tab-box {
+    .el-tabs__header { background: #fff; line-height: 40px; }
+    .el-tabs__content { padding: 0; }
+  }
+```
+
+没有横向滚动，也没有下划线指示器 —— 与 bill_setting 的 `.tab-box`
+（横滑 + `.item.on::after` 20px 宽 4px 高圆角下划线）差得远。
+
+### 3.2 做法（决策 10：不自绘，给 el-tabs 套皮）
+
+新增块 K，`.xform-h5 .h5-detail-wrap .el-tabs.tab-box`（0,4,0，压过对手的 0,2,0）：
+
+- `.el-tabs__nav-wrap` 横向可滚、隐藏滚动条、`::after` 那条通栏底线去掉；
+- `.el-tabs__item` 字号 13px、未选中 `#808080`、选中 `#323232`；
+- `.el-tabs__active-bar` 改成 20px 宽、4px 高、`border-radius:4px`、居中
+  （Element 的 active-bar 宽度是 JS 按 item 宽算的，要用 `transform` 配合
+  `width:20px !important` 覆盖，并注意它 `transition` 时的位移基准）。
+
+> bill_setting 自己的 `.tab-box` 目前是被 `style="height:0"` 关掉的 ——
+> 目标侧这块也没定型，所以本项优先级最低，可以最后做或先跳过。
+
+---
+
+## 四、自测清单
+
+wf：
+
+1. H5 表单挂到一条已启动流程的单据上：流程面板出现在内容区底部、能展开/折叠；
+2. 未启动流程的单据：底栏出现「流程启动」，点击弹移动版启动弹框；
+3. 有待办任务的单据：底栏出现「修改单据」，点击打开的是 **mobileurl** 指向的移动页（不是 PC 页）；
+4. 启动确认文案（`startConfirmText`）仍生效；
+5. wf 按钮与业务按钮一起参与 `maxVisibleButtons` 分流，不挤爆底栏；
+6. `wfEnabled=false` 的 H5 表单：不发流程请求、不渲染面板（回归底线）；
+7. **PC 表单的审批完全不受影响**（本项没动 `wfUtil.js`，重点回归 PC 详情页）。
+
+附件：
+
+8. H5 表单里附件缩略图 74×74、圆角 6、删除角标在右上角外挂；
+9. 上传格子是相机图标；
+10. 粘贴区在 H5 下隐藏（四个上传组件表现一致）。
+
+页签：
+
+11. 页签数量超出一屏时可横滑；
+12. 选中项下方是 20px 短下划线，不是通栏长条。
+
+回归：
+
+13. PC 版式（layoutType≠H5）下以上全部不生效；
+14. `npm run lint`；`npm run test:unit`；`npm run build:prod`。
+
+---
+
+## 五、待确认
+
+1. **移动 wf 面板的样式从哪来？**（1.7 风险 3）
+   `resources/css/h5.scss` 不随包发布、xform 引不到。三条路：
+   a) 把移动 wf 面板用到的样式搬进 `xform/styles/h5.scss`（工作量中等，但彻底）；
+   b) 只在 `.mobileApp` 场景下用，靠消费应用自带的 h5.scss 兜（回到"样式要手工同步"的老问题）；
+   c) 先做功能、样式缺失单列一期。
+   **倾向 a**，但需要先摸清移动 wf 面板究竟依赖哪些类名，可能不小。
+2. **`baseAttachment` / `vabUpload2` 的 isH5 死代码**：删掉，还是补齐成与另两个一致？倾向补齐。
+3. **页签这项要不要做？** 目标侧（bill_setting）自己都把页签关掉了，
+   做了也没有对照基准。倾向：先跳过，等真机看 el-tabs 默认样式在 H5 下是否可接受。