7 operaciones · base https://api.bestdoctorsrd.com
GET/v1/coverage-requirements
La matriz de cobertura de una unidad
Turnos y cargos en las filas, los siete días en las columnas.
`VIEW` basta: la dotación que un servicio necesita es información de operación, no dato personal
de nadie —el mismo criterio que ya aplica `GET /roster`—.
PAGINA EN SERVIDOR y lo que pagina son las FILAS de la matriz, es decir los pares (turno, cargo)
declarados. Con 48 cargos y un catálogo de turnos de seis, una unidad puede declarar decenas de
filas; los siete días viajan siempre completos porque media semana de requisito no se puede
leer.
Parámetros
Nombre
En
Tipo
Obl.
unitId
query
string
Sí
page
query
integer
No
page_size
query
integer
No
tenant_id
query
string o nulo
No
Respuestas
Código
Descripción
Devuelve
200
Respuesta correcta
CoverageMatrixOut
422
Error de validación
HTTPValidationError
PUT/v1/coverage-requirements
Declarar o cambiar un requisito
Fija el mínimo de un (unidad, turno, cargo) para varios días de una vez.
UN SOLO CAMINO para crear y para cambiar, y por eso es `PUT` y no `POST`: la celda de la matriz
se identifica por su clave natural —la misma que garantiza el índice único— y no por un id que
la pantalla tendría que recordar. Con dos caminos, quien vuelve a teclear el martes recibiría un
409 por corregir.
PERMISOS: `CREATE` para las celdas que NACEN y `UPDATE` para las que CAMBIAN, que es lo que pide
el criterio. Se resuelve después de leer qué días ya existen, y por eso la puerta previa es
`VIEW`: sin ella habría que exigir las dos siempre y auditoría —que sólo tiene lectura— vería un
403 distinto según lo que hubiera en la base.
UNA UNIDAD O UN TURNO DESACTIVADOS no admiten requisitos NUEVOS y conservan los que ya tienen:
la comprobación de «activo» sólo se exige si hay días por crear.
Parámetros
Nombre
En
Tipo
Obl.
tenant_id
query
string o nulo
No
Cuerpo obligatorioRequirementIn
Campo
Tipo
Obl.
unitId
string
Sí
shiftDefinitionId
string
Sí
staffTypeCode
string
Sí
days
lista de integer o nulo
No
dayPattern
string o nulo
No
minimum
integer
Sí
Respuestas
Código
Descripción
Devuelve
200
Respuesta correcta
RequirementResultOut
422
Error de validación
HTTPValidationError
GET/v1/coverage-requirements/cobertura
Requerido contra asignado
Lo requerido contra lo asignado, por día, turno y cargo.
La ARITMÉTICA no está aquí: está en `app.services.shift_coverage`, que es puro y por eso se prueba sin
HTTP. Esta ruta hace tres cosas y ninguna más: valida que la unidad sea de este centro, lee lo
que hay, y traduce.
LA SEMANA LA NORMALIZA EL SERVIDOR, con el mismo `inicio_de_semana` de la cuadrícula: dos
normalizaciones distintas harían que el semáforo y el rol hablaran de semanas distintas.
Es la lectura que el SEMÁFORO del CR-540 pintará encima de la cuadrícula. Aquí no se pinta nada.
Parámetros
Nombre
En
Tipo
Obl.
unitId
query
string
Sí
weekStart
query
string (date) o nulo
No
tenant_id
query
string o nulo
No
Respuestas
Código
Descripción
Devuelve
200
Respuesta correcta
CoverageOut
422
Error de validación
HTTPValidationError
POST/v1/coverage-requirements/copiar
Copiar la matriz de otra unidad
Copia la matriz de una unidad a otra, «para no llenar la misma veinte veces».
LAS DOS UNIDADES SON DE ESTE CENTRO, y la de origen puede estar desactivada —copiar de una
unidad que se cerró es leer historial— pero la de DESTINO no: escribir requisitos nuevos en una
unidad retirada es declarar dotación para un servicio que no existe.
TOLERANTE POR CELDA, como la vista previa de la importación de planilla: lo que no se puede
copiar se descarta CON SU MOTIVO y lo demás entra. Y el motivo viaja en la respuesta: un resumen
que sólo dijera «12 copiadas» dejaría creer que la matriz quedó igual que la de origen.
Sin `replace`, lo que el destino ya tenía declarado NO se toca: copiar no puede pisar en
silencio una dotación que alguien decidió a mano.
Parámetros
Nombre
En
Tipo
Obl.
tenant_id
query
string o nulo
No
Cuerpo obligatorioCopyIn
Campo
Tipo
Obl.
fromUnitId
string
Sí
toUnitId
string
Sí
replace
boolean
No
Respuestas
Código
Descripción
Devuelve
200
Respuesta correcta
CopyResultOut
422
Error de validación
HTTPValidationError
GET/v1/coverage-requirements/patrones
Atajos de días de la semana
«Entre semana», «fin de semana», «todos los días».
Los sirve el SERVIDOR para que la pantalla ofrezca exactamente lo que la puerta acepta: con la
lista quemada en el portal, añadir un atajo aquí lo dejaría inalcanzable y quitarlo daría 422
sin que nada lo avisara. Va declarada ANTES de cualquier ruta con parámetro: FastAPI resuelve
por orden y `/{requirement_id}` se tragaría «patrones».
Parámetros
Nombre
En
Tipo
Obl.
tenant_id
query
string o nulo
No
Respuestas
Código
Descripción
Devuelve
200
Respuesta correcta
lista de PatronOut
422
Error de validación
HTTPValidationError
GET/v1/coverage-requirements/resumen
Huecos de todas las unidades
Los huecos de TODAS las unidades del centro en una semana, por tamaño del hueco.
PARA QUÉ: con el cálculo de una unidad se sabe si la UCI está corta; para decidir **a quién
mover** hay que mirar las veinte unidades, y eso vuelve a ser contar a mano.
LA ARITMÉTICA NO ESTÁ AQUÍ. El requerido contra el asignado lo calcula
`app.services.shift_coverage` —el mismo que sirve la cuadrícula, para que las dos pantallas no
puedan discrepar— y la suma de la semana `app.services.coverage_summary`. Esta ruta lee, acota
por inquilino y traduce.
BASTA CON `VIEW`, que es criterio del CR: la cobertura de un servicio es información de
operación, no dato personal de asistencia — el mismo criterio que ya aplica la consulta del rol.
ORDENAR POR TAMAÑO DEL HUECO NO SE PUEDE DELEGAR EN SQL: el hueco no está en ninguna columna,
sale de restar el requisito contra lo asignado. Por eso se calcula el centro entero y se corta
la página aquí — que sigue siendo paginar EN EL SERVIDOR: al navegador sólo le llega su página.
LAS UNIDADES DESACTIVADAS QUEDAN FUERA. Un servicio cerrado no reclama dotación, y dejarlo
dentro llenaría de huecos falsos justo la lista que se abre para decidir a quién mover. Su
matriz y su rol se siguen abriendo uno por uno: eso es historial y hay que poder mirarlo.
Parámetros
Nombre
En
Tipo
Obl.
weekStart
query
string (date) o nulo
No
onlyWithGaps
query
boolean
No
page
query
integer
No
page_size
query
integer
No
tenant_id
query
string o nulo
No
Respuestas
Código
Descripción
Devuelve
200
Respuesta correcta
CoverageSummaryOut
422
Error de validación
HTTPValidationError
DELETE/v1/coverage-requirements/{requirement_id}
Retirar una celda
Quita UNA celda de la matriz.
Retirar no es declarar cero, y la diferencia es el criterio central del CR: «cero» dice que ese
día ese turno no necesita ese cargo, y no tener fila dice que nadie lo ha mirado. Por eso hay
las dos operaciones y no sólo un mínimo con valor cero.
`UPDATE` y no `CREATE`: es cambiar la matriz que ya existe.