openprompt-lang 0.3.0

package/docs/referencia-metodologia/ExtractorInformacion.py

@@ -0,0 +1,78 @@
+import os
+
+IGNORED_DIRS = {'.git', 'node_modules', 'dist', '.gemini', 'public'}
+IGNORED_FILES = {'ExtractorInformacion.py', 'proyecto_completo.md', 'package-lock.json','.env.local','.env'}
+IGNORED_EXTENSIONS = {'.png', '.jpg', '.jpeg', '.gif', '.ico', '.svg', '.webp', '.pdf', '.woff', '.woff2', '.ttf','.env'}
+
+def generate_tree(dir_path, prefix=""):
+    tree_str = ""
+    try:
+        entries = sorted(os.listdir(dir_path))
+    except PermissionError:
+        return ""
+    
+    entries = [e for e in entries if e not in IGNORED_DIRS and e not in IGNORED_FILES]
+    for i, entry in enumerate(entries):
+        path = os.path.join(dir_path, entry)
+        is_last = (i == len(entries) - 1)
+        
+        connector = "└── " if is_last else "├── "
+        tree_str += f"{prefix}{connector}{entry}\n"
+        
+        if os.path.isdir(path):
+            extension = "    " if is_last else "│   "
+            tree_str += generate_tree(path, prefix + extension)
+            
+    return tree_str
+
+def main():
+    base_dir = os.path.abspath(os.path.dirname(__file__))
+    output_file = os.path.join(base_dir, "proyecto_completo.md")
+    
+    with open(output_file, 'w', encoding='utf-8') as out:
+        out.write("# Contenido del Proyecto\n\n")
+        
+        for root, dirs, files in os.walk(base_dir):
+            dirs[:] = [d for d in dirs if d not in IGNORED_DIRS]
+            
+            for file in sorted(files):
+                if file in IGNORED_FILES:
+                    continue
+                    
+                _, ext = os.path.splitext(file)
+                if ext.lower() in IGNORED_EXTENSIONS:
+                    continue
+                
+                file_path = os.path.join(root, file)
+                rel_path = os.path.relpath(file_path, base_dir)
+                
+                try:
+                    with open(file_path, 'r', encoding='utf-8') as f:
+                        content = f.read()
+                except UnicodeDecodeError:
+                    continue # Sirve para evadir binarios que por casualidad no estaban en excluidos
+                
+                language = ext.replace('.', '')
+                if language not in ['ts', 'tsx', 'js', 'jsx', 'json', 'css', 'html', 'md', 'mdx']:
+                    language = ''
+                
+                if language == 'md' and file_path == output_file:
+                    continue # Evitar redundancia si el archivo se llama distinto de imprevisto
+
+                out.write(f"### Archivo: {rel_path}\n")
+                out.write(f"```{language}\n")
+                out.write(content)
+                if not content.endswith('\n'):
+                    out.write('\n')
+                out.write("```\n\n")
+
+        out.write("# Estructura de Carpetas\n")
+        out.write("```text\n")
+        out.write(os.path.basename(base_dir) + "/\n")
+        out.write(generate_tree(base_dir))
+        out.write("```\n")
+        
+    print(f"✅ Extracción completada. El archivo '{output_file}' ha sido generado.")
+
+if __name__ == '__main__':
+    main()

package/docs/referencia-metodologia/Fase - 1 .- Desarrollo de la Metodolog/303/255a.md"

