diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..d802c4a --- /dev/null +++ b/.env.example @@ -0,0 +1,9 @@ +# Application configuration +NODE_ENV=development + +# Database configuration +DB_HOST=db +DB_USER=postgres +DB_PASSWORD=secret +DB_NAME=hr_platform +DB_PORT=5432 diff --git a/.gitignore b/.gitignore index 3c3629e..c85fe15 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,74 @@ -node_modules +# Dependencies +/node_modules + +# Logs +logs +*.log +npm-debug.log* +yarn-debug.log* +yarn-error.log* + +# Runtime data +pids +*.pid +*.seed +*.pid.lock + +# Directory for instrumented libs generated by jscoverage/JSCover +lib-cov + +# Coverage directory used by tools like istanbul +coverage + +# nyc test coverage +.nyc_output + +# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-temporary-files) +.grunt + +# Bower dependency directory (https://bower.io/) +bower_components + +# node-waf configuration +.lock-wscript + +# Compiled binary addons (http://nodejs.org/api/addons.html) +build/Release + +# Dependency directories +jspm_packages/ + +# TypeScript v1 declaration files +typings/ + +# Optional npm cache directory +.npm + +# Optional eslint cache +.eslintcache + +# Microbundle cache +.rpt2_cache/ +.rts2_cache_cjs/ +.rts2_cache_es/ +.rts2_cache_umd/ + +# Optional REPL history +.node_repl_history + +# Output of 'npm pack' +*.tgz + +# Yarn Integrity file +.yarn-integrity + +# dotenv environment variables file +.env +.env.test +.env.production + +# Mac files +.DS_Store + +# VSCode files +.vscode/ diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..3c7d009 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,21 @@ +# Usar una imagen base oficial de Node.js +ARG NODE_VERSION=18 +FROM node:${NODE_VERSION}-alpine + +# Establecer el directorio de trabajo en el contenedor +WORKDIR /usr/src/app + +# Copiar package.json y package-lock.json (si existe) +COPY package*.json ./ + +# Instalar las dependencias del proyecto +RUN npm install + +# Copiar el resto del código de la aplicación +COPY . . + +# Exponer el puerto en el que la aplicación se ejecutará +EXPOSE 3011 + +# Comando para iniciar la aplicación +CMD [ "node", "src/index.js" ] diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..757a83a --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,34 @@ +version: '3.8' + +services: + api: + build: . + ports: + - "3011:3011" + volumes: + - .:/usr/src/app + networks: + - app-network + env_file: + - .env + + db: + image: postgres:13 + restart: always + environment: + POSTGRES_USER: ${DB_USER} + POSTGRES_PASSWORD: ${DB_PASSWORD} + POSTGRES_DB: ${DB_NAME} + ports: + - "5432:5432" + volumes: + - postgres-data:/var/lib/postgresql/data + networks: + - app-network + +networks: + app-network: + driver: bridge + +volumes: + postgres-data: diff --git a/docs/API_CONTRACTS.md b/docs/API_CONTRACTS.md new file mode 100644 index 0000000..c4660db --- /dev/null +++ b/docs/API_CONTRACTS.md @@ -0,0 +1,149 @@ +# Contratos de API y Modelos de Datos – HR Platform + +Este documento define los **contratos formales** para la API REST y las estructuras de datos del sistema. Sirve como la **fuente única de verdad** para los agentes de Backend (Agente 2), Frontend (Agente 10) y Testing (Agente 11). + +Cualquier desviación de este contrato debe ser discutida y aprobada por el Agente 0 (Arquitectura). + +--- + +## 1. Modelos de Datos Principales + +### 1.1 Socia (`Employee`) + +Representa a un miembro del personal. + +```json +{ + "id": "s-a8b7c6d5", + "firstName": "Ana", + "lastName": "García", + "email": "ana.garcia@example.com", + "hireDate": "2023-01-15T10:00:00Z", + "branchId": "b-f2e1d0c9", + "isActive": true, + "createdAt": "2023-01-10T09:00:00Z", + "updatedAt": "2023-01-10T09:00:00Z" +} +``` + +### 1.2 Vacación (`Vacation`) + +Representa una solicitud de vacaciones. + +```json +{ + "id": "v-1a2b3c4d", + "employeeId": "s-a8b7c6d5", + "startDate": "2024-08-01", + "endDate": "2024-08-05", + "daysUsed": 5, + "status": "APPROVED", // PENDING, APPROVED, REJECTED + "cycleYear": 2024, + "requestedAt": "2024-06-10T11:00:00Z", + "approvedBy": "u-d9e8f7g6", + "approvedAt": "2024-06-11T15:30:00Z" +} +``` + +### 1.3 Permiso (`Permission`) + +Representa una solicitud de permiso (ausencia no vacacional). + +```json +{ + "id": "p-5e6f7g8h", + "employeeId": "s-a8b7c6d5", + "permissionDate": "2024-07-20", + "hours": 4, // 0 si es día completo + "reason": "Cita médica", + "status": "APPROVED", // PENDING, APPROVED, REJECTED + "requestedAt": "2024-07-18T09:00:00Z" +} +``` + +### 1.4 Sucursal (`Branch`) + +Representa una ubicación física. + +```json +{ + "id": "b-f2e1d0c9", + "name": "Sucursal Centro", + "address": "Av. Principal 123, Ciudad" +} +``` + +### 1.5 Usuario (`User`) + +Representa un usuario del sistema con permisos. + +```json +{ + "id": "u-d9e8f7g6", + "username": "admin_juan", + "role": "ADMIN", // ROOT, ADMIN, USER + "permissions": [ + "socias.read", + "vacaciones.approve", + "permisos.read" + ] +} +``` + +--- + +## 2. Contratos de API (Endpoints) + +Todos los endpoints siguen el prefijo `/api/v1`. + +### 2.1 Health Check + +* **Endpoint:** `GET /health` +* **Descripción:** Verifica el estado del servicio. +* **Respuesta Exitosa (200 OK):** + ```json + { + "status": "ok", + "timestamp": "2024-01-01T12:00:00Z" + } + ``` + +### 2.2 Gestión de Socias (`/employees`) + +* **`GET /employees`** + * **Descripción:** Obtiene una lista de todas las socias. + * **Respuesta:** `200 OK` con un array de objetos `Socia`. + +* **`GET /employees/{id}`** + * **Descripción:** Obtiene una socia por su ID. + * **Respuesta:** `200 OK` con un objeto `Socia`. + +* **`POST /employees`** + * **Descripción:** Crea una nueva socia. + * **Request Body:** Objeto `Socia` (sin `id`, `createdAt`, `updatedAt`). + * **Respuesta:** `201 Created` con el objeto `Socia` completo. + +* **`PUT /employees/{id}`** + * **Descripción:** Actualiza una socia existente. + * **Request Body:** Objeto `Socia` con los campos a actualizar. + * **Respuesta:** `200 OK` con el objeto `Socia` actualizado. + +### 2.3 Gestión de Vacaciones (`/vacations`) + +* **`GET /employees/{employeeId}/vacations`** + * **Descripción:** Obtiene el historial de vacaciones de una socia. + * **Respuesta:** `200 OK` con un array de objetos `Vacacion`. + +* **`POST /employees/{employeeId}/vacations`** + * **Descripción:** Solicita nuevas vacaciones para una socia. + * **Request Body:** `{ "startDate": "YYYY-MM-DD", "endDate": "YYYY-MM-DD" }` + * **Respuesta:** `201 Created` con el objeto `Vacacion` creado. + +* **`PUT /vacations/{vacationId}/status`** + * **Descripción:** Aprueba o rechaza una solicitud de vacaciones (solo Admins). + * **Request Body:** `{ "status": "APPROVED" }` + * **Respuesta:** `200 OK` con el objeto `Vacacion` actualizado. + +--- + +Este documento evolucionará. Los cambios serán comunicados y registrados por el Agente 0. diff --git a/docs/agents/agent-00-architecture.md b/docs/agents/agent-00-architecture.md index 7e1ead6..3fa33c9 100644 --- a/docs/agents/agent-00-architecture.md +++ b/docs/agents/agent-00-architecture.md @@ -8,11 +8,21 @@ Su propósito es mantener un historial claro y auditable de las directrices arqu ## Entradas de Bitácora -### [Fecha] - Decisión/Observación +### 2024-07-29 - Definición de Contratos de API y Datos -* **Contexto:** [Descripción del problema o situación] -* **Decisión/Acción:** [Qué se decidió o qué acción se tomó] -* **Justificación:** [Por qué se tomó esa decisión] -* **Impacto:** [Sistemas o agentes afectados] +* **Contexto:** Para asegurar un desarrollo coherente y desacoplado entre los agentes de backend, frontend y testing, era necesario establecer una fuente única de verdad para las estructuras de datos y las interfaces de la API. +* **Decisión/Acción:** Se creó el documento `docs/API_CONTRACTS.md`. +* **Justificación:** Este documento previene la ambigüedad y reduce la fricción entre agentes. Define los modelos de datos principales (Socia, Vacación, Permiso) y los endpoints RESTful iniciales, permitiendo que el desarrollo en paralelo comience sobre una base sólida y acordada. +* **Impacto:** Afecta principalmente a: + * **Agente 2 (Backend):** Tiene una especificación clara de qué construir. + * **Agente 10 (Frontend):** Sabe qué datos esperar y cómo interactuar con la API. + * **Agente 11 (Testing):** Tiene una referencia para escribir los casos de prueba. + +### 2024-07-29 - Creación de Estructura Inicial + +* **Contexto:** El repositorio inicial carecía de una estructura para guiar el trabajo de los agentes de IA/humanos. +* **Decisión/Acción:** Se creó la estructura de directorios (`src`, `docs/agents`), los archivos de bitácora para cada agente y el documento de convenciones (`docs/CONVENTIONS.md`). +* **Justificación:** Esta estructura establece un flujo de trabajo claro, promueve la documentación consistente y asegura que todos los agentes operen bajo las mismas reglas. +* **Impacto:** Afecta a todos los agentes. --- diff --git a/docs/agents/agent-01-infraestructura.md b/docs/agents/agent-01-infraestructura.md index 3578677..ceb84ee 100644 --- a/docs/agents/agent-01-infraestructura.md +++ b/docs/agents/agent-01-infraestructura.md @@ -1,18 +1,19 @@ # Bitácora del Agente 1 – Infraestructura & DevOps -Este documento registra las decisiones, cambios y observaciones del **Agente 1**. +## Fecha: 2023-10-27 -Su propósito es mantener un historial claro y auditable de las tareas y soluciones implementadas. +### Cambios Realizados ---- +* **Creación de `Dockerfile`:** + * Se ha añadido un `Dockerfile` para construir la imagen del servicio de Node.js. + * La imagen se basa in `node:18-alpine` para mantenerla ligera. + * Se exponen el puerto 3011 y se define el comando de inicio `node src/index.js`. -## Entradas de Bitácora +* **Creación de `docker-compose.yml`:** + * Se ha creado un archivo `docker-compose.yml` para orquestar los servicios de la aplicación. + * Define dos servicios: `api` (el backend de Node.js) y `db` (una base de datos PostgreSQL). + * Configura una red `app-network` para la comunicación entre servicios. + * Se define un volumen `postgres-data` para la persistencia de los datos de la base de datos. -### [Fecha] - Tarea/Decisión - -* **Contexto:** [Descripción del requerimiento o problema] -* **Acción/Implementación:** [Qué se hizo o cómo se implementó] -* **Resultado:** [Cuál fue el resultado, ej. endpoint creado, test pasado] -* **Observaciones:** [Notas adicionales, dependencias, problemas encontrados] - ---- +* **Creación de `.env.example`:** + * Se ha añadido un archivo `.env.example` con las variables de entorno necesarias para la configuración de la base de datos y la aplicación.