roa2web-service-auto/.claude/rules/claude-learn-frontend.md

# Claude Learn: frontend
<!-- paths: src/**/*.vue, src/**/*.js, src/**/*.ts, src/**/*.css, vite.config.*, package.json -->

## P: Unified Vue SPA with Module Isolation via Error Boundaries
@2025-12-22 #vue #spa #error-boundary | inferred:med
Consolidate multiple Vue apps into a single SPA using lazy-loaded modules wrapped in error boundaries. Each module has its own layout component with ErrorBoundary wrapper to prevent crashes from propagating.
```vue
<template>
  <ErrorBoundary module-name="Rapoarte">
    <router-view />
  </ErrorBoundary>
</template>
```

## P: Dual API Proxy Pattern in Vite for Microservices
@2025-12-22 #vite #proxy #microservices | inferred:med
Configure Vite dev server to proxy multiple backend microservices under different paths. Allows unified frontend to communicate with separate backend services.
```javascript
proxy: {
  '/api/reports': { target: 'http://localhost:8001', changeOrigin: true },
  '/api/data-entry': { target: 'http://localhost:8003', changeOrigin: true }
}
```

## P: Pinia Store Factory Pattern for Shared Stores
@2025-12-22 #pinia #stores #factory-pattern | inferred:med
Create shared Pinia stores as factory functions that accept API service instances. Each module instantiates the shared stores with its own API service.
```javascript
export function createAuthStore(apiService) {
  return defineStore('auth', () => {
    const login = async (credentials) => await apiService.post('/auth/login', credentials)
    return { login, logout, isAuthenticated }
  })
}
```

## P: Module-Specific Shared Store Instances
@2025-12-22 #pinia #stores #module-isolation | inferred:med
Instantiate shared store factories in each module's dedicated file to ensure proper API service binding.
```javascript
import { createAuthStore } from '@shared/stores/auth'
import api from '@reports/services/api'
export const useAuthStore = createAuthStore(api)
```

## P: Vite Alias Strategy for Module Organization
@2025-12-22 #vite #aliases #architecture | inferred:med
Use Vite path aliases to create clear module boundaries: @shared for shared code, @reports and @data-entry for module-specific code.
```javascript
resolve: {
  alias: {
    '@shared': fileURLToPath(new URL('./src/shared', import.meta.url)),
    '@reports': fileURLToPath(new URL('./src/modules/reports', import.meta.url))
  }
}
```

## P: Vue Watcher for Auto-Loading Dependent Data
@2025-12-24 #vue #watch #reactive | inferred:med
Use Vue watch() to automatically trigger data loading when dependent selections change. Watch company selection changes to auto-load accounting periods.
```javascript
watch(
  () => companyStore.selectedCompany,
  async (newCompany) => {
    if (newCompany?.id_firma) await periodStore.loadPeriods(newCompany.id_firma)
  },
  { immediate: true }
)
```

## P: Axios Request Interceptor for JWT Token Injection
@2025-12-24 #axios #jwt #authentication | inferred:med
Add axios request interceptor to automatically inject JWT Bearer token from localStorage into all API requests.
```javascript
authApi.interceptors.request.use(config => {
  const token = localStorage.getItem('access_token')
  if (token) config.headers.Authorization = `Bearer ${token}`
  return config
})
```

## P: Pinia Store Factory with Lazy Instantiation
@2025-12-24 #pinia #stores #lazy-initialization | inferred:med
When store factories need to access other stores, use lazy instantiation with try-catch to avoid timing issues. Access stores inside functions, not at module level.
```javascript
const getStorageKey = () => {
  try {
    const authStore = useAuthStore();
    return `selected_period_${authStore.user?.username}`;
  } catch (e) { return null; }
};
```

## G: Import Path Hell: Default vs Named Exports
@2025-12-22 #javascript #imports #exports | inferred:med
**P**: Build failed with 'apiService is not exported' errors. Legacy code used `import { apiService }` but module uses `export default api`.
**S**: Change imports from `import { apiService }` to `import api`, then update all references.

