ai-engineering-init 1.3.4 → 1.4.1

package/.codex/skills/store-pc/SKILL.md

@@ -1,118 +1,71 @@
 ---
 name: store-pc
 description: |
-  PC 端（plus-ui）状态管理与 Hooks 指南。包含 Pinia Store、Hooks 组合式函数的创建和使用规范。
+  前端状态管理指南。包含 Vuex Store 的创建和使用规范。
 
   触发场景：
-  - 在 PC 后台创建/使用 Store
-  - Pinia 状态管理
-  - 跨组件数据共享（PC端）
-  - 持久化存储（useStorage）
-  - 权限判断
-  - 字典数据管理
+  - 创建/使用 Vuex Store
+  - Vuex 状态管理
+  - 跨组件数据共享
+  - 全局状态管理
 
-  触发词：PC Store、Pinia、defineStore、useUserStore、useDictStore、PC状态管理、useStorage、持久化、状态管理
+  触发词：Vuex、store、mapState、mapActions、commit、dispatch、状态管理
 
-  适用目录：plus-ui/**
+  适用目录：/Users/xujiajun/Developer/frontProj/web/src/store/**
 ---
 
-# PC 端状态管理指南
+# 前端状态管理指南
 
-> **适用于**: `plus-ui/` 目录下的 PC 后台管理系统
+> **适用于**: 腾云智慧食堂管理系统前端项目（Vue 2.7.16 + Vuex 3.4.0）
+>
+> **Store 目录**: `/Users/xujiajun/Developer/frontProj/web/src/store/`
 
-## 自动导入说明
-
-以下内容**无需手动 import**（通过 unplugin-auto-import 自动导入）：
-
-```typescript
-// Vue APIs
-ref, reactive, computed, watch, watchEffect, watchPostEffect, watchSyncEffect
-onMounted, onUnmounted, onBeforeMount, onBeforeUnmount, onBeforeUpdate, onUpdated
-onActivated, onDeactivated, onErrorCaptured, onRenderTracked, onRenderTriggered
-onServerPrefetch
-nextTick, toRefs, toRef, unref, isRef, isReactive, isReadonly, isProxy
-provide, inject, defineProps, defineEmits, defineExpose, defineOptions, defineSlots
-withDefaults, useSlots, useAttrs, useCssModule, useCssVars
-shallowRef, shallowReactive, shallowReadonly, triggerRef, customRef, toRaw, markRaw
-effectScope, getCurrentScope, onScopeDispose
-
-// Pinia
-defineStore, storeToRefs, acceptHMRUpdate, createPinia, setActivePinia, getActivePinia
-mapStores, mapState, mapWritableState, mapActions
-
-// Vue Router
-useRouter, useRoute, useLink, onBeforeRouteLeave, onBeforeRouteUpdate
+---
 
-// @vueuse/core
-useStorage, useLocalStorage, useSessionStorage, useMouse, useWindowSize
-// ... 以及其他 @vueuse/core 导出的函数
+## 目录结构
 
-// Element Plus
-ElMessage, ElMessageBox, ElNotification, ElLoading
-// ... 以及其他 Element Plus 组件和函数
 ```
-
-**需要手动 import 的**：
-
-```typescript
-// Stores（需要手动导入）
-import { useUserStore } from '@/store/modules/user'
-import { useDictStore } from '@/store/modules/dict'
-import { usePermissionStore } from '@/store/modules/permission'
-import { useAppStore } from '@/store/modules/app'
-import { useSettingsStore } from '@/store/modules/settings'
-import { useTagsViewStore } from '@/store/modules/tagsView'
-import { useNoticeStore } from '@/store/modules/notice'
-
-// Hooks（需要手动导入）
-import useDialog from '@/hooks/useDialog'
-
-// 工具函数（需要手动导入）
-import { getToken, setToken, removeToken } from '@/utils/auth'
+src/store/
+├── index.js           # Store 入口（Vuex 初始化）
+├── getters.js         # 全局 getters
+└── modules/           # Store 模块（28个）
+    ├── user.js        # 用户状态（最核心）
+    ├── app.js         # 应用状态（语言/尺寸）
+    ├── permission.js  # 权限路由管理
+    ├── tagsView.js    # 标签页管理
+    ├── settings.js    # 系统设置
+    ├── marketing.js   # 营销状态
+    ├── order.js       # 订单状态
+    ├── stock.js       # 库存状态
+    ├── reportcenter.js # 报表状态
+    ├── account.js     # 账户状态
+    ├── purchase.js    # 采购状态
+    ├── chart.js       # 图表状态
+    ├── notice.js      # 通知状态
+    ├── upload.js      # 上传状态
+    ├── menudish.js    # 菜品状态
+    ├── supplyChain.js # 供应链状态
+    └── ...            # 其他业务模块
 ```
 
 ---
 
-## 已有 Store 清单
-
-| Store | 文件 | 用途 | 关键方法 |
-|-------|------|------|---------|
-| `useUserStore` | `store/modules/user.ts` | 用户认证、权限 | login, logout, getInfo, setAvatar |
-| `useDictStore` | `store/modules/dict.ts` | 字典数据缓存 | getDict, setDict, removeDict, cleanDict |
-| `usePermissionStore` | `store/modules/permission.ts` | 路由权限 | generateRoutes, setRoutes, setSidebarRouters |
-| `useAppStore` | `store/modules/app.ts` | 应用配置（侧边栏、语言、尺寸） | toggleSideBar, closeSideBar, changeLanguage, setSize |
-| `useSettingsStore` | `store/modules/settings.ts` | 布局设置 | setTitle |
-| `useTagsViewStore` | `store/modules/tagsView.ts` | 标签页管理 | addView, delView, delAllViews, delOthersViews |
-| `useNoticeStore` | `store/modules/notice.ts` | 通知消息 | addNotice, removeNotice, readAll, clearNotice |
-
----
-
-## Hooks 清单
-
-> Hooks 是可复用的组合式函数，封装了特定业务逻辑。
-
-### 已有 Hooks
-
-| Hook | 文件 | 用途 | 关键方法/属性 |
-|------|------|------|--------------|
-| `useDialog` | `hooks/useDialog.ts` | 弹窗控制 | visible, title, openDialog, closeDialog |
-
-### useDialog 使用示例
-
-```typescript
-import useDialog from '@/hooks/useDialog'
-
-// 在组件中使用
-const { visible, title, openDialog, closeDialog } = useDialog({ title: '编辑用户' })
-
-// 打开弹窗
-const handleEdit = () => {
-  openDialog()
-}
-
-// 关闭弹窗
-const handleClose = () => {
-  closeDialog()
+## 全局 Getters（getters.js）
+
+```javascript
+// 常用全局 getters（可直接用 mapGetters 访问）
+{
+  token,            // 登录 token
+  name,             // 用户名
+  userInfo,         // 完整用户信息对象
+  permissions,      // 权限列表
+  hasRoles,         // 是否已加载角色（用于路由守卫）
+  permission_routes, // 已生成的权限路由
+  adminMerchant,    // 是否为超级管理员商户
+  url,              // API base URL
+  language,         // 当前语言（zh/en）
+  size,             // Element UI 组件尺寸
+  areaOptions,      // 区域选项（来自 supplyChain）
 }
 ```
 
@@ -122,261 +75,199 @@ const handleClose = () => {
 
 ### 标准模板
 
-```typescript
-// store/modules/xxx.ts
-// ✅ defineStore、ref、computed 已自动导入，无需手动 import
+```javascript
+// src/store/modules/xxx.js
+import { getList, getDetail } from '@/api/xxx'
 
-export const useXxxStore = defineStore('xxx', () => {
-  // ========== 状态 ==========
-  const list = ref<XxxVo[]>([])
-  const loading = ref(false)
-  const current = ref<XxxVo | null>(null)
-
-  // ========== 计算属性 ==========
-  const count = computed(() => list.value.length)
-  const isEmpty = computed(() => list.value.length === 0)
-  const hasSelected = computed(() => current.value !== null)
+const state = {
+  list: [],
+  current: null,
+  loading: false,
+  total: 0
+}
 
-  // ========== 方法 ==========
+const mutations = {
+  SET_LIST: (state, list) => {
+    state.list = list
+  },
+  SET_CURRENT: (state, current) => {
+    state.current = current
+  },
+  SET_LOADING: (state, loading) => {
+    state.loading = loading
+  },
+  SET_TOTAL: (state, total) => {
+    state.total = total
+  }
+}
 
+const actions = {
   /**
    * 获取列表
    */
