docs(forecast-form): 添加组件类型定义和JSDoc注释

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

@@ -1,9 +1,30 @@
+// @ts-check
+
 /**
  * @fileoverview 销售预测表单混入组件
  * @description 提供销售预测表单的数据管理、验证规则和业务逻辑的混入组件，支持新增和编辑模式
  */
 
 /**
+ * 销售预测表单混入组件实例类型定义
+ * @typedef {object} ForecastFormMixinComponent
+ * @property {import('./types').ForecastFormModel} formData - 表单数据
+ * @property {import('./types').FormOption} formOption - 表单配置选项
+ * @property {boolean} saveLoading - 保存加载状态
+ * @property {import('./types').CustomerOption[]} customerOptions - 客户选项列表
+ * @property {import('./types').ItemOption[]} itemOptions - 物料选项列表
+ * @property {number|null} currentInventory - 当前库存数量
+ * @property {import('./types').ApprovalStatusOption[]} approvalStatusOptions - 审批状态选项
+ * @property {import('./types').ForecastFormRules} formRules - 表单验证规则
+ * @property {boolean} visible - 表单可见性
+ * @property {boolean} isEdit - 是否为编辑模式
+ * @property {Object|null} editData - 编辑数据
+ * @property {Object|null} initialFormData - 初始表单数据
+ * @property {string} title - 表单标题
+ * @property {string} forecastId - 预测ID
+ */
+
+/**
  * 类型定义导入
  * @description 导入所有必要的TypeScript类型定义，确保类型安全
  */