@@ -0,0 +1,67 @@
+
+---
+
+> [!abstract] Objetivo de la Fase
+> Esta fase establece el control del proyecto. El objetivo es extraer información de alto valor, evaluar la viabilidad técnica temprana y estructurar una propuesta que posicione el servicio como una **inversión estratégica** y no como un simple gasto.
+
+## a. Entrevista de levantamiento estructurado (Plantilla de Diagnóstico)
+
+Para evitar soluciones superficiales, se utiliza un cuestionario estructurado dividido en tres pilares clave. Estas preguntas buscan llegar al dolor real del negocio:
+
+> [!question] 1. Pilar de Negocio y Problema Raíz
+> - ¿Cuál es el proceso manual que les toma más tiempo hoy en día?
+> - ¿Cuánto tiempo o dinero calculan que pierden a la semana por este cuello de botella o error del sistema actual?
+> - Si no solucionamos este problema en los próximos 6 meses, ¿qué impacto negativo tendrá en la empresa?
+> - ¿Cuál es el objetivo principal de este proyecto? *(Ej: Vender más, reducir tiempos de atención, evitar pérdida de datos).*
+
+> [!question] 2. Pilar de Usuarios y Contexto Operativo
+> - ¿Quién va a usar este sistema todos los días? ¿Qué nivel de conocimiento técnico tienen?
+> - ¿Desde qué dispositivos se usará principalmente? *(Computadoras de oficina viejas, celulares en la calle, tablets).*
+> - ¿Existe algún flujo crítico que no pueda detenerse por ningún motivo durante la transición?
+
+> [!question] 3. Pilar Técnico (Si ya existe un sistema)
+> - ¿Dónde está alojado el sistema actual y quién tiene los accesos?
+> - ¿El sistema se conecta con otras herramientas *(facturación, inventario, envíos)*?
+> - ¿Tienen documentación, diagramas o el contacto del desarrollador anterior?
+
+---
+
+## b. Evaluación de ruta: Desarrollo desde cero vs Refactorización.
+
+En la misma reunión, o posterior al análisis de las respuestas, se aplican criterios técnicos para decidir si el software actual es rescatable.
+
+> [!warning] Especificaciones técnicas para descartar un proyecto (Ir por "Desde Cero")
+> Se recomendará construir desde cero si el proyecto actual cumple 2 o más de estos criterios:
+> - **Stack Obsoleto:** Utiliza frameworks o versiones de lenguajes deprecados y sin soporte de seguridad activo.
+> - **Deuda Técnica Crítica:** Código fuertemente acoplado (espagueti) donde no hay separación entre frontend, backend y base de datos.
+> - **Base de Datos Corrompida:** No hay integridad referencial, hay duplicación masiva de datos o la arquitectura de la BD no soporta escalabilidad.
+> - **Parche sobre Parche:** El sistema fue construido por múltiples desarrolladores sin estándares, y arreglar un bug genera tres nuevos.
+
+> [!info] Especificaciones para Auditoría de Refactorización
+> Si el proyecto es rescatable, se establece el proceso de Auditoría Pagada. Las especificaciones incluyen:
+> - Firma de NDA (Acuerdo de confidencialidad).
+> - Solicitud de accesos (Repositorios de GitHub/GitLab, variables de entorno, accesos a base de datos en lectura).
+> - **Entregable de la auditoría:** Mapeo de dependencias, reporte de vulnerabilidades y estimación de horas necesarias para limpiar el código antes de agregar nuevas funciones.
+
+---
+
+## c. Propuesta preliminar y alineación de expectativas
+
+Con la información levantada, se genera una propuesta rápida para alinear presupuesto y tiempos antes del diseño profundo.
+
+- **Stack Tecnológico Sugerido:** Se plantea la tecnología a usar *(Ej: React para interfaces dinámicas, Supabase para bases de datos escalables y autenticación, Tailwind para diseño responsivo).*
+- **Rango de Inversión (T-Shirt Sizing):** No se da un precio cerrado, sino rangos *(Ej: "Un proyecto de esta magnitud ronda entre X e Y dólares").*
+- **Tiempos Estimados por Fases:** Se dividen los tiempos especulativos en semanas o sprints, dejando claro que dependerá de la velocidad de aprobación del cliente.
+
+---
+
+## d. Entregable de diagnóstico y valor (El Documento Final)
+
+Se redacta un documento PDF formal que actúa como la **"Radiografía del Negocio"**.
+
+> [!example] Estructura Técnica del PDF
+> 1. **Resumen Ejecutivo:** Descripción del problema raíz en un párrafo.
+> 2. **Análisis de Impacto:** Explicación del costo actual del problema (dinero o tiempo perdido).
+> 3. **Arquitectura Conceptual:** Diagrama de bloques simple (Nivel de Contexto) creado con herramientas visuales, mostrando cómo interactuarán los usuarios, el nuevo sistema y servicios externos.
+> 4. **Matriz de Beneficios:** Tabla comparativa de *"Cómo se hace hoy"* vs *"Cómo se hará con el nuevo sistema"*.
+> 5. **Siguientes Pasos:** Call to Action (Llamado a la acción) para aprobar el inicio de la Fase 2 (Levantamiento de requisitos generales y contratos para IA).

package/docs/referencia-metodologia/Fase - 2 .- Levantamiento de requisitos generales y traduccion a la IA.md

