cloud-web-corejs 1.0.54-dev.81 → 1.0.54-dev.811

package/src/components/xform/docs/2026-08 xform /347/247/273/345/212/250/347/253/257/345/270/203/345/261/200/345/257/271/351/275/220 bill_setting /346/226/271/346/241/210.md"

@@ -0,0 +1,400 @@
+# xform 移动端（H5）布局对齐 bill_setting —— 梳理与落地方案
+
+> 日期：2026-08-25
+> 范围：`src/components/xform/`（form-designer 的 H5 容器 + form-render 的 H5 渲染件 + H5 样式基线）
+> 目标参照：`src/views/user/bill_setting/`（单据设置的手写 H5 渲染器）
+> 状态：**仅梳理与方案，未编码**。本文是后续实现与验收基线。
+> 一句话结论：xform 的 H5 链路是**通的**（设计器可切 H5、有 4 个 H5 容器、有运行时根类），
+> 差的不是「有没有」，而是**版式口径**（字段排布、卡片皮肤、明细呈现、底栏、审批 UI）
+> 与**样式归属**（现有 H5 样式散在不随包发布的 `resources/css/style.scss` 里）。
+
+---
+
+## 一、目标与边界
+
+### 1.1 目标
+
+让 xform 在 `formConfig.layoutType === 'H5'` 下渲染出的表单，视觉与交互对齐
+`bill_setting` 的移动端效果：
+
+1. 页面骨架：标题栏 + 内部滚动区 + 底部动作栏，内容区不整页滚；
+2. 字段排布：`标签 : 值` 的紧凑行式表格版式，支持半宽（两列）/整宽；
+3. 分组卡片：白底圆角卡 + 标题左侧竖色条；
+4. 明细（子表）：卡片列表 + 主字段标题 + 点开看全字段；
+5. 附件：74px 缩略图网格 + 拍照上传格子；
+6. 底部动作栏：胶囊按钮，超出收「更多」；
+7. 审批（wf）：使用移动端审批 UI，而不是 PC 的 wf 弹框。
+
+### 1.2 不做
+
+- 不改 `src/views/user/bill_setting/` 任何文件（它是独立的存量单据渲染器，仍在线上跑）；
+- 不把 PC 的 `data-table` / `sub-form` 做「自动 H5 降级」——H5 表单仍需单独设计、用 `list-h5`（见 4.5）；
+- 不改 `App.vue` 的 `mobileApp`（UA 判定）语义；
+- 不动 `request.js`、不动后端协议。
+
+---
+
+## 二、现状盘点
+
+### 2.1 bill_setting 的移动端是怎么做出来的
+
+一套**自闭环的手写 H5 渲染器**，不是通用能力：
+
+| 层 | 文件 |
+|---|---|
+| 入口壳 | `h5_view.vue`、`h5_detailDialog.vue`、`h5_ModifyDialog.vue`、`previewDialog.vue` |
+| 渲染主体 | `render.vue`（模板 1-562；scoped scss 1466-2028） |
+| 明细行详情 | `itemViewDialog.vue` |
+| 对比标记 | `compareView.vue` |
+| 全局样式 | `resources/css/style.scss:14349` 起 `.mobileApp, .h5view-dialog { .form-table / .form-list-table / .viewForm-box }`；另有 13581、14470 两段 `.mobileApp` |
+| 移动开关 | `App.vue:2` 按 UA 给 `#app` 加 `mobileApp` |
+
+骨架：
+
+```
+.h5-wrap            max-width:640 居中，底色 #F1F5FB
+├─ .header-box      46px（.mobileApp 下 38px）标题栏
+└─ .form-box        display:flex; flex-direction:column; height:calc(100vh - 120px)
+   ├─ .tab-box      自绘横滑页签（当前被 style="height:0" 关着）
+   ├─ .c            flex:1; overflow:auto   ← 唯一滚动区
+   │  └─ .c-item    白底 radius12 卡片；.tit>b::before 是 4px 蓝色竖条
+   │     ├─ table.form-table       主表字段（th/td）
+   │     ├─ .pro-list>.pro-item    明细行卡片
+   │     └─ .uploadlist-box        附件 74px 网格
+   └─ .fix-bottom-btns              **在 flex 流内**（position:static），非 fixed
+```
+
+字段排布细节（`style.scss:14351` 起）：
+`tr` 高 48px + 下边线；`th` 宽 80px、`::after` 自动补 `:`；
+`td` 宽 `calc(50vw - 109px)`，内部 `el-form-item{float:right}`、输入框 `border:none`。
+一行放几个字段由 `fieldSize=='small'` 决定（`colspan 1` → 两个一行；否则 `colspan 3` → 整行）。
+
+### 2.2 xform 现有的 H5 能力
+
+| 环节 | 位置 |
+|---|---|
+| 设计器切换 | `form-designer/toolbar-panel/index.vue:30` 切 `formConfig.layoutType='H5'` |
+| 组件过滤 | `form-designer/widget-panel/indexMixin.js:342`（`!ftd.layoutType` 或与当前 layoutType 相等才显示） |
+| H5 容器 | `widgetsConfig.js`：`detail-h5`(537)、`list-h5`(557)、`h5-card`(710)、`h5-table`(741) |
+| 渲染件 | `form-render/container-item/`：`detail-h5-item`、`h5-card-item`、`h5-card-pane-item`、`h5-table-item`、`h5-table-cell-item`、`list-h5-item` |
+| 运行时根类 | `views/user/form/vform/render.vue:4` 依 layoutType 加 `.h5-layout` |
+| H5 样式 | `resources/css/style.scss:13740` 起：`.h5-header / .h5-detail-wrap / .h5-item / .h5-title / .h5-form-box / .h5-fixed-bottom-btns / .h5-search-box / .h5-list-box`；`10727` 起是设计器预览用的 `.h5-layout / .H5-layout` |
+| 上传适配 | 4 个上传组件已有 `isH5`（`baseAttachment-widget.vue:145` 等） |
+| 对比 | `form-render/compareView.vue` + `form-item-wrapper.vue` 已接入 `isCompareOn` |
+| 明细行详情 | `list-h5-item.vue:426` 已有「明细详情」弹框（`h5view-dialog`） |
+
+### 2.3 第三套：手写移动页的组件库
+
+`src/components/mobile/`（h5Card / statusTag / searchDialog / buttonGroup / oplogTable / wf/*）
++ `src/mixins/mobile/*` + `src/resources/css/h5.scss`。
+它复用了 bill_setting 的类名口径（`.c` / `.c-item` / `.tit`），是「第二个消费者」，
+说明 bill_setting 的版式已经是事实上的移动端设计语言 —— 本方案把它变成 xform 的第三个消费者。
+
+> `h5.scss` 只在 3 处 `@import`（`components/mobile/buttonGroup`、`views/mobile/user/*/dialog.vue`），
+> xform 引不到。`h5-v0.0.1.scss` 是旧副本，全库无人引用。
+
+---
+
+## 三、差距对照
+
+| # | 维度 | bill_setting | xform 现状 | 差距性质 |
+|---|---|---|---|---|
+| 1 | 作用域开关 | `#app.mobileApp`（UA） + `.h5view-dialog` | `.designer-view.h5-layout`（宿主壳加） | **口径不同源**，见 4.1 |
+| 2 | 字段排布 | `table.form-table` th/td，48px 行、label 80px 带冒号、值右浮、输入框无边框 | 一字段一个 `el-form-item`，38px 圆角实体输入框 | **最大差异**，见 4.3 |
+| 3 | 两列布局 | `fieldSize=='small'` → colspan | `.form-widget-list.m2` **死规则**（永不命中） | 缺能力 + 死代码 |
+| 4 | 分组卡片 | `.c-item` + `.tit>b::before` 竖条 | `.h5-item` + `.h5-title::after` 竖条 | 视觉接近，微调即可 |
+| 5 | 明细呈现 | `.pro-item` 卡（圆点标题 + 右箭头）→ itemViewDialog | `list-h5` 的 `.h5-list-box .item` + 明细详情弹框 | **概念已齐**，缺皮肤 |
+| 6 | PC 子表降级 | 无此问题（本就是 H5 专用） | `data-table`/`sub-form` 在 H5 下不卡片化 | 明确不做，写进约定 |
+| 7 | 附件 | 74px 缩略图 + 相机格子 | 两套并存：`h5.scss` 的 74px（引不到）/ `style.scss` 的 102px | 口径不统一 |
+| 8 | 底部按钮 | 胶囊 radius30、`calc(50%-10px)`、留了「更多」位 | 方角、flex:1、`height:56` | 样式 + 溢出策略 |
+| 9 | 审批 wf | 自绘 通过/驳回/转办 三弹框 | `detail-h5-item.createWf` → `wf/wfUtil.initWf`（**PC UI**，wfUtil 无 mobile 分支） | 缺移动分支 |
+| 10 | 骨架/滚动 | flex 列 + 内滚动，底栏在流内 | `padding-bottom:68px` + 底栏 `position:fixed`，整页滚 | 模型不同 |
+| 11 | 页签 | 自绘横滑下划线 | el-tabs + 轻改造 | 缺 H5 皮肤 |
+| 12 | 对比 | `compareView` + 行级 `el-icon-warning` | 字段级已对齐 | 缺行级标记 |
+
+---
+
+## 四、方案
+
+### 4.1 作用域根类与样式归属（先决项）
+
+**决策 1：xform 自己出根类 `.xform-h5`，由 form-render 输出，不蹭 `.mobileApp`，不依赖宿主壳的 `.h5-layout`。**
+
+理由：
+
+- `.h5-layout` 目前只有 `views/user/form/vform/render.vue` 一个宿主会加；
+  表单还会从 `formDialog` / `formDrawer` / `outLink/form_view` / 微前端子应用等路径渲染，
+  这些路径拿不到根类 —— 现在 `formDialog.vue:319`、`searchFormDialog.vue:488`、
+  `fileReferenceDialog.vue:277` 里各自写了 `::v-deep .H5 .h5-fixed-bottom-btns` 打补丁，
+  正是作用域漂移的证据。
+- `.mobileApp` 是 UA 判定，与 layoutType 正交：H5 表单可能在 PC 浏览器里预览（设计器/预览弹框），
+  PC 表单也可能在手机上打开。两者不能互相代替。
+
+落点：`form-render/index.vue` 根 `el-form` 的 `:class` 加上
+`layoutType === 'H5' ? 'xform-h5' : ''`（`layoutType` 从 `formConfig` 取，`indexMixin` 已有 `customClass` computed 可类比）。
+宿主壳的 `.h5-layout` 保留不动（设计器预览仍靠它）。
+
+**决策 2：新建包内样式文件 `src/components/xform/styles/h5.scss`，不再往 `resources/css/style.scss` 追加。**
+
+关键理由（**这条决定了方案能不能随包走**）：
+`package.json` 的 `files` 里只有 `src/resources/js`，**没有 `src/resources/css`**。
+也就是说 `style.scss` 不随 `cloud-web-corejs` 发布 —— 消费应用用的是自己那份拷贝
+（`src/styles/index.scss` 里 `@import '~@/resources/css/style.scss'`，`@` 指向消费应用自己的 src）。
+现有 `.h5-*` 样式写在 style.scss 里，等于每次改都要手工同步到每个消费应用与分支（stdxx / com@publish）。
+`src/components/xform` 在 `files` 内，样式放包内即可随包发布。
+
+引入方式：`form-render/index.vue` 的 `<style lang="scss">`（**非 scoped**，因为要穿透到
+各 field-widget 的 el-form-item）里 `@import "../styles/h5.scss";`，
+全部规则收在 `.xform-h5 { ... }` 下，天然不污染 PC。
+
+变量（同文件顶部定义，避免 5.4 的常量散落）：
+
+```scss
+$xformH5HeaderHeight: 38px;   // 标题栏
+$xformH5FooterHeight: 56px;   // 底部动作栏
+$xformH5DialogChrome: 73px;   // 弹框内 header+padding 占位
+$xformH5RowHeight: 48px;      // 字段行高
+$xformH5LabelWidth: 80px;     // 标签宽
+```
+
+> `$baseColor`、`$--color-primary` 等由 vue.config 的 sass `additionalData` 注入 `styles/global.scss` 提供，
+> 两个应用的 vue.config 已约定保持一致，可直接用。
+
+### 4.2 页面骨架与滚动模型
+
+**决策 3：`detail-h5-item` 改成 flex 列 + 内部滚动区，底栏回到流内（去掉 `position:fixed`）。**
+
+```
+.xform-h5 .h5-detail-wrap    display:flex; flex-direction:column; height:100%
+├─ .h5-header                flex:none; $xformH5HeaderHeight
+├─ .h5-detail-body（新增）    flex:1; overflow:auto;   ← 包住现有 panes 的 transition-group
+└─ .h5-fixed-bottom-btns     flex:none; $xformH5FooterHeight（改 static）
+```
+
+收益：
+
+- 去掉 `padding-bottom:68px` 这类「给 fixed 让位」的补丁；
+- 解决 iOS 键盘弹起时 `position:fixed` 底栏被顶飞的老问题；
+- 弹框内（`h5view-dialog`）不再需要逐处写 `calc(100vh - 73/112/119/205)`，
+  外层给定高度即可，内部自适应。
+
+`max-width:640 + margin:auto` 是否加：见 八、待确认 1。
+
+### 4.3 字段排布（核心）
+
+两条路：
+
+- **方案 A（真 table）**：容器渲染期把 `widgetList` 分组成行，每字段拆成 `<th>` + `<td>`。
+  照搬 bill_setting，视觉最像。
+  代价：字段组件全部依赖 `el-form-item`（`prop`/`rules` 挂在上面，`compareView` 也包在里面），
+  拆成两个单元格会打断校验链与对比包裹，且要改 `form-item-wrapper` 这个所有字段的公共入口。**风险高。**
+- **方案 B（CSS 复刻，推荐）**：DOM 不变，用 flex 复刻表格视觉。
+
+**决策 4：走方案 B。**
+
+```scss
+.xform-h5 .h5-form-box {
+  .form-widget-list { display: flex; flex-wrap: wrap; }
+  .field-wrapper { width: 100%; }
+  .field-wrapper.h5-half { width: 50%; }          // 两列
+  .el-form-item {
+    display: flex; align-items: flex-start;
+    min-height: $xformH5RowHeight;
+    border-bottom: 1px solid #f3f3f3;
+    .el-form-item__label {
+      width: $xformH5LabelWidth; padding: 0 5px 0 0;
+      line-height: 1.4; text-align: left;
+      &::after { content: ":"; }                   // 对齐 bill_setting 的 th::after
+    }
+    .el-form-item__content { flex: 1; text-align: right; }
+    .el-input__inner, .el-textarea__inner { border: none; text-align: right; }
+  }
+  .el-form-item:last-child { border-bottom: none; }
+}
+```
+
+**决策 5：半宽/整宽做成显式字段级选项 `h5Span: 'full' | 'half'`（默认 full），不要让用户手打 customClass。**
+
+- 数据落点：字段 `options.h5Span`；
+- 属性面板：`setting-panel/property-editor/` 下新增 `h5-span-editor`，仅
+  `formConfig.layoutType === 'H5'` 时显示（可参照 `grid-col-span-editor.vue:18` 的显隐写法）；
+- 渲染落点：`form-item-wrapper.vue` 根 `.field-wrapper` 的 `:class` 加
+  `field.options.h5Span === 'half' ? 'h5-half' : ''`；
+- 语义对齐 bill_setting 的 `fieldSize=='small'`。
+
+同时删除死规则 `.h5-form-box .form-widget-list.m2`（`style.scss:13806`）。
+
+### 4.4 分组卡片
+
+差距很小，只调 `.h5-item / .h5-title` 的竖条位置与字号，向 bill_setting 的 `.c-item / .tit` 靠：
+竖条 4px 宽、13px 高、`border-radius:4px`、`$baseColor`；标题 14px/600。
+
+**顺带修**：`h5-card-pane-item.vue` 根节点是裸的 `<div class="h5-item">`，
+定义了 `customClass` computed 却没绑（设计器侧 `h5-card-pane-widget.vue:2` 是绑了的）
+→ 设计器里配的 class 到运行期丢失。补 `:class="['h5-item', customClass]"`。
+
+### 4.5 明细（子表）
+
+**决策 6：`list-h5` 增加 `pro-item` 卡片皮肤，行详情弹框复用现成的；不做 PC 子表的自动降级。**
+
+- `list-h5` 的 `options` 加 `itemStyle: 'plain' | 'card'`（默认 `plain` 保持存量不变）；
+  `card` 时 `.h5-list-box .item` 套 `.pro-item` 皮肤：
+  1px 边框 + radius12 + 主字段标题（前置圆点、右侧 `\e6e0` 箭头角标）+ 卡内小字段区；
+- 卡内显示哪些字段：**沿用现有 `tableColumns[].showForRow`**（`widgetsConfig.js` 里已有），无需新字段；
+- 点卡片 → 现成的「明细详情」弹框（`list-h5-item.vue:426`）；
+- 行级变更标记：复用对比能力的 `getCompareRowClass` 口径，在 item 上加 `changed` 类 + `el-icon-warning` 角标。
+
+**约定（写进 README，避免反复问）**：H5 表单的明细必须用 `list-h5` 设计，
+PC 的 `data-table` / `sub-form` 在 H5 下不会卡片化。
+
+### 4.6 附件
+
+**决策 7：以 `h5.scss` 的 74px 口径为准，把该段样式搬进 `xform/styles/h5.scss`（`.xform-h5` 作用域下），
+废弃 `style.scss:13818` 那套 102px 的 xform 私有写法。**
+
+4 个上传组件的 `isH5` 判定（`baseAttachment / singleUpload / vabUpload / vabUpload2`）保持不变，
+只统一样式；相机格子用 `el-icon-camera`，删除角标沿用现有 `.el-icon-close` 红圆点。
+
+> 注意：附件是独立存储通道（见既有结论「xform 附件字段支持 URL 值」），本次只动样式，不碰取数与提交。
+
+### 4.7 底部动作栏
+
+**决策 8：胶囊皮肤 + 溢出收「更多」。**
+
+- 样式：`radius:30`、高 40、`.el-button` 带 iconfont 图标，2 个按钮时各占 `calc(50% - 10px)`，
+  3 个及以上等分；
+- 溢出：`detail-h5` 的 `options` 加 `maxVisibleButtons`（默认 2），
+  `detail-h5-item` 渲染 `widgetList` 时超出部分收进 `el-dropdown`
+  （下拉菜单加 `mobileApp_dropdown` 同款样式类）。
+  bill_setting `render.vue:317-333` 有一段注释掉的「更多」下拉原型，可直接参考结构。
+
+### 4.8 审批（wf）
+
+**决策 9：`wfUtil.initWf` 增加 H5 分支，按 layoutType 选 `src/components/mobile/wf/*`。**
+
+> ⚠ **本决策已被 P2 规格修正为「不改 `wfUtil.js`，`detail-h5-item` 改走声明式」。**
+> 同时本节下面「跑的是 PC 审批 UI」的描述也不准确 —— 实测是 `initWf` 的挂载点
+> （`.d-header > .fr` / `.d-cont`）在 H5 容器里根本不存在，**审批 UI 一概没挂上**。
+> 详见 `2026-08 xform H5 P2 实现规格.md` §1.1–1.3。
+
+现状：`detail-h5-item.createWf` 调 `initWf`（`components/wf/wfUtil.js`），
+而 `wfUtil.js` 里**没有任何 mobile/H5 分支**（全文 grep 无 `mobile`/`isMobile`/`h5`）。
+移动审批组件是齐的（`components/mobile/wf/`：`wfStartDialog`、`wfModifyDialog`、
+`addTaskUserdialog`、`setCandidateDialog`、`urgingDialog`、`content.vue`），只是没接上。
+
+接法：`initWf(option)` 的 `option` 增加 `layoutType`（由 `detail-h5-item` 传 `'H5'`），
+wfUtil 内部据此切换 content / 各弹框的组件来源。
+
+与既有 wf 方案的关系（**不冲突，但要写清**）：
+
+- 「审批按钮进详情标题栏」是 **PC** 口径；H5 下审批按钮进**底部动作栏**，不进标题栏；
+- 「流程确认框自动确认 param19」「保存并提交收敛为表单设置」是数据/流程口径，与布局无关，H5 直接继承。
+
+### 4.9 页签
+
+**决策 10：不自绘，给 el-tabs 套 H5 皮肤。**
+
+`.xform-h5 .el-tabs.tab-box`：header 横向可滚（`white-space:nowrap`）、
+去掉默认下边框、active 项用 20px 宽 4px 高的圆角下划线指示器（对齐 bill_setting `.tab-box .item.on::after`）。
+
+> bill_setting 自己的 `.tab-box` 目前是被 `style="height:0"` 关掉的，
+> 说明这块在目标侧也没定型 —— 优先级放 P2。
+
+---
+
+## 五、顺带要修的既有缺陷
+
+| # | 缺陷 | 位置 | 处理 |
+|---|---|---|---|
+| 5.1 | `h5-card-pane-item` 根节点漏绑 `customClass`（computed 定义了没用） | `form-render/container-item/h5-card-pane-item.vue:2` | 随 4.4 修 |
+| 5.2 | `.h5-form-box .form-widget-list.m2` 死规则（class 写死在 transition-group 上，customClass 落在 `.grid-cell`/`el-form-item`，永不命中） | `style.scss:13806` | 随 4.3 删 |
+| 5.3 | `h5-table-cell` 是 `1px solid #e5e5e5` 实线格子，与 bill_setting 的「无边框 + 行分隔线」冲突 | `h5-table-cell-item.vue` 的 scoped style | `.xform-h5` 下覆盖为行分隔线 |
+| 5.4 | 高度常量散在 4 处 5 个值（`render.vue` 的 120、两个 h5 dialog 的 205、`style.scss` 的 38/112/119、dialog 内联的 73） | 多处 | 4.1 收成 scss 变量；**这是 bill_setting 的债，不要照搬过来** |
+| 5.5 | `h5-v0.0.1.scss` 是 `h5.scss` 的旧副本，全库无人 import | `resources/css/h5-v0.0.1.scss` | 标记待删（不在本次范围，避免误伤消费应用） |
+| 5.6 | 三个 dialog 里的 `::v-deep .H5 .h5-fixed-bottom-btns` 补丁 | `formDialog.vue:319`、`searchFormDialog.vue:488`、`fileReferenceDialog.vue:277` | 4.1 根类落地后可回收 |
+
+---
+
+## 六、改动清单（文件级，供实现时对照）
+
+**新增**
+
+- `src/components/xform/styles/h5.scss` —— H5 样式基线（全部收在 `.xform-h5` 下 + 变量）
+- `src/components/xform/form-designer/setting-panel/property-editor/.../h5-span-editor.vue` —— 字段半宽/整宽
+
+**修改（xform 内）**
+
+- `form-render/index.vue` —— 根 class 加 `xform-h5`；非 scoped style 里 `@import` 样式基线
+- `form-render/container-item/detail-h5-item.vue` —— flex 列骨架 + 内滚动区；底栏溢出「更多」；`createWf` 传 layoutType
+- `form-render/container-item/h5-card-pane-item.vue` —— 补绑 customClass（5.1）
+- `form-render/container-item/h5-table-cell-item.vue` —— 边框口径（5.3）
+- `form-render/container-item/list-h5-item.vue` —— `itemStyle:'card'` 皮肤 + 行级变更标记
+- `form-designer/form-widget/field-widget/form-item-wrapper.vue` —— `.field-wrapper` 加 `h5-half`
+- `form-designer/widget-panel/widgetsConfig.js` —— `detail-h5.options.maxVisibleButtons`、`list-h5.options.itemStyle`、字段 `options.h5Span`
+- `form-designer/form-widget/dialog/{formDialog,searchFormDialog,fileReferenceDialog}.vue` —— 回收 `.H5` 补丁（5.6）
+
+**修改（xform 外，最小面）**
+
+- `src/components/wf/wfUtil.js` —— `initWf` 增加 H5 分支（4.8）
+- `src/resources/css/style.scss` —— 删死规则 5.2；**其余 `.h5-*` 暂不搬**（见 八、待确认 3）
+
+---
+
+## 七、分期
+
+| 期 | 内容 | 产出 |
+|---|---|---|
+| **P0** | 4.1 根类 + 样式基线文件、4.3 字段排布 + h5Span、4.4 卡片皮肤（含 5.1/5.2） | 视觉主体对齐，单张表单可对照截图验收 |
+| **P1** | 4.2 骨架滚动、4.7 底栏胶囊 + 「更多」、4.5 明细卡片皮肤 | 交互对齐 |
+| **P2** | 4.8 wf 移动化、4.6 附件统一、4.9 页签皮肤 | 全链路对齐 |
+| **P3** | 5.3 / 5.5 / 5.6 清理，README 补 H5 设计约定 | 收债 |
+
+P0 可独立上线（纯样式 + 一个字段选项，不改数据结构、不改提交）。
+
+> **P0 / P1 的实现级规格已分别成文**：
+> - `2026-08 xform H5 P0 实现规格.md` —— 样式规则清单与特异度策略、`h5Span` 三步挂点、
+>   老表单 `upgradeWidgetConfig` 补 null 的兼容口径、自测清单。
+> - `2026-08 xform H5 P1 实现规格.md` —— 骨架 flex 化与高度来源、底栏胶囊与「更多」分流
+>   （含 `el-dropdown-menu` append-to-body 的作用域坑）、`list-h5` 卡片皮肤与行级对比标记。
+>   **附带查实：三个弹框里的 `.H5` 底栏补丁全是死代码，H5 表单在弹框中底栏实际钉在屏幕底部，
+>   属现存 bug，由 P1 骨架改动修掉。**
+> - `2026-08 xform H5 P2 实现规格.md` —— 审批移动化（**修正决策 9**）、附件 74px 口径统一、
+>   页签皮肤。**附带查实：H5 表单的审批 UI 目前一概没挂上，P2 是从零到有而非换皮。**
+>
+> **进度：P0 / P1 / P2 均已编码完成**（2026-08-25，lint 无新增错误 + 601 单测全过 + 生产构建通过），待真机联调。
+> P2 的页签一项按拍板跳过；P3（清理）未开始。
+
+---
+
+## 八、待确认
+
+1. **PC 浏览器预览 H5 表单**要不要 `max-width:640 + 居中`？
+   bill_setting 有（`.h5-wrap`），xform 现在没有。加了 PC 预览更像手机，真机上无影响。倾向：加。
+2. **`h5Span` 是新选项还是复用 `fieldSize`？**
+   `fieldSize` 是 bill_setting 自己的字段协议，xform 字段 options 里没有同名字段。
+   倾向：新增 `h5Span`，语义自洽，不跨协议借词。
+3. **`style.scss` 里存量 `.h5-*`（13740-13990）搬不搬进包内？**
+   搬 = 彻底解决「不随包发布」，但可能影响仍在用这批类名的手写移动页（`components/mobile/*`）。
+   倾向：**先并存**（包内 `.xform-h5` 作用域优先级更高），P3 再评估回收。
+4. **stdxx / com@publish 两条分支怎么同步？**
+   既有约定：stdxx 是海尔分支，「JS 可覆盖、样式不覆盖、settings 增量」。
+   本次样式全部收在包内新文件 `.xform-h5` 下，**理论上可随 JS 一起整体覆盖**，
+   不触碰分支各自的 `style.scss` —— 这也是决策 2 的附带收益。需分支负责人确认。
+5. **底栏「更多」的默认阈值** `maxVisibleButtons` 取 2 还是 3？
+
+---
+
+## 九、验收基线
+
+同一张单据，分别用 bill_setting H5 与 xform H5 渲染，逐项对照：
+
+1. 标题栏高度/字号/居中；
+2. 卡片圆角、间距、标题竖条位置；
+3. 字段行高 48px、标签宽 80px 带冒号、值右对齐、输入框无边框；
+4. 半宽字段两列不错位（含长文本换行、必填星号位置）；
+5. 明细卡片：主字段标题 + 圆点 + 右箭头；点开详情弹框字段齐全；
+6. 附件 74px 网格 + 相机格子 + 删除角标；
+7. 底栏胶囊按钮；超阈值时收「更多」；键盘弹起底栏不飞；
+8. 内容区滚动时标题栏与底栏不动；
+9. 审批：通过/驳回/转办走移动弹框；
+10. 对比模式：字段级感叹号 + 明细行级标记。

