# PeopleExperience

Módulo para crear y gestionar encuestas de clima laboral (Work Environment Surveys): configuración, participantes, resultados y análisis (eNPS, heatmap, favorabilidad).

---

## Screens / flows

| Screen or flow | Entry path | URL | Description |
|---|---|---|---|
| Surveys list | `Surveys/index.tsx` | `/surveys` | Lista de encuestas con filtros por estado y tipo; acciones de crear, duplicar y eliminar |
| New survey (type picker) | `NewSurvey/index.tsx` | `/surveys/new` | Selector del tipo de encuesta a crear (clásica o workflow) |
| New workflow survey | `NewWorkflowSurvey/index.tsx` | `/surveys/new/workflow` | Creación de encuesta de tipo workflow |
| Classic new survey | `SurveyForm/index.tsx` | `/surveys/new/classic` | Wizard de creación de encuesta clásica |
| Edit survey | `SurveyForm/index.tsx` | `/surveys/:id/edit` | Wizard de edición de encuesta existente |
| Survey dashboard (landing) | `SurveyDashboard/index.tsx` | `/surveys/:id/dashboard` | Vista por defecto del dashboard de una encuesta lanzada |
| Survey config | `SurveyDashboard/SurveyConfig/index.tsx` | `/surveys/:id/dashboard/configuration` | Configuración de encuesta activa. Hijos: `general`, `participation`, `notifications`, `results-view` |
| Survey results | `SurveyDashboard/SurveyResults/index.tsx` | `/surveys/:id/dashboard/results` | Resultados de encuesta activa. Hijos: `participation`, `nps`, `list`, `heatmap` |
| Questions bank | `QuestionsBankList/index.tsx` | `/questions-bank` | Banco de preguntas y dimensiones; gestión de escalas personalizadas |
| Survey templates | `SurveyTemplates/index.tsx` | `/templates` | Lista de plantillas de encuesta gestionadas |
| Survey template detail | `SurveyTemplateDetail/index.tsx` | `/templates/:id` | Detalle de una plantilla; permite crear encuesta a partir de ella |

Todas las URLs están bajo el prefijo del módulo `/people-experience`.

---

## Routing notes

La mayoría de las entradas de `pxRouteConfig` son **rutas hermanas** bajo `/people-experience`. Aunque comparten prefijos de URL (varias empiezan con `/surveys/`), no son rutas anidadas en términos de React Router: en cada URL solo una está montada. A esto lo llamamos **composición de URL**, no anidamiento.

El único anidamiento real (**route nesting** con `<Outlet />`) en este módulo está dentro de `SurveyDashboard`: el layout (`SurveyDashboard/components/SurveyDashboardLayout`) renderiza un `<Outlet />` que monta `SurveyDashboard/index.tsx` (índice), `SurveyConfig` o `SurveyResults`. A su vez, `SurveyConfig` y `SurveyResults` tienen sus propios hijos anidados (`GeneralConfig`, `ParticipationConfig`, etc., y `EnpsResults`, `ListResults`, etc.).

```
/surveys/:id/dashboard            → SurveyDashboardLayout (Outlet)
  index                           → SurveyDashboard
  configuration                   → SurveyConfig (Outlet)
    general | participation | notifications | results-view
  results                         → SurveyResults (Outlet)
    participation | nps | list | heatmap
```

`routes.tsx` es la fuente de verdad de la estructura de rutas.

---

## Key forms