@@ -0,0 +1,64 @@
+
+---
+> [!abstract] Objetivo de la Fase
+> En esta fase, la información subjetiva del cliente se transforma en instrucciones exactas, deterministas y libres de ambigüedad. El objetivo es estructurar el sistema de manera que la Inteligencia Artificial (y cualquier desarrollador humano futuro) no tenga margen para asumir, interpretar mal o alucinar funcionalidades.
+
+## a. Detallado del funcionamiento del sistema en lenguaje enfocado a la IA
+
+El lenguaje natural humano es ambiguo; el lenguaje para la IA debe ser imperativo y restrictivo.
+
+> [!tip] Principios de redacción determinista
+> - **Eliminación de subjetividad:** Se prohíben adjetivos como "rápido", "bonito", "intuitivo" o "seguro". Todo debe ser cuantificable.
+> - **Especificación de alcance estricto:** La IA no tiene criterio propio, por lo tanto, no se dejan decisiones de negocio al azar. Se le dan órdenes exactas de lo que debe ocurrir y lo que está estrictamente prohibido que ocurra.
+> - **Contrastes obligatorios:** Se estructuran los prompts entregando ejemplos claros de lo que es correcto y lo que es incorrecto para calibrar el comportamiento generativo.
+> - **Reglas de negocio inmutables:** Se define el límite de la solución.
+
+### Ejemplos de comunicación con la IA (Correcto vs Incorrecto)
+
+| Lo que NO se debe hacer (Ambigüedad) | Lo que SÍ se debe hacer (Determinista) | Razón del cambio |
+| :--- | :--- | :--- |
+| "Crea una vista bonita para ver los productos y que cargue rápido." | "Crea un grid de 4 columnas (`Tailwind grid-cols-4`) para renderizar `ProductCard`. La petición inicial debe traer máximo 20 productos paginados." | La IA no sabe qué es "bonito" o "rápido". Necesita límites de diseño y rendimiento exactos. |
+| "Haz una función para guardar usuarios." | "Crea una función `registerUser(payload: UserDTO): Promise<boolean>`. Debe verificar si el email existe antes de insertar en Supabase." | Define estrictamente la firma de la función, entradas, salidas y la lógica de negocio obligatoria. |
+| "Si falla el login, muestra un error." | "Si falla Auth, captura el error de Firebase. Si es `wrong-password`, muestra un Toast rojo que diga 'Contraseña incorrecta'. Nunca devuelvas el error del servidor al cliente." | Evita que la IA alucine manejos de errores genéricos que rompan la experiencia de usuario o expongan datos. |
+
+---
+
+## b. Creación de Historias de Usuario con enfoque técnico
+
+A diferencia de las historias de usuario tradicionales que solo enfocan el "Qué", en esta metodología las historias se redactan pensando en el "Cómo se estructura" para alimentar directamente a la IA.
+
+> [!info] Estructura de una Historia de Usuario Determinista
+> Cada historia debe contener suficiente detalle lógico para que la IA sepa cómo trabajar y desarrollar el elemento sin generar dudas funcionales:
+> 1. **Actor y Contexto:** ¿Quién ejecuta la acción y en qué vista o módulo se encuentra?
+> 2. **Disparador (Trigger):** ¿Qué evento exacto inicia el proceso?
+> 3. **Lógica Interna General:** Descripción paso a paso de lo que el sistema debe hacer tras bambalinas.
+> 4. **Resultado Esperado (Success):** Estado del sistema tras una ejecución exitosa.
+> 5. **Resultado Fallido (Error):** Estado del sistema y mensaje exacto que se muestra si la ejecución falla.
+
+---
+
+## c. Traducción a definiciones de métodos complejos (El Contrato del Método)
+
+Esta es la pieza central para mantener la calidad del código generado por IA. Antes de permitir que la IA escriba la lógica interna de una función, se le exige generar un "Contrato Estructural" mediante comentarios.
+
+> [!warning] Estructura obligatoria de un Contrato de Método
+> La IA debe devolver el esqueleto de la función con la siguiente información claramente comentada, basándose en el nombre descriptivo y los requerimientos:
+> - **Nombre descriptivo de la función:** Debe indicar claramente la acción (Verbo + Entidad + Contexto. Ej: `fetchActiveProductsByCategoryId()`).
+> - **Parámetros de entrada (Inputs):** Qué recibe la función y cuál es su tipo de dato estricto (Typescript interfaces/types).
+> - **Salida esperada (Outputs):** Qué devuelve la función y en qué formato.
+> - **Responsabilidad en el flujo general:** Cuál es la importancia de este método en el sistema. ¿Es un método crítico de negocio o solo una utilidad visual?
+> - **Impacto de modificación:** Si este método se altera o falla, ¿qué otros módulos o pantallas se rompen? (Trazabilidad).
+> - **Manejo de Errores (Try/Catch):** Qué excepciones específicas debe atrapar y cómo debe responder el sistema ante ellas.
+
+### Ejemplo visual del esqueleto exigido a la IA
+
+| Componente del Contrato | Explicación exigida en el comentario generado por la IA |
+| :--- | :--- |
+| **Entradas (Inputs)** | `// Recibe: userId (string, UUID válido), amount (number, mayor a 0)` |
+| **Salidas (Outputs)** | `// Retorna: PaymentResult (Interface con status 'success' o 'failed' y transactionId)` |
+| **Lógica de Negocio** | `// Flujo: 1. Valida saldo. 2. Descuenta de wallet. 3. Registra en historial de transacciones.` |
+| **Impacto (Trazabilidad)**| `// Impacto: Método crítico. Su fallo afecta la vista de Checkout y el reporte contable diario.` |
+| **Manejo de Errores** | `// Error handling: Catch InsufficientFundsException -> Retorna status 400 'Saldo insuficiente'.` |
+
+> [!quote]
+> Este enfoque de *"Comentarios primero, Lógica después"* garantiza que, al momento de hacer alguna mejora, se entienda perfectamente el impacto estructural antes de modificar el código.

package/docs/referencia-metodologia/Fase - 3 .- Prototipado visual con IA (Figma Maker o equivalentes).md

