openprompt-lang 0.3.0

package/docs/referencia-metodologia/docs/CONVENCIONES_DOCUMENTACION.md

@@ -0,0 +1,209 @@
+# Convenciones de Documentación para Proyectos React + Supabase
+
+> Estándar para documentar tablas DB, arquitectura y flujos de datos. Integrado con openPrompt-Lang y las fases de la metodología.
+
+---
+
+## 1. Documentación de Tablas DB
+
+Cada tabla se documenta con este formato en `docs/DB/TABLES.md`:
+
+```markdown
+## products
+
+Tabla de productos del catálogo.
+
+| Columna | Tipo | Nulo | Default | FK | Descripción |
+|---|---|---|---|---|---|
+| id | `uuid` | NO | `gen_random_uuid()` | — | Primary key |
+| name | `text` | NO | — | — | Nombre del producto |
+| slug | `text` | NO | — | — | URL slug (único) |
+| description | `text` | SÍ | — | — | Descripción larga |
+| price | `numeric(10,2)` | NO | `0` | — | Precio en USD |
+| category_id | `uuid` | NO | — | `categories(id)` | Categoría |
+| active | `bool` | NO | `true` | — | Visible en catálogo |
+| metadata | `jsonb` | SÍ | `'{}'` | — | Datos flexibles |
+| created_at | `timestamptz` | NO | `now()` | — | Fecha de creación |
+| updated_at | `timestamptz` | NO | `now()` | — | Última modificación |
+
+### Índices
+| Nombre | Columnas | Tipo | Condición |
+|---|---|---|---|
+| `idx_products_category` | `category_id` | B-tree | — |
+| `idx_products_active` | `created_at` | B-tree partial | `WHERE active = true` |
+| `idx_products_name_search` | `name` | GIN trgm | — |
+
+### RLS
+| Operación | Política | USING |
+|---|---|---|
+| `SELECT` | `products_select_all` | `true` (catálogo público) |
+| `INSERT` | `products_insert_admin` | `auth.role() = 'admin'` |
+| `UPDATE` | `products_update_admin` | `auth.role() = 'admin'` |
+| `DELETE` | `products_delete_admin` | `auth.role() = 'admin'` |
+
+### Relaciones
+- `category_id` → `categories(id)` — Cada producto pertenece a una categoría
+- `order_items.product_id` → `products(id)` — Un producto aparece en muchos pedidos
+
+### Notas
+- `slug` tiene unique constraint + trigger de generación automática desde `name`
+- `metadata` almacena campos variables por tipo de producto (peso, color, talla)
+- Los productos inactivos no se muestran en el catálogo pero se mantienen para histórico
+```
+
+---
+
+## 2. Diagramas de Arquitectura (Mermaid)
+
+### 2.1 Árbol de Componentes (`graph TD`)
+
+Usar para visualizar la jerarquía de componentes de una página o feature:
+
+```mermaid
+graph TD
+    App --> Router
+    Router --> LoginPage
+    Router --> DashboardPage
+    Router --> ProductsPage
+    DashboardPage --> Header
+    DashboardPage --> StatsGrid
+    DashboardPage --> RecentOrders
+    StatsGrid --> StatCard
+    StatCard --> Icon
+    StatCard --> Value
+    ProductsPage --> ProductTable
+    ProductsPage --> ProductFilters
+    ProductTable --> RowActions
+    RowActions --> EditButton
+    RowActions --> DeleteButton
+    DeleteButton --> ConfirmModal
+```
+
+En markdown:
+````markdown
+```mermaid
+graph TD
+    App --> Router
+    Router --> DashboardPage
+    DashboardPage --> Header
+    DashboardPage --> StatsGrid
+```
+````
+
+### 2.2 Flujo de Datos (`sequenceDiagram`)
+
+Usar para visualizar interacciones usuario → UI → hook → servicio → DB:
+
+```mermaid
+sequenceDiagram
+    actor U as Usuario
+    participant PG as ProductsPage
+    participant H as useProducts
+    participant S as supabase
+    participant DB as PostgreSQL
+
+    U->>PG: Abre página de productos
+    PG->>H: mount
+    H->>S: .from('products').select('id,name,price')
+    S->>DB: SELECT con RLS
+    DB-->>S: rows
+    S-->>H: { data }
+    H-->>PG: render table
+    U->>PG: Click eliminar producto
+    PG->>ConfirmModal: open
+    U->>ConfirmModal: Confirmar
+    ConfirmModal->>H: delete(id)
+    H->>S: .update({ deleted_at: now() })
+    S-->>H: success
+    H-->>PG: refetch
+    Note over PG: Soft delete + refetch automático
+```
+
+### 2.3 Modelo Entidad-Relación (`erDiagram`)
+
+Para proyectos con más de 5 tablas relacionadas:
+
+```mermaid
+erDiagram
+    users ||--o{ orders : "places"
+    users {
+        uuid id PK
+        text email
+        text name
+    }
+    orders ||--|{ order_items : contains
+    orders {
+        uuid id PK
+        uuid user_id FK
+        numeric total
+        timestamptz created_at
+    }
+    products ||--o{ order_items : includes
+    products {
+        uuid id PK
+        text name
+        numeric price
+    }
+    order_items {
+        uuid id PK
+        uuid order_id FK
+        uuid product_id FK
+        int quantity
+        numeric price
+    }
+```
+
+---
+
+## 3. Documentación de APIs / RPC
+
+Cada función RPC se documenta con contrato de entrada/salida:
+
+```markdown
+## create_order
+
+Crea un pedido con sus items en una transacción.
+
+### Contrato
+| Campo | Descripción |
+|---|---|
+| **In** | `p_user_id: UUID`, `p_items: JSONB[{product_id, quantity, price}]` |
+| **Out** | `{ order_id: UUID, total: NUMERIC }` |
+| **Errores** | `23503` (producto no existe), `P0001` (stock insuficiente) |
+
+### Seguridad
+- `SECURITY DEFINER` — ejecuta con permisos del creador
+- RLS en tabla `orders` filtrada por `user_id`
+- Solo accesible vía RPC (no hay INSERT directo desde el cliente)
+
+### Uso desde frontend
+```typescript
+const { data, error } = await supabase.rpc('create_order', {
+  p_user_id: userId,
+  p_items: cart.map(i => ({ product_id: i.id, quantity: i.qty, price: i.price }))
+})
+if (error?.code === '23503') {
+  toast.error('Uno o más productos no existen')
+}
+```
+```
+
+---
+
+## 4. Integración con las Fases de la Metodología
+
+| Fase | Documentación generada | Archivos |
+|---|---|---|
+| **Fase 5 — Scaffolding** | Estructura de carpetas + routing + tipos globales | `docs/ARQUITECTURA.md`, diagrama component tree |
+| **Fase 6 — Backlog** | Definición de tablas + RLS + contratos RPC | `docs/DB/TABLES.md`, `docs/DB/RPCS.md` |
+| **Fase 7 — Desarrollo** | Por feature: secuencia de datos + componentes | Diagramas `sequenceDiagram` en cada PR/commit |
+| **Fase 8 — Entrega** | Documentación completa + índices + migraciones | Todo `docs/DB/`, diagramas actualizados |
+
+### Checklist por feature
+
+- [ ] ¿La tabla está documentada en `docs/DB/TABLES.md`?
+- [ ] ¿Las RLS policies están definidas por operación?
+- [ ] ¿Los índices cubren los filtros principales?
+- [ ] ¿Hay un `sequenceDiagram` del flujo principal?
+- [ ] ¿Los tipos TypeScript están generados desde la DB?
+- [ ] ¿La migración SQL está versionada con `supabase migration new`?

