openprompt-lang 0.3.0

package/docs/referencia-metodologia/Indice General.md

@@ -0,0 +1,83 @@
+---
+title: Metodología de Desarrollo Asistido por IA
+author: Matías Retamal
+version: 1.0.0
+tags:
+  - metodologia
+  - saas
+  - ia
+  - arquitectura
+date: 2026-04-25
+---
+
+# 🧠 Metodología de Desarrollo Asistido por IA
+
+> [!info] Sobre este documento
+> Este índice interactivo contiene la estructura definitiva del ciclo de vida de desarrollo de software para proyectos SaaS y Pymes, optimizado para el trabajo Full-Stack y la delegación algorítmica de código mediante Inteligencia Artificial.
+
+---
+
+## 🗂️ Índice General
+
+> [!abstract] ETAPA I: Descubrimiento y Planificación Estratégica
+> Comprende desde la primera reunión hasta la congelación del presupuesto y el alcance del MVP.
+>
+> **[[#1. Fase 1: Levantamiento de requisitos generales (Discovery)|1. Fase 1: Levantamiento de requisitos generales (Discovery)]]**
+> - a. Detallado del funcionamiento del negocio y su dolor principal
+> - b. Definición de límites comerciales (Alcance inicial)
+>
+> **[[#2. Fase 2: Traducción técnica y contratos (Historias de usuario)|2. Fase 2: Traducción técnica y contratos (Historias de usuario)]]**
+> - a. Creación de Historias de Usuario
+> - b. Traducción a definiciones de métodos (El Contrato Estructural)
+>
+> **[[#3. Fase 3: Diseño UI/UX y estructura visual (Wireframing)|3. Fase 3: Diseño UI/UX y estructura visual (Wireframing)]]**
+> - a. Diseño de Prototipos interactivos
+> - b. Estructura de vistas y componentes (Preparación para React)
+>
+> **[[#4. Fase 4: Especificación de requisitos e iteración con el cliente|4. Fase 4: Especificación de requisitos e iteración con el cliente]]**
+> - a. Integración de correcciones del cliente (Feedback Loop)
+> - b. Ciclo de preguntas, control de alcance y presupuesto final
+> - c. Especificación de nuevos elementos funcionales
+> - d. Bibliotecas necesarias y factibilidad técnica
+> - e. Checklist de Aprobación: Inicio Oficial de Desarrollo (Go / No-Go)
+
+> [!example] ETAPA II: Arquitectura y Preparación para IA
+> Diseño de la arquitectura de carpetas, esqueletos de código (Scaffolding) y división estricta de tareas.
+>
+> **[[#5. Fase 5: Estructuración y maquetado de funciones (Scaffolding)|5. Fase 5: Estructuración y maquetado de funciones (Scaffolding)]]**
+> - a. Creación de estructura básica de archivos de documentación
+> - b. Definición de estructura de carpetas definitiva
+> - c. Creación de archivos y esqueletos base (Scaffolding)
+> - d. Ejemplo práctico de definición técnica (Contrato en Código)
+> - e. Diagramas de apoyo técnico
+> - f. Prompt Maestro para Generación de Scaffolding con IA
+>
+> **[[#6. Fase 6: Estructuración del backlog y división de tareas|6. Fase 6: Estructuración del backlog y división de tareas]]**
+> - a. Sistema de Gestión Centralizado (Enfoque JSON-Driven)
+> - b. Estrategia de Desarrollo por Capas (Layered Development)
+> - c. Granularidad Extrema para la IA (Micro-Tasking)
+> - d. Refinamiento Continuo (Refactoring Temprano)
+
+> [!tip] ETAPA III: Desarrollo, Testing y Puesta en Producción
+> Programación activa, control de versiones semántico y transferencia del software al cliente.
+>
+> **[[#7. Fase 7: Desarrollo activo, pruebas y control de versiones|7. Fase 7: Desarrollo activo, pruebas y control de versiones]]**
+> - a. Metodología de Pruebas (Testing y Criterios de Aceptación)
+> - b. Control de Versiones y Trazabilidad (Micro-Commits)
+> - c. Ejemplo Práctico de un Commit Estandarizado
+> - d. Gestión de Despliegues y Versionado Semántico
+> - e. Sistema de Criterios para Cambio de Versión (SemVer Checklist)
+>
+> **[[#8. Fase 8: Entrega, capacitación y mantenimiento|8. Fase 8: Entrega, capacitación y mantenimiento]]**
+> - a. Protocolo de Entrega y Cierre Administrativo
+> - b. Capacitación y Onboarding del Cliente
+> - c. Políticas de Soporte y Canales de Comunicación
+> - d. Mantenimiento, Monitoreo y Escalabilidad
+
+> [!quote] 📎 ETAPA IV: Anexos Comerciales y Legales
+> **[[#Anexos Finales|Documentos de Respaldo y Estandarización]]**
+> - 💰 Anexo A: Tabla de Precios de Referencia (UF / CLP)
+> - 📄 Anexo B: Plantilla - Propuesta Inicial de Desarrollo
+> - 🤝 Anexo C: Plantilla - Acta de Entrega Final y Descargos de Responsabilidad
+
+---

package/docs/referencia-metodologia/Prompt refactorizar o creacion desde cero.md

@@ -0,0 +1,50 @@
+`**SYSTEM/CONTEXT:**`  
+`Eres un Arquitecto de Software Senior especializado en React 18+, TypeScript, Tailwind CSS y proyectos SaaS escalables. **OBLIGATORIO: Respeta y maximiza convenciones React para reusabilidad** (composition > inheritance, custom hooks para lógica, compound components, single responsibility, generics TS, shadcn/ui patterns con Tailwind utility-first, memo/useCallback, evita HOCs si hooks bastan). Analiza el proyecto, crea /docs/, audita priorizando reusabilidad perdida/ganada.`
+
+`**OBJETIVO PRINCIPAL:**`  
+`Mismo que antes, pero **en TODAS secciones integra reusabilidad React**: scaffolding con componentes reutilizables (ej: ui/Button.tsx genérico), ejemplos muestran composition, auditoría mide % de código reusable.`
+
+`**ESTRUCTURA /docs/:** Igual, + nueva sección **07-REUSABILIDAD-REACT.md** (convenciones aplicadas, métricas reusabilidad).`
+
+`**INSTRUCCIONES DETALLADAS (actualizadas):**`
+
+1. `**Auditoría (AUDITORIA.md):**`  
+    `Agrega columna | % Reusabilidad | (ej: "Components duplicados: 40% → refactor a hooks genéricos"). Plan acción: "Prioriza hooks como useFormInput reusable en orders/properties" .`
+    
+2. `**Scaffolding (tree-scaffolding.txt):**`  
+    `Enfatiza reusabilidad:`
+    
+    `text`
+    
+    `src/ ├── components/ │   └── ui/ (shadcn-style reutilizables: Button.tsx, Input.tsx, Card.tsx, index.ts exports) ├── hooks/ (useQueryProps.ts genérico, useAuth.ts, useFormReusable.ts) ├── features/properties/ (compone ui/Button + hooks)`
+    
+    `Nombres: ui/DataTable.tsx (genérico con <T>), `hooks/useCRUD.ts<T>`.`
+    
+`3. **Ejemplos (correctos/incorrectos.md):**`
+    
+    `- **Correcto (Reusabilidad):**`
+        
+        `tsx`
+        
+        ``// ui/Button.tsx (shadcn pattern, variants Tailwind) import { cva, type VariantProps } from 'class-variance-authority'; import { memo } from 'react'; const buttonVariants = cva("..."); // variants: primary, destructive interface ButtonProps extends VariantProps<typeof buttonVariants> { children: React.ReactNode; onClick?: () => void; } export const Button = memo<ButtonProps>(({ variant, ...props }) => <button className={buttonVariants({ variant })} {...props} />); // Uso reusable: <Button variant="primary" onClick={handleSave}>Guardar</Button> en forms/CRUD``
+        
+        `Impacto: Reusable en 10+ lugares, composition con Card/Form.`
+        
+    `- **Incorrecto:** God-component con 20 props/if-else. Fix: Split en hooks + ui primitives.`
+        
+`4. **Diccionario Variables:** Incluye | Reutilizable en | (ej: `buttonVariants` | ui/Button, Card | Afecta todos CTAs).`
+    
+`5. **Flujos:** Diagramas muestran composition: Page → Feature → ui/Hooks.`
+    
+`6. **Nueva 07-REUSABILIDAD-REACT.md:**`
+    
+    `- Lista convenciones: Custom hooks genéricos, Compound (Select + Options), Memo para perf.[](https://dev.to/hasancse/best-practices-for-creating-reusable-custom-hooks-in-react-37nj)`
+        
+    `- Métricas: Tabla | Componente | Lugares Reusado | Mejora Sugerida |.`
+        
+    `- Ej: "useQuery → genérico<T> para Supabase en properties/orders".`
+        
+`7. **INDEX-MAESTRO.md:** Sección ## Reusabilidad [link a 07].`
+    
+
+`**VALIDACIÓN:** Confirma >70% componentes reutilizables post-refactor. Genera todo listo para copiar.`

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

@@ -0,0 +1,410 @@
+# Convenciones de Base de Datos — Supabase / PostgreSQL
+
+> Prácticas priorizadas por impacto en rendimiento, seguridad y escalabilidad para proyectos React + Supabase. Cada práctica incluye ejemplo correcto ✅ e incorrecto ❌.
+
+---
+
+## 1. SELECT con columnas específicas
+
+Nunca uses `select(*)`. Reduce bandwidth 70-90%.
+
+```typescript
+// ✅ Correcto
+supabase.from('products').select('id, name, price, category_id')
+
+// ❌ Incorrecto
+supabase.from('products').select('*')
+```
+
+**Por qué:** `*` trae columnas que no necesitas (JSONB grandes, texto largo), satura la red y ralentiza el render.
+
+---
+
+## 2. Keyset pagination (cursor-based)
+
+Usa `WHERE id > last_id LIMIT n` en lugar de `offset`. Escala infinito sin degradación.
+
+```typescript
+// ✅ Correcto — keyset pagination
+async function getUsers(pageSize = 25, cursor?: string) {
+  let query = supabase.from('users').select('id, name, email').limit(pageSize).order('id', { ascending: true })
+  if (cursor) query = query.gt('id', cursor)
+  return query
+}
+
+// ❌ Incorrecto — offset based (se degrada con datos grandes)
+supabase.from('users').select('id, name').range(offset, offset + 25)
+```
+
+**Por qué:** `OFFSET` escanea filas descartadas en cada página. Keyset usa índices directamente.
+
+---
+
+## 3. RLS políticas granulares
+
+Cada tabla debe tener Row Level Security activado con políticas `USING (auth.uid() = user_id)`.
+
+```sql
+-- ✅ Correcto — RLS granular
+CREATE POLICY "users_own_profile" ON profiles
+  FOR ALL USING (auth.uid() = id);
+
+CREATE POLICY "select_own_orders" ON orders
+  FOR SELECT USING (auth.uid() = user_id);
+
+-- ❌ Incorrecto — bucket público o sin RLS
+-- (no deshabilitar RLS en tablas con datos de usuario)
+```
+
+**En el código:**
+```typescript
+// ✅ El frontend solo consulta, RLS filtra automáticamente
+const { data } = await supabase.from('orders').select('id, total')
+
+// ❌ Service Role Key en el cliente (NUNCA)
+const serviceClient = createClient(url, process.env.SERVICE_ROLE_KEY) // PELIGRO
+```
+
+**Por qué:** RLS es zero-trust: aunque el token sea válido, el usuario solo ve sus datos. No necesitas middleware de autorización.
+
+---
+
+## 4. RPC para lógica compleja (evitar N+1)
+
+Operaciones multi-paso o joins pesados van en funciones Postgres, no en el cliente.
+
+```sql
+-- ✅ Correcto — RPC en base de datos
+CREATE OR REPLACE FUNCTION get_dashboard_stats(user_id UUID)
+RETURNS JSONB LANGUAGE plpgsql SECURITY DEFINER AS $$
+DECLARE
+  result JSONB;
+BEGIN
+  SELECT jsonb_build_object(
+    'total_orders', (SELECT count(*) FROM orders WHERE orders.user_id = get_dashboard_stats.user_id),
+    'total_spent', (SELECT COALESCE(sum(total), 0) FROM orders WHERE orders.user_id = get_dashboard_stats.user_id)
+  ) INTO result;
+  RETURN result;
+END;
+$$;
+```
+
+```typescript
+// ✅ Llamada desde el frontend
+const { data } = await supabase.rpc('get_dashboard_stats', { user_id: userId })
+
+// ❌ Múltiples queries desde el cliente (N+1)
+const orders = await supabase.from('orders').select('id')
+for (const order of orders.data) {
+  await supabase.from('order_items').select('*').eq('order_id', order.id)
+}
+```
+
+**Por qué:** RPC ejecuta lógica del lado de la DB, sin round-trips múltiples, con acceso directo a memoria.
+
+---
+
+## 5. Índices en columnas WHERE / JOIN / ORDER BY
+
+Crea índices compuestos para los filtros más comunes de cada tabla.
+
+```sql
+-- ✅ Correcto — índice compuesto para filtros frecuentes
+CREATE INDEX idx_orders_user_status ON orders(user_id, status) WHERE status != 'cancelled';
+
+-- ✅ Cubrir SELECT con INCLUDE
+CREATE INDEX idx_orders_user_id ON orders(user_id) INCLUDE (total, created_at);
+
+-- ❌ Sin índice en columna de filtro frecuente
+-- SELECT * FROM orders WHERE user_id = '...' AND status = 'active'  ← full scan
+```
+
+**En migración:**
+```bash
+supabase migration new add_orders_indexes
+# Editar el archivo SQL generado
+```
+
+**Por qué:** Los índices convierten scans secuenciales en búsquedas O(log n). Los partial indexes son 90% más pequeños.
+
+---
+
+## 6. Signed URLs para archivos (no buckets públicos)
+
+```typescript
+// ✅ Correcto — Signed URL con expiración
+const { data } = await supabase.storage
+  .from('avatars')
+  .createSignedUrl(`users/${userId}.jpg`, 3600) // expira en 1h
+
+// ❌ Incorrecto — bucket público
+// Bucket config: public = true  ← cualquiera con la URL accede
+```
+
+**Por qué:** Signed URLs limitan acceso temporal. Incluso con RLS en tablas, los archivos en buckets públicos son accesibles por cualquiera que tenga la URL.
+
+---
+
+## 7. Service Role Key solo en backend
+
+```typescript
+// ✅ Correcto — Service Key solo en Edge Functions o backend
+// (Nunca en código frontend)
+const serviceClient = createClient(url, process.env.SERVICE_ROLE_KEY)
+
+// ❌ Incorrecto — Service Key en frontend
+// Si alguien extrae la key, tiene acceso total a tu BD
+```
+
+**Regla:** En el frontend usa solo la `anon key` con RLS. Para operaciones admin usa RPC con `SECURITY DEFINER` o Edge Functions.
+
+---
+
+## 8. Batch operations
+
+```typescript
+// ✅ Correcto — batch insert
+const { error } = await supabase.from('products').insert([
+  { name: 'Pro A', price: 100 },
+  { name: 'Pro B', price: 200 },
+  { name: 'Pro C', price: 300 },
+])
+
+// ❌ Incorrecto — inserts en loop
+for (const product of products) {
+  await supabase.from('products').insert(product)
+}
+```
+
+**Por qué:** Un batch insert es ~10x más rápido que inserts individuales por el overhead de cada query.
+
+---
+
+## 9. Tipos precisos (UUID, TIMESTAMPTZ, JSONB)
+
+```sql
+-- ✅ Correcto — tipos específicos
+CREATE TABLE products (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  name TEXT NOT NULL,
+  price NUMERIC(10,2) NOT NULL DEFAULT 0,
+  metadata JSONB DEFAULT '{}',
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- ❌ Incorrecto — tipos genéricos
+CREATE TABLE products (
+  id TEXT PRIMARY KEY,           -- UUID como TEXT desperdicia espacio e índices
+  price FLOAT,                   -- FLOAT tiene errores de redondeo
+  created_at TIMESTAMP           -- Sin timezone = ambigüedad
+);
+```
+
+**Por qué:** `UUID` vs `TEXT`: 16 bytes vs variable. `TIMESTAMPTZ` evita ambigüedad de zona horaria. `NUMERIC` es exacto para dinero.
+
+---
+
+## 10. Types generados desde la DB
+
+```bash
+# ✅ Correcto — tipos sincronizados automáticamente
+supabase gen types typescript --local > src/types/supabase.ts
+
+# ❌ Incorrecto — tipos escritos a mano (se desincronizan)
+interface Product {
+  id: string
+  name: string
+  // ... se rompe cuando agregas columnas
+}
+```
+
+Luego úsalos:
+```typescript
+import { Database } from '../types/supabase'
+type Product = Database['public']['Tables']['products']['Row']
+```
+
+---
+
+## 11. Migraciones versionadas
+
+```bash
+# ✅ Correcto — cada cambio de schema es una migración
+supabase migration new add_product_categories
+
+# Editar el SQL, luego:
+supabase db push
+
+# ❌ Incorrecto — cambios directos en tabla
+ALTER TABLE products ADD COLUMN category_id UUID;  -- sin migración
+```
+
+**Por qué:** Las migraciones dan historial, rollback, y reproducción exacta en producción.
+
+---
+
+## 12. Error handling por código PostgreSQL
+
+```typescript
+// ✅ Correcto — capturar errores por código
+try {
+  const { error } = await supabase.from('users').insert({ email })
+  if (error?.code === '23505') {
+    // Unique violation — email ya existe
+    return { error: 'Este email ya está registrado' }
+  }
+  if (error?.code === '23503') {
+    // Foreign key violation
+    return { error: 'Referencia inválida' }
+  }
+} catch (err) {
+  console.error('Error inesperado:', err)
+}
+
+// ❌ Incorrecto — error genérico
+catch (err) {
+  showToast('Error de base de datos')  // sin contexto para el usuario
+}
+```
+
+**Códigos comunes:** `23505` (unique), `23503` (foreign key), `42P01` (tabla no existe), `42501` (RLS denegado).
+
+---
+
+## 13. Soft deletes
+
+```sql
+-- ✅ Correcto — borrado lógico con columna deleted_at
+ALTER TABLE products ADD COLUMN deleted_at TIMESTAMPTZ;
+
+-- RLS que excluye borrados
+CREATE POLICY "select_active_products" ON products
+  FOR SELECT USING (deleted_at IS NULL);
+```
+
+```typescript
+// ✅ Soft delete
+await supabase.from('products').update({ deleted_at: new Date().toISOString() }).eq('id', id)
+
+// ❌ Hard delete (irreversible)
+await supabase.from('products').delete().eq('id', id)
+```
+
+**Por qué:** Soft delete permite recuperación, auditoría, y evita "cascades" de FK que rompen datos relacionados.
+
+---
+
+## 14. Transacciones multi-paso vía RPC
+
+Para operaciones que involucran múltiples tablas, usa una función RPC con transacción:
+
+```sql
+-- ✅ Correcto — todo en una transacción
+CREATE OR REPLACE FUNCTION create_order(p_user_id UUID, p_items JSONB)
+RETURNS JSONB LANGUAGE plpgsql SECURITY DEFINER AS $$
+DECLARE
+  v_order_id UUID;
+  v_total NUMERIC;
+BEGIN
+  INSERT INTO orders (user_id, status) VALUES (p_user_id, 'pending') RETURNING id INTO v_order_id;
+  INSERT INTO order_items (order_id, product_id, quantity, price)
+    SELECT v_order_id, item->>'product_id', (item->>'quantity')::INT, (item->>'price')::NUMERIC
+    FROM jsonb_array_elements(p_items) AS item;
+  SELECT SUM(quantity * price) INTO v_total FROM order_items WHERE order_id = v_order_id;
+  UPDATE orders SET total = v_total WHERE id = v_order_id;
+  RETURN jsonb_build_object('order_id', v_order_id, 'total', v_total);
+END;
+$$;
+```
+
+```typescript
+// ✅ Llamada única
+const { data } = await supabase.rpc('create_order', { p_user_id: userId, p_items: cart })
+
+// ❌ Múltiples queries sin transacción
+const { data: order } = await supabase.from('orders').insert({ user_id: userId }).select()
+// Si esto falla después, tienes datos huérfanos
+await supabase.from('order_items').insert(items.map(i => ({ order_id: order.id, ...i })))
+```
+
+---
+
+## 15. Realtime channels con cleanup
+
+```typescript
+// ✅ Correcto — unsubscribe en cleanup
+useEffect(() => {
+  const channel = supabase
+    .channel('orders-feed')
+    .on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'orders' }, payload => {
+      setOrders(prev => [...prev, payload.new])
+    })
+    .subscribe()
+
+  return () => { supabase.removeChannel(channel) } // cleanup!
+}, [])
+
+// ❌ Incorrecto — sin cleanup (fuga de conexiones)
+useEffect(() => {
+  supabase.channel('orders-feed').on('postgres_changes', ...).subscribe()
+  // Sin return → se acumulan canales al remontar el componente
+}, [])
+```
+
+---
+
+## 16. Unique constraints y Foreign Keys
+
+```sql
+-- ✅ Correcto — constraints explícitas
+CREATE TABLE products (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  sku TEXT UNIQUE NOT NULL,
+  category_id UUID NOT NULL REFERENCES categories(id) ON DELETE RESTRICT
+);
+
+-- ❌ Incorrecto — validación solo en código
+-- (dos usuarios pueden insertar el mismo SKU si la request llega al mismo tiempo)
+```
+
+**Por qué:** Las constraints de base de datos son el último filtro de integridad. El código puede tener bugs, la base de datos no.
+
+---
+
+## 17. Partial indexes para filtros comunes
+
+```sql
+-- ✅ Correcto — índice solo para filas activas (más pequeño, más rápido)
+CREATE INDEX idx_products_active ON products(created_at) WHERE active = true;
+
+-- ❌ Incorrecto — índice completo en tabla con 80% inactivos
+CREATE INDEX idx_products_created ON products(created_at);
+```
+
+**Por qué:** Un partial index es ~90% más pequeño que uno completo cuando filtras por un subconjunto.
+
+---
+
+## 18. Covering indexes (INCLUDE)
+
+```sql
+-- ✅ Correcto — index-only scan
+CREATE INDEX idx_orders_user ON orders(user_id) INCLUDE (total, status, created_at);
+
+-- ❌ Incorrecto — necesita ir a la tabla para obtener columnas extra
+CREATE INDEX idx_orders_user ON orders(user_id);
+-- SELECT user_id, total, status FROM orders WHERE user_id = 'x' → necesita heap lookup
+```
+
+**Por qué:** Con `INCLUDE`, la query se resuelve solo con el índice, sin tocar la tabla principal.
+
+---
+
+## Resumen: Prioridad por fase del proyecto
+
+| Fase | Prácticas esenciales |
+|---|---|
+| MVP / Prototipo | 1 (SELECT), 3 (RLS), 9 (tipos), 10 (types gen), 16 (constraints) |
+| Producción | + 4 (RPC), 5 (índices), 6 (signed URLs), 12 (error codes), 15 (realtime) |
+| Escalando | + 2 (keyset), 8 (batch), 11 (migrations), 13 (soft delete), 14 (transacciones), 17 (partial), 18 (covering) |
+| Auditoría/Seguridad | + 7 (service key), todo RLS revisado |