@@ -0,0 +1,64 @@
+
+---
+
+> [!abstract] Objetivo de la Fase
+> El objetivo de esta fase no es obtener un diseño final perfecto generado por IA, sino **acelerar radicalmente el proceso** creando una plantilla estructural sólida. Esta plantilla sirve como un borrador funcional y responsivo, que posteriormente se pulirá manualmente, ahorrando días de trabajo desde cero.
+
+## a. Creación de plantilla de interfaz gráfica inicial
+
+Al solicitar a la IA la generación de la interfaz (ya sea en código o herramientas visuales generativas), se le entregan directrices que aseguran que el resultado sea escalable y fácil de traducir a React y Tailwind.
+
+> [!tip] Reglas para el Prompt Visual Inicial
+> - **Conceptos ancla de estilo:** La IA comprende muy bien directrices abstractas de diseño. Se utilizan palabras clave específicas para definir el tono *(Ej: "UI minimalista, colores vibrantes, estilo SaaS B2B, alta legibilidad")*.
+> - **Referencias estructurales:** Se orienta a la IA indicando el patrón de diseño general *(Ej: "Estructura tipo Dashboard de administración", "Layout de Ecommerce con sidebar", "Landing page de alta conversión")*.
+> - **Enfoque Mobile-First:** Si la aplicación requiere uso móvil, se describen los elementos de navegación principales desde esa perspectiva *(Ej: "Bottom navbar fijo para navegación principal, menú hamburguesa secundario")*.
+
+---
+
+## b. Estructura visual y adaptación técnica (React + Tailwind)
+
+Para que el diseño generado sea útil, debe estar pensado desde su concepción para ser programado en componentes. La IA no debe generar una "página estática gigante", sino un rompecabezas de piezas reutilizables.
+
+- **Modularidad React:** Se le exige a la IA que estructure el diseño pensando en componentes aislados. Si hay una tarjeta de producto, debe ser un componente independiente (`ProductCard.tsx`), no un bloque de código repetido.
+- **Ausencia de CSS personalizado:** Al utilizar Tailwind, se elimina la necesidad de archivos `.css` sueltos. Todo el diseño debe resolverse mediante clases de utilidad directamente en el markup, manteniendo el orden del proyecto.
+- **Mapeo de carpetas de interfaz:** Junto con el diseño, se le pide a la IA que sugiera la estructura de carpetas de componentes *(Ej: `/components/ui/buttons`, `/components/layout/navbar`, `/views/dashboard`)*.
+
+---
+
+## c. Catálogo de buenas y malas estructuras (Anti-patrones visuales)
+
+La IA tiende a cometer errores de maquetación que destruyen la responsividad o la experiencia de usuario. Para evitarlo, se incluyen reglas de "Anti-patrones" en los prompts, bloqueando explícitamente estas prácticas.
+
+> [!warning] Tabla de Anti-Patrones Prohibidos vs. Buenas Prácticas Exigidas
+
+| Anti-Patrón (Prohibido en el Prompt) | Buena Práctica (Exigida en el Prompt) | Razón Técnica |
+| :--- | :--- | :--- |
+| Uso de medidas absolutas o fijas: `h-[500px]`, `w-[300px]`, `absolute`, `top-20`. | Uso de flexbox/grid y medidas relativas: `h-full`, `w-full`, `flex`, `grid`, `p-4`, `gap-2`. | Las medidas absolutas rompen el *Responsive Web Design*. La UI debe fluir y adaptarse al tamaño de la pantalla. |
+| Inconsistencia de UI: Dos botones que hacen lo mismo pero tienen distinto borde o tamaño. | Componentes Atómicos: Definir un solo estilo base para acciones y usar variantes. | La redundancia visual confunde al usuario y duplica el mantenimiento. |
+| Elementos táctiles diminutos: Botones de `h-4 w-4` en interfaces diseñadas para móviles. | Zonas táctiles seguras: Botones e inputs con un alto mínimo de `h-10` o `h-12` para móviles. | Mejora la accesibilidad y evita toques accidentales. |
+
+---
+
+## d. Prompt Maestro de Generación Base (Plantilla Inicial)
+
+Este es el prompt estandarizado que se utiliza como punto de partida para generar la estructura visual base. Posteriormente, se refina alimentando a la IA con los documentos de requisitos específicos de la Fase 2.
+
+> [!example] Prompt a utilizar
+> ```text
+> Eres un experto en diseño UI/UX y desarrollo Frontend con React y Tailwind CSS. Tu objetivo es generar la estructura visual base para un proyecto de tipo [TIPO DE PROYECTO: ej. Dashboard SaaS / Ecommerce App].
+> 
+> Concepto Visual: El estilo debe transmitir [CONCEPTOS: ej. minimalismo, seriedad corporativa, modernidad vibrante]. Usa una paleta de colores [TIPO DE PALETA: ej. neutra con acentos en azul oscuro].
+> 
+> Estructura Requerida:
+> 1. Diseña con enfoque Mobile-First, escalando luego a Desktop (responsive design obligatorio).
+> 2. Divide la interfaz en componentes lógicos reutilizables (Ej: Navbar, Sidebar, CardComponent, DataTable).
+> 3. Propón una estructura de carpetas limpia para estos componentes.
+> 
+> RESTRICCIONES ESTRICTAS (ANTI-PATRONES PROHIBIDOS):
+> - ESTRICTAMENTE PROHIBIDO usar posiciones o tamaños absolutos (absolute, top-x, h-[500px], w-[300px]). Todo debe fluir con flex, grid, porcentajes o medidas relativas (w-full, h-full, gap-x).
+> - PROHIBIDO generar botones o inputs con alturas táctiles menores a h-10 en vistas móviles.
+> - PROHIBIDO duplicar estilos para elementos que cumplen la misma función (Ej: si hay dos botones de 'Cerrar Modal', deben verse y codificarse exactamente igual).
+> - PROHIBIDO escribir CSS personalizado. Usa 100% clases de utilidad de Tailwind.
+> 
+> Entrégame el código de los componentes principales estructurados y listos para ser iterados más adelante con la lógica de negocio real.
+> ```

package/docs/referencia-metodologia/Fase - 4 .- Especificacion de requisitos e iteracion con el cliente.md

