Merge pull request #3 from marcogll/test-17334063531150954188

Test 17334063531150954188

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.

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]
+*   **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:** [Qué se decidió o qué acción se tomó]
+*   **Decisión/Acción:** Se creó el documento `docs/API_CONTRACTS.md`.
-*   **Justificación:** [Por qué se tomó esa decisión]
+*   **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:** [Sistemas o agentes afectados]
+*   **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.
 
 ---