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) - 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) - 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 y Guía de 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)
- 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.tsy desacoplados de los tipos de validación/entidad? (Ver Guía de 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) - Librería UI: ¿Se utilizan correctamente los elementos UI de
mappnext/ds-tw? (Ver Guía de Desarrollo Frontend) - Estructura Frontend: ¿Están los componentes presentacionales (
components/) claramente separados de la lógica del contenedor (page.tsxocontainers/) (Patrón Container/Presentational)? ¿Es apropiada la estructura frontend elegida para la complejidad? (Ver Guía de Desarrollo 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) - 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?