> ## Documentation Index
> Fetch the complete documentation index at: https://blog.mapptech.com.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Calidad y Convenciones

> Convenciones de nomenclatura obligatorias y la checklist del desarrollador para asegurar la calidad del código y la adherencia a los estándares arquitectónicos.

## Convenciones de Nomenclatura

Se requiere una adherencia estricta a estas convenciones de nomenclatura para la consistencia y predictibilidad del código en todo el monorepo.

| Tipo de Artefacto      | Convención Sufijo/Prefijo  | Ejemplo                      | Ejemplo de Ubicación Estándar                                       |
| ---------------------- | -------------------------- | ---------------------------- | ------------------------------------------------------------------- |
| Yup Schema             | Sufijo `Schema`            | `userSchema`                 | `packages/core/validation/userSchema.ts`                            |
| Tipo de Schema (Input) | Sufijo `Input`             | `CreateUserInput`            | `packages/core/validation/userSchema.ts`                            |
| Tipo de Entidad Base   | Sustantivo (Singular)      | `User`                       | `packages/core/types/entities/User.ts`                              |
| Máquina XState         | Sufijo `Machine`           | `userCreationMachine`        | `packages/core/machines/userCreationMachine.ts`                     |
| Tipo Context Máquina   | Sufijo `MachineContext`    | `UserCreationMachineContext` | `packages/core/types/machines/user/UserCreationMachineTypes.ts`     |
| Tipo Evento Máquina    | Sufijo `MachineEvent`      | `UserCreationMachineEvent`   | `packages/core/types/machines/user/UserCreationMachineTypes.ts`     |
| Interfaz de Servicio   | Sufijo `Service`           | `UserService`                | `packages/core/services/user/domain/UserService.ts`                 |
| Clase Impl Servicio    | Sufijo `[ImplName]Service` | `DefaultUserService`         | `packages/core/services/user/implementations/DefaultUserService.ts` |
| DTOs Método Servicio   | `[MethodName]Input/Output` | `CreateUserMethodInput`      | `packages/core/services/user/domain/UserTypes.ts`                   |
| Server Action          | Sufijo `Action`            | `createUserAction`           | `packages/core/actions/userActions.ts`                              |
| Comp. Contenedor       | Sufijo `Container`         | `UserFormContainer.tsx`      | `apps/[appName]/app/.../containers/`                                |
| Comp. de Página        | Nombre exacto `page.tsx`   | `page.tsx`                   | `apps/[appName]/app/.../[pageName]/page.tsx`                        |

***

## Checklist del Desarrollador

Antes de enviar un Pull Request para revisión, los desarrolladores **deben** verificar lo siguiente:

* [ ] **Validación de Entrada:** ¿Se validan los datos de entrada usando un esquema Yup compartido (`@core/validation`) dentro de la Server Action *antes* de iniciar la máquina? (Ver [Guía de Backend](./standards-backend))
* [ ] **Lógica de Action:** ¿La Server Action instancia la máquina XState correcta (`@core/machines`), pasa la entrada validada y el servicio resuelto al contexto, envía el evento inicial y espera su finalización? (Ver [Flujo de Trabajo Central](./standards-workflow))
* [ ] **Orquestación de Máquina:** ¿La máquina XState orquesta el flujo de la lógica de negocio?
* [ ] **Mapeo DTO Máquina-Servicio:** ¿La máquina XState **construye correctamente el DTO de Entrada del Servicio** antes de llamar al método del servicio? ¿**Procesa correctamente el DTO de Salida del Servicio** y actualiza su contexto? (Ver [Flujo de Trabajo Central](./standards-workflow) y [Guía de Backend](./standards-backend))
* [ ] **Invocación de Servicio:** ¿La máquina XState invoca métodos en las implementaciones de Servicio apropiadas (`@core/services/[domain]/implementations/`) obtenidas a través del contexto?
* [ ] **Resolución de Servicio:** ¿Se resuelve la implementación de servicio correcta (vía Factory/Locator) y se pone a disposición de la máquina (ej., vía contexto)? (Ver [Guía de Backend](./standards-backend))
* [ ] **Modelado de Estado:** ¿Están los flujos de trabajo complejos con estado modelados correctamente dentro de la máquina XState (`Patrón State`)?
* [ ] **Lógica de Servicio:** ¿Están las operaciones de negocio discretas implementadas dentro de las clases de Servicio (`Patrón Strategy`)?
* [ ] **Contratos de Servicio:** ¿Están definidas las Interfaces de Servicio en `@core/services/[domain]/domain/[Domain]Service.ts`? ¿Están definidos los **DTOs de Entrada/Salida específicos del Método de Servicio** en `@core/services/[domain]/domain/[Domain]Types.ts` y desacoplados de los tipos de validación/entidad? (Ver [Guía de Backend](./standards-backend))
* [ ] **Tipado:** ¿Están definidos los tipos de Contexto/Evento de la máquina XState en `@core/types/machines/[domain]/`? ¿Están definidos los tipos de entidad base en `@core/types/entities/`? (Ver [Guía de Backend](./standards-backend))
* [ ] **Librería UI:** ¿Se utilizan correctamente los elementos UI de `mappnext/ds-tw`? (Ver [Guía de Desarrollo Frontend](./standards-frontend))
* [ ] **Estructura Frontend:** ¿Están los componentes presentacionales (`components/`) claramente separados de la lógica del contenedor (`page.tsx` o `containers/`) (`Patrón Container/Presentational`)? ¿Es apropiada la estructura frontend elegida para la complejidad? (Ver [Guía de Desarrollo Frontend](./standards-frontend))
* [ ] **Reutilización de Código:** ¿Se han revisado los paquetes compartidos (`@core`, `@hooks`, `@config`) antes de escribir código nuevo? (Ver [Visión General](./standards-overview))
* [ ] **Build:** ¿El proyecto se construye correctamente (`pnpm build`)?
* [ ] **Documentación:** ¿Están actualizados los documentos/comentarios donde sea necesario (explicando el 'por qué' complejo, no el 'qué')?
* [ ] **Commits:** ¿Siguen todos los commits el formato de [Conventional Commits](./standards-git#git-commit-convention-standard)?

<Warning>
  Los Pull Requests que fallen estas verificaciones pueden ser rechazados. Presta especial atención al flujo correcto Action -> Machine -> Service (incluyendo el mapeo de DTO en la máquina), el cumplimiento del mensaje de commit, el uso de la librería UI, la adherencia a los patrones arquitectónicos y la separación de responsabilidades.
</Warning>