-  const fetchList = async (params?: XxxQuery) => {
-    loading.value = true
+  async fetchList({ commit }, params) {
+    commit('SET_LOADING', true)
     try {
-      const res = await pageXxxs(params)
-      list.value = res.data.records
-    } catch (error) {
-      console.error('获取列表失败:', error)
+      const res = await getList({
+        page: { current: params.current || 1, size: params.size || 20 },
+        object: params
+      })
+      commit('SET_LIST', res.records || [])
+      commit('SET_TOTAL', res.total || 0)
+      return res
     } finally {
-      loading.value = false
+      commit('SET_LOADING', false)
     }
-  }
+  },
 
   /**
-   * 设置当前选中项
+   * 获取详情
    */
-  const setCurrent = (item: XxxVo | null) => {
-    current.value = item
-  }
+  async fetchDetail({ commit }, id) {
+    const res = await getDetail({ id })
+    commit('SET_CURRENT', res)
+    return res
+  },
 
   /**
    * 重置状态
    */
-  const reset = () => {
-    list.value = []
-    current.value = null
-    loading.value = false
+  reset({ commit }) {
+    commit('SET_LIST', [])
+    commit('SET_CURRENT', null)
+    commit('SET_TOTAL', 0)
   }
+}
 
-  // ========== 返回 ==========
-  return {
-    // 状态
-    list,
-    loading,
-    current,
-    // 计算属性
-    count,
-    isEmpty,
-    hasSelected,
-    // 方法
-    fetchList,
-    setCurrent,
-    reset
-  }
-})
-```
-
----
-
-## 使用 Store
-
-### 基本用法
-
-```typescript
-import { useXxxStore } from '@/store/modules/xxx'
-
-const xxxStore = useXxxStore()
-
-// 访问状态（非响应式）
-console.log(xxxStore.list)
-console.log(xxxStore.count)
-
-// 调用方法
-await xxxStore.fetchList()
-xxxStore.setCurrent(item)
-xxxStore.reset()
-```
-
-### 响应式解构
-
-```typescript
-import { useXxxStore } from '@/store/modules/xxx'
-
-const xxxStore = useXxxStore()
-
-// ✅ 正确：使用 storeToRefs 解构状态
-const { list, loading, current } = storeToRefs(xxxStore)
-
-// ✅ 正确：方法直接解构（方法不需要响应式）
-const { fetchList, setCurrent, reset } = xxxStore
+const getters = {
+  list: state => state.list,
+  current: state => state.current,
+  loading: state => state.loading,
+  total: state => state.total
+}
 