@@ -0,0 +1,58 @@
+
+---
+> [!abstract] Objetivo de la Fase
+> Esta fase es el punto de no retorno antes de iniciar el desarrollo lógico profundo. Es el espacio diseñado para que el cliente visualice la solución propuesta, valide que resuelve su problema raíz y solicite ajustes. El objetivo principal es congelar el alcance del proyecto y definir el presupuesto exacto final.
+
+## a. Integración de correcciones del cliente (El "Feedback Loop")
+
+La presentación del prototipo y la lógica inicial se realiza idealmente en una reunión presencial o, en su defecto, mediante videollamada interactiva. **No se envían enlaces para revisión asíncrona sin contexto.**
+
+> [!info] Estructura de la reunión de presentación
+> - **Demostración del Producto Preliminar:** Se navega por el prototipo generado (Fase 3), explicando el flujo visual y cómo cada pantalla responde a los dolores levantados en la Fase 1.
+> - **Propuesta de Valor Agregado:** Se le exponen al cliente ideas de mejora proactivas que surgieron durante el diseño, explicando el impacto positivo que tendrían en la resolución de su problema.
+> - **Modificaciones en Vivo:** Se habilita un espacio de feedback inmediato. Los ajustes visuales menores o de distribución que el cliente solicita se intentan modificar de forma rápida y manual durante la misma sesión para agilizar la aprobación.
+
+---
+
+## b. Ciclo de preguntas, control de alcance (Scope Creep) y presupuesto final
+
+Es natural que, al ver la interfaz, el cliente solicite funciones nuevas que no estaban contempladas en el levantamiento inicial. Esta metodología abraza el cambio, pero lo somete a un estricto control de presupuesto y tiempo.
+
+> [!warning] Reglas para manejar nuevos requerimientos
+> 1. **Flexibilidad controlada:** Todos los cambios, adiciones o nuevas ideas que surjan en esta reunión son bienvenidos y se documentan.
+> 2. **Evaluación de impacto:** Se analiza en tiempo real (o en las siguientes 24 horas) cuánta dificultad técnica y tiempo de desarrollo añaden estas nuevas solicitudes.
+> 3. **Cierre de Presupuesto:** En esta misma reunión (o en una sesión breve posterior), se presenta el presupuesto exacto y final que absorbe todos los ajustes validados.
+> 4. **Congelamiento del Alcance:** Una vez aprobado el presupuesto y definido el proyecto en este punto, cualquier nueva funcionalidad *(Ej: "Agreguemos un módulo de chat")* será cotizada por separado y agendada para el final del desarrollo inicial (siguiente sprint o Fase 2 del producto).
+
+---
+
+## c. Especificación de nuevos elementos funcionales
+
+Cuando el cliente aprueba una nueva función o la modificación de una existente, esta no pasa directamente a programarse. Debe ser procesada por el mismo filtro de calidad determinista de la Fase 2.
+
+> [!tip] Protocolo de documentación de cambios
+> - **Modificación de elementos existentes:** Si el cliente pide alterar un botón o un flujo que ya estaba definido, se agrega un comentario técnico en la documentación original que invalida el comportamiento previo y detalla las nuevas condiciones.
+> - **Creación de elementos nuevos:** Si se agrega una vista, modal o interacción inédita, se redacta su "Contrato Estructural" (Inputs, Outputs, Manejo de errores y Relación con el sistema general).
+> - **Trazabilidad de equipo e IA:** Este registro estricto garantiza que tanto la Inteligencia Artificial como otros desarrolladores humanos que colaboren en el proyecto comprendan el cambio de rumbo sin confusiones.
+
+---
+
+## d. Bibliotecas necesarias y factibilidad técnica
+
+La adición de nuevos elementos funcionales suele acarrear necesidades técnicas que no estaban previstas originalmente. En este paso se define el stack complementario necesario para cumplir con las peticiones del cliente.
+
+- **Justificación de uso:** Antes de instalar cualquier paquete externo, se documenta por qué es necesario y qué problema específico resuelve.
+- **Auditoría de impacto:** Se revisa que la nueva biblioteca no entre en conflicto de versiones con el stack base, asegurando la escalabilidad del sistema recién re-definido.
+
+---
+
+## **✅ Checklist de Aprobación: Inicio Oficial de Desarrollo (Go / No-Go)**
+
+**Antes de escribir la primera línea de código de la Fase 5, se debe verificar que todos los puntos de esta tabla estén cumplidos. Si hay un solo "No" (o casilla desmarcada), el proyecto se pausa hasta resolverlo.**
+
+> [!success] 🚀 Go / No-Go (Checklist de Aprobación)
+> - [ ] **1. Diseño Base Aprobado:** El cliente vio el prototipo visual (Figma/App) y confirmó que el flujo principal es correcto.
+> - [ ] **2. Modificaciones Documentadas:** Todos los cambios solicitados en la reunión fueron anotados y procesados bajo las reglas estrictas de la Fase 2.
+> - [ ] **3. Presupuesto Final Aceptado:** Se envió la cotización exacta (que incluye los cambios de última hora) y el cliente dio su confirmación escrita/formal.
+> - [ ] **4. Alcance Congelado (Scope Lock):** El cliente entiende y aceptó que cualquier idea nueva a partir de hoy se cobra como un "Extra" o pasa a una Fase 2.
+> - [ ] **5. Viabilidad Técnica Confirmada:** Se validaron las bibliotecas, APIs o herramientas necesarias para cumplir con los nuevos requerimientos.

package/docs/referencia-metodologia/Fase - 5 .- Estructuracion y maquetado de funciones (Scaffolding).md

