Pinia 概述

┌─────────────────────────────────────────────────────────────┐
│                          App                                  │
│  ┌──────────┐     ┌──────────┐     ┌──────────┐            │
│  │ Header   │     │ Sidebar  │     │ Content  │            │
│  │ - 用户信息│     │ - 购物车 │     │ - 商品列表│            │
│  └────┬─────┘     └────┬─────┘     └────┬─────┘            │
│       │                │                │                   │
│       └────────────────┼────────────────┘                   │
│                        │                                    │
│              需要共享的状态：                                │
│              • 用户登录信息                                  │
│              • 购物车数据                                    │
│              • 全局主题设置                                  │
│              • 通知消息                                      │
└─────────────────────────────────────────────────────────────┘

Pinia 架构层次
├── Pinia 实例（createPinia）
│   ├── 管理所有 Store 注册
│   ├── 提供 Vue 应用集成
│   └── 插件系统入口
│
├── Store（defineStore）
│   ├── State（状态数据）
│   ├── Getters（计算属性）
│   └── Actions（方法）
│
└── 组合式函数
    ├── storeToRefs（响应式解构）
    └── mapStores（Options API 辅助）

// store/index.ts
import { createStore } from 'vuex'

export default createStore({
  state: {
    count: 0
  },
  mutations: {
    SET_COUNT(state, payload) {
      state.count = payload
    },
    INCREMENT(state) {
      state.count++
    }
  },
  actions: {
    async fetchCount({ commit }) {
      const res = await fetch('/api/count')
      const data = await res.json()
      commit('SET_COUNT', data)
    }
  },
  getters: {
    double: state => state.count * 2
  }
})

// 组件中使用
import { useStore } from 'vuex'
const store = useStore()
store.commit('INCREMENT')           // mutation
await store.dispatch('fetchCount')  // action
const double = computed(() => store.getters.double)

// stores/counter.ts
export const useCounterStore = defineStore('counter', () => {
  const count = ref(0)
  const double = computed(() => count.value * 2)
  
  async function fetchCount() {
    const res = await fetch('/api/count')
    count.value = await res.json()
  }
  
  return { count, double, fetchCount }
})

// 组件中使用
const counter = useCounterStore()
counter.count++                     // 直接修改
await counter.fetchCount()          // 调用 action
const { double } = storeToRefs(counter)  // getter

# npm
npm install pinia

# yarn
yarn add pinia

# pnpm
pnpm add pinia

// main.ts
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import App from './App.vue'

const app = createApp(App)

// 创建并注册 Pinia
const pinia = createPinia()
app.use(pinia)

app.mount('#app')

// main.ts
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import { createRouter, createWebHistory } from 'vue-router'
import App from './App.vue'

const app = createApp(App)
const pinia = createPinia()

const router = createRouter({
  history: createWebHistory(),
  routes: [...]
})

app.use(pinia)
app.use(router)
app.mount('#app')

// stores/counter.ts
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'

export const useCounterStore = defineStore('counter', () => {
  // ==================== State ====================
  const count = ref(0)
  const name = ref('My Counter')
  const history = ref<number[]>([])
  
  // ==================== Getters ====================
  const double = computed(() => count.value * 2)
  
  const isPositive = computed(() => count.value > 0)
  
  const historyCount = computed(() => history.value.length)
  
  // ==================== Actions ====================
  function increment() {
    count.value++
    history.value.push(count.value)
  }
  
  function decrement() {
    count.value--
    history.value.push(count.value)
  }
  
  function reset() {
    count.value = 0
    history.value = []
  }
  
  async function fetchInitialValue() {
    try {
      const response = await fetch('/api/counter/initial')
      const data = await response.json()
      count.value = data.value
    } catch (error) {
      console.error('Failed to fetch initial value:', error)
    }
  }
  
  return {
    // State
    count,
    name,
    history,
    // Getters
    double,
    isPositive,
    historyCount,
    // Actions
    increment,
    decrement,
    reset,
    fetchInitialValue
  }
})

<!-- components/Counter.vue -->
<script setup lang="ts">
import { useCounterStore } from '@/stores/counter'
import { storeToRefs } from 'pinia'

const counter = useCounterStore()

// 响应式解构 State 和 Getters
const { count, double, isPositive, history } = storeToRefs(counter)

// 直接解构 Actions
const { increment, decrement, reset } = counter
</script>

<template>
  <div class="counter">
    <h2>{{ counter.name }}</h2>
    
    <div class="display">
      <span class="count" :class="{ negative: !isPositive }">
        {{ count }}
      </span>
      <span class="double">Double: {{ double }}</span>
    </div>
    
    <div class="controls">
      <button @click="decrement">-</button>
      <button @click="reset">Reset</button>
      <button @click="increment">+</button>
    </div>
    
    <div class="history">
      <h3>History</h3>
      <span v-for="(val, i) in history" :key="i">{{ val }}</span>
    </div>
  </div>
</template>

<style scoped>
.counter {
  padding: 20px;
  text-align: center;
}

.count {
  font-size: 48px;
  font-weight: bold;
}

.count.negative {
  color: #f44336;
}

.double {
  margin-left: 20px;
  color: #666;
}

.controls button {
  margin: 10px 5px;
  padding: 10px 20px;
  font-size: 18px;
}
</style>

┌─────────────────────────────────────────────────────────────┐
│                         Pinia Store                          │
│                                                               │
│  ┌─────────┐        ┌──────────┐        ┌─────────────┐     │
│  │  State  │───────▶│ Getters  │        │   Actions   │     │
│  │ (数据)  │        │ (计算属性)│        │  (方法)     │     │
│  └────┬────┘        └────┬─────┘        └──────┬──────┘     │
│       │                  │                     │             │
│       │                  ▼                     │             │
│       │           ┌──────────┐                 │             │
│       └──────────▶│Component │◀────────────────┘             │
│                   │  组件    │                               │
│                   └──────────┘                               │
└─────────────────────────────────────────────────────────────┘

数据流向说明：
• State 变化 → 自动更新组件
• Getters 依赖 State → 缓存计算结果
• Actions 可修改 State → 触发更新

// 在控制台中直接访问
const counter = useCounterStore()

// 查看状态
console.log(counter.$state)

// 修改状态
counter.$patch({ count: 100 })

// 重置状态
counter.$reset()

// Vuex 模块
const store = {
  state: () => ({ count: 0 }),
  mutations: {
    INCREMENT(state) { state.count++ }
  },
  actions: {
    increment({ commit }) { commit('INCREMENT') }
  },
  getters: {
    double: state => state.count * 2
  }
}

// ↓ 迁移为 Pinia Store
export const useCounterStore = defineStore('counter', () => {
  const count = ref(0)
  const double = computed(() => count.value * 2)
  
  // mutations 合并到 actions
  function increment() {
    count.value++
  }
  
  return { count, double, increment }
})

defineStore(id, optionsOrSetup)

// ✅ 推荐：使用 kebab-case，语义化命名
defineStore('user-profile', ...)
defineStore('shopping-cart', ...)
defineStore('product-list', ...)