package/docs/referencia-metodologia/docs/PROMPTS/INDEX.md

@@ -0,0 +1,73 @@
+---
+title: Biblioteca de Prompts
+description: Índice de prompts reutilizables para desarrollo asistido por IA
+tags: [prompts, index, biblioteca]
+version: 1.0.0
+---
+
+# Biblioteca de Prompts
+
+> Cada prompt aquí ha sido probado al menos una vez en proyectos reales. Son plantillas para copiar-pegar, no recetas teóricas. La estructura sigue el formato determinista de `Framework de Desarrollo Asistido por IA.md` sección 9.
+
+---
+
+## Cómo usar
+
+1. Encuentra el prompt que necesitas por categoría
+2. Copia el contenido del archivo `.md` correspondiente
+3. Pega en la IA junto con la referencia: *"Revisa docs/AGENTS.md y docs/Framework de Desarrollo Asistido por IA.md antes de responder"*
+4. Ajusta los `{placeholder}` según tu contexto
+
+> 📚 **Documentación complementaria:**
+> - `docs/CONVENCIONES_DB.md` — 18 prácticas de base de datos (RLS, índices, paginación, batch, etc.)
+> - `docs/CONVENCIONES_DOCUMENTACION.md` — Estándares de documentación (tablas DB, diagramas Mermaid, contratos RPC)
+
+---
+
+## PLANTILLAS — Prompts genéricos reutilizables
+
+| # | Archivo | Para qué sirve | Stack |
+|---|---|---|---|
+| 01 | [01-hook-supabase.md](PLANTILLAS/01-hook-supabase.md) | Hook CRUD genérico con Supabase `<T>` | React + Supabase |
+| 02 | [02-componente-ui.md](PLANTILLAS/02-componente-ui.md) | Componente UI con variantes (cva) | React + Tailwind |
+| 03 | [03-pagina-feature.md](PLANTILLAS/03-pagina-feature.md) | Página completa con composición de componentes | React + Tailwind |
+| 04 | [04-comando-tauri.md](PLANTILLAS/04-comando-tauri.md) | Comando Tauri en Rust + llamada desde frontend | Tauri v2 + Rust |
+| 05 | [05-store-zustand.md](PLANTILLAS/05-store-zustand.md) | Store de estado global con Zustand | React + Zustand |
+| 06 | [06-servicio-supabase.md](PLANTILLAS/06-servicio-supabase.md) | Servicio CRUD con manejo de errores | Supabase + TS |
+| 07 | [07-formulario-validacion.md](PLANTILLAS/07-formulario-validacion.md) | Formulario con validación (react-hook-form + zod) | React + Zod |
+| 08 | [08-hook-capacitor.md](PLANTILLAS/08-hook-capacitor.md) | Hook para plugin nativo de Capacitor | Capacitor + React |
+| 09 | [09-refactor-division.md](PLANTILLAS/09-refactor-division.md) | Refactorizar componente grande en módulos pequeños | React + TS |
+| 10 | [10-scaffolding-inicial.md](PLANTILLAS/10-scaffolding-inicial.md) | Scaffolding completo de un feature/módulo | React + TS |
+| 11 | [11-supabase-crud-service.md](PLANTILLAS/11-supabase-crud-service.md) | Servicio CRUD con batch, RLS, signed URLs, errores por código | Supabase + TS |
+| 12 | [12-supabase-hook-usetable.md](PLANTILLAS/12-supabase-hook-usetable.md) | Hook useSupabaseList con keyset pagination y filtros | React + Supabase |
+| 13 | [13-tauri-command-rust.md](PLANTILLAS/13-tauri-command-rust.md) | Comando Tauri en Rust con validación de inputs | Tauri v2 + Rust |
+| 14 | [14-tauri-wrapper-typescript.md](PLANTILLAS/14-tauri-wrapper-typescript.md) | Wrapper TS para comandos Tauri con tipado estricto | Tauri v2 + TS |
+| 15 | [15-documentar-tabla-db.md](PLANTILLAS/15-documentar-tabla-db.md) | Documentar tabla DB: columnas, tipos, RLS, índices | Docs + Supabase |
+| 16 | [16-diagrama-arquitectura.md](PLANTILLAS/16-diagrama-arquitectura.md) | Diagramas Mermaid de componente tree + flujo de datos | Docs + Mermaid |
+| 17 | [17-documentar-api-rpc.md](PLANTILLAS/17-documentar-api-rpc.md) | Documentar función RPC con contrato in/out + errores | Docs + Supabase |
+
+---
+
+## STACK — Prompts específicos por tecnología
+
+| Archivo | Para qué sirve |
+|---|---|
+| [react-web-puro.md](STACK/react-web-puro.md) | Contexto completo para proyecto web React + Supabase (sin mobile/desktop) |
+| [ionic-capacitor.md](STACK/ionic-capacitor.md) | Contexto para proyecto mobile con Ionic + Capacitor |
+| [tauri-desktop.md](STACK/tauri-desktop.md) | Contexto para proyecto desktop con Tauri |
+
+---
+
+## HISTORIAL — Prompts archivados
+
+Los prompts que se usan en proyectos reales se archivean aquí con anotaciones de qué funcionó y qué no. Ver `HISTORIAL/`.
+
+---
+
+## Reglas de la biblioteca
+
+1. **Un prompt por archivo.** Si un prompt cubre dos cosas distintas, se divide.
+2. **Metadatos obligatorios** (title, tags, usado_en, fecha) al inicio del archivo.
+3. **Solo se archiva lo probado.** Si no se usó en un proyecto real, no se agrega.
+4. **Los fallos también se guardan** en `HISTORIAL/` con nota de por qué no funcionó.
+5. **Si se modifica un prompt**, se actualiza `ultima_modificacion` y se agrega changelog al final.

