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

Claude Learn: frontend

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.

<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.

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.

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.

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.

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.

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.

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.

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:

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