// ⚠️ 避免：过于简单或模糊
defineStore('store1', ...)
defineStore('data', ...)

export const useCounterStore = defineStore('counter', {
  // 状态：返回初始状态的函数
  state: () => ({
    count: 0,
    name: 'Counter',
    items: [] as string[]
  }),
  
  // 计算属性：派生状态
  getters: {
    double: (state) => state.count * 2,
    itemCount: (state) => state.items.length
  },
  
  // 方法：业务逻辑
  actions: {
    increment() {
      this.count++
    },
    addItem(item: string) {
      this.items.push(item)
    }
  }
})

// stores/user.ts
import { defineStore } from 'pinia'

interface User {
  id: number
  name: string
  email: string
  role: 'admin' | 'user'
}

interface UserState {
  user: User | null
  token: string | null
  loading: boolean
  error: string | null
}

export const useUserStore = defineStore('user', {
  state: (): UserState => ({
    user: null,
    token: null,
    loading: false,
    error: null
  }),
  
  getters: {
    isLoggedIn: (state) => !!state.user && !!state.token,
    
    isAdmin: (state) => state.user?.role === 'admin',
    
    // 访问其他 getter
    userDisplayName(): string {
      return this.user?.name ?? 'Guest'
    },
    
    // 接收参数
    hasPermission: (state) => (permission: string) => {
      // 假设有权限检查逻辑
      return state.user?.role === 'admin'
    }
  },
  
  actions: {
    async login(email: string, password: string) {
      this.loading = true
      this.error = null
      
      try {
        const response = await fetch('/api/login', {
          method: 'POST',
          body: JSON.stringify({ email, password })
        })
        
        if (!response.ok) {
          throw new Error('Login failed')
        }
        
        const data = await response.json()
        this.user = data.user
        this.token = data.token
      } catch (err) {
        this.error = err instanceof Error ? err.message : 'Unknown error'
      } finally {
        this.loading = false
      }
    },
    
    logout() {
      this.user = null
      this.token = null
    },
    
    async fetchProfile() {
      if (!this.token) return
      
      this.loading = true
      try {
        const response = await fetch('/api/profile', {
          headers: { Authorization: `Bearer ${this.token}` }
        })
        this.user = await response.json()
      } finally {
        this.loading = false
      }
    }
  }
})

export const useCounterStore = defineStore('counter', () => {
  // ==================== State ====================
  const count = ref(0)
  const name = ref('Counter')
  const items = ref<string[]>([])
  
  // ==================== Getters ====================
  const double = computed(() => count.value * 2)
  const itemCount = computed(() => items.value.length)
  
  // ==================== Actions ====================
  function increment() {
    count.value++
  }
  
  function addItem(item: string) {
    items.value.push(item)
  }
  
  // ⚠️ 必须返回所有需要暴露的属性
  return {
    count,
    name,
    items,
    double,
    itemCount,
    increment,
    addItem
  }
})

// stores/product.ts
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'

interface Product {
  id: number
  name: string
  price: number
  category: string
  stock: number
}

export const useProductStore = defineStore('products', () => {
  // ==================== State ====================
  const products = ref<Product[]>([])
  const categories = ref<string[]>([])
  const selectedCategory = ref<string | null>(null)
  const loading = ref(false)
  const error = ref<string | null>(null)
  
  // 私有状态（不暴露）
  const _cache = new Map<number, Product>()
  
  // ==================== Getters ====================
  const filteredProducts = computed(() => {
    if (!selectedCategory.value) return products.value
    return products.value.filter(
      p => p.category === selectedCategory.value
    )
  })
  
  const totalProducts = computed(() => products.value.length)
  
  const lowStockProducts = computed(() => 
    products.value.filter(p => p.stock < 10)
  )
  
  const getProductById = computed(() => 
    (id: number) => _cache.get(id) ?? products.value.find(p => p.id === id)
  )
  
  // ==================== Actions ====================
  async function fetchProducts() {
    loading.value = true
    error.value = null
    
    try {
      const response = await fetch('/api/products')
      products.value = await response.json()
      
      // 更新缓存
      products.value.forEach(p => _cache.set(p.id, p))
      
      // 提取分类
      categories.value = [...new Set(products.value.map(p => p.category))]
    } catch (err) {
      error.value = err instanceof Error ? err.message : 'Failed to fetch'
    } finally {
      loading.value = false
    }
  }
  
  function setCategory(category: string | null) {
    selectedCategory.value = category
  }
  
  async function updateStock(id: number, quantity: number) {
    const product = products.value.find(p => p.id === id)
    if (product) {
      product.stock += quantity
      _cache.set(id, product)
    }
  }
  
  // ==================== 重置功能 ====================
  const initialState = {
    products: [],
    categories: [],
    selectedCategory: null
  }
  
  function $reset() {
    products.value = initialState.products
    categories.value = initialState.categories
    selectedCategory.value = initialState.selectedCategory
    _cache.clear()
  }
  
  return {
    // State
    products,
    categories,
    selectedCategory,
    loading,
    error,
    // Getters
    filteredProducts,
    totalProducts,
    lowStockProducts,
    getProductById,
    // Actions
    fetchProducts,
    setCategory,
    updateStock,
    $reset
  }
})

// ✅ 使用 Option Store 的场景
// 1. 简单的状态管理
// 2. 团队熟悉 Vuex
// 3. 需要 $reset() 的便捷功能

export const useCounterStore = defineStore('counter', {
  state: () => ({ count: 0 }),
  getters: {
    double: state => state.count * 2
  },
  actions: {
    increment() { this.count++ }
  }
})

// ✅ 使用 Setup Store 的场景
// 1. 需要 TypeScript 完美支持
// 2. 复杂业务逻辑
// 3. 需要私有属性或方法
// 4. 需要组合其他组合式函数

export const useUserStore = defineStore('user', () => {
  // 可以使用私有变量
  const _secret = ref('private')
  
  // 可以调用其他组合式函数
  const { locale, t } = useI18n()
  const router = useRouter()
  
  const user = ref<User | null>(null)
  
  async function login(credentials: Credentials) {
    user.value = await authApi.login(credentials)
    router.push('/dashboard')
  }
  
  return { user, login }
  // _secret 不暴露，外部无法访问
})

src/stores/
├── index.ts              # 统一导出
├── user.ts               # 用户 Store
├── cart.ts               # 购物车 Store
├── products/
│   ├── index.ts          # 商品主 Store
│   ├── filters.ts        # 筛选逻辑
│   └── inventory.ts      # 库存逻辑
└── composables/
    ├── useAuth.ts        # 认证组合式函数
    └── useNotification.ts

// Store 文件名：kebab-case
// user-profile.ts
// shopping-cart.ts

// Store 函数名：useXxxStore
export const useUserProfileStore = defineStore('user-profile', ...)
export const useShoppingCartStore = defineStore('shopping-cart', ...)

// 组件中使用
const userProfile = useUserProfileStore()
const cart = useShoppingCartStore()

// stores/index.ts
export { useUserStore } from './user'
export { useCartStore } from './cart'
export { useProductStore } from './products'

