Módulo: Home (Dashboard / Resumen)

Scope

Tipo de organización	Acceso
Empresa	✅ (dashboard completo)
Agencia	✅ (pasos de activación)
Reclutador independiente	✅ (pasos de activación)

---

Permisos por rol

Acción	Disponible	Permiso
Ver dashboard resumen	✅	Autenticado (sesión activa)
Ver pasos de activación	✅	Autenticado
Ver métricas clave	✅	Empresa APROBADA
Pull-to-refresh	✅	Autenticado

---

¿Qué es?

La pantalla principal post-login. Muestra un resumen ejecutivo adaptado al tipo y estado de la organización:

• Empresa aprobada: Vista ejecutiva con métricas (vacantes, candidatos, mesa de control, wallet), pasos de activación si faltan, acceso rápido a perfil público, y acciones recomendadas.
• Empresa/Agencia pendiente: Pasos de activación con progreso, requisitos faltantes (blockers/warnings), y acción principal para completar registro.
• Reclutador independiente: Pasos de activación, siguientes pasos sugeridos, y perfil público.

¿Qué puede hacer el usuario?

• Ver estado general de su organización (aprobada, pendiente, en revisión)
• Ver progreso de activación (pasos completados / totales)
• Ver métricas clave en tarjetas horizontales (empresa aprobada)
• Ver secciones por módulo: vacantes, candidatos, mesa de control, wallet
• Navegar a módulos específicos desde las tarjetas
• Ejecutar acciones recomendadas (revisar vacantes, candidatos, completar registro)
• Acceder al perfil público
• Subir evidencias de activación
• Pull-to-refresh para actualizar datos

Flujo del usuario

Empresa aprobada

1. Inicia sesión → ve dashboard con métricas reales
2. Vista ejecutiva: nombre, estado "LISTO", fecha de actualización
3. Acciones recomendadas → navega al módulo correspondiente
4. Métricas clave: vacantes publicadas, en cobertura, candidatos activos, disputas abiertas, wallet disponible
5. Secciones detalladas con mini charts
6. Pull-to-refresh recarga todo

Empresa/Agencia pendiente

1. Inicia sesión → ve pasos de activación
2. Barra de progreso con porcentaje
3. Pasos: cuenta creada → datos del perfil → evidencias → revisión de plataforma
4. Toca paso pendiente → navega a la pantalla correspondiente
5. Completa → regresa → ve progreso actualizado
6. Requisitos faltantes listados con severidad (BLOCKER / WARNING)

Reclutador independiente

1. Inicia sesión → ve pasos de activación del reclutador
2. Pasos: cuenta → perfil de reclutador → evidencias → activación
3. Siguientes pasos sugeridos (perfil, vacantes, candidatos)
4. Acceso rápido al perfil público

Reglas de negocio

• El dashboard solo muestra datos reales cuando la empresa está APROBADA
• El endpoint dashboard-summary solo existe para COMPANY; agencias y reclutadores muestran pasos de activación
• La validación de status siempre se intenta cargar (es opcional, no falla)
• Si dashboard-summary retorna 404/403, se muestra el estado pendiente
• Los pasos de activación reflejan el registrationProgress del backend
• Las acciones recomendadas se derivan del dashboard (nextActions)
• El perfil público siempre es accesible desde el dashboard

---

Arquitectura

lib/features/home/
├── application/
│   ├── dashboard_cubit.dart       # Carga dashboard + validation status
│   └── dashboard_state.dart       # DashboardStatus enum, summary, validationStatus
├── data/
│   ├── datasources/
│   │   └── dashboard_remote_datasource.dart   # GET summary + validation-status
│   ├── models/
│   │   ├── dashboard_summary_model.dart       # fromJson con secciones
│   │   └── validation_status_model.dart       # fromJson con thresholds + progress
│   └── repositories/
│       └── dashboard_repository_impl.dart
├── domain/
│   ├── entities/
│   │   ├── dashboard_summary.dart   # Readiness, Health, Highlights, Sections
│   │   └── validation_status.dart   # Thresholds, MissingRequirements, Progress
│   ├── repositories/
│   │   └── dashboard_repository.dart
│   └── usecases/
│       ├── get_dashboard_summary_usecase.dart
│       └── get_validation_status_usecase.dart
└── presentation/
    ├── pages/
    │   └── home_page.dart           # Shell con bottom nav + drawer
    └── widgets/
        ├── home_content.dart        # Dashboard adaptativo por orgType
        ├── home_app_bar.dart
        ├── bottom_nav_bar.dart
        ├── app_drawer.dart
        └── nav_tabs_config.dart

Endpoints API (sin prefijo /api)

Método	Endpoint	Org Type	Descripción
GET	/companies/dashboard-summary	COMPANY	Resumen ejecutivo con métricas
GET	/companies/validation-status	COMPANY	Estado de activación empresa
GET	/agencies/validation-status	AGENCY	Estado de activación agencia
GET	/recruiters/validation-status	RECRUITER	Estado de activación reclutador

Entidades principales

DashboardSummary

DashboardSummary(readiness, health, highlights, nextActions, sections)
├── DashboardReadiness(organizationName, validationStatus, billingStatus, score, updatedAt)
├── DashboardHealth(key, tone)
├── DashboardHighlight(key, value, unit, tone)
├── DashboardAction(key, tone)
└── DashboardSections(vacancies?, candidates?, disputes?, wallet?)

ValidationStatus

ValidationStatus(thresholds, missingRequirements, registrationProgress?)
├── ValidationThresholds(accountCreated, profileComplete, fiscalValidated, profileEnabled)
├── MissingRequirement(label, severity)
└── RegistrationProgress(totalSteps, completedSteps, percent, currentStep)

Registro DI

• Datasource: LazySingleton
• Repository: LazySingleton
• Use Cases: LazySingleton (GetDashboardSummaryUseCase, GetHomeValidationStatusUseCase)
• Cubit: Factory (nueva instancia por pantalla)

getIt<DashboardCubit>()

Localización

✅ Completa — todos los strings usan context.l10n.homeXxx. Claves con prefijo home en ambos ARB files (es + en). Keys parametrizados con ICU: homeUpdatedAt, homeActivationProgress, homeMissingRequirements.