7.9 KiB
7.9 KiB
INICIO-AQUI.md — Punto de entrada para nuevos desarrollos frontend
La guía única que consolida todo el stack cognitivo y técnico de frontend-ai
Para: cualquier desarrollador de frontend o agente autónomo que empiece a trabajar en este proyecto
Tiempo estimado de lectura: 10 minutos
Tiempo estimado antes de escribir código: completar el §PASO 1
Mapa del proyecto
ibanking-ai-api/
│
├── AGENT.md ← SE CARGA AUTOMÁTICAMENTE en cada sesión de IA
│ (system prompt de frontend — NO EDITAR sin consenso)
│
├── INICIO-AQUI.md ← ESTE ARCHIVO — leerlo primero
│
├── docker-compose.yml ← NUEVO: Servidor WireMock local para APIs downstream
├── setup.sh ← NUEVO: Script de inicialización para Linux/Mac
├── setup.ps1 ← NUEVO: Script de inicialización para Windows
├── .env.local.template ← NUEVO: Plantilla de variables de entorno locales
│
├── mocks/ ← NUEVO: Mappings JSON de WireMock para simulación local
│ └── mappings/
│ ├── auth-me.json
│ ├── cuentas.json
│ └── transferencias.json
│
├── standards/ ← Referencia operacional durante la implementación
│ ├── README.md
│ ├── 01-log-tracing.md ← Server & client logging, enrutador POST /api/logs
│ ├── 02-security-tracing.md ← Middleware de sesión, cookies HTTP-only, cifrado Kong
│ ├── 03-headers-contract.md ← Propagación de traceId (sessionReference) y cookies JWT
│ ├── 04-configmap-management.md ← Gestión de .env.local, NEXT_PUBLIC_ y server private keys
│ └── 05-client-insumos.md ← ⭐ COMPLETAR CON EL DISEÑADOR/CLIENTE antes de empezar
│
├── docs/ ← Guías de referencia y visión del proyecto
│ ├── guia-4-implemented-pattern.md ← Los patrones clave de Next.js App Router y Zustand
│ ├── guia-4.5-skills-proposal.md ← Skills instalables y directrices del agente
│ ├── guia-prompting-v4.md ← Plantilla del prompt para generar UI robusta y segura
│ └── guia-v5-advanced-ai-architecture.md ← Integración avanzada con Engram Cloud + Graphify
│
├── .agents/ ← Skills congeladas comunitarias para excelencia operativa
│ ├── README.md
│ └── skills/
│ ├── test-driven-development/SKILL.md
│ ├── systematic-debugging/SKILL.md
│ ├── code-review-excellence/SKILL.md
│ ├── documentation-writer/SKILL.md
│ └── security-best-practices/SKILL.md
PASO 1 — Antes de abrir el editor (obligatorio)
1.1 Ejecutar el script de Setup Automatizado (Onboarding)
Ejecuta el script correspondiente a tu sistema operativo en la raíz del proyecto para inicializar el entorno, instalar dependencias de IA (Graphify, Engram) y crear tu archivo de configuración .env.local automáticamente:
# Para desarrolladores en macOS / Linux:
chmod +x setup.sh && ./setup.sh
# Para desarrolladores en Windows (PowerShell):
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process; .\setup.ps1
1.2 Levantar el Entorno de Mocks (Docker)
Para interactuar localmente con datos simulados y no quedar bloqueado por caídas de red o fallos en el backend:
docker-compose up -d
Esto levantará el servidor WireMock en http://localhost:8080 simulando de forma automática las respuestas del backend (Auth, Cuentas, y Transferencias).
1.3 Completar los insumos de pantalla y flujos
Abrir standards/05-client-insumos.md y completar las secciones de la interfaz de usuario con el cliente o equipo de producto:
- §1 Contrato de APIs e Integraciones (endpoints del backend Spring Boot)
- §2 Estructura y Comportamiento de la UI (Mockups, layouts y estados visuales)
- §3 Gestión de Estado en Cliente (variables a registrar en Zustand)
- §4 Niveles de Autenticación y Seguridad (páginas protegidas por middleware)
- §5 Trazabilidad y Eventos Críticos (qué logs registrar)
1.4 Verificar presencia de Skills locales
Los skills comunitarios están congelados y listos en .agents/skills/:
test-driven-development/SKILL.md(tdd estricto en frontend con Vitest/Testing Library)systematic-debugging/SKILL.md(diagnóstico paso a paso de estado e hidratación React)code-review-excellence/SKILL.md(checklist de accesibilidad, seguridad y rendimiento)documentation-writer/SKILL.md(documentación de Props y flujo de Zustand)security-best-practices/SKILL.md(sanitización, cookies y seguridad Kong en client)
1.5 Generar y actualizar el Knowledge Graph con Graphify
Para optimizar las búsquedas de código y componentes del agente:
# Registrar mcpServer local de Graphify (según se detalla en README.md)
# Actualizar el grafo tras cambios estructurales:
graphify update .
PASO 2 — El prompt de implementación de componentes
Plantilla de prompt rápido para inyectar al agente:
Implementa una pantalla/componente en Next.js siguiendo AGENT.md y docs/guia-4-implemented-pattern.md.
Reglas del Frontend Seguro:
- NO uses cookies ni secrets en el código del cliente.
- Utiliza Server Components por defecto. Usa 'use client' solo si hay interactividad.
- Centraliza estados globales en el store de Zustand en lib/auth/client/useAuthStore.ts.
- Registra logs críticos llamando al logger del cliente (client-logger) o servidor.
### Contexto de la Pantalla:
- Nombre: [ej. Dashboard / Perfil / Historial]
- Ruta: [ej. /dashboard o /api/user]
- Componentes UI requeridos: [ej. daisyUI tables, custom buttons]
### Insumos de la UI:
[pegar especificación de standards/05-client-insumos.md]
PASO 3 — Control de versiones y convencionalismo de commits
# Crear rama
git checkout -b feat/pantalla-<nombre-flujo>-agented
# Commit estructurado (Conventional Commit sin atribución AI)
git commit -m "feat(ui): [FRONTEND-SECURE] implementar pantalla de <nombre-flujo>
Pattern: Server-First, Zustand State
Skills: security-best-practices, code-review-excellence
Standards: standards/05-client-insumos.md completado"
PASO 4 — Checklist pre-PR (ejecutar desde el agente)
Haz una revisión completa con code-review-excellence
comparando la implementación contra el checklist de AGENT.md.
Reporta cualquier violación antes de continuar.
Referencia rápida — Los 5 pilares del Frontend Banesco
| # | Pilar | Solución Clave |
|---|---|---|
| 1 | Server-First | Server Components por defecto para fetching seguro y veloz |
| 2 | Cookies Protegidas | Cookies HTTP-only administradas server-side para JWT |
| 3 | Gobernanza de Estado | Stores Zustand puros y reactivos sin excesivos Contexts |
| 4 | Logs Enrutados | Centralización de logs del cliente mediante /api/logs a logs/app.log |
| 5 | Cifrado Perimetral | Encriptación Kong en datos confidenciales que viajan al cliente |
¿Cuándo consultar cada guía?
| Situación | Dónde ir |
|---|---|
| Primera vez en el proyecto | Este archivo |
| Definir campos de UI e integraciones | standards/05-client-insumos.md |
| Implementar logs en el cliente o servidor | standards/01-log-tracing.md |
| Autenticar rutas o encriptar datos | standards/02-security-tracing.md |
| Revisar el flujo de cookies y traceId | standards/03-headers-contract.md |
| Configurar archivos .env o variables públicas | standards/04-configmap-management.md |
| Entender patrones de Server/Client Components | docs/guia-4-implemented-pattern.md |
| Ver la propuesta de Skills y tooling | docs/guia-4.5-skills-proposal.md |
| Plantilla de prompt interactivo de UI | docs/guia-prompting-v4.md |
| Activar Engram Cloud y Graphify | docs/guia-v5-advanced-ai-architecture.md |