// 使用时
import { useUserStore, useCartStore } from '@/stores'

// stores/order.ts
import { defineStore } from 'pinia'
import { useUserStore } from './user'
import { useCartStore } from './cart'

export const useOrderStore = defineStore('order', () => {
  const userStore = useUserStore()
  const cartStore = useCartStore()
  
  const orders = ref<Order[]>([])
  
  const canCheckout = computed(() => {
    return userStore.isLoggedIn && cartStore.items.length > 0
  })
  
  async function checkout() {
    if (!canCheckout.value) return
    
    const order = await createOrder({
      userId: userStore.user!.id,
      items: cartStore.items
    })
    
    orders.value.push(order)
    cartStore.clear()
  }
  
  return { orders, canCheckout, checkout }
})

// composables/useAsync.ts
import { ref, type Ref } from 'vue'

export function useAsync<T>(asyncFn: () => Promise<T>) {
  const data: Ref<T | null> = ref(null)
  const loading = ref(false)
  const error: Ref<Error | null> = ref(null)
  
  async function execute() {
    loading.value = true
    error.value = null
    try {
      data.value = await asyncFn()
    } catch (e) {
      error.value = e instanceof Error ? e : new Error(String(e))
    } finally {
      loading.value = false
    }
  }
  
  return { data, loading, error, execute }
}

// stores/posts.ts
import { defineStore } from 'pinia'
import { useAsync } from '@/composables/useAsync'

export const usePostsStore = defineStore('posts', () => {
  const posts = ref<Post[]>([])
  
  // 复用异步逻辑
  const { loading, error, execute: fetchPosts } = useAsync(async () => {
    const res = await fetch('/api/posts')
    posts.value = await res.json()
    return posts.value
  })
  
  return { posts, loading, error, fetchPosts }
})

// ❌ 错误：在 Pinia 注册前调用 Store
const store = useUserStore() // Error!
const app = createApp(App)
app.use(createPinia())

// ✅ 正确：在组件或 setup 函数中调用
const app = createApp(App)
app.use(createPinia())
app.mount('#app')

// stores/a.ts
import { useBStore } from './b'  // 可能循环依赖

export const useAStore = defineStore('a', () => {
  // ✅ 解决方案：在函数内部导入
  function doSomething() {
    const bStore = useBStore()
    // ...
  }
})

// ❌ 错误：忘记返回
export const useStore = defineStore('store', () => {
  const count = ref(0)
  // 忘记 return
})

// ✅ 正确：显式返回
export const useStore = defineStore('store', () => {
  const count = ref(0)
  return { count }
})

// ── 简化版 createPinia ──
import { ref, effectScope, markRaw } from 'vue'

export function createPinia(): Pinia {
  // 用于管理所有副作用，确保在 dispose 时能一次性清理
  const scope = effectScope(true)
  // run() 执行传入函数并收集其中的 effect（watch、computed 等）
  const state = scope.run<Ref<Record<string, StateTree>>>(() =>
    ref<Record<string, StateTree>>({})
  )!

  // _s 是核心：Store ID → Store 实例的映射表
  const _s = new Map<string, Store>()

  // 存储所有通过 $onAction 注册的 action 订阅回调
  let actionSubscriptions: OnActionCallback[] = []

  // 存储所有插件列表
  const plugins: PiniaPlugin[] = []

  const pinia: Pinia = markRaw({
    install(app: App) {
      // 阻止多次注册同一个 pinia 实例
      if (isVue2) {
        app.config.globalProperties.$pinia = pinia
      } else {
        // 通过 provide 注入，让所有后代组件都能通过 inject 访问
        app.provide(piniaSymbol, pinia)
      }
      // 挂载到全局属性，方便 Options API 使用
      app.config.globalProperties.$pinia = pinia
      // 注册 devtools（见后续分析）
      if (process.env.NODE_ENV !== 'production') {
        registerPiniaDevtools(app, pinia)
      }
    },

    use(plugin: PiniaPlugin) {
      plugins.push(plugin)
      return this // 支持链式调用 pinia.use(a).use(b)
    },

    _s,  // Store 注册表
    _p: plugins,              // 插件列表
    _a: actionSubscriptions,  // Action 订阅列表
    _e: scope,                // effectScope 实例

    // $dispose: 销毁 pinia 实例
    async $dispose() {
      scope.stop()    // 停止所有副作用
      _s.clear()      // 清空 Store 注册表
      actionSubscriptions = [] // 清空 action 订阅
    },

    _testing: process.env.NODE_ENV !== 'production' ? { plugins, _s } : undefined,
    state // 根状态引用
  })

  return pinia
}

// ── 简化版 defineStore 核心逻辑 ──
function defineStore(
  idOrOptions: string | DefineStoreOptions,
  setupOrOptions?: SetupFunction | DefineStoreOptions
): StoreDefinition {
  let id: string
  let options: DefineStoreOptions

  // 处理两种调用签名
  if (typeof idOrOptions === 'string') {
    id = idOrOptions
    options = typeof setupOrOptions === 'function'
      ? { id, setup: setupOrOptions }
      : { id, ...setupOrOptions }
  } else {
    options = idOrOptions
    id = options.id
  }

  // 判断是否为 Setup Store
  const isSetupStore = typeof options.setup === 'function'

  function useStore(pinia?: Pinia | null): Store {
    // 获取当前 pinia 实例（从 inject 或参数）
    const currentInstance = pinia || getCurrentInstance()

    // ★ 核心：检查 _s Map 中是否已有该 Store 实例
    if (!currentInstance._s.has(id)) {
      if (isSetupStore) {
        createSetupStore(id, options.setup!, options, currentInstance)
      } else {
        createOptionsStore(id, options, currentInstance)
      }
    }

    // 返回已缓存的实例 —— 这就是单例保证
    return currentInstance._s.get(id)!
  }

  useStore.$id = id
  return useStore
}

// ── 简化版 createOptionsStore ──
function createOptionsStore(
  id: string,
  options: DefineStoreOptions,
  pinia: Pinia
): Store {
  const { state, getters, actions } = options

  // 将 Option Store 转换为 Setup Store 形式
  function setup() {
    // 1. 用 ref() 包装初始 state
    const localState = pinia.state.value[id] = state ? state() : {}

    // 2. 将 getters 转为 computed
    const localGetters: Record<string, ComputedRef> = {}
    for (const key in getters) {
      localGetters[key] = computed(() => {
        // getters 中的 this 指向 store 实例
        return getters[key].call(storeRef, storeRef)
      })
    }

    // 3. actions 保持为普通函数
    const localActions: Record<string, Function> = {}
    for (const key in actions) {
      localActions[key] = function (...args: any[]) {
        // action 中的 this 指向 store 实例
        return actions[key].apply(storeRef, args)
      }
    }

    return { ...localState, ...localGetters, ...localActions }
  }

  // 复用 Setup Store 的创建流程
  return createSetupStore(id, setup, options, pinia)
}

