From 839955712873177d23c564a3905d8276b46fe4f9 Mon Sep 17 00:00:00 2001 From: alejandrobailo Date: Mon, 23 Feb 2026 16:50:31 +0100 Subject: [PATCH] docs(ui): update org docs for modal-based flow --- ui/docs/aws-organizations-bulk-connect.md | 42 ++++---- ui/docs/aws-organizations-remediation-plan.md | 97 +++++++++++++++++++ 2 files changed, 121 insertions(+), 18 deletions(-) create mode 100644 ui/docs/aws-organizations-remediation-plan.md diff --git a/ui/docs/aws-organizations-bulk-connect.md b/ui/docs/aws-organizations-bulk-connect.md index 78b4addd59..8e8ff8e5a6 100644 --- a/ui/docs/aws-organizations-bulk-connect.md +++ b/ui/docs/aws-organizations-bulk-connect.md @@ -274,7 +274,7 @@ Frontend Backend |-- POST /.../discoveries/{id}/apply --------------->| (6) Apply selections |<-- 200 { providers_created_count, ... } -----------| | | - | (Redirect to test-connection for created providers)| + | (Continue inside modal to Validate Connection step) | | | ``` @@ -741,35 +741,41 @@ When the backend detects an AWS account has been closed/suspended: ## 8. Existing Frontend Architecture -### Current Provider Form Structure +### Current Provider Form Structure (Modal Wizard - Current) ``` ui/ -├── app/(prowler)/providers/(set-up-provider)/ -│ ├── layout.tsx # Sidebar stepper + content area -│ ├── connect-account/page.tsx # Step 1 page -│ ├── add-credentials/page.tsx # Step 2 page -│ ├── test-connection/page.tsx # Step 3 page -│ └── update-credentials/page.tsx ├── components/providers/ │ ├── add-provider-button.tsx # Entry point button -│ ├── radio-group-provider.tsx # Provider type radio selector -│ ├── workflow/ -│ │ ├── workflow-add-provider.tsx # Main stepper display (3 steps) -│ │ ├── vertical-steps.tsx # Custom stepper with Framer Motion -│ │ └── forms/ -│ │ ├── connect-account-form.tsx # Step 1: Choose provider + enter UID -│ │ ├── test-connection-form.tsx # Step 3: Test & scan -│ │ ├── add-via-role-form.tsx # AWS role-based credentials -│ │ └── add-via-credentials-form.tsx # AWS static credentials +│ ├── wizard/provider-wizard-modal.tsx # Main modal wizard owner +│ ├── wizard/steps/ # Connect/Credentials/Validate/Launch steps +│ ├── organizations/org-setup-form.tsx # Org setup + discovery polling owner +│ ├── organizations/org-account-selection.tsx # Apply + Test Connections +│ ├── organizations/org-launch-scan.tsx # Launch schedule (daily/single) +│ └── workflow/forms/ # Reused provider forms inside modal steps ├── actions/providers/ │ └── providers.ts # Server actions (addProvider, etc.) +├── actions/organizations/ +│ └── organizations.ts # Organizations/discovery/apply server actions ├── hooks/ │ └── use-credentials-form.ts # Form schema + state management +├── store/organizations/ +│ └── store.ts # Organizations wizard client state └── types/ - └── providers.ts # TypeScript interfaces + ├── providers.ts # Provider interfaces + └── organizations.ts # Organizations/discovery/apply interfaces ``` +### Legacy Route-Based Flow (Deprecated) + +Sections in this document that reference routes such as: +- `/providers/connect-account` +- `/providers/add-credentials` +- `/providers/test-connection` +- `/providers/update-credentials` + +are historical context only. The active implementation runs end-to-end inside `provider-wizard-modal.tsx` and validates step transitions by modal content/state, not by URL. + ### Tech Stack - **Next.js 16** (App Router) diff --git a/ui/docs/aws-organizations-remediation-plan.md b/ui/docs/aws-organizations-remediation-plan.md new file mode 100644 index 0000000000..2af6ea99f3 --- /dev/null +++ b/ui/docs/aws-organizations-remediation-plan.md @@ -0,0 +1,97 @@ +# AWS Organizations Wizard Remediation Plan + +## Objetivo +Corregir bugs funcionales y deuda técnica detectada en la rama del nuevo wizard de proveedores, manteniendo la UX acordada para AWS Organizations. + +## Decisiones Confirmadas +- El backend **no garantiza** el orden de `relationships.providers.data` respecto a `accounts` en `applyDiscovery`. +- Debemos **mantener** la validación de conexiones al pulsar `Test Connections`. +- Debemos **actualizar E2E** al flujo modal actual y eliminar dependencia de rutas legacy. + +## Alcance +- UI (`ui/components/providers/**`, `ui/actions/**`, `ui/store/**`, `ui/types/**`). +- Tests E2E (`ui/tests/providers/**`). +- Documentación técnica en `ui/docs/**`. +- Si hace falta contrato backend para mapping determinista, incluir cambio en API dentro del mismo PR o PR dependiente explícito. + +## Plan de Ejecución + +## Fase 1: Corregir Bugs Críticos de Datos +### 1.1 Mapping determinista Account -> Provider +- Problema actual: se hace mapping por índice entre `sanitizedSelectedAccountIds` y `providers.data`. +- Riesgo: errores y estados de conexión asignados a cuentas equivocadas. +- Acción: + - Introducir mapping explícito en la respuesta de `applyDiscovery` (preferido): `[{ account_id, provider_id }]`. + - Adaptar frontend para construir `accountToProviderMap` con ese mapping, sin usar índices. + - Fallback temporal solo si el backend no llega: resolver providers por `uid === accountId` en una consulta controlada. +- Criterio de aceptación: + - Con response desordenada, cada cuenta sigue mostrando su propio estado/error correctamente. + +## Fase 2: Normalizar Polling y Reducir Agresividad +### 2.1 Test Connections polling +- Acción: + - Limitar concurrencia de tests (ejemplo: 5 en paralelo). + - Aumentar intervalo base o usar backoff (ejemplo: 2s -> 3s -> 5s, con tope). + - Eliminar `getTask` extra final si `checkTaskStatus` ya devuelve `result` completo. +- Criterio de aceptación: + - Menos requests por minuto sin empeorar tiempo total percibido. + - No hay picos masivos al testear organizaciones grandes. + +### 2.2 Discovery polling duplicado +- Acción: + - Mantener **un solo owner** de polling para discovery. + - Eliminar o integrar `OrgDiscoveryLoader` si sigue siendo ruta muerta. + - Conservar la pantalla de `Validate Connection` para test de cuentas, que sí es obligatoria. +- Criterio de aceptación: + - No existe doble polling para discovery en el flujo real. + +## Fase 3: Limpieza de Código Stale/No Usado +### 3.1 Limpieza funcional +- Eliminar bloques de UI inalcanzables (ejemplo: `DETAILS && isSubmitting` en setup). +- Eliminar props no usadas o cablearlas correctamente (ejemplo: `hasConnectionErrors` en stepper). +- Revisar y eliminar lógica redundante de estados intermedios de wizard. + +### 3.2 Limpieza documental +- Actualizar `ui/docs/aws-organizations-bulk-connect.md` para reflejar flujo modal. +- Marcar explícitamente como legacy cualquier sección basada en rutas eliminadas. + +## Fase 4: Actualizar E2E al Flujo Modal +### 4.1 Refactor de page object +- Sustituir asunciones de URL legacy (`/providers/connect-account`, `/add-credentials`, `/test-connection`, `/update-credentials`) por selectores del modal y estados del stepper. +- Añadir helpers para: + - abrir/cerrar modal, + - avanzar por pasos del wizard, + - validar transiciones internas por contenido visible, no por URL. + +### 4.2 Cobertura mínima recomendada +- Alta de provider single-account. +- Alta por Organizations + `Test Connections`. +- Retry parcial cuando fallan algunas cuentas. +- Back navigation desde account tree hacia `Authentication Details`. +- Launch scan con selector `daily/single`. + +## Fase 5: Validación y Hardening +- Ejecutar `typecheck`, `eslint`, tests unitarios y E2E afectados. +- Añadir test unitario del mapping account->provider sin orden estable. +- Añadir test unitario del controlador de polling (concurrencia/backoff). +- Checklist final: + - Sin logs de debug residuales. + - Sin imports/props dead. + - Sin documentos desalineados con la implementación. + +## Entregables +- Código corregido en UI (y API si se requiere contrato de mapping). +- E2E migrados y verdes. +- Documentación actualizada. +- Nota de PR con riesgos, decisiones y estrategia de rollback. + +## Riesgos y Mitigación +- Dependencia de contrato backend para mapping: mitigar con fallback temporal documentado. +- Cambios en E2E pueden romper suites existentes: migrar page object en un PR dedicado y reusar helpers. +- Ajustar polling puede alterar timing de UX: validar con organizaciones pequeñas y grandes. + +## Orden Recomendado de PRs +1. PR de bug crítico de mapping account->provider. +2. PR de polling/concurrencia. +3. PR de limpieza stale + docs. +4. PR de migración E2E.