@@ -0,0 +1,118 @@
+
+---
+> [!abstract] Objetivo de la Fase
+> En esta fase se abandona la planificación y se comienza la construcción real del sistema, pero sin escribir lógica de negocio todavía. El objetivo es crear la "arquitectura vacía" (esqueletos) del proyecto, dejando todo el terreno documentado y preparado para que la IA (o el equipo humano) solo tenga que rellenar los espacios en blanco de forma determinista.
+
+## a. Creación de estructura básica de archivos de documentación
+
+Antes de crear carpetas de código, se debe centralizar el conocimiento del proyecto en un formato cómodo para el desarrollador y legible para la IA.
+
+> [!tip] Implementación del Diccionario en README.md
+> En lugar de depender de PDFs externos durante el desarrollo, toda la documentación viva se aloja en archivos Markdown (`.md`) dentro del propio repositorio. Esto permite actualizarla sin salir del editor de código (VS Code, Cursor, etc.).
+> - **Diccionario de Variables:** Un archivo donde se enlistan las variables globales o estados complejos, su tipo de dato, en qué módulo habitan y qué impacto tienen.
+> - **Diccionario de Funciones Críticas:** Un listado de los métodos principales del sistema, explicando qué hacen y qué dependencias tienen.
+> - **Registro de Bibliotecas:** Un bloque en el README con las dependencias instaladas *(Ej: `date-fns v3.0`, `zustand v4.5`)* y una breve justificación de su uso.
+
+---
+
+## b. Definición de estructura de carpetas definitiva
+
+Se define el árbol de directorios del proyecto. Un buen ordenamiento previene el "código espagueti" y permite que la IA entienda el contexto de un archivo solo por su ubicación.
+
+> [!info] Estructura de referencia (Ejemplo para React/TypeScript)
+> ```text
+> /src
+>   /assets         (Imágenes, iconos, fuentes)
+>   /components     (Componentes visuales aislados)
+>      /ui          (Botones, inputs, modales base - Atomic Design)
+>      /layout      (Navbar, Sidebar, Footers)
+>   /features       (Componentes complejos agrupados por dominio de negocio. Ej: /auth, /cart)
+>   /hooks          (Lógica reutilizable de React, ej: useAuth, useTable)
+>   /services       (Llamadas a APIs externas o bases de datos)
+>   /store          (Manejo de estado global, ej: Zustand, Redux)
+>   /types          (Interfaces y tipos de TypeScript globales)
+>   /utils          (Funciones puras de ayuda, ej: formatearFecha, calcularImpuesto)
+>   /views          (Las páginas completas que agrupan los componentes)
+> ```
+> Cada tecnología (Spring Boot, Next.js, Ionic) tendrá su variante, pero la regla es la misma: **Separación estricta de responsabilidades**.
+
+---
+
+## c. Creación de archivos y esqueletos base (Scaffolding)
+
+En lugar de programar la lógica inmediatamente, se crean todos los archivos necesarios vacíos, pero estructurados con "Comentarios de Contrato". Esto funciona como una orden estricta para la IA.
+
+> [!warning] Patrón de trabajo (El método Scaffolding)
+> 1. Se crea el archivo con su nombre definitivo.
+> 2. Se importan las dependencias obvias si se conocen.
+> 3. Se define la firma de la función (Input y Output).
+> 4. Se inyecta un bloque de comentarios estandarizado (Intención, Flujo, Dependencias).
+> 5. Se fuerza un error deliberado *(Ej: `throw new Error("Lógica pendiente")`)* para evitar que el sistema pase por alto funciones vacías.
+
+---
+
+## d. Ejemplo práctico de definición técnica (El Contrato en Código)
+
+A continuación, un ejemplo real de cómo se debe preparar un esqueleto (en este caso backend) antes de entregárselo a la IA para que desarrolle la lógica final. Este patrón es aplicable a cualquier lenguaje.
+
+```java
+    @Override
+    public AuthResponseDTO registrar(RegisterRequestDTO dto) {
+        /*
+         * INTENCIÓN:
+         *   Registrar nuevas credenciales de usuario.
+         *
+         * FLUJO ESPERADO:
+         *   Input: RegisterRequestDTO (username, password, rol)
+         *   Process:
+         *     1. Verificar si username existe (UsuarioYaExisteException si es así).
+         *     2. Normalizar username a minúsculas.
+         *     3. Hashear password usando PasswordEncoder.
+         *     4. Asignar ROLE_CL si rol viene null.
+         *     5. Guardar en UserCredentialRepository con activo=true.
+         *     6. Generar tokens via JwtService.
+         *   Output: AuthResponseDTO (JWT).
+         *
+         * DEPENDENCIAS:
+         *   - ms-usuarios (para crear perfil vinculado al credencialId generado).
+         */
+        throw new UnsupportedOperationException("Scaffolding: Lógica de negocio pendiente de implementación.");
+    }
+```
+> Al entregarle este archivo a la IA, la posibilidad de que alucine o escriba código fuera del estándar se reduce a cero, ya que el proceso actúa como un algoritmo inquebrantable.
+
+---
+
+## e. Diagramas de apoyo técnico
+
+Con los esqueletos listos, la arquitectura del proyecto ya es visible en el código. En este punto, si la complejidad lo amerita, se generan diagramas de apoyo que se adjuntarán a la documentación Markdown.
+
+- **Diagramas de Flujo:** Para lógicas pesadas *(Ej: Pasarela de pago o recuperación de contraseña).*
+- **Diagramas de Estado:** Para entidades que mutan *(Ej: Un "Pedido" que pasa de 'Pendiente' a 'Pagado').*
+- **Diagramas de Relación:** Para visualizar cómo los servicios se comunican con los módulos de interfaz.
+
+---
+
+## f. Prompt Maestro para Generación de Scaffolding con IA
+
+Para automatizar la creación de estos archivos base manteniendo el rigor técnico, se utiliza el siguiente prompt estandarizado en la herramienta de IA de preferencia (Claude, Cursor, ChatGPT).
+
+> [!example] Copiar Prompt Maestro
+> ```text
+> Actúa como un Arquitecto de Software Senior experto en [LENGUAJE/FRAMEWORK, Ej: React y TypeScript]. 
+> Tu tarea es generar el 'Scaffolding' (esqueleto de código vacío) para el módulo de [NOMBRE DEL MÓDULO, Ej: Autenticación].
+> 
+> REGLAS ESTRICTAS:
+> 1. NO implementes la lógica de negocio real. Solo crea las firmas de las funciones, clases o componentes.
+> 2. En cada función/método, debes incluir obligatoriamente este bloque de comentarios exacto:
+>    /*
+>     * INTENCIÓN: [Qué hace brevemente]
+>     * FLUJO ESPERADO:
+>     *   Input: [Argumentos/DTOs]
+>     *   Process: [Pasos enumerados del 1 al N de lo que debe ocurrir]
+>     *   Output: [Qué retorna]
+>     * DEPENDENCIAS: [Qué otros servicios, hooks o repositorios necesita]
+>     */
+> 3. El cuerpo de cada función debe contener únicamente un error forzado que diga 'Lógica pendiente de implementación' (Ej: `throw new Error(...)` o su equivalente en el lenguaje).
+> 4. Devuelve el código listo para copiar, indicando en qué ruta de carpetas debería guardarse este archivo.
+> ```