// ── 简化版 createSetupStore（核心骨架）──
function createSetupStore(
  id: string,
  setup: () => Record<string, unknown>,
  options: DefineStoreOptions,
  pinia: Pinia
): Store {
  const partialStore = {
    $id: id,
    $pinia: pinia,
    _customProperties: new Set() // 插件注入的属性追踪
  } as Store

  // 1. 在 pinia 的 effectScope 内运行 setup
  const setupReturns = pinia._e.run(() =>
    setup()
  )!

  // 2. 分离 state / getters / actions
  const stateKeys = new Set<string>()
  const getterKeys = new Set<string>()
  const actionKeys = new Set<string>()

  for (const key in setupReturns) {
    const value = setupReturns[key]
    if (isRef(value) && !isComputed(value)) {
      stateKeys.add(key)  // ref 且非 computed → state
    } else if (isComputed(value)) {
      getterKeys.add(key)  // computed → getter
    } else if (typeof value === 'function') {
      actionKeys.add(key)  // function → action
    } else {
      // 普通值 → 用 ref 包装为 state
      stateKeys.add(key)
    }
  }

  // 3. 用 reactive 包装整个 store，使其具备深度响应性
  //    Pinia 源码中这里是手动构建 Proxy，此处简化
  const store = reactive(partialStore) as Store

  // 4. 将 setup 的返回值挂载到 store 上
  for (const key in setupReturns) {
    const value = setupReturns[key]
    if (actionKeys.has(key)) {
      // Action 不经过 reactive，直接挂载
      store[key] = wrapAction(key, value as Function, store)
    } else {
      // state 和 getter 已经是响应式的（ref/computed）
      // 通过 reactive 的 store 代理访问
      Object.defineProperty(store, key, {
        get() { return setupReturns[key]; },
        set(val) {
          if (actionKeys.has(key)) return  // 禁止覆盖 action
          setupReturns[key] = val
        },
        enumerable: true,
        configurable: true
      })
    }
  }

  // 5. 注册到 pinia._s Map
  pinia._s.set(id, store)

  // 6. 运行插件
  pinia._p.forEach(plugin => plugin({ store, pinia, app: pinia._a }))

  // 7. Option Store 特殊处理：保存初始 state 用于 $reset
  if (options.state) {
    const initialState = options.state()
    store.$reset = () => store.$patch((state: any) => {
      Object.assign(state, initialState)
    })
  }

  return store
}

┌─────────────────────────────────────────────────────────────────┐
│                    useXxxStore() 调用流程                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  1. 获取 pinia 实例 (inject piniaSymbol)                        │
│                    │                                             │
│  2. 检查 pinia._s.has(id) → 已有？直接返回                      │
│                    │                                             │
│                    ▼ (首次创建)                                  │
│  3. 判断 Store 类型                                              │
│     ├─ Setup Store → createSetupStore(id, setup, options)       │
│     └─ Option Store → createOptionsStore(id, options)           │
│                         └→ 内部转为 setup 函数                  │
│                            └→ createSetupStore(...)              │
│                                                                  │
│  4. createSetupStore 核心步骤：                                  │
│     a. 在 effectScope 内运行 setup()，收集返回值                 │
│     b. 按类型分类：ref = state, computed = getter, fn = action  │
│     c. 用 reactive() 包装 store 对象                            │
│     d. 将属性挂载到 reactive store 上（defineProperty + proxy） │
│     e. 写入 pinia._s Map (单例缓存)                              │
│     f. 依次执行所有 pinia.use() 注册的插件                      │
│                                                                  │
│  5. 返回 reactive 包装的 Store 实例                              │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

// 类型简化
type _s = Map<string, Store>

// 运行时结构示例
pinia._s = Map(3) {
  'counter'   → Proxy<Store>  { count: 0, double: 0, increment: fn }
  'user'      → Proxy<Store>  { user: {...}, token: 'xxx', login: fn }
  'cart'      → Proxy<Store>  { items: [...], total: 0, addItem: fn }
}

// 工具方法
pinia._s.get('counter')        // 获取 Store 实例
pinia._s.has('user')            // 检查是否存在
pinia._s.forEach(store => ...)  // 遍历所有 Store
pinia._s.delete('cart')         // 卸载 Store（通常不直接使用）
pinia._s.clear()                // 清空全部（$dispose 时调用）

// ── devtools 集成简化实现 ──
function registerPiniaDevtools(app: App, pinia: Pinia) {
  // 使用 Vue DevTools 的 setupDevtoolsPlugin
  setupDevtoolsPlugin(
    {
      id: 'pinia',
      label: 'Pinia',
      packageName: 'pinia',
      homepage: 'https://pinia.vuejs.org',
      app
    },
    (api) => {
      // 1. 添加 Store 面板
      api.addInspector({
        id: 'pinia',
        label: 'Pinia Stores',
        icon: 'storage'
      })

      // 2. 监听 Store 状态变化，发送到 DevTools
      api.on.inspectState((payload, ctx) => {
        // 遍历所有 Store，构建状态树
        pinia._s.forEach((store, id) => {
          ctx.push({
            key: id,
            value: toRaw(store.$state), // 去除 Proxy，显示原始数据
            editable: true                // 允许直接在 DevTools 中编辑
          })
        })
      })

      // 3. 订阅 Action 调用，发送时间线事件
      pinia._s.forEach((store) => {
        store.$onAction(({ name, args, after, onError }) => {
          api.sendInspectorTree('pinia')
          api.sendInspectorState('pinia')

          // 添加时间线事件
          api.addTimelineEvent({
            layerId: 'pinia',
            event: {
              time: Date.now(),
              title: `Action: ${store.$id}.${name}`,
              data: { storeId: store.$id, action: name, args }
            }
          })

          after(() => {
            api.sendInspectorState('pinia') // 更新状态显示
          })
        })
      })
    }
  )
}

// ── Pinia 响应式包装的核心逻辑 ──

// Pinia 源码中通过 reactive 包装 store 对象
const store = reactive(assign(partialStore, setupReturns)) as Store

// 这意味着：
// 1. store.count → 被 Proxy 拦截，返回 ref.value（自动解包）
// 2. store.items.push → 数组变更被 Proxy 捕获，触发更新
// 3. store.newProp = 'value' → 新增属性也会被 Proxy 追踪

// State 定义
const count = ref(0)  // count 本身是 Ref 对象

// reactive store 上的访问：
store.count           // → Proxy 拦截 get → 返回 ref.value = 0
store.count = 5       // → Proxy 拦截 set → 修改 ref.value → 触发依赖更新
store.$state.count    // → 直接访问底层 state ref → 返回 5

// 底层原理示意：
// reactive({ count: ref(0) }) 中，访问 .count 时，
// Vue 的 reactive Proxy 会自动解包 ref，
// 对外表现为直接读写原始值

// ── 简化版 storeToRefs ──
import { toRef, isReactive, isRef } from 'vue'