-// ❌ 错误：直接解构状态会丢失响应式
-// const { list, loading } = xxxStore
+export default {
+  namespaced: true,
+  state,
+  mutations,
+  actions,
+  getters
+}
 ```
 
-### 在模板中使用
-
-```vue
-<template>
-  <div v-loading="xxxStore.loading">
-    <div v-for="item in xxxStore.list" :key="item.id">
-      {{ item.name }}
-    </div>
-    <div v-if="xxxStore.isEmpty">暂无数据</div>
-  </div>
-</template>
+### 在 index.js 中注册
 
-<script setup lang="ts">
-import { useXxxStore } from '@/store/modules/xxx'
+```javascript
+// src/store/index.js
+import xxx from './modules/xxx'
 
-const xxxStore = useXxxStore()
-
-onMounted(() => {
-  xxxStore.fetchList()
+export default new Vuex.Store({
+  modules: {
+    // ... 其他模块
+    xxx
+  }
 })
-</script>
 ```
 
 ---
 
-## 持久化存储
-
-> ⚠️ **重要**：本项目使用 `@vueuse/core` 的 `useStorage` 实现持久化存储，而不是 pinia-plugin-persist 插件。
-
-### useStorage 说明
-
-```typescript
-// useStorage 已自动导入，无需手动 import
-// 基于 localStorage
-const data = useStorage('key', defaultValue)
-
-// 基于 sessionStorage
-const data = useSessionStorage('key', defaultValue)
+## 使用 Store
 
-// 基于 localStorage（显式指定）
-const data = useLocalStorage('key', defaultValue)
+### 方式 1：直接访问
+
+```javascript
+export default {
+  computed: {
+    list() {
+      return this.$store.state.xxx.list
+    },
+    loading() {
+      return this.$store.state.xxx.loading
+    },
+    // 使用全局 getter
+    token() {
+      return this.$store.getters.token
+    },
+    userInfo() {
+      return this.$store.getters.userInfo
+    }
+  },
+  methods: {
+    getData() {
+      this.$store.dispatch('xxx/fetchList', this.queryParams)
+    }
+  }
+}
 ```
 
-### useStorage API
-
-```typescript
-// 设置值（自动保存到 localStorage）
-const token = useStorage('token', '')
-token.value = 'new-token'  // 自动保存
+### 方式 2：mapState / mapGetters / mapActions
 
