gubersail-platform-ui/src/components/order-form/order-form-mixin.js

/**
 * @fileoverview 订单表单混入组件
 * @description 提供订单表单的数据管理、验证规则和业务逻辑的混入组件，支持新增和编辑模式
 */

// API接口导入
import { add, update, getDetail } from '@/api/order/order'
import { getList as getOrderItemList } from '@/api/order/order-item'
import { createSalesOrder } from '@/api/order/sales-order'

// 常量和枚举导入
import {
  ORDER_TYPES,
  ORDER_STATUS,
  ORDER_TYPE_OPTIONS,
  ORDER_STATUS_OPTIONS
} from '@/constants/order'

// 本地常量定义导入
import {
  MaterialDetailDataSource
} from '@/constants/order'
import { ORDER_FORM_EVENTS, CUSTOMER_SELECT_EVENTS, ADDRESS_SELECT_EVENTS, MATERIAL_DETAIL_EVENTS } from './events'

// 数字格式化工具导入
import {
  formatAmount,
  formatFloatNumber,
  formatIntegerNumber,
  formatUnitPrice,
  formatTaxRate,
  preciseMultiply,
  preciseDivide,
  preciseRound,
  validateNumber,
  NUMBER_TYPES
} from './number-format-utils'

/**
 * 类型定义导入
 * @description 导入所有必要的TypeScript类型定义，确保类型安全
 */

/**
 * @typedef {import('./types').MaterialDetailRecord} MaterialDetailRecord
 * @description 物料明细记录类型
 */

/**
 * @typedef {import('./types').OrderFormModel} OrderFormModel
 * @description 订单表单数据模型类型
 */

/**
 * @typedef {import('./types').MaterialUpdateEventData} MaterialUpdateEventData
 * @description 物料更新事件数据类型
 */

/**
 * @typedef {import('./types').OrderFormRules} OrderFormRules
 * @description 订单表单验证规则类型
 */

/**
 * @typedef {import('./types').OrderFormMethods} OrderFormMethods
 * @description 订单表单方法类型
 */

/**
 * @typedef {import('smallwei__avue/form').AvueFormOption<OrderFormModel>} AvueFormOption
 * @typedef {import('smallwei__avue/form').AvueFormColumn<OrderFormModel>} AvueFormColumn
 * @typedef {import('smallwei__avue/form').AvueFormGroup<OrderFormModel>} AvueFormGroup
 * @typedef {import('smallwei__avue/crud').PageOption} PageOption
 */



/**
 * @typedef {import('./types').MaterialDeleteEventData} MaterialDeleteEventData
 * @description 物料删除事件数据类型
 */

/**
 * @typedef {import('./types').ApiResponse} ApiResponse
 * @description API响应数据类型
 */

/**
 * @typedef {import('./types').ValidationRule} ValidationRule
 * @description 表单验证规则类型
 */

/**
 * @typedef {import('@/api/types/order').SalesOrderCreateForm} SalesOrderCreateForm
 * @description 销售订单创建表单类型
 */

/**
 * @typedef {import('@/api/types/order').SalesOrderItemCreateForm} SalesOrderItemCreateForm
 * @description 销售订单明细创建表单类型
 */

/**
 * @typedef {import('@/constants/order').ORDER_TYPES} OrderTypeValue
 * @description 订单类型枚举值类型
 */

/**
 * @typedef {import('@/constants/order').ORDER_STATUS} OrderStatusValue
 * @description 订单状态枚举值类型
 */

/**
 * 订单表单混入组件
 * @description 提供订单表单的数据管理、验证规则和业务逻辑的混入组件
 * @mixin
 */
