Merge branch 'feat/backend-core-setup-17551761085875550719' into main

2026-01-13 13:25:16 +00:00 · 2025-12-13 16:12:04 -06:00
parent cacfd1e4eb 7db61d9af9
commit bcded88373
18 changed files with 2438 additions and 306 deletions
--- a/docs/API_CONTRACTS.md
+++ b/docs/API_CONTRACTS.md
@@ -1,149 +1,122 @@
-# Contratos de API y Modelos de Datos – HR Platform
+# API & Data Contracts

-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).
+Este documento es la **única fuente de verdad** para los modelos de datos y las APIs del sistema. Todos los agentes (backend, frontend, testing) deben adherirse a estos contratos.

 ---

-## 1. Modelos de Datos Principales
+## Modelos de Datos (Tablas)

-### 1.1 Socia (`Employee`)
+### `socias`

-Representa a un miembro del personal.
+Almacena la información de las empleadas.

-```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"
-}
-```
+| Columna | Tipo | Descripción |
+|---|---|---|
+| `id` | `INTEGER` | PK, Auto-increment |
+| `nombre` | `VARCHAR(255)` | Nombre de la socia |
+| `apellido` | `VARCHAR(255)` | Apellido de la socia |
+| `fecha_ingreso`| `DATE` | Fecha de ingreso a la empresa |
+| `id_sucursal` | `INTEGER` | FK a `sucursales.id` |
+| `activo` | `BOOLEAN` | `true` si está activa, `false` si no |
+| `created_at` | `TIMESTAMP` | Fecha de creación del registro |
+| `updated_at` | `TIMESTAMP` | Fecha de última modificación |

-### 1.2 Vacación (`Vacation`)
+### `sucursales`

-Representa una solicitud de vacaciones.
+Almacena las diferentes sucursales o centros de trabajo.

-```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"
-}
-```
+| Columna | Tipo | Descripción |
+|---|---|---|
+| `id` | `INTEGER` | PK, Auto-increment |
+| `nombre` | `VARCHAR(255)` | Nombre de la sucursal |
+| `direccion` | `TEXT` | Dirección física de la sucursal |
+| `created_at` | `TIMESTAMP` | Fecha de creación del registro |
+| `updated_at` | `TIMESTAMP` | Fecha de última modificación |

-### 1.3 Permiso (`Permission`)
+### `vacaciones`

-Representa una solicitud de permiso (ausencia no vacacional).
+Registra las solicitudes y periodos de vacaciones.

-```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"
-}
-```
+| Columna | Tipo | Descripción |
+|---|---|---|
+| `id` | `INTEGER` | PK, Auto-increment |
+| `id_socia` | `INTEGER` | FK a `socias.id` |
+| `fecha_inicio` | `DATE` | Inicio del periodo vacacional |
+| `fecha_fin` | `DATE` | Fin del periodo vacacional |
+| `dias_tomados` | `INTEGER` | Cantidad de días hábiles |
+| `estado` | `VARCHAR(50)` | `solicitada`, `aprobada`, `rechazada` |
+| `ciclo_anual` | `VARCHAR(10)`| Ciclo al que corresponden, ej: "2023-2024" |
+| `created_at` | `TIMESTAMP` | Fecha de creación del registro |
+| `updated_at` | `TIMESTAMP` | Fecha de última modificación |

-### 1.4 Sucursal (`Branch`)
+### `permisos`

-Representa una ubicación física.
+Registra ausencias justificadas que no son vacaciones.

-```json
-{
-  "id": "b-f2e1d0c9",
-  "name": "Sucursal Centro",
-  "address": "Av. Principal 123, Ciudad"
-}
-```
+| Columna | Tipo | Descripción |
+|---|---|---|
+| `id` | `INTEGER` | PK, Auto-increment |
+| `id_socia` | `INTEGER` | FK a `socias.id` |
+| `fecha` | `DATE` | Fecha del permiso |
+| `horas` | `INTEGER` | `NULL` si es por día completo |
+| `dias` | `INTEGER` | `NULL` si es por horas |
+| `motivo` | `TEXT` | Razón del permiso |
+| `estado` | `VARCHAR(50)` | `solicitado`, `aprobado`, `rechazado` |
+| `created_at` | `TIMESTAMP` | Fecha de creación del registro |
+| `updated_at` | `TIMESTAMP` | Fecha de última modificación |

-### 1.5 Usuario (`User`)
+### `eventos`

-Representa un usuario del sistema con permisos.
+Log de eventos para webhooks.