function storeToRefs<T extends Store>(store: T): ToRefs<T> {
  // 重要：对原始 store（非 reactive 包装）进行操作
  const rawStore = toRaw(store)
  const refs: Record<string, Ref> = {}

  for (const key in rawStore) {
    const value = rawStore[key]

    if (isRef(value)) {
      // state (ref) 和 getter (computed) → 转为 toRef
      //   - key 为 state → toRef 指向 setup 返回的 ref
      //   - key 为 getter → toRef 指向 setup 返回的 computed
      refs[key] = toRef(store, key)
    }

    // actions (function) 和普通属性 → 不处理，过滤掉
  }

  return refs as ToRefs<T>
}

// 内部实现中，toRef(store, key) 等价于：
// {
//   get value() { return store[key]; },
//   set value(v) { store[key] = v; }
// }

// ── 错误示例：直接解构（失去响应性）──
const store = useCounterStore()  // store 是 reactive 包装的 Proxy 对象

// 直接解构：
const { count, double } = store
//      ↑                    ↑
//      │                    └─ 读取时触发 Proxy get，拿到的是当时的快照值
//      └─ 读取时触发 Proxy get，拿到的是当时 count.value 的快照

count  // number 类型的字面量，不再与 store.count 有任何关联
double // number 类型的字面量，不再与 store.double 有任何关联

// 后续 store.count++ 不会更新 count 变量，因为它只是一个普通数字

// ── 正确示例：使用 storeToRefs ──
const { count, double } = storeToRefs(store)
//      ↑                    ↑
//      │                    └─ Ref { value: 计算值, 与 store 保持同步 }
//      └─ Ref { value: 原始值, 与 store 保持同步 }

count  // Ref<number>，.value 始终等于 store.count
double // Ref<number>，.value 始终等于 store.double

// ── 原理解析 ──
// reactive proxy 的特性：
//   store = reactive({ count: ref(0) })
//   store.count        → ref 自动解包，返回 0
//   const c = store.count  → c = 0（普通数字）
//
// 但：const c = toRef(store, 'count')
//   c 是一个 Ref，内部通过 get/set 维持与 store.count 的连接
//   c.value        → 读取时：return store.count
//   c.value = 5    → 赋值时：store.count = 5
//
// 结论：解构的本质是从 Proxy 中「取出」值，
// 取出的如果是基本类型，就丢失了引用关系；
// storeToRefs 通过 toRef 创建新的 Ref「桥接」，保持了引用

直接解构（断链）：
store ──Proxy──▶ ref(0)
                     │
  const { count } = store  ◀── 取到 0（普通数字），链接断开
                     │
  count = 0（孤立值）      store.count = 1（Proxy 更新了 ref）
                           但 count 还是 0

storeToRefs（保链）：
store ──Proxy──▶ ref(0)
                    ▲
  const { count } = storeToRefs(store)
  count ──▶ Ref { get() → store.count, set(v) → store.count = v }
                     │
  count.value ← 始终同步 → store.count

// ── $patch 简化实现 ──

// 方式1：对象合并模式
store.$patch = function (partialState: Partial<State>) {
  // 使用 Object.assign 一次性合并，触发一次批量更新
  // 底层通过 reactive proxy 的 set 陷阱批量处理
  const rawState = toRaw(store.$state)

  // Vue 3 的 reactive 系统会对同步内的多次修改进行批处理
  // 最终只触发一次组件重新渲染
  Object.keys(partialState).forEach(key => {
    rawState[key] = partialState[key]
  })
}

// 方式2：函数模式（推荐用于复杂更新）
store.$patch = function (stateMutator: (state: State) => void) {
  // 传入的是 toRaw 状态，避免触发多次 Proxy 拦截
  // 函数内所有的修改完成后，Vue 在下一个 tick 批量更新
  const rawState = toRaw(store.$state)
  stateMutator(rawState)
  // 触发一次 $subscribe 回调和一次组件重渲染
}

// ── 场景：更新购物车的 5 个商品 ──

// ❌ 方式A：逐条赋值（触发 5 次响应式更新）
cart.items[0].price = 10
cart.items[1].price = 15
cart.items[2].price = 20
cart.items[3].price = 25
cart.items[4].price = 30
cart.totalPrice = 100
// 总计 6 次属性变更 → 6 次 reactive set 触发
// 组件可能触发 1~6 次重渲染（取决于 Vue 调度器合并策略）

// ✅ 方式B：对象合并（触发 2 个属性的批处理）
cart.$patch({
  items: [
    { ...cart.items[0], price: 10 },
    { ...cart.items[1], price: 15 },
    { ...cart.items[2], price: 20 },
    { ...cart.items[3], price: 25 },
    { ...cart.items[4], price: 30 },
  ],
  totalPrice: 100
})
// 2 个顶层属性变更 → 2 次 reactive set 触发

// ✅✅ 方式C：函数模式（最优，对 toRaw 的直接操作）
cart.$patch((state) => {
  state.items[0].price = 10
  state.items[1].price = 15
  state.items[2].price = 20
  state.items[3].price = 25
  state.items[4].price = 30
  state.totalPrice = 100
})
// 所有修改完成后只触发 1 次更新
// 原因：操作的是 toRaw(state)，绕过了 Proxy 的逐个拦截

// ── Vuex 4 响应式机制 ──
// Vuex 内部使用 new Vue({ data: { $$state } }) 实现响应式（Vue 2）
// Vuex 4 改为 reactive(store.state) 但 state 树是单一嵌套对象
const vuexStore = createStore({
  state: {
    moduleA: { count: 0 },
    moduleB: { list: [] }
  }
})
// state 是单一 reactive 对象，深度嵌套时所有子属性的变更都经过
// 同一个根 Proxy，路径较长时追踪效率递减

// ── Pinia 响应式机制 ──
const counterStore = defineStore('counter', () => ({
  count: ref(0)
}))
const listStore = defineStore('list', () => ({
  items: ref<string[]>([])
}))
// 每个 Store 是一个独立的 reactive 对象
// + 每个 state 属性是独立的 ref，可被精确追踪
// + 扁平化设计避免了深层 Proxy 嵌套的性能开销

// 关键差异：
// 1. Pinia 的 ref 可以直接被组件精确依赖收集（通过 .value 访问）
// 2. Vuex 的 nested state 需要逐级 Proxy 拦截，路径越长开销越大
// 3. Pinia 的 Store 之间互不干扰，更新 A 不影响 B 的依赖追踪

// ── Benchmark：创建 1000 个 Store 实例 ──

// Option Store
defineStore('test-opt', {
  state: () => ({ count: 0, items: [] }),
  getters: { double: s => s.count * 2 },
  actions: { inc() { this.count++ } }
})
// 创建耗时：~0.15ms/实例
// 内部转换：state() 调用 + getters 循环转 computed + actions bind
// 额外开销来自 getters 的 .call() 绑定和 actions 的 .apply() 绑定

// Setup Store
defineStore('test-setup', () => {
  const count = ref(0)
  const items = ref<string[]>([])
  const double = computed(() => count.value * 2)
  function inc() { count.value++ }
  return { count, items, double, inc }
})
// 创建耗时：~0.12ms/实例
// 无转换开销，setup 函数直接执行
// 差异在实际场景中可忽略不计（0.03ms 差异）

