v3-upsert-store

创建或更新 Pinia Store

根据用户提供的 Store 名称、State 字段和 Actions 描述，生成或更新 Pinia Store 文件。

本 Skill 定义的是项目默认 Store 模式，当用户的实际需求与本 Skill 约定冲突时，以用户需求为准。

输入要求

用户需提供：

1. Store 名称（如 counter、notification）— 用于文件名和命名
2. State 字段列表 — 每个字段需明确：
   • 字段名（英文，camelCase）
   • 类型（string / number / boolean / array / object / 自定义类型等）
   • 初始值
   • 是否需要持久化到 localStorage
3. Actions 描述 — 需要哪些操作（如 reset、toggle、increment、fetch 等）

如果用户信息不完整，主动询问补全后再生成。

操作模式

创建新 Store

当 src/pinia/stores/<store名>.ts 不存在时，生成完整的 Store 文件。

更新已有 Store

当文件已存在时，在已有代码中追加新的 State 字段和 Actions，保留原有代码不动。追加时：

• 新 State 声明插入到已有 State 声明之后
• 新 Actions 插入到已有 Actions 之后（如有 // #region 分组则放在对应区域）
• 更新 return 语句，追加新导出的字段和方法

生成文件

Store 文件

路径：src/pinia/stores/<store名>.ts

持久化相关（仅在用户指定持久化字段时生成）

• 在 src/common/constants/cache-key.ts 的 CacheKey 类中追加新的 Key
• 在 src/common/utils/local-storage.ts 中追加对应的 get/set 函数

代码规范

Store 结构

完整的 Store 文件结构如下（以一个带持久化和辅助函数的 Store 为例）：

import type { XxxType } from "@@/types/xxx"
import { getXxx, setXxx } from "@@/utils/local-storage"
import { pinia } from "@/pinia"

interface Sidebar {
  opened: boolean
  withoutAnimation: boolean
}

/** 辅助函数的用途描述 */
function helperFunction(param: string) {
  // ...
}

export const useXxxStore = defineStore("xxx", () => {
  // Token
  const token = ref<string>(getToken() || "")

  // 侧边栏状态
  const sidebar: Sidebar = reactive({
    opened: true,
    withoutAnimation: false
  })

  // 设置 Token
  const setToken = (value: string) => {
    token.value = value
  }

  // 切换侧边栏
  const toggleSidebar = (withoutAnimation: boolean) => {
    sidebar.opened = !sidebar.opened
    sidebar.withoutAnimation = withoutAnimation
  }

  return { token, sidebar, setToken, toggleSidebar }
})

/**
 * @description 在 SPA 应用中可用于在 pinia 实例被激活前使用 store
 * @description 在 SSR 应用中可用于在 setup 外使用 store
 */
export function useXxxStoreOutside() {
  return useXxxStore(pinia)
}

关键规则

1. 必须使用 Setup Store 语法（defineStore("id", () => { ... })），不使用 Options API
2. 必须导出 useXxxStoreOutside 函数，且 JSDoc 注释原样保留（见上方模板）
3. defineStore 第一个参数（Store ID）：单词用小写（如 "user"），多词用 kebab-case（如 "tags-view"）
4. State 类型标注：
   • ref 用泛型：ref<string>("")、ref<number>(0)、ref<string[]>([])
   • reactive 在变量上标注类型：const sidebar: Sidebar = reactive({...})
5. Actions 统一使用箭头函数：const xxx = (param: Type) => { ... }
6. 注释风格：
   • Store 内部的 State 和 Actions 用 // 单行注释，描述具体用途（如 // 切换侧边栏、// 设置 Token）
   • 不要使用 /** */ JSDoc 注释 Store 内部成员
   • 不要使用泛化的分区标题（如 // state、// actions），每条注释直接描述对应内容
   • 模块级辅助函数（Store 外部）使用 /** */ JSDoc 注释
7. // #region / // #endregion 仅在同一类操作有多组变体时使用（如 tags-view 的 add/del/delOthers/delAll），普通 Store 不需要
8. 自动导入：defineStore、ref、reactive、watch、watchEffect、computed 无需手动 import
9. Vue 类型导入是允许的：如 import type { Ref } from "vue"