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, updateOrder } from '@/api/order/sales-order'
import { getCustomerInfo } from '@/api/common/index'
import { getList as getAddressList } from '@/api/order/address'

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

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

// 数字格式化工具导入
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} AvueFormOption
 * @typedef {import('smallwei__avue/form').AvueFormColumn} AvueFormColumn
 * @typedef {import('smallwei__avue/form').AvueFormGroup} 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').OrderFormMixinComponent}
   */
  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').OrderFormMixinComponent}
     */
    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 {AvueFormOption} 表单配置对象
     * @this {import('./types').OrderFormMixin}
     */
    formOption() {
      return getFormOption(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').OrderFormMixinComponent}
   */
  createInitialFormData() {
      return {
        id: undefined,
        orderCode: '',
        orgId: undefined,
        orgCode: '',
        orgName: '',
        customerId: null,
        customerCode: '',
        customerName: '',
        orderType: ORDER_TYPES.NORMAL,
        orderQuantity: 0,
        totalAmount: null,
        totalQuantity: null,
        addressId: null,
        receiverName: '',
        receiverPhone: '',
        receiverRegion: '',
        receiverAddress: '',
        status: ORDER_STATUS.DRAFT,
        remark: ''
      }
    },

    /**
     * 初始化表单数据
     * @description 根据编辑模式初始化表单，编辑模式加载订单详情数据，新增模式重置表单为初始状态
     * @returns {Promise<void>}
     * @throws {Error} 当初始化过程中发生错误时抛出异常
     * @public
     * @this {import('./types').OrderFormMixinComponent}
   */
  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').OrderFormMixinComponent}
   */
  async resetForm() {
      try {
        // 重置表单数据为初始状态
        this.formData = this.createInitialFormData()

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

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

        // 在新增模式下，调用getCustomerInfo接口获取客户信息
        if (!this.isEdit) {
          await this.loadCustomerInfo()
        }

        // 等待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 在新增模式下调用getCustomerInfo接口获取客户信息并填充表单
     * @returns {Promise<void>}
     * @throws {Error} 当API调用失败时抛出异常
     * @private
     * @this {import('./types').OrderFormMixinComponent}
     */
    async loadCustomerInfo() {
      try {
        this.formLoading = true

        const response = await getCustomerInfo()

        if (response?.data?.success && response.data.data) {
          const customerData = response.data.data

          // 填充客户相关字段到表单（根据实际API返回的字段名称）
          this.$set(this.formData, 'orgId', customerData.ORG_ID)
          this.$set(this.formData, 'orgCode', customerData.ORG_CODE || '')
          this.$set(this.formData, 'orgName', customerData.ORG_NAME || '')
          this.$set(this.formData, 'customerId', customerData.Customer_ID)
          this.$set(this.formData, 'customerCode', customerData.Customer_CODE || '')
          this.$set(this.formData, 'customerName', customerData.Customer_NAME || '')

          // 根据Customer_CODE加载地址信息
          if (customerData.Customer_CODE) {
            await this.loadCustomerAddresses(customerData.Customer_CODE)
          }
        } else {
          const errorMsg = response?.data?.msg || '获取客户信息失败'
          console.warn('获取客户信息失败:', errorMsg)
          this.$message.warning('获取客户信息失败，请手动填写相关信息')
        }
      } catch (error) {
        console.error('加载客户信息API调用失败:', error)
        this.$message.error('网络错误，获取客户信息失败')
        throw error
      } finally {
        this.formLoading = false
      }
    },

    /**
     * 加载客户地址信息
     * @description 根据客户ID获取地址列表，如果只有一个地址则直接选中，如果多个则选中默认地址
     * @param {string} customerCode - 客户ID
     * @returns {Promise<void>}
     * @throws {Error} 当API调用失败时抛出异常
     * @private
     * @this {import('./types').OrderFormMixinComponent}
     */
    async loadCustomerAddresses(customerCode) {
      try {
        // 使用getList方法，传递分页参数和查询条件
        const response = await getAddressList(1, 100, { customerCode })

        if (response?.data?.success && response.data.data?.records) {
          const addresses = response.data.data.records

          if (addresses.length === 1) {
            // 只有一个地址，直接选中
            this.selectAddress(addresses[0])
          } else if (addresses.length > 1) {
            // 多个地址，选中默认地址
            const defaultAddress = addresses.find(addr => addr.isDefault === 1)
            if (defaultAddress) {
              this.selectAddress(defaultAddress)
            }
          }
        } else {
          console.warn('获取客户地址失败:', response?.data?.msg || '未知错误')
        }
      } catch (error) {
        console.error('加载客户地址API调用失败:', error)
        // 地址加载失败不影响主流程，只记录错误
      }
    },

    /**
     * 选择地址
     * @description 将选中的地址信息填充到表单中
     * @param {import('@/api/types/address').CustomerAddressRecord} address - 地址对象
     * @returns {void}
     * @private
     * @this {import('./types').OrderFormMixinComponent}
     */
    selectAddress(address) {
      if (address && this.formData) {
        this.$set(this.formData, 'addressId', address.id.toString())
        this.$set(this.formData, 'receiverName', address.receiverName || '')
        this.$set(this.formData, 'receiverPhone', address.receiverPhone || '')
        this.$set(this.formData, 'receiverRegion', address.regionName || '')
        this.$set(this.formData, 'receiverAddress', address.detailAddress || '')
      }
    },

    /**
     * 加载订单详情数据
     * @description 根据订单ID从服务器获取订单详情并填充到表单中，同时并行加载物料明细数据以提高性能
     * @param {string|number} orderId - 订单唯一标识符
     * @returns {Promise<void>}
     * @throws {Error} 当订单ID无效、API调用失败或数据格式错误时抛出异常
     * @public
     * @this {import('./types').OrderFormMixinComponent}
   */
  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').OrderFormMixinComponent}
   */
  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)
            const availableQuantityValidation = validateNumber(material.availableQuantity)
            const confirmQuantityValidation = validateNumber(material.confirmQuantity)

            const detailData =  {
              ...material,
              id: String(material.id || ''),
              itemId: String(material.itemId || ''),
              warehouseId: String(material.warehouseId || ''),
              mainCategoryId: String(material.mainItemCategoryId) || '',
              mainItemCategoryId: material.mainItemCategoryId ? String(material.mainItemCategoryId) : undefined,
              mainItemCategoryName: material.mainItemCategoryName || material.mainCategoryName || '',
              mainCategoryName: material.mainItemCategoryName || material.mainCategoryName || '',
              createTime: material.createTime || new Date().toISOString(),
              updateTime: material.updateTime || new Date().toISOString(),
              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,
              availableQuantity: availableQuantityValidation.isValid ? preciseRound(availableQuantityValidation.value, 0) : 0,
              confirmQuantity: confirmQuantityValidation.isValid ? preciseRound(confirmQuantityValidation.value, 0) : 0,
              // 确保必要的字段存在
              itemCode: material.itemCode || '',
              itemName: material.itemName || '',
              specs: material.specs || ''
            }
            return detailData;
          } catch (itemError) {
            console.error(`格式化物料明细第${index + 1}项失败:`, itemError)
            // 返回默认的物料明细项，确保数据完整性
            return {
              ...material,
              id: String(material.id || ''),
              mainItemCategoryId: String(material.mainItemCategoryId || ''),
              mainItemCategoryName: material.mainItemCategoryName || material.mainCategoryName || '',
              mainCategoryName: material.mainItemCategoryName || material.mainCategoryName || '',
              itemId: String(material.itemId || ''),
              warehouseId: String(material.warehouseId || ''),
              createTime: material.createTime || new Date().toISOString(),
              updateTime: material.updateTime || new Date().toISOString(),
              dataSource: MaterialDetailDataSource.REMOTE,
              isDeletable: false,
              availableQuantity: 0,
              confirmQuantity: 0,
              orderQuantity: 0,
              unitPrice: 0,
              taxRate: 0,
              taxAmount: 0,
              totalAmount: 0,
              itemCode: material.itemCode || '',
              itemName: material.itemName || '',
              specs: material.specs || ''
            }
          }
        })
      } 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').OrderFormMixinComponent}
   */
  mapOrderDataToForm(orderData) {
      // 验证和格式化数字字段
      const totalAmountValidation = validateNumber(orderData.totalAmount)
      const totalQuantityValidation = validateNumber(orderData.totalQuantity)
      const orderQuantityValidation = validateNumber(orderData.orderQuantity)

      return {
        id: orderData.id ? String(orderData.id) : undefined,
        orderCode: String(orderData.orderCode || ''),
        orgId: orderData.orgId ? Number(orderData.orgId) : undefined,
        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()) : 0,
        totalAmount: totalAmountValidation.isValid ? preciseRound(totalAmountValidation.value, 2) : null,
        totalQuantity: totalQuantityValidation.isValid ? preciseRound(totalQuantityValidation.value, 4) : null,
        addressId: orderData.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').OrderFormMixinComponent}
   */
  handleBack() {
      /**
       * 返回列表事件
       * @event back
       * @description 用户点击返回按钮时触发
       */
      this.$emit(ORDER_FORM_EVENTS.BACK)
    },

    /**
     * 处理表单保存操作
     * @description 验证表单数据并提交到服务器，支持新增和编辑模式
     * 编辑模式下使用updateOrder方法一次性保存订单和物料明细数据
     * @returns {Promise<void>}
     * @throws {Error} 当表单验证失败或API调用失败时抛出异常
     * @public
     * @emits save-success 保存成功事件
     * @this {import('./types').OrderFormMixinComponent}
   */
  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)

        // 显示成功提示
        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接口，编辑模式下使用updateOrder包含物料明细，新建状态下使用createSalesOrder包含物料明细
     * @param {OrderFormModel} submitData - 要提交的订单数据
     * @returns {Promise<import("@/api/types/order").SalesOrderCreateResponse>} API响应结果
     * @private
     * @this {import('./types').OrderFormMixinComponent}
   */
  async submitOrderData(submitData) {
      if (this.isEdit) {
        // 编辑状态下使用updateOrder接口，包含物料明细数据
        const salesOrderData = this.prepareSalesOrderUpdateData(submitData)
        return await updateOrder(salesOrderData)
      } else {
        // 新建状态下使用createSalesOrder接口，包含物料明细数据
        const salesOrderData = this.prepareSalesOrderData(submitData)
        return await createSalesOrder(salesOrderData)
      }
    },

    /**
     * 准备销售订单创建数据
     * @description 将表单数据和物料明细数据组合为createSalesOrder接口所需的格式
     * @param {OrderFormModel} formData - 表单数据
     * @returns {SalesOrderCreateForm} 销售订单创建数据
     * @private
     * @this {import('./types').OrderFormMixinComponent}
     */
    prepareSalesOrderData(formData) {
      // 转换物料明细数据为API所需格式
      const pcBladeOrderItemList = this.materialDetails.map(material => ({
        itemId: Number(material.itemId) || 0,
        itemCode: material.itemCode || '',
        itemName: material.itemName || '',
        specs: material.specs || '',
        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: material.itemStatus || ORDER_ITEM_STATUS.UNCONFIRMED,
      }))

      // 创建销售订单数据对象
      const salesOrderData = {
        ...formData,
        id: formData.id ? Number(formData.id) : 0,
        orgId: formData.orgId ? Number(formData.orgId) : 0,
        customerId: formData.customerId ? Number(formData.customerId) : 0,
        orderType: Number(formData.orderType) || 0,
        totalAmount: Number(formData.totalAmount) || 0,
        totalQuantity: Number(formData.totalQuantity) || 0,
        addressId: formData.addressId ? String(formData.addressId) : '',
        status: formData.status,
        pcBladeOrderItemList
      }

      // 新增模式下，移除orderCode和id字段
      if (!this.isEdit) {
        const { orderCode, id, ...dataWithoutOrderCodeAndId } = salesOrderData
        return dataWithoutOrderCodeAndId
      }

      return salesOrderData
    },

    /**
     * 准备销售订单更新数据
     * @description 将表单数据和物料明细数据组合为updateOrder接口所需的格式
     * @param {OrderFormModel} formData - 表单数据
     * @returns {import('@/api/types/order').SalesOrderUpdateForm} 销售订单更新数据
     * @private
     * @this {import('./types').OrderFormMixinComponent}
     */
    prepareSalesOrderUpdateData(formData) {
      // 转换所有物料明细数据为API所需格式
      const pcBladeOrderItemList = this.materialDetails.map(material => ({
        id: material.id ? material.id : undefined, // 保持为字符串类型
        orderId: formData.id || '', // 保持为字符串类型，避免大整数精度丢失
        itemId: Number(material.itemId) || 0,
        itemCode: material.itemCode || '',
        itemName: material.itemName || '',
        specs: material.specs || '',
        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: material.itemStatus || ORDER_ITEM_STATUS.UNCONFIRMED,
      }))

      // 创建销售订单更新数据对象
      const salesOrderUpdateData = {
        id: formData.id, // 保持为字符串类型，避免大整数精度丢失
        orderCode: formData.orderCode || '',
        orgId: formData.orgId ? Number(formData.orgId) : 0,
        orgCode: formData.orgCode || '',
        orgName: formData.orgName || '',
        customerId: Number(formData.customerId) || 0,
        customerCode: formData.customerCode || '',
        customerName: formData.customerName || '',
        orderType: Number(formData.orderType) || 0,
        orderQuantity: Number(formData.orderQuantity) || 0,
        totalAmount: Number(formData.totalAmount) || 0,
        totalQuantity: Number(formData.totalQuantity) || 0,
        addressId: Number(formData.addressId) || 0,
        receiverName: formData.receiverName || '',
        receiverPhone: formData.receiverPhone || '',
        receiverRegion: formData.receiverRegion || '',
        receiverAddress: formData.receiverAddress || '',
        status: formData.status,
        remark: formData.remark || '',
        pcBladeOrderItemList
      }

      return salesOrderUpdateData
    },

    /**
     * 验证表单数据
     * @description 使用AvueJS表单的验证功能验证所有字段
     * @returns {Promise<boolean>} 验证结果，true表示验证通过，false表示验证失败
     * @public
     * @this {import('./types').OrderFormMixinComponent}
     */
    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').OrderFormMixinComponent}
     */
    async validateFormFields() {
      return new Promise((resolve) => {
        this.$refs?.orderForm?.validate(/** @param {boolean} valid */ (valid) => {
          resolve(Boolean(valid))
        })
      })
    },

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

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

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

      Object.keys(data).forEach(key => {
        const value = /** @type {Record<string, any>} */(data)[key]

        // 新增模式下，移除orderCode和id字段
        if (!this.isEdit && (key === 'orderCode' || key === 'id')) {
          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 if (key === 'id' && this.isEdit) {
          // 编辑模式下保持id字段为字符串类型，避免大整数精度丢失
          cleanedData[key] = String(value)
        } else if (key === 'addressId') {
          // 地址ID保持为字符串类型，确保与地址选择组件的类型一致
          cleanedData[key] = String(value)
        } else {
          cleanedData[key] = value
        }
      })

      return /** @type {any} */ (cleanedData)
    },



    /**
     * 处理物料删除事件
     * @description 从物料明细列表中删除指定的物料记录，仅允许删除可删除的物料
     * @param {import('./types').MaterialDetailRecord} row - 要删除的物料记录
     * @returns {void}
     * @public
     * @this {import('./types').OrderFormMixinComponent}
     */
    handleMaterialDelete(/** @type {{ row: import('./types').MaterialDetailRecord, index: number }} */ { 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').OrderFormMixinComponent}
     */
    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 && rateValidation.value > 0 ? preciseRound(rateValidation.value, 4) : 13
          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').OrderFormMixinComponent}
     */
    handleFormSubmit(/** @type {import('./types').OrderFormModel} */ formData, /** @type {Function} */ done) {
      this.handleSave().finally(() => {
        if (typeof done === 'function') {
          done()
        }
      })
    },

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

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

    /**
     * 处理物料明细更新事件
     * @description 当物料明细表格中的数据被编辑时的回调处理，自动重新计算订单总金额和总数量
     * @param {import('./types').MaterialUpdateEventData} eventData - 更新事件数据对象
     * @returns {void}
     * @this {import('./types').OrderFormMixinComponent}
     */
    handleMaterialUpdate(eventData) {
       if (!eventData || typeof eventData !== 'object') {
         console.warn('Invalid material update event data:', eventData)
         return
       }

       const { index, row } = eventData
       if (typeof index !== 'number' || index < 0) {
         console.warn('Invalid material update index:', index)
         return
       }

       if (!row || typeof row !== 'object') {
         console.warn('Invalid material update data:', row)
         return
       }

       // 验证索引是否在有效范围内
       if (index >= this.materialDetails.length) {
         console.warn('Material update index out of range:', index, 'length:', this.materialDetails.length)
         return
       }

       // 更新物料明细数据
       this.$set(this.materialDetails, index, {
         ...this.materialDetails[index],
         ...row,
         updateTime: new Date().toISOString()
       })

       // 重新计算订单总计
       this.calculateOrderTotal()
     },

    /**
     * 计算订单总金额和总数量
     * @description 根据物料明细计算订单总金额、总数量、总税额并更新表单数据
     * @returns {void}
     * @this {import('./types').OrderFormMixinComponent}
     */
    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 {import('./types').CustomerSelectData} customerData - 客户数据对象
     * @returns {void}
     * @this {import('./types').OrderFormMixinComponent}
     */
    handleCustomerSelected(/** @type {import('./types').CustomerSelectData} */ 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 {import('./types').AddressSelectData} addressData - 地址数据对象
     * @returns {void}
     * @this {import('./types').OrderFormMixinComponent}
     */
    handleAddressSelected(/** @type {import('./types').AddressSelectData} */ 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').OrderFormMixinComponent}
     */
    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)
      }
    }
  }
}