Skip to main content

Guías de Desarrollo

Bienvenido a las guías de desarrollo de InsureHero. Aquí se concentra el cómo: entorno, convenciones de código, extensión del monorepo sin romper el núcleo, contratos TypeScript, APIs Shield, tRPC, componentes y el landing de postventa (Vidanta).

Qué hay en esta sección​

GuíaContenido
Estructura base y extensiónQué partes son “base” estable, por dónde extender (adaptadores, rutas, tRPC) y anti‑patrones.
Interfaces y contratos TypeScriptDónde definir tipos, InsuranceAdapter, StandardRiskItem, Zod en bordes.
Nuevas rutas ShieldChecklist para endpoints bajo /api/shield, namespaces y versionado.
Guía de componentesComponentes React, carpetas, formularios, estilos.
Guía de tRPCRouters, procedimientos y uso en cliente.
Landing page VidantaRepo aparte (landing-next), variables y flujo post‑sales.

Orden de lectura recomendado​

  1. Configuración del entorno (abajo) y Estructura del monorepo.
  2. Estructura base y extensión + Integraciones (código) si trabajas con aseguradoras u orquestador.
  3. Según tu tarea: Interfaces…, Nuevas rutas Shield, tRPC o Componentes.

La referencia normativa de las APIs (tablas, autenticación) sigue en API Reference; estas guías son el manual de trabajo del repositorio.

Configuración del Entorno​

Requisitos Previos​

  • Node.js >= 18.17.x
  • Yarn (gestor de paquetes)
  • Git
  • Supabase CLI (opcional, para desarrollo local)

Instalación​

  1. Clonar el repositorio
  2. Instalar dependencias:
yarn install
  1. Compilar packages compartidos:
yarn compile

  1. Configurar variables de entorno (ver .env.example)

  2. Iniciar desarrollo:

yarn dev

Landing page Vidanta (repositorio aparte)​

El landing de Vidanta para titulares (OTP, viajeros, integración post-sales) vive en un proyecto Next.js fuera del monorepo principal. Contexto de negocio: Integraciones → Canal Vidanta. La guía técnica detallada (estructura del repo, variables, comandos) está en esta misma sección.

Estructura del Código​

Convenciones​

  • Componentes: PascalCase (ej: UserProfile.tsx)
  • Utilidades: camelCase (ej: formatDate.ts)
  • Tipos: PascalCase (ej: UserType.ts)
  • Constantes: UPPER_SNAKE_CASE (ej: MAX_RETRIES)

Organización de Archivos​

src/
├── app/              # App Router y API routes (`app/api/`)
├── components/       # Componentes React
├── integrations/     # Adaptadores externos, orquestador, contratos
├── trpc/             # Routers y procedimientos tRPC
├── utils/            # Utilidades
├── hooks/            # Custom hooks
├── stores/           # Estado global (Zustand)
└── types/            # Tipos TypeScript

La documentación de alto nivel de integraciones está en Integraciones (arquitectura) y el mapa HTTP en Superficies REST.

Flujo de Trabajo​

Crear una Nueva Feature​

  1. Crear branch desde develop
  2. Implementar cambios
  3. Agregar tests
  4. Ejecutar validaciones: yarn validate
  5. Crear Pull Request

Commits​

El proyecto utiliza Conventional Commits:

  • feat: Nueva funcionalidad
  • fix: Corrección de bug
  • docs: Documentación
  • style: Formato
  • refactor: Refactorización
  • test: Tests
  • chore: Tareas de mantenimiento

Testing​

Unit Tests​

yarn test

E2E Tests​

yarn test:e2e

Coverage​

yarn test:all

Linting y Formato​

Linting​

yarn lint

Formato​

yarn format

Verificar Formato​

yarn check-format