package/docs/referencia-metodologia/docs/PROMPTS/PLANTILLAS/01-hook-supabase.md

@@ -0,0 +1,79 @@
+---
+title: Hook CRUD genérico con Supabase
+tags: [hook, supabase, generics, typescript]
+usado_en: []
+fecha_creacion: 2026-05-13
+ultima_modificacion: 2026-05-13
+---
+
+## Cuándo usar
+
+Cuando necesites un hook que obtenga datos de una tabla de Supabase con filtros, ordenamiento y tipado genérico. Ideal para listas, tablas y vistas que consumen datos de una sola tabla.
+
+## Prompt
+
+```markdown
+## Contexto
+Stack: React 18 + TypeScript + Vite + Supabase.
+Convenciones: hooks en src/hooks/, un hook por archivo, máximo 80 líneas.
+Patrón: hook genérico con <T> para tipado dinámico.
+Referencia: docs/Framework de Desarrollo Asistido por IA.md sección 7 (patrón custom hook genérico).
+
+## Objetivo
+Crear el hook `useSupabaseTable<T>` que haga CRUD a una tabla de Supabase con tipado genérico.
+
+## Especificaciones técnicas
+- Archivo: `src/hooks/useSupabaseTable.ts`
+- Retornar: `{ data: T[]; loading: boolean; error: string | null; refetch: () => void }`
+- Parámetros: `{ table: string; select?: string; filters?: Record<string, unknown>; order?: { column: string; ascending?: boolean } }`
+- Máximo 65 líneas
+- Usar el cliente de Supabase desde `src/services/supabase/client.ts`
+
+## Reglas estrictas
+- Tipar con TypeScript usando genéricos `<T>` 
+- `loading` debe iniciar en `true`
+- `error` debe ser `string | null`, nunca `any`
+- El fetch debe ejecutarse en un `useEffect` con dependencias `[table, JSON.stringify(filters)]`
+- Si `filters` cambia, debe refetch automáticamente
+
+## Anti-patrones (prohibido)
+- NO usar `any`
+- NO mezclar lógica de UI en el hook
+- NO hacer fetch en el render, solo en useEffect
+- NO mutar el estado directamente
+
+## Ejemplo correcto
+```typescript
+interface UseTableOptions<T> {
+  table: string
+  select?: string
+  filters?: Record<string, unknown>
+}
+
+interface UseTableResult<T> {
+  data: T[]
+  loading: boolean
+  error: string | null
+  refetch: () => void
+}
+
+export function useSupabaseTable<T>({ table, select = "*", filters }: UseTableOptions<T>): UseTableResult<T> {
+  // implementación con useState + useEffect + supabase.from(table).select(select)
+}
+```
+
+## Ejemplo incorrecto
+```typescript
+// ❌ Sin genéricos, sin loading state, any en filters
+export function useTable(table: string) {
+  const [data, setData] = useState<any[]>([])
+  useEffect(() => {
+    supabase.from(table).select("*").then((res: any) => setData(res.data))
+  }, [])
+  return data
+}
+```
+
+## Formato de salida esperado
+Archivo completo listo para copiar a `src/hooks/useSupabaseTable.ts`.
+```