## G: Pinia Store Factory Pattern Not Auto-Exported
@2025-12-22 #pinia #stores #factory-pattern | inferred:med
**P**: Build failed with 'useCompanyStore is not exported' because shared stores are factory functions, not direct exports.
**S**: Create module-specific sharedStores.js that instantiates factory functions with module's API service and exports store instances.

## G: Circular Reference in API Wrapper
@2025-12-22 #javascript #naming #scope | inferred:med
**P**: 'Identifier api has already been declared' - imported api and declared `const api = { ... }` wrapper with same name.
**S**: Rename import to apiClient: `import apiClient from 'api'`, then use in wrapper.

## G: CSS Import Paths Breaking Build in Unified Structure
@2025-12-22 #css #imports #build-errors | inferred:med
**P**: Build failed with 'Unable to resolve @import' - CSS import paths pointed to old shared/frontend location.
**S**: Comment problematic @imports or update paths to use @shared alias or correct relative paths.

## G: Module Component Utilities Not Copied During Migration
@2025-12-22 #migration #dependencies #file-structure | inferred:med
**P**: Build failed with 'Could not resolve ../utils/exportUtils' - utils/ and components/ directories weren't copied.
**S**: Copy entire utils/ and components/ directories from source apps. Supporting files are essential dependencies.

## G: Vite Build Transform Count is Progress Indicator
@2025-12-22 #vite #build #debugging | inferred:low
**P**: Hard to tell if build is making progress when fixing import issues.
**S**: Watch 'transforming... N modules transformed' count - it increases with each successful fix. Use as encouragement!

## G: Menu Structure Mismatch: Flat Array vs Nested Sections
@2025-12-24 #vue #data-structure #component-contract | inferred:med
**P**: Hamburger menu appeared empty - used .flatMap() but SlideMenu expected nested structure.
**S**: Remove .flatMap() and return nested structure directly: `[{title: 'Section', items: [...]}]`.

## G: TypeError: useAuthStore is not a function - Store Timing Issue
@2025-12-24 #pinia #stores #timing | inferred:high
**P**: Period store threw 'TypeError: useAuthStore is not a function' when calling useAuthStore() - timing issue.
**S**: Wrap store access in try-catch with lazy instantiation. Call inside function, not at module level. Return null if stores aren't ready.

## G: Missing Auth Token in API Requests Causes 500 Errors
@2025-12-24 #axios #jwt #authentication | inferred:high
**P**: Backend returned 500 - no Authorization header in requests even though JWT token existed in localStorage.
**S**: Add axios request interceptor to inject token AFTER creating axios instance but BEFORE making API calls.

## G: Period Auto-Load Never Triggered Despite Handler Exists
@2025-12-24 #vue #watch #reactive | inferred:high
**P**: Period dropdown stayed on placeholder - handleCompanyChanged() existed but periods never loaded.
**S**: Add Vue watch() on companyStore.selectedCompany with { immediate: true } to handle both initial load and changes.

## G: Mobile File Input Reset Causes Page Reload/Crash
@2026-01-10 #mobile #file-upload #async #chrome-android | explicit:high
**P**: On Chrome Mobile (Android/iOS), selecting multiple files in bulk upload caused page reload before "Process" button could be clicked. Files disappeared.
**C**: Race condition - `onFilesSelected` called async `handleFiles()` (which clones files with `arrayBuffer()`) but immediately reset `fileInput.value = ''` without waiting. On mobile browsers, resetting input invalidates File object references while `arrayBuffer()` is still reading them.
**S**: Make event handler async and await `handleFiles()` before resetting input:
```javascript
const onFilesSelected = async (event) => {
  const files = event.target?.files
  if (files?.length > 0) {
    await handleFiles(Array.from(files))  // Wait for cloning!
  }
  // Reset AFTER handleFiles completes
  if (fileInput.value) fileInput.value.value = ''
}
```
**Applied in**: `src/modules/data-entry/components/bulk/BulkUploadZone.vue`