package/src/components/xform/docs/2026-08 /345/210/227/350/241/250/345/257/274/345/207/272/350/204/261/346/225/217/345/210/227/345/211/224/351/231/244/350/220/275/345/234/260/346/226/207/346/241/243.md"

@@ -0,0 +1,173 @@
+# 列表导出脱敏列剔除（2026-08）
+
+> 起因：配置了「加密」（密文文本）的字段，页面显示 `138****1234`，导出 Excel 却是完整明文。
+> 排查范围：`src/components/xform/**`、`src/components/excelExport/**`、`src/components/table/**`。
+
+## 一、问题定性
+
+「加密」是**纯前端展示遮罩**，不是数据加密：
+
+- 配置入口：属性面板 `textFlag-editor.vue` → `options.userTextRuleEnabled` + `options.userTextRuleConfig[]`
+- 单条规则 `{ serveName, companyCodes, roleCodes, type, encryptFormula }`，`type=1` 角色不匹配时脱敏、`type=2` 角色匹配时脱敏，`encryptFormula` 形如 `3*3`
+- 改造前实现只有一处：`form-item-wrapper.vue` —— `created` → `initShowType()` 算出 `widgetTextFlag=2`，模板改渲染 `<span>{{ getShowValue() }}</span>`，`getShowValue()` → `getProcessText()` 做星号替换
+
+**原始值始终完整存在于 `row[field]` / `fieldModel` 中**，遮罩只发生在渲染层。
+
+## 二、根因：导出取值绕开渲染层
+
+导出取值优先级（`excelExport/mixins.js:828 getExportCellValue`）：
+
+1. `column.params.exportVal`
+2. **`column.slots.filterVal(params)`** ← 命中点
+3. 无自定义渲染 → `row[field]`（有 `formatter` 则格式化）
+4. 兜底 `getCellValue()`：挂载 vNode 渲染再爬 DOM
+
+而 `data-table-mixin.js:1888` 对 `input / number / text / select / checkbox / radio / status / vabsearch / date / textarea / a-link / a-text` 这 12 类组件列统一注册了 `col.slots.filterVal`，函数体直接返回 `row[field]`（select/radio/checkbox 返回 optionLabel，vabsearch 返回 label 字段，date 返回格式化值）——**整条路径不碰 `form-item-wrapper`，不读 `widgetTextFlag`**。
+
+这 12 类恰好是最常配脱敏的字段类型。副作用是不一致：不在这 12 类里的组件列（`slots.default = "widget"`，无 `filterVal`）走第 4 条兜底，会真实渲染 wrapper 并爬 DOM，**导出的反而是星号**。同一张表有的列明文、有的列打码，且非有意设计。
+
+其它同源泄漏点：
+
+| 路径 | 改造前 |
+|---|---|
+| 明细导出（`exportItemColumns`，`data-table-mixin.js:2406`） | 必明文：列只有 `field/title`，行数据后端原样返回 |
+| 条件导出 / 全量导出 | 明文：`loopToDo` 分页拉后端原始行 → 同一个 `getExcelData` |
+| H5 列表容器 `list-h5-item.vue` | 明文：独立 `exportData`，列带 `params.widget` 但无 `filterVal` |
+| vxe 工具栏自带导出（`table/index.js` `exportConfig`） | 明文：vxe 用行原始值 |
+| 列筛选下拉候选值（`vxeFilter/mixin.js`） | 明文（不属导出，本轮未处理） |
+| 接口响应 / JS 内存 | 明文（需后端脱敏，前端不可解） |
+
+## 三、方案选型
+
+| 档位 | 做法 | 结论 |
+|---|---|---|
+| 1 | 前端一致性：给 `filterVal` 结果也套一层遮罩 | 未选。要同步改 4 处取值路径，且"导出打码值"对下游数据消费无意义 |
+| **2** | **命中脱敏规则的列直接整列不导出** | **本次采用** |
+| 3 | 后端按角色脱敏返回 / 提供脱敏导出接口 | 真正解法，本轮范围外。方案 1、2 都只是"看不见"，不是"拿不到" |
+
+方案 2 之所以成立：**所有导出（列表 / 条件 / 选择 / 明细）都必须先过 `exportFieldDialog`**（`mixins.js:133` 是唯一入口，`:1072` 回传 columns/leafColumns），而 `params.exportDisabled` 已被三处消费：
+
+| 位置 | 效果 |
+|---|---|
+| `exportFieldDialog.vue:95 filterNonDataExportColumns`（`:160` 调用） | 字段选择树里不出现该列，子列全没了则父分组也去掉 |
+| `exportFieldDialog.vue:319 dialogConfirm→loopDo` | 生成表头 JSON 时跳过 |
+| `excelExport/mixins.js:860 getExcelData` | 取数时过滤 `leafColumns` |
+
+所以只要把标记打到列上即可一次收口，无需改任何取值逻辑。
+
+> 曾评估过变体「保留表头、值置空」：需给通用 `excelExport` 新增 `exportMasked` 语义，且整列空白易被下游误读成"该记录无值"，已否决。
+
+## 四、改动清单
+
+### 1. 新增 `src/components/xform/utils/textMaskUtil.js`
+
+脱敏判定的**唯一实现**，渲染侧与导出侧共用（否则界面打码、导出放行必然漂移）。
+
+| 导出 | 职责 |
+|---|---|
+| `resolveTextMaskFlag(widgetOptions, ctx)` | 判定是否脱敏 + 带出命中的 `encryptFormula` |
+| `compareToList(list1, list2)` | 编码列表匹配，空列表表示不限 |
+| `hasTextMaskRule(widgetOptions)` | 是否配了有效规则（不代表当前用户命中） |
+| `buildTextMaskContext(formRef, companyCode)` | 组装 `{ bdService, companyCode, roleCodeList }` |
+| `markMaskedExportColumns($grid, ctx)` | 给命中列打 `params.exportDisabled`，并同步到明细导出列 |
+
+判定逻辑逐行照搬原 `initShowType`，包括两个易被"优化"掉的细节：
+
+- 规则列表**全遍历而非命中即止**，后置规则会覆盖前置结论；
+- `encryptFormula` 只要 serveName/companyCodes 命中就赋值，与 masked 与否无关。
+
+### 2. `form-item-wrapper.vue:676 initShowType`
+
+保留两个早退外壳（`!!this.designer`、`isLoadEntity && !dataId`）与 `field.options.widgetTextFlag` 写回，中间判定改调 util。行为等价，净减 73 行。
+
+`compareToList` 保留为薄封装委托 util —— 本包对外发布，不删以免破坏下游调用。
+
+### 3. `data-table-mixin.js`
+
+- `:3231 markMaskedColumnsForExport()` —— 3 行委托 util
+- `:3245 exportData()` 入口调用
+- `:253 mounted` 建列后 `$nextTick` 再调一次（见下节决策 3）
+
+### 4. `list-h5-item.vue:1664 / :1671`
+
+H5 列表容器有独立 `exportData`，同样处理。这是编码阶段才发现的第二条泄漏路径。
+
+### 5. `components/table/index.js:580`
+
+`exportConfig` 增加 `columnFilterMethod`，堵 vxe 工具栏自带导出旁路。
+
+**行为变化**：原有的操作列、图片列等 `exportDisabled` 列也会从原生导出中消失。属修正，但需业务知晓。
+
+### 6. `tests/unit/components/xform/textMaskUtil.spec.js`
+
+17 个用例，覆盖规则匹配的各分支、fail-closed、自愈还原、分组表头递归、明细列对齐。
+
+## 五、关键设计决策
+
+**决策 1 —— 判定放在导出触发时，不放在建列时。**
+`bdService` / `userRoleDTOs` 由异步接口填充（`form-render/indexMixin.js:458、479、498`），建列时可能尚未就绪。
+
+**决策 2 —— 不做"上下文未就绪"的收紧判断（踩过坑，见第十节）。**
+判定结论与渲染层严格一致即可：同一个 `resolveTextMaskFlag`、同一份用户上下文，且导出必然发生在单元格渲染之后（用户已经看到明文或密文）。**不要再引入任何"上下文是否就绪"的启发式**。
+
+**决策 3 —— `mounted` 也标记一次。**
+vxe 原生导出不走 `exportData()`，若只在导出入口标记，`columnFilterMethod` 会拿到一张没标记的列表，等于没堵。故建列后先按当时的上下文标记一次；此刻结论未必准，但只会"少防护"不会误伤，之后每次 `exportData` 会按最新上下文自愈修正。
+
+**决策 4 —— 标记幂等且可自愈，用私有键区分归属。**
+`exportDisabled` 也可能是 `isNonDataExportColumn`（`data-table-mixin.js:1710`）打的。若无差别地 `delete`，自愈会误放行操作列。故引入 `MASK_MARK_KEY = "exportDisabledByTextMask"`（`textMaskUtil.js:19`）：
+
+- 列本就带 `exportDisabled` 且无私有键 → 不接管，不打私有键
+- 由本函数从无到有打上 → 同时写私有键
+- 撤销时只在私有键存在时才删
+
+## 六、覆盖范围
+
+| 泄漏点 | 现状 |
+|---|---|
+| 列表导出 / 条件导出 / 选择导出 | ✅ 堵住 |
+| H5 列表导出 | ✅ 堵住 |
+| 明细导出 | ⚠️ 按 field 名对齐，见局限 L1 |
+| vxe 工具栏原生导出 | ✅ 决策 3 + 改动 5 |
+| 列筛选下拉候选值明文 | ❌ 未纳入（不属导出） |
+| 接口响应 / JS 内存明文 | ❌ 需后端脱敏 |
+| 打印 / PDF | 走 DOM，应是打码的，**未验证** |
+| 单元格区域复制 | **未验证**，疑似明文 |
+
+## 七、已知局限
+
+- **L1**：明细导出列只有 `field/title`，只能按字段名匹配主表脱敏字段集合。明细独有字段、或明细导出脚本返回的字段名与主表不一致时，仍会明文导出。
+- **L2**：动态列 / 行级 schema（`fieldSchemaMap`）下同列不同行配置可能不同，判定按列模板走；模板未配、个别行配了的情况会漏。
+- **L3**：表单低代码脚本里直接读 `row.xxx`、或列上配了自定义 `params.exportVal` 的，不受影响。
+- **L4**：脱敏是**列级**判定；将来若出现行级脱敏，本方案不适用。
+- **L5**：`exportFieldDialog.addTableExportColumns()`（`:252`）会把勾选状态持久化到 `$grid.exportColumns`。脱敏列不在树里 → 记为 `export:false`。同一用户换成不脱敏角色后，该列默认不勾选，需手动勾一次。
+
+## 八、验证情况
+
+已验证：
+
+- `npx jest`：13 套 157 个用例全过（新增 18 个）
+- ESLint：新增文件 0 error；改动文件只剩改动前就存在的既有错误（全库 132 个，`npm run lint` 本就不通过）
+
+**未做真机联调**，以下回归项待验：
+
+1. 配了脱敏的字段列，四种导出（列表 / 条件 / 选择 / 明细）文件中均无该列；
+2. 两种规则方向：`type=2 + 角色匹配`、`type=1 + 角色不匹配`；
+3. 未配脱敏的列完全不受影响；
+4. **分组表头 2 层 / 3 层下剔除叶子列后表头不错位**（`loopDo` 会重算 `colSpan/rowSpan`，本轮风险最高的一处）；
+5. 页面遮罩显示效果与改造前一致（验证 `initShowType` 重构无回归）；
+6. vxe 工具栏导出（若宿主开启了该按钮）。
+
+## 九、联调发现的问题（2026-08-04，已修）
+
+**现象**：配了规则后，部分用户看明文、部分看密文（符合预期），但**所有用户导出时该列都消失**。
+
+**根因**：首版实现有一个 `isTextMaskContextReady(ctx)`，用 `ctx.bdService` 非空 + 角色列表非空当作"用户上下文已就绪"的判据，未就绪时 fail-closed 剔除整列。但 `bdService` 来自 `/form_develop/getBdService`（`indexMixin.js:489`），`res.objx` 在大量环境本就是空值 —— 于是 `contextReady` 恒为 false，凡配了规则的列对所有用户一律被剔除。
+
+**修复**：删除 `isTextMaskContextReady`，`markMaskedExportColumns` 直接采用 `resolveTextMaskFlag` 的结论。
+
+**教训**：fail-closed 本身没错，错在"就绪"判据是拿业务值反推运行状态的启发式。这里根本不需要它 —— 渲染层用同一函数、同一上下文，且导出必然晚于渲染，结论天然一致；页面显示什么，导出就该按什么处理。回归用例见 spec 中「bdService 为空时结论仍只由规则决定」。
+
+## 十、同步提示
+
+- `textMaskUtil.js` 属包内新增文件，海尔分支（stdxx）整体覆盖时需一并带上，否则 `form-item-wrapper.vue` 与两个容器的 import 会解析失败；
+- 改动 5 落在 `components/table/index.js`（通用表格默认配置），影响面超出 xform，同步时注意与分支上的本地修改合并。