package/docs/referencia-metodologia/docs/PROMPTS/PLANTILLAS/02-componente-ui.md

@@ -0,0 +1,82 @@
+---
+title: Componente UI con variantes (cva)
+tags: [componente, ui, cva, tailwind, shadcn]
+usado_en: []
+fecha_creacion: 2026-05-13
+ultima_modificacion: 2026-05-13
+---
+
+## Cuándo usar
+
+Cuando necesites crear un componente de UI reutilizable con variantes visuales (ej: Button con primary/secondary/ghost, Input con estados error/success). Sigue el patrón shadcn/ui con `class-variance-authority`.
+
+## Prompt
+
+```markdown
+## Contexto
+Stack: React 18 + TypeScript + Tailwind CSS 3.4.
+Convenciones: componentes atómicos en src/components/ui/, un componente por archivo, máximo 120 líneas, 100% Tailwind.
+Patrón: shadcn/ui con cva (class-variance-authority) para variantes.
+Referencia: docs/Framework de Desarrollo Asistido por IA.md sección 7 (patrón componente UI reutilizable).
+
+## Objetivo
+Crear el componente `{ComponenteName}` con variantes visuales usando cva.
+
+## Especificaciones técnicas
+- Archivo: `src/components/ui/{ComponenteName}.tsx`
+- Usar `class-variance-authority` para las variantes
+- Usar `memo` para evitar re-renderizados innecesarios
+- Extender las props nativas del elemento HTML correspondiente
+- Exportar: el componente + `{componenteName}Variants` (el objeto cva)
+- Incluir `displayName` en el componente
+- Máximo 90 líneas
+
+## Variantes requeridas
+- variant: { lista de variantes, ej: primary, secondary, ghost, destructive }
+- size: { lista de tamaños, ej: sm, default, lg }
+
+## Reglas estrictas
+- Tipar con `VariantProps<typeof componenteVariants>` para las variantes
+- Usar `React.forwardRef` o pasar ref directamente según el elemento
+- `memo` obligatorio para evitar re-renders
+- Incluir clases base comunes en el primer argumento de cva
+- Valores por defecto en `defaultVariants`
+
+## Anti-patrones (prohibido)
+- NO usar CSS personalizado o modules
+- NO usar `any`
+- NO mezclar lógica de negocio en el componente UI
+- NO omitir `displayName`
+
+## Ejemplo correcto
+```typescript
+import { cva, type VariantProps } from "class-variance-authority"
+import { memo } from "react"
+
+const buttonVariants = cva("inline-flex items-center justify-center rounded-md text-sm font-medium", {
+  variants: {
+    variant: {
+      primary: "bg-blue-600 text-white hover:bg-blue-700",
+      secondary: "bg-gray-100 text-gray-900 hover:bg-gray-200",
+    },
+    size: {
+      default: "h-10 px-4 py-2",
+      sm: "h-9 rounded-md px-3",
+    },
+  },
+  defaultVariants: { variant: "primary", size: "default" },
+})
+
+interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {}
+
+const Button = memo<ButtonProps>(({ className, variant, size, ...props }) => (
+  <button className={buttonVariants({ variant, size, className })} {...props} />
+))
+Button.displayName = "Button"
+
+export { Button, buttonVariants }
+```
+
+## Formato de salida esperado
+Archivo completo listo para `src/components/ui/{ComponenteName}.tsx`.
+```

