Template
251 lines
8.5 KiB
Markdown
251 lines
8.5 KiB
Markdown
---
|
||
name: v3-upsert-store
|
||
description: 创建或更新全局状态（Store）。当用户提到以下任何场景时都应触发：新建状态管理、新增 Pinia Store、给 Store 加字段。即使用户没有明确说 Store，只要意图是和状态管理器有关就应该使用此 Skill。使用时需提供 Store 名称、State 字段和 Actions 描述。
|
||
metadata:
|
||
author: pany
|
||
version: "2026.06.01"
|
||
---
|
||
|
||
# 创建或更新 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 为例）：
|
||
|
||
```ts
|
||
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"`
|
||
|
||
### 文件结构顺序
|
||
|
||
```
|
||
1. import type 语句（类型导入）
|
||
2. import 语句（运行时导入，Pinia 实例必须导入）
|
||
3. interface / type 声明（Store 需要的本地类型）
|
||
4. 模块级辅助函数（不需要响应式访问的纯函数，用 /** */ 注释）
|
||
5. export const useXxxStore = defineStore(...)
|
||
6. export function useXxxStoreOutside()
|
||
```
|
||
|
||
### 持久化模式
|
||
|
||
当字段需要持久化时，遵循项目已有模式：
|
||
|
||
**1. CacheKey 常量**（`src/common/constants/cache-key.ts`）：
|
||
|
||
```ts
|
||
static readonly XXX_DATA = `${SYSTEM_NAME}-xxx-data-key`
|
||
```
|
||
|
||
命名规则：大写下划线 + `-key` 后缀。
|
||
|
||
**2. localStorage 工具函数**（`src/common/utils/local-storage.ts`）：
|
||
|
||
简单字符串值：
|
||
```ts
|
||
// #region Xxx 描述
|
||
export function getXxx() {
|
||
return localStorage.getItem(CacheKey.XXX_DATA)
|
||
}
|
||
|
||
export function setXxx(value: string) {
|
||
localStorage.setItem(CacheKey.XXX_DATA, value)
|
||
}
|
||
// #endregion
|
||
```
|
||
|
||
对象/数组值：
|
||
```ts
|
||
// #region Xxx 描述
|
||
export function getXxx() {
|
||
const json = localStorage.getItem(CacheKey.XXX_DATA)
|
||
return json ? (JSON.parse(json) as XxxType) : null
|
||
}
|
||
|
||
export function setXxx(data: XxxType) {
|
||
localStorage.setItem(CacheKey.XXX_DATA, JSON.stringify(data))
|
||
}
|
||
// #endregion
|
||
```
|
||
|
||
**3. Store 中使用**：
|
||
|
||
```ts
|
||
import { getXxx, setXxx } from "@@/utils/local-storage"
|
||
|
||
// Xxx 数据
|
||
const data = ref<XxxType>(getXxx() ?? defaultValue)
|
||
|
||
// 监听变化并持久化
|
||
watch(data, (newVal) => {
|
||
setXxx(newVal)
|
||
})
|
||
```
|
||
|
||
当需要同时监听多个持久化字段时，用 `watchEffect` 代替多个 `watch`：
|
||
|
||
```ts
|
||
watchEffect(() => {
|
||
setVisitedViews(visitedViews.value)
|
||
setCachedViews(cachedViews.value)
|
||
})
|
||
```
|
||
|
||
### 类型定义
|
||
|
||
- 简单类型直接在 Store 文件中用 `interface` 或 `type` 声明（定义在 Store 函数之前）
|
||
- 需要被外部引用的类型加 `export`（如 `export type TagView = Partial<RouteLocationNormalizedGeneric>`）
|
||
- 复杂、共享类型抽离到 `types` 目录或就近放置
|
||
|
||
## 命名约定
|
||
|
||
Store 名为 `notification` 时：
|
||
|
||
| 位置 | 命名 |
|
||
|------|------|
|
||
| 文件 | `src/pinia/stores/notification.ts` |
|
||
| Store ID | `"notification"` |
|
||
| Composable | `useNotificationStore` |
|
||
| Outside | `useNotificationStoreOutside` |
|
||
| CacheKey（如需） | `NOTIFICATION_DATA` |
|
||
| localStorage 函数（如需） | `getNotificationData` / `setNotificationData` |
|
||
|
||
多词 Store 名使用 kebab-case 文件名和 Store ID（如 `user-preference` → `"user-preference"` → `useUserPreferenceStore`）。
|
||
|
||
## 导入规范
|
||
|
||
```ts
|
||
// 类型导入
|
||
import type { Ref } from "vue"
|
||
import type { RouteRecordRaw } from "vue-router"
|
||
|
||
// 运行时导入：常量和工具函数
|
||
import { SIDEBAR_CLOSED, SIDEBAR_OPENED } from "@@/constants/app-key"
|
||
import { getSidebarStatus, setSidebarStatus } from "@@/utils/local-storage"
|
||
|
||
// 运行时导入：Pinia 实例（必需）
|
||
import { pinia } from "@/pinia"
|
||
|
||
// 运行时导入：其他 Store（当需要跨 Store 交互时）
|
||
import { useSettingsStore } from "./settings"
|
||
```
|
||
|
||
注意导入顺序：类型导入在前，运行时导入在后；`@@` 路径在前，`@` 路径在后。
|
||
|
||
## 设计决策指引
|
||
|
||
**ref vs reactive** — 当 State 是一个有结构的对象且字段间关联紧密时用 `reactive`（如 sidebar 的 opened + withoutAnimation），否则每个独立状态用 `ref`。大多数情况下用 `ref`。
|
||
|
||
**watch vs watchEffect** — 监听单个字段变化时用 `watch`；监听多个字段且都需要持久化时用 `watchEffect`（自动追踪依赖，代码更简洁）。
|
||
|
||
**辅助函数放在 Store 内还是外** — 不依赖响应式状态的纯逻辑函数放在 Store 外部（如权限过滤、格式化），需要访问 Store 内 `ref` / `reactive` 的函数放在内部作为 Action。
|
||
|
||
**是否需要 Reset Action** — 如果 Store 管理的是临时状态（如表单数据、UI 状态），通常需要一个 Reset 方法恢复初始值。如果是用户身份等持久数据，通常不需要通用 Reset。
|
||
|
||
**是否需要 Outside 函数** — 始终生成。这是项目约定，确保在路由守卫、Axios 拦截器等 setup 外场景可用。
|