MLAPP — Consulta de empleados por organización

Estado: Implementado en PHP; pendiente de prueba de integración.
Alcance: API PHP interna (no es una ruta pública que React deba consumir directamente).
Endpoint: GET /organizaciones/{id}/empleados

Objetivo

Obtener los vínculos de personas asociadas a una organización, con nombre, apellido, identificador, puesto y fecha de ingreso. React debe consumir la API Go que Flavio defina; Go es quien consume esta API PHP.

Autenticación y tenant

Requiere JWT válido del backend PHP. El idTenant se obtiene del contexto autenticado y nunca del query string ni del body.

Solo devuelve filas en las que la organización y la persona pertenecen al mismo tenant. Una organización inexistente o ajena al tenant devuelve HTTP 404.

Parámetros

Parámetro	Ubicación	Tipo	Valor por defecto	Descripción
`id`	path	entero positivo	obligatorio	ID de la organización
`page`	query	entero	1	Página solicitada
`limit`	query	entero	50	Registros por página, máximo 100
`incluirInactivos`	query	cadena	`false`	Enviar exactamente `true` para incluir vínculos inactivos

Respuesta HTTP 200 (ejemplo ficticio)

{
  "results": [
    {
      "id": 25,
      "idOrganizacion": 8,
      "idPersona": 14,
      "apellido": "Pérez",
      "nombres": "Juan",
      "identificador": "30111222",
      "puesto": "Operario",
      "fechaIngreso": "2025-03-01",
      "activo": 1
    }
  ],
  "totalItems": 1,
  "page": 1,
  "limit": 50
}

Notas: identificador contiene únicamente el valor del primer identificador ordenado por principal DESC, id ASC y puede ser null; todavía no se devuelve su tipo. puesto y fechaIngreso pueden ser null. Según la configuración PDO/DBAL, activo puede serializarse como entero o booleano; Go debe normalizarlo. Los registros ordenan por apellido, nombres e ID de vínculo.

Errores

400: ID de organización inválido.
401/403: autenticación o contexto tenant no válido, según middleware y capa de seguridad.
404: organización no encontrada dentro del tenant.
500: error inesperado de servidor.

Límites funcionales

Esta ruta es de solo lectura. Altas y modificaciones pertenecen al CRUD de organizaciones_personas y personas.
La desactivación se representa con activo=false; no se recomienda eliminación física desde la interfaz.
La vinculación con una empresa no implica que la persona ya sea paciente.
Una persona puede tener vínculos con diferentes organizaciones.
No incorpora riesgos, puesto normalizado ni relevamientos de seguridad e higiene.

Pruebas de integración pendientes

Organización existente sin empleados devuelve 200 con results=[] y totalItems=0.
Vínculos activos visibles por defecto, inactivos visibles solo con incluirInactivos=true.
El JWT de otro tenant recibe 404 y nunca obtiene información.
Una relación inconsistente entre tenants no se muestra.
Se respetan paginación, orden y límite máximo.