package/docs/referencia-metodologia/docs/PROMPTS/PLANTILLAS/03-pagina-feature.md

@@ -0,0 +1,70 @@
+---
+title: Página completa con composición de componentes
+tags: [pagina, feature, composicion, layout]
+usado_en: []
+fecha_creacion: 2026-05-13
+ultima_modificacion: 2026-05-13
+---
+
+## Cuándo usar
+
+Cuando necesites crear una página completa de un feature. El prompt fuerza la división en componentes más pequeños desde el inicio, evitando páginas monolíticas.
+
+## Prompt
+
+```markdown
+## Contexto
+Stack: React 18 + TypeScript + Tailwind CSS + {router}.
+Convenciones: páginas en src/features/{feature}/, componentes específicos en src/features/{feature}/components/, hooks en src/features/{feature}/hooks/.
+Límite: FeaturePage max 200 líneas. Cada componente hijo max 120 líneas.
+Referencia: docs/Framework de Desarrollo Asistido por IA.md sección 2 (estructura features/).
+
+## Objetivo
+Crear la página `{FeatureName}Page` con sus componentes y hooks necesarios.
+
+## Especificaciones técnicas
+Archivos a crear:
+- `src/features/{feature}/{FeatureName}Page.tsx` (máx 200 líneas, solo composición)
+- `src/features/{feature}/components/{SubComponente1}.tsx` (máx 120 líneas)
+- `src/features/{feature}/components/{SubComponente2}.tsx` (máx 120 líneas)
+- `src/features/{feature}/hooks/use{FeatureName}.ts` (máx 80 líneas)
+
+## Secciones visuales de la página
+1. {Header: título, acciones principales}
+2. {Listado/Tabla: datos principales}
+3. {Modal/Formulario: crear/editar}
+4. {Empty state: cuando no hay datos}
+
+## Reglas estrictas
+- La página SOLO compone componentes hijos, no implementa lógica directamente
+- Cada sección identificable debe ser un componente separado
+- La lógica de datos va en el hook `use{FeatureName}`, no en la página
+- Tipos específicos del feature van en `src/features/{feature}/types/`
+
+## Anti-patrones (prohibido)
+- NO crear una página monolítica de 500+ líneas
+- NO poner lógica de fetching en el componente de página
+- NO mezclar estilos inline con Tailwind
+
+## Estructura esperada del archivo principal
+```typescript
+// {FeatureName}Page.tsx
+function {FeatureName}Page() {
+  const { data, loading, error, handleCreate, handleDelete } = use{FeatureName}()
+  
+  if (loading) return <Skeleton />
+  if (error) return <ErrorState message={error} />
+  if (!data.length) return <EmptyState />
+  
+  return (
+    <div className="p-6">
+      <PageHeader title="..." onAdd={handleCreate} />
+      <DataTable data={data} onDelete={handleDelete} />
+    </div>
+  )
+}
+```
+
+## Formato de salida esperado
+Todos los archivos del feature listos para copiar, con imports correctos entre ellos.
+```