-// 获取值
-console.log(token.value)
+```javascript
+import { mapState, mapGetters, mapActions, mapMutations } from 'vuex'
 
-// 删除值
-token.value = null
+export default {
+  computed: {
+    // 模块内 state
+    ...mapState('xxx', ['list', 'loading', 'total']),
 
-// 带类型的存储
-const user = useStorage<UserInfo>('user', null)
-user.value = { name: 'admin', age: 18 }
-```
+    // 全局 getters
+    ...mapGetters(['token', 'userInfo', 'permissions', 'adminMerchant'])
+  },
+  methods: {
+    ...mapActions('xxx', ['fetchList', 'fetchDetail', 'reset']),
 
-### 在 Store 中使用 useStorage
-
-```typescript
-// store/modules/app.ts 示例
-import { defineStore } from 'pinia'
-import { useStorage } from '@vueuse/core'
-
-export const useAppStore = defineStore('app', () => {
-  // ✅ 使用 useStorage 实现持久化
-  const sidebarStatus = useStorage('sidebarStatus', '1')
-  const size = useStorage<'large' | 'default' | 'small'>('size', 'default')
-  const language = useStorage('language', 'zh_CN')
-
-  // 状态会自动持久化到 localStorage
-  const sidebar = reactive({
-    opened: sidebarStatus.value ? !!+sidebarStatus.value : true,
-    withoutAnimation: false,
-    hide: false
-  })
-
-  const toggleSideBar = (withoutAnimation: boolean) => {
-    sidebar.opened = !sidebar.opened
-    sidebar.withoutAnimation = withoutAnimation
-    // ✅ 修改 sidebarStatus 会自动保存到 localStorage
-    sidebarStatus.value = sidebar.opened ? '1' : '0'
-  }
-
-  return {
-    sidebar,
-    size,
-    language,
-    toggleSideBar
+    async getData() {
+      await this.fetchList({ ...this.queryParams, ...this.page })
+    }
+  },
+  mounted() {
+    this.getData()
   }
-})
+}
 ```
 
-### Token 管理示例
+---
 
-```typescript
-// utils/auth.ts 示例
-import { useStorage } from '@vueuse/core'
+## 核心 Store 模块说明
 
-const TokenKey = 'Admin-Token'
-const tokenStorage = useStorage<null | string>(TokenKey, null)
+### user.js（用户状态）
 
-export const getToken = () => tokenStorage.value
+最重要的模块，包含：
+- `state.token` - 登录 token
+- `state.userInfo` - 完整用户信息（userId、roles、roleCode、merchantId 等）
+- `state.hasRoles` - 是否已加载角色信息
+- `state.adminMerchant` - 是否为超级管理员（`roleCode === 'ROLE_ADMIN'`）
+- `state.merchantList` - 商户列表（管理员可切换商户）
 
-export const setToken = (access_token: string) => (tokenStorage.value = access_token)
+```javascript
+// 在路由守卫中获取用户信息
+const userInfo = await store.dispatch('user/getInfo')
 
-export const removeToken = () => (tokenStorage.value = null)
+// 登出
+await store.dispatch('user/resetToken')
+localStorage.clear()
+locationHref()
 ```
 
-### 在 useUserStore 中使用
+### permission.js（权限路由）
 
-```typescript
-// store/modules/user.ts 示例
-import { defineStore } from 'pinia'
-import { getToken, setToken, removeToken } from '@/utils/auth'
+- 根据用户角色动态生成路由
+- `state.routes` - 完整路由表（用于菜单渲染）
+- `state.addRoutes` - 动态添加的路由
 
-export const useUserStore = defineStore('user', () => {
-  // ✅ token 通过 utils/auth.ts 中的 useStorage 持久化
-  const token = ref(getToken())
-  const roles = ref<Array<string>>([])
-  const permissions = ref<Array<string>>([])
-
-  const login = async (userInfo: LoginData): Promise<void> => {
-    const res = await loginApi(userInfo)
-    const data = res.data
-    setToken(data.access_token)  // ✅ 自动保存到 localStorage
-    token.value = data.access_token
-  }
-
-  const logout = async (): Promise<void> => {
-    await logoutApi()
-    token.value = ''
-    roles.value = []
-    permissions.value = []
-    removeToken()  // ✅ 自动从 localStorage 删除
-  }
-
-  return {
-    token,
-    roles,
-    permissions,
-    login,
-    logout
-  }
+```javascript
+// 在路由守卫中生成权限路由
+const accessRoutes = await store.dispatch('permission/generateRoutes')
+accessRoutes.forEach(route => {
+  router.addRoute(route)
 })
 ```
 
+### app.js（应用状态）
+
+- `state.language` - 当前语言（zh/en）
+- `state.size` - Element UI 组件尺寸
+
 ---
 
 ## 最佳实践
@@ -386,106 +277,90 @@ export const useUserStore = defineStore('user', () => {
 | 场景 | 是否使用 Store |
 |------|---------------|
 | 多个页面/组件共享的数据 | ✅ 使用 |
-| 用户登录状态、权限 | ✅ 使用 |
-| 全局配置、主题设置 | ✅ 使用 |
-| 字典数据缓存 | ✅ 使用 |
-| 页面内部状态 | ❌ 用 ref/reactive |
-| 组件内部状态 | ❌ 用 ref/reactive |
+| 用户登录状态、权限 | ✅ 使用（user 模块） |
+| 全局配置（语言、尺寸） | ✅ 使用（app 模块） |
+| 页面内部状态（表单数据）| ❌ 用 data |
 | 父子组件传值 | ❌ 用 props/emit |
-| 兄弟组件通信（简单） | ❌ 用 provide/inject |
-
-### 2. Store 命名规范
+| 兄弟组件通信（简单） | ❌ 用 eventBus |
 
-```typescript
-// ✅ 正确：use + 业务名 + Store
-export const useUserStore = defineStore('user', ...)
-export const useCartStore = defineStore('cart', ...)
-export const useDictStore = defineStore('dict', ...)
+### 2. 命名规范
 
-// ❌ 错误：不规范的命名
-export const userStore = defineStore('user', ...)
-export const useUser = defineStore('user', ...)
-```
-
-### 3. 避免循环依赖
+```javascript
+// ✅ 正确：Mutation 大写字母+下划线
+const mutations = {
+  SET_LIST: (state, list) => { state.list = list },
+  SET_LOADING: (state, v) => { state.loading = v }
+}
 
-```typescript
-// ❌ 避免 Store 之间循环引用
-// userStore.ts
-import { useOrderStore } from './order'  // orderStore 又引用 userStore
+// ✅ 正确：Action 小驼峰
+const actions = {
+  fetchList: async ({ commit }, params) => { },
+  fetchDetail: async ({ commit }, id) => { }
+}
 
-// ✅ 正确做法：在组件层协调，或使用事件
+// ✅ 正确：模块文件名小写，匹配业务名
+// store/modules/marketing.js
+// store/modules/order.js
 ```
 
-### 4. 重置 Store（登出时）
-
-```typescript
-// 在 useUserStore 中
-const logout = async () => {
-  // 重置所有相关 Store
-  const dictStore = useDictStore()
-  const permissionStore = usePermissionStore()
-
-  // 重置当前 Store
-  token.value = ''
-  roles.value = []
-  permissions.value = []
-  removeToken()
+### 3. 登出时重置 Store
 
-  // 重置其他 Store
-  dictStore.cleanDict()
-
-  // 跳转登录页
-  router.push('/login')
+```javascript
+// 在 user store 中
+const actions = {
+  async resetToken({ commit }) {
+    commit('SET_TOKEN', '')
+    commit('SET_HAS_ROLES', false)
+    removeToken()
+    removeTenant()
+  }
 }
+
+// 登出时（permission.js 路由守卫中）
+await store.dispatch('user/resetToken')
+localStorage.clear()
+locationHref()  // 使用全局 locationHref 跳转（不用 router.push）
 ```
 
-### 5. 使用 Setup Syntax
+### 4. 分页数据格式
 
-```typescript
-// ✅ 推荐：使用 Setup 语法（Composition API）
-export const useXxxStore = defineStore('xxx', () => {
-  const state = ref(0)
-  const increment = () => state.value++
-  return { state, increment }
-})
+```javascript
+// 后端返回的分页数据格式
+{
+  records: [],  // 数据列表（非 rows）
+  total: 100,
+  current: 1,
+  size: 20
+}
 
-// ❌ 不推荐：使用 Options API
-export const useXxxStore = defineStore('xxx', {
-  state: () => ({ count: 0 }),
-  actions: {
-    increment() { this.count++ }
-  }
-})
+// 请求分页参数格式
+{
+  page: { current: 1, size: 20 },
+  object: { ...queryParams }  // 查询条件
+}
 ```
 
 ---
 
 ## 参考文件
 
-### Stores
-
-- Store 目录：`plus-ui/src/store/modules/`
-- 用户 Store：`plus-ui/src/store/modules/user.ts`
-- 字典 Store：`plus-ui/src/store/modules/dict.ts`
-- 权限 Store：`plus-ui/src/store/modules/permission.ts`
-- 应用 Store：`plus-ui/src/store/modules/app.ts`
-- 设置 Store：`plus-ui/src/store/modules/settings.ts`
-- 标签页 Store：`plus-ui/src/store/modules/tagsView.ts`
-- 通知 Store：`plus-ui/src/store/modules/notice.ts`
+| Store | 路径 |
+|-------|------|
+| Store 入口 | `/Users/xujiajun/Developer/frontProj/web/src/store/index.js` |
+| 全局 Getters | `/Users/xujiajun/Developer/frontProj/web/src/store/getters.js` |
+| 用户 Store | `/Users/xujiajun/Developer/frontProj/web/src/store/modules/user.js` |
+| 权限 Store | `/Users/xujiajun/Developer/frontProj/web/src/store/modules/permission.js` |
+| 应用 Store | `/Users/xujiajun/Developer/frontProj/web/src/store/modules/app.js` |
+| 设置 Store | `/Users/xujiajun/Developer/frontProj/web/src/store/modules/settings.js` |
+| 标签页 Store | `/Users/xujiajun/Developer/frontProj/web/src/store/modules/tagsView.js` |
 
-### Hooks
-
-- Hooks 目录：`plus-ui/src/hooks/`
-- 弹窗控制：`plus-ui/src/hooks/useDialog.ts`
-
-### 工具类
-
-- Token 管理：`plus-ui/src/utils/auth.ts`（使用 useStorage）
-
-### 配置文件
-
-- 自动导入配置：`plus-ui/vite/plugins/auto-import.ts`
-- Vite 配置：`plus-ui/vite.config.ts`
 ---
 
+## 注意事项
+
+1. **本项目使用 Vuex 3.x**（非 Pinia），与 Vue 2 配套
+2. **Store 模块必须设置 `namespaced: true`**
+3. **异步操作放在 Actions 中**，同步操作放在 Mutations 中
+4. **分页数据用 `records`**，不是 `rows`（与 RuoYi 后端框架不同）
+5. **登出使用 `locationHref()`** 而非 `router.push('/login')`，目的是清除内存中的数据
+6. **`adminMerchant` 为 true 时**，用户是超级管理员（`roleCode === 'ROLE_ADMIN'`），可切换商户