0. Ficha del proyecto
1. Descripción general del producto
2. Arquitectura del sistema
3. Modelo de datos
4. Especificación de la API
5. Historias de usuario
6. Tickets de trabajo
7. Pull requests

**

TBD

Puede ser pública o privada, en cuyo caso deberás compartir los accesos de manera segura. Puedes enviarlos a [email protected] usando algún servicio como onetimesecret.

https://github.com/Criptos/Innovacion-Fase-0

Propósito: Digitalizar, centralizar y hacer accionable la Fase 0 del proceso de innovación de productos . Valor que aporta: Transforma el entendimiento del usuario de un ejercicio estático a un "activo vivo" que se revalida continuamente a lo largo de todo el ciclo de vida del producto (Fases 1 a 5) . Reduce el riesgo crítico de desarrollar una solución desconectada de las necesidades reales del mercado (Riesgo R1) . Qué soluciona: Elimina el trabajo en silos y las suposiciones o sesgos internos al proporcionar una "brújula de usuario" estructurada para todo el equipo multidisciplinario . Para quién: Principalmente para el Líder de Producto / Negocio (responsable de definir requerimientos), Arquitectos de Soluciones e Investigadores/Diseñadores que participan en la etapa temprana de ideación

El producto contará con un gestor de usuarios independiente y se estructurará en módulos funcionales orientados a la captura y exportación de valor: Módulo 1: Identificación de Jobs-To-Be-Done (JTBD) e Integración Gestor de "Job Statements": Formularios para capturar los trabajos funcionales, emocionales y sociales del usuario . Creador de "Job Stories": Plantillas para documentar situaciones con la estructura Cuando [Contexto] + Quiero [Motivación] + Para poder [Progreso] . Centro de Integraciones (Jira/Confluence): Panel de configuración donde los usuarios podrán dar de alta y gestionar de forma segura sus credenciales (API Keys / Tokens) de Jira y Confluence. Exportador Ágil: Funcionalidad para empujar con un solo clic las "Job Stories" validadas y el "Mapa de Oportunidades" directamente a Jira, convirtiéndolas automáticamente en Épicas o User Stories , listos para el Product Backlog de la Fase 3 . Módulo 2: Mapa de Empatía Dinámico Canvas Interactivo de 6 Cuadrantes: Lienzo digital para mapear lo que el usuario Piensa/Siente, Ve, Oye, Dice/Hace, junto con sus Dolores (Pains) y Ganancias (Gains) . Gestor de Insights: Herramienta para agrupar post-its o notas similares generadas durante la lluvia de ideas . Módulo 3: Perfilado Técnico y Táctico Mapeo Informacional DACI: Formulario ilustrativo para documentar las 3 dimensiones del rol del Buyer Persona (Formal, Funcional y de Influencia) . Aquí se registrará si el cliente/usuario analizado actúa como Driver, Approver, Contributor o Informed . Nota: Esta información es netamente documental para el análisis del perfil y no afecta los permisos de acceso a nuestra aplicación. Priorizador de Dolores: Matriz para catalogar dolores en Síntoma, Causa e Impacto . Gestor de Canales: Registro de dónde consume información el usuario . Módulo 4: Seguridad y Rendimiento (Backend) Rate Limiting & OWASP: Motor de seguridad basado en Redis para prevenir ataques de fuerza bruta, controlar el límite de peticiones (Rate Limiting) por IP/Usuario y mitigar vulnerabilidades del Top 10 de OWASP en los endpoints de Swoole. .

Nota: La siguiente descripción está concebida para que el equipo de diseño UI construya los prototipos basándose estrictamente en las guías de Google Material Design (M3) utilizando los componentes nativos de Angular 19. Estética General: Uso extensivo de Material Cards con sombras sutiles (elevation) para separar la información, Floating Action Buttons (FAB) en la esquina inferior derecha para añadir rápidamente nuevos hallazgos (ej. un nuevo Dolor o un nuevo Job Story), y Snackbars para confirmar acciones (ej. "Exportado a Jira exitosamente"). Navegación: Un Navigation Drawer (menú lateral colapsable) oscuro o neutro para cambiar entre Iniciativas/Proyectos. Dentro de la "Fase 0", el flujo se manejará mediante Material Tabs horizontales: 1. JTBD | 2. Mapa de Empatía | 3. Perfilado | 4. Exportación. Experiencia del Mapa de Empatía: Un lienzo responsivo dividido en 6 zonas . Al hacer clic en el FAB, se abrirá un Material Dialog (modal) para escribir la nota y elegir el cuadrante, representándose luego como pequeñas tarjetas de colores tipo "post-it" dentro de la cuadrícula. Gestión de Integraciones: Una pantalla de configuración limpia con Text Fields delineados (Outlined) para introducir de manera enmascarada las credenciales de Jira/Confluence, con un botón para realizar un "Test de Conexión" antes de guardar.