package/docs/referencia-metodologia/Fase - 6 .- Estructuracion del backlog y division de tareas.md

@@ -0,0 +1,48 @@
+
+
+---
+> [!abstract] Objetivo de la Fase
+> Con la arquitectura base y los esqueletos (Scaffolding) ya creados en el código, el proyecto deja de ser un concepto y se convierte en una lista de tareas ejecutables. En esta fase se abandona el desarrollo "de memoria" y se adopta un sistema estrictamente documentado para no abrumar ni al desarrollador ni a la Inteligencia Artificial.
+
+## a. Sistema de Gestión Centralizado (Enfoque JSON-Driven)
+
+Para manejar múltiples proyectos sin colapsar, las tareas no pueden vivir en la cabeza del programador. Se utiliza un formato estructurado (como un JSON estandarizado) que actúa como la única fuente de verdad del proyecto.
+
+> [!info] Estructura del Backlog Documentado
+> - **Formato de entrada:** Se genera un documento (idealmente un JSON o matriz) que contiene el backlog completo.
+> - **Atributos obligatorios por tarea:** Cada ítem debe tener un ID, descripción técnica, prioridad (Alta, Media, Baja), fecha límite (deadline) y el módulo al que pertenece.
+> - **Propósito:** Este formato permite alimentar un gestor de tareas (ya sea una herramienta de terceros o una aplicación propia) que dicte exactamente *qué* se debe programar cada día, eliminando la fatiga de decisión.
+
+---
+
+## b. Estrategia de Desarrollo por Capas (Layered Development)
+
+El orden de ejecución se dicta estrictamente por el backlog estructurado. El desarrollo avanza por capas técnicas, agregando valor de manera progresiva y secuencial en lugar de saltar entre el frontend y el backend desordenadamente.
+
+> [!tip] Flujo de progreso por capas
+> 1. **Capa de Datos:** Diseño y consolidación de la base de datos *(Ej: Tablas en PostgreSQL/Supabase, políticas RLS).*
+> 2. **Capa de Negocio (Backend):** Desarrollo de la lógica en los servicios, controladores y repositorios, asegurando que los endpoints devuelvan los datos correctos.
+> 3. **Capa de Presentación (Frontend):** Integración de las APIs con la interfaz de usuario, manejo del estado global y refinamiento visual.
+> 
+> *Este enfoque garantiza que cuando se llega al frontend, la base de datos y la lógica ya son estables y predecibles.*
+
+---
+
+## c. Granularidad Extrema para la IA (Micro-Tasking)
+
+El mayor riesgo al programar con Inteligencia Artificial es el exceso de contexto. Si se le pide a la IA que programe un módulo entero, alucinará, inventará variables y romperá el código existente.
+
+> [!warning] Regla de Oro del Desarrollo Asistido: "Un método a la vez"
+> - **Trabajo Aislado:** La tarea mínima entregable no es "Hacer el Login", sino "Implementar la lógica del método `registrar()` en `AuthServiceImpl`".
+> - **Foco Absoluto:** Al delegar a la IA (Claude, Cursor, etc.), el prompt solo debe contener el esqueleto de ESE método específico y sus dependencias directas.
+> - **Testeo Inmediato:** Una vez que la IA devuelve el código de ese método, se verifica que cumpla el contrato, se repara si hay errores menores y recién entonces se pasa al siguiente método del backlog.
+
+---
+
+## d. Refinamiento Continuo (Refactoring Temprano)
+
+Si durante el desarrollo de un método se percibe que la tarea es demasiado compleja o que la IA empieza a cometer errores de lógica, se aplica un freno inmediato.
+
+> [!caution] Protocolo de división
+> - Si un método requiere **más de 3 responsabilidades distintas** *(Ej: Validar usuario, subir imagen, procesar pago y enviar correo)*, la tarea original se considera "demasiado grande".
+> - Se pausa el desarrollo, se subdivide la tarea en el backlog en funciones más pequeñas y privadas, y se vuelve a aplicar el *Micro-Tasking* método por método.

package/docs/referencia-metodologia/Fase - 7 .- Desarrollo activo, pruebas y control de versiones.md

