Mateo Ferreyra commited on
Commit
ee18ee7
·
1 Parent(s): cbc2d86

docs: spec de auditoría de cama (M6)

Browse files
docs/superpowers/specs/2026-06-26-auditoria-cama-design.md ADDED
@@ -0,0 +1,239 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Auditoría de Cama — Diseño
2
+
3
+ **Fecha:** 2026-06-26
4
+ **Módulo:** M6 — Internación y Gestión de Camas
5
+ **Estado:** Aprobado para planificación
6
+
7
+ ## Objetivo
8
+
9
+ Registrar de forma persistente todo evento que ocurra sobre una cama durante su ciclo de vida: solicitudes, aprobaciones/rechazos, asignaciones, traslados, cambios de estado (manuales y automáticos), bajas y eventos de reservas de quirófano. Hoy estos eventos mutan el estado sin dejar rastro. Se expone además un endpoint GET para que el frontend pueda obtener el historial completo con filtros.
10
+
11
+ ## Alcance
12
+
13
+ Auditoría de **todo el dominio**: eventos de `CAMA`, `SOLICITUD` y `RESERVA_QUIROFANO`. Una sola tabla genérica con `entidad` / `entidad_id`, más un `cama_id` denormalizado que permite recuperar "todo lo que pasó con la cama X" aunque el evento haya sido originado por una solicitud o reserva.
14
+
15
+ Actor de cada evento: `usuario_id` (`sub` del JWT) + `rol`. Los eventos automáticos o disparados por webhooks de otros módulos (M1 HCE, M9 Monitoreo, M2 Turnos) se registran con `rol = SISTEMA` y `origen = WEBHOOK | SISTEMA`.
16
+
17
+ ### Fuera de alcance (YAGNI)
18
+
19
+ - No se modifican los contratos de las APIs existentes (mismas respuestas).
20
+ - No hay borrado ni edición de registros de auditoría (append-only).
21
+ - No hay export (CSV/PDF) ni agregaciones/estadísticas — solo el listado con filtros.
22
+ - No se versiona el estado completo de la entidad; solo `estado_anterior` / `estado_nuevo` y un `detalle` JSON con el contexto relevante.
23
+
24
+ ## Decisión arquitectónica
25
+
26
+ **Instrumentación explícita en la capa de servicios.** En cada punto de mutación de `cama_service.py` y `solicitud_service.py` se invoca `crud.auditoria.registrar(...)`. Es coherente con el patrón actual (services orquestan la lógica, crud persiste) y es el único enfoque que conoce el contexto de negocio completo: quién actuó, qué acción fue, estado anterior/nuevo y la solicitud/reserva asociada.
27
+
28
+ Alternativas descartadas:
29
+ - **Triggers de PostgreSQL**: no capturan el actor del JWT ni el contexto de negocio; quedan fuera del código y son invisibles para los tests.
30
+ - **Middleware/decorador HTTP**: no conoce el estado anterior/nuevo del dominio ni los eventos disparados por webhooks internos.
31
+
32
+ ## Modelo de datos
33
+
34
+ Tabla nueva `auditoria` (Supabase / PostgreSQL).
35
+
36
+ | Campo | Tipo | Nullable | Descripción |
37
+ |---|---|---|---|
38
+ | `id` | bigint identity | PK | Identificador del evento de auditoría |
39
+ | `entidad` | text | no | `CAMA` \| `SOLICITUD` \| `RESERVA_QUIROFANO` |
40
+ | `entidad_id` | text | no | Id de la entidad afectada (texto: admite ids numéricos y `solicitud_hce_id`) |
41
+ | `cama_id` | bigint | sí | Cama afectada; denormalizado para filtrar el historial por cama |
42
+ | `evento` | text | no | Tipo de evento (ver enum `TipoEventoAuditoriaEnum`) |
43
+ | `estado_anterior` | text | sí | Estado previo de la entidad |
44
+ | `estado_nuevo` | text | sí | Estado resultante |
45
+ | `paciente_id` | bigint | sí | Paciente involucrado, si aplica |
46
+ | `usuario_id` | text | sí | `sub` del JWT; null en eventos de sistema |
47
+ | `rol` | text | sí | `ADMINISTRATIVO` \| `MEDICO` \| `LIMPIEZA` \| `SISTEMA` |
48
+ | `origen` | text | no | `API` \| `WEBHOOK` \| `SISTEMA` |
49
+ | `descripcion` | text | sí | Texto legible para el frontend |
50
+ | `detalle` | jsonb | sí | Contexto extra (motivo, cama_origen, acción, etc.) |
51
+ | `hospital_id` | text | sí | Denormalizado para filtrado multi-hospital |
52
+ | `creado_en` | timestamptz | no | Default `now()` |
53
+
54
+ Índices: `cama_id`, `(entidad, entidad_id)`, `paciente_id`, `creado_en DESC`, `hospital_id`.
55
+
56
+ ### SQL de creación
57
+
58
+ ```sql
59
+ -- Ejecutar en Supabase SQL Editor
60
+ CREATE TABLE IF NOT EXISTS auditoria (
61
+ id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
62
+ entidad TEXT NOT NULL,
63
+ entidad_id TEXT NOT NULL,
64
+ cama_id BIGINT,
65
+ evento TEXT NOT NULL,
66
+ estado_anterior TEXT,
67
+ estado_nuevo TEXT,
68
+ paciente_id BIGINT,
69
+ usuario_id TEXT,
70
+ rol TEXT,
71
+ origen TEXT NOT NULL DEFAULT 'API',
72
+ descripcion TEXT,
73
+ detalle JSONB,
74
+ hospital_id TEXT,
75
+ creado_en TIMESTAMPTZ NOT NULL DEFAULT now()
76
+ );
77
+
78
+ CREATE INDEX IF NOT EXISTS idx_auditoria_cama_id ON auditoria (cama_id);
79
+ CREATE INDEX IF NOT EXISTS idx_auditoria_entidad ON auditoria (entidad, entidad_id);
80
+ CREATE INDEX IF NOT EXISTS idx_auditoria_paciente_id ON auditoria (paciente_id);
81
+ CREATE INDEX IF NOT EXISTS idx_auditoria_creado_en ON auditoria (creado_en DESC);
82
+ CREATE INDEX IF NOT EXISTS idx_auditoria_hospital_id ON auditoria (hospital_id);
83
+ ```
84
+
85
+ ## Enums (en `app/schemas/enums.py`)
86
+
87
+ ```python
88
+ class EntidadAuditoriaEnum(str, Enum):
89
+ CAMA = "CAMA"
90
+ SOLICITUD = "SOLICITUD"
91
+ RESERVA_QUIROFANO = "RESERVA_QUIROFANO"
92
+
93
+ class OrigenAuditoriaEnum(str, Enum):
94
+ API = "API"
95
+ WEBHOOK = "WEBHOOK"
96
+ SISTEMA = "SISTEMA"
97
+
98
+ class TipoEventoAuditoriaEnum(str, Enum):
99
+ SOLICITUD_RECIBIDA = "SOLICITUD_RECIBIDA"
100
+ SOLICITUD_APROBADA = "SOLICITUD_APROBADA"
101
+ SOLICITUD_RECHAZADA = "SOLICITUD_RECHAZADA"
102
+ CAMA_CREADA = "CAMA_CREADA"
103
+ CAMA_ASIGNADA = "CAMA_ASIGNADA"
104
+ CAMA_TRASLADO = "CAMA_TRASLADO"
105
+ CAMA_CAMBIO_ESTADO = "CAMA_CAMBIO_ESTADO"
106
+ CAMA_ALTA = "CAMA_ALTA"
107
+ CAMA_CODIGO_ROJO = "CAMA_CODIGO_ROJO"
108
+ CAMA_ALERTA_RESUELTA = "CAMA_ALERTA_RESUELTA"
109
+ CAMA_BAJA = "CAMA_BAJA"
110
+ RESERVA_CREADA = "RESERVA_CREADA"
111
+ RESERVA_CAMBIO_ESTADO = "RESERVA_CAMBIO_ESTADO"
112
+ RESERVA_URGENTE = "RESERVA_URGENTE"
113
+ RESERVA_DESPLAZADA = "RESERVA_DESPLAZADA"
114
+ RESERVA_CANCELADA = "RESERVA_CANCELADA"
115
+ ```
116
+
117
+ ## Componentes
118
+
119
+ Siguiendo las capas existentes (`routers → services → crud → models`):
120
+
121
+ - **`app/models/auditoria.py`** — clase `Auditoria` con `__init__` y `from_dict`, en el mismo estilo que `Cama`.
122
+ - **`app/schemas/auditoria.py`** — `AuditoriaResponse` (`from_attributes=True`) y `AuditoriaListResponse` (`{ total, eventos: list[AuditoriaResponse] }`).
123
+ - **`app/crud/auditoria.py`**:
124
+ - `registrar(db, *, entidad, entidad_id, evento, cama_id=None, estado_anterior=None, estado_nuevo=None, paciente_id=None, actor=None, origen="API", descripcion=None, detalle=None, hospital_id=None) -> None` — inserta una fila. **Best-effort**: envuelto en `try/except`, ante error solo loguea `warning` y nunca propaga (la auditoría jamás rompe la operación de negocio).
125
+ - `get_all(db, *, cama_id, entidad, entidad_id, paciente_id, evento, rol, usuario_id, hospital_id, fecha_desde, fecha_hasta, limit, offset) -> tuple[list[Auditoria], int]` — query con filtros, orden `creado_en` desc, paginación. Devuelve filas + total.
126
+ - **`app/routers/auditoria.py`** — `GET /auditoria`.
127
+ - **`app/schemas/enums.py`** — enums nuevos (arriba).
128
+ - **`app/main.py`** — registrar el router.
129
+
130
+ ### Actor
131
+
132
+ Tipo liviano para transportar el actor desde el router hasta el crud. Un `dict` con `usuario_id`, `rol`. Los servicios que mutan reciben un parámetro `actor: dict | None = None`; cuando es `None` (webhooks/automáticos) se registra con `rol = SISTEMA`. Los routers construyen el actor desde `user` (`{"usuario_id": user["sub"], "rol": user["rol"]}`).
133
+
134
+ ## Puntos de instrumentación
135
+
136
+ `cama_service.py`:
137
+
138
+ | Función | Evento | Notas |
139
+ |---|---|---|
140
+ | `create_cama` | `CAMA_CREADA` | estado_nuevo=DISPONIBLE |
141
+ | `update_cama` (cambio de estado) | `CAMA_CAMBIO_ESTADO` | estado_anterior→estado_nuevo, actor del router |
142
+ | `delete_cama` | `CAMA_BAJA` | estado_anterior→BAJA_PERMANENTE |
143
+ | `asignar_cama` (INGRESO) | `CAMA_ASIGNADA` | paciente_id, cama destino |
144
+ | `asignar_cama` (TRASLADO) | `CAMA_TRASLADO` | detalle con cama_origen_id; un evento por la cama destino |
145
+ | `update_quirofano` (cambio de estado) | `CAMA_CAMBIO_ESTADO` | |
146
+ | `update_reserva_estado` | `RESERVA_CAMBIO_ESTADO` (+ `CAMA_CAMBIO_ESTADO` por la cama) | la cama cambia de estado al pasar a EN_CURSO/COMPLETADA |
147
+ | `create_reserva` | `RESERVA_CREADA` | solo si `created=True` |
148
+ | `crear_reserva_urgente` | `RESERVA_URGENTE` (+ `RESERVA_DESPLAZADA` si hubo candidata) | origen=WEBHOOK |
149
+
150
+ `solicitud_service.py`:
151
+
152
+ | Función | Evento | Notas |
153
+ |---|---|---|
154
+ | `recibir_solicitud` | `SOLICITUD_RECIBIDA` | origen=WEBHOOK; solo si se creó (no idempotente) |
155
+ | `resolver_solicitud` → `_rechazar` | `SOLICITUD_RECHAZADA` | detalle con motivo |
156
+ | `resolver_solicitud` → `_aprobar_internacion` | `SOLICITUD_APROBADA` (+ `CAMA_ASIGNADA`) | actor=resuelto_por |
157
+ | `resolver_solicitud` → `_aprobar_traslado` | `SOLICITUD_APROBADA` (+ `CAMA_TRASLADO`) | actor=resuelto_por |
158
+ | `procesar_alta_medica` | `CAMA_ALTA` | origen=WEBHOOK; estado→EN_LIMPIEZA |
159
+ | `procesar_alerta_emergencia` | `CAMA_CODIGO_ROJO` | origen=WEBHOOK |
160
+ | `procesar_alerta_resuelta` | `CAMA_ALERTA_RESUELTA` | origen=WEBHOOK; CODIGO_ROJO→OCUPADA |
161
+ | `cancelar_reserva_por_turno` | `RESERVA_CANCELADA` | origen=WEBHOOK |
162
+
163
+ Para registrar el actor donde hoy no llega, se agrega un parámetro `actor` a las funciones de servicio invocadas desde routers autenticados (`update_cama`, `delete_cama`, `asignar_cama`, `update_quirofano`, `update_reserva_estado`, `create_reserva`, `resolver_solicitud`). Los routers lo construyen desde el JWT. Las funciones disparadas por webhooks no reciben actor y registran `SISTEMA`/`WEBHOOK`.
164
+
165
+ ## Endpoint
166
+
167
+ ```
168
+ GET /api/v1/auditoria
169
+ ```
170
+
171
+ Autorización: roles `ADMINISTRATIVO`, `MEDICO`.
172
+
173
+ Query params (todos opcionales):
174
+
175
+ | Param | Tipo | Default | Descripción |
176
+ |---|---|---|---|
177
+ | `cama_id` | int | — | Filtra por cama |
178
+ | `entidad` | enum | — | CAMA \| SOLICITUD \| RESERVA_QUIROFANO |
179
+ | `entidad_id` | str | — | Id de entidad |
180
+ | `paciente_id` | int | — | Filtra por paciente |
181
+ | `evento` | enum | — | Tipo de evento |
182
+ | `rol` | str | — | Actor |
183
+ | `usuario_id` | str | — | Actor |
184
+ | `hospital_id` | str | — | Hospital |
185
+ | `fecha_desde` | datetime ISO | — | `creado_en >=` |
186
+ | `fecha_hasta` | datetime ISO | — | `creado_en <=` |
187
+ | `limit` | int | 100 | Máx 500 |
188
+ | `offset` | int | 0 | Paginación |
189
+
190
+ Respuesta `200`:
191
+
192
+ ```json
193
+ {
194
+ "total": 42,
195
+ "eventos": [
196
+ {
197
+ "id": 42,
198
+ "entidad": "CAMA",
199
+ "entidad_id": "12",
200
+ "cama_id": 12,
201
+ "evento": "CAMA_CAMBIO_ESTADO",
202
+ "estado_anterior": "OCUPADA",
203
+ "estado_nuevo": "EN_LIMPIEZA",
204
+ "paciente_id": 7,
205
+ "usuario_id": "1",
206
+ "rol": "ADMINISTRATIVO",
207
+ "origen": "API",
208
+ "descripcion": "Cama 12: OCUPADA → EN_LIMPIEZA",
209
+ "detalle": {"motivo": "alta médica"},
210
+ "hospital_id": "HOSP-001",
211
+ "creado_en": "2026-06-26T14:30:00Z"
212
+ }
213
+ ]
214
+ }
215
+ ```
216
+
217
+ `401` sin token, `403` rol no autorizado.
218
+
219
+ ## Manejo de errores
220
+
221
+ - `registrar(...)` es best-effort: cualquier excepción se captura y loguea como `warning`; **no** afecta la transacción de negocio. Razón: la auditoría es observabilidad, no debe degradar la disponibilidad de la gestión de camas.
222
+ - El GET valida `limit` (1–500) y `offset` (≥0) vía FastAPI `Query`.
223
+
224
+ ## Testing
225
+
226
+ `tests/test_auditoria.py`:
227
+
228
+ - El GET sin token devuelve 401; con rol `LIMPIEZA` devuelve 403.
229
+ - El GET devuelve eventos filtrables por `cama_id`, `evento`, `paciente_id` y rango de fechas, ordenados desc.
230
+ - Crear/actualizar/dar de baja una cama genera los eventos esperados (`CAMA_CREADA`, `CAMA_CAMBIO_ESTADO`, `CAMA_BAJA`) con `estado_anterior`/`estado_nuevo` correctos.
231
+ - Aprobar una solicitud de internación genera `SOLICITUD_APROBADA` + `CAMA_ASIGNADA`.
232
+ - Un fallo del insert de auditoría (mock que lanza) **no** rompe la operación de negocio.
233
+
234
+ Se sigue el patrón existente de `tests/conftest.py` y `tests/factories.py` (revisar cómo mockean Supabase para extenderlo a la tabla `auditoria`).
235
+
236
+ ## Documentación
237
+
238
+ - Añadir el `CREATE TABLE auditoria` al README junto al bloque de reseteo de tablas, y `auditoria` al `DROP TABLE` de reset.
239
+ ```