graph TD %% Definición de Usuario y Frontend User(("👤 Usuario\n(Líder / Arquitecto)")) UI["💻 Angular 19\n(Frontend - Material Design)"]

%% Capa de Seguridad y Balanceo
WAF["🛡️ Nginx + OWASP\n(API Gateway / Rate Limiting)"]

%% Ecosistema Hexagonal (Microservicios)
subgraph Microservicios [Microservicios PHP/Swoole - Arquitectura Hexagonal]
    direction TB
    
    subgraph Puertos_Entrada [Puertos de Entrada / Driving Ports]
        PortHTTPS("🔌 Puerto HTTPS\n(Controladores REST)")
        PortObs("🔌 Puerto de Observabilidad\n(Métricas / Health Check)")
    end

    Dominio(("🧠 Dominio y Lógica de Negocio\n(Casos de Uso / Phase 0 Core)"))

    subgraph Puertos_Salida [Puertos de Salida / Driven Ports]
        PortDB("🔌 Puerto de Persistencia\n(Repositorios)")
        PortCache("🔌 Puerto de Seguridad/Caché\n(Gestor de Políticas)")
        PortLogs("🔌 Puerto de Bitácoras\n(Eventos / Logs)")
    end

    %% Conexiones internas del hexágono (Inversión de Dependencias)
    PortHTTPS -->|Invoca Casos de Uso| Dominio
    PortObs -->|Monitorea Estado| Dominio
    Dominio -->|Usa Interfaces| PortDB
    Dominio <-->|Consulta/Actualiza| PortCache
    Dominio -->|Registra| PortLogs
end

%% Infraestructura Externa (Adaptadores)
DB[("🗄️ MariaDB / MySQL\n(Datos Relacionales)")]
Redis[("⚡ Valkey / Redis\n(Rate Limit / OWASP)")]
Logs["📄 Sistema de Bitácoras\n(Archivos / ELK)"]
Monitor["👁️ Plataforma de Observabilidad\n(Prometheus / Grafana)"]

%% Flujo de Interacción Externa
User -->|Interactúa| UI
UI -->|Peticiones seguras| WAF
WAF -->|Ruteo| PortHTTPS

Monitor -->|Scraping / Polling| PortObs

PortDB -->|Lectura / Escritura| DB
PortCache <-->|Validación y Tokens| Redis
PortLogs -->|Escritura de logs| Logs

%% Estilos básicos
classDef hexagonal fill:#f9f9f9,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5;
class Microservicios hexagonal;

. Capa de Presentación (Frontend y Usuario) Componente: UI (Angular 19 - Material Design). Tecnologías: Node.js (v20+) y Angular CLI (v19.x). Función Técnica y de Negocio: Es el punto de interacción principal para el "Líder de Producto / Negocio" y el "Arquitecto de Soluciones" . A través de componentes responsivos de Material Design compilados con Node/Angular CLI, se renderizan las interfaces clave de la Fase 0, como el Canvas interactivo de los 6 cuadrantes del Mapa de Empatía y los formularios para capturar las "Job Stories" sin hacer mención a la tecnología . 2. Capa de Seguridad Perimetral y Balanceo (WAF / API Gateway) Componente: WAF (Nginx + OWASP). Tecnologías: Nginx configurado con el módulo ModSecurity. Función Técnica y de Negocio: Actúa como proxy inverso y la primera línea de defensa de la infraestructura. ModSecurity inspecciona todas las peticiones HTTPS entrantes desde Angular para bloquear inyecciones SQL, Cross-Site Scripting (XSS) y otras vulnerabilidades del Top 10 de OWASP. Además, funciona como el ruteador principal hacia los microservicios, asegurando que las entidades puras del dominio nunca queden expuestas directamente a internet. 3. Capa de Microservicios (Arquitectura Hexagonal en PHP) Componente: Ecosistema PHP/Swoole (Microservicios). Tecnologías: PHP (8.2+) con extensión Swoole (para concurrencia y procesamiento asíncrono) y dependencias gestionadas mediante Composer. Función Técnica y de Negocio: Aquí reside el "cerebro" de la aplicación. Swoole permite que PHP mantenga su estado en memoria, procesando múltiples peticiones simultáneas con latencias mínimas. Puertos de Entrada (Driving Ports): Los controladores REST reciben las peticiones seguras de Nginx. El Puerto de Observabilidad expone métricas de salud (health checks) vitales para construir los Tableros de Control Técnicos exigidos como salida obligatoria en la Fase 4 . Dominio y Lógica de Negocio: Lógica pura de PHP (sin dependencias externas gracias a Composer). Aquí residen las reglas matemáticas e lógicas, como la Matriz de priorización de dolores que clasifica automáticamente un dolor en "Crítico, Importante o Latente" cruzando su Frecuencia e Impacto . Puertos de Salida (Driven Ports): Interfaces (contratos) que dictan cómo la lógica central se comunicará con las bases de datos o sistemas de caché. Al aislar así el Dominio, se mitiga directamente el Riesgo R2 ("Desviación o sobrecostos imprevistos en la solución"), asegurando que la tecnología se someta a las reglas de negocio y no al revés . 4. Capa de Infraestructura Externa (Adaptadores de Salida) Componente: Puerto de Persistencia (Base de Datos Relacional). Tecnologías: Servidor MariaDB (v10.11+ o superior). Función Técnica y de Negocio: Implementa los repositorios dictados por el Puerto de Salida. MariaDB almacenará permanentemente la información transaccional estructurada: las declaraciones de Jobs-To-Be-Done y el control de versiones del Mapa de Empatía, garantizando que este último se comporte a nivel de sistema como un "activo vivo" que puede consultarse y re-validarse en las Fases 1 a la 5 . Componente: Puerto de Seguridad y Caché (Rate Limiting). Tecnologías: Servidor Valkey (v7.2+ o superior). Función Técnica y de Negocio: Operando como un reemplazo directo y 100% compatible de Redis, Valkey almacena claves-valor en memoria a velocidades extremadamente altas. Su función principal será validar tokens temporales de sesión de los usuarios, gestionar las políticas de limitación de tasa (Rate Limiting) en coordinación con Nginx+ModSecurity, y acelerar las consultas frecuentes a la base de datos (por ejemplo, cargar rápidamente los catálogos de los roles DACI ). Componente: Puerto de Bitácoras (Logs). Tecnologías: Sistema de archivos y salida estándar (preparado para ingesta por plataformas ELK/Prometheus). Función Técnica y de Negocio: Registra todos los eventos del sistema.