@@ -259,6 +280,7 @@ export default {
     /**
      * 表单标题
      * @description 根据编辑模式动态显示表单标题
+     * @this {ForecastFormMixinComponent & Vue}
      * @returns {string} 表单标题文本
      */
     formTitle() {
@@ -277,6 +299,7 @@ export default {
     /**
      * 监听表单可见性变化
      * @param {boolean} val - 新的可见性值
+     * @this {ForecastFormMixinComponent & Vue}
      */
     visible(val) {
       if (val) {
@@ -304,6 +327,7 @@ export default {
     /**
      * 监听初始表单数据变化
      * @param {Object} val - 新的初始表单数据
+     * @this {ForecastFormMixinComponent & Vue}
      */
     initialFormData(val) {
       if (val) {
@@ -313,6 +337,7 @@ export default {
 
     /**
      * 监听编辑数据变化
+     * @this {ForecastFormMixinComponent & Vue}
      */
     editData: {
       handler(newData) {
@@ -329,6 +354,7 @@ export default {
 
     /**
      * 监听编辑模式变化
+     * @this {ForecastFormMixinComponent & Vue}
      */
     isEdit: {
       handler(newVal) {
@@ -343,6 +369,7 @@ export default {
     /**
      * 监听预测ID变化
      * @param {string|number} val - 新的预测ID
+     * @this {ForecastFormMixinComponent & Vue}
      */
     forecastId: {
       handler(val) {
@@ -356,6 +383,7 @@ export default {
 
   /**
    * 组件创建时
+   * @this {ForecastFormMixinComponent & Vue}
    */
   created() {
     this.initFormOption()
@@ -371,6 +399,7 @@ export default {
      * 创建初始表单数据
      * @description 创建销售预测表单的初始数据结构
      * @returns {ForecastFormModel} 初始化的表单数据对象
+     * @this {ForecastFormMixinComponent & Vue}
      * @private
      */
     createInitialFormData() {
@@ -382,6 +411,7 @@ export default {
      * @description 对表单数据进行清理和格式化处理
      * @param {any} data - 原始表单数据
      * @returns {ForecastFormModel} 清理和格式化后的表单数据
+     * @this {ForecastFormMixinComponent & Vue}
      * @private
      */
     cleanAndFormatFormData(data) {
@@ -632,6 +662,8 @@ export default {
 
     /**
      * 初始化表单数据
+     * @description 根据编辑模式初始化表单数据，新增模式自动填入下个月
+     * @this {ForecastFormMixinComponent & Vue}
      */
     initFormData() {
       if (this.isEdit && this.editData) {
@@ -700,6 +732,7 @@ export default {
     /**
      * 客户选择事件处理
      * @param {CustomerSelectData} customerData - 客户选择数据
+     * @this {ForecastFormMixinComponent & Vue}
      */
     handleCustomerSelected(customerData) {
       if (customerData && customerData.customerId) {
@@ -715,6 +748,7 @@ export default {
 
     /**
      * 品牌变更处理
+     * @this {ForecastFormMixinComponent & Vue}
      */
     handleBrandChange(brandId) {
       const selectedBrand = this.brandOptions.find(brand => brand.id === brandId)
@@ -731,6 +765,7 @@ export default {
      * 物料选择处理
      * @description 处理MaterialSelect组件的物料选择事件
      * @param {MaterialSelectData} materialData - 物料选择数据
+     * @this {ForecastFormMixinComponent & Vue}
      */
     handleMaterialSelected(materialData) {
       if (materialData && materialData.itemId) {
@@ -752,6 +787,7 @@ export default {
     /**
      * 获取当前库存
      * @param {string|number} itemId - 物料ID
+     * @this {ForecastFormMixinComponent & Vue}
      */
     getCurrentInventory(itemId) {
       // 简化实现，实际应该调用API
@@ -763,6 +799,7 @@ export default {
 
     /**
      * 表单提交处理
+     * @this {ForecastFormMixinComponent & Vue}
      */
     handleSubmit() {
       // 表单验证
@@ -776,6 +813,7 @@ export default {
 
     /**
      * 表单重置处理
+     * @this {ForecastFormMixinComponent & Vue}
      */
     handleReset() {
       this.initFormData()
@@ -786,6 +824,7 @@ export default {
     /**
      * 提交表单数据
      * @description 执行表单数据的提交操作，包括数据验证和API调用
+     * @this {ForecastFormMixinComponent & Vue}
      * @returns {Promise<void>} 提交操作的Promise
      * @throws {Error} 当提交失败时抛出错误
      */
@@ -838,6 +877,7 @@ export default {
     /**
      * 关闭表单
      * @description 关闭表单并重置数据
+     * @this {ForecastFormMixinComponent & Vue}
      * @returns {void}
      */
     closeForm() {

src/components/forecast-form/index.js

@@ -1,8 +1,29 @@
+// @ts-check
+
 /**
  * @fileoverview 销售预测表单混入组件
  * @description 提供销售预测表单的数据管理、验证规则和业务逻辑的混入组件，支持新增和编辑模式
  */
 
+/**
+ * 销售预测表单混入组件实例类型定义
+ * @typedef {object} ForecastFormMixinComponent
+ * @property {import('./types').ForecastFormModel} formData - 表单数据
+ * @property {import('./types').FormOption} formOption - 表单配置选项
+ * @property {boolean} saveLoading - 保存加载状态
+ * @property {import('./types').CustomerOption[]} customerOptions - 客户选项列表
+ * @property {import('./types').ItemOption[]} itemOptions - 物料选项列表
+ * @property {number|null} currentInventory - 当前库存数量
+ * @property {import('./types').ApprovalStatusOption[]} approvalStatusOptions - 审批状态选项
+ * @property {import('./types').ForecastFormRules} formRules - 表单验证规则
+ * @property {boolean} visible - 表单可见性
+ * @property {boolean} isEdit - 是否为编辑模式
+ * @property {Object|null} editData - 编辑数据
+ * @property {Object|null} initialFormData - 初始表单数据
+ * @property {string} title - 表单标题
+ * @property {string} forecastId - 预测ID
+ */
+
 // API接口导入
 import { addForecast, updateForecast, getForecastDetail } from '@/api/forecast'
 
@@ -182,6 +203,7 @@ export default {
     /**
      * 表单标题
      * @description 根据编辑模式动态显示表单标题
+     * @this {ForecastFormMixinComponent & Vue}
      * @returns {string} 表单标题文本
      */
     formTitle() {
@@ -199,6 +221,7 @@ export default {
   watch: {
     /**
      * 监听表单可见性变化
+     * @this {ForecastFormMixinComponent & Vue}
      * @param {boolean} val - 新的可见性值
      */
     visible(val) {
@@ -226,6 +249,7 @@ export default {
 
     /**
      * 监听初始表单数据变化
+     * @this {ForecastFormMixinComponent & Vue}
      * @param {Object} val - 新的初始表单数据
      */
     initialFormData(val) {
@@ -236,6 +260,7 @@ export default {
 
     /**
      * 监听预测ID变化
+     * @this {ForecastFormMixinComponent & Vue}
      * @param {string|number} val - 新的预测ID
      */
     forecastId: {
@@ -256,6 +281,7 @@ export default {
     /**
      * 创建初始表单数据
      * @description 创建销售预测表单的初始数据结构
+     * @this {ForecastFormMixinComponent & Vue}
      * @returns {Object} 初始化的表单数据对象
      * @private
      */
@@ -266,6 +292,7 @@ export default {
     /**
      * 清理和格式化表单数据
      * @description 对表单数据进行清理和格式化处理
+     * @this {ForecastFormMixinComponent & Vue}
      * @param {Object} data - 原始表单数据
      * @returns {Object} 清理和格式化后的表单数据
      * @private
@@ -315,6 +342,7 @@ export default {
     /**
      * 加载销售预测详情
      * @description 根据ID加载销售预测详情数据
+     * @this {ForecastFormMixinComponent & Vue}
      * @param {string|number} id - 销售预测ID
      * @returns {Promise<void>}
      * @private
@@ -356,6 +384,7 @@ export default {
     /**
      * 加载单个客户选项
      * @description 为编辑模式加载特定客户的选项数据
+     * @this {ForecastFormMixinComponent & Vue}
      * @param {string|number} customerId - 客户ID
      * @param {string} customerName - 客户名称
      * @returns {Promise<void>}
@@ -375,6 +404,7 @@ export default {
     /**
      * 远程搜索客户
      * @description 根据关键字远程搜索客户数据
+     * @this {ForecastFormMixinComponent & Vue}
      * @param {string} query - 搜索关键字
      * @returns {Promise<void>}
      */
@@ -410,6 +440,7 @@ export default {
     /**
      * 加载单个物料选项
      * @description 为编辑模式加载特定物料的选项数据
+     * @this {ForecastFormMixinComponent & Vue}
      * @param {string|number} itemId - 物料ID
      * @param {string} itemName - 物料名称
      * @param {string} itemCode - 物料编码
@@ -439,6 +470,7 @@ export default {
     /**
      * 远程搜索物料
      * @description 根据关键字远程搜索物料数据
+     * @this {ForecastFormMixinComponent & Vue}
      * @param {string} query - 搜索关键字
      * @returns {Promise<void>}
      */
@@ -475,6 +507,7 @@ export default {
     /**
      * 客户选择变化处理
      * @description 处理客户选择变化，更新表单中的客户相关字段
+     * @this {ForecastFormMixinComponent & Vue}
      * @param {string|number} customerId - 客户ID
      * @returns {void}
      */
@@ -493,6 +526,7 @@ export default {
     /**
      * 物料选择变化处理
      * @description 处理物料选择变化，更新表单中的物料相关字段
+     * @this {ForecastFormMixinComponent & Vue}
      * @param {string|number} itemId - 物料ID
      * @returns {void}
      */
@@ -512,6 +546,7 @@ export default {
     /**
      * 生成预测编码
      * @description 自动生成销售预测编码
+     * @this {ForecastFormMixinComponent & Vue}
      * @returns {void}
      */
     generateForecastCode() {
@@ -525,6 +560,7 @@ export default {
     /**
      * 表单提交
      * @description 提交表单数据，根据编辑模式调用不同的API
+     * @this {ForecastFormMixinComponent & Vue}
      * @returns {Promise<void>}
      */
     async submitForm() {
@@ -568,6 +604,7 @@ export default {
     /**
      * 准备提交数据
      * @description 复制表单数据并进行清理和格式化处理
+     * @this {ForecastFormMixinComponent & Vue}
      * @returns {Object} 准备好的提交数据
      * @private
      */
@@ -594,6 +631,7 @@ export default {
     /**
      * 关闭表单
      * @description 关闭表单并重置数据
+     * @this {ForecastFormMixinComponent & Vue}
      * @returns {void}
      */
     closeForm() {

src/components/forecast-form/index.vue

@@ -58,6 +58,25 @@ import CustomerSelect from '@/components/common/customer-select.vue'
 import MaterialSelect from '@/components/common/material-select.vue'
 
 /**
+ * 销售预测表单组件实例类型定义
+ * @typedef {object} ForecastFormAvueComponent
+ * @property {import('./types').ForecastFormModel} formData - 表单数据
+ * @property {import('./types').FormOption} formOption - 表单配置选项
+ * @property {boolean} saveLoading - 保存加载状态
+ * @property {import('./types').CustomerOption[]} customerOptions - 客户选项列表
+ * @property {import('./types').ItemOption[]} itemOptions - 物料选项列表
+ * @property {number|null} currentInventory - 当前库存数量
+ * @property {import('./types').ApprovalStatusOption[]} approvalStatusOptions - 审批状态选项
+ * @property {import('./types').ForecastFormRules} formRules - 表单验证规则
+ * @property {boolean} visible - 表单可见性
+ * @property {boolean} isEdit - 是否为编辑模式
+ * @property {Object|null} editData - 编辑数据
+ * @property {Object|null} initialFormData - 初始表单数据
+ * @property {string} title - 表单标题
+ * @property {string} forecastId - 预测ID
+ */
+
+/**
  * 销售预测表单组件 - AvueJS版本
  * @description 基于AvueJS的销售预测表单组件，支持新增和编辑销售预测功能
  */