Join Sailor Sam on a delightful ocean adventure aboard his trusty tugboat, 'The Mighty Tug'! With his magical Sea-Smart Tablet, Sam navigates sparkling waters, solves sea-snarls, and fills out 'Adventure Scrolls' to keep the ocean safe and sound. This vibrant tale celebrates helpful technology, quick thinking, and the joy of maritime life, all brought to life with cheerful illustrations and playful characters.
Rol: Actúa como un Arquitecto de Software Senior Full-Stack especializado en aplicaciones empresariales de misión crítica y alta usabilidad (UX). Objetivo: Diseñar y construir el "Sistema de Gestión de Operaciones Marítimas", una aplicación web progresiva (PWA) para tripulantes de remolcadores. La aplicación debe consumir la API de Helm Connect, ofrecer un dashboard intuitivo y un sistema de llenado de formularios secuencial estilo "Typeform" de alta fidelidad. Nivel de Calidad: Enterprise-Grade. Código modular, tipado estricto, manejo de errores robusto para conexiones inestables y UI/UX de clase mundial optimizada para tablets/móviles. 1. Stack Tecnológico Definido Frontend (Cliente - Tripulante): Framework: React 18+ (Vite). Lenguaje: TypeScript (Modo estricto obligatorio). Estilos: Tailwind CSS (Diseño mobile-first, componentes grandes para uso con guantes). Estado & Formularios: React Hook Form + Zod (Validación) + Zustand (Estado global de la sesión). UX/Animaciones: Framer Motion (Para lograr transiciones suaves entre pasos tipo Typeform). Backend (BFF - Proxy Seguro): Framework: FastAPI (Python 3.10+). Validación de Datos: Pydantic v2 (Modelos estrictos que reflejen la documentación de Helm). Cliente HTTP: httpx con implementación de tenacity para reintentos automáticos (exponential backoff) ante fallos de red satelital. Caching: Implementar caché en memoria (ej. Redis o local) para datos de baja rotación como /assets. 2. Integración API Helm Connect (Reglas de Negocio Estrictas) El backend FastAPI debe encapsular toda la lógica de Helm. El frontend NUNCA llama a Helm directamente. Configuración del Cliente HTTP (Python): Base URL: Configurable por variable de entorno. Auth Headers: Debe inyectar API-Key: {TU_API_KEY} y Content-Type: application/json en cada petición. ¡NO usar prefijo 'Bearer'! Mapeo de Endpoints Verificados (Implementar en Servicios FastAPI): Servicio de Activos (Assets): GET /api/v2/public/assets: Obtener lista de remolcadores. Cachear respuesta por 24h. Mapear campos clave: Id, Name. Servicio de Dashboard: GET /api/v2/public/tasks: Listar tareas pendientes. POST /api/v1/jobs/jobs/AcknowledgeJob: Botón de acción rápida para reconocer trabajos. Servicio de Formularios (Motor Crítico): Listar (Regla de Oro): Al llamar a GET /api/v2/public/forms, es OBLIGATORIO inyectar el parámetro de query $filter=AssetId eq '{TUG_UUID}'. Si no se envía, la API retorna error 400. Detalle: GET /api/v2/public/forms/{Id}. Extraer la estructura ItemValues para construir el formulario. Finalizar: PATCH /api/v2/public/forms/{Id}. Enviar el payload completo de respuestas al terminar. Manejo de Respuestas v2: El backend debe interceptar el wrapper estándar { "Data": { "Results": [...] } } y devolver al frontend solo el array limpio de datos para simplificar el consumo en React. 3. Especificaciones de UX/UI (Frontend React) A. Dashboard "Tripulante-Centric" Diseño: Minimalista, tarjetas grandes, tipografía clara. Selector de Contexto: Un dropdown prominente al inicio para seleccionar el Remolcador (Asset) actual. Esto filtra toda la aplicación. Semáforo de Prioridad: Sección "Crítico" (Rojo): Formularios/Tareas con DueDate vencido o estado 'Overdue'. Sección "Próximo" (Amarillo): Pendientes para la semana actual. B. Motor de Formularios "Typeform-Style" (Wizard) No renderizar una lista larga de inputs. Implementar un componente de pasos (Stepper): Vista Unitaria: Solo se muestra UNA pregunta a la vez en el centro de la pantalla con una transición animada (fade-in/slide-up) al cambiar. Navegación Intuitiva: Preguntas Booleanas (Sí/No): Botones gigantes que avanzan automáticamente al hacer clic. Otros inputs: Botón "Siguiente" grande y claro. Permitir navegación atrás. Barra de Progreso Real: Indicador visual superior (ej. "Pregunta 3 de 15"). Persistencia Local: Guardar el progreso en localStorage del navegador. Si la tablet se apaga, al volver debe estar en la misma pregunta. 4. Entregables Solicitados Genera la estructura del proyecto y el código esencial para los siguientes componentes clave, demostrando la conexión entre ellos: Backend (/backend/app/services/helm_service.py): La clase Python usando httpx y tenacity que implementa la llamada segura a /api/v2/public/forms con la regla obligatoria del $filter. Tipos Frontend (/frontend/src/types/helm.d.ts): Interfaces TypeScript derivadas de la documentación para asegurar el tipado de las respuestas. Componente Wizard (/frontend/src/components/forms/FormWizard.tsx): El esqueleto del componente React que orquesta el estado de los pasos, la animación con Framer Motion y la presentación de una pregunta a la vez.
