mirror of
https://github.com/marcogll/hr_soul23.git
synced 2026-01-13 13:25:16 +00:00
b110f5891c
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.
150 lines
3.9 KiB
Markdown
150 lines
3.9 KiB
Markdown
# 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.
|