@@ -0,0 +1,98 @@
+
+---
+> [!abstract] Objetivo de la Fase
+> En esta etapa, el código se construye de forma iterativa tomando cada método del backlog, programándolo con asistencia de IA, probándolo exhaustivamente y asegurando su versionado. La disciplina en esta fase es innegociable para evitar que el proyecto colapse a medida que escala la complejidad.
+
+## a. Metodología de Pruebas (Testing y Criterios de Aceptación)
+
+No se asume que el código entregado por la IA funciona solo porque compila. Cada método individual debe superar una batería de pruebas manuales y lógicas antes de darse por terminado.
+
+> [!warning] Niveles de validación por método
+> 1. **Definición de Criterios:** Antes de probar, se establecen los criterios de aceptación exactos de lo que debe cumplir el método.
+> 2. **Prueba de Humo (Smoke Test):** Se ejecuta el flujo feliz (*Happy Path*) para validar que la función hace lo mínimo esperado sin romperse.
+> 3. **Prueba de Errores e Inputs Inválidos:** Se inyectan datos corruptos, nulos o malformados para asegurar que el sistema maneje las excepciones correctamente y no exponga información sensible.
+> 4. **Pruebas de Estado Inter-métodos:** Se evalúa cómo reacciona el método si un estado previo (manejado por otras funciones) falla o cambia inesperadamente. Si se detectan fugas lógicas, se crean tests o validaciones específicas para cubrir esa eventualidad.
+
+---
+
+## b. Control de Versiones y Trazabilidad (Micro-Commits)
+
+El uso de Git (GitHub) no es solo para guardar el código, sino que funciona como la bitácora exacta de avance del proyecto. Se evita hacer commits gigantescos que mezclan múltiples funcionalidades.
+
+> [!info] Protocolo de Commits y Tracking
+> - **Commit por Método:** Se realiza un commit de forma inmediata cada vez que un método es completado y supera las pruebas.
+> - **Mensajes Detallados:** El mensaje del commit debe explicar claramente qué cambios se hicieron, por qué se hicieron y cómo afectan al sistema.
+> - **Checklists de Estado (Task Lists):** En la descripción del commit o pull request, se pega una lista de tareas (checkboxes) del módulo actual. Se van marcando las tareas completadas, dejando un registro visual claro de cuánto falta para terminar esa sección específica.
+
+---
+
+## c. Ejemplo Práctico de un Commit Estandarizado
+
+Para mantener la legibilidad del historial del proyecto, todos los commits deben seguir una estructura similar a esta, incluyendo siempre la versión actual y la fecha de modificación en el checklist:
+
+> [!example] Estructura del Commit
+> **Título del Commit:**
+> `feat(auth): implementación y validación de método registrar() en AuthServiceImpl`
+> 
+> **Cuerpo / Descripción del Commit:**
+> ```text
+> - 
+> - 
+> - Se integró la lógica de hasheo de contraseñas usando BCrypt.
+> - Se configuró el manejo de excepción `UsuarioYaExisteException` si el username está duplicado.
+> - Se probó exitosamente en Postman inyectando datos nulos y duplicados.
+> 
+> Progreso del Módulo Auth | Versión Actual: v1.2.3 | Fecha: 25-04-2026
+> - [x] registrar()
+> - [ ] login()
+> - [ ] refresh()
+> - [ ] logout()
+> ```
+> *Nota: Este formato permite que, con un simple vistazo al historial de Git, se sepa exactamente en qué estado, versión y fecha quedó el módulo tras el cambio.*
+
+<type>(<scope>): <descripción corta en imperativo>
+
+- cambio 1
+- cambio 2
+- cambio 3
+
+Progreso del módulo <nombre>:
+- [x] función lista
+- [ ] función pendiente
+- [ ] función pendiente
+- [ ] función pendiente
+
+Versión actual: vx.y.z
+Fecha: YYYY-MM-DD
+---
+
+## d. Gestión de Despliegues y Versionado Semántico
+
+Para optimizar recursos y no agotar tokens o minutos de compilación innecesarios en plataformas como Netlify o Railway, el despliegue no está automatizado en cada push. Se realiza de forma manual, controlada y estratégica.
+
+- **Estabilidad Garantizada:** Solo se desencadena un despliegue (Deploy) cuando se define que el conjunto de métodos terminados conforma una versión completamente estable y funcional.
+- **Versionado Semántico (SemVer):** Cada subida a producción se rige por un cambio en la versión del software *(Ej: v1.2.3)*.
+
+---
+
+## e. Sistema de Criterios para Cambio de Versión (SemVer Checklist)
+
+Para eliminar la ambigüedad sobre qué número de versión debe actualizarse (Mayor.Menor.Parche), se aplica el siguiente cuestionario de impacto cada vez que se decide subir a producción. Se actualiza el número de la categoría más alta en la que se responda "Sí" a al menos una pregunta.
+
+> [!success] Nivel 1: Versión de Parche / Patch (Ej: `v1.2.3` pasa a `v1.2.4`)
+> **Impacto:** Mantenimiento puro. El usuario apenas nota el cambio.
+> - [ ] ¿Se arregló un bug visual o lógico que estaba fallando en producción?
+> - [ ] ¿Se optimizó una consulta a la base de datos sin cambiar el resultado final?
+> - [ ] ¿Se corrigieron textos, colores o pequeños detalles de UI?
+
+> [!tip] Nivel 2: Versión Menor / Minor (Ej: `v1.2.4` pasa a `v1.3.0`)
+> **Impacto:** Evolución segura. Nuevas cosas disponibles, pero lo viejo sigue funcionando igual.
+> - [ ] ¿Se agregó una funcionalidad completamente nueva (Ej: Nuevo botón, nueva pantalla, nuevo endpoint de API)?
+> - [ ] ¿Se integró un nuevo microservicio o herramienta de terceros (Ej: Nueva pasarela de pagos opcional)?
+> - [ ] ¿Se agregó una nueva tabla a la base de datos para soportar una nueva característica?
+
+> [!danger] Nivel 3: Versión Mayor / Major (Ej: `v1.3.0` pasa a `v2.0.0`)
+> **Impacto:** Ruptura o Reinvención (Breaking Changes). Lo viejo ya no funciona como antes.
+> - [ ] ¿Se alteró la estructura de la base de datos de tal forma que los datos antiguos debieron ser migrados?
+> - [ ] ¿Se eliminaron endpoints de la API o se cambió la forma en que el frontend debe comunicarse con el backend?
+> - [ ] ¿Se rediseñó completamente la experiencia de usuario (UX) obligando al cliente a aprender a usar el sistema de nuevo?