La documentación técnica representa todos los principios, prácticas y reglas que están representadas en el proyecto. Además muestra el correcto uso y continuo desarrollo para los developers.
Esta sección define los lineamientos obligatorios para la escritura, organización y entrega del código del proyecto challenge de Puul. El cumplimiento de estos estándares garantiza legibilidad, rastreabilidad y trabajo eficiente en equipo.
El proyecto sigue el flujo GitFlow, que separa el trabajo por ambientes y propósitos. Esto asegura escalabilidad a cualquier proyecto para una colaboración en equipo. La siguiente tabla define cada tipo de rama y su uso:
| Rama | Propósito | Ejemplo |
|---|---|---|
| main | Código productivo y estable. Solo recibe merges desde release o hotfix. | main |
| develop | Rama de integración continua. Todas las features se fusionan aquí antes de ir a producción. | develop |
| feature/ | Nuevas funcionalidades. Se crea desde develop y se fusiona de regreso a develop. | feature/task-management, feature/user-analytics |
| fix/ | Corrección de errores detectados en develop o main. | fix/db-connection-issue, fix/filter-query-bug |
| refactor/ | Mejoras internas sin cambio de comportamiento externo. | refactor/dto-validation, refactor/analytics-query |
Todos los commits deben seguir el estándar Conventional Commits para mantener un historial limpio y generar changelogs automáticos:
| Prefijo | Cuándo usarlo | Ejemplo |
|---|---|---|
| feat: | Se añade una nueva característica o endpoint al sistema. | feat: se agrega endpoint analytics |
| fix: | Se corrige un bug o comportamiento incorrecto. | fix: corrección de due_date filter query |
| docs: | Cambios exclusivamente en archivos de documentación. | docs: se actualiza README con variables de entorno |
| style: | Cambios de formato que no afectan la lógica (espacios, comas). | style: se modicica formato del servicio analytics |
| refactor: | Reestructuración (mejoras) del código sin cambiar su comportamiento. | refactor: se mejora código de servicio task |
| test: | Se agregan o corrigen pruebas unitarias o de integración | test: se crea unit test para la creación de usuarios |
La consistencia en la nomenclatura reduce la curva de aprendizaje del equipo y previene errores. Los estándares adoptados son:
| Contexto | Convención | Ejemplo |
|---|---|---|
| Variables y funciones | camelCase | taskEstimatedHours, findAllUsers() |
| Clases, Entidades y DTOs | PascalCase | CreateTaskDto, TaskOrm, UsersService |
| Archivos TypeScript | kebab-case.type.ts | create-user.dto.ts, tasks.service.ts |
| Tablas en base de datos | snake_case plural | users, tasks, task_assignments |
| Columnas de tabla | snake_case | estimated_hours, due_date, created_at |
| Módulos NestJS | PascalCase + Module | UsersModule, TasksModule, AnalyticsModule |
| Enumeraciones (Enum) | UPPER_SNAKE_CASE para valores | TaskStatus.ACTIVE, UserRole.ADMIN |
El backend está construido con NestJS + TypeScript sobre Node.js, usando TypeORM como ORM y PostgreSQL como base de datos.
Users Module (Gestión de Usuarios)
Responsable de toda la lógica relacionada con la identidad dentro del sistema. Gestiona quién puede acceder y cuál es su rol.