Se definenn de esta forma para openspec: schema: spec-driven

context: | Este proyecto implementa un servidor de Mocking de APIs de alto rendimiento sobre OpenSwoole en PHP. Pila Tecnológica (Tech Stack):

• Lenguaje: PHP 8.x+ con tipos estrictos declarados obligatoriamente (declare(strict_types=1);).
• Servidor HTTP: OpenSwoole (openswoole/core). Diseño puramente stateless (sin persistencia de datos).
• Logging: Monolog (monolog/monolog). Configuración: Se debe utilizar la configuración por defecto de Monolog. No se permite el uso de LineFormatter personalizados o formateadores adicionales para asegurar la simplicidad y consistencia en los logs.
• Librería de Pruebas: PHPUnit (phpunit/phpunit v11+). Estructura de Directorios y Espacios de Nombres (PSR-4 App\ -> src/, Tests\ -> tests/):
• Dominio (src/Domain/): Entidades de respuesta, definidores de esquemas (JSON Schemas) y reglas de negocio para la generación de respuestas simuladas. Los modelos de datos deberán vivir en el directorio src/Domain/Model y las excepciones en src/Domain/Exception.
• Aplicación (src/Application/): Casos de Uso (Simulación de Endpoints) y Puertos (Ports) definidos como interfaces (ej. HttpInputPort, ResponseGeneratorPort), los puertos de entrada creados en src/Application/Ports/In y los puertos de salida creado en src/application/Ports/Out para separar la loginca de entrada y salida.
• Infraestructura (src/Infrastructure/): Adaptadores concretos para HTTP/HTTPS (incluyendo autodetección de certificados SSL: la carpeta ssl/ será la ubicación por omisión para buscar, crear o actualizar los certificados; si no existen en dicho directorio, genera certificados genéricos para asegurar la encriptación) y Logger. Sin adaptadores de base de datos o colas.
• Scripts de Entrada (bin/): Script del servidor (bin/server.php). Pautas de Diseño y Pruebas:
• Diseño 100% Stateless: No se utiliza base de datos, caché persistente, ni colas de mensajería. Toda la lógica reside en memoria y se reinicia con el servidor.
• Pruebas:
  • Unitarias (tests/Unit/): Prueban la lógica de coincidencia de peticiones y generación de respuestas (Mocking).
  • E2E (tests/E2E/): Prueban flujos completos levantando el servidor HTTP de OpenSwoole contra peticiones reales. rules: proposal:
