From b110f5891cdeec487b26656cb84285f1ead05202 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sat, 13 Dec 2025 21:24:01 +0000 Subject: [PATCH] docs: Definir contratos de API y modelos de datos MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Crea el documento `docs/API_CONTRACTS.md` para establecer una fuente única de verdad para las estructuras de datos y los endpoints de la API REST. - Define los modelos de datos principales: Socia (Employee), Vacación (Vacation), Permiso (Permission), Sucursal (Branch) y Usuario (User). - Esboza los endpoints RESTful iniciales para el chequeo de salud y la gestión de socias y vacaciones. - Actualiza la bitácora del Agente 0 para registrar esta decisión arquitectónica. Este documento es fundamental para guiar el trabajo de los agentes de Backend, Frontend y Testing, permitiendo un desarrollo desacoplado y coherente. --- docs/API_CONTRACTS.md | 149 +++++++++++++++++++++++++++ docs/agents/agent-00-architecture.md | 20 +++- 2 files changed, 164 insertions(+), 5 deletions(-) create mode 100644 docs/API_CONTRACTS.md 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. ---