feat(forecast-form): 添加类型定义并统一表单事件常量

src/components/forecast-form/forecast-form-mixin.js

@@ -3,6 +3,56 @@
  * @description 提供销售预测表单的数据管理、验证规则和业务逻辑的混入组件，支持新增和编辑模式
  */
 
+/**
+ * 类型定义导入
+ * @description 导入所有必要的TypeScript类型定义，确保类型安全
+ */
+
+/**
+ * @typedef {import('./types').ForecastFormModel} ForecastFormModel
+ * @description 销售预测表单数据模型类型
+ */
+
+/**
+ * @typedef {import('./types').ForecastFormMixinData} ForecastFormMixinData
+ * @description 销售预测表单混入数据类型
+ */
+
+/**
+ * @typedef {import('./types').CustomerOption} CustomerOption
+ * @description 客户选项类型
+ */
+
+/**
+ * @typedef {import('./types').ItemOption} ItemOption
+ * @description 物料选项类型
+ */
+
+/**
+ * @typedef {import('./types').ApprovalStatusOption} ApprovalStatusOption
+ * @description 审批状态选项类型
+ */
+
+/**
+ * @typedef {import('./types').MaterialSelectData} MaterialSelectData
+ * @description 物料选择数据类型
+ */
+
+/**
+ * @typedef {import('./types').CustomerSelectData} CustomerSelectData
+ * @description 客户选择数据类型
+ */
+
+/**
+ * @typedef {import('./types').ApiResponse} ApiResponse
+ * @description API响应数据类型
+ */
+
+/**
+ * @typedef {import('./types').ValidationRule} ValidationRule
+ * @description 表单验证规则类型
+ */
+
 // API接口导入
 import { addForecast, updateForecast, getForecastDetail } from '@/api/forecast'
 
