179 lines
7.9 KiB
Markdown
179 lines
7.9 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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` |
|