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`

## P: Mobile Material Design Component Architecture
@2026-01-12 #mobile #material-design #vue #architecture | explicit:high
Unified mobile UI using shared MD3-inspired components. All mobile pages MUST use MobileTopBar for header and MobileBottomNav for persistent navigation. Components are in `src/shared/components/mobile/`.
```vue
<template>
  <div class="mobile-page">
    <MobileTopBar
      :title="pageTitle"
      :show-back="hasBackNavigation"
      :show-menu="!hasBackNavigation"
      :actions="headerActions"
      @back-click="goBack"
      @action-click="handleAction"
    />

    <main class="mobile-content">
      <!-- Page content with padding for fixed bars -->
    </main>

    <MobileBottomNav :items="navItems" />
  </div>
</template>

<script setup>
import MobileTopBar from '@shared/components/mobile/MobileTopBar.vue'
import MobileBottomNav from '@shared/components/mobile/MobileBottomNav.vue'
</script>

<style scoped>
.mobile-content {
  padding-top: 56px;    /* MobileTopBar height */
  padding-bottom: 56px; /* MobileBottomNav height */
}
</style>
```

## P: Bottom Sheet Filter Pattern
@2026-01-12 #mobile #material-design #filters #bottom-sheet | explicit:high
On mobile, filters MUST be placed in a BottomSheet component instead of inline. BottomSheet slides up from bottom with drag-to-close gesture. Use a filter icon in MobileTopBar actions to toggle.
```vue
<template>
  <MobileTopBar
    title="Lista"
    :actions="[{ icon: 'pi pi-filter', label: 'Filtre', active: hasActiveFilters }]"
    @action-click="handleAction"
  />

  <BottomSheet v-model="isFilterOpen">
    <div class="filter-content">
      <h3>Filtre</h3>
      <Dropdown v-model="selectedStatus" :options="statusOptions" />
      <Calendar v-model="dateRange" selectionMode="range" />
      <div class="filter-actions">
        <Button label="Resetează" severity="secondary" @click="resetFilters" />
        <Button label="Aplică" @click="applyFilters" />
      </div>
    </div>
  </BottomSheet>
</template>

<script setup>
import BottomSheet from '@shared/components/mobile/BottomSheet.vue'
</script>
```

## P: Mobile Selection Mode Flow
@2026-01-12 #mobile #material-design #selection #batch-actions | explicit:high
When items are selected on mobile, batch actions appear in MobileSelectionFooter (bottom), NOT in the header. The footer slides up when `selectedItems.length > 0`. Actions array defines available operations per context.
```vue
<template>
  <!-- List with selection -->
  <div v-for="item in items" :key="item.id" @click="toggleSelection(item)">
    <Checkbox v-model="selectedItems" :value="item.id" />
    {{ item.name }}
  </div>

  <!-- Selection footer - appears when items selected -->
  <MobileSelectionFooter
    :visible="selectedItems.length > 0 && isMobile"
    :actions="selectionActions"
  />
</template>

<script setup>
import MobileSelectionFooter from '@shared/components/mobile/MobileSelectionFooter.vue'

const selectionActions = [
  { label: 'Șterge', icon: 'pi pi-trash', severity: 'danger', handler: handleDelete },
  { label: 'Export', icon: 'pi pi-download', severity: 'secondary', handler: handleExport }
]
</script>
```

## G: Nu duplica delete button în header și footer pe mobil
@2026-01-12 #mobile #material-design #ux #selection | explicit:high
**P**: Butonul de ștergere apărea în două locuri pe mobil: în bulk-actions-bar (header tabel) ȘI în mobile-selection-bottom-bar (footer), creând confuzie UX.
**C**: Desktop și mobile foloseau același cod pentru bulk actions, dar pe mobil acțiunile trebuie să fie DOAR în footer pentru ergonomie touch.
**S**: Afișează bulk-actions-bar DOAR când `!isMobile`. Pe mobil, toate acțiunile de selecție apar exclusiv în MobileSelectionFooter:
```vue
<!-- Desktop: header actions -->
<div v-if="selectedItems.length > 0 && !isMobile" class="bulk-actions-bar">
  <Button icon="pi pi-trash" label="Șterge" @click="handleDelete" />
</div>

<!-- Mobile: footer actions (MobileSelectionFooter handles visibility) -->
<MobileSelectionFooter
  :visible="selectedItems.length > 0 && isMobile"
  :actions="mobileSelectionActions"
/>
```
**Applied in**: `src/modules/data-entry/views/ReceiptsListView.vue`