symfonia-ai-tools 1.0.0

package/templates/packs/vue3/_ai/instructions/store.instructions.md

@@ -0,0 +1,504 @@
+---
+applyTo: "**/*.store.ts"
+---
+
+# Pinia Store Instructions
+
+## Core Pinia Store Principles
+
+### Architecture Rules
+- **Stores handle state management ONLY** - no business logic
+- **Use Composition API syntax** with `defineStore`
+- **Business logic goes in composables**, not stores
+- **Stores are reactive data containers** with actions for mutations
+- **Follow strict TypeScript typing** - never use `any`
+
+### Store Structure Template
+```typescript
+import { defineStore } from 'pinia'
+import { ref, computed } from 'vue'
+import type { IUser, IUserFilters, IUserState } from '@/types/user'
+
+export const useUserStore = defineStore('user', () => {
+  // 1. State (reactive refs)
+  const users = ref<IUser[]>([])
+  const loading = ref(false)
+  const error = ref<string | null>(null)
+  const filters = ref<IUserFilters>({
+    search: '',
+    category: null,
+    isActive: true
+  })
+
+  // 2. Getters (computed properties)
+  const filteredUsers = computed((): IUser[] => {
+    return users.value.filter(user => {
+      const matchesSearch = !filters.value.search ||
+        user.name.toLowerCase().includes(filters.value.search.toLowerCase())
+      const matchesCategory = !filters.value.category ||
+        user.categoryId === filters.value.category
+      const matchesActive = user.isActive === filters.value.isActive
+
+      return matchesSearch && matchesCategory && matchesActive
+    })
+  })
+
+  const totalUsers = computed((): number => users.value.length)
+
+  const activeUsersCount = computed((): number =>
+    users.value.filter(user => user.isActive).length
+  )
+
+  // 3. Actions (state mutations only)
+  const setUsers = (newUsers: IUser[]): void => {
+    users.value = newUsers
+  }
+
+  const addUser = (user: IUser): void => {
+    users.value.push(user)
+  }
+
+  const updateUser = (userId: string, updatedUser: Partial<IUser>): void => {
+    const index = users.value.findIndex(user => user.id === userId)
+    if (index !== -1) {
+      users.value[index] = { ...users.value[index], ...updatedUser }
+    }
+  }
+
+  const removeUser = (userId: string): void => {
+    const index = users.value.findIndex(user => user.id === userId)
+    if (index !== -1) {
+      users.value.splice(index, 1)
+    }
+  }
+
+  const setLoading = (isLoading: boolean): void => {
+    loading.value = isLoading
+  }
+
+  const setError = (errorMessage: string | null): void => {
+    error.value = errorMessage
+  }
+
+  const updateFilters = (newFilters: Partial<IUserFilters>): void => {
+    filters.value = { ...filters.value, ...newFilters }
+  }
+
+  const resetFilters = (): void => {
+    filters.value = {
+      search: '',
+      category: null,
+      isActive: true
+    }
+  }
+
+  const clearError = (): void => {
+    error.value = null
+  }
+
+  const resetStore = (): void => {
+    users.value = []
+    loading.value = false
+    error.value = null
+    resetFilters()
+  }
+
+  // 4. Return everything that should be exposed
+  return {
+    // State
+    users,
+    loading,
+    error,
+    filters,
+
+    // Getters
+    filteredUsers,
+    totalUsers,
+    activeUsersCount,
+
+    // Actions
+    setUsers,
+    addUser,
+    updateUser,
+    removeUser,
+    setLoading,
+    setError,
+    updateFilters,
+    resetFilters,
+    clearError,
+    resetStore
+  }
+})
+
+// 5. Export type for store usage in composables
+export type UserStore = ReturnType<typeof useUserStore>
+```
+
+## Mandatory Requirements
+
+### 1. TypeScript Interfaces
+- **ALL state properties must be typed** with proper interfaces
+- **Prefix interfaces with `I`** (e.g., `IUserState`, `IUserFilters`)
+- **Export store type** for use in composables: `export type UserStore = ReturnType<typeof useUserStore>`
+- **NEVER use `any` type** - strict typing required
+
+### 2. State Management Rules
+- **Only reactive data storage** - no business logic in stores
+- **Use `ref()` for state** and `computed()` for derived state
+- **Actions only mutate state** - no API calls or complex logic
+- **Clear separation**: state -> getters -> actions
+
+### 3. Naming Conventions
+- **Store names**: `use[Entity]Store` (e.g., `useUserStore`, `useProductStore`)
+- **File names**: `[entity].store.ts` (e.g., `user.store.ts`, `product.store.ts`)
+- **State properties**: descriptive, camelCase
+- **Actions**: verb-based (e.g., `setUsers`, `addUser`, `updateUser`)
+
+### 4. Store Organization
+- **Module-specific stores**: `{{MODULE_PATH}}/stores/`
+- **Global stores**: `/src/stores/`
+- **One entity per store** - avoid mega-stores
+
+## Store Development Guidelines
+
+### State Definition Best Practices
+```typescript
+// Good: Proper state typing and initialization
+const users = ref<IUser[]>([])
+const currentUser = ref<IUser | null>(null)
+const loading = ref<boolean>(false)
+const error = ref<string | null>(null)
+const pagination = ref<IPagination>({
+  page: 1,
+  limit: 20,
+  total: 0
+})
+
+// Bad: No typing, unclear initialization
+const data = ref()
+const isLoading = ref()
+const err = ref()
+```
+
+### Getters (Computed Properties)
+```typescript
+// Good: Clear, typed computed properties
+const filteredUsers = computed((): IUser[] => {
+  return users.value.filter(user =>
+    user.name.toLowerCase().includes(searchTerm.value.toLowerCase())
+  )
+})
+
+const hasUsers = computed((): boolean => users.value.length > 0)
+
+const usersByCategory = computed((): Record<string, IUser[]> => {
+  return users.value.reduce((acc, user) => {
+    const category = user.category || 'unassigned'
+    if (!acc[category]) acc[category] = []
+    acc[category].push(user)
+    return acc
+  }, {} as Record<string, IUser[]>)
+})
+```
+
+### Actions Best Practices
+```typescript
+// Good: Simple state mutations
+const setUsers = (newUsers: IUser[]): void => {
+  users.value = newUsers
+}
+
+const updateUserStatus = (userId: string, isActive: boolean): void => {
+  const user = users.value.find(u => u.id === userId)
+  if (user) {
+    user.isActive = isActive
+  }
+}
+
+// Good: Batch operations
+const updateMultipleUsers = (updates: Array<{ id: string; data: Partial<IUser> }>): void => {
+  updates.forEach(({ id, data }) => {
+    const index = users.value.findIndex(user => user.id === id)
+    if (index !== -1) {
+      users.value[index] = { ...users.value[index], ...data }
+    }
+  })
+}
+```
+
+### Error and Loading State Management
+```typescript
+// Good: Consistent error/loading patterns
+const setLoading = (isLoading: boolean): void => {
+  loading.value = isLoading
+}
+
+const setError = (errorMessage: string | null): void => {
+  error.value = errorMessage
+  if (errorMessage) {
+    loading.value = false
+  }
+}
+
+const clearError = (): void => {
+  error.value = null
+}
+
+// Good: Reset functionality
+const resetStore = (): void => {
+  users.value = []
+  loading.value = false
+  error.value = null
+  currentUser.value = null
+}
+```
+
+## What NOT to Do in Stores
+
+### Never Do This
+```typescript
+// BAD: Business logic in stores
+const fetchUsers = async (): Promise<void> => {
+  try {
+    loading.value = true
+    const response = await api.get('/users')
+    users.value = response.data
+  } catch (error) {
+    handleError(error)
+  } finally {
+    loading.value = false
+  }
+}
+
+// BAD: Complex business calculations
+const calculateUserMetrics = (): void => {
+  // Complex business logic here
+}
+
+// BAD: Direct API calls
+const saveUser = async (user: IUser): Promise<void> => {
+  const response = await userService.save(user)
+  // ...
+}
+
+// BAD: Using any type
+const data = ref<any>([])
+
+// BAD: Mega-store with multiple entities
+const useAppStore = defineStore('app', () => {
+  const users = ref([])
+  const products = ref([])
+  const orders = ref([])
+  // Too many responsibilities
+})
+```
+
+### Always Do This
+```typescript
+// GOOD: Simple state mutations only
+const setUsers = (newUsers: IUser[]): void => {
+  users.value = newUsers
+}
+
+const updateUser = (userId: string, userData: Partial<IUser>): void => {
+  const index = users.value.findIndex(user => user.id === userId)
+  if (index !== -1) {
+    users.value[index] = { ...users.value[index], ...userData }
+  }
+}
+
+// GOOD: Proper typing
+const users = ref<IUser[]>([])
+const loading = ref<boolean>(false)
+
+// GOOD: Single responsibility
+export const useUserStore = defineStore('user', () => {
+  // Only user-related state and mutations
+})
+```
+
+## Store Integration Patterns
+
+### Using Stores in Composables
+```typescript
+// {{MODULE_PATH}}/composables/useUserManagement.ts
+import { useUserStore } from '{{MODULE_PATH}}/stores/user.store'
+import { userService } from '{{MODULE_PATH}}/services/user.service'
+
+export function useUserManagement() {
+  const userStore = useUserStore()
+
+  const fetchUsers = async (): Promise<void> => {
+    try {
+      userStore.setLoading(true)
+      userStore.clearError()
+
+      const users = await userService.getUsers()
+      userStore.setUsers(users)
+    } catch (error) {
+      userStore.setError('Failed to fetch users')
+      printError(error)
+    } finally {
+      userStore.setLoading(false)
+    }
+  }
+
+  return {
+    // Expose store state
+    users: userStore.users,
+    loading: userStore.loading,
+    error: userStore.error,
+
+    // Expose business logic
+    fetchUsers
+  }
+}
+```
+
+### Store Communication Patterns
+```typescript
+// Good: Store-to-store communication through composables
+export function useUserCategorySync() {
+  const userStore = useUserStore()
+  const categoryStore = useCategoryStore()
+
+  const syncUserCategories = (): void => {
+    const categoryIds = userStore.users.map(user => user.categoryId)
+    const uniqueCategoryIds = [...new Set(categoryIds)]
+    categoryStore.setActiveCategories(uniqueCategoryIds)
+  }
+
+  return { syncUserCategories }
+}
+```
+
+## Testing Store Requirements
+
+### Store Unit Testing with VITEST
+```typescript
+// user.store.test.ts
+import { describe, it, expect, beforeEach } from 'vitest'
+import { setActivePinia, createPinia } from 'pinia'
+import { useUserStore } from './user.store'
+
+describe('User Store', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+  })
+
+  it('should initialize with empty state', () => {
+    const store = useUserStore()
+
+    expect(store.users).toEqual([])
+    expect(store.loading).toBe(false)
+    expect(store.error).toBe(null)
+  })
+
+  it('should set users correctly', () => {
+    const store = useUserStore()
+    const mockUsers = [
+      { id: '1', name: 'John Doe', isActive: true }
+    ]
+
+    store.setUsers(mockUsers)
+
+    expect(store.users).toEqual(mockUsers)
+    expect(store.totalUsers).toBe(1)
+  })
+
+  it('should filter users correctly', () => {
+    const store = useUserStore()
+    const mockUsers = [
+      { id: '1', name: 'John Doe', isActive: true },
+      { id: '2', name: 'Jane Smith', isActive: false }
+    ]
+
+    store.setUsers(mockUsers)
+    store.updateFilters({ isActive: true })
+
+    expect(store.filteredUsers).toHaveLength(1)
+    expect(store.filteredUsers[0].name).toBe('John Doe')
+  })
+})
+```
+
+## Performance Considerations
+
+### Store Optimization
+```typescript
+// Good: Efficient state updates
+const updateUsersBatch = (updates: IUserUpdate[]): void => {
+  // Batch updates to minimize reactivity triggers
+  const updatedUsers = [...users.value]
+
+  updates.forEach(({ id, data }) => {
+    const index = updatedUsers.findIndex(user => user.id === id)
+    if (index !== -1) {
+      updatedUsers[index] = { ...updatedUsers[index], ...data }
+    }
+  })
+
+  users.value = updatedUsers
+}
+
+// Good: Memoized complex getters
+const expensiveComputation = computed(() => {
+  // Use shallowRef for large datasets if needed
+  return users.value.reduce((acc, user) => {
+    // Complex calculation
+    return acc
+  }, {})
+})
+```
+
+## File Organization Standards
+
+### Store File Structure
+```
+src/
+├── stores/                 # Global stores
+│   ├── index.ts           # Store exports
+│   ├── auth.store.ts      # Authentication store
+│   └── app.store.ts       # Application-wide state
+└── modules/
+    └── user/
+        └── stores/        # Module-specific stores
+            └── user.store.ts
+```
+
+### Store Index File
+```typescript
+// /src/stores/index.ts
+export { useAuthStore } from './auth.store'
+export { useAppStore } from './app.store'
+
+// Module stores
+export { useUserStore } from '{{MODULE_PATH}}/stores/user.store'
+export { useProductStore } from '{{MODULE_PATH}}/stores/product.store'
+```
+
+## Store Persistence
+
+### Local Storage Integration
+```typescript
+// Good: Persistence through composables, not stores
+export function useUserStorePersistence() {
+  const userStore = useUserStore()
+
+  const saveToLocalStorage = (): void => {
+    localStorage.setItem('userFilters', JSON.stringify(userStore.filters))
+  }
+
+  const loadFromLocalStorage = (): void => {
+    const saved = localStorage.getItem('userFilters')
+    if (saved) {
+      const filters = JSON.parse(saved)
+      userStore.updateFilters(filters)
+    }
+  }
+
+  return { saveToLocalStorage, loadFromLocalStorage }
+}
+```
+
+Remember: Pinia stores are reactive data containers. Keep them simple, focused, and free of business logic. Use composables to orchestrate store operations and handle complex business requirements.