# Performance

Módulo de evaluaciones de desempeño: listado de ciclos, completado de reviews (own / leader / peer / external), selección de pares, share de resultados al evaluado y calibración para gerentes superiores.

---

## Pantallas y flujos

| Pantalla / flujo | Descripción | Entrada | Ruta |
|---|---|---|---|
| Cycles List (home) | Listado paginado de ciclos de performance del usuario con búsqueda y acciones contextuales por ciclo | `CyclesList/index.tsx` | `/performance` |
| Performance Review | Detalle de un ciclo: completar reviews, ver progreso del equipo (leader dashboard), share de resultados y my results | `PerformanceReview/index.tsx` | `/performance/:id` |
| Peer Selection | Selección de pares para evaluar dentro de un ciclo | `PerformancePeerSelection/index.tsx` | `/performance/:id/peer` |
| External Reviewer Overlay | Vista para reviewers externos (sin sesión): listado y completado de reviews vía link | `PerformanceExternalReview/index.tsx` | `/performance/:id/external` |
| Calibration Detail | Vista de calibración para gerentes superiores: revisar y rellenar respuestas sobre un evaluado, comparación con subordinate review | `CalibrationDetail/index.tsx` | `/performance/:cycleId/calibration/:formReviewId` |

---

## Forms clave

| Form | Descripción | Path |
|---|---|---|
| `ReviewForm` | Wizard principal de completado de un review (own / leader / peer): tabs por sección (form / goals / competencies), stepper, autosave, modal de confirmación final | `PerformanceReview/components/ReviewForm.tsx` |
| `ExternalReviewForm` | Wizard equivalente para reviewers externos (sin sesión) — usa endpoints `external-reviewers`. Estructurado en subcomponentes (`ReviewedHeader`, `ReviewSectionsNav`, `ReviewFormActions`) + hooks (`useExternalReview` para data layer, `useReviewSteps` para navegación) | `PerformanceExternalReview/components/ExternalReviewForm/` |
| `CalibrationForm` | Wizard de calibración: rellenar respuestas con steps, schema Zod, comparación con subordinados | `CalibrationDetail/CalibrationForm/` |
| `Summary` (editor) | Edición y share del resumen final del review al evaluado | `PerformanceReview/components/Summary/` |
| `PeerSelectComponent` | Autocomplete + alta de external reviewers + selección de pares por dirección | `PerformancePeerSelection/components/PeerSelectComponent/` |

---

## Componentes y hooks clave

| Nombre | Descripción | Ubicación |
|---|---|---|
| `PerformanceReviewContext` | Context React con `selectedReview`, `reviews`, `nextReview`, `setUserToShareId`, `setMenuSelected`, etc. Provee state global del flujo de review | `PerformanceReviewContext.tsx` |
| `usePerformanceCyclesList` | Lógica del home: paginación server-side, búsqueda con debounce, acciones por ciclo | `CyclesList/hooks/usePerformanceCyclesList.ts` |
| `useLeaderDashboard` | Datos y filtros del dashboard de equipo dentro de PerformanceReview (stat cards, progreso, listado de colaboradores) | `PerformanceReview/hooks/useLeaderDashboard.ts` |
| `useCalibrationDetail` | Carga el detalle de calibración y orquesta navegación entre formReviews | `CalibrationDetail/hooks/useCalibrationDetail.ts` |
| `useCalibrationsSidebar` | Paginación + búsqueda del sidebar de calibraciones | `CalibrationDetail/hooks/useCalibrationsSidebar.ts` |
| `useFillCalibration` | Mutación para enviar respuestas de calibración | `CalibrationDetail/hooks/useFillCalibration.ts` |
| `useCalibrationFormSteps` | Construcción de steps del wizard de calibración a partir del cuestionario | `CalibrationDetail/CalibrationForm/hooks/useCalibrationFormSteps.ts` |
| `useCalibrationComparison` | Lógica del drawer de comparación con respuestas de subordinados | `CalibrationDetail/CalibrationForm/hooks/useCalibrationComparison.ts` |
| `useCurrentStepValidation` | Validación reactiva del paso actual de un review/calibration (RHF scoped subscription) | `hooks/useCurrentStepValidation.ts` |
| `useMenuQueryParam` | Sincroniza el menú activo de PerformanceReview con un query param de la URL | `hooks/useMenuQueryParam.ts` |
| `ReviewsMenu` | Menú lateral del flujo de review con grupos por dirección (own / leader / peer / external / others) | `components/ReviewsMenu.tsx` |
| `ReviewInputSection` | Sección genérica del wizard de review/calibration: form / goal / competency questions | `components/ReviewInputSection/` |
| `GetReviewInputComponent` | Dispatcher que renderiza el input correcto según el tipo de pregunta del review | `components/GetReviewInputComponent.tsx` |
| `RichText` | Renderer de contenido rich-text (descripciones de form, etc.); incluye `constants.ts` y `utils.ts` propios | `components/RichText/` |