export default {
  /**
   * 组件响应式数据
   * @description 定义组件的响应式数据状态
   * @returns {import('./types').OrderFormMixinData} 组件数据对象
   * @this {import('./types').OrderFormMixin}
   */
  data() {
    return {
      /**
       * 订单表单数据模型
       * @description 存储订单表单的所有字段数据
       * @type {OrderFormModel}
       */
      formData: this.createInitialFormData(),

      /**
       * 保存操作加载状态
       * @description 控制保存按钮的加载状态，防止重复提交
       * @type {boolean}
       */
      saveLoading: false,

      /**
       * 表单加载状态
       * @description 控制表单整体的加载状态，用于数据获取时的UI反馈
       * @type {boolean}
       */
      formLoading: false,

      /**
       * 物料明细列表
       * @description 存储当前订单的物料明细数据，包含数据来源和删除权限标识
       * @type {MaterialDetailRecord[]}
       */
      materialDetails: [],

      /**
       * 订单类型选项列表
       * @description 订单类型下拉选择器的选项数据
       * @type {typeof ORDER_TYPE_OPTIONS}
       */
      orderTypeOptions: ORDER_TYPE_OPTIONS,

      /**
       * 订单状态选项列表
       * @description 订单状态下拉选择器的选项数据
       * @type {typeof ORDER_STATUS_OPTIONS}
       */
      orderStatusOptions: ORDER_STATUS_OPTIONS,

      // 事件常量，用于模板中的动态事件绑定
      CUSTOMER_SELECT_EVENTS,
      ADDRESS_SELECT_EVENTS,
      MATERIAL_DETAIL_EVENTS
    }
  },

  /**
   * 计算属性
   * @description 组件的响应式计算属性
   */
  computed: {
    /**
     * 订单表单验证规则
     * @description 定义订单表单各字段的验证规则，支持必填、长度、格式等验证
     * @returns {OrderFormRules} 完整的表单验证规则对象
     * @this {import('./types').OrderFormMixin}
     */
    formRules() {
      return {
        orderCode: [
          {
            required: true,
            message: '请输入订单编码',
            trigger: 'blur'
          },
          {
            min: 3,
            max: 50,
            message: '订单编码长度在 3 到 50 个字符',
            trigger: 'blur'
          }
        ],
        orgCode: [
          {
            required: true,
            message: '请输入组织编码',
            trigger: 'blur'
          },
          {
            min: 2,
            max: 20,
            message: '组织编码长度在 2 到 20 个字符',
            trigger: 'blur'
          }
        ],
        orgName: [
          {
            required: true,
            message: '请输入组织名称',
            trigger: 'blur'
          },
          {
            min: 2,
            max: 100,
            message: '组织名称长度在 2 到 100 个字符',
            trigger: 'blur'
          }
        ],
        customerCode: [
          {
            required: true,
            message: '请输入客户编码',
            trigger: 'blur'
          },
          {
            min: 3,
            max: 50,
            message: '客户编码长度在 3 到 50 个字符',
            trigger: 'blur'
          }
        ],
        customerName: [
          {
            required: true,
            message: '请输入客户名称',
            trigger: 'blur'
          },
          {
            min: 2,
            max: 100,
            message: '客户名称长度在 2 到 100 个字符',
            trigger: 'blur'
          }
        ],
        orderType: [
          {
            required: true,
            message: '请选择订单类型',
            trigger: 'change'
          }
        ],
        totalAmount: [
          {
            required: true,
            message: '请输入订单总金额',
            trigger: 'blur'
          },
          {
            type: 'number',
            min: 0.01,
            message: '订单总金额必须大于0',
            trigger: 'blur'
          }
        ],
        totalQuantity: [
          {
            required: true,
            message: '请输入订单总数量',
            trigger: 'blur'
          },
          {
            type: 'number',
            min: 0.0001,
            message: '订单总数量必须大于0',
            trigger: 'blur'
          }
        ],
        receiverName: [
          {
            required: true,
            message: '请输入收货人姓名',
            trigger: 'blur'
          },
          {
            min: 2,
            max: 50,
            message: '收货人姓名长度在 2 到 50 个字符',
            trigger: 'blur'
          }
        ],
        receiverPhone: [
          {
            required: true,
            message: '请输入收货人电话',
            trigger: 'blur'
          },
          {
            /**
             * 手机号码格式验证器
             * @description 验证手机号码格式是否正确，支持1开头的11位数字
             * @param {Object} rule - 验证规则对象
             * @param {string} value - 待验证的值
             * @param {Function} callback - 验证回调函数
             * @returns {void}
             */
            validator: (rule, value, callback) => {
              if (!value || typeof value !== 'string') {
                callback()
                return
              }

              // 手机号码正则表达式：1开头，第二位为3-9，总共11位数字
              const phoneRegex = /^1[3-9]\d{9}$/

              if (!phoneRegex.test(value.trim())) {
                callback(new Error('请输入正确的手机号码格式（1开头的11位数字）'))
              } else {
                callback()
              }
            },
            trigger: 'blur'
          }
        ],
        receiverRegion: [
          {
            required: true,
            message: '请输入收货地区',
            trigger: 'blur'
          },
          {
            min: 2,
            max: 100,
            message: '收货地区长度在 2 到 100 个字符',
            trigger: 'blur'
          }
        ],
        receiverAddress: [
          {
            required: true,
            message: '请输入收货地址',
            trigger: 'blur'
          },
          {
            min: 5,
            max: 500,
            message: '收货地址长度在 5 到 500 个字符',
            trigger: 'blur'
          }
        ],
        remark: [
          {
            max: 1000,
            message: '备注信息不能超过 1000 个字符',
            trigger: 'blur'
          }
        ]
      }
    },

    /**
     * 表单标题
     * @description 根据编辑模式动态显示表单标题
     * @returns {string} 表单标题文本
     * @this {import('./types').OrderFormMixin}
     */
    formTitle() {
      return this.isEdit ? '编辑订单' : '新增订单'
    },

    /**
     * 物料明细表格配置
     * @description 获取物料明细表格的配置选项
     * @returns {Object} 表格配置对象
     * @this {import('./types').OrderFormMixin}
     */
    materialDetailTableOption() {
      return {
        border: true,
        stripe: true,
        menuAlign: 'center',
        align: 'center',
        addBtn: false,
        editBtn: false,
        delBtn: true,
        viewBtn: false,
        column: [
          {
            label: '物料编码',
            prop: 'itemCode',
            width: 120
          },
          {
            label: '物料名称',
            prop: 'itemName',
            width: 150
          },
          {
            label: '规格型号',
            prop: 'specs',
            width: 120
          },
          {
            label: '订单数量',
            prop: 'orderQuantity',
            width: 100
          },
          {
            label: '单价',
            prop: 'unitPrice',
            width: 100
          },
          {
            label: '总金额',
            prop: 'totalAmount',
            width: 120
          }
        ]
      }
    }
  },

  /**
   * 组件方法
   * @description 组件的业务逻辑方法集合
   */
  methods: {
    /**
     * 创建初始表单数据
     * @description 创建订单表单的初始数据结构
     * @returns {OrderFormModel} 初始化的表单数据对象
     * @private
     * @this {import('./types').OrderFormMixin}
     */
    createInitialFormData() {
      return {
        id: null,
        orderCode: '',
        orgCode: '',
        orgName: '',
        customerId: null,
        customerCode: '',
        customerName: '',
        orderType: ORDER_TYPES.NORMAL,
        totalAmount: null,
        totalQuantity: null,
        addressId: '',
        receiverName: '',
        receiverPhone: '',
        receiverRegion: '',
        receiverAddress: '',
        status: ORDER_STATUS.DRAFT,
        remark: ''
      }
    },

    /**
     * 初始化表单数据
     * @description 根据编辑模式初始化表单，编辑模式加载订单详情数据，新增模式重置表单为初始状态
     * @returns {Promise<void>}
     * @throws {Error} 当初始化过程中发生错误时抛出异常
     * @public
     * @this {import('./types').OrderFormMixin}
     */
    async initForm() {
      try {
        if (this.isEdit && this.orderId) {
          // 编辑模式：加载现有订单数据
          await this.loadOrderDetail(this.orderId)
        } else {
          // 新增模式：重置表单为初始状态
          await this.resetForm()
        }
      } catch (error) {
        console.error('初始化表单失败:', error)
        const errorMessage = error.message || '初始化表单失败，请刷新页面重试'
        this.$message.error(errorMessage)
        throw error
      }
    },

    /**
     * 重置表单数据
     * @description 将表单数据重置为初始状态，清除所有验证错误信息，并重置物料明细列表
     * @returns {Promise<void>}
     * @throws {Error} 当重置过程中发生严重错误时抛出异常
     * @public
     * @this {import('./types').OrderFormMixin}
     */
    async resetForm() {
      try {
        // 重置表单数据为初始状态
        this.formData = this.createInitialFormData()

        // 重置物料明细列表（如果存在）
        if (Array.isArray(this.materialDetails)) {
          this.materialDetails = []
        }

        // 重置保存状态
        this.saveLoading = false

        // 等待DOM更新后清除表单验证
        await this.$nextTick()

        // 清除表单验证状态
        if (this.$refs.orderForm && typeof this.$refs.orderForm.clearValidate === 'function') {
          this.$refs.orderForm.clearValidate()
        }
      } catch (error) {
        console.error('重置表单失败:', error)
        // 重置表单时发生严重错误，抛出异常
        throw new Error('重置表单失败，请刷新页面重试')
      }
    },

    /**
     * 加载订单详情数据
     * @description 根据订单ID从服务器获取订单详情并填充到表单中，同时并行加载物料明细数据以提高性能
     * @param {string|number} orderId - 订单唯一标识符
     * @returns {Promise<void>}
     * @throws {Error} 当订单ID无效、API调用失败或数据格式错误时抛出异常
     * @public
     * @this {import('./types').OrderFormMixin}
     */
    async loadOrderDetail(orderId) {
      // 参数验证
      if (!orderId || (typeof orderId !== 'string' && typeof orderId !== 'number')) {
        throw new Error('订单ID不能为空且必须是有效的字符串或数字')
      }

      try {
        // 并行加载订单详情和物料明细数据以提高性能
        const [orderResponse, materialResponse] = await Promise.all([
          getDetail(orderId),
          this.loadMaterialDetails(orderId)
        ])

        // 验证订单详情响应数据
        if (!orderResponse?.data?.success) {
          const errorMsg = orderResponse?.data?.msg || '获取订单详情失败'
          throw new Error(errorMsg)
        }

        if (!orderResponse.data.data) {
          throw new Error('订单数据不存在或已被删除')
        }

        const orderData = orderResponse.data.data

        // 安全地映射订单数据到表单，确保数据类型正确
        this.formData = this.mapOrderDataToForm(orderData)

        // 设置物料明细数据（确保是数组类型）
        this.materialDetails = Array.isArray(materialResponse) ? materialResponse : []

        console.log(`成功加载订单详情，订单编码: ${orderData.orderCode || orderId}`)

      } catch (error) {
        console.error('加载订单详情失败:', error)
        const errorMessage = error.message || '加载订单详情失败，请检查网络连接后重试'
        this.$message.error(errorMessage)
        throw error
      }
    },

    /**
     * 加载物料明细数据
     * @description 根据订单ID获取物料明细列表，并对数值字段进行格式化和验证，确保数据精确性和类型安全
     * @param {string|number} orderId - 订单唯一标识符
     * @returns {Promise<MaterialDetailRecord[]>} 格式化后的物料明细数组，数值字段已进行精度处理
     * @throws {Error} 当订单ID无效或API调用失败时抛出异常
     * @private
     * @this {import('./types').OrderFormMixin}
     */
    async loadMaterialDetails(orderId) {
      // 参数验证
      if (!orderId || (typeof orderId !== 'string' && typeof orderId !== 'number')) {
        console.error('loadMaterialDetails: 订单ID无效', orderId)
        return []
      }

      try {
        const response = await getOrderItemList(1, 1000, { orderId })

        // 验证响应数据结构
        if (!response?.data?.success) {
          const errorMsg = response?.data?.msg || '获取物料明细失败'
          throw new Error(errorMsg)
        }

        if (!response.data.data) {
          console.warn('物料明细数据为空')
          return []
        }

        const materialDetails = response.data.data.records

        // 确保返回的是数组类型
        if (!Array.isArray(materialDetails)) {
          console.warn('物料明细数据格式异常，返回空数组')
          return []
        }

        // 为远程加载的物料数据添加数据来源标识并格式化数字字段
        return materialDetails.map((material, index) => {
          try {
            // 验证和格式化数字字段，确保类型安全
            const orderQuantityValidation = validateNumber(material.orderQuantity)
            const unitPriceValidation = validateNumber(material.unitPrice)
            const taxRateValidation = validateNumber(material.taxRate)
            const taxAmountValidation = validateNumber(material.taxAmount)
            const totalAmountValidation = validateNumber(material.totalAmount)

            /** @type MaterialDetailRecord */
            const detailData =  {
              ...material,
              dataSource: MaterialDetailDataSource.REMOTE,
              isDeletable: false, // 远程加载的数据不可删除
              // 格式化数字字段，确保精度和类型正确
              orderQuantity: orderQuantityValidation.isValid ? Math.round(orderQuantityValidation.value) : 0,
              unitPrice: unitPriceValidation.isValid ? preciseRound(unitPriceValidation.value, 2) : 0,
              taxRate: taxRateValidation.isValid ? preciseRound(taxRateValidation.value, 4) : 0,
              taxAmount: taxAmountValidation.isValid ? preciseRound(taxAmountValidation.value, 2) : 0,
              totalAmount: totalAmountValidation.isValid ? preciseRound(totalAmountValidation.value, 2) : 0,
              // 确保必要的字段存在
              itemCode: material.itemCode || '',
              itemName: material.itemName || '',
              specs: material.specs || '',
            }
            return detailData;
          } catch (itemError) {
            console.error(`格式化物料明细第${index + 1}项失败:`, itemError)
            // 返回默认的物料明细项，确保数据完整性
            return {
              ...material,
              dataSource: MaterialDetailDataSource.REMOTE,
              isDeletable: false,
              orderQuantity: 0,
              unitPrice: 0,
              taxRate: 0,
              taxAmount: 0,
              totalAmount: 0,
              itemCode: material.itemCode || '',
              itemName: material.itemName || '',
              specs: material.specs || material.specification || '',
              unit: material.unit || ''
            }
          }
        })
      } catch (error) {
        console.error('加载物料明细失败:', error)
        this.$message.warning('加载物料明细失败，请稍后重试')
        return []
      }
    },

    /**
     * 映射订单数据到表单格式
     * @description 将API返回的订单数据安全地映射为表单数据格式，并格式化数字字段
     * @param {import('@/api/types/order').OrderRecord} orderData - 从API获取的原始订单数据
     * @returns {OrderFormModel} 格式化后的表单数据
     * @private
     * @this {import('./types').OrderFormMixin}
     */
    mapOrderDataToForm(orderData) {
      // 验证和格式化数字字段
      const totalAmountValidation = validateNumber(orderData.totalAmount)
      const totalQuantityValidation = validateNumber(orderData.totalQuantity)
      const orderQuantityValidation = validateNumber(orderData.orderQuantity)

      return {
        id: orderData.id || null,
        orderCode: String(orderData.orderCode || ''),
        orgCode: String(orderData.orgCode || ''),
        orgName: String(orderData.orgName || ''),
        customerId: Number(orderData.customerId) || null,
        customerCode: String(orderData.customerCode || ''),
        customerName: String(orderData.customerName || ''),
        orderType: Number(orderData.orderType) || ORDER_TYPES.NORMAL,
        orderQuantity: orderQuantityValidation.isValid ? parseInt(orderQuantityValidation.value.toString()) : null,
        totalAmount: totalAmountValidation.isValid ? preciseRound(totalAmountValidation.value, 2) : null,
        totalQuantity: totalQuantityValidation.isValid ? preciseRound(totalQuantityValidation.value, 4) : null,
        addressId: String(orderData.addressId || ''),
        receiverName: String(orderData.receiverName || ''),
        receiverPhone: String(orderData.receiverPhone || ''),
        receiverRegion: String(orderData.receiverRegion || ''),
        receiverAddress: String(orderData.receiverAddress || ''),
        status: Number(orderData.status) || ORDER_STATUS.DRAFT,
        remark: String(orderData.remark || '')
      }
    },

    /**
     * 处理返回列表操作
     * @description 触发返回列表事件，通知父组件关闭表单
     * @returns {void}
     * @public
     * @emits back 返回列表事件
     * @this {import('./types').OrderFormMixin}
     */
    handleBack() {
      /**
       * 返回列表事件
       * @event back
       * @description 用户点击返回按钮时触发
       */
      this.$emit(ORDER_FORM_EVENTS.BACK)
    },

    /**
     * 处理表单保存操作
     * @description 验证表单数据并提交到服务器，支持新增和编辑模式
     * 编辑模式下先保存订单数据，再批量保存物料明细数据
     * @returns {Promise<void>}
     * @throws {Error} 当表单验证失败或API调用失败时抛出异常
     * @public
     * @emits save-success 保存成功事件
     * @this {import('./types').OrderFormMixin}
     */
    async handleSave() {
      if (this.saveLoading) {
        return // 防止重复提交
      }

      try {
        // 表单验证
        const isValid = await this.validateForm()
        if (!isValid) {
          return
        }

        this.saveLoading = true

        // 准备提交数据
        const submitData = this.prepareSubmitData()

        // 调用相应的API
        const response = await this.submitOrderData(submitData)

        // 编辑模式下，保存订单数据后再批量保存物料明细
        if (this.isEdit) {
          await this.saveMaterialDetails()
        }

        // 显示成功提示
        const successMessage = this.isEdit ? '订单更新成功' : '订单创建成功'
        this.$message.success(successMessage)

        /**
         * 保存成功事件
         * @event typeof ORDER_FORM_EVENTS.SAVE_SUCCESS
         * @param {Object} data - 保存后的订单数据
         * @description 订单保存成功后触发，携带最新的订单数据
         */
        this.$emit(ORDER_FORM_EVENTS.SAVE_SUCCESS, response.data.data)

        // 返回列表
        this.handleBack()

      } catch (error) {
        const errorMessage = this.isEdit ? '订单更新失败，请重试' : '订单创建失败，请重试'
        this.$message.error(errorMessage)
        throw error
      } finally {
        this.saveLoading = false
      }
    },

    /**
     * 提交订单数据到服务器
     * @description 根据编辑模式调用相应的API接口，新建状态下使用createSalesOrder包含物料明细
     * @param {OrderFormModel} submitData - 要提交的订单数据
     * @returns {Promise<import("@/api/types/order").SalesOrderCreateResponse>} API响应结果
     * @private
     * @this {import('./types').OrderFormMixin}
     */
    async submitOrderData(submitData) {
      if (this.isEdit) {
        return await update(submitData)
      } else {
        // 新建状态下使用createSalesOrder接口，包含物料明细数据
        const salesOrderData = this.prepareSalesOrderData(submitData)
        return await createSalesOrder(salesOrderData)
      }
    },

    /**
     * 准备销售订单创建数据
     * @description 将表单数据和物料明细数据组合为createSalesOrder接口所需的格式
     * @param {OrderFormModel} formData - 表单数据
     * @returns {SalesOrderCreateForm} 销售订单创建数据
     * @private
     * @this {import('./types').OrderFormMixin}
     */
    prepareSalesOrderData(formData) {
      // 转换物料明细数据为API所需格式
      const pcBladeOrderItemList = this.materialDetails.map(material => ({
        itemId: Number(material.itemId) || 0,
        itemCode: material.itemCode || '',
        itemName: material.itemName || '',
        specs: material.specs || material.specification || '',
        mainItemCategoryId: Number(material.mainItemCategoryId) || Number(material.mainCategoryId) || 0,
        mainItemCategoryName: material.mainItemCategoryName || material.mainCategoryName || '',
        warehouseId: Number(material.warehouseId) || 0,
        warehouseName: material.warehouseName || '',
        availableQuantity: Number(material.availableQuantity) || 0,
        orderQuantity: Number(material.orderQuantity) || 0,
        confirmQuantity: Number(material.confirmQuantity) || Number(material.orderQuantity) || 0,
        unitPrice: Number(material.unitPrice) || 0,
        taxRate: Number(material.taxRate) || 0,
        taxAmount: Number(material.taxAmount) || 0,
        totalAmount: Number(material.totalAmount) || 0,
        itemStatus: Number(material.itemStatus) || Number(material.status) || 0
      }))

      // 创建销售订单数据对象，不包含orderCode字段
      const salesOrderData = {
        ...formData,
        orgId: Number(formData.orgId) || 0,
        customerId: Number(formData.customerId) || 0,
        orderType: Number(formData.orderType) || 0,
        totalAmount: Number(formData.totalAmount) || 0,
        totalQuantity: Number(formData.totalQuantity) || 0,
        addressId: Number(formData.addressId) || 0,
        status: Number(formData.status) || 0,
        pcBladeOrderItemList
      }

      // 新增模式下，移除orderCode字段
      if (!this.isEdit && salesOrderData.orderCode) {
        delete salesOrderData.orderCode
      }

      return salesOrderData
    },

    /**
     * 验证表单数据
     * @description 使用AvueJS表单的验证功能验证所有字段
     * @returns {Promise<boolean>} 验证结果，true表示验证通过，false表示验证失败
     * @public
     * @this {import('./types').OrderFormMixin}
     */
    async validateForm() {
      if (!this.$refs.orderForm) {
        return false
      }

      try {
        // 使用更简洁的Promise包装器函数
        const isValid = await this.validateFormFields()

        if (!isValid) {
          this.$message.warning('请检查表单填写是否正确')
        }

        return isValid
      } catch (error) {
        this.$message.warning('请检查表单填写是否正确')
        return false
      }
    },

    /**
     * 验证表单字段
     * @description 验证AvueJS表单的所有字段，确保数据有效性
     * @returns {Promise<boolean>} 验证结果
     * @private
     * @this {import('./types').OrderFormMixin}
     */
    async validateFormFields() {
      return new Promise((resolve) => {
        this.$refs?.orderForm?.validate((valid) => {
          resolve(Boolean(valid))
        })
      })
    },

    /**
     * 准备提交数据
     * @description 复制表单数据并进行清理和格式化处理
     * @returns {OrderFormModel} 准备好的提交数据
     * @private
     * @this {import('./types').OrderFormMixin}
     */
    prepareSubmitData() {
      const submitData = { ...this.formData }

      // 清理和格式化数据
      return this.cleanAndFormatSubmitData(submitData)
    },

    /**
     * 清理和格式化提交数据
     * @description 移除空值字段并确保数据类型正确，使用精确的数字验证和格式化
     * @param {OrderFormModel} data - 原始表单数据
     * @returns {OrderFormModel} 清理后的数据对象
     * @private
     * @this {import('./types').OrderFormMixin}
     */
    cleanAndFormatSubmitData(data) {
      const cleanedData = {}

      Object.keys(data).forEach(key => {
        const value = data[key]

        // 新增模式下，移除orderCode字段
        if (!this.isEdit && key === 'orderCode') {
          return
        }

        // 跳过null、undefined和空字符串，但保留备注字段
        if (value === null || value === undefined || (value === '' && key !== 'remark')) {
          return
        }

        // 使用精确的数字验证和格式化
        if (key === 'totalAmount') {
          const validation = validateNumber(value)
          cleanedData[key] = validation.isValid ? preciseRound(validation.value, 2) : 0
        } else if (key === 'totalQuantity') {
          const validation = validateNumber(value)
          cleanedData[key] = validation.isValid ? Math.round(validation.value) : 0
        } else if (['orderType', 'status'].includes(key)) {
          cleanedData[key] = Number(value) || 0
        } else {
          cleanedData[key] = value
        }
      })

      return cleanedData
    },

    /**
     * 批量保存物料明细数据
     * @description 编辑模式下，只保存通过导入获取的物料数据，使用新增接口
     * @returns {Promise<void>}
     * @throws {Error} 当物料明细保存失败时抛出异常
     * @private
     * @this {import('./types').OrderFormMixin}
     */
    async saveMaterialDetails() {
      if (!this.materialDetails || this.materialDetails.length === 0) {
        return
      }

      // 过滤出通过导入获取的物料数据
      const importedMaterials = this.materialDetails.filter(material =>
        material.dataSource === MaterialDetailDataSource.IMPORTED
      )

      if (importedMaterials.length === 0) {
        return
      }

      const { add: addOrderItem } = await import('@/api/order/order-item')
      const savePromises = []
      const failedItems = []

      // 准备所有导入物料明细的保存请求
      for (let i = 0; i < importedMaterials.length; i++) {
        const material = importedMaterials[i]
        const materialData = this.prepareMaterialItemData(material)

        const savePromise = addOrderItem(materialData)
          .catch(error => {
            failedItems.push({ index: i + 1, itemCode: material.itemCode, error })
            return null
          })

        savePromises.push(savePromise)
      }

      // 等待所有保存操作完成
      await Promise.all(savePromises)

      // 检查是否有失败的项目
      if (failedItems.length > 0) {
        const errorMessage = `导入物料明细保存失败：${failedItems.map(item => `第${item.index}条(${item.itemCode})`).join('、')}`
        throw new Error(errorMessage)
      }
    },

    /**
     * 准备物料明细数据
     * @description 将物料明细数据转换为API接口所需的格式，用于新增物料明细
     * @param {MaterialDetailRecord} material - 物料明细数据
     * @returns {SalesOrderItemCreateForm} 格式化后的物料明细数据
     * @private
     * @this {import('./types').OrderFormMixin}
     */
    prepareMaterialItemData(material) {
      return {
        orderId: this.formData.id,
        orderCode: this.formData.orderCode || '',
        itemId: Number(material.itemId) || 0,
        itemCode: material.itemCode || '',
        itemName: material.itemName || '',
        specs: material.specs || material.specification || '',
        mainItemCategoryId: Number(material.mainItemCategoryId) || Number(material.mainCategoryId) || 0,
        mainItemCategoryName: material.mainItemCategoryName || material.mainCategoryName || '',
        warehouseId: Number(material.warehouseId) || 0,
        warehouseName: material.warehouseName || '',
        availableQuantity: Number(material.availableQuantity) || 0,
        orderQuantity: Number(material.orderQuantity) || 0,
        confirmQuantity: Number(material.confirmQuantity) || Number(material.orderQuantity) || 0,
        unitPrice: Number(material.unitPrice) || 0,
        taxRate: Number(material.taxRate) || 0,
        taxAmount: Number(material.taxAmount) || 0,
        totalAmount: Number(material.totalAmount) || 0,
        itemStatus: Number(material.itemStatus) || Number(material.status) || 0
      }
    },

    /**
     * 处理物料删除事件
     * @description 从物料明细列表中删除指定的物料记录，仅允许删除可删除的物料
     * @param {MaterialDeleteEventData} deleteData - 删除数据对象
     * @param {MaterialDetailRecord} deleteData.row - 要删除的物料记录
     * @param {number} deleteData.index - 记录在当前页的索引
     * @returns {void}
     * @public
     * @this {import('./types').OrderFormMixin}
     */
    handleMaterialDelete({ row, index }) {
       if (!row) {
         this.$message.warning('删除数据无效')
         return
       }

       // 检查物料是否可删除
       if (!row.isDeletable) {
         this.$message.warning('该物料不允许删除')
         return
       }

       try {
         // 从物料明细列表中移除该记录
         const materialIndex = this.materialDetails.findIndex(item =>
           item.itemCode === row.itemCode &&
           item.dataSource === row.dataSource
         )

         if (materialIndex !== -1) {
           this.materialDetails.splice(materialIndex, 1)
           this.$message.success(`物料 "${row.itemName}" 删除成功`)
         } else {
           this.$message.warning('未找到要删除的物料记录')
         }
       } catch (error) {
         this.$message.error('删除物料失败，请重试')
         console.error('删除物料失败:', error)
       }
     },

    /**
     * 处理物料导入事件
     * @description 将导入的物料数据添加到物料明细列表中，格式化数字字段并标记为可删除
     * @param {MaterialDetailRecord[]} importedMaterials - 导入的物料数据数组
     * @returns {void}
     * @public
     * @this {import('./types').OrderFormMixin}
     */
    handleMaterialImport(importedMaterials) {
      if (!Array.isArray(importedMaterials) || importedMaterials.length === 0) {
        this.$message.warning('没有有效的物料数据可导入')
        return
      }

      try {
        // 为导入的物料添加数据来源标识并格式化数字字段
        const formattedMaterials = importedMaterials.map(material => {
          const formatted = {
            ...material,
            dataSource: MaterialDetailDataSource.IMPORTED,
            isDeletable: true
          }

          // 格式化数字字段
          const quantityValidation = validateNumber(formatted.orderQuantity)
          const priceValidation = validateNumber(formatted.unitPrice)
          const rateValidation = validateNumber(formatted.taxRate)
          const amountValidation = validateNumber(formatted.totalAmount)
          const taxAmountValidation = validateNumber(formatted.taxAmount)

          formatted.orderQuantity = quantityValidation.isValid ? Math.round(quantityValidation.value) : 1
          formatted.unitPrice = priceValidation.isValid ? preciseRound(priceValidation.value, 2) : 0
          formatted.taxRate = rateValidation.isValid ? preciseRound(rateValidation.value, 4) : 0
          formatted.taxAmount = taxAmountValidation.isValid ? preciseRound(taxAmountValidation.value, 2) : 0
          formatted.totalAmount = amountValidation.isValid ? preciseRound(amountValidation.value, 2) : 0

          return formatted
        })

        // 添加到物料明细列表
        this.materialDetails.push(...formattedMaterials)

        this.$message.success(`成功导入 ${importedMaterials.length} 条物料明细`)
      } catch (error) {
        this.$message.error('导入物料失败，请重试')
        console.error('导入物料失败:', error)
      }
    },

    /**
     * 处理表单提交事件
     * @description AvueJS表单提交时的回调处理
     * @param {OrderFormModel} formData - 表单数据
     * @param {Function} done - 完成回调函数
     * @this {import('./types').OrderFormMixin}
     */
    handleFormSubmit(formData, done) {
      this.handleSave().finally(() => {
        if (typeof done === 'function') {
          done()
        }
      })
    },

    /**
     * 处理表单重置事件
     * @description AvueJS表单重置时的回调处理
     * @this {import('./types').OrderFormMixin}
     */
    handleFormReset() {
      this.resetForm()
    },

    /**
     * 处理物料明细数据变化
     * @description 当物料明细表格数据发生变化时的回调处理，自动重新计算订单总金额和总数量
     * @param {MaterialDetailRecord[]} materialDetails - 更新后的物料明细列表
     * @returns {void}
     * @this {import('./types').OrderFormMixin}
     */
    handleMaterialChange(materialDetails) {
      this.materialDetails = materialDetails
      // 可以在这里添加其他业务逻辑，如计算订单总金额等
      this.calculateOrderTotal()
    },

    /**
     * 处理物料明细更新事件
     * @description 当物料明细表格中的数据被编辑时的回调处理，自动重新计算订单总金额和总数量
     * @param {MaterialUpdateEventData} updateData - 更新数据对象
     * @returns {void}
     * @this {import('./types').OrderFormMixin}
     */
    handleMaterialUpdate({ row, index }) {
      // 如果有有效的索引，更新物料明细列表中对应的记录
      if (index >= 0 && index < this.materialDetails.length) {
        this.$set(this.materialDetails, index, { ...row })
      }

      // 无论索引是否有效，都重新计算订单总金额
      this.calculateOrderTotal()
    },

    /**
     * 计算订单总金额和总数量
     * @description 根据物料明细计算订单总金额、总数量、总税额并更新表单数据
     * @returns {void}
     * @this {import('./types').OrderFormMixin}
     */
    calculateOrderTotal() {
      // 计算订单总金额
      const totalAmount = this.materialDetails.reduce((sum, item) => {
        return sum + (Number(item.totalAmount) || 0)
      }, 0)

      // 计算订单总数量
      const totalQuantity = this.materialDetails.reduce((sum, item) => {
        return sum + (Number(item.orderQuantity) || 0)
      }, 0)

      // 计算总税额
      const totalTaxAmount = this.materialDetails.reduce((sum, item) => {
        return sum + (Number(item.taxAmount) || 0)
      }, 0)

      // 更新表单中的总金额、总数量和税额字段
      if (this.formData) {
        this.$set(this.formData, 'totalAmount', Math.round(totalAmount * 100) / 100)
        this.$set(this.formData, 'totalQuantity', Math.round(totalQuantity))
        this.$set(this.formData, 'totalTaxAmount', Math.round(totalTaxAmount * 100) / 100)
      }
    },

    /**
     * 处理客户选择事件
     * @description 当客户选择组件选择客户时的回调处理，自动填充客户编码和客户名称，并清空地址相关字段
     * @param {Object} customerData - 客户数据对象
     * @param {string|number} customerData.customerId - 客户ID
     * @param {string} customerData.customerCode - 客户编码
     * @param {string} customerData.customerName - 客户名称
     * @returns {void}
     * @this {import('./types').OrderFormMixin}
     */
    handleCustomerSelected(customerData) {
      if (this.formData) {
        // 更新客户相关字段
        this.$set(this.formData, 'customerId', customerData.customerId)
        this.$set(this.formData, 'customerCode', customerData.customerCode)
        this.$set(this.formData, 'customerName', customerData.customerName)

        // 清空地址相关字段
        this.$set(this.formData, 'addressId', '')
        this.$set(this.formData, 'receiverName', '')
        this.$set(this.formData, 'receiverPhone', '')
        this.$set(this.formData, 'receiverRegion', '')
        this.$set(this.formData, 'receiverAddress', '')
      }
    },

    /**
     * 处理地址选择事件
     * @description 当地址选择组件选择地址时的回调处理，自动填充收货人相关信息
     * @param {Object} addressData - 地址数据对象
     * @param {string|number} addressData.addressId - 地址ID
     * @param {string} addressData.receiverName - 收货人姓名
     * @param {string} addressData.receiverPhone - 收货人电话
     * @param {string} addressData.regionCode - 地区编码
     * @param {string} addressData.regionName - 地区名称
     * @param {string} addressData.detailAddress - 详细地址
     * @param {string} addressData.postalCode - 邮政编码
     * @returns {void}
     * @this {import('./types').OrderFormMixin}
     */
    handleAddressSelected(addressData) {
      if (this.formData) {
        // 更新地址相关字段
        this.$set(this.formData, 'addressId', addressData.addressId)
        this.$set(this.formData, 'receiverName', addressData.receiverName || '')
        this.$set(this.formData, 'receiverPhone', addressData.receiverPhone || '')
        this.$set(this.formData, 'receiverRegion', addressData.regionName || '')
        this.$set(this.formData, 'receiverAddress', addressData.detailAddress || '')
      }
    },

    /**
     * 处理地址回显
     * @description 在编辑模式下，根据表单中的地址信息在地址选择组件中进行回显
     * @returns {void}
     * @this {import('./types').OrderFormMixin}
     */
    handleAddressEcho() {
      // 查找地址选择组件的引用
      const addressSelectRefs = this.$refs.orderForm?.$refs?.addressId
      const addressSelectComponent = Array.isArray(addressSelectRefs) ? addressSelectRefs[0] : addressSelectRefs

      if (addressSelectComponent && typeof addressSelectComponent.setEchoValue === 'function') {
        // 构建地址信息对象用于匹配
        const addressInfo = {
          receiverName: this.formData.receiverName,
          receiverPhone: this.formData.receiverPhone,
          regionName: this.formData.receiverRegion,
          detailAddress: this.formData.receiverAddress
        }

        // 调用地址选择组件的回显方法
        addressSelectComponent.setEchoValue(addressInfo)
      }
    }
  }
}