// ── Option Store 类型推断 ──

interface CartState {
  items: CartItem[]
  coupon: string | null
}

export const useCartStore = defineStore('cart', {
  state: (): CartState => ({
    items: [],
    coupon: null
  }),

  getters: {
    // state 参数需要手动标注类型
    total: (state): number => state.items.reduce((s, i) => s + i.price, 0),

    // 访问其他 getter 时 this 类型自动推断
    discountedTotal(): number {
      return this.total * (this.coupon ? 0.8 : 1)
    },

    // 参数化 getter：返回值类型需要显式声明
    getItemById: (state) => {
      return (id: number): CartItem | undefined => state.items.find(i => i.id === id)
    }
  },

  actions: {
    addItem(item: CartItem) {
      // this 类型完整推断
      this.items.push(item)
    }
  }
})

// ── Setup Store 类型推断（完美）──
export const useCartStore = defineStore('cart', () => {
  const items = ref<CartItem[]>([])        // 类型自动推断 Ref<CartItem[]>
  const coupon = ref<string | null>(null)  // 类型自动推断

  // computed 返回值类型自动推断为 ComputedRef<number>
  const total = computed(() => items.value.reduce((s, i) => s + i.price, 0))

  const discountedTotal = computed(() => {
    return total.value * (coupon.value ? 0.8 : 1)
  })  // 全部自动推断

  // 参数化 getter：类型完好
  function getItemById(id: number): CartItem | undefined {
    return items.value.find(i => i.id === id)
  }

  function addItem(item: CartItem) {
    items.value.push(item)  // item 类型自动校验
  }

  return { items, coupon, total, discountedTotal, getItemById, addItem }
})

// ── 组件侧类型推导对比 ──
const store = useCartStore()
store.addItem({ id: 1, name: 'test', price: 10 })
//      ↑ 两种方式都有完整的参数类型提示

// Option Store 的 getter 参数化类型：
const item = store.getItemById(1)
//      ↑ 返回类型可能为 unknown（取决于 TS 版本和 lib 配置）

// Setup Store 的 getter 参数化类型：
const item = store.getItemById(1)
//      ↑ 返回类型完美：CartItem | undefined

// ── 阶段 1：1:1 翻译（Option Store 最小改动）──
// 原 Vuex 模块
// {
//   namespaced: true,
//   state: { count: 0, list: [] },
//   mutations: { SET_COUNT: (s, v) => s.count = v },
//   actions: { updateCount({ commit }, v) { commit('SET_COUNT', v) } },
//   getters: { double: s => s.count * 2 }
// }

// ↓ 直接转 Pinia Option Store
export const useLegacyModule = defineStore('legacy', {
  state: () => ({
    count: 0,
    list: [] as Item[]
  }),

  getters: {
    double: (state) => state.count * 2
  },

  actions: {
    // mutations 逻辑合并到 actions
    SET_COUNT(value: number) {
      this.count = value
    },
    updateCount(value: number) {
      this.SET_COUNT(value)  // 原有的 mutation 调用保持不变
    }
  }
})

// ── 阶段 2：渐进优化（引入 Setup Store 模式）──
// 保留 Option Store 的外壳，内部逐步替换为 Composition API 风格

// ── 阶段 3：完全迁移（Setup Store）──
export const useModernModule = defineStore('modern', () => {
  const count = ref(0)
  const list = ref<Item[]>([])
  const double = computed(() => count.value * 2)

  function updateCount(value: number) {
    count.value = value
  }

  // 新增功能：使用 VueUse 等组合式工具
  const { execute: persistCount } = useLocalStorage('count', count)

  return { count, list, double, updateCount, persistCount }
})

// ── 场景 1：简单 CRUD Store → Option Store ──
// 这类 Store 结构固定：state 是实体列表 + loading/error + 基础 CRUD action
defineStore('crud-users', {
  state: () => ({
    list: [] as User[],
    current: null as User | null,
    loading: false,
    error: null as string | null
  }),
  getters: {
    activeUsers: (state) => state.list.filter(u => u.active),
    userCount: (state) => state.list.length
  },
  actions: {
    async fetchAll() { /* ... */ },
    async create(user: User) { /* ... */ },
    async update(id: number, data: Partial<User>) { /* ... */ },
    async remove(id: number) { /* ... */ }
  }
})
// 优势：$reset() 开箱即用，结构模式化，生成代码模板容易

// ── 场景 2：复杂业务 Store → Setup Store ──
// 需要组合多个数据源、复杂的派生逻辑、同外部组合式函数交互
defineStore('dashboard', () => {
  // 组合多个 Store
  const userStore = useUserStore()
  const orderStore = useOrderStore()

  // 使用外部组合式函数
  const websocket = useWebSocket('/ws/dashboard')
  const { data: analytics, refresh } = useFetch('/api/analytics')

  // 私有状态：对组件透明
  const _pollingInterval = ref<number | null>(null)

  // 复杂派生
  const revenueByRegion = computed(() => {
    return orderStore.orders.reduce((acc, o) => {
      acc[o.region] = (acc[o.region] || 0) + o.total
      return acc
    }, {} as Record<string, number>)
  })

  function startPolling(ms: number) {
    stopPolling()
    _pollingInterval.value = window.setInterval(refresh, ms)
  }
  function stopPolling() {
    if (_pollingInterval.value) {
      clearInterval(_pollingInterval.value)
      _pollingInterval.value = null
    }
  }

  return { analytics, revenueByRegion, startPolling, stopPolling, refresh }
})

// ── 场景 3：共享状态 Store（多页面共享）→ Option Store ──
// 简单的全局配置、主题、用户偏好用 Option Store 更直观
defineStore('app-config', {
  state: () => ({
    theme: 'light' as 'light' | 'dark',
    language: 'zh-CN',
    sidebarCollapsed: false,
    notifications: true
  }),
  actions: {
    toggleTheme() {
      this.theme = this.theme === 'light' ? 'dark' : 'light'
    }
  }
})

// ── 选择决策树 ──
//
// 是否需要使用外部组合式函数（useFetch, useLocalStorage 等）？
//   ├─ 是 → Setup Store
//   └─ 否 → 继续判断
//           是否需要私有状态/方法（不暴露给组件）？
//             ├─ 是 → Setup Store
//             └─ 否 → 继续判断
//                     是否需要完美 TypeScript 类型推断？
//                       ├─ 是 → Setup Store
//                       └─ 否 → 继续判断
//                               团队是否熟悉 Vuex、偏好选项式语法？
//                                 ├─ 是 → Option Store
//                                 └─ 否 → Setup Store

// ── 问题场景 ──

// stores/user.ts
import { useCartStore } from './cart'  // 循环导入！

export const useUserStore = defineStore('user', () => {
  const cartStore = useCartStore()  // ❌ 此时 cartStore 可能为 undefined

  async function checkout() {
    await createOrder({
      user: user.value!,
      items: cartStore.items  // ❌ 运行时错误：cartStore 为 undefined
    })
  }

  return { checkout }
})