package/docs/referencia-metodologia/docs/PROMPTS/PLANTILLAS/04-comando-tauri.md

@@ -0,0 +1,56 @@
+---
+title: Comando Tauri en Rust + llamada frontend
+tags: [tauri, rust, comando, ipc]
+usado_en: []
+fecha_creacion: 2026-05-13
+ultima_modificacion: 2026-05-13
+---
+
+## Cuándo usar
+
+Cuando necesites crear un comando Tauri (Rust) que se llame desde el frontend React. Típicamente para operaciones de sistema de archivos, procesos locales o acceso a hardware que no cubre Capacitor.
+
+## Prompt
+
+```markdown
+## Contexto
+Stack: Tauri v2 + Rust + React + TypeScript.
+Convenciones: comandos Rust en src-tauri/src/commands/, cada comando en su propio archivo.
+Llamadas desde frontend en src/services/tauri/.
+Referencia: docs/Framework de Desarrollo Asistido por IA.md sección 1 (convenciones Tauri).
+
+## Objetivo
+Crear el comando Tauri `{command_name}` que {descripción de lo que hace}.
+
+## Especificaciones técnicas
+Archivos a crear/modificar:
+- `src-tauri/src/commands/{command_name}.rs` (comando Rust)
+- `src-tauri/src/main.rs` (registrar el comando)
+- `src/services/tauri/{command_name}.ts` (wrapper tipado para frontend)
+
+### Comando Rust
+- Anotación: `#[tauri::command]`
+- Firma: `fn {command_name}({params}) -> Result<{output}, String>`
+- Validar todos los inputs antes de ejecutar
+- Devolver error legible en español
+
+### Wrapper frontend
+- Usar `import { invoke } from "@tauri-apps/api/core"`
+- Tipar entrada y salida con interfaces
+- Manejar error con try/catch
+
+## Reglas estrictas
+- Tipado estricto en Rust (String, no &str para parámetros)
+- No permitir path traversal si el comando accede al sistema de archivos
+- Devolver error específico, no genérico
+- El wrapper frontend debe tipar el invoke con genéricos
+
+## Anti-patrones (prohibido)
+- NO usar `std::fs::read_to_string` sin validar path primero
+- NO exponer comandos inseguros sin validación de permisos
+- NO poner lógica de negocio compleja en Rust si puede ir en el frontend
+- NO mezclar con lógica de Capacitor en el mismo servicio
+
+## Formato de salida esperado
+Código Rust del comando + wrapper TypeScript + instrucción de registro en main.rs.
+```

package/docs/referencia-metodologia/docs/PROMPTS/PLANTILLAS/05-store-zustand.md

@@ -0,0 +1,74 @@
+---
+title: Store de estado global con Zustand
+tags: [zustand, store, estado-global, typescript]
+usado_en: []
+fecha_creacion: 2026-05-13
+ultima_modificacion: 2026-05-13
+---
+
+## Cuándo usar
+
+Cuando necesites estado global compartido entre múltiples componentes (sesión de usuario, UI state, carrito, etc). Zustand es la opción recomendada sobre Context por su simplicidad y performance.
+
+## Prompt
+
+```markdown
+## Contexto
+Stack: React 18 + TypeScript + Zustand.
+Convenciones: stores en src/store/, un store por dominio, máximo 100 líneas.
+Patrón: store con actions y state separados (slice pattern si es complejo).
+Referencia: docs/Framework de Desarrollo Asistido por IA.md sección 2 (estructura store/).
+
+## Objetivo
+Crear el store Zustand `{name}Store` para manejar {descripción del dominio}.
+
+## Especificaciones técnicas
+- Archivo: `src/store/{name}Store.ts`
+- Usar `import { create } from "zustand"`
+- Estado: {listar las propiedades del estado}
+- Acciones: {listar las acciones: set, reset, fetch, etc.}
+- Integrar con {algún servicio externo si aplica}
+- Máximo 80 líneas
+
+## Reglas estrictas
+- Tipar todo el estado y las acciones con interfaces
+- Acciones que modifican el estado deben ser inmutables (usar spread o immer)
+- Si hay lógica async, las acciones deben ser async y manejar loading/error
+- Exportar el hook `use{Name}Store` como default
+
+## Anti-patrones (prohibido)
+- NO mutar el estado directamente
+- NO poner lógica de UI en el store
+- NO duplicar estado que ya existe en Supabase/BD local
+- NO crear stores globales para estado que podría ser prop drilling simple
+
+## Ejemplo parcial
+```typescript
+import { create } from "zustand"
+
+interface AuthState {
+  user: User | null
+  loading: boolean
+  login: (email: string, password: string) => Promise<void>
+  logout: () => void
+}
+
+export const useAuthStore = create<AuthState>((set) => ({
+  user: null,
+  loading: false,
+  login: async (email, password) => {
+    set({ loading: true })
+    try {
+      const user = await authService.login(email, password)
+      set({ user, loading: false })
+    } catch {
+      set({ loading: false })
+    }
+  },
+  logout: () => set({ user: null }),
+}))
+```
+
+## Formato de salida esperado
+Archivo completo listo para `src/store/{name}Store.ts`.
+```