---

## Archivos compartidos del módulo

| Archivo | Contenido |
|---|---|
| `routes.ts` | URL builders del módulo (`performance`, `review.detail`, `review.peer`, `calibration`) |
| `services.ts` | Llamados a la API de performance-reviews (cycles, reviews, calibrations, external reviewers) |
| `types.ts` | Tipos de dominio: `ReviewCycle`, `ReviewDetail`, `CalibrationReview`, `ReviewDirection`, etc. |
| `queries.ts` | Query keys y helpers de invalidación de React Query |
| `constants.ts` | `PILL_TYPE`, `PerformanceCycleActions`, `REVIEW_DIRECTION_ORDER`, `getReviewBoxMenuItems()` |
| `components/rowConstants.ts` | Constantes de layout/columnas compartidas por listados de reviews y dashboards |
| `utils.ts` | Utilidades de dominio: `groupReviewsByDirection`, `splitReviewInputs`, `createReviewAnswers`, `formatScore`, etc. |
| `PerformanceReviewContext.tsx` | Context compartido entre `PerformanceReview` y `PerformancePeerSelection` |
| `hooks/` | Hooks de scope módulo (`useCurrentStepValidation`, `useMenuQueryParam`) |
| `components/` | Componentes compartidos por 2+ rutas: `ReviewsMenu`, `ReviewInputSection`, `GetReviewInputComponent`, `ReviewNextStepButton`, `PerformanceLoading`, `RichText`, `Calibration/`, `UserList/`, `shared/`, etc. |

---

## Estructura de directorios

```
performance/
├── CyclesList/                     # Home: listado de ciclos
│   ├── components/                 # NoReviews, PerformanceCycleRow
│   └── hooks/                      # usePerformanceCyclesList
├── PerformanceReview/              # Detalle de ciclo (review own / leader / peer / share)
│   ├── components/                 # ReviewForm, ReviewContent, Summary/, score/, leader-dashboard/...
│   └── hooks/                      # useLeaderDashboard
├── PerformancePeerSelection/       # Selección de pares
│   └── components/                 # PeerSelection, PeerSelectComponent/
├── PerformanceExternalReview/      # Overlay para reviewers externos
│   ├── index.tsx                   # Container con loading + ExternalReviewLayout
│   └── components/
│       ├── ExternalReviewLayout.tsx
│       ├── ExternalReview.tsx
│       └── ExternalReviewForm/
│           ├── index.tsx
│           ├── hooks/              # useExternalReview, useReviewSteps
│           └── components/         # ReviewedHeader, ReviewSectionsNav, ReviewFormActions
├── CalibrationDetail/              # Calibración (gerentes superiores)
│   ├── components/                 # CalibrationDetailContent, CalibrationNavigationSidebar, CalibrationComparisonDrawer/
│   ├── CalibrationForm/            # Wizard de calibración con schemas Zod
│   │   ├── hooks/                  # useCalibrationFormSteps, useCalibrationComparison, useCalibrationFormState
│   │   ├── constants.ts, schemas.ts, types.ts, utils.ts
│   │   └── index.tsx
│   └── hooks/                      # useCalibrationDetail, useCalibrationsSidebar, useFillCalibration
├── components/                     # Compartidos entre 2+ rutas
│   ├── Calibration/                # Listado de calibraciones embebido en PerformanceReview
│   ├── ReviewInputSection/, RichText/, Progress/, CompetencyGroup/, Goal/, Inputs/, Shared/
│   ├── TemplateDescription/, UserList/
│   ├── ReviewsMenu, GetReviewInputComponent, ReviewNextStepButton, ReviewEvaluationsList
│   ├── AllReviewsCompleted, NoReviewText, PerformanceLoading
│   └── rowConstants.ts
├── hooks/                          # Hooks de scope módulo
├── routes.ts
├── services.ts
├── types.ts
├── queries.ts
├── constants.ts
├── utils.ts
└── PerformanceReviewContext.tsx
```

---

> Actualizar este README cuando se agreguen pantallas, flujos principales o se reorganicen carpetas.