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

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

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

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

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

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