cloud-web-corejs 1.0.54-dev.8 → 1.0.54-dev.800

package/src/components/bizTab/bizBillDetailMixin.js

@@ -0,0 +1,687 @@
+/**
+ * 单据详情通用 mixin —— 配合 BizTabListPage 使用。
+ *
+ * 负责这几件事（宿主页面只写业务表单和取数/保存请求）：
+ *   1. 取数时把流程信息挂到详情页（复用 mixins/wf 的 _getBillInfo → wfUtil.initWf）
+ *   2. 新增页就能「保存并提交」：先静默保存拿单号，立刻拉起启动流程弹框
+ *   3. 流程动作完成后按配置「刷新本页」或「关页签回列表刷新」
+ *   4. 流程审批点「通过」时自动保存单据（先校验、后保存、再提交任务）
+ *   5. 上一单 / 下一单翻单（列表侧把 navRows/navIndex 传进来才有）
+ *
+ * 宿主页面必须实现：
+ *   billOptions        computed/data，见下方 defaultBillOptions
+ *   buildLoadRequest(dataId) -> { url, method, data }   取单据详情的请求
+ *   applyBillData(objx)                                 把详情数据灌进表单模型；objx 为 null 表示新增
+ *   saveBill({ confirm, successMsg }) -> Promise<dataId> 保存，返回单号（新增时是新单号）
+ *
+ * 宿主页面可选实现：
+ *   validateBill()  -> Promise<Boolean>   默认校验 $refs.editForm + $refs.extraForm
+ *   validateBillData()-> String|false     数据级校验（子表必填等），返回文案即中止
+ *   getBillTitle()  -> String             默认取表单模型的 titleField
+ *   canEditBill()   -> Boolean            默认「流程没启动、或当前节点允许改」；
+ *                                         字段禁用与保存按钮显隐的唯一判据
+ *   canSaveOnAgree()-> Boolean            默认 wfInfo.toModify === true
+ *   canStartWf()    -> Boolean            默认 true；按单据状态卡「提交流程」就覆盖它
+ *   isBillDirty()   -> Boolean            实现了它，关页签时就按它提示未保存
+ *
+ * 不在页签里独立使用（如从待办直接打开详情）也能跑：此时退回 $baseReload 的默认行为。
+ */
+import wfMixin from "@base/mixins/wf/index";
+import { checkRequired, checkRows } from "./billValidators";
+import { openStartWfDialog } from "@base/components/wf/wfUtil";
+import {
+  getWfButtonNames,
+  loadWfButtonNames,
+  DEFAULT_SUBMIT_BTN,
+  DEFAULT_SAVE_SUBMIT_BTN,
+} from "@base/components/wf/wfButtonName";
+
+// wf 组件回调 _handleCallback(flag) 的 flag → 页签行为类型
+const WF_FLAG_KIND = {
+  1: "agree", // 通过（提交任务）
+  2: "reject", // 驳回
+  3: "interrupt", // 中断 / 撤回
+  4: "transfer", // 转办
+  5: "talk", // 沟通
+};
+
+const defaultBillOptions = {
+  prefix: "", // 服务前缀，如 PMD_PREFIX
+  serviceId: null, // 流程服务名；不传则从 prefix 里取（"/pmd" → "pmd"）
+  formCode: null, // 表单编码
+  taBm: null, // 主表表名
+  wfCode: null, // 流程编码
+  titleField: "name", // 页签标题字段
+  wfEnabled: true, // 是否启用流程
+  saveSubmitEnabled: true, // 新增页是否显示「保存并提交流程」
+  wfStartBindSave: true, // 点「提交流程」时是否先校验并自动保存
+  wfAgreeBindSave: true, // 审批点「通过」时是否自动保存单据
+  /**
+   * 流程中（节点不允许改单据时）仍然放开的字段。两种写法：
+   *   ["memo", "amount"]                 所有节点都放开这几个
+   *   { "2": ["amount"], "*": ["memo"] } 按 wfInfo.taskStep 分节点，"*" 兜底
+   * 只配这里不会自动生效——模板上还要给那个字段套一层 <el-form> 隔断整片禁用，
+   * 因为 element 的 inputDisabled 是 `this.disabled || elForm.disabled`（OR），
+   * 整片禁用后单个字段传 :disabled="false" 是压不回来的。详见 README。
+   */
+  wfEditableFields: null,
+  /**
+   * 启动流程时带给流程引擎的业务参数（/wf/start 的 formData，流程里做条件分支用）。
+   * 可以是对象，也可以是函数（this 指向详情组件，每次启动时求值，适合取当前表单值）。
+   */
+  startParam: null,
+  hiddenAllButton: false, // true = 流程面板上所有操作按钮都不出（纯查看态）
+  showModifyBtn: true, // 是否放出 wfUtil 注入的「修改单据」按钮
+  hideWf: false, // true = 不挂流程信息面板（wfUtil 读详情组件的 _hideWf）
+};
+
+// 必须由宿主页面实现的钩子，缺了只会在运行到某一步时莫名其妙地崩，所以开发期先喊一声。
+// buildLoadRequest 不在这里查：取数不走 $http 的页面会整个覆盖 loadBill()，那时它就不需要。
+const REQUIRED_HOOKS = ["applyBillData", "saveBill"];
+
+export default {
+  mixins: [wfMixin],
+  inject: {
+    bizTabHost: { default: null },
+  },
+  props: {
+    // 页签对象，由 BizTabListPage 的 #detail 插槽透传；独立使用时不传
+    tab: {
+      type: Object,
+      default: () => null,
+    },
+    // 独立使用（待办打开、旧页面内嵌）时的单号入口
+    _dataId: [String, Number],
+  },
+  data() {
+    return {
+      dataId: null,
+      hasWf: false,
+      wfChecked: false, // 是否已查过流程状态；查完再决定要不要显示「提交流程」，避免闪一下
+      wfInfo: null,
+      wfParam: {},
+      billSaving: false,
+      billSubmitting: false, // 启动流程弹框已拉起、尚未落地：期间不许再点保存
+    };
+  },
+  computed: {
+    billConfig() {
+      return Object.assign({}, defaultBillOptions, this.billOptions || {});
+    },
+    isAdd() {
+      return this.dataId == null || this.dataId === "" || this.dataId === 0;
+    },
+    // 「保存并提交流程」：只在新增页、且流程没启动时出现
+    showSaveSubmitBtn() {
+      let cfg = this.billConfig;
+      if (!cfg.wfEnabled || !cfg.saveSubmitEnabled || !cfg.wfCode) return false;
+      return this.isAdd && !this.hasWf && this.canStartWf();
+    },
+    // 「提交流程」：已有单号、流程状态已查回、且尚未启动
+    showWfStartBtn() {
+      let cfg = this.billConfig;
+      if (!cfg.wfEnabled || !cfg.wfCode) return false;
+      return !this.isAdd && this.wfChecked && !this.hasWf && this.canStartWf();
+    },
+    /**
+     * 单据当前是否只读。绑到 el-form 的 :disabled 上，表单里的字段就整片自动禁用，
+     * 不用逐个字段绑（详情页模板那两条约束里有怎么写）。
+     * 判据只看流程；要叠加单据状态（作废/已完结不许改）就覆盖 canEditBill()。
+     */
+    billDisabled() {
+      return !this.canEditBill();
+    },
+    // 当前节点放开的字段清单（解析 billOptions.wfEditableFields）
+    wfEditableFields() {
+      return this.getWfEditableFields();
+    },
+    /**
+     * 是否不挂流程信息面板。名字必须是这个：wfUtil 读的是详情组件上的
+     * `that._hideWf || that.$attrs._hideWf`，不是 wfConfig 里的字段。
+     * （另外两个同类开关 defaultShowWfContent / toWfArea 也只认 $attrs，
+     *   直接写在详情组件标签上即可：<bill-detail :tab="tab" default-show-wf-content />）
+     */
+    _hideWf() {
+      return this.billConfig.hideWf === true;
+    },
+    submitButtonName() {
+      return getWfButtonNames().submitBtn || this.$t1(DEFAULT_SUBMIT_BTN);
+    },
+    saveSubmitButtonName() {
+      return (
+        getWfButtonNames().saveSubmitBtn || this.$t1(DEFAULT_SAVE_SUBMIT_BTN)
+      );
+    },
+    // ===== 上一单 / 下一单：快照由列表侧 openDetail(row, param, {navRows, navIndex}) 带进来 =====
+    billNavState() {
+      let tab = this.tab;
+      if (!tab || tab.isAdd) return null;
+      let rows = tab.navRows;
+      if (!Array.isArray(rows) || !rows.length) return null;
+      return { rows, index: tab.navIndex == null ? -1 : tab.navIndex };
+    },
+    canPrevBill() {
+      let state = this.billNavState;
+      return !!state && state.index > 0;
+    },
+    canNextBill() {
+      let state = this.billNavState;
+      return !!state && state.index >= 0 && state.index < state.rows.length - 1;
+    },
+  },
+  created() {
+    // 页签模式下单号以 tab.dataId 为准（新增页签是 null），独立使用时取 _dataId
+    let dataId = this.tab ? this.tab.dataId : this._dataId;
+    this.dataId = dataId == null || dataId === 0 ? null : dataId;
+    loadWfButtonNames(this);
+    this.checkBillHooks();
+    // 登记到宿主：关页签确认要问详情脏没脏、翻单要按 tabName 找回实例
+    let host = this.bizTabHost;
+    if (host && this.tab) host.registerDetail(this.tab, this);
+  },
+  methods: {
+    checkBillHooks() {
+      if (process.env.NODE_ENV === "production") return;
+      if (!this.billOptions) {
+        console.warn(
+          "[bizBillDetailMixin] 详情页缺少 billOptions（单据/流程配置），流程相关功能不会生效"
+        );
+      }
+      REQUIRED_HOOKS.forEach((name) => {
+        if (typeof this[name] !== "function") {
+          console.warn(`[bizBillDetailMixin] 详情页缺少必须实现的 ${name}()`);
+        }
+      });
+    },
+
+    // ===== 取数 =====
+    loadBill() {
+      if (this.isAdd) {
+        this.applyBillData(null);
+        return Promise.resolve();
+      }
+      let cfg = this.billConfig;
+      if (typeof this.buildLoadRequest !== "function") {
+        if (process.env.NODE_ENV !== "production") {
+          console.warn(
+            "[bizBillDetailMixin] 详情页既没实现 buildLoadRequest()、也没覆盖 loadBill()，取不到数据"
+          );
+        }
+        return Promise.resolve();
+      }
+      let request = this.buildLoadRequest(this.dataId) || {};
+      return this._getBillInfo({
+        method: "post",
+        isLoading: true,
+        modalStrictly: true,
+        ...request,
+        // 流程未启用、或本身就是新增时不挂流程
+        wfConfig: cfg.wfEnabled && cfg.wfCode ? () => this.buildWfOption() : null,
+        success: (res) => {
+          this.applyBillData((res && res.objx) || null);
+          // 取数回来再同步一次页签标题：保存接口通常只回主键，不回单号，
+          // promoteTab 那一刻标题字段还是空的，页签会一直停在「新增」。
+          this.syncTabTitle();
+        },
+      });
+    },
+    // 把当前模型的标题字段同步到页签（空值保持原标题，由宿主判定）
+    syncTabTitle() {
+      let host = this.bizTabHost;
+      if (!host || !this.tab) return;
+      host.syncTabTitle(this.tab, this.getBillTitle());
+    },
+
+    // ===== 流程选项：initWf 挂载、提交流程按钮、保存并提交，三个入口共用 =====
+    buildWfOption(overrides) {
+      let cfg = this.billConfig;
+      let option = {
+        objId: this.dataId,
+        wfCode: cfg.wfCode,
+        formCode: cfg.formCode,
+        // 显式传：mixins/wf 的 _getBillInfo 只在没传时才按取数 url 首段推导服务名
+        serviceId: this.getServiceId(),
+        showStartBtn: true,
+        // 启动按钮由 BizBillActions 声明式渲染，不让 wfUtil 往 DOM 里塞
+        injectStartBtn: false,
+        showWfFold: true,
+        // 启动流程带给流程引擎的业务参数（/wf/start 的 formData）
+        startParam: this.getWfStartParam(),
+        // 纯查看态藏掉流程面板全部按钮 / 控制「修改单据」按钮
+        hiddenAllButton: cfg.hiddenAllButton === true,
+        showModifyBtn: cfg.showModifyBtn !== false,
+        // 自己控制 done 的时机：等详情数据渲染完再挂流程面板，避免取不到 .d-cont
+        auto: false,
+        // 启动确认文案跟随后台 param18 的按钮名，和「保存并提交」那条链路口径一致
+        startConfirmText: () =>
+          this.$t1(`您确定要${this.submitButtonName}吗？`),
+        callback: (wfParam) => {
+          this.wfParam = wfParam || {};
+          this.hasWf = !!this.wfParam.hasWf;
+          this.wfInfo = this.wfParam.wfInfo || null;
+          this.wfChecked = true;
+          this.$nextTick(() => {
+            this.wfParam.done && this.wfParam.done();
+          });
+        },
+        // 流程启动成功 → 按配置刷新本页 / 关页签回列表
+        onStartSuccess: () => this.onWfActionDone("submit"),
+        // 失败/取消都要解掉提交态；是否顺带刷详情看本次有没有真的存过（见 onWfStartAbort）
+        onStartFail: () => this.onWfStartAbort(),
+        onCancel: () => this.onWfStartAbort(),
+      };
+
+      if (cfg.wfStartBindSave) {
+        // 启动流程时自动保存：先校验（弹框前），再保存（确认后、提交前）。
+        option.onStart = (done) => {
+          this.validateBill().then((valid) => {
+            if (valid) done();
+          });
+        };
+        option.onBeforeStartSubmit = (done) => {
+          this.runSave({ confirm: false, successMsg: false }).then((dataId) => {
+            if (dataId == null || dataId === "") return;
+            this.promoteAfterSave(dataId);
+            // 到这里单据已入库、只等提交：此后必然走 onStartSuccess/onStartFail/onCancel
+            // 三者之一，置提交态是安全的（不像启动确认框那样有取消不回调的空档）。
+            this.billSubmitting = true;
+            this._wfStartSaved = true; // 本次启动伴随了保存 → 失败/取消时要刷到编辑态
+            done();
+          });
+        };
+      }
+
+      if (cfg.wfAgreeBindSave) {
+        // 审批「通过」自动保存单据：
+        //   onClickAgree —— 点通过、意见框弹出「之前」校验，避免填完意见才报必填
+        //   onBeforeAgree —— 点确定、调 /wf/submit 「之前」静默保存
+        option.onClickAgree = (done) => {
+          if (!this.canSaveOnAgree()) return done();
+          this.validateBill().then((valid) => {
+            if (valid) done();
+          });
+        };
+        option.onBeforeAgree = (done) => {
+          if (!this.canSaveOnAgree()) return done();
+          this.saveBill({ confirm: false, successMsg: false }).then((dataId) => {
+            if (dataId == null || dataId === "") return;
+            done();
+          });
+        };
+      }
+
+      return Object.assign(option, overrides || {});
+    },
+
+    // ===== 按钮行为 =====
+    // 普通保存：新增保存后就地升为编辑态并刷新一次（出流程信息 / 切只读态）
+    async saveHandle() {
+      if (!(await this.guardSaving())) return false;
+      let valid = await this.validateBill();
+      if (!valid) return false;
+      let dataId = await this.runSave({ confirm: true, successMsg: true });
+      if (dataId == null || dataId === "") return false;
+      this.promoteAfterSave(dataId);
+      this.reloadDetail();
+      return true;
+    },
+
+    /**
+     * 保存并提交流程（新增页上的一步到位入口）。
+     *
+     * 顺序：校验 → 确认 → 静默保存拿单号 → 只升级页签元数据（不刷详情）→ 拉起启动流程弹框。
+     * 保存完立刻升级成编辑态是关键：万一随后提交失败或关掉候选人弹框取消了，
+     * 再点一次也是「更新」而不是「再新增一张」；详情那一次刷新留给流程结束分支，不刷两遍。
+     */
+    async saveAndSubmitHandle() {
+      let cfg = this.billConfig;
+      if (!cfg.wfEnabled || !cfg.wfCode) return false;
+      if (!(await this.guardSaving())) return false;
+      let valid = await this.validateBill();
+      if (!valid) return false;
+      let confirmText = this.$t1(`您确定要${this.saveSubmitButtonName}吗？`);
+      try {
+        await this.$baseConfirm(confirmText);
+      } catch (e) {
+        return false;
+      }
+      let dataId = await this.runSave({ confirm: false, successMsg: false });
+      if (dataId == null || dataId === "") return false;
+      this.promoteAfterSave(dataId);
+      // 弹框拉起后到流程落地之间，单据已入库但还没提交：这段时间禁掉保存，避免并发写
+      this.billSubmitting = true;
+      this._wfStartSaved = true; // 已经存过了 → 失败/取消都要把详情刷到编辑态
+      openStartWfDialog(
+        this,
+        this.buildWfOption({
+          objId: dataId,
+          skipStartConfirm: true, // 已经确认过一次了，不再弹第二次
+          onStart: null, // 校验/保存都做完了，不再走 wfStartBindSave 那套
+          onBeforeStartSubmit: null,
+        })
+      );
+      return true;
+    },
+
+    // 「提交流程」按钮（已有单号、流程未启动）
+    startWfHandle() {
+      let cfg = this.billConfig;
+      if (!cfg.wfEnabled || !cfg.wfCode || this.isAdd) return;
+      // 这里不置 billSubmitting：单模板 + 启动确认框那条路，用户点「取消」时
+      // wfStartDialog 既不 close 也不回调 onCancel（close 只挂在 el-dialog 的 @close 上，
+      // 而那种情况 showDialog 从没置过 true），置了就再没人来解，保存按钮会永久禁用。
+      // 真正需要防并发的窗口是「已入库、待提交」，由 onBeforeStartSubmit 内部置。
+      openStartWfDialog(this, this.buildWfOption());
+    },
+
+    // 上一单 / 下一单
+    gotoPrevBill() {
+      this.navigateBill(-1);
+    },
+    gotoNextBill() {
+      this.navigateBill(1);
+    },
+    // 返回 Promise<Boolean>：宿主会先确认有没有未保存的修改，再决定翻不翻
+    navigateBill(step) {
+      let host = this.bizTabHost;
+      if (!host || !this.tab) return Promise.resolve(false);
+      return host.navigateTab(this.tab, step);
+    },
+
+    // ===== 流程结束后的页签行为 =====
+    /**
+     * 某个流程动作成功后走这里。behavior 由列表宿主配置：
+     *   refreshCurrent 刷新当前页签（默认）
+     *   closeToList    关页签 → 回列表 → 刷新列表
+     */
+    onWfActionDone(kind, alreadyReloaded) {
+      this.billSubmitting = false;
+      this._wfStartSaved = false;
+      let host = this.bizTabHost;
+      if (!host || !this.tab) {
+        // 不在页签里（待办直开等）：保持原有行为。
+        // alreadyReloaded 表示 wf 的 reloadContent() 已经刷过一次了，别再刷第二次。
+        if (!alreadyReloaded) this.reloadDetail();
+        return;
+      }
+      if (host.getBehavior(kind) === "closeToList") {
+        this.cancelPendingReload();
+        host.closeTabToList(this.tab);
+      } else if (!this._reloadTimer) {
+        host.refreshTab(this.tab);
+      }
+    },
+    /**
+     * 启动流程失败 / 取消（关掉启动弹框或候选人弹框、后台没配流程单据直接被 close 掉…）。
+     *
+     * 只有「本次启动确实伴随过保存」才刷详情——保存过不刷，页面会停在新增态、看不到单号；
+     * 没保存过就刷是纯粹的打扰：比如后台没配流程单据时 wf 会弹「无法启动，没有流程单据」
+     * 然后 close()，这时什么都没发生，用户看到的却是详情整个重载（还会丢掉未保存的编辑）。
+     * 判据不能用 wfStartBindSave 这个配置项：它只说明「会不会存」，不说明「这次存没存」。
+     */
+    onWfStartAbort() {
+      this.billSubmitting = false;
+      if (!this._wfStartSaved) return;
+      this._wfStartSaved = false;
+      this.reloadDetail();
+    },
+
+    /**
+     * wf 组件在「通过/驳回/中断/转办/沟通」成功后调用（wf.js closeWinOnCheck）。
+     *
+     * 注意时序：wf 那边是 reloadContent() 先跑、closeWinOnCheck() 后跑，也就是
+     * 先触发一次刷新，才轮到这里告诉我们本次是什么动作。所以下面的 $baseReload
+     * 把刷新延后一拍，这里若判定要关页签，就把那次刷新撤掉，不做无用功。
+     */
+    _handleCallback(flag) {
+      let kind = WF_FLAG_KIND[flag];
+      if (!kind) return;
+      this.onWfActionDone(kind, true);
+    },
+
+    /**
+     * 覆盖全局的 $baseReload（Vue.prototype 上那个 $emit("reload")）。
+     * wf 组件内部所有刷新都硬编码走 $baseReload，覆盖它是把流程刷新接进页签体系
+     * 又不改 wf.js 的唯一切口。不在页签里时原样退回默认实现。
+     */
+    $baseReload(param) {
+      let host = this.bizTabHost;
+      if (!host || !this.tab) {
+        this.$emit("reload", this, param);
+        return;
+      }
+      this.cancelPendingReload();
+      this._reloadTimer = setTimeout(() => {
+        this._reloadTimer = null;
+        host.refreshTab(this.tab);
+      }, 0);
+    },
+
+    // ===== 内部工具 =====
+    reloadDetail() {
+      let host = this.bizTabHost;
+      if (host && this.tab) {
+        this.cancelPendingReload();
+        host.refreshTab(this.tab);
+      } else {
+        this.$emit("reload", this, { updateParam: { _dataId: this.dataId } });
+      }
+    },
+    cancelPendingReload() {
+      if (this._reloadTimer) {
+        clearTimeout(this._reloadTimer);
+        this._reloadTimer = null;
+      }
+    },
+    // 保存成功后：本地转编辑态 + 页签元数据升级（转编辑态、换标题），不重渲染
+    promoteAfterSave(dataId) {
+      this.dataId = dataId;
+      let host = this.bizTabHost;
+      if (host && this.tab) {
+        host.promoteTab(this.tab, { dataId, title: this.getBillTitle() });
+      }
+    },
+    async runSave(options) {
+      this.billSaving = true;
+      try {
+        return await this.saveBill(options);
+      } finally {
+        this.billSaving = false;
+      }
+    },
+    async guardSaving() {
+      if (this.billSaving || this.billSubmitting) {
+        this.$message.warning(this.$t1("数据正在保存，请勿重复操作"));
+        return false;
+      }
+      return true;
+    },
+    getServiceId() {
+      let cfg = this.billConfig;
+      if (cfg.serviceId) return cfg.serviceId;
+      return (cfg.prefix || "").replace(/^\//, "") || null;
+    },
+
+    // ===== 可被宿主页面覆盖的默认实现 =====
+    /**
+     * 校验单据。默认校验 $refs.editForm，外加 $refs.extraForm（可以是 v-for 出来的数组）。
+     *
+     * extraForm 是给「流程中放开的字段」用的：那些字段套在内层 <el-form> 里，
+     * el-form-item 只会向最近的 form 注册（form-item.vue 的 dispatch('ElForm')），
+     * 所以外层 editForm 压根不认识它们，不给内层也校一遍就等于没有必填。
+     *
+     * 两个必须守的点：
+     *  - 只校验绑了 :model 的 form。element 的 validate() 开头是
+     *    `if (!this.model) { warn; return; }`——没绑 model 就直接返回、callback 永不触发，
+     *    塞进 Promise 会永久挂起，把保存链路锁死（隔断 disabled 用的空 el-form 就是这种）。
+     *  - 各 form 都用 errorTip:false 关掉各自的提示，统一在最后只提示一次，免得弹好几条。
+     */
+    validateBill() {
+      let forms = [this.$refs.editForm].concat(this.getExtraForms());
+      let tasks = forms
+        .filter((form) => form && form.$baseValidate && form.model)
+        .map(
+          (form) =>
+            new Promise((resolve) => {
+              form.$baseValidate((valid) => resolve(!!valid), {
+                errorTip: false,
+              });
+            })
+        );
+      return Promise.all(tasks).then((results) => {
+        if (!results.every(Boolean)) {
+          this.$message({
+            message: this.$t2("必填项不能为空", "system.message.required"),
+            type: "error",
+            duration: 2000,
+          });
+          return false;
+        }
+        // 表单校验过了，再跑数据级校验（子表必填、合计、业务规则）
+        return Promise.resolve(this.validateBillData()).then((ret) => {
+          if (ret === false) return false;
+          if (typeof ret === "string" && ret) {
+            this.$message.warning(ret);
+            return false;
+          }
+          return true;
+        });
+      });
+    },
+    /**
+     * 数据级校验钩子，表单校验通过后执行。返回错误文案（或 false）即中止保存/提交。
+     * 可以返回 Promise。
+     *
+     * 子表必填**必须**在这里兜一道，不能只靠行内 <el-form-item> ——
+     * $vxeTableUtil 给表格配的是 scrollY: { gt: 20 }，子表超过 20 行就开虚拟滚动，
+     * 屏幕外的行压根没渲染、行内 form-item 不存在，外层 form 的 fields 里也就没有它们，
+     * 结果是「看着校验过了，其实漏了半张子表」。分页子表的其它页同理。
+     * 行内 form-item 留着做即时红框提示，可靠性靠这里。
+     */
+    validateBillData() {
+      return null;
+    },
+    /**
+     * 校验主表（表头）字段。附件、多选这类集合型字段的必填**必须**走这里：
+     * async-validator 的 required 不指定 type 时空数组是放行的，el-form-item 上写了也校不出来。
+     *
+     *   validateBillData() {
+     *     return (
+     *       this.checkBillRequired([
+     *         { field: "attachmentDTOs", label: "附件", type: "attachment" },
+     *         { field: "areaIds", label: "适用区域", type: "multi" },
+     *       ])
+     *       || this.checkRowsRequired({ … })
+     *     );
+     *   }
+     *
+     * @param {Array} fields [{field, label, type: "text"|"attachment"|"multi", check}]
+     * @param {Object} target 默认取 getBillModel()
+     * @returns {String|null} 错误文案，全通过返回 null
+     */
+    checkBillRequired(fields, target) {
+      return checkRequired(target || this.getBillModel(), fields, {
+        t: (str) => this.$t1(str),
+      });
+    },
+    /**
+     * 校验子表：先卡行数（默认至少 1 行），再逐行按字段清单校验。
+     * rows 传全量数据（grid.getTableData().fullData），别传当前渲染的行——
+     * 表格 scrollY gt:20 会开虚拟滚动，屏幕外的行拿不到。
+     *
+     * @param {Object} config { rows, label, minRows = 1, fields }
+     * @returns {String|null}
+     */
+    checkRowsRequired(config) {
+      return checkRows({ ...(config || {}), t: (str) => this.$t1(str) });
+    },
+    /**
+     * 除 editForm 之外还要一起校验的 form：**所有 ref 以 "extraForm" 开头的**内层 el-form。
+     *
+     * 收前缀而不是只认 ref="extraForm"，是因为一个详情页往往有好几处内层 form
+     * （放开的主表字段一处、整表放开的子表又一处），而 Vue 2 里同名的非 v-for ref
+     * 会互相覆盖、只留最后挂载的那个——那就会有 form 被漏校。
+     * 所以按需要起名 extraForm / extraFormProduct / extraFormItems…都会被收进来，
+     * v-for 出来的数组也支持。
+     */
+    getExtraForms() {
+      let refs = this.$refs || {};
+      let forms = [];
+      Object.keys(refs).forEach((key) => {
+        if (key.indexOf("extraForm") !== 0) return;
+        let val = refs[key];
+        (Array.isArray(val) ? val : [val]).forEach((form) => {
+          if (form) forms.push(form);
+        });
+      });
+      return forms;
+    },
+    // 启动流程带给流程引擎的业务参数；配对象或函数（函数每次启动时求值）
+    getWfStartParam() {
+      let param = this.billConfig.startParam;
+      if (typeof param === "function") return param.call(this) || null;
+      return param || null;
+    },
+    getBillTitle() {
+      let field = this.billConfig.titleField;
+      let model = this.getBillModel();
+      return model && field ? model[field] : null;
+    },
+    // 默认取宿主页面的 billModel（data 里的表单对象）；不叫这个名就自己覆盖 getBillTitle
+    getBillModel() {
+      return this.billModel || null;
+    },
+    /**
+     * 单据当前能不能改。字段禁用（billDisabled）和「重置/保存」的显隐（BizBillActions.canEdit）
+     * 都以它为唯一判据，不会出现「字段能改却没有保存按钮」这种错配。
+     * 默认：流程没启动就能改，启动了看当前节点给不给改。
+     * 要叠加单据状态就覆盖它（状态字段名各单据不统一，故不在 billOptions 里约定）：
+     *   canEditBill() {
+     *     if (this.hasWf) return !!(this.wfInfo && this.wfInfo.toModify);
+     *     return this.isAdd || this.billModel.status === 0;
+     *   }
+     */
+    canEditBill() {
+      if (!this.hasWf) return true;
+      return !!(this.wfInfo && this.wfInfo.toModify);
+    },
+    /**
+     * 单个字段现在能不能改。整单可改时恒为 false（不禁）；整单只读时看白名单。
+     * 配合模板上的嵌套 <el-form> 使用：
+     *   <el-form>                                     隔断整片禁用
+     *     <el-form-item prop="memo">
+     *       <el-input v-model="billModel.memo" :disabled="fieldDisabled('memo')" />
+     *     </el-form-item>
+     *   </el-form>
+     */
+    fieldDisabled(field) {
+      if (this.canEditBill()) return false;
+      return this.wfEditableFields.indexOf(field) < 0;
+    },
+    // 解析 billOptions.wfEditableFields；要按角色/自定义规则放开就覆盖它
+    getWfEditableFields() {
+      let cfg = this.billConfig.wfEditableFields;
+      if (!cfg) return [];
+      if (Array.isArray(cfg)) return cfg;
+      let step
+        = this.wfInfo && this.wfInfo.taskStep != null
+          ? String(this.wfInfo.taskStep)
+          : "";
+      return cfg[step] || cfg["*"] || [];
+    },
+    // 审批「通过」时能不能存：默认看流程给的可修改标记
+    canSaveOnAgree() {
+      return !!(this.wfInfo && this.wfInfo.toModify);
+    },
+    // 能不能启动流程：默认放开。按单据状态卡（如作废/已完结不许提交）就覆盖它，
+    // 各单据状态字段名不统一，故不在 billOptions 里约定字段。
+    canStartWf() {
+      return true;
+    },
+  },
+  beforeDestroy() {
+    this.cancelPendingReload();
+    let host = this.bizTabHost;
+    if (host && this.tab) host.unregisterDetail(this.tab, this);
+  },
+};