@create-lft-app/nextjs 3.0.0 → 3.2.0

package/template/CLAUDE.md

@@ -1,279 +1,1239 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## 🚨 CRITICAL: MANDATORY ARCHITECTURAL PATTERN 🚨
-
-**⚠️ BEFORE WRITING ANY CODE, YOU MUST READ AND FOLLOW THIS PATTERN ⚠️**
-
-This section is **NON-NEGOTIABLE** and MUST be followed in **100% of cases** when creating or modifying features in this codebase.
-
-## ⚠️ The Most Common Mistake (DON'T DO THIS!)
-
-```typescript
-// ❌ WRONG - NEVER IMPORT MUTATIONS OR QUERIES DIRECTLY IN COMPONENTS
-import { useEntityMutations } from '@/modules/[entity]/hooks/useEntityMutations'
-import { useEntityQueries } from '@/modules/[entity]/hooks/useEntityQueries'
-
-export function MyComponent() {
-  const { createEntity } = useEntityMutations() // ❌ ARCHITECTURAL VIOLATION
-  const { entities } = useEntityQueries() // ❌ ARCHITECTURAL VIOLATION
-}
-
-// ✅ CORRECT - ALWAYS USE THE UNIFIED HOOK
-import { useEntity } from '@/modules/[entity]/hooks/useEntity'
-
-export function MyComponent() {
-  const { createEntity, entities } = useEntity() // ✅ CORRECT PATTERN
-}
-```
-
-## 🚨 MANDATORY Pattern: Store → Queries → Mutations → Unified Hook → Component
-
-**THIS IS THE ONLY ACCEPTABLE ARCHITECTURE FOR THIS CODEBASE.**
-
-Every module MUST follow this exact structure:
-
-```
-modules/
-└── [entity]/
-    ├── actions/
-    │   └── [entity]-actions.ts          # Server actions with RLS
-    ├── components/
-    │   ├── [entity]-list.tsx            # Component imports ONLY unified hook
-    │   ├── [entity]-form.tsx
-    │   └── [entity]-detail.tsx
-    ├── hooks/
-    │   ├── use[Entity]Queries.ts        # TanStack Query (read operations)
-    │   ├── use[Entity]Mutations.ts      # TanStack Mutations (write operations)
-    │   └── use[Entity].ts               # UNIFIED HOOK (components use THIS)
-    ├── stores/
-    │   └── use[Entity]Store.ts          # Zustand store (UI state only)
-    ├── schemas/
-    │   └── [entity].schema.ts           # Zod validation schemas
-    ├── columns.tsx                      # TanStack Table column definitions (if needed)
-    └── index.ts                         # Barrel export
-```
-
-## 📋 Mandatory Implementation Checklist
-
-Before writing ANY code, verify this checklist:
-
-- [ ] **Step 1**: Create Drizzle schema in `db/schema/[entity].ts`
-- [ ] **Step 2**: Create Zod schemas in `modules/[entity]/schemas/[entity].schema.ts`
-- [ ] **Step 3**: Create Server actions in `modules/[entity]/actions/[entity]-actions.ts`
-- [ ] **Step 4**: Create Zustand store with separate state/actions selectors using `useShallow` in `modules/[entity]/stores/`
-- [ ] **Step 5**: Create Queries hook in `modules/[entity]/hooks/use[Entity]Queries.ts`
-- [ ] **Step 6**: Create Mutations hook with cache invalidation in `modules/[entity]/hooks/use[Entity]Mutations.ts`
-- [ ] **Step 7**: Create Unified hook that combines store + queries + mutations in `modules/[entity]/hooks/use[Entity].ts`
-- [ ] **Step 8**: Components ONLY import the unified hook (NEVER queries/mutations directly)
-- [ ] **Step 9**: Test with `pnpm typecheck && pnpm lint` before committing
-
-## 🔴 NEVER DO THIS (Anti-Patterns)
-
-```typescript
-// ❌ NEVER: Import queries or mutations directly in components
-import { useEntityQueries } from '@/modules/[entity]/hooks/useEntityQueries'
-import { useEntityMutations } from '@/modules/[entity]/hooks/useEntityMutations'
-
-// ❌ NEVER: Consume entire store (causes re-renders)
-const store = useEntityStore()
-
-// ❌ NEVER: Manual data fetching in useEffect
-useEffect(() => {
-  fetch('/api/entities').then(setData)
-}, [])
-
-// ❌ NEVER: Server actions without authenticated user context (RLS won't work)
-export async function deleteEntity(id: string) {
-  const supabase = createClient() // Anonymous client - RLS will fail!
-  await supabase.from('entities').delete().eq('id', id)
-}
-```
-
-## ✅ ALWAYS DO THIS (Correct Patterns)
-
-```typescript
-// ✅ ALWAYS: Use the unified hook in components
-import { useEntity } from '@/modules/[entity]/hooks/useEntity'
-
-// ✅ ALWAYS: Use separate selectors with useShallow
-import { useEntityStore } from '@/modules/[entity]/stores/useEntityStore'
-import { useShallow } from 'zustand/react/shallow'
-
-const state = useEntityStore(useShallow((s) => s.state))
-const actions = useEntityStore(useShallow((s) => s.actions))
-
-// ✅ ALWAYS: Use TanStack Query for data fetching
-const { data } = useQuery({ queryKey: ['entities'], queryFn: fetchEntities })
-
-// ✅ ALWAYS: Use authenticated Supabase client in server actions (RLS enforced)
-'use server'
-
-import { createClient } from '@/lib/supabase/server'
-
-export async function deleteEntity(id: string) {
-  const supabase = await createClient() // Authenticated client with user context
-  const { data: { user } } = await supabase.auth.getUser()
-
-  if (!user) throw new Error('Unauthorized')
-
-  // RLS policies will automatically enforce authorization
-  const { error } = await supabase.from('entities').delete().eq('id', id)
-
-  if (error) throw error
-}
-```
-
-## 📁 Complete Project Structure
-
-```
-src/
-├── app/
-│   ├── (auth)/                          # Rutas autenticadas
-│   │   ├── dashboard/
-│   │   │   └── page.tsx
-│   │   └── layout.tsx
-│   ├── (public)/                        # Rutas públicas
-│   │   ├── login/
-│   │   │   └── page.tsx
-│   │   └── layout.tsx
-│   ├── api/
-│   │   └── webhooks/
-│   │       └── route.ts
-│   ├── layout.tsx
-│   ├── page.tsx
-│   └── providers.tsx
-│
-├── modules/                             # Feature-based modules
-│   ├── auth/
-│   │   ├── actions/
-│   │   │   └── auth-actions.ts
-│   │   ├── components/
-│   │   │   └── login-form.tsx
-│   │   ├── hooks/
-│   │   │   ├── useAuthQueries.ts
-│   │   │   ├── useAuthMutations.ts
-│   │   │   └── useAuth.ts
-│   │   ├── stores/
-│   │   │   └── useAuthStore.ts
-│   │   ├── schemas/
-│   │   │   └── auth.schema.ts
-│   │   └── index.ts
-│   └── users/
-│       ├── actions/
-│       │   └── users-actions.ts
-│       ├── components/
-│       │   ├── users-list.tsx
-│       │   ├── users-form.tsx
-│       │   └── users-detail.tsx
-│       ├── hooks/
-│       │   ├── useUsersQueries.ts
-│       │   ├── useUsersMutations.ts
-│       │   └── useUsers.ts
-│       ├── stores/
-│       │   └── useUsersStore.ts
-│       ├── schemas/
-│       │   └── users.schema.ts
-│       ├── columns.tsx
-│       └── index.ts
-│
-├── components/
-│   ├── ui/                              # Radix custom components
-│   │   ├── button.tsx
-│   │   ├── dialog.tsx
-│   │   └── index.ts
-│   ├── tables/                          # TanStack Table components
-│   │   ├── data-table.tsx
-│   │   ├── data-table-pagination.tsx
-│   │   ├── data-table-toolbar.tsx
-│   │   ├── data-table-column-header.tsx
-│   │   └── index.ts
-│   ├── layout/
-│   │   ├── header.tsx
-│   │   └── sidebar.tsx
-│   └── shared/
-│       └── ...
-│
-├── stores/                              # Global Zustand stores
-│   ├── useUiStore.ts
-│   └── index.ts
-│
-├── hooks/                               # Global hooks
-│   ├── useMediaQuery.ts
-│   ├── useDebounce.ts
-│   └── useDataTable.ts
-│
-├── lib/
-│   ├── supabase/
-│   │   ├── client.ts
-│   │   ├── server.ts
-│   │   ├── proxy.ts
-│   │   └── types.ts
-│   ├── excel/
-│   │   ├── parser.ts
-│   │   ├── exporter.ts
-│   │   └── index.ts
-│   ├── date/
-│   │   ├── config.ts
-│   │   ├── formatters.ts
-│   │   └── index.ts
-│   ├── validations/
-│   │   ├── common.ts
-│   │   └── index.ts
-│   ├── query-client.ts
-│   └── utils.ts
-│
-├── db/
-│   ├── schema/
-│   │   ├── users.ts
-│   │   └── index.ts
-│   ├── migrations/
-│   ├── index.ts
-│   └── seed.ts
-│
-├── types/
-│   ├── api.ts
-│   ├── table.ts
-│   └── index.ts
-│
-├── config/
-│   ├── site.ts
-│   └── navigation.ts
-│
-└── styles/
-    └── globals.css
-
-supabase/
-├── functions/
-│   ├── process-excel/
-│   │   └── index.ts
-│   └── send-notification/
-│       └── index.ts
-├── migrations/
-└── config.toml
-
-# Root files
-├── .env.local
-├── .env.example
-├── drizzle.config.ts
-├── proxy.ts
-├── next.config.ts
-├── package.json
-├── tsconfig.json
-└── tailwind.config.ts
-```
-
-## 🛠️ Tech Stack
-
-- **Framework**: Next.js 16 (App Router)
-- **State Management**: Zustand 5
-- **Data Fetching**: TanStack Query 5
-- **Tables**: TanStack Table 8
-- **Database**: Supabase + Drizzle ORM
-- **Validation**: Zod
-- **UI**: Radix UI + Tailwind CSS
-- **Forms**: React Hook Form + Zod resolver
-- **Excel**: xlsx (SheetJS)
-- **Dates**: dayjs
-- **Package Manager**: pnpm
+# CLAUDE.md - Instrucciones para Claude Code
+
+**IMPORTANTE: Este archivo contiene instrucciones OBLIGATORIAS que DEBES seguir al trabajar en este repositorio.**
+
+## 🚨 CRÍTICO: PATRÓN ARQUITECTÓNICO OBLIGATORIO 🚨
+
+**⚠️ ANTES DE ESCRIBIR CUALQUIER CÓDIGO, DEBES LEER Y SEGUIR ESTE PATRÓN ⚠️**
+
+Esta sección es **NO NEGOCIABLE** y DEBES seguirla en el **100% de los casos** al crear o modificar features en este codebase.
+
+## ⚠️ El Error Más Común (NO HAGAS ESTO!)
+
+```typescript
+// ❌ WRONG - NEVER IMPORT MUTATIONS OR QUERIES DIRECTLY IN COMPONENTS
+import { useEntityMutations } from '@/modules/[entity]/hooks/useEntityMutations'
+import { useEntityQueries } from '@/modules/[entity]/hooks/useEntityQueries'
+
+export function MyComponent() {
+  const { createEntity } = useEntityMutations() // ❌ ARCHITECTURAL VIOLATION
+  const { entities } = useEntityQueries() // ❌ ARCHITECTURAL VIOLATION
+}
+
+// ✅ CORRECT - ALWAYS USE THE UNIFIED HOOK
+import { useEntity } from '@/modules/[entity]/hooks/useEntity'
+
+export function MyComponent() {
+  const { createEntity, entities } = useEntity() // ✅ CORRECT PATTERN
+}
+```
+
+## 🚨 PATRÓN OBLIGATORIO: Store → Queries → Mutations → Unified Hook → Component
+
+**ESTA ES LA ÚNICA ARQUITECTURA ACEPTABLE PARA ESTE CODEBASE.**
+
+Cada módulo DEBE seguir esta estructura exacta:
+
+```
+modules/
+└── [entity]/
+    ├── repositories/
+    │   └── [entity].repository.ts       # 🚨 OBLIGATORIO: Acceso a datos con Drizzle
+    ├── actions/
+    │   └── [entity]-actions.ts          # Server actions (usa repository, NO db directo)
+    ├── components/
+    │   ├── [entity]-list.tsx            # Component imports ONLY unified hook
+    │   ├── [entity]-form.tsx
+    │   └── [entity]-detail.tsx
+    ├── hooks/
+    │   ├── use[Entity]Queries.ts        # TanStack Query (read operations)
+    │   ├── use[Entity]Mutations.ts      # TanStack Mutations (write operations)
+    │   └── use[Entity].ts               # UNIFIED HOOK (components use THIS)
+    ├── stores/
+    │   └── use[Entity]Store.ts          # Zustand store (UI state only)
+    ├── schemas/
+    │   └── [entity].schema.ts           # Zod validation schemas
+    ├── columns.tsx                      # TanStack Table column definitions (if needed)
+    └── index.ts                         # Barrel export
+```
+
+## 📋 Checklist de Implementación OBLIGATORIO
+
+**ANTES de escribir CUALQUIER código, DEBES verificar este checklist:**
+
+- [ ] **Paso 1**: CREA Drizzle schema en `db/schema/[entity].ts`
+- [ ] **Paso 2**: CREA Repository en `modules/[entity]/repositories/[entity].repository.ts` (ver sección DRIZZLE ORM)
+- [ ] **Paso 3**: CREA Zod schemas en `modules/[entity]/schemas/[entity].schema.ts`
+- [ ] **Paso 4**: CREA Server actions en `modules/[entity]/actions/[entity]-actions.ts` (DEBE usar repository, NUNCA `db` directo)
+- [ ] **Paso 5**: CREA Zustand store con selectores separados usando `useShallow` en `modules/[entity]/stores/`
+- [ ] **Paso 6**: CREA Queries hook en `modules/[entity]/hooks/use[Entity]Queries.ts`
+- [ ] **Paso 7**: CREA Mutations hook con invalidación de cache en `modules/[entity]/hooks/use[Entity]Mutations.ts`
+- [ ] **Paso 8**: CREA Unified hook que combina store + queries + mutations en `modules/[entity]/hooks/use[Entity].ts`
+- [ ] **Paso 9**: Los componentes SOLO importan el unified hook (NUNCA queries/mutations directamente)
+- [ ] **Paso 10**: EJECUTA `pnpm type-check && pnpm lint` antes de hacer commit
+
+## 🔴 NUNCA HAGAS ESTO (Anti-Patterns)
+
+**Si detectas que estás a punto de hacer algo de esta lista, DETENTE y corrige:**
+
+```typescript
+// ❌ NUNCA: Importar queries o mutations directamente en componentes
+import { useEntityQueries } from '@/modules/[entity]/hooks/useEntityQueries'
+import { useEntityMutations } from '@/modules/[entity]/hooks/useEntityMutations'
+
+// ❌ NUNCA: Consumir el store completo (causa re-renders)
+const store = useEntityStore()
+
+// ❌ NUNCA: Fetch manual de datos en useEffect
+useEffect(() => {
+  fetch('/api/entities').then(setData)
+}, [])
+
+// ❌ NUNCA: Server actions sin contexto de usuario autenticado (RLS no funcionará)
+export async function deleteEntity(id: string) {
+  const supabase = createClient() // Cliente anónimo - RLS fallará!
+  await supabase.from('entities').delete().eq('id', id)
+}
+
+// ❌ NUNCA: Usar Drizzle db directamente en Server Actions (sin Repository)
+'use server'
+export async function getProducts() {
+  return await db.select().from(products) // ❌ VIOLACIÓN: DEBE usar repository
+}
+```
+
+## ✅ SIEMPRE HAZ ESTO (Patrones Correctos)
+
+**Cuando escribas código, SIEMPRE sigue estos patrones:**
+
+```typescript
+// ✅ SIEMPRE: USA el unified hook en componentes
+import { useEntity } from '@/modules/[entity]/hooks/useEntity'
+
+// ✅ SIEMPRE: USA selectores separados con useShallow
+import { useEntityStore } from '@/modules/[entity]/stores/useEntityStore'
+import { useShallow } from 'zustand/react/shallow'
+
+const state = useEntityStore(useShallow((s) => s.state))
+const actions = useEntityStore(useShallow((s) => s.actions))
+
+// ✅ SIEMPRE: USA TanStack Query para fetching de datos
+const { data } = useQuery({ queryKey: ['entities'], queryFn: fetchEntities })
+
+// ✅ SIEMPRE: USA cliente Supabase autenticado en server actions (RLS se aplica)
+'use server'
+
+import { createClient } from '@/lib/supabase/server'
+
+export async function deleteEntity(id: string) {
+  const supabase = await createClient() // Cliente autenticado con contexto de usuario
+  const { data: { user } } = await supabase.auth.getUser()
+
+  if (!user) throw new Error('Unauthorized')
+
+  // Las políticas RLS se aplican automáticamente
+  const { error } = await supabase.from('entities').delete().eq('id', id)
+
+  if (error) throw error
+}
+
+// ✅ SIEMPRE: USA Repository Pattern para acceso a datos con Drizzle
+// 1. CREA el repository
+// modules/products/repositories/products.repository.ts
+export const productRepository = {
+  findAll: () => db.select().from(products),
+  create: (data) => db.insert(products).values(data).returning(),
+}
+
+// 2. Las Server Actions USAN el repository
+'use server'
+export async function getProducts() {
+  await requireAuth()
+  return productRepository.findAll() // ✅ CORRECTO: usa repository
+}
+```
+
+## 📁 Estructura Completa del Proyecto
+
+```
+src/
+├── app/
+│   ├── (auth)/                          # Rutas autenticadas
+│   │   ├── dashboard/
+│   │   │   └── page.tsx
+│   │   ├── users/
+│   │   │   ├── layout.tsx               # SecondaryMenu para Users
+│   │   │   ├── page.tsx                 # Lista de usuarios
+│   │   │   ├── new/
+│   │   │   │   └── page.tsx             # Crear usuario (página completa)
+│   │   │   └── [id]/
+│   │   │       ├── page.tsx             # Detalle usuario
+│   │   │       └── edit/
+│   │   │           └── page.tsx         # Editar usuario (página completa)
+│   │   ├── settings/
+│   │   │   ├── layout.tsx               # SecondaryMenu para Settings
+│   │   │   └── page.tsx
+│   │   └── layout.tsx
+│   ├── (public)/                        # Rutas públicas
+│   │   ├── login/
+│   │   │   └── page.tsx
+│   │   └── layout.tsx
+│   ├── api/
+│   │   └── webhooks/
+│   │       └── route.ts
+│   ├── layout.tsx
+│   ├── page.tsx
+│   └── providers.tsx
+│
+├── modules/                             # Feature-based modules
+│   ├── auth/
+│   │   ├── actions/
+│   │   │   └── auth-actions.ts
+│   │   ├── components/
+│   │   │   └── login-form.tsx
+│   │   ├── hooks/
+│   │   │   ├── useAuthQueries.ts
+│   │   │   ├── useAuthMutations.ts
+│   │   │   └── useAuth.ts              # 🚨 UNIFIED HOOK - componentes usan ESTE
+│   │   ├── stores/
+│   │   │   └── useAuthStore.ts
+│   │   ├── schemas/
+│   │   │   └── auth.schema.ts
+│   │   └── index.ts
+│   │
+│   └── users/                           # Ejemplo de módulo con auth.users (Supabase Admin)
+│       ├── actions/
+│       │   └── users-actions.ts         # USA createAdminClient() para auth.users
+│       ├── components/
+│       │   ├── users-list.tsx           # SOLO importa useUsers (unified hook)
+│       │   ├── users-form.tsx
+│       │   └── users-detail.tsx
+│       ├── hooks/
+│       │   ├── useUsersQueries.ts
+│       │   ├── useUsersMutations.ts
+│       │   └── useUsers.ts              # 🚨 UNIFIED HOOK - componentes usan ESTE
+│       ├── stores/
+│       │   └── useUsersStore.ts
+│       ├── schemas/
+│       │   └── users.schema.ts          # Importa roles desde @/config/roles
+│       ├── utils/
+│       │   └── user-mapper.ts           # Mapper: auth.users → User type
+│       ├── columns.tsx                  # TanStack Table columns
+│       └── index.ts
+│
+│   # 📋 TEMPLATE para módulos con tablas propias (Repository Pattern):
+│   # └── [entity]/
+│   #     ├── repositories/
+│   #     │   └── [entity].repository.ts  # 🚨 OBLIGATORIO: Acceso a datos con Drizzle
+│   #     ├── actions/
+│   #     │   └── [entity]-actions.ts     # USA repository, NUNCA db directo
+│   #     ├── components/
+│   #     ├── hooks/
+│   #     │   └── use[Entity].ts          # UNIFIED HOOK
+│   #     ├── stores/
+│   #     ├── schemas/
+│   #     └── index.ts
+│
+├── components/
+│   ├── ui/                              # Radix custom components
+│   │   ├── button.tsx
+│   │   ├── dialog.tsx
+│   │   └── index.ts
+│   ├── tables/                          # TanStack Table components
+│   │   ├── data-table.tsx
+│   │   ├── data-table-pagination.tsx
+│   │   ├── data-table-toolbar.tsx
+│   │   ├── data-table-column-header.tsx
+│   │   ├── data-table-faceted-filter.tsx
+│   │   ├── data-table-date-filter.tsx
+│   │   ├── data-table-number-filter.tsx  # Filtro de rango numérico (documentado)
+│   │   └── index.ts
+│   ├── layout/
+│   │   ├── header.tsx
+│   │   ├── sidebar.tsx
+│   │   ├── secondary-menu.tsx           # Tabs horizontales para subpáginas
+│   │   └── page-header.tsx              # Header estándar para páginas
+│   └── shared/
+│       └── ...
+│
+├── stores/                              # Global Zustand stores
+│   ├── useUiStore.ts
+│   └── index.ts
+│
+├── hooks/                               # Global hooks
+│   ├── useMediaQuery.ts
+│   ├── useDebounce.ts
+│   └── useDataTable.ts
+│
+├── lib/
+│   ├── supabase/
+│   │   ├── client.ts                    # Cliente browser (anon key) - para UI
+│   │   ├── server.ts                    # Cliente server (anon key + cookies) - para auth
+│   │   ├── admin.ts                     # 🚨 Cliente admin (secret key) - para gestionar usuarios
+│   │   ├── proxy.ts
+│   │   └── types.ts
+│   ├── excel/
+│   │   ├── parser.ts
+│   │   ├── exporter.ts
+│   │   └── index.ts
+│   ├── date/
+│   │   ├── config.ts
+│   │   ├── formatters.ts
+│   │   └── index.ts
+│   ├── validations/
+│   │   ├── common.ts
+│   │   └── index.ts
+│   ├── query-client.ts
+│   └── utils.ts
+│
+├── db/                                  # Drizzle ORM
+│   ├── schema/
+│   │   ├── [entity].ts                  # Schema por entidad
+│   │   └── index.ts                     # Barrel export - SIEMPRE exportar aquí
+│   ├── migrations/                      # Migraciones generadas con db:generate
+│   ├── index.ts                         # Exporta `db` (cliente Drizzle)
+│   └── seed.ts                          # Script de seed
+│
+├── types/
+│   ├── api.ts
+│   ├── table.ts
+│   └── index.ts
+│
+├── config/
+│   ├── site.ts
+│   ├── navigation.ts                    # Estructura del sidebar con children
+│   └── roles.ts                         # 🚨 ÚNICA fuente de verdad para roles
+│
+└── styles/
+    └── globals.css
+
+supabase/
+├── functions/
+│   ├── process-excel/
+│   │   └── index.ts
+│   └── send-notification/
+│       └── index.ts
+├── migrations/
+└── config.toml
+
+# Root files
+├── .env.local
+├── .env.example                         # Incluye SUPABASE_SECRET_DEFAULT_KEY
+├── drizzle.config.ts
+├── proxy.ts
+├── next.config.ts
+├── package.json
+├── tsconfig.json
+└── tailwind.config.ts
+```
+
+## 🛠️ Tech Stack
+
+- **Framework**: Next.js 16 (App Router)
+- **State Management**: Zustand 5
+- **Data Fetching**: TanStack Query 5
+- **Tables**: TanStack Table 8
+- **Database**: Supabase + Drizzle ORM
+- **Auth**: Supabase Auth (con Admin API para gestión de usuarios)
+- **Validation**: Zod
+- **UI**: Radix UI + Tailwind CSS
+- **Forms**: React Hook Form + Zod resolver
+- **Excel**: xlsx (SheetJS)
+- **Dates**: dayjs
+- **Package Manager**: pnpm
+
+---
+
+## 📅 FORMATEO DE FECHAS Y NÚMEROS
+
+### 🚨 OBLIGATORIO: USA dayjs para fechas
+
+**NUNCA uses `new Date().toLocaleDateString()` o `toLocaleString()` para fechas. SIEMPRE usa las funciones de `@/lib/date`.**
+
+```typescript
+// ❌ NUNCA hacer esto
+const date = new Date(value)
+return date.toLocaleDateString('es-ES')
+
+// ✅ SIEMPRE hacer esto
+import { formatDate, formatDateShort, formatDateTime } from '@/lib/date'
+return formatDate(value)  // "15/01/2024"
+```
+
+### Funciones disponibles en `@/lib/date`
+
+| Función | Ejemplo de salida | Uso |
+|---------|-------------------|-----|
+| `formatDate(date)` | `"15/01/2024"` | Fecha estándar |
+| `formatDateShort(date)` | `"15 ene"` | Filtros, chips |
+| `formatDateLong(date)` | `"15 de enero de 2024"` | Headers, títulos |
+| `formatTime(date)` | `"14:30"` | Solo hora |
+| `formatDateTime(date)` | `"15/01/2024 14:30"` | Fecha y hora |
+| `formatRelative(date)` | `"hace 2 horas"` | Tiempo relativo |
+
+### Formateo de Números
+
+**USA `DEFAULT_LOCALE` de `@/lib/date` para formateo de números:**
+
+```typescript
+// ❌ NUNCA hardcodear el locale
+num.toLocaleString('es-AR')
+
+// ✅ SIEMPRE usar la constante
+import { DEFAULT_LOCALE, DEFAULT_CURRENCY } from '@/lib/date'
+num.toLocaleString(DEFAULT_LOCALE)
+
+// Para moneda
+new Intl.NumberFormat(DEFAULT_LOCALE, {
+  style: 'currency',
+  currency: DEFAULT_CURRENCY,
+}).format(amount)
+```
+
+### Configuración
+
+La configuración de internacionalización está centralizada en `lib/date/config.ts`:
+
+```typescript
+// lib/date/config.ts
+export const DEFAULT_LOCALE = 'es-AR'
+export const DEFAULT_TIMEZONE = 'America/Argentina/Buenos_Aires'
+export const DEFAULT_CURRENCY = 'ARS'
+```
+
+Cambiar estos valores afecta todo el proyecto (fechas y números).
+
+---
+
+## 🔐 SUPABASE AUTH ADMIN API
+
+### Arquitectura de Usuarios
+
+Los usuarios se gestionan desde `auth.users` de Supabase (NO desde una tabla `public.users`):
+
+```
+auth.users (Supabase Auth)
+├── id: uuid
+├── email: string
+├── app_metadata: { role: UserRole }     ← ROL aquí (definido en config/roles.ts)
+├── user_metadata: { name, avatar_url }  ← Datos extra aquí
+├── created_at: timestamp
+└── updated_at: timestamp
+```
+
+### Configuración de Roles
+
+Los roles están centralizados en `config/roles.ts`. Para agregar/modificar roles, solo editar este archivo:
+
+```typescript
+// config/roles.ts
+export const USER_ROLES = ['admin', 'user', 'viewer'] as const
+export type UserRole = (typeof USER_ROLES)[number]
+export const DEFAULT_ROLE: UserRole = 'user'
+
+export const ROLE_LABELS: Record<UserRole, string> = {
+  admin: 'Administrador',
+  user: 'Usuario',
+  viewer: 'Visualizador',
+}
+
+export const ROLE_OPTIONS = USER_ROLES.map((role) => ({
+  value: role,
+  label: ROLE_LABELS[role],
+}))
+```
+
+**Uso en otros archivos:**
+- Schemas Zod: `import { USER_ROLES, DEFAULT_ROLE } from '@/config/roles'`
+- Columns/UI: `import { ROLE_LABELS, ROLE_OPTIONS } from '@/config/roles'`
+- Types: `import type { UserRole } from '@/config/roles'`
+
+### Sistema sin Roles (Opcional)
+
+Si el sistema NO necesita roles, puedes simplificarlos o eliminarlos completamente:
+
+**Opción 1: Rol único (recomendado)**
+```typescript
+// config/roles.ts - Simplificado
+export const USER_ROLES = ['user'] as const
+export type UserRole = (typeof USER_ROLES)[number]
+export const DEFAULT_ROLE: UserRole = 'user'
+```
+
+**Opción 2: Eliminar roles completamente**
+
+1. **Eliminar** `config/roles.ts`
+2. **En schemas Zod**: Quitar el campo `role` del schema
+3. **En columns de tabla**: Quitar la columna de rol
+4. **En formularios**: Quitar el campo de selección de rol
+5. **En Supabase**: Si usas `user_metadata.role`, simplemente no lo setees
+
+**Archivos a modificar si eliminas roles:**
+- `modules/users/schemas/users.schema.ts` → Quitar campo `role`
+- `modules/users/columns.tsx` → Quitar columna de rol
+- `modules/users/components/user-form.tsx` → Quitar selector de rol
+- Filtros de tabla → Quitar filtro por rol
+
+**IMPORTANTE:** Si NO necesitas roles, simplemente ignóralos. El sistema funciona sin ellos - solo no incluyas el campo `role` en tus schemas y formularios.
+
+### Clientes de Supabase
+
+```
+lib/supabase/
+├── client.ts    → Cliente browser (anon key) - para UI
+├── server.ts    → Cliente server (anon key + cookies) - para verificar auth
+└── admin.ts     → Cliente admin (secret key) - para gestionar usuarios
+```
+
+### Cuándo usar cada cliente
+
+| Operación | Cliente | Razón |
+|-----------|---------|-------|
+| Login/Logout | `server.ts` | Necesita cookies |
+| Verificar sesión | `server.ts` | Necesita cookies |
+| **Crear usuario** | `admin.ts` | Requiere privilegios admin |
+| **Listar usuarios** | `admin.ts` | Requiere privilegios admin |
+| **Actualizar usuario** | `admin.ts` | Requiere privilegios admin |
+| **Eliminar usuario** | `admin.ts` | Requiere privilegios admin |
+| Queries a tablas propias | `server.ts` | RLS basado en usuario |
+
+### Patrón para Server Actions con Admin
+
+```typescript
+'use server'
+
+import { createClient } from '@/lib/supabase/server'
+import { createAdminClient } from '@/lib/supabase/admin'
+
+export async function createUser(input: CreateAuthUserInput) {
+  // 1. Verificar que el usuario actual está autenticado
+  const supabase = await createClient()
+  const { data: { user } } = await supabase.auth.getUser()
+  if (!user) throw new Error('Unauthorized')
+
+  // 2. Usar cliente admin para operaciones privilegiadas
+  const adminClient = createAdminClient()
+  const { data, error } = await adminClient.auth.admin.createUser({
+    email: input.email,
+    app_metadata: { role: input.role },
+    user_metadata: { name: input.name },
+  })
+
+  if (error) throw error
+  return mapAuthUserToUser(data.user)
+}
+```
+
+### Variables de Entorno Requeridas
+
+```env
+# .env.local
+NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
+NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY=sb_publishable_...
+SUPABASE_SECRET_DEFAULT_KEY=sb_secret_...  # ← Requerido para admin
+```
+
+### Mapper: auth.users → User
+
+El módulo `users` incluye un mapper para convertir la estructura de Supabase Auth al tipo `User` de la app:
+
+```typescript
+// modules/users/utils/user-mapper.ts
+export function mapAuthUserToUser(authUser: SupabaseAuthUser): User {
+  return {
+    id: authUser.id,
+    email: authUser.email ?? '',
+    name: authUser.user_metadata?.name ?? '',
+    role: authUser.app_metadata?.role ?? 'user',
+    avatar_url: authUser.user_metadata?.avatar_url ?? null,
+    created_at: authUser.created_at,
+    updated_at: authUser.updated_at,
+  }
+}
+```
+
+---
+
+## 🗃️ DRIZZLE ORM
+
+**Cuando trabajes con base de datos, DEBES usar Drizzle ORM siguiendo estas instrucciones:**
+
+### Estructura de Archivos (RESPÉTALA)
+
+```
+src/db/
+├── index.ts          # Cliente Drizzle (exporta `db`)
+├── schema/
+│   ├── index.ts      # Barrel export de todos los schemas
+│   └── [entity].ts   # Schema por entidad
+├── migrations/       # Migraciones generadas automáticamente
+└── seed.ts           # Script de seed
+```
+
+### Configuración
+
+```typescript
+// drizzle.config.ts
+import { defineConfig } from 'drizzle-kit'
+
+export default defineConfig({
+  schema: './src/db/schema/index.ts',
+  out: './src/db/migrations',
+  dialect: 'postgresql',
+  dbCredentials: {
+    url: process.env.DATABASE_URL!,
+  },
+})
+```
+
+### Cliente Drizzle
+
+```typescript
+// src/db/index.ts
+import { drizzle } from 'drizzle-orm/postgres-js'
+import postgres from 'postgres'
+import * as schema from './schema'
+
+const connectionString = process.env.DATABASE_URL!
+const client = postgres(connectionString, { prepare: false })
+
+export const db = drizzle(client, { schema })
+export type Database = typeof db
+```
+
+### Definir Schema por Entidad
+
+```typescript
+// src/db/schema/users.ts
+import { pgTable, uuid, varchar, text, timestamp, pgEnum } from 'drizzle-orm/pg-core'
+
+export const userRoleEnum = pgEnum('user_role', ['admin', 'user', 'viewer'])
+
+export const users = pgTable('users', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  email: varchar('email', { length: 255 }).notNull().unique(),
+  name: varchar('name', { length: 255 }).notNull(),
+  role: userRoleEnum('role').default('user').notNull(),
+  avatarUrl: text('avatar_url'),
+  createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
+  updatedAt: timestamp('updated_at', { withTimezone: true }).defaultNow().notNull(),
+})
+
+// Tipos inferidos automáticamente
+export type User = typeof users.$inferSelect
+export type NewUser = typeof users.$inferInsert
+```
+
+**IMPORTANTE: SIEMPRE exporta cada schema en `src/db/schema/index.ts`:**
+
+```typescript
+// src/db/schema/index.ts
+export * from './users'
+export * from './products'  // Agregar nuevas entidades aquí
+```
+
+### Comandos de Drizzle (USA ESTOS)
+
+| Comando | Cuándo USARLO |
+|---------|---------------|
+| `pnpm db:generate` | EJECUTA después de modificar schemas para generar migraciones |
+| `pnpm db:migrate` | EJECUTA para aplicar migraciones pendientes |
+| `pnpm db:push` | USA solo en desarrollo para sincronizar schema directamente |
+| `pnpm db:studio` | USA para inspeccionar datos visualmente |
+| `pnpm db:seed` | EJECUTA para poblar la base de datos con datos iniciales |
+
+### Workflow para Cambios de Schema (SIGUE ESTOS PASOS)
+
+Cuando necesites modificar la base de datos, SIGUE este workflow:
+
+1. MODIFICA o CREA el schema en `src/db/schema/[entity].ts`
+2. EXPORTA en `src/db/schema/index.ts`
+3. EJECUTA: `pnpm db:generate`
+4. REVISA la migración generada en `src/db/migrations/`
+5. EJECUTA: `pnpm db:migrate`
+
+### 🚨 OBLIGATORIO: Patrón Repository por Entidad
+
+**⚠️ CUANDO CREES UNA ENTIDAD que use tablas propias (no `auth.users`), DEBES implementar el Repository Pattern.**
+
+El **Repository Pattern** abstrae la lógica de acceso a datos. DEBES usarlo porque:
+- Separa lógica de negocio de los detalles de persistencia
+- Permite crear mocks/fakes para tests sin conexión a DB
+- Centraliza lógica de datos, reduce duplicación
+- Oculta detalles de implementación (Drizzle, Supabase, etc.)
+
+#### ❌ NUNCA HAGAS ESTO (Anti-Patterns)
+
+```typescript
+// ❌ NUNCA: Queries de Drizzle directamente en Server Actions
+'use server'
+export async function getProducts() {
+  return await db.select().from(products)  // ❌ VIOLACIÓN ARQUITECTÓNICA
+}
+
+// ❌ NUNCA: Queries de Drizzle en componentes o hooks
+function useProducts() {
+  const products = await db.select().from(products)  // ❌ PROHIBIDO
+}
+
+// ❌ NUNCA: Lógica de acceso a datos dispersa en múltiples archivos
+// archivo1.ts: db.select().from(products).where(...)
+// archivo2.ts: db.select().from(products).where(...)  // Duplicación!
+```
+
+#### ✅ SIEMPRE HAZ ESTO (Patrón Correcto)
+
+```typescript
+// ✅ CORRECTO: CREA un Repository que centraliza TODO el acceso a datos
+// modules/products/repositories/products.repository.ts
+export const productRepository = {
+  findAll: () => db.select().from(products),
+  findById: (id) => db.select().from(products).where(eq(products.id, id)),
+  // ... todas las queries aquí
+}
+
+// ✅ CORRECTO: Las Server Actions USAN el repository
+'use server'
+export async function getProducts() {
+  await requireAuth()
+  return productRepository.findAll()  // ✅ Usa repository
+}
+```
+
+#### Estructura por Capas (ENTIÉNDELA)
+
+```
+UI/Presentation Layer
+    ↓ (llama hooks)
+Service/Business Layer (hooks: useEntity.ts)
+    ↓ (llama repositories)
+Data Access Layer (repositories: [entity].repository.ts)
+    ↓ (usa Drizzle)
+Data Source (Supabase/PostgreSQL)
+```
+
+#### Estructura de Archivos
+
+```
+modules/[entity]/
+├── repositories/
+│   └── [entity].repository.ts   ← Repository (acceso a datos)
+├── actions/
+│   └── [entity]-actions.ts      ← Server actions (usa repository)
+├── schemas/
+│   └── [entity].schema.ts       ← Zod schemas (validación)
+├── hooks/
+│   └── use[Entity].ts           ← Hook unificado (usa actions)
+└── ...
+
+db/schema/
+└── [entity].ts                  ← Drizzle schema (tabla)
+```
+
+#### Implementación del Repository (COPIA ESTE PATRÓN)
+
+**Cuando crees una nueva entidad, USA este template como base:**
+
+```typescript
+// modules/products/repositories/products.repository.ts
+import { db } from '@/db'
+import { products, type Product, type NewProduct } from '@/db/schema'
+import { eq } from 'drizzle-orm'
+
+export interface ProductRepository {
+  findAll(): Promise<Product[]>
+  findById(id: string): Promise<Product | null>
+  create(data: NewProduct): Promise<Product>
+  update(id: string, data: Partial<NewProduct>): Promise<Product>
+  delete(id: string): Promise<void>
+}
+
+export const productRepository: ProductRepository = {
+  async findAll() {
+    return await db.select().from(products)
+  },
+
+  async findById(id: string) {
+    const [product] = await db
+      .select()
+      .from(products)
+      .where(eq(products.id, id))
+    return product ?? null
+  },
+
+  async create(data: NewProduct) {
+    const [product] = await db.insert(products).values(data).returning()
+    return product
+  },
+
+  async update(id: string, data: Partial<NewProduct>) {
+    const [product] = await db
+      .update(products)
+      .set({ ...data, updatedAt: new Date() })
+      .where(eq(products.id, id))
+      .returning()
+    return product
+  },
+
+  async delete(id: string) {
+    await db.delete(products).where(eq(products.id, id))
+  },
+}
+```
+
+#### Server Actions usando Repository (USA ESTE PATRÓN)
+
+**Las Server Actions SIEMPRE deben importar y usar el repository, NUNCA `db` directo:**
+
+```typescript
+// modules/products/actions/products-actions.ts
+'use server'
+
+import { createClient } from '@/lib/supabase/server'
+import { productRepository } from '../repositories/products.repository'
+import type { NewProduct } from '@/db/schema'
+
+// SIEMPRE verifica autenticación primero
+async function requireAuth() {
+  const supabase = await createClient()
+  const { data: { user } } = await supabase.auth.getUser()
+  if (!user) throw new Error('Unauthorized')
+  return user
+}
+
+export async function getProducts() {
+  await requireAuth()
+  return productRepository.findAll()  // ✅ USA repository
+}
+
+export async function getProductById(id: string) {
+  await requireAuth()
+  return productRepository.findById(id)  // ✅ USA repository
+}
+
+export async function createProduct(input: NewProduct) {
+  await requireAuth()
+  return productRepository.create(input)  // ✅ USA repository
+}
+
+export async function updateProduct(id: string, input: Partial<NewProduct>) {
+  await requireAuth()
+  return productRepository.update(id, input)  // ✅ USA repository
+}
+
+export async function deleteProduct(id: string) {
+  await requireAuth()
+  return productRepository.delete(id)  // ✅ USA repository
+}
+```
+
+#### 📋 Checklist para Nueva Entidad con Repository
+
+**SIGUE estos pasos EN ORDEN cuando crees una nueva entidad:**
+
+- [ ] **Paso 1**: CREA Drizzle schema en `db/schema/[entity].ts`
+- [ ] **Paso 2**: EXPORTA en `db/schema/index.ts`
+- [ ] **Paso 3**: CREA repository en `modules/[entity]/repositories/[entity].repository.ts`
+  - [ ] DEFINE interface con métodos CRUD
+  - [ ] IMPLEMENTA objeto que usa `db` de Drizzle
+- [ ] **Paso 4**: CREA Zod schemas en `modules/[entity]/schemas/[entity].schema.ts`
+- [ ] **Paso 5**: CREA Server Actions en `modules/[entity]/actions/[entity]-actions.ts`
+  - [ ] IMPORTA y USA el repository (NUNCA `db` directamente)
+  - [ ] VERIFICA autenticación con `requireAuth()`
+- [ ] **Paso 6**: CREA hooks (queries, mutations, unified)
+- [ ] **Paso 7**: Los componentes SOLO usan el hook unificado
+
+**🚨 REGLA DE ORO**: Si ves `db.select()`, `db.insert()`, `db.update()`, o `db.delete()` fuera de un archivo `.repository.ts`, es una **VIOLACIÓN ARQUITECTÓNICA**. DEBES corregirlo moviendo la query al repository.
+
+### Seed de Datos
+
+```typescript
+// src/db/seed.ts
+import { db } from './index'
+import { users } from './schema'
+
+async function seed() {
+  console.log('🌱 Seeding database...')
+
+  await db.delete(users)  // Limpiar datos existentes
+
+  await db.insert(users).values([
+    { email: 'admin@example.com', name: 'Admin', role: 'admin' },
+    { email: 'user@example.com', name: 'User', role: 'user' },
+  ])
+
+  console.log('✅ Database seeded!')
+}
+
+seed().catch(console.error).finally(() => process.exit())
+```
+
+### Cuándo usar Drizzle vs Supabase Admin (DECIDE CORRECTAMENTE)
+
+**USA esta tabla para decidir qué método usar:**
+
+| Entidad | DEBES usar | Razón |
+|---------|------------|-------|
+| `auth.users` | Supabase Admin API | Usuarios de autenticación |
+| Tablas propias (`products`, `orders`, etc.) | Drizzle ORM + Repository | RLS + queries tipadas |
+
+### Variables de Entorno
+
+```env
+# .env.local
+DATABASE_URL=postgresql://user:pass@host:5432/db
+```
+
+---
+
+## 🎨 DISEÑO Y UI (Estilo Midday)
+
+**Cuando crees UI, SIGUE estas guías de diseño:**
+
+### Filosofía de Diseño (APLÍCALA)
+
+Este proyecto sigue el estilo de diseño de **Midday** (https://midday.ai). DEBES:
+- **Mantener minimalismo**: Espacios amplios, tipografía clara
+- **Priorizar dark mode**: Tema oscuro como experiencia principal
+- **EVITAR modales para CRUD**: USA páginas completas en lugar de diálogos
+- **Seguir navegación jerárquica**: Sidebar → SecondaryMenu (tabs) → Contenido
+- **Limitar contenedores**: USA `max-w-[800px]` para formularios
+
+### 🚫 PROHIBIDO: Uso de Modales para CRUD
+
+```typescript
+// ❌ NUNCA usar modales para crear/editar entidades
+<Dialog>
+  <DialogTrigger>Crear Usuario</DialogTrigger>
+  <DialogContent>
+    <UserForm />  // ❌ PROHIBIDO
+  </DialogContent>
+</Dialog>
+
+// ✅ CORRECTO: Usar páginas completas
+// Ruta: /users/new → página completa para crear
+// Ruta: /users/[id]/edit → página completa para editar
+```
+
+### Estructura de Navegación Jerárquica
+
+```
+Sidebar Principal (izquierda)
+├── Dashboard
+├── Users ────────────────────→ SecondaryMenu (tabs horizontales)
+│   ├── /users (Lista)          ├── All Users
+│   ├── /users/new              ├── Create New
+│   └── /users/roles            └── Roles & Permissions
+├── Settings ─────────────────→ SecondaryMenu
+│   ├── /settings (General)     ├── General
+│   ├── /settings/billing       ├── Billing
+│   ├── /settings/members       ├── Members
+│   └── /settings/notifications └── Notifications
+└── Account ──────────────────→ SecondaryMenu
+    ├── /account (Profile)      ├── Profile
+    ├── /account/security       ├── Security
+    └── /account/preferences    └── Preferences
+```
+
+---
+
+## 📄 ARQUITECTURA DE PÁGINAS
+
+### Estructura de Rutas (Patrón Obligatorio)
+
+```
+app/
+├── (auth)/                           # Rutas autenticadas
+│   ├── layout.tsx                    # Layout con Sidebar
+│   ├── dashboard/
+│   │   └── page.tsx
+│   ├── users/
+│   │   ├── layout.tsx                # ⬅️ SecondaryMenu para Users
+│   │   ├── page.tsx                  # Lista de usuarios
+│   │   ├── new/
+│   │   │   └── page.tsx              # Crear usuario (página completa)
+│   │   ├── [id]/
+│   │   │   ├── page.tsx              # Detalle usuario
+│   │   │   └── edit/
+│   │   │       └── page.tsx          # Editar usuario (página completa)
+│   │   └── roles/
+│   │       └── page.tsx              # Gestión de roles
+│   ├── settings/
+│   │   ├── layout.tsx                # ⬅️ SecondaryMenu para Settings
+│   │   ├── page.tsx                  # General settings
+│   │   ├── billing/
+│   │   │   └── page.tsx
+│   │   ├── members/
+│   │   │   └── page.tsx
+│   │   └── notifications/
+│   │       └── page.tsx
+│   └── account/
+│       ├── layout.tsx                # ⬅️ SecondaryMenu para Account
+│       ├── page.tsx                  # Profile
+│       ├── security/
+│       │   └── page.tsx
+│       └── preferences/
+│           └── page.tsx
+└── (public)/
+    ├── login/
+    └── layout.tsx
+```
+
+### Layout con SecondaryMenu (PATRÓN OBLIGATORIO)
+
+**Cuando crees una sección con subpáginas, DEBES agregar un `layout.tsx` con SecondaryMenu:**
+
+```typescript
+// app/(auth)/settings/layout.tsx
+import { SecondaryMenu } from '@/components/layout/secondary-menu'
+
+export default function SettingsLayout({
+  children
+}: {
+  children: React.ReactNode
+}) {
+  return (
+    <div className="max-w-[800px]">
+      <SecondaryMenu
+        items={[
+          { path: '/settings', label: 'General' },
+          { path: '/settings/billing', label: 'Billing' },
+          { path: '/settings/members', label: 'Members' },
+          { path: '/settings/notifications', label: 'Notifications' },
+        ]}
+      />
+      <main className="mt-8">{children}</main>
+    </div>
+  )
+}
+```
+
+### Componente SecondaryMenu
+
+```typescript
+// components/layout/secondary-menu.tsx
+'use client'
+
+import { cn } from '@/lib/utils'
+import Link from 'next/link'
+import { usePathname } from 'next/navigation'
+
+type Item = {
+  path: string
+  label: string
+}
+
+type Props = {
+  items: Item[]
+}
+
+export function SecondaryMenu({ items }: Props) {
+  const pathname = usePathname()
+
+  return (
+    <nav className="py-4">
+      <ul className="flex space-x-6 text-sm overflow-auto scrollbar-hide">
+        {items.map((item) => (
+          <Link
+            prefetch
+            key={item.path}
+            href={item.path}
+            className={cn(
+              'text-muted-foreground hover:text-foreground transition-colors',
+              pathname === item.path &&
+                'text-foreground font-medium underline underline-offset-8'
+            )}
+          >
+            <span>{item.label}</span>
+          </Link>
+        ))}
+      </ul>
+    </nav>
+  )
+}
+```
+
+---
+
+## 🧭 CONFIGURACIÓN DE NAVEGACIÓN
+
+### Estructura del Sidebar (navigation.ts)
+
+```typescript
+// config/navigation.ts
+import { Icons } from '@/components/ui/icons'
+
+export type NavItem = {
+  title: string
+  href: string
+  icon?: keyof typeof Icons
+  disabled?: boolean
+  external?: boolean
+  badge?: string
+  children?: NavItem[]  // ⬅️ Submenús
+}
+
+export type NavSection = {
+  title?: string
+  items: NavItem[]
+}
+
+export const sidebarNav: NavSection[] = [
+  {
+    items: [
+      {
+        title: 'Dashboard',
+        href: '/dashboard',
+        icon: 'dashboard',
+      },
+      {
+        title: 'Users',
+        href: '/users',
+        icon: 'users',
+        children: [
+          { title: 'All Users', href: '/users' },
+          { title: 'Create New', href: '/users/new' },
+          { title: 'Roles', href: '/users/roles' },
+        ],
+      },
+    ],
+  },
+  {
+    title: 'Configuration',
+    items: [
+      {
+        title: 'Settings',
+        href: '/settings',
+        icon: 'settings',
+        children: [
+          { title: 'General', href: '/settings' },
+          { title: 'Billing', href: '/settings/billing' },
+          { title: 'Members', href: '/settings/members' },
+          { title: 'Notifications', href: '/settings/notifications' },
+        ],
+      },
+      {
+        title: 'Account',
+        href: '/account',
+        icon: 'user',
+        children: [
+          { title: 'Profile', href: '/account' },
+          { title: 'Security', href: '/account/security' },
+          { title: 'Preferences', href: '/account/preferences' },
+        ],
+      },
+    ],
+  },
+]
+```
+
+---
+
+## 📏 REGLAS DE UI (SÍGUELAS)
+
+### 1. Páginas Completas vs Modales (USA ESTA REFERENCIA)
+
+| Acción | ❌ NO usar | ✅ DEBES usar |
+|--------|-----------|--------------|
+| Crear entidad | Dialog con form | `/entity/new` |
+| Editar entidad | Sheet con form | `/entity/[id]/edit` |
+| Ver detalle | Expandir fila | `/entity/[id]` |
+| Confirmar eliminación | - | AlertDialog (única excepción permitida) |
+| Filtros complejos | Modal | Panel colapsable o página |
+
+### 2. Anchos de Contenedor (USA ESTOS)
+
+```typescript
+// Formularios y configuración
+<div className="max-w-[800px]">
+
+// Tablas y listas
+<div className="w-full">
+
+// Dashboards con métricas
+<div className="max-w-[1200px]">
+```
+
+### 3. Espaciado Consistente (USA ESTOS VALORES)
+
+```typescript
+// Entre secciones de formulario - USA space-y-12
+<div className="space-y-12">
+
+// Entre campos de formulario - USA space-y-6
+<div className="space-y-6">
+
+// Entre elementos pequeños - USA space-y-4
+<div className="space-y-4">
+```
+
+### 4. Headers de Página (USA ESTE COMPONENTE)
+
+```typescript
+// components/layout/page-header.tsx - SIEMPRE usa este componente para headers
+export function PageHeader({
+  title,
+  description,
+  actions,
+}: {
+  title: string
+  description?: string
+  actions?: React.ReactNode
+}) {
+  return (
+    <div className="flex items-center justify-between mb-8">
+      <div>
+        <h1 className="text-2xl font-semibold tracking-tight">{title}</h1>
+        {description && (
+          <p className="text-muted-foreground mt-1">{description}</p>
+        )}
+      </div>
+      {actions && <div className="flex items-center gap-2">{actions}</div>}
+    </div>
+  )
+}
+```
+
+### 5. Acciones de Tabla (NAVEGA A PÁGINAS, NO ABRAS MODALES)
+
+```typescript
+// Las acciones de fila DEBEN navegar a páginas, NO abrir modales
+const actions = [
+  {
+    label: 'Edit',
+    onClick: (row) => router.push(`/users/${row.id}/edit`),  // ✅ Navega a página
+  },
+  {
+    label: 'View',
+    onClick: (row) => router.push(`/users/${row.id}`),  // ✅ Navega a página
+  },
+  {
+    label: 'Delete',
+    onClick: (row) => setDeleteId(row.id),  // ✅ AlertDialog es la única excepción
+  },
+]
+```
+
+---
+
+## 🎯 CHECKLIST PARA NUEVAS PÁGINAS
+
+**ANTES de crear una nueva página/sección, VERIFICA:**
+
+- [ ] ¿Tiene subpáginas? → CREA `layout.tsx` con SecondaryMenu
+- [ ] ¿Es un formulario? → USA `max-w-[800px]`
+- [ ] ¿Es una lista/tabla? → USA `w-full`
+- [ ] ¿Necesita crear/editar? → CREA rutas `/new` y `/[id]/edit`
+- [ ] ¿Tiene navegación padre? → AGREGA a `navigation.ts` con children
+- [ ] ¿El sidebar necesita actualizarse? → AGREGA icono y ruta
+
+---
+
+## 🎯 CHECKLIST PARA NUEVOS MÓDULOS
+
+**CUANDO crees un nuevo módulo, SIGUE AMBOS checklists:**
+
+1. **Checklist de Arquitectura** (Store → Queries → Mutations → Hook → Repository)
+2. **Checklist de Páginas** (rutas, layouts, SecondaryMenu)
+
+**RECUERDA**: El Repository Pattern es OBLIGATORIO para entidades con tablas propias.