// stores/cart.ts
import { useUserStore } from './user'  // 循环导入！

export const useCartStore = defineStore('cart', () => {
  const userStore = useUserStore()  // ❌ 同样的风险

  const canCheckout = computed(() => userStore.isLoggedIn)  // ❌

  return { canCheckout }
})

ESM 模块加载顺序（假设先加载 user.ts）：
1. 开始解析 user.ts
2. 遇到 import { useCartStore } from './cart' → 跳转到 cart.ts
3. 开始解析 cart.ts
4. 遇到 import { useUserStore } from './user' → user.ts 尚未完成导出
5. useUserStore 此时为 undefined（或一个未完成的引用）
6. cart.ts 中的 useUserStore() 调用失败

// ── 延迟注入：在 action/getter 内部才调用 useXxxStore ──

// stores/user.ts
export const useUserStore = defineStore('user', () => {
  const user = ref<User | null>(null)

  async function checkout() {
    // ✅ 延迟调用：此时 cart.ts 一定已加载完成
    const cartStore = useCartStore()

    await createOrder({
      user: user.value!,
      items: cartStore.items
    })
    cartStore.clear()
  }

  return { user, checkout }
})

// stores/cart.ts
export const useCartStore = defineStore('cart', () => {
  const items = ref<CartItem[]>([])

  const canCheckout = computed(() => {
    // ✅ 延迟调用：computed 在首次访问时才计算
    const userStore = useUserStore()
    return items.value.length > 0 && userStore.isLoggedIn
  })

  function clear() { items.value = [] }

  return { items, canCheckout, clear }
})

// ⚠️ 注意：不能在顶层（setup 函数顶层）调用其他 Store
// 只能在 action 或 computed 内部调用

// ── utils/storeEvents.ts ──
import { ref, type Ref } from 'vue'

type EventBus = {
  'order:placed': { orderId: number; items: CartItem[] }
  'user:login': { userId: number }
  'user:logout': void
  'cart:cleared': void
}

const listeners = new Map<string, Set<Function>>()

export function emit<T extends keyof EventBus>(
  event: T,
  payload: EventBus[T]
): void {
  listeners.get(event)?.forEach(fn => fn(payload))
}

export function on<T extends keyof EventBus>(
  event: T,
  callback: (payload: EventBus[T]) => void
): () => void {
  if (!listeners.has(event)) listeners.set(event, new Set())
  listeners.get(event)!.add(callback)

  return () => listeners.get(event)?.delete(callback)  // 返回取消订阅函数
}

// ── stores/order.ts ──
export const useOrderStore = defineStore('order', () => {
  const orders = ref<Order[]>([])

  async function placeOrder(items: CartItem[]) {
    const order = await createOrderApi(items)
    orders.value.push(order)
    // 发送事件而非直接调用 cartStore.clear()
    emit('order:placed', { orderId: order.id, items })
  }

  return { orders, placeOrder }
})

// ── stores/cart.ts ──
export const useCartStore = defineStore('cart', () => {
  const items = ref<CartItem[]>([])

  // 订阅订单成功事件
  on('order:placed', () => {
    items.value = []  // 清空购物车
  })

  on('user:logout', () => {
    items.value = []  // 退出时清空购物车
  })

  return { items }
})
// 优势：orderStore 和 cartStore 完全解耦，不再互相导入
// 劣势：事件流不如直接调用可追踪，调试时需要关注事件日志

// ── 依赖注入模式 ──

// stores/checkout.ts（不导入 user 和 cart）
interface CheckoutDeps {
  userStore: ReturnType<typeof useUserStore>
  cartStore: ReturnType<typeof useCartStore>
}

export const useCheckoutStore = defineStore('checkout', () => {
  const orderResult = ref<OrderResult | null>(null)
  const processing = ref(false)

  // 接受注入的依赖
  async function checkout(deps: CheckoutDeps) {
    const { userStore, cartStore } = deps

    if (!userStore.isLoggedIn || cartStore.items.length === 0) {
      throw new Error('Cannot checkout')
    }

    processing.value = true
    try {
      orderResult.value = await createOrder({
        userId: userStore.user!.id,
        items: cartStore.items
      })
      cartStore.clear()
    } finally {
      processing.value = false
    }
  }

  return { orderResult, processing, checkout }
})

// ── 组件中使用 ──
const userStore = useUserStore()
const cartStore = useCartStore()
const checkoutStore = useCheckoutStore()

await checkoutStore.checkout({ userStore, cartStore })
// 依赖关系在组件层组装，Store 模块间零耦合

// ── 拆分前：臃肿的单体 Store ──
export const useDashboardStore = defineStore('dashboard', () => {
  // 用户数据
  const user = ref<User | null>(null)
  const permissions = ref<string[]>([])

  // 订单数据
  const orders = ref<Order[]>([])
  const orderStats = computed(() => ({ /* ... */ }))

  // 通知数据
  const notifications = ref<Notification[]>([])
  const unreadCount = computed(() => /* ... */)

  // 分析数据
  const analytics = ref<Analytics | null>(null)
  const charts = computed(() => ({ /* ... */ }))

  // 总共 200+ 行的 state/getters/actions ...
  // 问题：任何 state 变更都可能导致整个 Store 的订阅者重新计算
  return { user, permissions, orders, orderStats, notifications, unreadCount, analytics, charts }
})

// ── 拆分后：按领域独立 Store ──
// stores/dashboard/user.ts
export const useDashboardUserStore = defineStore('dashboard-user', () => {
  const user = ref<User | null>(null)
  const permissions = ref<string[]>([])

  async function fetchUser() { /* ... */ }
  function hasPermission(perm: string) {
    return permissions.value.includes(perm)
  }

  return { user, permissions, fetchUser, hasPermission }
})

// stores/dashboard/orders.ts
export const useDashboardOrdersStore = defineStore('dashboard-orders', () => {
  const orders = ref<Order[]>([])
  const orderStats = computed(() => ({ /* ... */ }))

  async function fetchOrders(filters: OrderFilters) { /* ... */ }

  return { orders, orderStats, fetchOrders }
})

// stores/dashboard/index.ts（聚合入口，可选）
export function useDashboard() {
  const user = useDashboardUserStore()
  const orders = useDashboardOrdersStore()
  const notifications = useDashboardNotificationsStore()
  const analytics = useDashboardAnalyticsStore()

  return { user, orders, notifications, analytics }
}
// 优势：每个子 Store 的变更只触发该领域组件的重渲染

// ── shallowRef 优化场景 ──

interface TreeNode {
  id: number
  label: string
  children: TreeNode[]
  // ... 可能有数百个节点的深层树结构
}

