hr_soul23/docs/API_CONTRACTS.md

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.

{
  "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.

{
  "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).

{
  "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.

{
  "id": "b-f2e1d0c9",
  "name": "Sucursal Centro",
  "address": "Av. Principal 123, Ciudad"
}

1.5 Usuario (User)

Representa un usuario del sistema con permisos.

{
  "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):

  {
    "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.