@@ -37,12 +87,19 @@ export const FORECAST_FORM_EVENTS = {
   /** 客户选择变更事件 */
   CUSTOMER_CHANGE: 'customer-change',
   /** 物料选择变更事件 */
-  ITEM_CHANGE: 'item-change'
+  ITEM_CHANGE: 'item-change',
+  /** 表单重置事件 */
+  RESET: 'reset',
+  /** 表单提交事件 */
+  SUBMIT: 'submit',
+  /** 更新可见性事件 */
+  UPDATE_VISIBLE: 'update:visible'
 }
 
 /**
  * 销售预测表单混入
  * @description 提供销售预测表单的数据管理、验证规则和业务逻辑
+ * @mixin
  */
 export default {
   /**
@@ -111,13 +168,14 @@ export default {
   /**
    * 组件响应式数据
    * @description 定义组件的响应式数据状态
+   * @returns {ForecastFormMixinData} 组件数据对象
    */
   data() {
     return {
       /**
        * 销售预测表单数据模型
        * @description 存储销售预测表单的所有字段数据
-       * @type {Object}
+       * @type {ForecastFormModel}
        */
       formData: this.createInitialFormData(),
 
@@ -138,7 +196,7 @@ export default {
       /**
        * 客户选项列表
        * @description 客户下拉选择器的选项数据
-       * @type {Array<{value: string|number, label: string, customerCode: string}>}
+       * @type {CustomerOption[]}
        */
       customerOptions: [],
 
@@ -152,7 +210,7 @@ export default {
       /**
        * 物料选项列表
        * @description 物料下拉选择器的选项数据
-       * @type {Array<{value: string|number, label: string, itemCode: string, specs: string}>}
+       * @type {ItemOption[]}
        */
       itemOptions: [],
 
@@ -166,7 +224,7 @@ export default {
       /**
        * 审批状态选项列表
        * @description 审批状态下拉选择器的选项数据
-       * @type {typeof APPROVAL_STATUS_OPTIONS}
+       * @type {ApprovalStatusOption[]}
        */
       approvalStatusOptions: APPROVAL_STATUS_OPTIONS,
 
@@ -312,7 +370,7 @@ export default {
     /**
      * 创建初始表单数据
      * @description 创建销售预测表单的初始数据结构
-     * @returns {Object} 初始化的表单数据对象
+     * @returns {ForecastFormModel} 初始化的表单数据对象
      * @private
      */
     createInitialFormData() {
@@ -322,8 +380,8 @@ export default {
     /**
      * 清理和格式化表单数据
      * @description 对表单数据进行清理和格式化处理
-     * @param {Object} data - 原始表单数据
-     * @returns {Object} 清理和格式化后的表单数据
+     * @param {any} data - 原始表单数据
+     * @returns {ForecastFormModel} 清理和格式化后的表单数据
      * @private
      */
     cleanAndFormatFormData(data) {
@@ -641,6 +699,7 @@ export default {
 
     /**
      * 客户选择事件处理
+     * @param {CustomerSelectData} customerData - 客户选择数据
      */
     handleCustomerSelected(customerData) {
       if (customerData && customerData.customerId) {
@@ -671,12 +730,7 @@ export default {
     /**
      * 物料选择处理
      * @description 处理MaterialSelect组件的物料选择事件
-     * @param {Object} materialData - 物料选择数据
-     * @param {string|number} materialData.itemId - 物料ID
-     * @param {string} materialData.itemCode - 物料编码
-     * @param {string} materialData.itemName - 物料名称
-     * @param {string} materialData.specification - 物料规格
-     * @param {import('@/api/types/common').ItemRecord|null} materialData.materialData - API返回的物料数据对象
+     * @param {MaterialSelectData} materialData - 物料选择数据
      */
     handleMaterialSelected(materialData) {
       if (materialData && materialData.itemId) {
@@ -726,7 +780,7 @@ export default {
     handleReset() {
       this.initFormData()
       this.currentInventory = null
-      this.$emit('reset')
+      this.$emit(FORECAST_FORM_EVENTS.RESET)
     },
 
     /**
@@ -739,7 +793,7 @@ export default {
       try {
         // 提交数据
         const submitData = { ...this.formData }
-        
+
         let res
         if (this.isEdit) {
           res = await updateForecast(submitData)
@@ -748,7 +802,7 @@ export default {
         }
 
         // 触发提交成功事件，传递API响应数据
-        this.$emit('submit', res.data)
+        this.$emit(FORECAST_FORM_EVENTS.SUBMIT, res.data)
       } catch (error) {
         console.error('提交表单失败:', error)
         this.$message.error(error.message || '操作失败，请重试')
@@ -791,7 +845,7 @@ export default {
       this.$emit(FORECAST_FORM_EVENTS.CANCEL)
       
       // 更新可见性
-      this.$emit('update:visible', false)
+      this.$emit(FORECAST_FORM_EVENTS.UPDATE_VISIBLE, false)
       
       // 重置表单数据
       this.formData = this.createInitialFormData()

src/components/forecast-form/index.js

@@ -34,7 +34,13 @@ export const FORECAST_FORM_EVENTS = {
   /** 客户选择变更事件 */
   CUSTOMER_CHANGE: 'customer-change',
   /** 物料选择变更事件 */
-  ITEM_CHANGE: 'item-change'
+  ITEM_CHANGE: 'item-change',
+  /** 表单重置事件 */
+  RESET: 'reset',
+  /** 表单提交事件 */
+  SUBMIT: 'submit',
+  /** 更新可见性事件 */
+  UPDATE_VISIBLE: 'update:visible'
 }
 
 /**
@@ -595,7 +601,7 @@ export default {
       this.$emit(FORECAST_FORM_EVENTS.CANCEL)
       
       // 更新可见性
-      this.$emit('update:visible', false)
+      this.$emit(FORECAST_FORM_EVENTS.UPDATE_VISIBLE, false)
       
       // 重置表单数据
       this.formData = this.createInitialFormData()

src/components/forecast-form/types.d.ts

@@ -0,0 +1,344 @@
+/**
+ * 销售预测表单组件类型定义
+ * @description 为销售预测表单相关组件提供完整的TypeScript类型支持
+ */
+
+import { AxiosResponse } from 'axios'
+import { ApiResponseData, PageResult, CustomerItem, ItemRecord } from '@/api/types/common'
+
+/**
+ * 审批状态枚举
+ */
+export enum ApprovalStatus {
+  /** 待审批 */
+  PENDING = 0,
+  /** 已审批 */
+  APPROVED = 1,
+  /** 已拒绝 */
+  REJECTED = 2
+}
+
+/**
+ * 表单验证规则接口
+ */
+export interface ValidationRule {
+  /** 是否必填 */
+  required?: boolean;
+  /** 验证失败提示信息 */
+  message?: string;
+  /** 触发验证的事件类型 */
+  trigger?: 'blur' | 'change' | 'submit';
+  /** 最小长度 */
+  min?: number;
+  /** 最大长度 */
+  max?: number;
+  /** 数据类型 */
+  type?: 'string' | 'number' | 'boolean' | 'method' | 'regexp' | 'integer' | 'float' | 'array' | 'object' | 'enum' | 'date' | 'url' | 'hex' | 'email';
+  /** 最小值（数字类型） */
+  minimum?: number;
+  /** 最大值（数字类型） */
+  maximum?: number;
+  /** 正则表达式模式 */
+  pattern?: RegExp;
+  /** 自定义验证函数 */
+  validator?: (rule: ValidationRule, value: any, callback: (error?: Error) => void) => void;
+}
+
+/**
+ * 销售预测表单数据模型接口
+ */
+export interface ForecastFormModel {
+  /** 预测唯一标识 */
+  id: string | number | null;
+  /** 预测编码 */
+  forecastCode: string;
+  /** 年份 */
+  year: string;
+  /** 月份 */
+  month: number;
+  /** 客户ID */
+  customerId: string | number | null;
+  /** 客户编码 */
+  customerCode: string;
+  /** 客户名称 */
+  customerName: string;
+  /** 品牌ID */
+  brandId: number | null;
+  /** 品牌编码 */
+  brandCode: string;
+  /** 品牌名称 */
+  brandName: string;
+  /** 物料ID */
+  itemId: string | number | null;
+  /** 物料编码 */
+  itemCode: string;
+  /** 物料名称 */
+  itemName: string;
+  /** 物料规格 */
+  specs: string;
+  /** 物料规格（别名） */
+  itemSpecs: string;
+  /** 预测数量 */
+  forecastQuantity: number | null;
+  /** 当前库存 */
+  currentInventory: number | null;
+  /** 审批状态 */
+  approvalStatus: ApprovalStatus;
+  /** 审批人姓名 */
+  approvedName: string;
+  /** 审批时间 */
+  approvedTime: string | null;
+  /** 审批备注 */
+  approvalRemark: string;
+  /** 创建时间 */
+  createTime: string | null;
+  /** 更新时间 */
+  updateTime: string | null;
+}
+
+/**
+ * 销售预测表单验证规则类型
+ */
+export type ForecastFormRules = Partial<Record<keyof ForecastFormModel, ValidationRule[]>>;
+
+/**
+ * 下拉选择器选项接口
+ */
+export interface SelectOption<T = any> {
+  /** 显示标签 */
+  label: string;
+  /** 选项值 */
+  value: T;
+  /** 是否禁用 */
+  disabled?: boolean;
+  /** 选项描述 */
+  description?: string;
+}
+
+/**
+ * 客户选项类型
+ */
+export interface CustomerOption {
+  /** 客户ID */
+  value: string | number;
+  /** 客户名称 */
+  label: string;
+  /** 客户编码 */
+  customerCode: string;
+}
+
+/**
+ * 物料选项类型
+ */
+export interface ItemOption {
+  /** 物料ID */
+  value: string | number;
+  /** 物料名称 */
+  label: string;
+  /** 物料编码 */
+  itemCode: string;
+  /** 物料规格 */
+  specs: string;
+}
+
+/**
+ * 审批状态选项类型
+ */
+export type ApprovalStatusOption = SelectOption<ApprovalStatus>;
+
+/**
+ * 销售预测表单混入数据类型
+ * @description 定义销售预测表单混入组件的数据结构
+ */
+export interface ForecastFormMixinData {
+  /** 销售预测表单数据模型 */
+  formData: ForecastFormModel;
+  /** 保存操作加载状态 */
+  saveLoading: boolean;
+  /** 表单加载状态 */
+  formLoading: boolean;
+  /** 客户选项列表 */
+  customerOptions: CustomerOption[];
+  /** 客户选项加载状态 */
+  customerLoading: boolean;
+  /** 物料选项列表 */
+  itemOptions: ItemOption[];
+  /** 物料选项加载状态 */
+  itemLoading: boolean;
+  /** 审批状态选项列表 */
+  approvalStatusOptions: ApprovalStatusOption[];
+  /** 表单验证规则 */
+  formRules: typeof FORECAST_FORM_RULES;
+  /** 表单配置 */
+  formOption: any;
+  /** 当前库存 */
+  currentInventory: number | null;
+}
+
+/**
+ * API响应基础接口
+ */
+export interface ApiResponse<T = any> {
+  /** 响应状态码 */
+  code: number;
+  /** 响应消息 */
+  message: string;
+  /** 响应数据 */
+  data: T;
+  /** 是否成功 */
+  success?: boolean;
+  /** 时间戳 */
+  timestamp?: number;
+}
+
+/**
+ * 销售预测详情响应类型
+ */
+export type ForecastDetailResponse = ApiResponse<ForecastFormModel>;
+
+/**
+ * 销售预测列表响应类型
+ */
+export type ForecastListResponse = ApiResponse<PageResult<ForecastFormModel>>;
+
+/**
+ * 销售预测保存响应类型
+ */
+export type ForecastSaveResponse = ApiResponse<ForecastFormModel>;
+
+/**
+ * 销售预测表单事件接口
+ */
+export interface ForecastFormEvents {
+  /** 表单提交成功事件 */
+  'submit-success': (data: ForecastFormModel) => void;
+  /** 表单取消事件 */
+  cancel: () => void;
+  /** 表单加载完成事件 */
+  loaded: (data: ForecastFormModel) => void;
+  /** 客户选择变更事件 */
+  'customer-change': (customer: CustomerOption) => void;
+  /** 物料选择变更事件 */
+  'item-change': (item: ItemOption) => void;
+  /** 表单重置事件 */
+  reset: () => void;
+  /** 表单提交事件 */
+  submit: (data: any) => void;
+}
+
+/**
+ * 销售预测表单属性接口
+ */
+export interface ForecastFormProps {
+  /** 表单可见性控制 */
+  visible: boolean;
+  /** 编辑模式标识 */
+  isEdit: boolean;
+  /** 初始表单数据 */
+  initialFormData: ForecastFormModel | null;
+  /** 表单标题 */
+  title: string;
+  /** 编辑时的表单数据 */
+  editData: ForecastFormModel;
+}
+
+/**
+ * 销售预测表单计算属性接口
+ */
+export interface ForecastFormComputed {
+  /** 表单标题 */
+  formTitle: string;
+}
+
+/**
+ * 销售预测表单方法接口
+ */
+export interface ForecastFormMethods {
+  /** 创建初始表单数据 */
+  createInitialFormData(): ForecastFormModel;
+  /** 清理和格式化表单数据 */
+  cleanAndFormatFormData(data: any): ForecastFormModel;
+  /** 加载销售预测详情 */
+  loadForecastDetail(id: string | number): Promise<void>;
+  /** 加载单个客户选项 */
+  loadCustomerOption(customerId: string | number, customerName: string): Promise<void>;
+  /** 远程搜索客户 */
+  remoteSearchCustomer(query: string): Promise<void>;
+  /** 加载单个物料选项 */
+  loadItemOption(itemId: string | number, itemName: string, itemCode: string, specs: string): Promise<void>;
+  /** 远程搜索物料 */
+  remoteSearchItem(query: string): Promise<void>;
+  /** 客户选择变化处理 */
+  handleCustomerChange(customerId: string | number): void;
+  /** 物料选择变化处理 */
+  handleItemChange(itemId: string | number): void;
+  /** 初始化表单配置 */
+  initFormOption(): void;
+  /** 初始化表单数据 */
+  initFormData(): void;
+  /** 生成预测编码 */
+  generateForecastCode(): void;
+  /** 客户选择事件处理 */
+  handleCustomerSelected(customerData: any): void;
+  /** 品牌变更处理 */
+  handleBrandChange(brandId: number): void;
+  /** 物料选择处理 */
+  handleMaterialSelected(materialData: any): void;
+  /** 获取当前库存 */
+  getCurrentInventory(itemId: string | number): void;
+  /** 表单提交处理 */
+  handleSubmit(): void;
+  /** 表单重置处理 */
+  handleReset(): void;
+  /** 提交表单数据 */
+  submitForm(): Promise<void>;
+}
+
+/**
+ * 销售预测表单组件完整接口
+ */
+export interface ForecastFormComponent extends ForecastFormProps, ForecastFormMixinData, ForecastFormComputed, ForecastFormMethods {
+  /** 组件引用 */
+  $refs: {
+    forecastForm: any;
+  };
+  /** 事件发射器 */
+  $emit: <K extends keyof ForecastFormEvents>(event: K, ...args: Parameters<ForecastFormEvents[K]>) => void;
+  /** 消息提示 */
+  $message: {
+    success(message: string): void;
+    error(message: string): void;
+    warning(message: string): void;
+    info(message: string): void;
+  };
+  /** 下一个tick */
+  $nextTick(): Promise<void>;
+}
+
+/**
+ * 物料选择数据接口
+ */
+export interface MaterialSelectData {
+  /** 物料ID */
+  itemId: string | number;
+  /** 物料编码 */
+  itemCode: string;
+  /** 物料名称 */
+  itemName: string;
+  /** 物料规格 */
+  specification: string;
+  /** API返回的物料数据对象 */
+  materialData: ItemRecord | null;
+}
+
+/**
+ * 客户选择数据接口
+ */
+export interface CustomerSelectData {
+  /** 客户ID */
+  customerId: string | number;
+  /** 客户编码 */
+  customerCode: string;
+  /** 客户名称 */
+  customerName: string;
+}