-```json
-{
-  "id": "u-d9e8f7g6",
-  "username": "admin_juan",
-  "role": "ADMIN", // ROOT, ADMIN, USER
-  "permissions": [
-    "socias.read",
-    "vacaciones.approve",
-    "permisos.read"
-  ]
-}
-```
+| Columna | Tipo | Descripción |
+|---|---|---|
+| `id` | `INTEGER` | PK, Auto-increment |
+| `tipo_evento` | `VARCHAR(100)`| Ej: `vacaciones.solicitada` |
+| `payload` | `JSON` | Datos del evento |
+| `endpoint_url` | `VARCHAR(255)`| URL a la que se envió el webhook |
+| `estado_entrega`| `VARCHAR(50)` | `pendiente`, `enviado`, `fallido` |
+| `created_at` | `TIMESTAMP` | Fecha de creación del registro |
+
+### `configuraciones`
+
+Almacena configuraciones clave-valor para el sistema.
+
+| Columna | Tipo | Descripción |
+|---|---|---|
+| `id` | `INTEGER` | PK, Auto-increment |
+| `clave` | `VARCHAR(100)`| Clave única de configuración |
+| `valor` | `TEXT` | Valor de la configuración |
+| `descripcion` | `TEXT` | Para qué sirve la configuración |
+| `created_at` | `TIMESTAMP` | Fecha de creación del registro |
+| `updated_at` | `TIMESTAMP` | Fecha de última modificación |
+
+### `usuarios`
+
+Usuarios que pueden acceder al sistema.
+
+| Columna | Tipo | Descripción |
+|---|---|---|
+| `id` | `INTEGER` | PK, Auto-increment |
+| `nombre` | `VARCHAR(255)` | Nombre del usuario |
+| `email` | `VARCHAR(255)`| Email único para login |
+| `password_hash`| `VARCHAR(255)`| Hash de la contraseña |
+| `rol` | `VARCHAR(50)` | `root`, `admin`, `user` |
+| `created_at` | `TIMESTAMP` | Fecha de creación del registro |
+| `updated_at` | `TIMESTAMP` | Fecha de última modificación |
+
+### `permisos_granulares`
+
+Define permisos específicos por usuario y recurso.
+
+| Columna | Tipo | Descripción |
+|---|---|---|
+| `id` | `INTEGER` | PK, Auto-increment |
+| `id_usuario` | `INTEGER` | FK a `usuarios.id` |
+| `recurso` | `VARCHAR(100)`| Ej: `socias`, `vacaciones` |
+| `accion` | `VARCHAR(50)` | `crear`, `leer`, `actualizar`, `eliminar` |
+| `permitido` | `BOOLEAN` | `true` si tiene el permiso |
+| `created_at` | `TIMESTAMP` | Fecha de creación del registro |
+| `updated_at` | `TIMESTAMP` | Fecha de última modificación |

 ---
-
-## 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.
--- a/docs/agents/agent-00-architecture.md
+++ b/docs/agents/agent-00-architecture.md
@@ -8,21 +8,11 @@ Su propósito es mantener un historial claro y auditable de las directrices arqu

 ## Entradas de Bitácora

-### 2024-07-29 - Definición de Contratos de API y Datos
+### [Fecha] - Decisión/Observación

-*   **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.
+*   **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]

 ---
--- a/docs/agents/agent-01-infraestructura.md
+++ b/docs/agents/agent-01-infraestructura.md
@@ -1,19 +1,18 @@
 # Bitácora del Agente 1 – Infraestructura & DevOps

-## Fecha: 2023-10-27
+Este documento registra las decisiones, cambios y observaciones del **Agente 1**.

-### Cambios Realizados
+Su propósito es mantener un historial claro y auditable de las tareas y soluciones implementadas.

-*   **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`.
+---

-*   **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.
+## Entradas de Bitácora

-*   **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.
+### [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]
+
+---
--- a/docs/agents/agent-03-base.md
+++ b/docs/agents/agent-03-base.md
@@ -10,14 +10,14 @@ Su propósito es mantener un historial claro y auditable de las tareas y solucio

 ### 2024-07-29 - Creación del Sistema de Migraciones y Esquema Inicial

-*   **Contexto:** La tarea principal del Agente 3 es establecer la base de datos como la "fuente única de verdad". Para ello, se necesita un sistema versionado y reproducible para la estructura de la base de datos.
+*   **Contexto:** Se necesitaba una base de datos y un modelo de datos para poder continuar con el desarrollo de la aplicación.
 *   **Acción/Implementación:**
-    1.  Se inicializó un proyecto Node.js con `npm init`.
-    2.  Se instalaron las dependencias `knex` y `pg`.
-    3.  Se creó el archivo de configuración `knexfile.js` para definir la conexión a la base de datos.
-    4.  Se generó la primera migración (`..._initial_schema.js`) utilizando el CLI de `knex`.
-    5.  Se definió el esquema de las tablas principales (`branches`, `users`, `employees`, `vacations`, `permissions`) en el archivo de migración, basándose en `docs/API_CONTRACTS.md`.
-*   **Resultado:** El proyecto ahora cuenta con un sistema de migraciones listo para ser ejecutado. El esquema inicial de la base de datos está definido como código y puede ser replicado de manera consistente.
-*   **Observaciones:** Se añadió un archivo `.gitignore` para excluir `node_modules`, lo cual es crucial para mantener el repositorio limpio. La conexión en `knexfile.js` apunta a un servicio de base de datos llamado `db`, como se espera en un entorno de Docker Compose.
+    * Se ha definido un contrato de datos en `docs/API_CONTRACTS.md` que servirá como única fuente de verdad para los modelos de datos.
+    * Se ha seleccionado `knex.js` con `sqlite3` como sistema de base de datos para el desarrollo inicial.
+    * Se ha configurado la conexión a la base de datos y un sistema de migraciones.
+    * Se han creado las migraciones iniciales para todas las tablas requeridas.
+    * Se han creado seeds para poblar la base de datos con datos de prueba.
+*   **Resultado:** La base de datos está lista y poblada con datos iniciales. El esquema está versionado a través de migraciones.
+*   **Observaciones:** El uso de `sqlite3` es temporal para facilitar el desarrollo. Se deberá migrar a una base de datos más robusta como PostgreSQL para producción.

 ---