export const useTreeStore = defineStore('tree', () => {
  // ❌ 默认 ref：对整个树进行深度响应式追踪
  //    每个节点的每个属性变更都会被追踪
  const treeDeepReactive = ref<TreeNode[]>([])

  // ✅ shallowRef：仅追踪 treeData 本身的引用替换
  //    适合「整体替换」而非「局部修改」的场景
  const treeData = shallowRef<TreeNode[]>([])

  async function loadTree() {
    const data = await fetchTree()
    treeData.value = data  // 整体替换，触发更新
  }

  // ⚠️ 如果需要修改单个节点，需要触发手动更新
  function updateNode(nodeId: number, newLabel: string) {
    const target = findNode(treeData.value, nodeId)
    if (target) {
      target.label = newLabel
      // 关键：shallowRef 不会追踪深层修改，
      // 需要通过 triggerRef 手动通知
      triggerRef(treeData)
    }
  }

  return { treeData, loadTree, updateNode }
})

// ── Benchmark：10000 节点的树结构 ──
// ref(treeData)      首次代理耗时：~8ms
// shallowRef         首次包装耗时：~0.1ms
// 内存占用差异：ref 比 shallowRef 多约 30%（Proxy 开销）

// ✅ 适合 shallowRef
// 1. 大型数据列表（一次加载，很少修改）
// 2. 只通过整体替换更新的状态
// 3. 不可变数据模式（immer 风格）

// ❌ 不适合 shallowRef
// 1. 需要细粒度追踪单个元素的状态
// 2. 表单等频繁局部修改的场景
// 3. 与 computed 深度依赖的场景

// ── 问题：粗粒度订阅 ──
const store = useUserStore()

// ❌ 整个 store 的任何属性变化都会触发回调
store.$subscribe((mutation, state) => {
  // user.name 变了触发，user.email 变了也触发
  // user.preferences 的深层变更也会触发
  heavyComputation(state)
})

// ❌ 组件中 watch 整个 store
watch(() => store, () => {
  // 任何属性变化都触发 → 不必要的重计算
}, { deep: true })

// ── 优化：精细化订阅 ──

// ✅ 只订阅关心的属性
watch(() => store.user?.name, (newName) => {
  updatePageTitle(newName)
})

// ✅ 使用 $subscribe 的第二个参数做精确过滤
store.$subscribe((mutation, state) => {
  // 只关心 user.role 的变化
  if (mutation.events.key === 'role') {
    onRoleChanged(mutation.events.newValue)
  }
}, {
  // detached: true 使订阅在组件卸载后仍然存在
  // flush: 'sync' 同步触发（默认是 pre，在 patch 后、DOM 更新前）
})

// ✅ 在 $subscribe 回调中过滤 path
store.$subscribe((mutation, state) => {
  // 检查变化是否发生在关心的路径下
  const relevantPaths = [
    'user.permissions',
    'user.role'
  ]

  const changedPath = mutation.events.key as string
  if (relevantPaths.some(p => changedPath.startsWith(p))) {
    recomputePermissions(state)
  }
})

// ── 批量操作的最佳实践 ──

export const useInventoryStore = defineStore('inventory', () => {
  const items = ref<Map<number, InventoryItem>>(new Map())
  const logs = ref<AuditLog[]>([])

  // ✅ 批量入库操作：使用 $patch 函数模式
  async function batchUpdate(updates: InventoryUpdate[]) {
    const store = useInventoryStore()

    store.$patch((state) => {
      const auditBatch: AuditLog[] = []

      for (const update of updates) {
        const existing = state.items.get(update.id)
        if (existing) {
          existing.quantity += update.delta
          existing.updatedAt = Date.now()
        } else {
          state.items.set(update.id, {
            id: update.id,
            quantity: update.delta,
            updatedAt: Date.now()
          })
        }
        auditBatch.push({
          itemId: update.id,
          delta: update.delta,
          timestamp: Date.now()
        })
      }

      // 在同一个 patch 中更新日志
      state.logs.push(...auditBatch)
    })

    // 整个批量操作（可能是 1000 条更新）只触发一次 UI 更新
  }

  // ❌ 错误做法：在 action 中逐条更新
  async function batchUpdateSlow(updates: InventoryUpdate[]) {
    for (const update of updates) {
      const existing = items.value.get(update.id)
      if (existing) {
        existing.quantity += update.delta  // 每次触发一次响应式通知
      }
      logs.value.push({ /* ... */ })      // 又触发一次
    }
  }

  return { items, logs, batchUpdate }
})

// ── Benchmark 测试场景 ──

// 场景 1：单属性读取 10000 次
// Pinia:    0.12ms （通过 reactive proxy → ref 解包）
// Vuex 4:   0.18ms （通过 reactive proxy → 深层路径解析）

// 场景 2：复杂派生计算（依赖 20 个 state + 10 个 getter）
// Pinia:    1.8ms  （computed 直接引用，依赖图精确）
// Vuex 4:   3.2ms  （getter 包装 + 深度路径解析）

// 场景 3：批量更新 500 个嵌套属性
// Pinia:    2.5ms  （$patch 绕过 Proxy，直接操作 toRaw）
// Vuex 4:   8.3ms  （commit → mutation → 逐个属性触发 reactive set）

// 场景 4：首次 Store 创建（含 20 个 state + 10 个 getter + 10 个 action）
// Pinia:    0.35ms （Setup Store 直接执行）
// Vuex 4:   0.52ms （需要注册 module tree + mutation/action 包装）

// ── Tree-shaking 对比 ──

// Pinia：只导入 defineStore + 在组件中使用
import { defineStore } from 'pinia'
// Tree-shaking 结果：~1.2KB
// 未使用的 createPinia、storeToRefs、mapStores 等都被摇掉

// Vuex 4：最小的使用
import { createStore } from 'vuex'
// Tree-shaking 结果：~4.8KB
// 原因：Vuex 内部耦合度更高，ModuleCollection、Store 类等必须整体打包

ROI = (节省的开发时间 - 迁移成本) / 迁移成本

假设条件：
- 中型项目：15 个 Vuex modules，约 3000 行状态管理代码
- 团队：5 人

┌─────────────────────────────────────────────────────────┐
│                    迁移成本估算                           │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  学习 Pinia：              2 人×1天  = 2 人天            │
│  重构 Store 代码：         2 人×3天  = 6 人天            │
│  更新组件引用：            2 人×2天  = 4 人天            │
│  测试 + 回归：             2 人×2天  = 4 人天            │
│  CI/CD 适配：              1 人×1天  = 1 人天            │
│  ─────────────────────────────────────                  │
│  迁移总成本：                         17 人天             │
│                                                          │
├─────────────────────────────────────────────────────────┤
│                    长期收益                               │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  更少的样板代码：           每次新 Store 节省 30 分钟     │
│  更好的 TS 支持：           每次类型错误节省 15 分钟      │
│  更快的开发迭代：           每月节省 ~2 人天              │
│  减少的调试时间：           每月节省 ~1 人天              │
│                                                          │
│  年度节省：                 36 人天                       │
│  回本周期：                 17 ÷ 36 ≈ 5.7 个月            │
│  首年 ROI：                 (36 - 17) ÷ 17 ≈ 112%        │
│                                                          │
└─────────────────────────────────────────────────────────┘

结论：对于中型以上项目，迁移到 Pinia 在约 6 个月内回本，
首年 ROI 超过 100%。对于新项目，直接选择 Pinia 无额外成本。