Source: stores/modules/useApp.js

/**
 * @file stores/modules/appStore.js
 * @description Pinia Store，用于管理应用程序的全局加载状态。
 * 该 Store 通过跟踪正在进行的异步请求数量来控制一个全局加载指示器。
 * @module AppStore
 */

import { defineStore } from 'pinia'
import { ref } from 'vue'

/**
 * @function useAppStore
 * @description Pinia Store，用于管理应用程序的全局加载状态。
 * 它通过维护一个请求计数器来判断是否显示全局加载动画。
 * @returns {{
 * isLoading: Ref<boolean>,
 * startLoading: Function,
 * stopLoading: Function
 * }}
 * @property {Ref<boolean>} isLoading - 响应式布尔值，表示应用程序当前是否处于加载状态。
 * @property {Function} startLoading - 递增加载计数，并根据计数显示加载动画。
 * @property {Function} stopLoading - 递减加载计数，并根据计数隐藏加载动画。
 */
export const useAppStore = defineStore('app', () => {
  // --- 状态 (State) ---
  /**
   * @type {Ref<number>}
   * @description 记录当前正在进行的异步请求数量。
   */
  const globalLoadingCount = ref(0)
  /**
   * @type {Ref<boolean>}
   * @description 表示应用程序是否处于加载状态（当 `globalLoadingCount > 0` 时为 `true`）。
   */
  const isLoading = ref(false)

  // --- 操作 (Actions) ---

  /**
   * @function startLoading
   * @description 递增加载计数器。
   * 如果计数器从 0 变为 1，则将 `isLoading` 设置为 `true`，显示全局加载动画。
   * @returns {void}
   */
  function startLoading() {
    globalLoadingCount.value++
    if (globalLoadingCount.value > 0) {
      isLoading.value = true
    }
  }

  /**
   * @function stopLoading
   * @description 递减加载计数器。
   * 如果计数器变为 0 或更小，则将 `isLoading` 设置为 `false`，隐藏全局加载动画。
   * 同时确保计数器不会变为负数。通常在异步请求完成后调用。
   * @returns {void}
   */
  function stopLoading() {
    globalLoadingCount.value--
    if (globalLoadingCount.value <= 0) {
      globalLoadingCount.value = 0 // 防止计数器出现负数
      isLoading.value = false
    }
  }

  // --- 返回 Store 的状态和操作 ---
  return {
    isLoading,
    startLoading,
    stopLoading
  }
})