hr_soul23/docs/CONVENTIONS.md

Convenciones del Proyecto – HR Platform

Este documento define las convenciones técnicas y de estilo que deben seguir todos los agentes que contribuyan al proyecto.

Su objetivo es asegurar la consistencia, legibilidad y mantenibilidad del código y la documentación.

---

1. Nomenclatura (Naming Conventions)

1.1 General

• Idioma: Inglés para todo el código (variables, funciones, clases). Español para documentación y comentarios si es necesario aclarar un término de negocio específico de la región.
• Claridad sobre brevedad: calculateAnnualLeave es mejor que calcLev.

1.2 Variables y Funciones

• Estilo: camelCase.
  • Ejemplo: const currentUser = ...;
  • Ejemplo: function calculateSalary(...)

1.3 Clases y Tipos

• Estilo: PascalCase (o UpperCamelCase).
  • Ejemplo: class EmployeeService { ... }
  • Ejemplo: interface UserProfile { ... }

1.4 Constantes

• Estilo: UPPER_CASE con guiones bajos.
  • Ejemplo: const MAX_LOGIN_ATTEMPTS = 5;

1.5 Archivos

• Componentes/Módulos: PascalCase.js (ej. EmployeeCard.js)
• Servicios/Rutas/Config: kebab-case.js (ej. user-routes.js, database-config.js)

---

2. Estilo de Código (Code Style)

2.1 JavaScript/Node.js

• Formateador: Prettier con la configuración por defecto.
• Linter: ESLint con un conjunto de reglas estándar (ej. eslint:recommended).
• Módulos: Usar import/export (ES Modules) en lugar de require/module.exports (CommonJS) siempre que sea posible.
• Punto y coma: Obligatorio.

2.2 Comentarios

• Cuándo: Comentar lógica de negocio compleja, no código obvio.
• Cómo: Usar JSDoc para funciones y módulos para describir propósito, parámetros y valores de retorno.

---

3. Contratos de API (API Contracts)

3.1 Endpoints

• Formato: RESTful. Usar sustantivos en plural para las colecciones.
  • GET /api/v1/employees (Obtener todos los empleados)
  • GET /api/v1/employees/{id} (Obtener un empleado)
  • POST /api/v1/employees (Crear un empleado)
  • PUT /api/v1/employees/{id} (Actualizar un empleado)
  • DELETE /api/v1/employees/{id} (Eliminar un empleado)

3.2 Versionado

• Incluir el número de versión en la URL: /api/v1/...

3.3 Payloads (Request/Response)

• Formato: JSON.
• Estilo de claves: camelCase.
• Respuestas de error: Usar una estructura consistente.

  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "El campo 'email' es inválido.",
      "details": [
        { "field": "email", "issue": "Formato incorrecto" }
      ]
    }
  }
  

---

4. Commits en Git

4.1 Mensajes de Commit

• Formato: Conventional Commits.
  • feat: Implementar login de usuarios
  • fix: Corregir cálculo de vacaciones en años bisiestos
  • docs: Actualizar README con instrucciones de despliegue
  • style: Formatear código con Prettier
  • refactor: Mover lógica de negocio a capa de servicio
  • test: Añadir pruebas unitarias para el módulo de permisos
  • chore: Actualizar dependencias de npm

4.2 Ramas

• main: Rama principal, representa el estado de producción.
• develop: Rama de integración para el trabajo en curso.
• test: Rama de pruebas.
• Ramas de feature: feature/nombre-corto-del-feature (ej. feature/user-auth)
• Ramas de bugfix: fix/descripcion-corta-del-bug (ej. fix/login-error)

---

5. Documentación

• Bitácoras de Agente: Cada agente debe registrar sus decisiones y progreso en su archivo correspondiente en docs/agents/.
• READMEs: Cualquier nuevo módulo complejo debe tener su propio README.md explicando su propósito y uso.

---

Este documento es una guía viva y puede ser actualizado por el Agente 0 (Arquitectura) según las necesidades del proyecto.