• El diseño debe justificar la lógica de match (ej. qué criterios de Request se usan para retornar qué Response).
• Describir cómo se mantiene la arquitectura hexagonal sin persistencia (puertos de entrada HTTP, lógica pura en aplicación).
• El código generado debe estar documentado, explicando el propósito de cada componente.
• Cada uso de la directiva use debe ir acompañado de un comentario que explique su necesidad específica en ese contexto.
• El proceso debe seguir el orden: primero diseñar la arquitectura y lógica, y posteriormente documentar el código resultante. specs:
• Utilizar formato Given/When/Then.
• Incluir casos de prueba para validar el comportamiento del mock (ej. "Given a GET /users request, When received, Then return 200 OK with specific JSON"). design:
• Definir firmas de interfaces con tipos estrictos.
• Estructura de adaptadores: Solo HTTP/HTTPS (Primary) y Logger (Secondary).
• Gestión de certificados: Incluir un switch o flag de configuración para permitir la rotación forzada de certificados SSL en caso de que estén vencidos, siempre que no sean los certificados autogenerados. tasks:
• Dividir las tareas estrictamente por capas: 1. Domain, 2. Application, 3. Infrastructure, 4. Tests.
• Cada tarea debe contener criterios de aceptación unitarios e independientes.

TBD

1. Seguridad Perimetral y Prevención de Ataques (Capa Adaptadora) WAF (Web Application Firewall) con Nginx y ModSecurity: Se implementará como la primera línea de defensa para inspeccionar todas las peticiones HTTPS entrantes desde Angular. Su función es bloquear vulnerabilidades del Top 10 de OWASP, como Inyecciones SQL y Cross-Site Scripting (XSS). Rate Limiting y Prevención de Fuerza Bruta: Utilizando Valkey (anteriormente Redis), se controlará la cantidad máxima de peticiones que una IP o usuario puede hacer por minuto. Esto protege a los microservicios PHP/Swoole de caídas por saturación o ataques de denegación de servicio (DDoS).
2. Aislamiento Estructural de los Datos (Arquitectura Hexagonal) Protección del Dominio: Al utilizar Arquitectura Hexagonal, las entidades de negocio puras (como los Job Stories o el Mapa de Empatía) nunca están expuestas directamente a internet. Toda interacción debe atravesar puertos de entrada estrictamente tipados. Mitigación de Riesgos Técnicos: Este aislamiento previene que vulnerabilidades en paquetes externos o bases de datos afecten el núcleo del sistema, ayudando a mitigar el Riesgo R2 (Desviación o sobrecostos imprevistos en la solución) .
3. Gestión Segura de Credenciales e Integraciones Cifrado de Tokens Tácticos: Dado que la aplicación empujará datos hacia Jira y Confluence, las credenciales (API Keys / Tokens) que los usuarios den de alta en el sistema se manejarán a través de variables de entorno seguras (.env) y se almacenarán de forma cifrada en la base de datos MariaDB para evitar fugas de información. Validación de Sesiones: El control de acceso de los usuarios a través del gestor independiente validará los tokens temporales de sesión directamente en memoria mediante Valkey para garantizar respuestas ultra rápidas y seguras.
4. Gobernanza, Trazabilidad y Auditoría (Alineado al Proceso de Innovación) Puertos de Bitácoras (Logs) y Observabilidad: El ecosistema de microservicios cuenta con puertos de salida dedicados a registrar de manera inmutable todos los eventos y accesos al sistema. Tableros de Control Técnicos: Estas bitácoras y métricas de salud (Health Checks) alimentarán plataformas de monitoreo para cumplir con la exigencia de la generación de Tableros de Control Técnicos . Auditoría Operativa: Toda esta trazabilidad permitirá que las áreas correspondientes puedan realizar auditorías precisas sobre el funcionamiento y rentabilidad de la herramienta sin comprometer la integridad de los datos .

Describe brevemente algunos de los tests realizados

Recomendamos usar mermaid para el modelo de datos, y utilizar todos los parámetros que permite la sintaxis para dar el máximo detalle, por ejemplo las claves primarias y foráneas.

Recuerda incluir el máximo detalle de cada entidad, como el nombre y tipo de cada atributo, descripción breve si procede, claves primarias y foráneas, relaciones y tipo de relación, restricciones (unique, not null…), etc.

Si tu backend se comunica a través de API, describe los endpoints principales (máximo 3) en formato OpenAPI. Opcionalmente puedes añadir un ejemplo de petición y de respuesta para mayor claridad

Documenta 3 de las historias de usuario principales utilizadas durante el desarrollo, teniendo en cuenta las buenas prácticas de producto al respecto.

Historia de Usuario 1

Historia de Usuario 2

Historia de Usuario 3

Documenta 3 de los tickets de trabajo principales del desarrollo, uno de backend, uno de frontend, y uno de bases de datos. Da todo el detalle requerido para desarrollar la tarea de inicio a fin teniendo en cuenta las buenas prácticas al respecto.

Ticket 1

Ticket 2

Ticket 3

Documenta 3 de las Pull Requests realizadas durante la ejecución del proyecto

Pull Request 1

Pull Request 2

Pull Request 3