| Form | Path | Description |
|---|---|---|
| General step | `SurveyForm/components/GeneralStep.tsx` | Nombre, descripción y configuración base |
| Questions step | `SurveyForm/components/QuestionsStep/` | Selector de preguntas del banco; orden y configuración por pregunta |
| Participants step | `SurveyForm/components/ParticipantsStep/` | Segmentación de usuarios participantes |
| Data segmentation step | `SurveyForm/components/DataSegmentationStep/` | Configuración de segmentación de datos en resultados |
| Summary step | `SurveyForm/components/SummaryStep/` | Revisión final y publicación |
| General config | `SurveyDashboard/SurveyConfig/GeneralConfig/` | Edición de nombre, anonimidad y método de cálculo de encuesta activa |
| Participation config | `SurveyDashboard/SurveyConfig/ParticipationConfig/` | Gestión de segmentación y datos faltantes |
| Notifications config | `SurveyDashboard/SurveyConfig/NotificationsConfig/` | Envío de recordatorios |
| Results view config | `SurveyDashboard/SurveyConfig/ResultsViewConfig/` | Permiso para que managers vean resultados |
| Question builder form | `QuestionsBankList/forms/QuestionBuilderForm/` | Construcción de preguntas; consumido por `QuestionBuilderDrawer/` en la misma página |
| Question form | `QuestionsBankList/forms/QuestionForm/` | Formulario legado de edición de preguntas del banco |
| Dimension form | `QuestionsBankList/forms/DimensionForm/` | Creación y edición de dimensiones del banco |
| Custom scale drawer | `components/CustomScaleDrawer/` | Creación y edición de escalas personalizadas para preguntas Likert |
| Calc method drawer | `components/CalcMethodDrawer/` | Widget compartido a nivel de módulo, usado por `SurveyForm/SummaryStep` y `SurveyDashboard/SurveyConfig/GeneralConfig` |

---

## Shared assets

| File | Purpose |
|---|---|
| `routes.tsx` | Path helpers (`pxPaths`, `pxRoutes`, `pxLinks`), imports diferidos y `pxRouteConfig` para `src/routes.tsx` |
| `services.ts` | Todas las llamadas HTTP del módulo (encuestas, dimensiones, preguntas, segmentación, analítica) |
| `queries.ts` | Factory de query keys (`pxKeys`) para React Query |
| `types.ts` | Tipos locales del módulo (formularios, filtros de estado). Incluye el enum `PreviewType` compartido entre `SurveyForm/QuestionsStep` y `QuestionsBankList/QuestionBuilderDrawer` |
| `constants.ts` | Constantes del módulo |
| `hooks/` | Hooks compartidos del módulo: `useSurveyDetail`, `useSurveyId` (lector puro de la URL), `useManagerParticipation`, `useMissingInfo`, `useMissingUsers`, `useNewSurveyDetail`, `useNewSurveyId/`, `usePopover` |
| `utils/` | `formatting.ts`, `questionScales.ts`, `questionsUtils.ts` (parse/serialize de preguntas), `rendering.ts`, `encoding.ts`, `index.ts` |
| `components/` | Componentes compartidos del módulo: drawers y widgets (`CalcMethodDrawer/`, `CalcMethodSidebar/`, `CalcMethodUpdateButton.tsx`, `CustomScaleDrawer/`), autocompletes de temas (`TopicAutocomplete.tsx`, `TopicsAutocomplete/`, `TopicsAutocompleteEnhanced.tsx`), tarjetas y chips de diferencias (`DifferenceCard.tsx`, `DifferenceCardLayout.tsx`, `DifferenceChip/`), listas de usuarios con datos faltantes (`MissingDataUserList/`, `MissingDataUsersList/`), y utilitarios de UI (`ConfirmDialog/`, `DataCheckStatus/`, `DisplayGroup/`, `EmptyState.tsx`, `ExoticRadio.tsx`, `FieldContainer.tsx`, `List/`, `ScorePopover.tsx`, `Sidebar/`, `TextOverflowTip.tsx`, `AnonymityThresholdForm.tsx`, `CollapsibleSection.tsx`, `ComparisonCard.tsx`, `CustomPopover.tsx`, `RadioFiltersList.tsx`) |

> **Note:** `src/types/peopleExperience.ts` contiene los tipos principales de la API (compartidos con `EmployeeLifecycle`) y no está dentro de este módulo.

---

> Update this file when screens, forms, or shared assets change significantly.