siesa-agents 2.1.45 → 2.1.47

package/bmad/bmm/workflows/3-solutioning/create-architecture/data/company-standards/frontend-standards.md

@@ -1,56 +1,410 @@
 # Frontend Development Standards
 
-## Architecture Principles
-
-### Clean Architecture Implementation
-- **Domain Layer**: Business entities, value objects, and business rules only
-- **Application Layer**: Use cases, custom hooks, and state management
-- **Infrastructure Layer**: API clients, repositories implementations, external service adapters
-- **Presentation Layer**: React components, pages, and UI logic only
-
-### Dependency Rules
-- Inner layers must not know about outer layers
-- Dependencies point inward (from outer to inner layers)
-- Use dependency inversion for external concerns
-
-## Technology Stack Standards
-
-### Core Technologies
-- **Next.js**: 14+ with App Router and TypeScript
-- **React**: 18+ with functional components and hooks (via Next.js)
-- **TypeScript**: Strict mode enabled, no `any` types
-- **TailwindCSS**: Utility-first CSS framework
-- **Shadcn/ui + Radix UI**: Component library foundation
-
-### Framework Selection Rules
-- **Default**: Always use Next.js 16+ with App Router
-- **Exception**: Only use pure React + Vite when user specifically requests offline-first functionality
-- **Reasoning**: Next.js provides better DX, built-in optimization, and easier deployment while maintaining PWA capabilities
-
-### State Management
-- **Zustand**: Primary state management solution
-- Feature-based stores following DDD patterns
-- Global state only for truly global concerns
-- Local state for component-specific needs
-
-### Development Tools
-- **Next.js**: Built-in build system and development server
-- **Vitest**: Unit and integration testing (configured with Next.js)
-- **React Testing Library**: Component testing
-- **MSW**: API mocking for tests
-- **ESLint + Prettier**: Code quality and formatting (Next.js config)
-
-## Component Strategy
-- **Always First**: Check siesa-ui-kit before creating any component
-- **If not in siesa-ui-kit**: Ask user:
-  [1] Use shadcn directly
-  [2] Create custom for siesa-ui-kit (requires MR to Platform team)
-- **Shadcn Fallback**: Only use MCP Shadcn registry when user chooses option [1]
-- **Error Reduction**: 90% fewer bugs using existing components vs manual creation
-
-## Component Standards
-
-### Component Structure
+## Resumen
+
+Este documento define los estándares de desarrollo frontend para aplicaciones empresariales usando **Vite** como bundler, **TanStack Router** para enrutamiento type-safe, **Zustand** para estado global, y **Clean Architecture** con estructura modular preparada para microfrontends.
+
+---
+
+## Tabla de Contenidos
+
+1. [Principios de Arquitectura](#1-principios-de-arquitectura)
+2. [Stack Tecnológico](#2-stack-tecnológico)
+3. [Convenciones de Routing](#3-convenciones-de-routing)
+4. [Organización de Archivos](#4-organización-de-archivos)
+5. [Estándares de Componentes](#5-estándares-de-componentes)
+6. [Patrones de Estado](#6-patrones-de-estado)
+7. [Estándares de Testing](#7-estándares-de-testing)
+8. [Accesibilidad](#8-accesibilidad)
+9. [Rendimiento](#9-rendimiento)
+10. [Seguridad](#10-seguridad)
+11. [Manejo de Errores](#11-manejo-de-errores)
+12. [Progressive Web App](#12-progressive-web-app)
+13. [Estándares de Idioma](#13-estándares-de-idioma)
+14. [Consideraciones Generales](#14-consideraciones-generales)
+15. [Configuración Base](#15-configuración-base)
+16. [Checklist de Implementación](#16-checklist-de-implementación)
+
+---
+
+## 1. Principios de Arquitectura
+
+### 1.1 Implementación de Clean Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    PRESENTATION LAYER                           │
+│         React components, pages, UI logic, routes               │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    APPLICATION LAYER                            │
+│         Use cases, custom hooks, Zustand stores                 │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                   INFRASTRUCTURE LAYER                          │
+│      API clients, repositories impl, external adapters          │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                      DOMAIN LAYER                               │
+│       Business entities, value objects, business rules          │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+| Capa | Responsabilidad | Contenido |
+|------|-----------------|-----------|
+| **Domain** | Reglas de negocio puras | Entities, value objects, interfaces de repositorios |
+| **Application** | Orquestación de casos de uso | Use cases, hooks, stores Zustand |
+| **Infrastructure** | Implementaciones externas | API clients, repositorios concretos, adapters |
+| **Presentation** | Interfaz de usuario | Componentes React, páginas, estilos |
+
+### 1.2 Reglas de Dependencia
+
+- Las capas internas **NO deben conocer** las capas externas
+- Las dependencias apuntan hacia adentro (de externo a interno)
+- Usar inversión de dependencias para concerns externos
+- Domain layer no importa nada de otras capas
+
+---
+
+## 2. Stack Tecnológico
+
+### 2.1 Tecnologías Core
+
+| Categoría | Tecnología | Versión | Notas |
+|-----------|------------|---------|-------|
+| **Bundler** | Vite | 5+ | Build tool y dev server |
+| **Framework** | React | 18+ | Functional components y hooks |
+| **Router** | TanStack Router | 1+ | File-based routing con type-safety |
+| **Lenguaje** | TypeScript | 5+ | Strict mode, sin `any` |
+| **Estilos** | TailwindCSS | 4+ | Utility-first CSS |
+| **Componentes** | shadcn/ui + Radix UI | - | Base de componentes |
+| **Estado** | Zustand | 4+ | Estado global por feature |
+| **Data Fetching** | TanStack Query | 5+ | Cache y sincronización |
+
+### 2.2 Reglas de Selección de Framework
+
+| Escenario | Framework | Razón |
+|-----------|-----------|-------|
+| **Default** | Vite + TanStack Router | Mejor DX, type-safety, preparado para microfrontends |
+| **Microfrontends** | Vite + Module Federation | Arquitectura distribuida |
+
+### 2.3 Herramientas de Desarrollo
+
+| Herramienta | Propósito |
+|-------------|-----------|
+| **Vite** | Build system y dev server |
+| **Vitest** | Unit e integration testing |
+| **React Testing Library** | Component testing |
+| **MSW** | API mocking para tests |
+| **ESLint + Prettier** | Code quality y formatting |
+| **TypeScript** | Type checking |
+
+---
+
+## 3. Convenciones de Routing
+
+TanStack Router usa prefijos especiales en nombres de archivo para definir comportamientos.
+
+### 3.1 Prefijo `_` (Underscore) - Pathless Layout Routes
+
+**Propósito:** Agrupar rutas bajo un layout compartido **SIN agregar segmentos a la URL**.
+
+#### ❌ El Problema (sin `_`)
+
+```
+routes/
+├── __root.tsx
+├── auth/
+│   └── login.tsx          → URL: /auth/login ❌
+├── app/
+│   ├── dashboard.tsx      → URL: /app/dashboard ❌
+│   └── orders.tsx         → URL: /app/orders ❌
+```
+
+**Resultado:** Las URLs incluyen el nombre de la carpeta, lo cual es indeseable.
+
+#### ✅ La Solución (con `_`)
+
+```
+routes/
+├── __root.tsx
+├── _auth.tsx              → NO agrega nada a la URL (solo layout)
+├── _auth/
+│   └── login.tsx          → URL: /login ✅
+│
+├── _app.tsx               → NO agrega nada a la URL (solo layout)
+├── _app/
+│   ├── dashboard.tsx      → URL: /dashboard ✅
+│   └── orders.tsx         → URL: /orders ✅
+```
+
+#### Ejemplo de Implementación
+
+```typescript
+// routes/_app.tsx - Layout protegido
+import { createFileRoute, Outlet, redirect } from '@tanstack/react-router';
+import { Sidebar, TopNav } from '@/shared/components/layout';
+import { useAuthStore } from '@/modules/users/authentication/login/application/store';
+
+export const Route = createFileRoute('/_app')({
+  beforeLoad: () => {
+    const { isAuthenticated } = useAuthStore.getState();
+    if (!isAuthenticated) {
+      throw redirect({ to: '/login' });
+    }
+  },
+  component: AppLayout,
+});
+
+function AppLayout() {
+  return (
+    <div className="flex h-screen">
+      <Sidebar />
+      <div className="flex-1 flex flex-col">
+        <TopNav />
+        <main className="flex-1 overflow-auto p-6">
+          <Outlet />
+        </main>
+      </div>
+    </div>
+  );
+}
+```
+
+### 3.2 Prefijo `.` (Punto) - Flat Routing
+
+**Propósito:** Definir rutas anidadas **sin crear carpetas**.
+
+```
+routes/
+├── orders.tsx              → /orders (layout)
+├── orders.index.tsx        → /orders
+├── orders.$orderId.tsx     → /orders/:orderId
+├── orders.$orderId.edit.tsx → /orders/:orderId/edit
+```
+
+#### ¿Cuándo usar `.` vs Carpetas?
+
+| Escenario | Recomendación |
+|-----------|---------------|
+| Pocas rutas anidadas (2-3) | Flat con `.` |
+| Muchas rutas anidadas (4+) | Carpetas |
+| Rutas con componentes colocados | Carpetas con `-components/` |
+
+### 3.3 Prefijo `-` (Guión) - Ignorar Archivos
+
+**Propósito:** Excluir archivos/carpetas de la generación de rutas para colocación de código.
+
+```
+routes/
+├── orders/
+│   ├── $orderId.tsx             → /orders/:orderId ✅
+│   ├── -components/             → ❌ Ignorado por el router
+│   │   └── OrderHeader.tsx
+│   └── -hooks/                  → ❌ Ignorado por el router
+│       └── useOrderCalculations.ts
+```
+
+### 3.4 Prefijo `$` (Dólar) - Parámetros Dinámicos
+
+```typescript
+// routes/_app/orders/$orderId.tsx
+import { createFileRoute } from '@tanstack/react-router';
+
+export const Route = createFileRoute('/_app/orders/$orderId')({
+  component: OrderDetail,
+});
+
+function OrderDetail() {
+  const { orderId } = Route.useParams(); // Tipado automático
+  return <div>Order: {orderId}</div>;
+}
+```
+
+### 3.5 Resumen de Prefijos
+
+| Prefijo | Nombre | Efecto en URL | Uso Principal |
+|---------|--------|---------------|---------------|
+| `_` | Pathless | **No aparece** | Layouts sin path |
+| `.` | Flat | Crea anidamiento | Evitar carpetas |
+| `-` | Ignore | **No genera ruta** | Colocación de código |
+| `$` | Dynamic | Captura valor | Parámetros de URL |
+| `__` | Root | Raíz del árbol | Solo `__root.tsx` |
+
+---
+
+## 4. Organización de Archivos
+
+### 4.1 Estructura Enterprise (Module/Domain/Feature)
+
+```
+src/
+├── main.tsx                        # React entry point
+├── router.tsx                      # TanStack Router config
+├── routeTree.gen.ts                # Auto-generado (NO EDITAR)
+├── globals.css                     # Estilos globales + Tailwind
+│
+├── routes/                         # 🛣️ SOLO definición de rutas
+│   ├── __root.tsx                  # Layout raíz (providers)
+│   ├── index.tsx                   # Redirect inicial
+│   ├── _auth.tsx                   # Layout público
+│   ├── _auth/
+│   │   └── login.tsx
+│   ├── _app.tsx                    # Layout protegido
+│   └── _app/
+│       ├── dashboard.tsx
+│       ├── sales/
+│       │   ├── quotes.tsx
+│       │   └── invoices.tsx
+│       └── inventory/
+│           └── products.tsx
+│
+├── modules/                        # 🏢 Lógica de negocio por módulo
+│   ├── sales/                      # MODULE
+│   │   ├── quotes/                 # DOMAIN
+│   │   │   ├── cart/               # FEATURE
+│   │   │   │   ├── domain/
+│   │   │   │   │   ├── entities/
+│   │   │   │   │   │   └── CartItem.ts
+│   │   │   │   │   ├── repositories/      # Interfaces
+│   │   │   │   │   │   └── ICartRepository.ts
+│   │   │   │   │   ├── services/          # Domain services
+│   │   │   │   │   │   └── CartCalculator.ts
+│   │   │   │   │   └── types/
+│   │   │   │   │       └── cart.types.ts
+│   │   │   │   ├── application/
+│   │   │   │   │   ├── use-cases/
+│   │   │   │   │   │   ├── AddToCart.ts
+│   │   │   │   │   │   └── RemoveFromCart.ts
+│   │   │   │   │   ├── hooks/
+│   │   │   │   │   │   └── useCart.ts
+│   │   │   │   │   └── store/
+│   │   │   │   │       └── cart.store.ts
+│   │   │   │   ├── infrastructure/
+│   │   │   │   │   ├── repositories/      # Implementations
+│   │   │   │   │   │   └── CartRepository.ts
+│   │   │   │   │   ├── api/
+│   │   │   │   │   │   └── cart.api.ts
+│   │   │   │   │   └── adapters/
+│   │   │   │   └── presentation/
+│   │   │   │       ├── components/
+│   │   │   │       │   ├── CartList.tsx
+│   │   │   │       │   └── CartItem.tsx
+│   │   │   │       └── pages/
+│   │   │   │           └── CartPage.tsx
+│   │   │   └── products/           # FEATURE
+│   │   │       ├── domain/
+│   │   │       ├── application/
+│   │   │       ├── infrastructure/
+│   │   │       └── presentation/
+│   │   └── billing/                # DOMAIN
+│   │       ├── invoices/           # FEATURE
+│   │       └── reports/            # FEATURE
+│   │
+│   ├── inventory/                  # MODULE
+│   │   ├── products/               # DOMAIN
+│   │   │   ├── catalog/            # FEATURE
+│   │   │   └── stock/              # FEATURE
+│   │   └── warehouses/             # DOMAIN
+│   │
+│   └── users/                      # MODULE
+│       └── authentication/         # DOMAIN
+│           ├── login/              # FEATURE
+│           └── registration/       # FEATURE
+│
+├── shared/                         # 🔄 Código reutilizable
+│   ├── components/
+│   │   └── ui/                     # shadcn/ui + siesa-ui-kit
+│   ├── hooks/
+│   │   ├── useDebounce.ts
+│   │   └── useLocalStorage.ts
+│   ├── lib/
+│   │   ├── utils.ts                # cn(), formatters
+│   │   ├── api-client.ts           # Axios/fetch config
+│   │   └── env.ts                  # Variables de entorno tipadas
+│   ├── types/
+│   │   └── common.types.ts
+│   └── constants/
+│
+├── app/                            # 🎯 Configuración global
+│   ├── store/                      # Global store (si necesario)
+│   ├── providers/                  # Context providers
+│   │   ├── ThemeProvider.tsx
+│   │   └── QueryProvider.tsx
+│   └── config/
+│
+├── infrastructure/                 # 🔌 Servicios externos globales
+│   ├── api/                        # API configuration
+│   ├── storage/                    # IndexedDB, localStorage
+│   └── pwa/                        # PWA configuration
+│
+├── assets/                         # 📁 Recursos estáticos
+│   ├── fonts/
+│   │   ├── SiesaBT-Light.otf
+│   │   ├── SiesaBT-Regular.otf
+│   │   └── SiesaBT-Bold.otf
+│   └── images/
+│       └── logos/
+│
+└── styles/
+    └── globals.css
+```
+
+### 4.2 Jerarquía de Carpetas
+
+```
+MODULE (módulo de negocio)
+└── DOMAIN (área funcional)
+    └── FEATURE (funcionalidad específica)
+        ├── domain/          # Reglas de negocio
+        ├── application/     # Casos de uso y estado
+        ├── infrastructure/  # Implementaciones externas
+        └── presentation/    # UI
+```
+
+### 4.3 Organización de Imports
+
+```typescript
+// 1. Librerías externas
+import React from 'react';
+import { create } from 'zustand';
+import { useQuery } from '@tanstack/react-query';
+
+// 2. Módulos internos (por capa, de interno a externo)
+import { CartItem } from '../domain/entities/CartItem';
+import { addToCartUseCase } from '../application/use-cases/AddToCart';
+import { cartRepository } from '../infrastructure/repositories/CartRepository';
+
+// 3. Shared
+import { cn } from '@/shared/lib/utils';
+import { Button } from '@/shared/components/ui/button';
+
+// 4. Types
+import type { Cart } from '../domain/types/cart.types';
+```
+
+---
+
+## 5. Estándares de Componentes
+
+### 5.1 Estrategia de Componentes
+
+| Prioridad | Acción |
+|-----------|--------|
+| **1. siesa-ui-kit** | Siempre verificar primero si existe el componente |
+| **2. Si no existe** | Preguntar al usuario: [1] Usar shadcn directamente, [2] Crear para siesa-ui-kit (requiere MR) |
+| **3. Shadcn fallback** | Solo usar registro MCP Shadcn si el usuario elige opción [1] |
+
+> **Beneficio:** 90% menos bugs usando componentes existentes vs creación manual.
+
+### 5.2 Estructura de Componentes
+
 ```typescript
 interface ComponentProps {
   // Required props
@@ -67,9 +421,11 @@ export const Component = memo<ComponentProps>(({
   variant = 'default',
   'data-testid': testId = 'component'
 }) => {
-  // Component implementation
   return (
-    <div className={cn(baseStyles, variantStyles[variant], className)} data-testid={testId}>
+    <div 
+      className={cn(baseStyles, variantStyles[variant], className)} 
+      data-testid={testId}
+    >
       {children}
     </div>
   );
@@ -78,299 +434,742 @@ export const Component = memo<ComponentProps>(({
 Component.displayName = 'Component';
 ```
 
-### Component Naming
-- **PascalCase** for component names
-- **kebab-case** for file names and data-testid attributes
-- **camelCase** for props and functions
-- Descriptive names that indicate purpose
+### 5.3 Convenciones de Nombrado
+
+| Elemento | Convención | Ejemplo |
+|----------|------------|---------|
+| Componentes | PascalCase | `OrderCard.tsx` |
+| Archivos | kebab-case | `order-card.tsx` |
+| data-testid | kebab-case | `data-testid="order-card"` |
+| Props/funciones | camelCase | `onSubmit`, `isLoading` |
+| Constantes | SCREAMING_SNAKE | `MAX_ITEMS` |
+
+### 5.4 Guidelines de Props
+
+- Siempre definir interfaces TypeScript para props
+- Usar props opcionales con defaults sensatos
+- Incluir `className` para overrides de estilos
+- Agregar `data-testid` para testing
+- Documentar props complejas con JSDoc
+
+---
 
-### Props Guidelines
-- Always define TypeScript interfaces for props
-- Use optional props with sensible defaults
-- Include className for style overrides
-- Add data-testid for testing
-- Document complex props with JSDoc
+## 6. Patrones de Estado
 
-## State Management Patterns
+### 6.1 Estructura de Zustand Store
 
-### Zustand Store Structure
 ```typescript
-interface FeatureState {
+// modules/sales/quotes/cart/application/store/cart.store.ts
+import { create } from 'zustand';
+import { devtools } from 'zustand/middleware';
+import type { CartItem } from '../../domain/entities/CartItem';
+import { addToCartUseCase } from '../use-cases/AddToCart';
+import { removeFromCartUseCase } from '../use-cases/RemoveFromCart';
+
+interface CartState {
   // Domain entities
-  entities: Entity[];
-  selectedEntity: Entity | null;
+  items: CartItem[];
   
   // UI state
   loading: boolean;
   error: string | null;
   
-  // Actions (use case calls)
-  loadEntities: () => Promise<void>;
-  selectEntity: (id: string) => void;
-  updateEntity: (entity: Entity) => Promise<void>;
+  // Actions (delegan a use cases)
+  addItem: (productId: string, quantity: number) => Promise<void>;
+  removeItem: (itemId: string) => Promise<void>;
+  clearCart: () => void;
   clearError: () => void;
 }
 
-export const useFeatureStore = create<FeatureState>()(
+export const useCartStore = create<CartState>()(
   devtools(
     (set, get) => ({
       // Initial state
-      entities: [],
-      selectedEntity: null,
+      items: [],
       loading: false,
       error: null,
       
-      // Actions implementation
-      loadEntities: async () => {
+      // Actions
+      addItem: async (productId, quantity) => {
+        set({ loading: true, error: null });
+        try {
+          const newItem = await addToCartUseCase.execute({ productId, quantity });
+          set((state) => ({ 
+            items: [...state.items, newItem], 
+            loading: false 
+          }));
+        } catch (error) {
+          set({ error: (error as Error).message, loading: false });
+        }
+      },
+      
+      removeItem: async (itemId) => {
         set({ loading: true, error: null });
         try {
-          const entities = await loadEntitiesUseCase.execute();
-          set({ entities, loading: false });
+          await removeFromCartUseCase.execute(itemId);
+          set((state) => ({
+            items: state.items.filter(item => item.id !== itemId),
+            loading: false
+          }));
         } catch (error) {
-          set({ error: error.message, loading: false });
+          set({ error: (error as Error).message, loading: false });
         }
       },
       
-      // Other actions...
+      clearCart: () => set({ items: [] }),
+      clearError: () => set({ error: null }),
     }),
-    { name: 'featureStore' }
+    { name: 'cartStore' }
   )
 );
 ```
 
-## Testing Standards
+### 6.2 Cuándo Usar Cada Tipo de Estado
+
+| Tipo | Cuándo Usar | Herramienta |
+|------|-------------|-------------|
+| **Server State** | Datos del API, cache | TanStack Query |
+| **Global Client State** | Auth, theme, cart | Zustand |
+| **Local Component State** | Forms, UI toggles | useState/useReducer |
+| **URL State** | Filtros, paginación | TanStack Router search params |
+
+### 6.3 Integración con TanStack Query
+
+```typescript
+// modules/sales/quotes/products/infrastructure/api/products.api.ts
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { productRepository } from '../repositories/ProductRepository';
+
+export const productKeys = {
+  all: ['products'] as const,
+  lists: () => [...productKeys.all, 'list'] as const,
+  list: (filters: ProductFilters) => [...productKeys.lists(), filters] as const,
+  detail: (id: string) => [...productKeys.all, 'detail', id] as const,
+};
+
+export function useProducts(filters: ProductFilters) {
+  return useQuery({
+    queryKey: productKeys.list(filters),
+    queryFn: () => productRepository.getAll(filters),
+  });
+}
+
+export function useProduct(id: string) {
+  return useQuery({
+    queryKey: productKeys.detail(id),
+    queryFn: () => productRepository.getById(id),
+    enabled: !!id,
+  });
+}
+```
+
+---
+
+## 7. Estándares de Testing
+
+### 7.1 Estrategia de Testing
+
+| Tipo | Cobertura | Herramienta | Qué Testear |
+|------|-----------|-------------|-------------|
+| **Unit** | Alta | Vitest | Entities, use cases, utilities |
+| **Integration** | Media | Vitest + MSW | Feature workflows, API integration |
+| **Component** | Media | React Testing Library | User interactions, accessibility |
+| **E2E** | Baja | Playwright | Critical user journeys |
+
+### 7.2 Estructura de Tests
+
+```typescript
+// modules/sales/quotes/cart/application/use-cases/__tests__/AddToCart.test.ts
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { addToCartUseCase } from '../AddToCart';
+import { mockCartRepository } from '../../__mocks__/cartRepository.mock';
+
+describe('AddToCart UseCase', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should add item to cart successfully', async () => {
+    const input = { productId: 'prod-1', quantity: 2 };
+    
+    const result = await addToCartUseCase.execute(input);
+    
+    expect(result).toMatchObject({
+      productId: 'prod-1',
+      quantity: 2,
+    });
+    expect(mockCartRepository.save).toHaveBeenCalledWith(expect.objectContaining(input));
+  });
+
+  it('should throw error when quantity is invalid', async () => {
+    const input = { productId: 'prod-1', quantity: -1 };
+    
+    await expect(addToCartUseCase.execute(input)).rejects.toThrow(
+      'La cantidad debe ser mayor a 0'
+    );
+  });
+});
+```
 
-### Testing Strategy
-- **Unit Tests**: Domain entities, use cases, utilities
-- **Integration Tests**: Feature workflows, API integration
-- **Component Tests**: User interactions, accessibility
-- **E2E Tests**: Critical user journeys (minimal)
+### 7.3 Component Testing
 
-### Test Structure
 ```typescript
-describe('ComponentName', () => {
+// modules/sales/quotes/cart/presentation/components/__tests__/CartItem.test.tsx
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { axe } from 'vitest-axe';
+import { CartItem } from '../CartItem';
+
+describe('CartItem', () => {
+  const defaultProps = {
+    item: { id: '1', name: 'Producto Test', quantity: 2, price: 100 },
+    onRemove: vi.fn(),
+  };
+
   it('should render correctly with default props', () => {
-    render(<ComponentName>Test content</ComponentName>);
-    expect(screen.getByTestId('component-name')).toBeInTheDocument();
+    render(<CartItem {...defaultProps} />);
+    
+    expect(screen.getByTestId('cart-item')).toBeInTheDocument();
+    expect(screen.getByText('Producto Test')).toBeInTheDocument();
   });
-  
-  it('should handle user interactions', async () => {
-    const handleClick = jest.fn();
-    render(<ComponentName onClick={handleClick} />);
+
+  it('should handle remove action', async () => {
+    const user = userEvent.setup();
+    render(<CartItem {...defaultProps} />);
     
-    await user.click(screen.getByRole('button'));
-    expect(handleClick).toHaveBeenCalled();
+    await user.click(screen.getByRole('button', { name: /eliminar/i }));
+    
+    expect(defaultProps.onRemove).toHaveBeenCalledWith('1');
   });
-  
+
   it('should be accessible', async () => {
-    const { container } = render(<ComponentName />);
+    const { container } = render(<CartItem {...defaultProps} />);
     const results = await axe(container);
+    
     expect(results).toHaveNoViolations();
   });
 });
 ```
 
-## Accessibility Standards
+---
+
+## 8. Accesibilidad
+
+### 8.1 Cumplimiento WCAG 2.1 AA
+
+| Requisito | Implementación |
+|-----------|----------------|
+| Elementos semánticos | Usar HTML semántico (`<nav>`, `<main>`, `<article>`) |
+| Jerarquía de headings | Un solo `<h1>`, headings en orden descendente |
+| Navegación por teclado | Todos los elementos interactivos accesibles con Tab |
+| Screen readers | Labels descriptivos, roles ARIA cuando necesario |
+| Contraste de color | Mínimo 4.5:1 para texto normal |
 
-### WCAG 2.1 AA Compliance
-- Semantic HTML elements
-- Proper heading hierarchy
-- Keyboard navigation support
-- Screen reader compatibility
-- Color contrast minimum 4.5:1
+### 8.2 Implementación ARIA
 
-### ARIA Implementation
-- Use semantic HTML first, ARIA second
-- Proper labeling with aria-label or aria-labelledby
-- Role attributes for custom components
-- State communication with aria-expanded, aria-selected
-- Live regions for dynamic content updates
+```typescript
+// ✅ Correcto - HTML semántico primero
+<button onClick={handleSubmit}>Guardar</button>
+
+// ✅ Correcto - ARIA cuando es necesario
+<div 
+  role="tabpanel" 
+  aria-labelledby="tab-1"
+  aria-expanded={isOpen}
+>
+  {content}
+</div>
 
-## Performance Standards
+// ❌ Incorrecto - ARIA innecesario
+<button role="button" aria-label="button">Guardar</button>
+```
 
-### Bundle Optimization
-- Code splitting by route and feature
-- Lazy loading for non-critical components
-- Tree shaking for unused code
-- Bundle size budget: 500KB total
+---
 
-### Runtime Performance
-- React.memo for expensive components
-- useMemo for expensive calculations
-- useCallback for event handlers passed to children
-- Virtual scrolling for large lists
+## 9. Rendimiento
 
-### Loading Performance
-- Image optimization and lazy loading
-- Progressive loading strategies
-- Skeleton screens for loading states
-- Prefetch critical resources
+### 9.1 Optimización de Bundle
 
-## Security Guidelines
+| Estrategia | Implementación |
+|------------|----------------|
+| Code splitting | Por ruta (automático con TanStack Router) |
+| Lazy loading | `React.lazy()` para componentes no críticos |
+| Tree shaking | Imports específicos, no barrel exports en shared |
+| Bundle budget | Máximo 500KB total |
 
-### Client-Side Security
-- No API keys or secrets in frontend code
-- Input validation and sanitization
-- XSS prevention measures
-- Secure handling of user data
+### 9.2 Rendimiento en Runtime
 
-### Authentication
-- Token-based authentication (JWT)
-- Secure token storage
-- Automatic token refresh
-- Proper logout handling
+```typescript
+// ✅ React.memo para componentes costosos
+export const ExpensiveList = memo<ListProps>(({ items }) => {
+  return items.map(item => <ExpensiveItem key={item.id} item={item} />);
+});
 
-## File Organization
+// ✅ useMemo para cálculos costosos
+const sortedItems = useMemo(() => 
+  items.sort((a, b) => a.name.localeCompare(b.name)),
+  [items]
+);
 
-### Feature Structure
+// ✅ useCallback para handlers pasados a children
+const handleClick = useCallback((id: string) => {
+  onSelect(id);
+}, [onSelect]);
 ```
-src/
-├── modules/
-│   ├── sales/                    # MODULE
-│   │   ├── quotes/              # DOMAIN
-│   │   │   ├── cart/            # FEATURE
-│   │   │   │   ├── domain/
-│   │   │   │   │   ├── entities/
-│   │   │   │   │   ├── repositories/     # Interfaces
-│   │   │   │   │   ├── services/         # Domain services
-│   │   │   │   │   └── types/
-│   │   │   │   ├── application/
-│   │   │   │   │   ├── use-cases/
-│   │   │   │   │   ├── hooks/            # Custom hooks
-│   │   │   │   │   └── store/            # Zustand store
-│   │   │   │   ├── infrastructure/
-│   │   │   │   │   ├── repositories/     # Implementations
-│   │   │   │   │   ├── api/
-│   │   │   │   │   └── adapters/
-│   │   │   │   └── presentation/
-│   │   │   │       ├── components/
-│   │   │   │       ├── pages/
-│   │   │   │       └── styles/
-│   │   │   └── products/        # FEATURE
-│   │   │       ├── domain/
-│   │   │       ├── application/
-│   │   │       ├── infrastructure/
-│   │   │       └── presentation/
-│   │   └── billing/             # DOMAIN
-│   │       ├── invoices/        # FEATURE
-│   │       └── reports/         # FEATURE
-│   ├── inventory/               # MODULE
-│   │   ├── products/            # DOMAIN
-│   │   │   ├── catalog/         # FEATURE
-│   │   │   └── stock/           # FEATURE
-│   │   └── warehouses/          # DOMAIN
-│   └── users/                   # MODULE
-│       └── authentication/      # DOMAIN
-│           ├── login/           # FEATURE
-│           └── registration/    # FEATURE
-├── shared/
-│   ├── components/              # Shadcn/ui components
-│   │   └── ui/                  # Base UI Kit components from proyecto/components/ui/
-│   ├── hooks/
-│   ├── utils/
-│   ├── types/
-│   └── constants/
-├── app/
-│   ├── store/                   # Global store
-│   ├── providers/               # Context providers
-│   ├── router/                  # Routing config
-│   └── app.tsx
-├── infrastructure/
-│   ├── api/                     # API configuration
-│   ├── storage/                 # IndexedDB, localStorage
-│   └── pwa/                     # PWA configuration
-├── assets/
-│   ├── fonts/                   # Fonts from proyecto/public/fonts/
-│   │   ├── SiesaBT-Light.otf
-│   │   ├── SiesaBT-Regular.otf
-│   │   └── SiesaBT-Bold.otf
-│   ├── images/
-│   │   └── logos/               # Logos from proyecto/public/images/logos/
-│   │       ├── Siesa_Logosimbolo_Azul.svg
-│   │       ├── Siesa_Logosimbolo_Blanco.svg
-│   │       ├── Siesa_Simbolo_Azul.svg
-│   │       └── Siesa_Simbolo_Blanco.svg
-│   └── favicon.ico              # Favicon from proyecto/public/favicon.ico
-└── styles/
-    └── globals.css              # Consolidated styles + Tailwind + WCAG from proyecto/styles/globals.css
+
+### 9.3 Loading Performance
+
+- Optimización de imágenes y lazy loading
+- Skeleton screens para estados de carga
+- Prefetch de recursos críticos
+- Virtual scrolling para listas grandes
+
+---
+
+## 10. Seguridad
+
+### 10.1 Seguridad Client-Side
+
+| Riesgo | Mitigación |
+|--------|------------|
+| API keys expuestas | Nunca en código frontend, usar variables de entorno server-side |
+| XSS | Sanitización de inputs, no usar `dangerouslySetInnerHTML` |
+| Datos sensibles | No almacenar en localStorage sin encriptar |
+
+### 10.2 Autenticación
+
+```typescript
+// Manejo seguro de tokens
+const useAuthStore = create<AuthState>((set) => ({
+  token: null,
+  
+  setToken: (token: string) => {
+    // Almacenar en memoria, no localStorage
+    set({ token });
+  },
+  
+  logout: () => {
+    set({ token: null });
+    // Limpiar cualquier dato sensible
+  },
+}));
 ```
 
-### Import Organization
+---
+
+## 11. Manejo de Errores
+
+### 11.1 Error Boundaries por Feature
+
 ```typescript
-// External libraries
-import React from 'react';
-import { create } from 'zustand';
+// shared/components/feedback/ErrorBoundary.tsx
+import { Component, ErrorInfo, ReactNode } from 'react';
+
+interface Props {
+  children: ReactNode;
+  fallback?: ReactNode;
+}
+
+interface State {
+  hasError: boolean;
+  error: Error | null;
+}
+
+export class ErrorBoundary extends Component<Props, State> {
+  state: State = { hasError: false, error: null };
 
-// Internal utilities
-import { cn } from '@/lib/utils';
+  static getDerivedStateFromError(error: Error): State {
+    return { hasError: true, error };
+  }
 
-// Types
-import type { User } from '../domain/types/User';
+  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+    console.error('Error capturado:', error, errorInfo);
+    // Enviar a servicio de logging
+  }
 
-// Components
-import { Button } from '@/components/ui/button';
+  render() {
+    if (this.state.hasError) {
+      return this.props.fallback || (
+        <div className="p-4 text-center">
+          <h2 className="text-lg font-semibold text-red-600">
+            Algo salió mal
+          </h2>
+          <p className="text-gray-600">
+            Por favor, intenta recargar la página
+          </p>
+        </div>
+      );
+    }
+
+    return this.props.children;
+  }
+}
+```
+
+### 11.2 Manejo de Errores en API
+
+```typescript
+// shared/lib/api-client.ts
+import axios, { AxiosError } from 'axios';
+
+const apiClient = axios.create({
+  baseURL: import.meta.env.VITE_API_URL,
+});
+
+apiClient.interceptors.response.use(
+  (response) => response,
+  (error: AxiosError<{ message: string }>) => {
+    const message = error.response?.data?.message || 'Error de conexión';
+    
+    // Mensaje amigable para el usuario
+    return Promise.reject(new Error(message));
+  }
+);
 ```
 
-## Error Handling
+---
+
+## 12. Progressive Web App
+
+### 12.1 Features PWA
 
-### Error Boundaries
-- Feature-level error boundaries
-- Graceful fallback UI
-- Error reporting and logging
-- User-friendly error messages
+| Feature | Implementación |
+|---------|----------------|
+| Service Worker | Caching y soporte offline |
+| Web App Manifest | Instalabilidad |
+| Push Notifications | Cuando sea necesario |
+| Background Sync | Sincronización al restaurar conexión |
 
-### API Error Handling
-- Centralized error handling in HTTP client
-- Proper error typing
-- User-friendly error messages
-- Retry mechanisms for transient errors
+### 12.2 Estrategia Offline
 
-## Progressive Web App Standards
+| Tipo de Recurso | Estrategia |
+|-----------------|------------|
+| Assets estáticos | Cache-first |
+| Datos dinámicos | Network-first con fallback |
+| Páginas offline | Fallback pre-cacheado |
+| Formularios | Queue y sync cuando online |
 
-### PWA Features
-- Service worker for caching and offline support
-- Web app manifest for installability
-- Push notifications (when needed)
-- Background sync capabilities
+---
 
-### Offline Strategy
-- Cache-first for static assets
-- Network-first for dynamic data
-- Fallback pages for offline scenarios
-- Sync when connection restored
+## 13. Estándares de Idioma
 
-## Language Standards (Frontend & Backend)
+### 13.1 Español para Todo Contenido Visible al Usuario
 
-### Spanish for All User-Facing Content (CRITICAL RULE)
+**REGLA CRÍTICA: Todo texto visible al usuario final DEBE estar en español.**
 
-**MANDATORY: All text visible to end users MUST be in Spanish.**
+#### ✅ Español Requerido
 
-#### ✅ Spanish Required:
-- UI labels, buttons, forms, messages, notifications
-- API responses, validation errors, email templates
-- Any text the user sees (frontend or backend)
+- Labels de UI, botones, formularios, mensajes, notificaciones
+- Respuestas de API, errores de validación, templates de email
+- Cualquier texto que el usuario vea (frontend o backend)
 
-#### ✅ English Required:
-- Code (variables, functions, classes)
-- Technical logs, comments, git commits
-- Developer documentation
+#### ✅ Inglés Requerido
 
-#### ❌ Never mix languages in user-facing text
+- Código (variables, funciones, clases)
+- Logs técnicos, comentarios, commits de git
+- Documentación técnica para desarrolladores
+
+#### ❌ Nunca Mezclar Idiomas en Texto Visible
 
-**Examples:**
 ```typescript
-// ✅ CORRECT
+// ✅ CORRECTO
 <Button>Guardar</Button>
 toast.success("Datos guardados correctamente");
 throw new BadRequestException('No se pudo crear el usuario');
 
-// ❌ INCORRECT
+// ❌ INCORRECTO
 <Button>Save cambios</Button>
 toast.error("Failed al guardar");
 throw new BadRequestException('Invalid datos proporcionados');
 ```
 
-**Implementation:**
-- Create message constants in Spanish
-- Validate all user-facing text before story completion
-- Technical logs stay in English, user messages in Spanish
+### 13.2 Implementación
+
+```typescript
+// shared/constants/messages.ts
+export const MESSAGES = {
+  SUCCESS: {
+    SAVED: 'Datos guardados correctamente',
+    DELETED: 'Elemento eliminado correctamente',
+    UPDATED: 'Información actualizada',
+  },
+  ERROR: {
+    GENERIC: 'Ha ocurrido un error. Por favor, intenta de nuevo',
+    NOT_FOUND: 'El recurso solicitado no fue encontrado',
+    UNAUTHORIZED: 'No tienes permisos para realizar esta acción',
+    VALIDATION: 'Por favor, verifica los datos ingresados',
+  },
+  LOADING: {
+    DEFAULT: 'Cargando...',
+    SAVING: 'Guardando...',
+    PROCESSING: 'Procesando...',
+  },
+} as const;
+```
+
+---
+
+## 14. Consideraciones Generales
+
+### 14.1 Gestor de Paquetes
+
+**Regla:** Usar `pnpm` como gestor de paquetes por defecto, pero respetar el gestor existente en proyectos ya iniciados.
+
+| Escenario | Acción | Razón |
+|-----------|--------|-------|
+| Proyecto nuevo | Usar `pnpm` | Mejor rendimiento y manejo de dependencias |
+| Proyecto con `package-lock.json` | Continuar con `npm` | Evitar conflictos de lockfiles |
+| Proyecto con `yarn.lock` | Continuar con `yarn` | Evitar conflictos de lockfiles |
+| Proyecto con `pnpm-lock.yaml` | Continuar con `pnpm` | Ya está configurado |
+
+#### Cómo Identificar el Gestor Actual
+
+```bash
+ls -la | grep -E "package-lock|yarn.lock|pnpm-lock"
+```
+
+| Archivo encontrado | Gestor a usar |
+|--------------------|---------------|
+| `package-lock.json` | `npm` |
+| `yarn.lock` | `yarn` |
+| `pnpm-lock.yaml` | `pnpm` |
+| Ninguno | `pnpm` (proyecto nuevo) |
+
+#### Comandos Equivalentes
+
+| Acción | pnpm | npm | yarn |
+|--------|------|-----|------|
+| Instalar | `pnpm install` | `npm install` | `yarn` |
+| Agregar dep | `pnpm add <pkg>` | `npm install <pkg>` | `yarn add <pkg>` |
+| Agregar dev | `pnpm add -D <pkg>` | `npm install -D <pkg>` | `yarn add -D <pkg>` |
+| Ejecutar script | `pnpm <script>` | `npm run <script>` | `yarn <script>` |
+| Remover | `pnpm remove <pkg>` | `npm uninstall <pkg>` | `yarn remove <pkg>` |
+
+> **⚠️ Importante:** Nunca mezclar gestores de paquetes en un mismo proyecto.
+
+---
+
+## 15. Configuración Base
+
+### 15.1 `vite.config.ts`
+
+```typescript
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { TanStackRouterVite } from '@tanstack/router-plugin/vite';
+import viteTsConfigPaths from 'vite-tsconfig-paths';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+  plugins: [
+    // TanStack Router DEBE ir primero
+    TanStackRouterVite({
+      target: 'react',
+      autoCodeSplitting: true,
+      routesDirectory: './src/routes',
+      generatedRouteTree: './src/routeTree.gen.ts',
+      routeFileIgnorePrefix: '-',
+    }),
+    react(),
+    viteTsConfigPaths(),
+    tailwindcss(),
+  ],
+  resolve: {
+    alias: {
+      '@': '/src',
+      '@modules': '/src/modules',
+      '@shared': '/src/shared',
+      '@app': '/src/app',
+    },
+  },
+  server: {
+    port: 3000,
+  },
+  build: {
+    outDir: 'dist',
+  },
+});
+```
+
+### 15.2 `src/router.tsx`
+
+```typescript
+import { createRouter as createTanStackRouter } from '@tanstack/react-router';
+import { QueryClient } from '@tanstack/react-query';
+import { routerWithQueryClient } from '@tanstack/react-router-with-query';
+import { routeTree } from './routeTree.gen';
+
+function NotFoundPage() {
+  return (
+    <div className="min-h-screen flex items-center justify-center">
+      <div className="text-center">
+        <h1 className="text-6xl font-bold">404</h1>
+        <p className="mt-4">Página no encontrada</p>
+      </div>
+    </div>
+  );
+}
+
+function ErrorPage({ error }: { error: Error }) {
+  return (
+    <div className="min-h-screen flex items-center justify-center">
+      <div className="text-center">
+        <h1 className="text-2xl font-bold text-red-600">Error</h1>
+        <p className="mt-4">{error.message}</p>
+      </div>
+    </div>
+  );
+}
+
+export function createRouter() {
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: 60 * 1000,
+        refetchOnWindowFocus: false,
+      },
+    },
+  });
+
+  const router = createTanStackRouter({
+    routeTree,
+    context: { queryClient },
+    defaultPreload: 'intent',
+    scrollRestoration: true,
+    defaultNotFoundComponent: NotFoundPage,
+    defaultErrorComponent: ErrorPage,
+  });
+
+  return routerWithQueryClient(router, queryClient);
+}
+
+declare module '@tanstack/react-router' {
+  interface Register {
+    router: ReturnType<typeof createRouter>;
+  }
+}
+```
+
+### 15.3 `src/main.tsx`
+
+```typescript
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { RouterProvider } from '@tanstack/react-router';
+import { createRouter } from './router';
+import './globals.css';
+
+const router = createRouter();
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <RouterProvider router={router} />
+  </StrictMode>
+);
+```
+
+### 15.4 `src/routes/__root.tsx`
+
+```typescript
+import { createRootRouteWithContext, Outlet } from '@tanstack/react-router';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { Toaster } from 'sonner';
+
+interface RouterContext {
+  queryClient: QueryClient;
+}
+
+export const Route = createRootRouteWithContext<RouterContext>()({
+  component: RootComponent,
+});
+
+function RootComponent() {
+  const { queryClient } = Route.useRouteContext();
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      <Outlet />
+      <Toaster position="bottom-right" />
+    </QueryClientProvider>
+  );
+}
+```
+
+### 15.5 `vitest.config.ts`
+
+```typescript
+import { defineConfig } from 'vitest/config';
+import react from '@vitejs/plugin-react';
+import viteTsConfigPaths from 'vite-tsconfig-paths';
+
+export default defineConfig({
+  plugins: [react(), viteTsConfigPaths()],
+  test: {
+    globals: true,
+    environment: 'jsdom',
+    setupFiles: ['./src/test/setup.ts'],
+    include: ['src/**/*.{test,spec}.{ts,tsx}'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      exclude: [
+        'node_modules/',
+        'src/test/',
+        '**/*.d.ts',
+        'src/routeTree.gen.ts',
+      ],
+    },
+  },
+});
+```
+
+---
+
+## 16. Checklist de Implementación
+
+### Configuración Inicial
+
+- [ ] Instalar dependencias: `@tanstack/react-router`, `@tanstack/router-plugin`, `@tanstack/react-query`
+- [ ] Crear `vite.config.ts` con TanStackRouterVite plugin (PRIMERO)
+- [ ] Crear `src/router.tsx` con configuración del router
+- [ ] Crear `src/main.tsx` con RouterProvider
+- [ ] Crear `src/routes/__root.tsx`
+- [ ] Configurar path aliases en `tsconfig.json`
+- [ ] Agregar `routeTree.gen.ts` a `.prettierignore` y `.eslintignore`
+- [ ] Configurar Vitest
+
+### Estructura de Rutas
+
+- [ ] Crear layouts pathless (`_auth.tsx`, `_app.tsx`)
+- [ ] Implementar guards de autenticación en `beforeLoad`
+- [ ] Usar `$param` para rutas dinámicas
+- [ ] Usar `-` para carpetas de colocación
+- [ ] Verificar que las URLs sean correctas
+
+### Arquitectura
+
+- [ ] Organizar módulos siguiendo Module/Domain/Feature
+- [ ] Implementar capas de Clean Architecture por feature
+- [ ] Configurar stores Zustand por feature
+- [ ] Configurar TanStack Query para server state
+- [ ] Crear barrel exports (`index.ts`) por feature
+
+### Calidad
+
+- [ ] Configurar Vitest con coverage
+- [ ] Agregar tests unitarios para use cases
+- [ ] Agregar tests de componentes
+- [ ] Verificar accesibilidad (axe)
+- [ ] Validar textos en español
+
+---
+
+## Referencias
+
+- [TanStack Router Documentation](https://tanstack.com/router/latest)
+- [TanStack Query Documentation](https://tanstack.com/query/latest)
+- [Zustand Documentation](https://zustand-demo.pmnd.rs/)
+- [Vite Documentation](https://vitejs.dev/)
+- [Vitest Documentation](https://vitest.dev/)
+- [Clean Architecture - Robert C. Martin](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)