jpsoron commited on
Commit
3f84646
Β·
unverified Β·
2 Parent(s): 6d76dbb46d7170

Merge pull request #5 from MateFerreyra/jps/integracion-M10

Browse files
.env.example CHANGED
@@ -9,6 +9,21 @@ JWT_SECRET=CAMBIAR_POR_SECRET_ALEATORIO_DE_64_CARACTERES
9
  JWT_ALGORITHM=HS256
10
  JWT_EXPIRE_MINUTES=60
11
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
12
  # ─── Entorno ───────────────────────────────────────────────────────────────
13
  # Valores vΓ‘lidos: development | staging | production
14
  # En 'production', el endpoint /auth/token queda deshabilitado
 
9
  JWT_ALGORITHM=HS256
10
  JWT_EXPIRE_MINUTES=60
11
 
12
+ # ─── Auth: mock local vs. Core (M10) real ──────────────────────────────────
13
+ # "mock": JWT propios (comportamiento actual, requiere JWT_SECRET arriba).
14
+ # "core": JWT emitidos por M10, verificados vΓ­a JWKS (requiere M10_CORE_URL
15
+ # y la cuenta de servicio de abajo).
16
+ AUTH_MODE=mock
17
+
18
+ # Cuenta de servicio de M6 en el Core (solo si AUTH_MODE=core). Se usa para
19
+ # el lookup de roles (GET /roles) y para autenticar las llamadas salientes.
20
+ CORE_SERVICE_EMAIL=
21
+ CORE_SERVICE_PASSWORD=
22
+
23
+ # TTL de los caches de integraciΓ³n con Core (segundos)
24
+ JWKS_CACHE_TTL_SECONDS=300
25
+ CORE_ROLES_CACHE_TTL_SECONDS=300
26
+
27
  # ─── Entorno ───────────────────────────────────────────────────────────────
28
  # Valores vΓ‘lidos: development | staging | production
29
  # En 'production', el endpoint /auth/token queda deshabilitado
app/config.py CHANGED
@@ -1,3 +1,5 @@
 
 
1
  from pydantic_settings import BaseSettings, SettingsConfigDict
2
 
3
 
@@ -17,6 +19,20 @@ class Settings(BaseSettings):
17
  jwt_algorithm: str = "HS256"
18
  jwt_expire_minutes: int = 60
19
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
20
  # Entorno β€” controla comportamiento de endpoints de desarrollo
21
  environment: str = "development"
22
 
 
1
+ from typing import Literal
2
+
3
  from pydantic_settings import BaseSettings, SettingsConfigDict
4
 
5
 
 
19
  jwt_algorithm: str = "HS256"
20
  jwt_expire_minutes: int = 60
21
 
22
+ # ─── Auth: mock local vs. Core (M10) real ──────────────────────────────
23
+ # "mock": JWT propios firmados con jwt_secret (comportamiento actual).
24
+ # "core": JWT emitidos por M10, verificados localmente vΓ­a JWKS.
25
+ auth_mode: Literal["mock", "core"] = "mock"
26
+
27
+ # Cuenta de servicio de M6 en el Core: usada para el lookup de roles
28
+ # (GET /roles) y para autenticar las llamadas salientes a M1/M2/M7/M10.
29
+ core_service_email: str = ""
30
+ core_service_password: str = ""
31
+
32
+ # TTL de los caches de integraciΓ³n con Core (segundos)
33
+ jwks_cache_ttl_seconds: int = 300
34
+ core_roles_cache_ttl_seconds: int = 300
35
+
36
  # Entorno β€” controla comportamiento de endpoints de desarrollo
37
  environment: str = "development"
38
 
app/dependencies.py CHANGED
@@ -62,6 +62,10 @@ def get_current_user(
62
  ) -> dict:
63
  if credentials is None:
64
  raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail=_ERROR_401)
 
 
 
 
65
  try:
66
  payload = decode_token(credentials.credentials)
67
  except ValueError:
@@ -73,6 +77,33 @@ def get_current_user(
73
  return payload
74
 
75
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
76
  def require_roles(*roles: str):
77
  """
78
  Uso: Depends(require_roles("ADMINISTRATIVO", "MEDICO"))
 
62
  ) -> dict:
63
  if credentials is None:
64
  raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail=_ERROR_401)
65
+
66
+ if settings.auth_mode == "core":
67
+ return _get_current_user_core(credentials.credentials)
68
+
69
  try:
70
  payload = decode_token(credentials.credentials)
71
  except ValueError:
 
77
  return payload
78
 
79
 
80
+ def _get_current_user_core(token: str) -> dict:
81
+ """
82
+ Rama `auth_mode="core"`: verifica el JWT del Core vΓ­a JWKS, resuelve el
83
+ rol del usuario contra el Core (el token no lo transporta β€” ver
84
+ `app/integrations/core_auth.py`) y lo traduce al rol interno de M6.
85
+ Devuelve la misma forma que el modo mock (`{"sub", "rol"}`) para que
86
+ `require_roles`, la auditorΓ­a y los routers no necesiten distinguir modo.
87
+ """
88
+ from app.integrations import core_auth
89
+
90
+ try:
91
+ payload = core_auth.verify_core_token(token)
92
+ except ValueError:
93
+ raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail=_ERROR_401)
94
+
95
+ user_id = payload.get("user_id")
96
+ if user_id is None:
97
+ raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail=_ERROR_401)
98
+
99
+ role_names = core_auth.resolve_user_roles(user_id)
100
+ rol = core_auth.map_core_roles_to_internal(role_names)
101
+ if rol is None:
102
+ raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=_ERROR_403)
103
+
104
+ return {"sub": str(user_id), "rol": rol, "core_roles": role_names}
105
+
106
+
107
  def require_roles(*roles: str):
108
  """
109
  Uso: Depends(require_roles("ADMINISTRATIVO", "MEDICO"))
app/integrations/_base.py CHANGED
@@ -4,14 +4,21 @@ Helpers HTTP internos compartidos por todos los clientes de integraciΓ³n.
4
  import logging
5
  import httpx
6
  from app.config import settings
 
7
 
8
  logger = logging.getLogger(__name__)
9
 
10
 
11
  def _headers(token: str | None = None) -> dict:
12
  h = {"Content-Type": "application/json"}
13
- if token:
14
- h["Authorization"] = f"Bearer {token}"
 
 
 
 
 
 
15
  return h
16
 
17
 
 
4
  import logging
5
  import httpx
6
  from app.config import settings
7
+ from app.integrations import core_auth
8
 
9
  logger = logging.getLogger(__name__)
10
 
11
 
12
  def _headers(token: str | None = None) -> dict:
13
  h = {"Content-Type": "application/json"}
14
+ # Si no se pasΓ³ un token explΓ­cito (ej. propagar el del usuario), usar
15
+ # la cuenta de servicio de M6 β€” necesaria para llamadas disparadas por
16
+ # webhooks entrantes, donde no hay usuario humano autenticado. En modo
17
+ # mock (`auth_mode != "core"`) devuelve None y el comportamiento no
18
+ # cambia respecto de antes.
19
+ effective_token = token or core_auth.get_service_token()
20
+ if effective_token:
21
+ h["Authorization"] = f"Bearer {effective_token}"
22
  return h
23
 
24
 
app/integrations/core.py CHANGED
@@ -9,4 +9,8 @@ def validate_patient(paciente_id: int) -> dict | None:
9
  """Verifica existencia del paciente en M10. Retorna datos bΓ‘sicos o None."""
10
  if settings.mock_external_services:
11
  return {"id": paciente_id, "nombre": "Paciente", "apellido": "Mock"}
12
- return _get(f"{settings.m10_core_url}/api/v1/usuarios/{paciente_id}")
 
 
 
 
 
9
  """Verifica existencia del paciente en M10. Retorna datos bΓ‘sicos o None."""
10
  if settings.mock_external_services:
11
  return {"id": paciente_id, "nombre": "Paciente", "apellido": "Mock"}
12
+ # Los pacientes son usuarios del Core (consigna M10 Β§10: "Maestro de
13
+ # Usuarios ... mΓ©dicos, enfermeros, administrativos, bioquΓ­micos y
14
+ # pacientes"). Path real del spec (verificado contra M10_openapi.yaml):
15
+ # GET /users/{id}, sin prefijo /api/v1.
16
+ return _get(f"{settings.m10_core_url}/users/{paciente_id}")
app/integrations/core_auth.py ADDED
@@ -0,0 +1,214 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ M10 Core β€” integraciΓ³n de autenticaciΓ³n real: verificaciΓ³n de JWT vΓ­a JWKS,
3
+ resoluciΓ³n de rol de usuario y cuenta de servicio de M6.
4
+
5
+ Solo se usa cuando `settings.auth_mode == "core"`. En modo "mock" (default),
6
+ `app/dependencies.py` sigue firmando y validando sus propios JWT (HS256).
7
+ """
8
+ import logging
9
+ import time
10
+
11
+ import httpx
12
+ from jose import JWTError, jwt
13
+
14
+ from app.config import settings
15
+
16
+ logger = logging.getLogger(__name__)
17
+
18
+
19
+ # ─── VerificaciΓ³n de firma (JWKS) ──────────────────────────────────────────
20
+
21
+ # Cache en memoria del JWKS del Core, indexado por `kid`. Un ΓΊnico proceso
22
+ # uvicorn (igual que el resto de la app, ver M6_DISEΓ‘O Β§3) β€” no hay estado
23
+ # compartido entre workers que resolver acΓ‘.
24
+ _jwks_cache: dict = {"keys_by_kid": {}, "fetched_at": 0.0}
25
+
26
+
27
+ def _fetch_jwks() -> dict:
28
+ url = f"{settings.m10_core_url}/.well-known/jwks.json"
29
+ r = httpx.get(url, timeout=settings.http_timeout_seconds)
30
+ r.raise_for_status()
31
+ return r.json()
32
+
33
+
34
+ def get_signing_key(kid: str) -> dict:
35
+ """
36
+ Devuelve la JWK (dict) del Core que matchea el `kid` del header de un
37
+ token. Refresca el cache si expirΓ³ (TTL `jwks_cache_ttl_seconds`) o si el
38
+ `kid` pedido no estΓ‘ β€” cubre la rotaciΓ³n de claves del Core sin reiniciar
39
+ M6.
40
+ """
41
+ now = time.monotonic()
42
+ stale = (now - _jwks_cache["fetched_at"]) > settings.jwks_cache_ttl_seconds
43
+ if stale or kid not in _jwks_cache["keys_by_kid"]:
44
+ jwks = _fetch_jwks()
45
+ _jwks_cache["keys_by_kid"] = {k["kid"]: k for k in jwks.get("keys", []) if "kid" in k}
46
+ _jwks_cache["fetched_at"] = now
47
+
48
+ key = _jwks_cache["keys_by_kid"].get(kid)
49
+ if key is None:
50
+ raise ValueError(f"No se encontrΓ³ una clave JWKS del Core con kid={kid!r}")
51
+ return key
52
+
53
+
54
+ def verify_core_token(token: str) -> dict:
55
+ """
56
+ Verifica la firma de un JWT emitido por M10 (Core) contra su JWKS y
57
+ devuelve el payload decodificado (`{exp, iat, permissions[], user_id}`).
58
+
59
+ Confirmado contra el Core real (`https://api.healthcare.cantero.ar`):
60
+ el token no lleva `iss` ni `aud`, asΓ­ que no se validan acΓ‘ β€” solo firma
61
+ y expiraciΓ³n (`jwt.decode` valida `exp` por default).
62
+ """
63
+ try:
64
+ header = jwt.get_unverified_header(token)
65
+ except JWTError as e:
66
+ raise ValueError("Header de token invΓ‘lido") from e
67
+
68
+ kid = header.get("kid")
69
+ if not kid:
70
+ raise ValueError("Token del Core sin 'kid' en el header")
71
+
72
+ key = get_signing_key(kid)
73
+ try:
74
+ return jwt.decode(token, key, algorithms=[key.get("alg", "RS256")])
75
+ except JWTError as e:
76
+ raise ValueError("Token del Core invΓ‘lido o expirado") from e
77
+
78
+
79
+ # ─── Cuenta de servicio de M6 ───────────────────────────────────────────────
80
+
81
+ # Token de la cuenta de servicio de M6 en el Core. Se usa para: (1) firmar
82
+ # las llamadas salientes a M1/M2/M7/M10 (adjuntado automΓ‘ticamente por
83
+ # `app/integrations/_base.py`), y (2) el lookup de roles de S2
84
+ # (`resolve_user_roles`), incluidas las llamadas disparadas por webhooks
85
+ # entrantes donde no hay un usuario humano autenticado.
86
+ _service_token_cache: dict = {"token": None, "expires_at": 0.0}
87
+
88
+ # Margen de expiraciΓ³n: se renueva el token antes de que venza de verdad,
89
+ # para no arriesgar un 401 a mitad de una llamada saliente.
90
+ _SERVICE_TOKEN_EXPIRY_MARGIN_SECONDS = 30
91
+
92
+
93
+ def get_service_token() -> str | None:
94
+ """
95
+ Devuelve un token vΓ‘lido de la cuenta de servicio de M6, refrescΓ‘ndolo
96
+ si expirΓ³ o no se pidiΓ³ todavΓ­a. `None` si `auth_mode` no es "core" o si
97
+ faltan las credenciales de servicio (`CORE_SERVICE_EMAIL`/`_PASSWORD`) β€”
98
+ en ambos casos el llamador debe seguir sin el header `Authorization`,
99
+ igual que el comportamiento actual en modo mock.
100
+ """
101
+ if settings.auth_mode != "core":
102
+ return None
103
+ if not settings.core_service_email or not settings.core_service_password:
104
+ logger.warning(
105
+ "auth_mode=core pero CORE_SERVICE_EMAIL/CORE_SERVICE_PASSWORD no estΓ‘n configurados"
106
+ )
107
+ return None
108
+
109
+ cached = _service_token_cache["token"]
110
+ if cached and time.time() < _service_token_cache["expires_at"]:
111
+ return cached
112
+
113
+ return _login_service_account()
114
+
115
+
116
+ def _login_service_account() -> str | None:
117
+ url = f"{settings.m10_core_url}/auth/login"
118
+ payload = {"email": settings.core_service_email, "password": settings.core_service_password}
119
+ try:
120
+ r = httpx.post(url, json=payload, timeout=settings.http_timeout_seconds)
121
+ r.raise_for_status()
122
+ token = r.json().get("token")
123
+ except Exception as e:
124
+ logger.warning("No se pudo autenticar la cuenta de servicio de M6 en el Core: %s", e)
125
+ return None
126
+
127
+ if not token:
128
+ return None
129
+
130
+ try:
131
+ exp = jwt.get_unverified_claims(token).get("exp")
132
+ except JWTError:
133
+ exp = None
134
+
135
+ _service_token_cache["token"] = token
136
+ _service_token_cache["expires_at"] = (
137
+ exp - _SERVICE_TOKEN_EXPIRY_MARGIN_SECONDS if exp else time.time() + 60
138
+ )
139
+ return token
140
+
141
+
142
+ # ─── ResoluciΓ³n de rol (S2-A: lookup de GET /roles) ────────────────────────
143
+
144
+ # El JWT del Core no lleva el nombre del rol (confirmado en vivo: solo trae
145
+ # `permissions[]` planas) β€” hay que resolverlo con una llamada aparte. Este
146
+ # mapeo es la ΓΊnica fuente de la verdad de quΓ© rol de Core habilita quΓ© rol
147
+ # interno de M6; ajustar acΓ‘ si cambian los nombres en el Core compartido.
148
+ CORE_ROLE_TO_INTERNAL: dict[str, str] = {
149
+ "admin_internacion": "ADMINISTRATIVO",
150
+ "admin": "ADMINISTRATIVO", # super-admin del Core β€” a confirmar con el equipo M10
151
+ "Medico": "MEDICO",
152
+ "limpieza": "LIMPIEZA",
153
+ }
154
+
155
+ # Si un usuario tiene varios roles mapeados, gana el de mayor alcance.
156
+ _ROLE_PRECEDENCE = ("ADMINISTRATIVO", "MEDICO", "LIMPIEZA")
157
+
158
+ # Índice inverso `user_id -> [nombres de rol]`, cacheado con TTL
159
+ # (`core_roles_cache_ttl_seconds`). Trae el padrΓ³n completo en cada refresh
160
+ # porque `GET /roles` es lo ΓΊnico que la cuenta de servicio puede leer hoy
161
+ # (`GET /users/{id}` requiere `users:read`, no disponible β€” ver S2-B en el
162
+ # plan). Aceptable al tamaΓ±o actual del Core compartido; un usuario reciΓ©n
163
+ # asignado a un rol puede tardar hasta el TTL en reflejarse.
164
+ _roles_index_cache: dict = {"user_id_to_roles": {}, "fetched_at": 0.0}
165
+
166
+
167
+ def _fetch_roles_index() -> dict[int, list[str]]:
168
+ token = get_service_token()
169
+ headers = {"Authorization": f"Bearer {token}"} if token else {}
170
+ url = f"{settings.m10_core_url}/roles"
171
+ r = httpx.get(
172
+ url, headers=headers, params={"pageSize": 200}, timeout=settings.http_timeout_seconds
173
+ )
174
+ r.raise_for_status()
175
+ data = r.json()
176
+
177
+ index: dict[int, list[str]] = {}
178
+ for role in data.get("data", []):
179
+ name = role.get("name")
180
+ for user in role.get("users") or []:
181
+ uid = user.get("id")
182
+ if uid is None or name is None:
183
+ continue
184
+ index.setdefault(uid, []).append(name)
185
+ return index
186
+
187
+
188
+ def resolve_user_roles(user_id: int) -> list[str]:
189
+ """Nombres de rol de Core asignados a `user_id` (S2-A: vΓ­a GET /roles)."""
190
+ now = time.monotonic()
191
+ stale = (now - _roles_index_cache["fetched_at"]) > settings.core_roles_cache_ttl_seconds
192
+ if stale:
193
+ try:
194
+ _roles_index_cache["user_id_to_roles"] = _fetch_roles_index()
195
+ _roles_index_cache["fetched_at"] = now
196
+ except Exception as e:
197
+ logger.warning("No se pudo refrescar el Γ­ndice de roles del Core: %s", e)
198
+ # Sin Γ­ndice previo, no hay de dΓ³nde resolver β€” se propaga.
199
+ if not _roles_index_cache["user_id_to_roles"]:
200
+ raise
201
+
202
+ return _roles_index_cache["user_id_to_roles"].get(user_id, [])
203
+
204
+
205
+ def map_core_roles_to_internal(role_names: list[str]) -> str | None:
206
+ """
207
+ Traduce roles de Core al rol interno de M6, con precedencia si el
208
+ usuario tiene mΓ‘s de uno mapeado. `None` si ninguno mapea (sin acceso).
209
+ """
210
+ mapped = {CORE_ROLE_TO_INTERNAL[name] for name in role_names if name in CORE_ROLE_TO_INTERNAL}
211
+ for rol in _ROLE_PRECEDENCE:
212
+ if rol in mapped:
213
+ return rol
214
+ return None
app/main.py CHANGED
@@ -75,10 +75,15 @@ app.include_router(auditoria.router, prefix=PREFIX)
75
  )
76
  def get_dev_token(usuario: str, password: str):
77
  """
78
- Solo habilitado si ENVIRONMENT=development.
79
  Genera un JWT de prueba. Roles vΓ‘lidos: ADMINISTRATIVO | MEDICO | LIMPIEZA
 
 
 
 
 
80
  """
81
- if settings.environment != "development":
82
  return JSONResponse(
83
  status_code=404,
84
  content={"codigo": "RECURSO_NO_ENCONTRADO", "mensaje": "Not Found"},
 
75
  )
76
  def get_dev_token(usuario: str, password: str):
77
  """
78
+ Solo habilitado si ENVIRONMENT=development y AUTH_MODE=mock.
79
  Genera un JWT de prueba. Roles vΓ‘lidos: ADMINISTRATIVO | MEDICO | LIMPIEZA
80
+
81
+ Con AUTH_MODE=core, la autenticaciΓ³n es responsabilidad del Core (M10):
82
+ este endpoint no aplica β€” un token HS256 propio no pasa la verificaciΓ³n
83
+ RS256 vΓ­a JWKS que usa `get_current_user` en ese modo. Loguearse contra
84
+ el Core real: `POST /auth/login` en `settings.m10_core_url`.
85
  """
86
+ if settings.environment != "development" or settings.auth_mode != "mock":
87
  return JSONResponse(
88
  status_code=404,
89
  content={"codigo": "RECURSO_NO_ENCONTRADO", "mensaje": "Not Found"},
docs/.DS_Store CHANGED
Binary files a/docs/.DS_Store and b/docs/.DS_Store differ
 
docs/superpowers/.DS_Store CHANGED
Binary files a/docs/superpowers/.DS_Store and b/docs/superpowers/.DS_Store differ
 
documentation/M10_integration.md ADDED
@@ -0,0 +1,573 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Tutorial: Comunicacion entre microservicios
2
+
3
+ Esta guia va al grano: como conectar microservicios usando el Core como punto de configuracion y publicacion.
4
+
5
+ La idea, cortita y al pie ( β€’ ̀ω‒́ )✧:
6
+
7
+ - Las colas se crean desde el Core.
8
+ - Los eventos se crean desde el Core.
9
+ - Los bindings entre eventos y colas se hacen desde el Core.
10
+ - Los microservicios escuchan sus propias colas de respuesta en RabbitMQ.
11
+ - Los microservicios publican mensajes llamando al Core.
12
+
13
+ Regla mental: RabbitMQ para escuchar; Core para configurar y publicar. Asi evitamos colas creadas a mano y bindings fantasma. ദࡍദി Λ‰ΝˆΜ€κ’³Λ‰ΝˆΜ )✧
14
+
15
+ ## Conceptos
16
+
17
+ ### Requests
18
+
19
+ Una `request` es un pedido que un microservicio le manda a otro.
20
+
21
+ Ejemplo:
22
+
23
+ `appointments` le pide a `billing` que cree una factura.
24
+
25
+ ### Responses
26
+
27
+ Una `response` es la respuesta a una request anterior.
28
+
29
+ Ejemplo:
30
+
31
+ `billing` le responde a `appointments` que la factura fue creada.
32
+
33
+ ### Correlation ID
34
+
35
+ Si una request espera respuesta, agreguen un `correlation_id`.
36
+
37
+ La response tiene que devolver ese mismo `correlation_id`.
38
+
39
+ Sirve para que quien hizo la request pueda saber a que pedido corresponde la respuesta.
40
+
41
+ Ejemplo de request:
42
+
43
+ ```json
44
+ {
45
+ "correlation_id": "9b9cfd23-8cc4-4ec3-a6e8-6d83f8f73b45",
46
+ "patient_id": 123,
47
+ "appointment_id": 987
48
+ }
49
+ ```
50
+
51
+ ## Grafico del flujo
52
+
53
+ ```mermaid
54
+ sequenceDiagram
55
+ participant A as Appointments
56
+ participant Core as Core API
57
+ participant Rabbit as RabbitMQ
58
+ participant B as Billing
59
+
60
+ A->>Core: Crea cola appointments.responses
61
+ A->>Core: Crea evento de response
62
+ B->>Core: Crea cola billing.requests
63
+ B->>Core: Crea evento de request
64
+ A->>B: Comparte response_event_id
65
+ B->>A: Comparte request_event_id
66
+ A->>Core: POST /events/log request + correlation_id + response_event_id
67
+ Core->>Rabbit: Publica request en health_grid_exchange
68
+ Rabbit->>B: Entrega mensaje en billing.requests
69
+ B->>B: Procesa request
70
+ B->>Core: POST /events/log response + mismo correlation_id
71
+ Core->>Rabbit: Publica response
72
+ Rabbit->>A: Entrega mensaje en appointments.responses
73
+ A->>A: Relaciona response usando correlation_id
74
+ ```
75
+
76
+ ## 1. Configurar cliente RabbitMQ ₍ ᐒ.Λ¬.α’β‚Ž
77
+
78
+ Cada microservicio recibe credenciales RabbitMQ con permisos limitados.
79
+
80
+ Ejemplo:
81
+
82
+ ```text
83
+ RABBITMQ_HOST=localhost
84
+ RABBITMQ_PORT=5672
85
+ RABBITMQ_USER=admin@admin.com
86
+ RABBITMQ_PASSWORD=123123
87
+ RABBITMQ_VHOST=/
88
+ ```
89
+
90
+ Si arman una URL AMQP, el `@` del email tiene que ir escapado como `%40`:
91
+
92
+ ```text
93
+ amqp://admin%40admin.com:123123@localhost:5672/
94
+ ```
95
+
96
+ El microservicio usa RabbitMQ solo para escuchar sus colas.
97
+
98
+ ## 2. Login en el Core
99
+
100
+ Todos los endpoints del Core usan JWT.
101
+
102
+ Primero obtener token:
103
+
104
+ ```http
105
+ POST /auth/login
106
+ Content-Type: application/json
107
+
108
+ {
109
+ "email": "user@mail.com",
110
+ "password": "1234"
111
+ }
112
+ ```
113
+
114
+ Usar el token devuelto:
115
+
116
+ ```http
117
+ Authorization: Bearer <token>
118
+ ```
119
+
120
+ ## 3. Crear colas desde el Core
121
+
122
+ Endpoint:
123
+
124
+ ```http
125
+ POST /rabbit/queues
126
+ Authorization: Bearer <token>
127
+ Content-Type: application/json
128
+ ```
129
+
130
+ El Core agrega automaticamente el sufijo:
131
+
132
+ - `requests` crea `<queue_name>.requests`
133
+ - `responses` crea `<queue_name>.responses`
134
+
135
+ Tambien crea la DLQ:
136
+
137
+ - `<queue_name>.requests.dlq`
138
+ - `<queue_name>.responses.dlq`
139
+
140
+ ### Si el microservicio recibe requests
141
+
142
+ Crear una cola de requests:
143
+
144
+ ```json
145
+ {
146
+ "queue_name": "billing",
147
+ "queue_type": "requests"
148
+ }
149
+ ```
150
+
151
+ Resultado:
152
+
153
+ ```json
154
+ {
155
+ "queue_name": "billing.requests",
156
+ "queue_type": "requests",
157
+ "dlq_name": "billing.requests.dlq",
158
+ "rabbit_username": "user@mail.com"
159
+ }
160
+ ```
161
+
162
+ ### Si el microservicio espera responses
163
+
164
+ Crear una cola de responses:
165
+
166
+ ```json
167
+ {
168
+ "queue_name": "appointments",
169
+ "queue_type": "responses"
170
+ }
171
+ ```
172
+
173
+ Resultado:
174
+
175
+ ```json
176
+ {
177
+ "queue_name": "appointments.responses",
178
+ "queue_type": "responses",
179
+ "dlq_name": "appointments.responses.dlq",
180
+ "rabbit_username": "user@mail.com"
181
+ }
182
+ ```
183
+
184
+ ## 4. Crear eventos desde el Core
185
+
186
+ Endpoint:
187
+
188
+ ```http
189
+ POST /events/types
190
+ Authorization: Bearer <token>
191
+ Content-Type: application/json
192
+ ```
193
+
194
+ ### Evento para requests
195
+
196
+ Crear este evento si otros microservicios tienen que mandarle requests a tu servicio.
197
+
198
+ Este evento lo crea el microservicio que recibe la request.
199
+
200
+ Ejemplo: `billing` recibe pedidos para crear facturas, entonces `billing` crea:
201
+
202
+ ```json
203
+ {
204
+ "name": "billing.invoice.create.requested",
205
+ "description": "Request para que billing cree una factura",
206
+ "source_module": "billing"
207
+ }
208
+ ```
209
+
210
+ Guardar el `id` devuelto. Ese es el `event_type_id` que otros microservicios usaran para pedirle cosas a `billing`.
211
+
212
+ ### Evento para responses
213
+
214
+ Crear este evento si tu servicio hizo una request y necesita recibir una response.
215
+
216
+ Ejemplo: `appointments` le pide a `billing` que cree una factura y quiere recibir respuesta. Entonces `appointments` crea:
217
+
218
+ ```json
219
+ {
220
+ "name": "billing.invoice.create.responded",
221
+ "description": "Response de billing para la creacion de factura",
222
+ "source_module": "appointments"
223
+ }
224
+ ```
225
+
226
+ Guardar el `id` devuelto. Ese ID se comparte con `billing` y tambien viaja en la request como `response_event_id`.
227
+
228
+ Mini resumen:
229
+
230
+ ```text
231
+ Recibo requests: creo el evento request.
232
+ Espero responses: creo el evento response.
233
+ Proceso requests: NO creo el evento response; uso el response_event_id recibido.
234
+ ```
235
+
236
+ ## 5. Vincular eventos con colas
237
+
238
+ Endpoint:
239
+
240
+ ```http
241
+ POST /rabbit/bindings
242
+ Authorization: Bearer <token>
243
+ Content-Type: application/json
244
+ ```
245
+
246
+ ### Bind de requests
247
+
248
+ Si `billing` recibe requests, bindear el evento request con la cola `billing.requests`:
249
+
250
+ ```json
251
+ {
252
+ "event_id": 10,
253
+ "queue_name": "billing.requests"
254
+ }
255
+ ```
256
+
257
+ Desde ese momento, todo mensaje publicado al evento `10` llega a `billing.requests`.
258
+
259
+ ### Bind de responses
260
+
261
+ Si `appointments` espera responses, bindear el evento response con la cola `appointments.responses`:
262
+
263
+ ```json
264
+ {
265
+ "event_id": 11,
266
+ "queue_name": "appointments.responses"
267
+ }
268
+ ```
269
+
270
+ Desde ese momento, toda respuesta publicada al evento `11` llega a `appointments.responses`.
271
+
272
+ ## 6. Escuchar una cola
273
+
274
+ El microservicio escucha su cola directamente en RabbitMQ.
275
+
276
+ Ejemplo conceptual:
277
+
278
+ ```text
279
+ Conectar a RabbitMQ
280
+ Abrir canal
281
+ Consumir cola: appointments.responses
282
+ Por cada mensaje:
283
+ 1. Parsear mensaje externo del Core
284
+ 2. Parsear campo payload
285
+ 3. Leer correlation_id
286
+ 4. Procesar
287
+ 5. ACK
288
+ ```
289
+
290
+ El mensaje que llega por Rabbit tiene este formato externo:
291
+
292
+ ```json
293
+ {
294
+ "event_type_id": 11,
295
+ "event_type_name": "billing.invoice.create.responded",
296
+ "source_module": "appointments",
297
+ "publisher_module": "billing",
298
+ "log_id": 456,
299
+ "payload": "{\"correlation_id\":\"9b9cfd23-8cc4-4ec3-a6e8-6d83f8f73b45\",\"status\":\"created\",\"invoice_id\":321}",
300
+ "published_at": "2026-07-03T12:00:00Z"
301
+ }
302
+ ```
303
+
304
+ Ojo tecnico: `payload` llega como string. Primero parsean el mensaje externo y despues ese JSON interno.
305
+
306
+ ## 7. Definir payloads por evento
307
+
308
+ Cada evento necesita un contrato claro.
309
+
310
+ Ese contrato lo definen y lo comparten los equipos duenos del flujo.
311
+
312
+ ### Payload de request
313
+
314
+ Ejemplo para `billing.invoice.create.requested`:
315
+
316
+ ```json
317
+ {
318
+ "correlation_id": "9b9cfd23-8cc4-4ec3-a6e8-6d83f8f73b45",
319
+ "appointment_id": 987,
320
+ "patient_id": 123,
321
+ "amount": 15000,
322
+ "currency": "ARS",
323
+ "response_event_id": 11
324
+ }
325
+ ```
326
+
327
+ Campos recomendados:
328
+
329
+ - `correlation_id`: obligatorio si se espera respuesta.
330
+ - `response_event_id`: evento donde se publica la respuesta. Este ID lo define y lo comparte quien espera recibir la response.
331
+ - Datos de negocio necesarios para procesar la request.
332
+
333
+ ### Payload de response
334
+
335
+ El payload de response lo acuerdan los microservicios del flujo.
336
+
337
+ Regla practica:
338
+
339
+ - Quien espera la response crea el evento de response.
340
+ - Quien procesa la request publica esa response usando el `response_event_id` recibido.
341
+
342
+ Ejemplo para `billing.invoice.create.responded`:
343
+
344
+ ```json
345
+ {
346
+ "correlation_id": "9b9cfd23-8cc4-4ec3-a6e8-6d83f8f73b45",
347
+ "status": "created",
348
+ "invoice_id": 321,
349
+ "error": null
350
+ }
351
+ ```
352
+
353
+ Reglas:
354
+
355
+ - Usar el mismo `correlation_id` recibido en la request.
356
+ - Publicar al `event_type_id` recibido como `response_event_id`.
357
+ - Incluir `status`.
358
+ - Si falla, incluir informacion simple de error.
359
+
360
+ Ejemplo de error:
361
+
362
+ ```json
363
+ {
364
+ "correlation_id": "9b9cfd23-8cc4-4ec3-a6e8-6d83f8f73b45",
365
+ "status": "failed",
366
+ "invoice_id": null,
367
+ "error": {
368
+ "code": "INVALID_AMOUNT",
369
+ "message": "El monto debe ser mayor a cero"
370
+ }
371
+ }
372
+ ```
373
+
374
+ ## 8. Que comparte cada microservicio
375
+
376
+ ### Si tu microservicio recibe requests
377
+
378
+ Compartir con los demas equipos:
379
+
380
+ - ID del evento de request.
381
+ - Nombre del evento de request.
382
+ - Payload que tienen que enviarte.
383
+ - Payload de response.
384
+
385
+ No tenes que crear ni compartir el evento de response.
386
+
387
+ Ese evento lo crea quien hizo la request y espera recibir la respuesta.
388
+
389
+ Si tu microservicio va a responder, lee el `response_event_id` del payload de la request (o solicitalo al microservicio emisor) y publica ahi la response.
390
+
391
+ Ejemplo:
392
+
393
+ ```text
394
+ Microservicio: billing
395
+ Request event id: 10
396
+ Request event name: billing.invoice.create.requested
397
+ Request payload: ver contrato billing.invoice.create.requested
398
+ ```
399
+
400
+ ### Si tu microservicio espera responses
401
+
402
+ Compartir con el servicio que va a responder:
403
+
404
+ - ID del evento de responses.
405
+ - Nombre del evento de responses.
406
+
407
+ Este ID tambien viaja en la request como `response_event_id`.
408
+
409
+ Ejemplo:
410
+
411
+ ```text
412
+ Microservicio: appointments
413
+ Response event id: 11
414
+ Response event name: billing.invoice.create.responded
415
+ Response queue: appointments.responses
416
+ Response payload: ver contrato billing.invoice.create.responded
417
+ ```
418
+
419
+ Resumen mini:
420
+
421
+ ```text
422
+ Recibo requests: comparto mi event_id.
423
+ Espero responses: comparto mi event_id.
424
+ Proceso requests: respondo al response_event_id que me mandaron.
425
+ ```
426
+
427
+ ## 9. Publicar mensajes al Core
428
+
429
+ Los microservicios publican llamando al Core.
430
+
431
+ Endpoint:
432
+
433
+ ```http
434
+ POST /events/log
435
+ Authorization: Bearer <token>
436
+ Content-Type: application/json
437
+ ```
438
+
439
+ Body base:
440
+
441
+ ```json
442
+ {
443
+ "event_type_id": 10,
444
+ "publisher_module": "appointments",
445
+ "payload": "{\"correlation_id\":\"9b9cfd23-8cc4-4ec3-a6e8-6d83f8f73b45\"}"
446
+ }
447
+ ```
448
+
449
+ Ojo tecnico: `payload` va como string.
450
+
451
+ ### Publicar una request
452
+
453
+ La request incluye el `response_event_id` si se espera respuesta.
454
+
455
+ Ese `response_event_id` lo creo el microservicio solicitante.
456
+
457
+ ```json
458
+ {
459
+ "event_type_id": 10,
460
+ "publisher_module": "appointments",
461
+ "payload": "{\"correlation_id\":\"9b9cfd23-8cc4-4ec3-a6e8-6d83f8f73b45\",\"appointment_id\":987,\"patient_id\":123,\"amount\":15000,\"currency\":\"ARS\",\"response_event_id\":11}"
462
+ }
463
+ ```
464
+
465
+ Si el evento `10` esta bindeado a `billing.requests`, `billing` recibe la request.
466
+
467
+ ### Publicar una response
468
+
469
+ La response se publica al `event_type_id` que llego como `response_event_id` en la request.
470
+
471
+ El `correlation_id` tiene que ser el mismo.
472
+
473
+ ```json
474
+ {
475
+ "event_type_id": 11,
476
+ "publisher_module": "billing",
477
+ "payload": "{\"correlation_id\":\"9b9cfd23-8cc4-4ec3-a6e8-6d83f8f73b45\",\"status\":\"created\",\"invoice_id\":321,\"error\":null}"
478
+ }
479
+ ```
480
+
481
+ Si el evento `11` esta bindeado a `appointments.responses`, `appointments` recibe la response.
482
+
483
+ ## 10. Checklist rapido
484
+
485
+ Para recibir requests:
486
+
487
+ - Tener credenciales RabbitMQ.
488
+ - Crear cola `<servicio>.requests`.
489
+ - Crear evento de request.
490
+ - Bindear evento de request con `<servicio>.requests`.
491
+ - Escuchar `<servicio>.requests`.
492
+ - Compartir request event id, payload esperado y payload de respuesta si corresponde.
493
+
494
+ Para esperar responses:
495
+
496
+ - Tener credenciales RabbitMQ.
497
+ - Crear cola `<servicio>.responses`.
498
+ - Crear evento de response.
499
+ - Bindear evento de response con `<servicio>.responses`.
500
+ - Escuchar `<servicio>.responses`.
501
+ - Compartir `response_event_id` con el servicio que va a responder.
502
+ - Enviar ese ID en la request como `response_event_id`.
503
+
504
+ Para publicar:
505
+
506
+ - Generar `correlation_id` si se espera respuesta (random UUID).
507
+ - Armar payload segun contrato del evento.
508
+ - Enviar `POST /events/log` al Core.
509
+
510
+ ## 11. Errores comunes ༼;´༎ຢ ۝ ༎ຢ༽
511
+
512
+ ### No llega ningun mensaje
513
+
514
+ Checklist rapido para debuggear:
515
+
516
+ - La cola existe.
517
+ - El evento existe.
518
+ - El evento esta bindeado a la cola correcta.
519
+ - El microservicio escucha la cola con el sufijo correcto.
520
+ - El mensaje se publico con el `event_type_id` correcto.
521
+
522
+ ### El responder publico a un evento incorrecto
523
+
524
+ Checklist rapido para debuggear:
525
+
526
+ - La request incluia `response_event_id`.
527
+ - El responder publico la response usando ese `response_event_id`.
528
+ - El evento de response fue creado y bindeado por quien espera la response.
529
+
530
+ ### No se puede relacionar una response con una request
531
+
532
+ Checklist rapido para debuggear:
533
+
534
+ - La request tenia `correlation_id`.
535
+ - La response copio exactamente el mismo `correlation_id`.
536
+
537
+ ### El payload llega como texto
538
+
539
+ Esto es normal: el mensaje externo trae `payload` como string.
540
+
541
+ Primero parseen el mensaje externo y despues parseen `payload`.
542
+
543
+ ## 12. Resumen final: que tiene que hacer cada uno (❀ˆᴗˆ)(β€’Μα΄—β€’Μ€βœΏ)
544
+
545
+ Si tu microservicio recibe requests:
546
+
547
+ - Pedir credenciales RabbitMQ al equipo del Core.
548
+ - Crear desde el Core una cola tipo `requests`, por ejemplo `billing.requests`.
549
+ - Crear desde el Core el evento de request, por ejemplo `billing.invoice.create.requested`.
550
+ - Vincular ese evento con tu cola `requests`.
551
+ - Escuchar tu cola en RabbitMQ con las credenciales recibidas.
552
+ - Definir y compartir el payload que esperas recibir y que pretendes devolver.
553
+ - Compartir con los demas equipos el `request_event_id`.
554
+ - Si vas a responder, leer de la request el `response_event_id` y publicar la response ahi.
555
+
556
+ Si tu microservicio hace requests y espera responses:
557
+
558
+ - Pedir credenciales RabbitMQ al equipo del Core.
559
+ - Crear desde el Core una cola tipo `responses`, por ejemplo `appointments.responses`.
560
+ - Crear desde el Core el evento de response, por ejemplo `billing.invoice.create.responded`.
561
+ - Vincular ese evento con tu cola `responses`.
562
+ - Escuchar tu cola de responses en RabbitMQ.
563
+ - Compartir el `response_event_id` con el microservicio que va a responder.
564
+ - Enviar en la request un `correlation_id` y el `response_event_id`.
565
+ - Cuando llegue la response, matchearla usando el mismo `correlation_id`.
566
+
567
+ Para publicar mensajes:
568
+
569
+ - Usar `POST /events/log` del Core.
570
+ - Mandar el `event_type_id` correcto.
571
+ - Enviar `payload` como string JSON.
572
+ - Incluir `correlation_id` si despues necesitas reconocer la response.
573
+
documentation/M10_openapi.yaml ADDED
@@ -0,0 +1,3075 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ basePath: /
2
+ definitions:
3
+ models.AdminCreateUserRequest:
4
+ properties:
5
+ email:
6
+ type: string
7
+ first_name:
8
+ type: string
9
+ last_name:
10
+ type: string
11
+ role_id:
12
+ minimum: 1
13
+ type: integer
14
+ required:
15
+ - email
16
+ - first_name
17
+ - last_name
18
+ - role_id
19
+ type: object
20
+ models.AssignLocationRequest:
21
+ properties:
22
+ location_id:
23
+ example: 1
24
+ type: integer
25
+ required:
26
+ - location_id
27
+ type: object
28
+ models.AssignPermissionToRoleRequest:
29
+ properties:
30
+ permission_id:
31
+ type: integer
32
+ required:
33
+ - permission_id
34
+ type: object
35
+ models.AssignRoleRequest:
36
+ properties:
37
+ role_id:
38
+ example: 1
39
+ type: integer
40
+ required:
41
+ - role_id
42
+ type: object
43
+ models.AssignSpecialityRequest:
44
+ properties:
45
+ speciality_id:
46
+ example: 1
47
+ type: integer
48
+ required:
49
+ - speciality_id
50
+ type: object
51
+ models.AuthResponse:
52
+ properties:
53
+ token:
54
+ type: string
55
+ user:
56
+ $ref: '#/definitions/models.User'
57
+ type: object
58
+ models.BindRabbitQueueRequest:
59
+ properties:
60
+ event_id:
61
+ example: 1
62
+ type: integer
63
+ queue_name:
64
+ example: billing.requests
65
+ type: string
66
+ required:
67
+ - event_id
68
+ - queue_name
69
+ type: object
70
+ models.ChangePasswordRequest:
71
+ properties:
72
+ current_password:
73
+ type: string
74
+ new_password:
75
+ minLength: 6
76
+ type: string
77
+ required:
78
+ - current_password
79
+ - new_password
80
+ type: object
81
+ models.CreateEventLogRequest:
82
+ properties:
83
+ event_type_id:
84
+ type: integer
85
+ payload:
86
+ type: string
87
+ publisher_module:
88
+ type: string
89
+ required:
90
+ - event_type_id
91
+ - publisher_module
92
+ type: object
93
+ models.CreateEventSubscriptionRequest:
94
+ properties:
95
+ endpoint_url:
96
+ type: string
97
+ event_type_id:
98
+ type: integer
99
+ subscriber_module:
100
+ type: string
101
+ required:
102
+ - endpoint_url
103
+ - event_type_id
104
+ - subscriber_module
105
+ type: object
106
+ models.CreateEventTypeRequest:
107
+ properties:
108
+ description:
109
+ type: string
110
+ name:
111
+ type: string
112
+ source_module:
113
+ type: string
114
+ required:
115
+ - name
116
+ - source_module
117
+ type: object
118
+ models.CreateLocationRequest:
119
+ properties:
120
+ address:
121
+ type: string
122
+ city:
123
+ type: string
124
+ country:
125
+ type: string
126
+ name:
127
+ type: string
128
+ required:
129
+ - address
130
+ - city
131
+ - country
132
+ - name
133
+ type: object
134
+ models.CreatePermissionRequest:
135
+ properties:
136
+ name:
137
+ type: string
138
+ required:
139
+ - name
140
+ type: object
141
+ models.CreateRabbitQueueRequest:
142
+ properties:
143
+ queue_name:
144
+ example: billing
145
+ type: string
146
+ queue_type:
147
+ enum:
148
+ - requests
149
+ - responses
150
+ example: requests
151
+ type: string
152
+ required:
153
+ - queue_name
154
+ - queue_type
155
+ type: object
156
+ models.CreateRoleRequest:
157
+ properties:
158
+ name:
159
+ type: string
160
+ required:
161
+ - name
162
+ type: object
163
+ models.CreateSpecialityRequest:
164
+ properties:
165
+ name:
166
+ type: string
167
+ required:
168
+ - name
169
+ type: object
170
+ models.CreateUserRequest:
171
+ properties:
172
+ email:
173
+ type: string
174
+ first_name:
175
+ type: string
176
+ last_name:
177
+ type: string
178
+ password:
179
+ minLength: 6
180
+ type: string
181
+ required:
182
+ - email
183
+ - first_name
184
+ - last_name
185
+ - password
186
+ type: object
187
+ models.ErrorResponse:
188
+ properties:
189
+ error:
190
+ type: string
191
+ type: object
192
+ models.EventLog:
193
+ properties:
194
+ created_at:
195
+ type: string
196
+ event_type:
197
+ $ref: '#/definitions/models.EventType'
198
+ event_type_id:
199
+ type: integer
200
+ id:
201
+ type: integer
202
+ payload:
203
+ type: string
204
+ publisher_module:
205
+ type: string
206
+ status:
207
+ description: pending, delivered, failed
208
+ type: string
209
+ type: object
210
+ models.EventLogListResponse:
211
+ properties:
212
+ data:
213
+ items:
214
+ $ref: '#/definitions/models.EventLog'
215
+ type: array
216
+ pagination:
217
+ $ref: '#/definitions/models.Pagination'
218
+ total:
219
+ type: integer
220
+ type: object
221
+ models.EventSubscription:
222
+ properties:
223
+ created_at:
224
+ type: string
225
+ deleted_at:
226
+ type: string
227
+ endpoint_url:
228
+ type: string
229
+ event_type:
230
+ $ref: '#/definitions/models.EventType'
231
+ event_type_id:
232
+ type: integer
233
+ id:
234
+ type: integer
235
+ is_active:
236
+ type: boolean
237
+ subscriber_module:
238
+ type: string
239
+ type: object
240
+ models.EventSubscriptionListResponse:
241
+ properties:
242
+ data:
243
+ items:
244
+ $ref: '#/definitions/models.EventSubscription'
245
+ type: array
246
+ pagination:
247
+ $ref: '#/definitions/models.Pagination'
248
+ total:
249
+ type: integer
250
+ type: object
251
+ models.EventType:
252
+ properties:
253
+ created_at:
254
+ type: string
255
+ deleted_at:
256
+ type: string
257
+ description:
258
+ type: string
259
+ id:
260
+ type: integer
261
+ name:
262
+ type: string
263
+ source_module:
264
+ type: string
265
+ type: object
266
+ models.EventTypeListResponse:
267
+ properties:
268
+ data:
269
+ items:
270
+ $ref: '#/definitions/models.EventType'
271
+ type: array
272
+ pagination:
273
+ $ref: '#/definitions/models.Pagination'
274
+ total:
275
+ type: integer
276
+ type: object
277
+ models.ForgotPasswordRequest:
278
+ properties:
279
+ email:
280
+ type: string
281
+ required:
282
+ - email
283
+ type: object
284
+ models.JWK:
285
+ properties:
286
+ alg:
287
+ type: string
288
+ e:
289
+ type: string
290
+ kid:
291
+ type: string
292
+ kty:
293
+ type: string
294
+ "n":
295
+ type: string
296
+ use:
297
+ type: string
298
+ type: object
299
+ models.JWKS:
300
+ properties:
301
+ keys:
302
+ items:
303
+ $ref: '#/definitions/models.JWK'
304
+ type: array
305
+ type: object
306
+ models.Location:
307
+ properties:
308
+ address:
309
+ type: string
310
+ city:
311
+ type: string
312
+ country:
313
+ type: string
314
+ created_at:
315
+ type: string
316
+ deleted_at:
317
+ type: string
318
+ id:
319
+ type: integer
320
+ name:
321
+ type: string
322
+ type: object
323
+ models.LocationListResponse:
324
+ properties:
325
+ data:
326
+ items:
327
+ $ref: '#/definitions/models.Location'
328
+ type: array
329
+ pagination:
330
+ $ref: '#/definitions/models.Pagination'
331
+ total:
332
+ type: integer
333
+ type: object
334
+ models.LoginRequest:
335
+ properties:
336
+ email:
337
+ type: string
338
+ password:
339
+ type: string
340
+ required:
341
+ - email
342
+ - password
343
+ type: object
344
+ models.MessageResponse:
345
+ properties:
346
+ message:
347
+ type: string
348
+ type: object
349
+ models.Pagination:
350
+ properties:
351
+ page:
352
+ type: integer
353
+ pageSize:
354
+ type: integer
355
+ type: object
356
+ models.Permission:
357
+ properties:
358
+ deleted_at:
359
+ type: string
360
+ id:
361
+ type: integer
362
+ name:
363
+ type: string
364
+ roles:
365
+ items:
366
+ $ref: '#/definitions/models.Role'
367
+ type: array
368
+ type: object
369
+ models.PermissionListResponse:
370
+ properties:
371
+ data:
372
+ items:
373
+ $ref: '#/definitions/models.Permission'
374
+ type: array
375
+ pagination:
376
+ $ref: '#/definitions/models.Pagination'
377
+ total:
378
+ type: integer
379
+ type: object
380
+ models.RabbitQueueBindingResponse:
381
+ properties:
382
+ event_id:
383
+ type: integer
384
+ exchange:
385
+ type: string
386
+ queue_name:
387
+ type: string
388
+ rabbit_username:
389
+ type: string
390
+ routing_key:
391
+ type: string
392
+ type: object
393
+ models.RabbitQueueResponse:
394
+ properties:
395
+ dlq_name:
396
+ type: string
397
+ queue_name:
398
+ type: string
399
+ queue_type:
400
+ type: string
401
+ rabbit_username:
402
+ type: string
403
+ type: object
404
+ models.ResetPasswordRequest:
405
+ properties:
406
+ code:
407
+ type: string
408
+ email:
409
+ type: string
410
+ new_password:
411
+ minLength: 6
412
+ type: string
413
+ required:
414
+ - code
415
+ - email
416
+ - new_password
417
+ type: object
418
+ models.Role:
419
+ properties:
420
+ deleted_at:
421
+ type: string
422
+ id:
423
+ type: integer
424
+ name:
425
+ type: string
426
+ permissions:
427
+ items:
428
+ $ref: '#/definitions/models.Permission'
429
+ type: array
430
+ users:
431
+ items:
432
+ $ref: '#/definitions/models.User'
433
+ type: array
434
+ type: object
435
+ models.RoleListResponse:
436
+ properties:
437
+ data:
438
+ items:
439
+ $ref: '#/definitions/models.Role'
440
+ type: array
441
+ pagination:
442
+ $ref: '#/definitions/models.Pagination'
443
+ total:
444
+ type: integer
445
+ type: object
446
+ models.SSOExchangeRequest:
447
+ properties:
448
+ ticket:
449
+ type: string
450
+ required:
451
+ - ticket
452
+ type: object
453
+ models.SSOTicketResponse:
454
+ properties:
455
+ expires_in:
456
+ type: integer
457
+ ticket:
458
+ type: string
459
+ type: object
460
+ models.Speciality:
461
+ properties:
462
+ deleted_at:
463
+ type: string
464
+ id:
465
+ type: integer
466
+ name:
467
+ type: string
468
+ type: object
469
+ models.SpecialityListResponse:
470
+ properties:
471
+ data:
472
+ items:
473
+ $ref: '#/definitions/models.Speciality'
474
+ type: array
475
+ pagination:
476
+ $ref: '#/definitions/models.Pagination'
477
+ total:
478
+ type: integer
479
+ type: object
480
+ models.UpdateEventLogStatusRequest:
481
+ properties:
482
+ status:
483
+ description: 'Status must be one of: pending, delivered, failed'
484
+ enum:
485
+ - pending
486
+ - delivered
487
+ - failed
488
+ example: delivered
489
+ type: string
490
+ required:
491
+ - status
492
+ type: object
493
+ models.UpdateEventSubscriptionRequest:
494
+ properties:
495
+ endpoint_url:
496
+ type: string
497
+ is_active:
498
+ type: boolean
499
+ type: object
500
+ models.UpdateEventTypeRequest:
501
+ properties:
502
+ description:
503
+ type: string
504
+ name:
505
+ type: string
506
+ source_module:
507
+ type: string
508
+ type: object
509
+ models.UpdateLocationRequest:
510
+ properties:
511
+ address:
512
+ type: string
513
+ city:
514
+ type: string
515
+ country:
516
+ type: string
517
+ name:
518
+ type: string
519
+ type: object
520
+ models.UpdatePermissionRequest:
521
+ properties:
522
+ name:
523
+ type: string
524
+ type: object
525
+ models.UpdateRoleRequest:
526
+ properties:
527
+ name:
528
+ type: string
529
+ type: object
530
+ models.UpdateSpecialityRequest:
531
+ properties:
532
+ name:
533
+ type: string
534
+ type: object
535
+ models.UpdateUserRequest:
536
+ properties:
537
+ email:
538
+ type: string
539
+ first_name:
540
+ type: string
541
+ last_name:
542
+ type: string
543
+ type: object
544
+ models.User:
545
+ properties:
546
+ created_at:
547
+ type: string
548
+ deleted_at:
549
+ type: string
550
+ email:
551
+ type: string
552
+ first_name:
553
+ type: string
554
+ has_credentials:
555
+ type: boolean
556
+ id:
557
+ type: integer
558
+ last_name:
559
+ type: string
560
+ locations:
561
+ items:
562
+ $ref: '#/definitions/models.Location'
563
+ type: array
564
+ roles:
565
+ items:
566
+ $ref: '#/definitions/models.Role'
567
+ type: array
568
+ specialities:
569
+ items:
570
+ $ref: '#/definitions/models.Speciality'
571
+ type: array
572
+ updated_at:
573
+ type: string
574
+ type: object
575
+ models.UserListResponse:
576
+ properties:
577
+ data:
578
+ items:
579
+ $ref: '#/definitions/models.User'
580
+ type: array
581
+ pagination:
582
+ $ref: '#/definitions/models.Pagination'
583
+ total:
584
+ type: integer
585
+ type: object
586
+ models.ValidateTokenResponse:
587
+ properties:
588
+ user_id:
589
+ type: integer
590
+ valid:
591
+ type: boolean
592
+ type: object
593
+ models.VerifyAccountRequest:
594
+ properties:
595
+ password:
596
+ minLength: 6
597
+ type: string
598
+ token:
599
+ type: string
600
+ required:
601
+ - password
602
+ - token
603
+ type: object
604
+ host: api.healthcare.cantero.ar
605
+ info:
606
+ contact: {}
607
+ description: API principal del sistema. Gestiona autenticaciΓ³n, usuarios, roles,
608
+ permisos, especialidades, locaciones y eventos.
609
+ title: Core API
610
+ version: 1.0.0
611
+ paths:
612
+ /.well-known/jwks.json:
613
+ get:
614
+ description: Returns the JSON Web Key Set (JWKS) for verifying JWT signatures
615
+ issued by this service. Used by other services to validate tokens without
616
+ contacting this API.
617
+ produces:
618
+ - application/json
619
+ responses:
620
+ "200":
621
+ description: OK
622
+ schema:
623
+ $ref: '#/definitions/models.JWKS'
624
+ "500":
625
+ description: Internal Server Error
626
+ schema:
627
+ $ref: '#/definitions/models.ErrorResponse'
628
+ summary: JWKS
629
+ tags:
630
+ - Auth
631
+ /auth/forgot-password:
632
+ post:
633
+ consumes:
634
+ - application/json
635
+ description: Sends a one-time password reset code to the user's email address.
636
+ parameters:
637
+ - description: Email address
638
+ in: body
639
+ name: body
640
+ required: true
641
+ schema:
642
+ $ref: '#/definitions/models.ForgotPasswordRequest'
643
+ produces:
644
+ - application/json
645
+ responses:
646
+ "200":
647
+ description: Reset code sent to email
648
+ schema:
649
+ $ref: '#/definitions/models.MessageResponse'
650
+ "400":
651
+ description: Invalid email format
652
+ schema:
653
+ $ref: '#/definitions/models.ErrorResponse'
654
+ "404":
655
+ description: No user found with that email
656
+ schema:
657
+ $ref: '#/definitions/models.ErrorResponse'
658
+ summary: Request password reset
659
+ tags:
660
+ - Auth
661
+ /auth/login:
662
+ post:
663
+ consumes:
664
+ - application/json
665
+ description: Authenticates a user with email and password. Returns a JWT token
666
+ and user data.
667
+ parameters:
668
+ - description: Login credentials
669
+ in: body
670
+ name: body
671
+ required: true
672
+ schema:
673
+ $ref: '#/definitions/models.LoginRequest'
674
+ produces:
675
+ - application/json
676
+ responses:
677
+ "200":
678
+ description: OK
679
+ schema:
680
+ $ref: '#/definitions/models.AuthResponse'
681
+ "400":
682
+ description: Invalid request body
683
+ schema:
684
+ $ref: '#/definitions/models.ErrorResponse'
685
+ "401":
686
+ description: Invalid credentials
687
+ schema:
688
+ $ref: '#/definitions/models.ErrorResponse'
689
+ summary: Login
690
+ tags:
691
+ - Auth
692
+ /auth/logout:
693
+ post:
694
+ description: Invalidates the current JWT token. Requires a valid Bearer token
695
+ in the Authorization header.
696
+ produces:
697
+ - application/json
698
+ responses:
699
+ "200":
700
+ description: OK
701
+ schema:
702
+ $ref: '#/definitions/models.MessageResponse'
703
+ "400":
704
+ description: Missing or malformed Authorization header
705
+ schema:
706
+ $ref: '#/definitions/models.ErrorResponse'
707
+ "401":
708
+ description: Invalid or expired token
709
+ schema:
710
+ $ref: '#/definitions/models.ErrorResponse'
711
+ "500":
712
+ description: Internal Server Error
713
+ schema:
714
+ $ref: '#/definitions/models.ErrorResponse'
715
+ security:
716
+ - Bearer: []
717
+ summary: Logout
718
+ tags:
719
+ - Auth
720
+ /auth/refresh:
721
+ post:
722
+ description: Issues a new JWT token using the current (still valid) token. Requires
723
+ a valid Bearer token in the Authorization header.
724
+ produces:
725
+ - application/json
726
+ responses:
727
+ "200":
728
+ description: OK
729
+ schema:
730
+ $ref: '#/definitions/models.AuthResponse'
731
+ "400":
732
+ description: Missing or malformed Authorization header
733
+ schema:
734
+ $ref: '#/definitions/models.ErrorResponse'
735
+ "401":
736
+ description: Invalid or expired token
737
+ schema:
738
+ $ref: '#/definitions/models.ErrorResponse'
739
+ security:
740
+ - Bearer: []
741
+ summary: Refresh token
742
+ tags:
743
+ - Auth
744
+ /auth/register:
745
+ post:
746
+ consumes:
747
+ - application/json
748
+ description: Creates a new user account with email and password. Returns a JWT
749
+ token and user data.
750
+ parameters:
751
+ - description: Registration data
752
+ in: body
753
+ name: body
754
+ required: true
755
+ schema:
756
+ $ref: '#/definitions/models.CreateUserRequest'
757
+ produces:
758
+ - application/json
759
+ responses:
760
+ "201":
761
+ description: Created
762
+ schema:
763
+ $ref: '#/definitions/models.AuthResponse'
764
+ "400":
765
+ description: Invalid request or email already exists
766
+ schema:
767
+ $ref: '#/definitions/models.ErrorResponse'
768
+ summary: Register
769
+ tags:
770
+ - Auth
771
+ /auth/reset-password:
772
+ post:
773
+ consumes:
774
+ - application/json
775
+ description: Resets the user's password using the code sent via email. The code
776
+ expires after a limited time.
777
+ parameters:
778
+ - description: Reset data (email, code, new password)
779
+ in: body
780
+ name: body
781
+ required: true
782
+ schema:
783
+ $ref: '#/definitions/models.ResetPasswordRequest'
784
+ produces:
785
+ - application/json
786
+ responses:
787
+ "200":
788
+ description: Password changed successfully
789
+ schema:
790
+ $ref: '#/definitions/models.MessageResponse'
791
+ "400":
792
+ description: Invalid or expired code, or password does not meet requirements
793
+ schema:
794
+ $ref: '#/definitions/models.ErrorResponse'
795
+ "404":
796
+ description: No user found with that email
797
+ schema:
798
+ $ref: '#/definitions/models.ErrorResponse'
799
+ summary: Reset password
800
+ tags:
801
+ - Auth
802
+ /auth/sso-exchange:
803
+ post:
804
+ consumes:
805
+ - application/json
806
+ description: Redeems a single-use SSO ticket for a fresh JWT and user data.
807
+ Called server-to-server by the destination module's backend after receiving
808
+ the ticket via redirect. The ticket is consumed on first use and cannot be
809
+ reused.
810
+ parameters:
811
+ - description: SSO ticket
812
+ in: body
813
+ name: body
814
+ required: true
815
+ schema:
816
+ $ref: '#/definitions/models.SSOExchangeRequest'
817
+ produces:
818
+ - application/json
819
+ responses:
820
+ "200":
821
+ description: OK
822
+ schema:
823
+ $ref: '#/definitions/models.AuthResponse'
824
+ "400":
825
+ description: Invalid request body
826
+ schema:
827
+ $ref: '#/definitions/models.ErrorResponse'
828
+ "401":
829
+ description: Invalid, used or expired ticket
830
+ schema:
831
+ $ref: '#/definitions/models.ErrorResponse'
832
+ summary: Exchange SSO ticket
833
+ tags:
834
+ - Auth
835
+ /auth/sso-ticket:
836
+ post:
837
+ description: Issues a short-lived, single-use SSO ticket for the authenticated
838
+ user. The frontend redirects the browser to another module (on a different
839
+ domain) with this ticket, and that module's backend redeems it via /auth/sso-exchange
840
+ for a fresh JWT. The ticket expires in seconds and can be used only once.
841
+ produces:
842
+ - application/json
843
+ responses:
844
+ "200":
845
+ description: OK
846
+ schema:
847
+ $ref: '#/definitions/models.SSOTicketResponse'
848
+ "401":
849
+ description: Invalid or expired token
850
+ schema:
851
+ $ref: '#/definitions/models.ErrorResponse'
852
+ "500":
853
+ description: Internal Server Error
854
+ schema:
855
+ $ref: '#/definitions/models.ErrorResponse'
856
+ security:
857
+ - Bearer: []
858
+ summary: Create SSO ticket
859
+ tags:
860
+ - Auth
861
+ /auth/validate:
862
+ get:
863
+ description: Verifies whether a JWT token is valid and returns the associated
864
+ user ID. Requires a valid Bearer token in the Authorization header.
865
+ produces:
866
+ - application/json
867
+ responses:
868
+ "200":
869
+ description: OK
870
+ schema:
871
+ $ref: '#/definitions/models.ValidateTokenResponse'
872
+ "400":
873
+ description: Missing or malformed Authorization header
874
+ schema:
875
+ $ref: '#/definitions/models.ErrorResponse'
876
+ "401":
877
+ description: Invalid or expired token
878
+ schema:
879
+ $ref: '#/definitions/models.ErrorResponse'
880
+ security:
881
+ - Bearer: []
882
+ summary: Validate token
883
+ tags:
884
+ - Auth
885
+ /auth/verify-account:
886
+ post:
887
+ consumes:
888
+ - application/json
889
+ description: Activates an account created by an admin. The user sets their password
890
+ using the token received by email and receives a JWT token to start their
891
+ session immediately.
892
+ parameters:
893
+ - description: Verification token and chosen password
894
+ in: body
895
+ name: body
896
+ required: true
897
+ schema:
898
+ $ref: '#/definitions/models.VerifyAccountRequest'
899
+ produces:
900
+ - application/json
901
+ responses:
902
+ "200":
903
+ description: OK
904
+ schema:
905
+ $ref: '#/definitions/models.AuthResponse'
906
+ "400":
907
+ description: Token invalid, already used, or expired
908
+ schema:
909
+ $ref: '#/definitions/models.ErrorResponse'
910
+ "500":
911
+ description: Internal Server Error
912
+ schema:
913
+ $ref: '#/definitions/models.ErrorResponse'
914
+ summary: Verify account
915
+ tags:
916
+ - Auth
917
+ /events/log:
918
+ get:
919
+ description: 'Returns a paginated audit log of all published events. Optionally
920
+ filter by event_type_id or publisher_module. Requires permission: `events:log:read`'
921
+ parameters:
922
+ - default: 1
923
+ description: 'Page number (default: 1)'
924
+ in: query
925
+ minimum: 1
926
+ name: page
927
+ type: integer
928
+ - default: 10
929
+ description: 'Items per page (default: 10)'
930
+ in: query
931
+ minimum: 1
932
+ name: pageSize
933
+ type: integer
934
+ - description: Filter by event type ID
935
+ in: query
936
+ name: event_type_id
937
+ type: integer
938
+ - description: Filter by publisher module name
939
+ in: query
940
+ name: publisher_module
941
+ type: string
942
+ produces:
943
+ - application/json
944
+ responses:
945
+ "200":
946
+ description: OK
947
+ schema:
948
+ $ref: '#/definitions/models.EventLogListResponse'
949
+ "400":
950
+ description: Invalid pagination or filter parameters
951
+ schema:
952
+ $ref: '#/definitions/models.ErrorResponse'
953
+ "401":
954
+ description: Unauthenticated
955
+ schema:
956
+ $ref: '#/definitions/models.ErrorResponse'
957
+ "403":
958
+ description: 'Missing permission: events:log:read'
959
+ schema:
960
+ $ref: '#/definitions/models.ErrorResponse'
961
+ "500":
962
+ description: Internal Server Error
963
+ schema:
964
+ $ref: '#/definitions/models.ErrorResponse'
965
+ security:
966
+ - Bearer: []
967
+ summary: List event log
968
+ tags:
969
+ - Events
970
+ post:
971
+ consumes:
972
+ - application/json
973
+ description: 'Publishes an event to the bus. Creates an event log entry with
974
+ status `pending` and notifies all active subscribers. Requires permission:
975
+ `events:log:publish`'
976
+ parameters:
977
+ - description: Event data
978
+ in: body
979
+ name: body
980
+ required: true
981
+ schema:
982
+ $ref: '#/definitions/models.CreateEventLogRequest'
983
+ produces:
984
+ - application/json
985
+ responses:
986
+ "201":
987
+ description: Created
988
+ schema:
989
+ $ref: '#/definitions/models.EventLog'
990
+ "400":
991
+ description: Invalid request body
992
+ schema:
993
+ $ref: '#/definitions/models.ErrorResponse'
994
+ "401":
995
+ description: Unauthenticated
996
+ schema:
997
+ $ref: '#/definitions/models.ErrorResponse'
998
+ "403":
999
+ description: 'Missing permission: events:log:publish'
1000
+ schema:
1001
+ $ref: '#/definitions/models.ErrorResponse'
1002
+ security:
1003
+ - Bearer: []
1004
+ summary: Publish event
1005
+ tags:
1006
+ - Events
1007
+ /events/log/{id}:
1008
+ get:
1009
+ description: 'Returns a single event log entry by ID. Requires permission: `events:log:read`'
1010
+ parameters:
1011
+ - description: Event log entry ID
1012
+ in: path
1013
+ name: id
1014
+ required: true
1015
+ type: integer
1016
+ produces:
1017
+ - application/json
1018
+ responses:
1019
+ "200":
1020
+ description: OK
1021
+ schema:
1022
+ $ref: '#/definitions/models.EventLog'
1023
+ "400":
1024
+ description: Invalid ID
1025
+ schema:
1026
+ $ref: '#/definitions/models.ErrorResponse'
1027
+ "401":
1028
+ description: Unauthenticated
1029
+ schema:
1030
+ $ref: '#/definitions/models.ErrorResponse'
1031
+ "403":
1032
+ description: 'Missing permission: events:log:read'
1033
+ schema:
1034
+ $ref: '#/definitions/models.ErrorResponse'
1035
+ "404":
1036
+ description: Event log entry not found
1037
+ schema:
1038
+ $ref: '#/definitions/models.ErrorResponse'
1039
+ "500":
1040
+ description: Internal Server Error
1041
+ schema:
1042
+ $ref: '#/definitions/models.ErrorResponse'
1043
+ security:
1044
+ - Bearer: []
1045
+ summary: Get event log entry
1046
+ tags:
1047
+ - Events
1048
+ /events/log/{id}/status:
1049
+ patch:
1050
+ consumes:
1051
+ - application/json
1052
+ description: 'Updates the delivery status of an event log entry. Used by subscribers
1053
+ to report whether the event was delivered successfully. Requires permission:
1054
+ `events:log:update-status`'
1055
+ parameters:
1056
+ - description: Event log entry ID
1057
+ in: path
1058
+ name: id
1059
+ required: true
1060
+ type: integer
1061
+ - description: New status
1062
+ in: body
1063
+ name: body
1064
+ required: true
1065
+ schema:
1066
+ $ref: '#/definitions/models.UpdateEventLogStatusRequest'
1067
+ produces:
1068
+ - application/json
1069
+ responses:
1070
+ "200":
1071
+ description: OK
1072
+ schema:
1073
+ $ref: '#/definitions/models.EventLog'
1074
+ "400":
1075
+ description: Invalid ID or status value
1076
+ schema:
1077
+ $ref: '#/definitions/models.ErrorResponse'
1078
+ "401":
1079
+ description: Unauthenticated
1080
+ schema:
1081
+ $ref: '#/definitions/models.ErrorResponse'
1082
+ "403":
1083
+ description: 'Missing permission: events:log:update-status'
1084
+ schema:
1085
+ $ref: '#/definitions/models.ErrorResponse'
1086
+ "404":
1087
+ description: Event log entry not found
1088
+ schema:
1089
+ $ref: '#/definitions/models.ErrorResponse'
1090
+ "500":
1091
+ description: Internal Server Error
1092
+ schema:
1093
+ $ref: '#/definitions/models.ErrorResponse'
1094
+ security:
1095
+ - Bearer: []
1096
+ summary: Update event delivery status
1097
+ tags:
1098
+ - Events
1099
+ /events/subscriptions:
1100
+ get:
1101
+ description: 'Returns a paginated list of event subscriptions. Optionally filter
1102
+ by event_type_id. Requires permission: `events:subscriptions:read`'
1103
+ parameters:
1104
+ - default: 1
1105
+ description: 'Page number (default: 1)'
1106
+ in: query
1107
+ minimum: 1
1108
+ name: page
1109
+ type: integer
1110
+ - default: 10
1111
+ description: 'Items per page (default: 10)'
1112
+ in: query
1113
+ minimum: 1
1114
+ name: pageSize
1115
+ type: integer
1116
+ - description: Filter by event type ID
1117
+ in: query
1118
+ name: event_type_id
1119
+ type: integer
1120
+ produces:
1121
+ - application/json
1122
+ responses:
1123
+ "200":
1124
+ description: OK
1125
+ schema:
1126
+ $ref: '#/definitions/models.EventSubscriptionListResponse'
1127
+ "400":
1128
+ description: Invalid pagination or filter parameters
1129
+ schema:
1130
+ $ref: '#/definitions/models.ErrorResponse'
1131
+ "401":
1132
+ description: Unauthenticated
1133
+ schema:
1134
+ $ref: '#/definitions/models.ErrorResponse'
1135
+ "403":
1136
+ description: 'Missing permission: events:subscriptions:read'
1137
+ schema:
1138
+ $ref: '#/definitions/models.ErrorResponse'
1139
+ "500":
1140
+ description: Internal Server Error
1141
+ schema:
1142
+ $ref: '#/definitions/models.ErrorResponse'
1143
+ security:
1144
+ - Bearer: []
1145
+ summary: List event subscriptions
1146
+ tags:
1147
+ - Events
1148
+ post:
1149
+ consumes:
1150
+ - application/json
1151
+ description: 'Subscribes a module to an event type. The API gateway uses this
1152
+ to route published events to the correct endpoint. Requires permission: `events:subscriptions:manage`'
1153
+ parameters:
1154
+ - description: Subscription data
1155
+ in: body
1156
+ name: body
1157
+ required: true
1158
+ schema:
1159
+ $ref: '#/definitions/models.CreateEventSubscriptionRequest'
1160
+ produces:
1161
+ - application/json
1162
+ responses:
1163
+ "201":
1164
+ description: Created
1165
+ schema:
1166
+ $ref: '#/definitions/models.EventSubscription'
1167
+ "400":
1168
+ description: Invalid request body
1169
+ schema:
1170
+ $ref: '#/definitions/models.ErrorResponse'
1171
+ "401":
1172
+ description: Unauthenticated
1173
+ schema:
1174
+ $ref: '#/definitions/models.ErrorResponse'
1175
+ "403":
1176
+ description: 'Missing permission: events:subscriptions:manage'
1177
+ schema:
1178
+ $ref: '#/definitions/models.ErrorResponse'
1179
+ security:
1180
+ - Bearer: []
1181
+ summary: Create event subscription
1182
+ tags:
1183
+ - Events
1184
+ /events/subscriptions/{id}:
1185
+ delete:
1186
+ description: 'Deletes an event subscription by ID. Requires permission: `events:subscriptions:manage`'
1187
+ parameters:
1188
+ - description: Subscription ID
1189
+ in: path
1190
+ name: id
1191
+ required: true
1192
+ type: integer
1193
+ produces:
1194
+ - application/json
1195
+ responses:
1196
+ "200":
1197
+ description: OK
1198
+ schema:
1199
+ $ref: '#/definitions/models.MessageResponse'
1200
+ "400":
1201
+ description: Invalid ID
1202
+ schema:
1203
+ $ref: '#/definitions/models.ErrorResponse'
1204
+ "401":
1205
+ description: Unauthenticated
1206
+ schema:
1207
+ $ref: '#/definitions/models.ErrorResponse'
1208
+ "403":
1209
+ description: 'Missing permission: events:subscriptions:manage'
1210
+ schema:
1211
+ $ref: '#/definitions/models.ErrorResponse'
1212
+ "500":
1213
+ description: Internal Server Error
1214
+ schema:
1215
+ $ref: '#/definitions/models.ErrorResponse'
1216
+ security:
1217
+ - Bearer: []
1218
+ summary: Delete event subscription
1219
+ tags:
1220
+ - Events
1221
+ get:
1222
+ description: 'Returns an event subscription by ID. Requires permission: `events:subscriptions:read`'
1223
+ parameters:
1224
+ - description: Subscription ID
1225
+ in: path
1226
+ name: id
1227
+ required: true
1228
+ type: integer
1229
+ produces:
1230
+ - application/json
1231
+ responses:
1232
+ "200":
1233
+ description: OK
1234
+ schema:
1235
+ $ref: '#/definitions/models.EventSubscription'
1236
+ "400":
1237
+ description: Invalid ID
1238
+ schema:
1239
+ $ref: '#/definitions/models.ErrorResponse'
1240
+ "401":
1241
+ description: Unauthenticated
1242
+ schema:
1243
+ $ref: '#/definitions/models.ErrorResponse'
1244
+ "403":
1245
+ description: 'Missing permission: events:subscriptions:read'
1246
+ schema:
1247
+ $ref: '#/definitions/models.ErrorResponse'
1248
+ "404":
1249
+ description: Subscription not found
1250
+ schema:
1251
+ $ref: '#/definitions/models.ErrorResponse'
1252
+ "500":
1253
+ description: Internal Server Error
1254
+ schema:
1255
+ $ref: '#/definitions/models.ErrorResponse'
1256
+ security:
1257
+ - Bearer: []
1258
+ summary: Get event subscription
1259
+ tags:
1260
+ - Events
1261
+ put:
1262
+ consumes:
1263
+ - application/json
1264
+ description: 'Updates a subscription''s endpoint URL or active status. All fields
1265
+ are optional. Requires permission: `events:subscriptions:manage`'
1266
+ parameters:
1267
+ - description: Subscription ID
1268
+ in: path
1269
+ name: id
1270
+ required: true
1271
+ type: integer
1272
+ - description: Fields to update (all optional)
1273
+ in: body
1274
+ name: body
1275
+ required: true
1276
+ schema:
1277
+ $ref: '#/definitions/models.UpdateEventSubscriptionRequest'
1278
+ produces:
1279
+ - application/json
1280
+ responses:
1281
+ "200":
1282
+ description: OK
1283
+ schema:
1284
+ $ref: '#/definitions/models.EventSubscription'
1285
+ "400":
1286
+ description: Invalid ID or request body
1287
+ schema:
1288
+ $ref: '#/definitions/models.ErrorResponse'
1289
+ "401":
1290
+ description: Unauthenticated
1291
+ schema:
1292
+ $ref: '#/definitions/models.ErrorResponse'
1293
+ "403":
1294
+ description: 'Missing permission: events:subscriptions:manage'
1295
+ schema:
1296
+ $ref: '#/definitions/models.ErrorResponse'
1297
+ "404":
1298
+ description: Subscription not found
1299
+ schema:
1300
+ $ref: '#/definitions/models.ErrorResponse'
1301
+ "500":
1302
+ description: Internal Server Error
1303
+ schema:
1304
+ $ref: '#/definitions/models.ErrorResponse'
1305
+ security:
1306
+ - Bearer: []
1307
+ summary: Update event subscription
1308
+ tags:
1309
+ - Events
1310
+ /events/types:
1311
+ get:
1312
+ description: 'Returns a paginated list of all registered event types. Requires
1313
+ permission: `events:types:read`'
1314
+ parameters:
1315
+ - default: 1
1316
+ description: 'Page number (default: 1)'
1317
+ in: query
1318
+ minimum: 1
1319
+ name: page
1320
+ type: integer
1321
+ - default: 10
1322
+ description: 'Items per page (default: 10)'
1323
+ in: query
1324
+ minimum: 1
1325
+ name: pageSize
1326
+ type: integer
1327
+ produces:
1328
+ - application/json
1329
+ responses:
1330
+ "200":
1331
+ description: OK
1332
+ schema:
1333
+ $ref: '#/definitions/models.EventTypeListResponse'
1334
+ "400":
1335
+ description: Invalid pagination parameters
1336
+ schema:
1337
+ $ref: '#/definitions/models.ErrorResponse'
1338
+ "401":
1339
+ description: Unauthenticated
1340
+ schema:
1341
+ $ref: '#/definitions/models.ErrorResponse'
1342
+ "403":
1343
+ description: 'Missing permission: events:types:read'
1344
+ schema:
1345
+ $ref: '#/definitions/models.ErrorResponse'
1346
+ "500":
1347
+ description: Internal Server Error
1348
+ schema:
1349
+ $ref: '#/definitions/models.ErrorResponse'
1350
+ security:
1351
+ - Bearer: []
1352
+ summary: List event types
1353
+ tags:
1354
+ - Events
1355
+ post:
1356
+ consumes:
1357
+ - application/json
1358
+ description: 'Registers a new event type in the system. Requires permission:
1359
+ `events:types:manage`'
1360
+ parameters:
1361
+ - description: Event type data
1362
+ in: body
1363
+ name: body
1364
+ required: true
1365
+ schema:
1366
+ $ref: '#/definitions/models.CreateEventTypeRequest'
1367
+ produces:
1368
+ - application/json
1369
+ responses:
1370
+ "201":
1371
+ description: Created
1372
+ schema:
1373
+ $ref: '#/definitions/models.EventType'
1374
+ "400":
1375
+ description: Invalid request body
1376
+ schema:
1377
+ $ref: '#/definitions/models.ErrorResponse'
1378
+ "401":
1379
+ description: Unauthenticated
1380
+ schema:
1381
+ $ref: '#/definitions/models.ErrorResponse'
1382
+ "403":
1383
+ description: 'Missing permission: events:types:manage'
1384
+ schema:
1385
+ $ref: '#/definitions/models.ErrorResponse'
1386
+ "500":
1387
+ description: Internal Server Error
1388
+ schema:
1389
+ $ref: '#/definitions/models.ErrorResponse'
1390
+ security:
1391
+ - Bearer: []
1392
+ summary: Create event type
1393
+ tags:
1394
+ - Events
1395
+ /events/types/{id}:
1396
+ delete:
1397
+ description: 'Soft-deletes an event type by ID. Requires permission: `events:types:manage`'
1398
+ parameters:
1399
+ - description: Event type ID
1400
+ in: path
1401
+ name: id
1402
+ required: true
1403
+ type: integer
1404
+ produces:
1405
+ - application/json
1406
+ responses:
1407
+ "200":
1408
+ description: OK
1409
+ schema:
1410
+ $ref: '#/definitions/models.MessageResponse'
1411
+ "400":
1412
+ description: Invalid ID
1413
+ schema:
1414
+ $ref: '#/definitions/models.ErrorResponse'
1415
+ "401":
1416
+ description: Unauthenticated
1417
+ schema:
1418
+ $ref: '#/definitions/models.ErrorResponse'
1419
+ "403":
1420
+ description: 'Missing permission: events:types:manage'
1421
+ schema:
1422
+ $ref: '#/definitions/models.ErrorResponse'
1423
+ "500":
1424
+ description: Internal Server Error
1425
+ schema:
1426
+ $ref: '#/definitions/models.ErrorResponse'
1427
+ security:
1428
+ - Bearer: []
1429
+ summary: Delete event type
1430
+ tags:
1431
+ - Events
1432
+ get:
1433
+ description: 'Returns an event type by ID. Requires permission: `events:types:read`'
1434
+ parameters:
1435
+ - description: Event type ID
1436
+ in: path
1437
+ name: id
1438
+ required: true
1439
+ type: integer
1440
+ produces:
1441
+ - application/json
1442
+ responses:
1443
+ "200":
1444
+ description: OK
1445
+ schema:
1446
+ $ref: '#/definitions/models.EventType'
1447
+ "400":
1448
+ description: Invalid ID
1449
+ schema:
1450
+ $ref: '#/definitions/models.ErrorResponse'
1451
+ "401":
1452
+ description: Unauthenticated
1453
+ schema:
1454
+ $ref: '#/definitions/models.ErrorResponse'
1455
+ "403":
1456
+ description: 'Missing permission: events:types:read'
1457
+ schema:
1458
+ $ref: '#/definitions/models.ErrorResponse'
1459
+ "404":
1460
+ description: Event type not found
1461
+ schema:
1462
+ $ref: '#/definitions/models.ErrorResponse'
1463
+ "500":
1464
+ description: Internal Server Error
1465
+ schema:
1466
+ $ref: '#/definitions/models.ErrorResponse'
1467
+ security:
1468
+ - Bearer: []
1469
+ summary: Get event type
1470
+ tags:
1471
+ - Events
1472
+ put:
1473
+ consumes:
1474
+ - application/json
1475
+ description: 'Updates an event type''s fields. All fields are optional. Requires
1476
+ permission: `events:types:manage`'
1477
+ parameters:
1478
+ - description: Event type ID
1479
+ in: path
1480
+ name: id
1481
+ required: true
1482
+ type: integer
1483
+ - description: Fields to update (all optional)
1484
+ in: body
1485
+ name: body
1486
+ required: true
1487
+ schema:
1488
+ $ref: '#/definitions/models.UpdateEventTypeRequest'
1489
+ produces:
1490
+ - application/json
1491
+ responses:
1492
+ "200":
1493
+ description: OK
1494
+ schema:
1495
+ $ref: '#/definitions/models.EventType'
1496
+ "400":
1497
+ description: Invalid ID or request body
1498
+ schema:
1499
+ $ref: '#/definitions/models.ErrorResponse'
1500
+ "401":
1501
+ description: Unauthenticated
1502
+ schema:
1503
+ $ref: '#/definitions/models.ErrorResponse'
1504
+ "403":
1505
+ description: 'Missing permission: events:types:manage'
1506
+ schema:
1507
+ $ref: '#/definitions/models.ErrorResponse'
1508
+ "404":
1509
+ description: Event type not found
1510
+ schema:
1511
+ $ref: '#/definitions/models.ErrorResponse'
1512
+ "500":
1513
+ description: Internal Server Error
1514
+ schema:
1515
+ $ref: '#/definitions/models.ErrorResponse'
1516
+ security:
1517
+ - Bearer: []
1518
+ summary: Update event type
1519
+ tags:
1520
+ - Events
1521
+ /locations:
1522
+ get:
1523
+ description: 'Returns a paginated list of all locations. Requires permission:
1524
+ `locations:read`'
1525
+ parameters:
1526
+ - default: 1
1527
+ description: 'Page number (default: 1)'
1528
+ in: query
1529
+ minimum: 1
1530
+ name: page
1531
+ type: integer
1532
+ - default: 10
1533
+ description: 'Items per page (default: 10)'
1534
+ in: query
1535
+ minimum: 1
1536
+ name: pageSize
1537
+ type: integer
1538
+ produces:
1539
+ - application/json
1540
+ responses:
1541
+ "200":
1542
+ description: OK
1543
+ schema:
1544
+ $ref: '#/definitions/models.LocationListResponse'
1545
+ "400":
1546
+ description: Invalid pagination parameters
1547
+ schema:
1548
+ $ref: '#/definitions/models.ErrorResponse'
1549
+ "401":
1550
+ description: Unauthenticated
1551
+ schema:
1552
+ $ref: '#/definitions/models.ErrorResponse'
1553
+ "403":
1554
+ description: 'Missing permission: locations:read'
1555
+ schema:
1556
+ $ref: '#/definitions/models.ErrorResponse'
1557
+ "500":
1558
+ description: Internal Server Error
1559
+ schema:
1560
+ $ref: '#/definitions/models.ErrorResponse'
1561
+ security:
1562
+ - Bearer: []
1563
+ summary: List locations
1564
+ tags:
1565
+ - Locations
1566
+ post:
1567
+ consumes:
1568
+ - application/json
1569
+ description: 'Creates a new location. Requires permission: `locations:manage`'
1570
+ parameters:
1571
+ - description: Location data
1572
+ in: body
1573
+ name: body
1574
+ required: true
1575
+ schema:
1576
+ $ref: '#/definitions/models.CreateLocationRequest'
1577
+ produces:
1578
+ - application/json
1579
+ responses:
1580
+ "201":
1581
+ description: Created
1582
+ schema:
1583
+ $ref: '#/definitions/models.Location'
1584
+ "400":
1585
+ description: Invalid request body
1586
+ schema:
1587
+ $ref: '#/definitions/models.ErrorResponse'
1588
+ "401":
1589
+ description: Unauthenticated
1590
+ schema:
1591
+ $ref: '#/definitions/models.ErrorResponse'
1592
+ "403":
1593
+ description: 'Missing permission: locations:manage'
1594
+ schema:
1595
+ $ref: '#/definitions/models.ErrorResponse'
1596
+ security:
1597
+ - Bearer: []
1598
+ summary: Create location
1599
+ tags:
1600
+ - Locations
1601
+ /locations/{id}:
1602
+ delete:
1603
+ description: 'Soft-deletes a location by ID. Requires permission: `locations:manage`'
1604
+ parameters:
1605
+ - description: Location ID
1606
+ in: path
1607
+ name: id
1608
+ required: true
1609
+ type: integer
1610
+ produces:
1611
+ - application/json
1612
+ responses:
1613
+ "200":
1614
+ description: OK
1615
+ schema:
1616
+ $ref: '#/definitions/models.MessageResponse'
1617
+ "400":
1618
+ description: Invalid location ID
1619
+ schema:
1620
+ $ref: '#/definitions/models.ErrorResponse'
1621
+ "401":
1622
+ description: Unauthenticated
1623
+ schema:
1624
+ $ref: '#/definitions/models.ErrorResponse'
1625
+ "403":
1626
+ description: 'Missing permission: locations:manage'
1627
+ schema:
1628
+ $ref: '#/definitions/models.ErrorResponse'
1629
+ "404":
1630
+ description: Location not found
1631
+ schema:
1632
+ $ref: '#/definitions/models.ErrorResponse'
1633
+ "500":
1634
+ description: Internal Server Error
1635
+ schema:
1636
+ $ref: '#/definitions/models.ErrorResponse'
1637
+ security:
1638
+ - Bearer: []
1639
+ summary: Delete location
1640
+ tags:
1641
+ - Locations
1642
+ get:
1643
+ description: 'Returns a location by ID. Requires permission: `locations:read`'
1644
+ parameters:
1645
+ - description: Location ID
1646
+ in: path
1647
+ name: id
1648
+ required: true
1649
+ type: integer
1650
+ produces:
1651
+ - application/json
1652
+ responses:
1653
+ "200":
1654
+ description: OK
1655
+ schema:
1656
+ $ref: '#/definitions/models.Location'
1657
+ "400":
1658
+ description: Invalid location ID
1659
+ schema:
1660
+ $ref: '#/definitions/models.ErrorResponse'
1661
+ "401":
1662
+ description: Unauthenticated
1663
+ schema:
1664
+ $ref: '#/definitions/models.ErrorResponse'
1665
+ "403":
1666
+ description: 'Missing permission: locations:read'
1667
+ schema:
1668
+ $ref: '#/definitions/models.ErrorResponse'
1669
+ "404":
1670
+ description: Location not found
1671
+ schema:
1672
+ $ref: '#/definitions/models.ErrorResponse'
1673
+ "500":
1674
+ description: Internal Server Error
1675
+ schema:
1676
+ $ref: '#/definitions/models.ErrorResponse'
1677
+ security:
1678
+ - Bearer: []
1679
+ summary: Get location
1680
+ tags:
1681
+ - Locations
1682
+ put:
1683
+ consumes:
1684
+ - application/json
1685
+ description: 'Updates a location''s fields. All fields are optional. Requires
1686
+ permission: `locations:manage`'
1687
+ parameters:
1688
+ - description: Location ID
1689
+ in: path
1690
+ name: id
1691
+ required: true
1692
+ type: integer
1693
+ - description: Fields to update (all optional)
1694
+ in: body
1695
+ name: body
1696
+ required: true
1697
+ schema:
1698
+ $ref: '#/definitions/models.UpdateLocationRequest'
1699
+ produces:
1700
+ - application/json
1701
+ responses:
1702
+ "200":
1703
+ description: OK
1704
+ schema:
1705
+ $ref: '#/definitions/models.Location'
1706
+ "400":
1707
+ description: Invalid location ID or request body
1708
+ schema:
1709
+ $ref: '#/definitions/models.ErrorResponse'
1710
+ "401":
1711
+ description: Unauthenticated
1712
+ schema:
1713
+ $ref: '#/definitions/models.ErrorResponse'
1714
+ "403":
1715
+ description: 'Missing permission: locations:manage'
1716
+ schema:
1717
+ $ref: '#/definitions/models.ErrorResponse'
1718
+ "404":
1719
+ description: Location not found
1720
+ schema:
1721
+ $ref: '#/definitions/models.ErrorResponse'
1722
+ "500":
1723
+ description: Internal Server Error
1724
+ schema:
1725
+ $ref: '#/definitions/models.ErrorResponse'
1726
+ security:
1727
+ - Bearer: []
1728
+ summary: Update location
1729
+ tags:
1730
+ - Locations
1731
+ /permissions:
1732
+ get:
1733
+ description: 'Returns a paginated list of all permissions. Requires permission:
1734
+ `permissions:read`'
1735
+ parameters:
1736
+ - default: 1
1737
+ description: 'Page number (default: 1)'
1738
+ in: query
1739
+ minimum: 1
1740
+ name: page
1741
+ type: integer
1742
+ - default: 10
1743
+ description: 'Items per page (default: 10)'
1744
+ in: query
1745
+ minimum: 1
1746
+ name: pageSize
1747
+ type: integer
1748
+ produces:
1749
+ - application/json
1750
+ responses:
1751
+ "200":
1752
+ description: OK
1753
+ schema:
1754
+ $ref: '#/definitions/models.PermissionListResponse'
1755
+ "400":
1756
+ description: Invalid pagination parameters
1757
+ schema:
1758
+ $ref: '#/definitions/models.ErrorResponse'
1759
+ "401":
1760
+ description: Unauthenticated
1761
+ schema:
1762
+ $ref: '#/definitions/models.ErrorResponse'
1763
+ "403":
1764
+ description: 'Missing permission: permissions:read'
1765
+ schema:
1766
+ $ref: '#/definitions/models.ErrorResponse'
1767
+ "500":
1768
+ description: Internal Server Error
1769
+ schema:
1770
+ $ref: '#/definitions/models.ErrorResponse'
1771
+ security:
1772
+ - Bearer: []
1773
+ summary: List permissions
1774
+ tags:
1775
+ - Permissions
1776
+ post:
1777
+ consumes:
1778
+ - application/json
1779
+ description: 'Creates a new permission. Permission names follow the format `resource:action`
1780
+ or `resource:action:sub-action` (e.g. `users:read`, `users:roles:manage`).
1781
+ Requires permission: `permissions:manage`'
1782
+ parameters:
1783
+ - description: Permission data
1784
+ in: body
1785
+ name: body
1786
+ required: true
1787
+ schema:
1788
+ $ref: '#/definitions/models.CreatePermissionRequest'
1789
+ produces:
1790
+ - application/json
1791
+ responses:
1792
+ "201":
1793
+ description: Created
1794
+ schema:
1795
+ $ref: '#/definitions/models.Permission'
1796
+ "400":
1797
+ description: Invalid request body
1798
+ schema:
1799
+ $ref: '#/definitions/models.ErrorResponse'
1800
+ "401":
1801
+ description: Unauthenticated
1802
+ schema:
1803
+ $ref: '#/definitions/models.ErrorResponse'
1804
+ "403":
1805
+ description: 'Missing permission: permissions:manage'
1806
+ schema:
1807
+ $ref: '#/definitions/models.ErrorResponse'
1808
+ security:
1809
+ - Bearer: []
1810
+ summary: Create permission
1811
+ tags:
1812
+ - Permissions
1813
+ /permissions/{id}:
1814
+ delete:
1815
+ description: 'Soft-deletes a permission by ID. Requires permission: `permissions:manage`'
1816
+ parameters:
1817
+ - description: Permission ID
1818
+ in: path
1819
+ name: id
1820
+ required: true
1821
+ type: integer
1822
+ produces:
1823
+ - application/json
1824
+ responses:
1825
+ "200":
1826
+ description: OK
1827
+ schema:
1828
+ $ref: '#/definitions/models.MessageResponse'
1829
+ "400":
1830
+ description: Invalid permission ID
1831
+ schema:
1832
+ $ref: '#/definitions/models.ErrorResponse'
1833
+ "401":
1834
+ description: Unauthenticated
1835
+ schema:
1836
+ $ref: '#/definitions/models.ErrorResponse'
1837
+ "403":
1838
+ description: 'Missing permission: permissions:manage'
1839
+ schema:
1840
+ $ref: '#/definitions/models.ErrorResponse'
1841
+ "500":
1842
+ description: Internal Server Error
1843
+ schema:
1844
+ $ref: '#/definitions/models.ErrorResponse'
1845
+ security:
1846
+ - Bearer: []
1847
+ summary: Delete permission
1848
+ tags:
1849
+ - Permissions
1850
+ get:
1851
+ description: 'Returns a permission by ID including the roles it is assigned
1852
+ to. Requires permission: `permissions:read`'
1853
+ parameters:
1854
+ - description: Permission ID
1855
+ in: path
1856
+ name: id
1857
+ required: true
1858
+ type: integer
1859
+ produces:
1860
+ - application/json
1861
+ responses:
1862
+ "200":
1863
+ description: OK
1864
+ schema:
1865
+ $ref: '#/definitions/models.Permission'
1866
+ "400":
1867
+ description: Invalid permission ID
1868
+ schema:
1869
+ $ref: '#/definitions/models.ErrorResponse'
1870
+ "401":
1871
+ description: Unauthenticated
1872
+ schema:
1873
+ $ref: '#/definitions/models.ErrorResponse'
1874
+ "403":
1875
+ description: 'Missing permission: permissions:read'
1876
+ schema:
1877
+ $ref: '#/definitions/models.ErrorResponse'
1878
+ "404":
1879
+ description: Permission not found
1880
+ schema:
1881
+ $ref: '#/definitions/models.ErrorResponse'
1882
+ "500":
1883
+ description: Internal Server Error
1884
+ schema:
1885
+ $ref: '#/definitions/models.ErrorResponse'
1886
+ security:
1887
+ - Bearer: []
1888
+ summary: Get permission
1889
+ tags:
1890
+ - Permissions
1891
+ put:
1892
+ consumes:
1893
+ - application/json
1894
+ description: 'Updates a permission''s name. Requires permission: `permissions:manage`'
1895
+ parameters:
1896
+ - description: Permission ID
1897
+ in: path
1898
+ name: id
1899
+ required: true
1900
+ type: integer
1901
+ - description: Fields to update
1902
+ in: body
1903
+ name: body
1904
+ required: true
1905
+ schema:
1906
+ $ref: '#/definitions/models.UpdatePermissionRequest'
1907
+ produces:
1908
+ - application/json
1909
+ responses:
1910
+ "200":
1911
+ description: OK
1912
+ schema:
1913
+ $ref: '#/definitions/models.Permission'
1914
+ "400":
1915
+ description: Invalid permission ID or request body
1916
+ schema:
1917
+ $ref: '#/definitions/models.ErrorResponse'
1918
+ "401":
1919
+ description: Unauthenticated
1920
+ schema:
1921
+ $ref: '#/definitions/models.ErrorResponse'
1922
+ "403":
1923
+ description: 'Missing permission: permissions:manage'
1924
+ schema:
1925
+ $ref: '#/definitions/models.ErrorResponse'
1926
+ "500":
1927
+ description: Internal Server Error
1928
+ schema:
1929
+ $ref: '#/definitions/models.ErrorResponse'
1930
+ security:
1931
+ - Bearer: []
1932
+ summary: Update permission
1933
+ tags:
1934
+ - Permissions
1935
+ /rabbit/bindings:
1936
+ post:
1937
+ consumes:
1938
+ - application/json
1939
+ description: Binds an existing queue to `health_grid_exchange` using the event
1940
+ name as routing key. The authenticated user's email must exist as a RabbitMQ
1941
+ username and have read permission on the queue.
1942
+ parameters:
1943
+ - description: Binding data
1944
+ in: body
1945
+ name: body
1946
+ required: true
1947
+ schema:
1948
+ $ref: '#/definitions/models.BindRabbitQueueRequest'
1949
+ produces:
1950
+ - application/json
1951
+ responses:
1952
+ "200":
1953
+ description: OK
1954
+ schema:
1955
+ $ref: '#/definitions/models.RabbitQueueBindingResponse'
1956
+ "400":
1957
+ description: Invalid request body
1958
+ schema:
1959
+ $ref: '#/definitions/models.ErrorResponse'
1960
+ "401":
1961
+ description: Unauthenticated
1962
+ schema:
1963
+ $ref: '#/definitions/models.ErrorResponse'
1964
+ "403":
1965
+ description: RabbitMQ user does not have read permission
1966
+ schema:
1967
+ $ref: '#/definitions/models.ErrorResponse'
1968
+ "404":
1969
+ description: Queue or event not found
1970
+ schema:
1971
+ $ref: '#/definitions/models.ErrorResponse'
1972
+ "503":
1973
+ description: RabbitMQ unavailable
1974
+ schema:
1975
+ $ref: '#/definitions/models.ErrorResponse'
1976
+ security:
1977
+ - Bearer: []
1978
+ summary: Bind RabbitMQ queue to event
1979
+ tags:
1980
+ - Rabbit
1981
+ /rabbit/queues:
1982
+ post:
1983
+ consumes:
1984
+ - application/json
1985
+ description: Creates a durable RabbitMQ queue with suffix `.requests` or `.responses`
1986
+ and its DLQ. The authenticated user's email must exist as a RabbitMQ username.
1987
+ parameters:
1988
+ - description: Queue data
1989
+ in: body
1990
+ name: body
1991
+ required: true
1992
+ schema:
1993
+ $ref: '#/definitions/models.CreateRabbitQueueRequest'
1994
+ produces:
1995
+ - application/json
1996
+ responses:
1997
+ "201":
1998
+ description: Created
1999
+ schema:
2000
+ $ref: '#/definitions/models.RabbitQueueResponse'
2001
+ "400":
2002
+ description: Invalid request body
2003
+ schema:
2004
+ $ref: '#/definitions/models.ErrorResponse'
2005
+ "401":
2006
+ description: Unauthenticated
2007
+ schema:
2008
+ $ref: '#/definitions/models.ErrorResponse'
2009
+ "403":
2010
+ description: Authenticated user is not a RabbitMQ user
2011
+ schema:
2012
+ $ref: '#/definitions/models.ErrorResponse'
2013
+ "503":
2014
+ description: RabbitMQ unavailable
2015
+ schema:
2016
+ $ref: '#/definitions/models.ErrorResponse'
2017
+ security:
2018
+ - Bearer: []
2019
+ summary: Create RabbitMQ request/response queue
2020
+ tags:
2021
+ - Rabbit
2022
+ /roles:
2023
+ get:
2024
+ description: 'Returns a paginated list of all roles. Requires permission: `roles:read`'
2025
+ parameters:
2026
+ - default: 1
2027
+ description: 'Page number (default: 1)'
2028
+ in: query
2029
+ minimum: 1
2030
+ name: page
2031
+ type: integer
2032
+ - default: 10
2033
+ description: 'Items per page (default: 10)'
2034
+ in: query
2035
+ minimum: 1
2036
+ name: pageSize
2037
+ type: integer
2038
+ produces:
2039
+ - application/json
2040
+ responses:
2041
+ "200":
2042
+ description: OK
2043
+ schema:
2044
+ $ref: '#/definitions/models.RoleListResponse'
2045
+ "400":
2046
+ description: Invalid pagination parameters
2047
+ schema:
2048
+ $ref: '#/definitions/models.ErrorResponse'
2049
+ "401":
2050
+ description: Unauthenticated
2051
+ schema:
2052
+ $ref: '#/definitions/models.ErrorResponse'
2053
+ "403":
2054
+ description: 'Missing permission: roles:read'
2055
+ schema:
2056
+ $ref: '#/definitions/models.ErrorResponse'
2057
+ "500":
2058
+ description: Internal Server Error
2059
+ schema:
2060
+ $ref: '#/definitions/models.ErrorResponse'
2061
+ security:
2062
+ - Bearer: []
2063
+ summary: List roles
2064
+ tags:
2065
+ - Roles
2066
+ post:
2067
+ consumes:
2068
+ - application/json
2069
+ description: 'Creates a new role. Requires permission: `roles:manage`'
2070
+ parameters:
2071
+ - description: Role data
2072
+ in: body
2073
+ name: body
2074
+ required: true
2075
+ schema:
2076
+ $ref: '#/definitions/models.CreateRoleRequest'
2077
+ produces:
2078
+ - application/json
2079
+ responses:
2080
+ "201":
2081
+ description: Created
2082
+ schema:
2083
+ $ref: '#/definitions/models.Role'
2084
+ "400":
2085
+ description: Invalid request body
2086
+ schema:
2087
+ $ref: '#/definitions/models.ErrorResponse'
2088
+ "401":
2089
+ description: Unauthenticated
2090
+ schema:
2091
+ $ref: '#/definitions/models.ErrorResponse'
2092
+ "403":
2093
+ description: 'Missing permission: roles:manage'
2094
+ schema:
2095
+ $ref: '#/definitions/models.ErrorResponse'
2096
+ security:
2097
+ - Bearer: []
2098
+ summary: Create role
2099
+ tags:
2100
+ - Roles
2101
+ /roles/{id}:
2102
+ delete:
2103
+ description: 'Soft-deletes a role by ID. Requires permission: `roles:manage`'
2104
+ parameters:
2105
+ - description: Role ID
2106
+ in: path
2107
+ name: id
2108
+ required: true
2109
+ type: integer
2110
+ produces:
2111
+ - application/json
2112
+ responses:
2113
+ "200":
2114
+ description: OK
2115
+ schema:
2116
+ $ref: '#/definitions/models.MessageResponse'
2117
+ "400":
2118
+ description: Invalid role ID
2119
+ schema:
2120
+ $ref: '#/definitions/models.ErrorResponse'
2121
+ "401":
2122
+ description: Unauthenticated
2123
+ schema:
2124
+ $ref: '#/definitions/models.ErrorResponse'
2125
+ "403":
2126
+ description: 'Missing permission: roles:manage'
2127
+ schema:
2128
+ $ref: '#/definitions/models.ErrorResponse'
2129
+ "500":
2130
+ description: Internal Server Error
2131
+ schema:
2132
+ $ref: '#/definitions/models.ErrorResponse'
2133
+ security:
2134
+ - Bearer: []
2135
+ summary: Delete role
2136
+ tags:
2137
+ - Roles
2138
+ get:
2139
+ description: 'Returns a role by ID including its assigned permissions. Requires
2140
+ permission: `roles:read`'
2141
+ parameters:
2142
+ - description: Role ID
2143
+ in: path
2144
+ name: id
2145
+ required: true
2146
+ type: integer
2147
+ produces:
2148
+ - application/json
2149
+ responses:
2150
+ "200":
2151
+ description: OK
2152
+ schema:
2153
+ $ref: '#/definitions/models.Role'
2154
+ "400":
2155
+ description: Invalid role ID
2156
+ schema:
2157
+ $ref: '#/definitions/models.ErrorResponse'
2158
+ "401":
2159
+ description: Unauthenticated
2160
+ schema:
2161
+ $ref: '#/definitions/models.ErrorResponse'
2162
+ "403":
2163
+ description: 'Missing permission: roles:read'
2164
+ schema:
2165
+ $ref: '#/definitions/models.ErrorResponse'
2166
+ "404":
2167
+ description: Role not found
2168
+ schema:
2169
+ $ref: '#/definitions/models.ErrorResponse'
2170
+ "500":
2171
+ description: Internal Server Error
2172
+ schema:
2173
+ $ref: '#/definitions/models.ErrorResponse'
2174
+ security:
2175
+ - Bearer: []
2176
+ summary: Get role
2177
+ tags:
2178
+ - Roles
2179
+ put:
2180
+ consumes:
2181
+ - application/json
2182
+ description: 'Updates a role''s name. Requires permission: `roles:manage`'
2183
+ parameters:
2184
+ - description: Role ID
2185
+ in: path
2186
+ name: id
2187
+ required: true
2188
+ type: integer
2189
+ - description: Fields to update
2190
+ in: body
2191
+ name: body
2192
+ required: true
2193
+ schema:
2194
+ $ref: '#/definitions/models.UpdateRoleRequest'
2195
+ produces:
2196
+ - application/json
2197
+ responses:
2198
+ "200":
2199
+ description: OK
2200
+ schema:
2201
+ $ref: '#/definitions/models.Role'
2202
+ "400":
2203
+ description: Invalid role ID or request body
2204
+ schema:
2205
+ $ref: '#/definitions/models.ErrorResponse'
2206
+ "401":
2207
+ description: Unauthenticated
2208
+ schema:
2209
+ $ref: '#/definitions/models.ErrorResponse'
2210
+ "403":
2211
+ description: 'Missing permission: roles:manage'
2212
+ schema:
2213
+ $ref: '#/definitions/models.ErrorResponse'
2214
+ "500":
2215
+ description: Internal Server Error
2216
+ schema:
2217
+ $ref: '#/definitions/models.ErrorResponse'
2218
+ security:
2219
+ - Bearer: []
2220
+ summary: Update role
2221
+ tags:
2222
+ - Roles
2223
+ /roles/{id}/permissions:
2224
+ post:
2225
+ consumes:
2226
+ - application/json
2227
+ description: 'Assigns an existing permission to a role. Users with this role
2228
+ will gain that permission. Requires permission: `roles:permissions:manage`'
2229
+ parameters:
2230
+ - description: Role ID
2231
+ in: path
2232
+ name: id
2233
+ required: true
2234
+ type: integer
2235
+ - description: Permission to assign
2236
+ in: body
2237
+ name: body
2238
+ required: true
2239
+ schema:
2240
+ $ref: '#/definitions/models.AssignPermissionToRoleRequest'
2241
+ produces:
2242
+ - application/json
2243
+ responses:
2244
+ "200":
2245
+ description: OK
2246
+ schema:
2247
+ $ref: '#/definitions/models.MessageResponse'
2248
+ "400":
2249
+ description: Invalid role ID or request body
2250
+ schema:
2251
+ $ref: '#/definitions/models.ErrorResponse'
2252
+ "401":
2253
+ description: Unauthenticated
2254
+ schema:
2255
+ $ref: '#/definitions/models.ErrorResponse'
2256
+ "403":
2257
+ description: 'Missing permission: roles:permissions:manage'
2258
+ schema:
2259
+ $ref: '#/definitions/models.ErrorResponse'
2260
+ "500":
2261
+ description: Internal Server Error
2262
+ schema:
2263
+ $ref: '#/definitions/models.ErrorResponse'
2264
+ security:
2265
+ - Bearer: []
2266
+ summary: Assign permission to role
2267
+ tags:
2268
+ - Roles
2269
+ /roles/{id}/permissions/{permissionId}:
2270
+ delete:
2271
+ description: 'Removes a permission from a role. Users with this role will lose
2272
+ that permission. Requires permission: `roles:permissions:manage`'
2273
+ parameters:
2274
+ - description: Role ID
2275
+ in: path
2276
+ name: id
2277
+ required: true
2278
+ type: integer
2279
+ - description: Permission ID
2280
+ in: path
2281
+ name: permissionId
2282
+ required: true
2283
+ type: integer
2284
+ produces:
2285
+ - application/json
2286
+ responses:
2287
+ "200":
2288
+ description: OK
2289
+ schema:
2290
+ $ref: '#/definitions/models.MessageResponse'
2291
+ "400":
2292
+ description: Invalid role ID or permission ID
2293
+ schema:
2294
+ $ref: '#/definitions/models.ErrorResponse'
2295
+ "401":
2296
+ description: Unauthenticated
2297
+ schema:
2298
+ $ref: '#/definitions/models.ErrorResponse'
2299
+ "403":
2300
+ description: 'Missing permission: roles:permissions:manage'
2301
+ schema:
2302
+ $ref: '#/definitions/models.ErrorResponse'
2303
+ "500":
2304
+ description: Internal Server Error
2305
+ schema:
2306
+ $ref: '#/definitions/models.ErrorResponse'
2307
+ security:
2308
+ - Bearer: []
2309
+ summary: Remove permission from role
2310
+ tags:
2311
+ - Roles
2312
+ /specialities:
2313
+ get:
2314
+ description: 'Returns a paginated list of all specialities. Requires permission:
2315
+ `specialities:read`'
2316
+ parameters:
2317
+ - default: 1
2318
+ description: 'Page number (default: 1)'
2319
+ in: query
2320
+ minimum: 1
2321
+ name: page
2322
+ type: integer
2323
+ - default: 10
2324
+ description: 'Items per page (default: 10)'
2325
+ in: query
2326
+ minimum: 1
2327
+ name: pageSize
2328
+ type: integer
2329
+ produces:
2330
+ - application/json
2331
+ responses:
2332
+ "200":
2333
+ description: OK
2334
+ schema:
2335
+ $ref: '#/definitions/models.SpecialityListResponse'
2336
+ "400":
2337
+ description: Invalid pagination parameters
2338
+ schema:
2339
+ $ref: '#/definitions/models.ErrorResponse'
2340
+ "401":
2341
+ description: Unauthenticated
2342
+ schema:
2343
+ $ref: '#/definitions/models.ErrorResponse'
2344
+ "403":
2345
+ description: 'Missing permission: specialities:read'
2346
+ schema:
2347
+ $ref: '#/definitions/models.ErrorResponse'
2348
+ "500":
2349
+ description: Internal Server Error
2350
+ schema:
2351
+ $ref: '#/definitions/models.ErrorResponse'
2352
+ security:
2353
+ - Bearer: []
2354
+ summary: List specialities
2355
+ tags:
2356
+ - Specialities
2357
+ post:
2358
+ consumes:
2359
+ - application/json
2360
+ description: 'Creates a new speciality. Requires permission: `specialities:manage`'
2361
+ parameters:
2362
+ - description: Speciality data
2363
+ in: body
2364
+ name: body
2365
+ required: true
2366
+ schema:
2367
+ $ref: '#/definitions/models.CreateSpecialityRequest'
2368
+ produces:
2369
+ - application/json
2370
+ responses:
2371
+ "201":
2372
+ description: Created
2373
+ schema:
2374
+ $ref: '#/definitions/models.Speciality'
2375
+ "400":
2376
+ description: Invalid request body
2377
+ schema:
2378
+ $ref: '#/definitions/models.ErrorResponse'
2379
+ "401":
2380
+ description: Unauthenticated
2381
+ schema:
2382
+ $ref: '#/definitions/models.ErrorResponse'
2383
+ "403":
2384
+ description: 'Missing permission: specialities:manage'
2385
+ schema:
2386
+ $ref: '#/definitions/models.ErrorResponse'
2387
+ security:
2388
+ - Bearer: []
2389
+ summary: Create speciality
2390
+ tags:
2391
+ - Specialities
2392
+ /specialities/{id}:
2393
+ delete:
2394
+ description: 'Soft-deletes a speciality by ID. Requires permission: `specialities:manage`'
2395
+ parameters:
2396
+ - description: Speciality ID
2397
+ in: path
2398
+ name: id
2399
+ required: true
2400
+ type: integer
2401
+ produces:
2402
+ - application/json
2403
+ responses:
2404
+ "200":
2405
+ description: OK
2406
+ schema:
2407
+ $ref: '#/definitions/models.MessageResponse'
2408
+ "400":
2409
+ description: Invalid speciality ID
2410
+ schema:
2411
+ $ref: '#/definitions/models.ErrorResponse'
2412
+ "401":
2413
+ description: Unauthenticated
2414
+ schema:
2415
+ $ref: '#/definitions/models.ErrorResponse'
2416
+ "403":
2417
+ description: 'Missing permission: specialities:manage'
2418
+ schema:
2419
+ $ref: '#/definitions/models.ErrorResponse'
2420
+ "500":
2421
+ description: Internal Server Error
2422
+ schema:
2423
+ $ref: '#/definitions/models.ErrorResponse'
2424
+ security:
2425
+ - Bearer: []
2426
+ summary: Delete speciality
2427
+ tags:
2428
+ - Specialities
2429
+ get:
2430
+ description: 'Returns a speciality by ID. Requires permission: `specialities:read`'
2431
+ parameters:
2432
+ - description: Speciality ID
2433
+ in: path
2434
+ name: id
2435
+ required: true
2436
+ type: integer
2437
+ produces:
2438
+ - application/json
2439
+ responses:
2440
+ "200":
2441
+ description: OK
2442
+ schema:
2443
+ $ref: '#/definitions/models.Speciality'
2444
+ "400":
2445
+ description: Invalid speciality ID
2446
+ schema:
2447
+ $ref: '#/definitions/models.ErrorResponse'
2448
+ "401":
2449
+ description: Unauthenticated
2450
+ schema:
2451
+ $ref: '#/definitions/models.ErrorResponse'
2452
+ "403":
2453
+ description: 'Missing permission: specialities:read'
2454
+ schema:
2455
+ $ref: '#/definitions/models.ErrorResponse'
2456
+ "404":
2457
+ description: Speciality not found
2458
+ schema:
2459
+ $ref: '#/definitions/models.ErrorResponse'
2460
+ "500":
2461
+ description: Internal Server Error
2462
+ schema:
2463
+ $ref: '#/definitions/models.ErrorResponse'
2464
+ security:
2465
+ - Bearer: []
2466
+ summary: Get speciality
2467
+ tags:
2468
+ - Specialities
2469
+ put:
2470
+ consumes:
2471
+ - application/json
2472
+ description: 'Updates a speciality''s name. Requires permission: `specialities:manage`'
2473
+ parameters:
2474
+ - description: Speciality ID
2475
+ in: path
2476
+ name: id
2477
+ required: true
2478
+ type: integer
2479
+ - description: Fields to update
2480
+ in: body
2481
+ name: body
2482
+ required: true
2483
+ schema:
2484
+ $ref: '#/definitions/models.UpdateSpecialityRequest'
2485
+ produces:
2486
+ - application/json
2487
+ responses:
2488
+ "200":
2489
+ description: OK
2490
+ schema:
2491
+ $ref: '#/definitions/models.Speciality'
2492
+ "400":
2493
+ description: Invalid speciality ID or request body
2494
+ schema:
2495
+ $ref: '#/definitions/models.ErrorResponse'
2496
+ "401":
2497
+ description: Unauthenticated
2498
+ schema:
2499
+ $ref: '#/definitions/models.ErrorResponse'
2500
+ "403":
2501
+ description: 'Missing permission: specialities:manage'
2502
+ schema:
2503
+ $ref: '#/definitions/models.ErrorResponse'
2504
+ "500":
2505
+ description: Internal Server Error
2506
+ schema:
2507
+ $ref: '#/definitions/models.ErrorResponse'
2508
+ security:
2509
+ - Bearer: []
2510
+ summary: Update speciality
2511
+ tags:
2512
+ - Specialities
2513
+ /users:
2514
+ get:
2515
+ description: 'Returns a paginated list of all users. Requires permission: `users:read`'
2516
+ parameters:
2517
+ - default: 1
2518
+ description: 'Page number (default: 1)'
2519
+ in: query
2520
+ minimum: 1
2521
+ name: page
2522
+ type: integer
2523
+ - default: 10
2524
+ description: 'Items per page (default: 10)'
2525
+ in: query
2526
+ minimum: 1
2527
+ name: pageSize
2528
+ type: integer
2529
+ produces:
2530
+ - application/json
2531
+ responses:
2532
+ "200":
2533
+ description: OK
2534
+ schema:
2535
+ $ref: '#/definitions/models.UserListResponse'
2536
+ "400":
2537
+ description: Invalid pagination parameters
2538
+ schema:
2539
+ $ref: '#/definitions/models.ErrorResponse'
2540
+ "401":
2541
+ description: Unauthenticated
2542
+ schema:
2543
+ $ref: '#/definitions/models.ErrorResponse'
2544
+ "403":
2545
+ description: 'Missing permission: users:read'
2546
+ schema:
2547
+ $ref: '#/definitions/models.ErrorResponse'
2548
+ "500":
2549
+ description: Internal Server Error
2550
+ schema:
2551
+ $ref: '#/definitions/models.ErrorResponse'
2552
+ security:
2553
+ - Bearer: []
2554
+ summary: List users
2555
+ tags:
2556
+ - Users
2557
+ post:
2558
+ consumes:
2559
+ - application/json
2560
+ description: 'An admin creates an account for another person and assigns them
2561
+ a role. The system sends a 48-hour activation email; the user sets their password
2562
+ via /auth/verify-account. Requires permission: `users:create:role:{roleID}`'
2563
+ parameters:
2564
+ - description: New user data including role assignment
2565
+ in: body
2566
+ name: body
2567
+ required: true
2568
+ schema:
2569
+ $ref: '#/definitions/models.AdminCreateUserRequest'
2570
+ produces:
2571
+ - application/json
2572
+ responses:
2573
+ "201":
2574
+ description: Created
2575
+ schema:
2576
+ $ref: '#/definitions/models.User'
2577
+ "400":
2578
+ description: Bad Request
2579
+ schema:
2580
+ $ref: '#/definitions/models.ErrorResponse'
2581
+ "401":
2582
+ description: Unauthenticated
2583
+ schema:
2584
+ $ref: '#/definitions/models.ErrorResponse'
2585
+ "403":
2586
+ description: 'Missing permission: users:create:role:{roleID}'
2587
+ schema:
2588
+ $ref: '#/definitions/models.ErrorResponse'
2589
+ "409":
2590
+ description: Email already exists
2591
+ schema:
2592
+ $ref: '#/definitions/models.ErrorResponse'
2593
+ "500":
2594
+ description: Internal Server Error
2595
+ schema:
2596
+ $ref: '#/definitions/models.ErrorResponse'
2597
+ security:
2598
+ - Bearer: []
2599
+ summary: Create user (admin)
2600
+ tags:
2601
+ - Users
2602
+ /users/{id}:
2603
+ delete:
2604
+ description: 'Soft-deletes a user by ID. The user is marked as deleted but remains
2605
+ in the database. Requires permission: `users:delete`'
2606
+ parameters:
2607
+ - description: User ID
2608
+ in: path
2609
+ name: id
2610
+ required: true
2611
+ type: integer
2612
+ produces:
2613
+ - application/json
2614
+ responses:
2615
+ "200":
2616
+ description: OK
2617
+ schema:
2618
+ $ref: '#/definitions/models.MessageResponse'
2619
+ "400":
2620
+ description: Invalid user ID
2621
+ schema:
2622
+ $ref: '#/definitions/models.ErrorResponse'
2623
+ "401":
2624
+ description: Unauthenticated
2625
+ schema:
2626
+ $ref: '#/definitions/models.ErrorResponse'
2627
+ "403":
2628
+ description: 'Missing permission: users:delete'
2629
+ schema:
2630
+ $ref: '#/definitions/models.ErrorResponse'
2631
+ "500":
2632
+ description: Internal Server Error
2633
+ schema:
2634
+ $ref: '#/definitions/models.ErrorResponse'
2635
+ security:
2636
+ - Bearer: []
2637
+ summary: Delete user
2638
+ tags:
2639
+ - Users
2640
+ get:
2641
+ description: 'Returns a user by ID including their roles, locations and specialities.
2642
+ Requires permission: `users:read`'
2643
+ parameters:
2644
+ - description: User ID
2645
+ in: path
2646
+ name: id
2647
+ required: true
2648
+ type: integer
2649
+ produces:
2650
+ - application/json
2651
+ responses:
2652
+ "200":
2653
+ description: OK
2654
+ schema:
2655
+ $ref: '#/definitions/models.User'
2656
+ "400":
2657
+ description: Invalid user ID
2658
+ schema:
2659
+ $ref: '#/definitions/models.ErrorResponse'
2660
+ "401":
2661
+ description: Unauthenticated
2662
+ schema:
2663
+ $ref: '#/definitions/models.ErrorResponse'
2664
+ "403":
2665
+ description: 'Missing permission: users:read'
2666
+ schema:
2667
+ $ref: '#/definitions/models.ErrorResponse'
2668
+ "404":
2669
+ description: User not found
2670
+ schema:
2671
+ $ref: '#/definitions/models.ErrorResponse'
2672
+ "500":
2673
+ description: Internal Server Error
2674
+ schema:
2675
+ $ref: '#/definitions/models.ErrorResponse'
2676
+ security:
2677
+ - Bearer: []
2678
+ summary: Get user
2679
+ tags:
2680
+ - Users
2681
+ put:
2682
+ consumes:
2683
+ - application/json
2684
+ description: 'Updates a user''s profile fields (first name, last name, email).
2685
+ All fields are optional. Requires permission: `users:write`'
2686
+ parameters:
2687
+ - description: User ID
2688
+ in: path
2689
+ name: id
2690
+ required: true
2691
+ type: integer
2692
+ - description: Fields to update (all optional)
2693
+ in: body
2694
+ name: body
2695
+ required: true
2696
+ schema:
2697
+ $ref: '#/definitions/models.UpdateUserRequest'
2698
+ produces:
2699
+ - application/json
2700
+ responses:
2701
+ "200":
2702
+ description: OK
2703
+ schema:
2704
+ $ref: '#/definitions/models.User'
2705
+ "400":
2706
+ description: Invalid user ID or request body
2707
+ schema:
2708
+ $ref: '#/definitions/models.ErrorResponse'
2709
+ "401":
2710
+ description: Unauthenticated
2711
+ schema:
2712
+ $ref: '#/definitions/models.ErrorResponse'
2713
+ "403":
2714
+ description: 'Missing permission: users:write'
2715
+ schema:
2716
+ $ref: '#/definitions/models.ErrorResponse'
2717
+ "500":
2718
+ description: Internal Server Error
2719
+ schema:
2720
+ $ref: '#/definitions/models.ErrorResponse'
2721
+ security:
2722
+ - Bearer: []
2723
+ summary: Update user
2724
+ tags:
2725
+ - Users
2726
+ /users/{id}/locations:
2727
+ post:
2728
+ consumes:
2729
+ - application/json
2730
+ description: 'Assigns an existing location to a user. Requires permission: `users:locations:manage`'
2731
+ parameters:
2732
+ - description: User ID
2733
+ in: path
2734
+ name: id
2735
+ required: true
2736
+ type: integer
2737
+ - description: Location to assign
2738
+ in: body
2739
+ name: body
2740
+ required: true
2741
+ schema:
2742
+ $ref: '#/definitions/models.AssignLocationRequest'
2743
+ produces:
2744
+ - application/json
2745
+ responses:
2746
+ "200":
2747
+ description: OK
2748
+ schema:
2749
+ $ref: '#/definitions/models.MessageResponse'
2750
+ "400":
2751
+ description: Invalid user ID or request body
2752
+ schema:
2753
+ $ref: '#/definitions/models.ErrorResponse'
2754
+ "401":
2755
+ description: Unauthenticated
2756
+ schema:
2757
+ $ref: '#/definitions/models.ErrorResponse'
2758
+ "403":
2759
+ description: 'Missing permission: users:locations:manage'
2760
+ schema:
2761
+ $ref: '#/definitions/models.ErrorResponse'
2762
+ "500":
2763
+ description: Internal Server Error
2764
+ schema:
2765
+ $ref: '#/definitions/models.ErrorResponse'
2766
+ security:
2767
+ - Bearer: []
2768
+ summary: Assign location to user
2769
+ tags:
2770
+ - Users
2771
+ /users/{id}/locations/{locationId}:
2772
+ delete:
2773
+ description: 'Removes a location from a user. Requires permission: `users:locations:manage`'
2774
+ parameters:
2775
+ - description: User ID
2776
+ in: path
2777
+ name: id
2778
+ required: true
2779
+ type: integer
2780
+ - description: Location ID
2781
+ in: path
2782
+ name: locationId
2783
+ required: true
2784
+ type: integer
2785
+ produces:
2786
+ - application/json
2787
+ responses:
2788
+ "200":
2789
+ description: OK
2790
+ schema:
2791
+ $ref: '#/definitions/models.MessageResponse'
2792
+ "400":
2793
+ description: Invalid user ID or location ID
2794
+ schema:
2795
+ $ref: '#/definitions/models.ErrorResponse'
2796
+ "401":
2797
+ description: Unauthenticated
2798
+ schema:
2799
+ $ref: '#/definitions/models.ErrorResponse'
2800
+ "403":
2801
+ description: 'Missing permission: users:locations:manage'
2802
+ schema:
2803
+ $ref: '#/definitions/models.ErrorResponse'
2804
+ "500":
2805
+ description: Internal Server Error
2806
+ schema:
2807
+ $ref: '#/definitions/models.ErrorResponse'
2808
+ security:
2809
+ - Bearer: []
2810
+ summary: Remove location from user
2811
+ tags:
2812
+ - Users
2813
+ /users/{id}/password:
2814
+ put:
2815
+ consumes:
2816
+ - application/json
2817
+ description: 'Changes the authenticated user''s own password. The `{id}` in
2818
+ the path must match the authenticated user''s ID. Requires permission: `users:password:self`'
2819
+ parameters:
2820
+ - description: User ID (must match authenticated user)
2821
+ in: path
2822
+ name: id
2823
+ required: true
2824
+ type: integer
2825
+ - description: Current and new password
2826
+ in: body
2827
+ name: body
2828
+ required: true
2829
+ schema:
2830
+ $ref: '#/definitions/models.ChangePasswordRequest'
2831
+ produces:
2832
+ - application/json
2833
+ responses:
2834
+ "200":
2835
+ description: OK
2836
+ schema:
2837
+ $ref: '#/definitions/models.MessageResponse'
2838
+ "400":
2839
+ description: Invalid request or incorrect current password
2840
+ schema:
2841
+ $ref: '#/definitions/models.ErrorResponse'
2842
+ "401":
2843
+ description: Unauthenticated
2844
+ schema:
2845
+ $ref: '#/definitions/models.ErrorResponse'
2846
+ "403":
2847
+ description: 'Missing permission: users:password:self, or ID mismatch'
2848
+ schema:
2849
+ $ref: '#/definitions/models.ErrorResponse'
2850
+ security:
2851
+ - Bearer: []
2852
+ summary: Change password
2853
+ tags:
2854
+ - Users
2855
+ /users/{id}/resend-verification:
2856
+ post:
2857
+ description: 'Resends the activation email if the user hasn''t used the previous
2858
+ link (expires in 48h). Fails if the account is already verified. Requires
2859
+ permission: `users:create`'
2860
+ parameters:
2861
+ - description: User ID
2862
+ in: path
2863
+ name: id
2864
+ required: true
2865
+ type: integer
2866
+ produces:
2867
+ - application/json
2868
+ responses:
2869
+ "200":
2870
+ description: Verification email sent
2871
+ schema:
2872
+ $ref: '#/definitions/models.MessageResponse'
2873
+ "401":
2874
+ description: Unauthenticated
2875
+ schema:
2876
+ $ref: '#/definitions/models.ErrorResponse'
2877
+ "403":
2878
+ description: 'Missing permission: users:create'
2879
+ schema:
2880
+ $ref: '#/definitions/models.ErrorResponse'
2881
+ "404":
2882
+ description: User not found
2883
+ schema:
2884
+ $ref: '#/definitions/models.ErrorResponse'
2885
+ "409":
2886
+ description: Account already verified
2887
+ schema:
2888
+ $ref: '#/definitions/models.ErrorResponse'
2889
+ security:
2890
+ - Bearer: []
2891
+ summary: Resend verification email
2892
+ tags:
2893
+ - Users
2894
+ /users/{id}/roles:
2895
+ post:
2896
+ consumes:
2897
+ - application/json
2898
+ description: 'Assigns an existing role to a user. Requires permission: `users:roles:manage`'
2899
+ parameters:
2900
+ - description: User ID
2901
+ in: path
2902
+ name: id
2903
+ required: true
2904
+ type: integer
2905
+ - description: Role to assign
2906
+ in: body
2907
+ name: body
2908
+ required: true
2909
+ schema:
2910
+ $ref: '#/definitions/models.AssignRoleRequest'
2911
+ produces:
2912
+ - application/json
2913
+ responses:
2914
+ "200":
2915
+ description: OK
2916
+ schema:
2917
+ $ref: '#/definitions/models.MessageResponse'
2918
+ "400":
2919
+ description: Invalid user ID or request body
2920
+ schema:
2921
+ $ref: '#/definitions/models.ErrorResponse'
2922
+ "401":
2923
+ description: Unauthenticated
2924
+ schema:
2925
+ $ref: '#/definitions/models.ErrorResponse'
2926
+ "403":
2927
+ description: 'Missing permission: users:roles:manage'
2928
+ schema:
2929
+ $ref: '#/definitions/models.ErrorResponse'
2930
+ "500":
2931
+ description: Internal Server Error
2932
+ schema:
2933
+ $ref: '#/definitions/models.ErrorResponse'
2934
+ security:
2935
+ - Bearer: []
2936
+ summary: Assign role to user
2937
+ tags:
2938
+ - Users
2939
+ /users/{id}/roles/{roleId}:
2940
+ delete:
2941
+ description: 'Removes a role from a user. Requires permission: `users:roles:manage`'
2942
+ parameters:
2943
+ - description: User ID
2944
+ in: path
2945
+ name: id
2946
+ required: true
2947
+ type: integer
2948
+ - description: Role ID
2949
+ in: path
2950
+ name: roleId
2951
+ required: true
2952
+ type: integer
2953
+ produces:
2954
+ - application/json
2955
+ responses:
2956
+ "200":
2957
+ description: OK
2958
+ schema:
2959
+ $ref: '#/definitions/models.MessageResponse'
2960
+ "400":
2961
+ description: Invalid user ID or role ID
2962
+ schema:
2963
+ $ref: '#/definitions/models.ErrorResponse'
2964
+ "401":
2965
+ description: Unauthenticated
2966
+ schema:
2967
+ $ref: '#/definitions/models.ErrorResponse'
2968
+ "403":
2969
+ description: 'Missing permission: users:roles:manage'
2970
+ schema:
2971
+ $ref: '#/definitions/models.ErrorResponse'
2972
+ "500":
2973
+ description: Internal Server Error
2974
+ schema:
2975
+ $ref: '#/definitions/models.ErrorResponse'
2976
+ security:
2977
+ - Bearer: []
2978
+ summary: Remove role from user
2979
+ tags:
2980
+ - Users
2981
+ /users/{id}/specialities:
2982
+ post:
2983
+ consumes:
2984
+ - application/json
2985
+ description: 'Assigns an existing speciality to a user. Requires permission:
2986
+ `users:specialities:manage`'
2987
+ parameters:
2988
+ - description: User ID
2989
+ in: path
2990
+ name: id
2991
+ required: true
2992
+ type: integer
2993
+ - description: Speciality to assign
2994
+ in: body
2995
+ name: body
2996
+ required: true
2997
+ schema:
2998
+ $ref: '#/definitions/models.AssignSpecialityRequest'
2999
+ produces:
3000
+ - application/json
3001
+ responses:
3002
+ "200":
3003
+ description: OK
3004
+ schema:
3005
+ $ref: '#/definitions/models.MessageResponse'
3006
+ "400":
3007
+ description: Invalid user ID or request body
3008
+ schema:
3009
+ $ref: '#/definitions/models.ErrorResponse'
3010
+ "401":
3011
+ description: Unauthenticated
3012
+ schema:
3013
+ $ref: '#/definitions/models.ErrorResponse'
3014
+ "403":
3015
+ description: 'Missing permission: users:specialities:manage'
3016
+ schema:
3017
+ $ref: '#/definitions/models.ErrorResponse'
3018
+ "500":
3019
+ description: Internal Server Error
3020
+ schema:
3021
+ $ref: '#/definitions/models.ErrorResponse'
3022
+ security:
3023
+ - Bearer: []
3024
+ summary: Assign speciality to user
3025
+ tags:
3026
+ - Users
3027
+ /users/{id}/specialities/{specialityId}:
3028
+ delete:
3029
+ description: 'Removes a speciality from a user. Requires permission: `users:specialities:manage`'
3030
+ parameters:
3031
+ - description: User ID
3032
+ in: path
3033
+ name: id
3034
+ required: true
3035
+ type: integer
3036
+ - description: Speciality ID
3037
+ in: path
3038
+ name: specialityId
3039
+ required: true
3040
+ type: integer
3041
+ produces:
3042
+ - application/json
3043
+ responses:
3044
+ "200":
3045
+ description: OK
3046
+ schema:
3047
+ $ref: '#/definitions/models.MessageResponse'
3048
+ "400":
3049
+ description: Invalid user ID or speciality ID
3050
+ schema:
3051
+ $ref: '#/definitions/models.ErrorResponse'
3052
+ "401":
3053
+ description: Unauthenticated
3054
+ schema:
3055
+ $ref: '#/definitions/models.ErrorResponse'
3056
+ "403":
3057
+ description: 'Missing permission: users:specialities:manage'
3058
+ schema:
3059
+ $ref: '#/definitions/models.ErrorResponse'
3060
+ "500":
3061
+ description: Internal Server Error
3062
+ schema:
3063
+ $ref: '#/definitions/models.ErrorResponse'
3064
+ security:
3065
+ - Bearer: []
3066
+ summary: Remove speciality from user
3067
+ tags:
3068
+ - Users
3069
+ securityDefinitions:
3070
+ Bearer:
3071
+ description: 'JWT token de autenticaciΓ³n. Formato: "Bearer {token}"'
3072
+ in: header
3073
+ name: Authorization
3074
+ type: apiKey
3075
+ swagger: "2.0"
documentation/M1_integration.md DELETED
@@ -1,177 +0,0 @@
1
- # IntegraciΓ³n M6 ↔ Core API (M1)
2
-
3
- **Host:** `https://api.healthcare.cantero.ar`
4
- **Spec:** `documentation/M1_openapi.yaml`
5
- **Estado:** plan aprobado, pendiente de implementaciΓ³n
6
-
7
- ---
8
-
9
- ## Contexto
10
-
11
- El Core API centraliza autenticaciΓ³n, usuarios, roles, permisos y un event bus para todo el sistema Health Grid. M6 hoy tiene su propio sistema de auth (JWT HS256 con secreto compartido, tokens generados localmente). La integraciΓ³n reemplaza ese sistema por el del Core API.
12
-
13
- ---
14
-
15
- ## Hallazgos clave (previos a implementar)
16
-
17
- ### Estructura del JWT del Core API
18
-
19
- Decodificado de un token real de usuario registrado:
20
-
21
- ```json
22
- {
23
- "user_id": 20,
24
- "permissions": [],
25
- "exp": 1782858312,
26
- "iat": 1782771912
27
- }
28
- ```
29
-
30
- **Diferencias crΓ­ticas respecto al JWT actual de M6:**
31
-
32
- | Campo | JWT M6 actual | JWT Core API |
33
- |---|---|---|
34
- | ID de usuario | `sub` (string) | `user_id` (integer) |
35
- | Rol | `rol` (string: "MEDICO") | No existe |
36
- | Permisos | No existe | `permissions` (array de strings) |
37
- | Algoritmo | HS256 (secreto compartido) | RS256 (clave pΓΊblica via JWKS) |
38
-
39
- El Core API **no incluye nombres de rol en el JWT** β€” embebe permisos directamente. Esto impacta cΓ³mo M6 verifica acceso (ver Fase B).
40
-
41
- ### JWKS β€” verificaciΓ³n sin llamadas a M1
42
-
43
- El Core API expone `GET /.well-known/jwks.json` con la clave pΓΊblica RSA. M6 la descarga una vez, la cachea, y verifica la firma de cada token localmente sin llamar al Core API en cada request. El Core API firma con la clave privada; cualquier mΓ³dulo verifica con la clave pΓΊblica.
44
-
45
- ---
46
-
47
- ## QuΓ© cambia en M6
48
-
49
- ### 1. `app/config.py`
50
-
51
- - Eliminar: `jwt_secret`, `jwt_algorithm`, `jwt_expire_minutes`
52
- - Agregar: `m1_core_url` con default `https://api.healthcare.cantero.ar`
53
- - El secreto compartido desaparece β€” la verificaciΓ³n pasa a ser criptogrΓ‘fica
54
-
55
- ### 2. `app/dependencies.py` β€” `decode_token`
56
-
57
- - Hoy: `jwt.decode(token, settings.jwt_secret, algorithms=["HS256"])`
58
- - DespuΓ©s: descarga JWKS desde `{m1_core_url}/.well-known/jwks.json`, verifica con RS256, extrae `user_id` y `permissions`
59
- - El JWKS se cachea en memoria con TTL (sugerido: 1 hora) para no hacer HTTP en cada request
60
-
61
- ### 3. `app/dependencies.py` β€” `require_roles` β†’ `require_permissions`
62
-
63
- El guard de acceso cambia de chequear un string de rol a chequear si el token contiene un permiso especΓ­fico.
64
-
65
- Hoy:
66
- ```python
67
- require_roles("MEDICO", "ADMINISTRATIVO")
68
- # verifica payload["rol"] in ("MEDICO", "ADMINISTRATIVO")
69
- ```
70
-
71
- DespuΓ©s (dos opciones β€” ver decisiΓ³n pendiente):
72
-
73
- **OpciΓ³n A β€” mapeo permiso β†’ rol interno (mΓ­nimo impacto):**
74
- ```python
75
- # M6 mantiene su concepto de rol internamente
76
- # y deriva el rol desde los permisos del JWT
77
- _PERMISOS_POR_ROL = {
78
- "MEDICO": {"camas:read", "solicitudes:read", ...},
79
- "ADMINISTRATIVO": {"camas:write", "solicitudes:manage", ...},
80
- "LIMPIEZA": {"camas:limpieza", ...},
81
- }
82
- ```
83
-
84
- **OpciΓ³n B β€” guards nativos de permiso (mΓ‘s correcto a largo plazo):**
85
- ```python
86
- require_permissions("camas:read")
87
- # verifica que "camas:read" estΓ© en payload["permissions"]
88
- ```
89
-
90
- La OpciΓ³n B requiere cambiar todos los guards en todos los routers. La OpciΓ³n A es un shim que deja los routers intactos.
91
- **DecisiΓ³n pendiente** (ver secciΓ³n de incΓ³gnitas).
92
-
93
- ### 4. `app/main.py` β€” eliminar endpoint de dev token
94
-
95
- `GET /api/v1/auth/token` genera tokens HS256 propios β€” ya no serΓ‘n vΓ‘lidos cuando M6 valide con JWKS.
96
- Reemplazar con credenciales reales del Core API en `.env` local y secretos de HF Spaces.
97
-
98
- ### 5. `app/integrations/core.py`
99
-
100
- Actualmente vacΓ­o o stub. Agregar cliente HTTP para llamadas al Core API:
101
- - `GET /users/{id}` β€” obtener datos de usuario (nombre, roles) cuando sea necesario
102
- - `POST /auth/refresh` β€” renovar token si M6 necesita actuar en nombre de un usuario
103
-
104
- ---
105
-
106
- ## Plan de implementaciΓ³n por fases
107
-
108
- ### Fase A β€” VerificaciΓ³n de firma RS256 (independiente de permisos)
109
-
110
- Se puede implementar ahora, sin conocer los nombres de permisos.
111
-
112
- 1. Agregar `PyJWT[crypto]` o `python-jose[cryptography]` a `requirements.txt` (verificar cuΓ‘l ya estΓ‘)
113
- 2. Implementar cachΓ© de JWKS en `app/dependencies.py` (dict en mΓ³dulo con timestamp)
114
- 3. Cambiar `decode_token` para usar RS256 + JWKS
115
- 4. Cambiar extracciΓ³n de `sub` β†’ `user_id`
116
- 5. Eliminar `jwt_secret` de `config.py`; agregar `m1_core_url`
117
- 6. Eliminar endpoint dev token de `main.py`
118
- 7. Agregar `M1_CORE_URL` a `.env` y a los secretos de HF Spaces
119
- 8. Actualizar tests: reemplazar tokens HS256 propios por tokens mockeados con la estructura correcta del Core API
120
-
121
- ### Fase B β€” Mapeo de permisos (bloqueada hasta resolver incΓ³gnita #1)
122
-
123
- 9. Definir tabla de mapeo permiso β†’ rol M6 (o migrar a guards de permiso nativos)
124
- 10. Actualizar `require_roles` / crear `require_permissions`
125
- 11. Actualizar tests de autorizaciΓ³n
126
-
127
- ### Fase C β€” Event bus (opcional, posterior)
128
-
129
- El Core API tiene un bus de eventos con suscripciones. M6 podrΓ­a:
130
- - **Publicar** eventos al bus cuando ocurren internaciones, altas, traslados (`POST /events/log`)
131
- - **Suscribirse** a eventos de otros mΓ³dulos (`POST /events/subscriptions`)
132
-
133
- Requiere que M6 tenga un usuario de sistema con permiso `events:log:publish` configurado en el Core API.
134
- No es necesario para la integraciΓ³n de auth β€” se puede hacer en una etapa posterior.
135
-
136
- ---
137
-
138
- ## IncΓ³gnitas bloqueantes
139
-
140
- ### #1 β€” Nombres de permisos para cada rol (bloqueante para Fase B)
141
-
142
- Necesitamos saber quΓ© permisos tiene asignados cada rol del sistema. Con un usuario sin rol asignado, `permissions: []`. Opciones para resolverlo:
143
-
144
- - **OpciΓ³n preferida:** El equipo del Core API asigna el rol MEDICO, ADMINISTRATIVO o LIMPIEZA al usuario ID 20 (`sorondojp@gmail.com`), se obtiene un token nuevo y se decodifica para ver los permisos reales.
145
- - **Alternativa:** El equipo del Core API comparte la lista de permisos por rol directamente.
146
-
147
- La pregunta concreta a hacerles:
148
- > ΒΏQuΓ© permisos (`permission.name`) tienen asignados los roles que corresponden a mΓ©dico, administrativo y personal de limpieza en el sistema?
149
-
150
- ### #2 β€” Nombres exactos de roles en el Core API
151
-
152
- Los roles de M6 son `MEDICO`, `ADMINISTRATIVO`, `LIMPIEZA`. ΒΏEl Core API usa esos mismos strings o nombres distintos (ej: `doctor`, `admin`, `cleaning`)? Esto define si hace falta una tabla de traducciΓ³n.
153
-
154
- ---
155
-
156
- ## Variables de entorno afectadas
157
-
158
- | Variable actual | AcciΓ³n | Nueva variable |
159
- |---|---|---|
160
- | `JWT_SECRET` | Eliminar | β€” |
161
- | `JWT_ALGORITHM` | Eliminar | β€” |
162
- | `JWT_EXPIRE_MINUTES` | Eliminar | β€” |
163
- | β€” | Agregar | `M1_CORE_URL=https://api.healthcare.cantero.ar` |
164
-
165
- En HF Spaces: agregar `M1_CORE_URL` como secreto, eliminar las tres variables de JWT.
166
-
167
- ---
168
-
169
- ## Estado actual
170
-
171
- - [x] Spec analizado (`M1_openapi.yaml`)
172
- - [x] JWT real decodificado β€” estructura conocida (`user_id`, `permissions[]`)
173
- - [x] JWKS endpoint identificado (`/.well-known/jwks.json`)
174
- - [ ] Nombres de permisos por rol β€” **pendiente** (incΓ³gnita #1)
175
- - [ ] Fase A implementada
176
- - [ ] Fase B implementada
177
- - [ ] Credenciales de Core API configuradas en HF Spaces
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
documentation/M6_DISEΓ‘O.md CHANGED
@@ -330,9 +330,28 @@ Tablas principales en PostgreSQL (Supabase): `camas` (incluye quirΓ³fanos), `res
330
 
331
  ## 11. Seguridad
332
 
333
- AutenticaciΓ³n por JWT centralizada en Core (M10). Un middleware en FastAPI valida el token en cada request entrante (`POST /auth/validate-token` contra M10), salvo los webhooks entrantes, que se autentican por el mecanismo que acuerde el Bus de Eventos (secreto compartido o firma). El esquema es `BearerAuth` (HTTP Bearer, formato JWT) y aplica de forma global. La autorizaciΓ³n por rol (quΓ© acciΓ³n puede hacer cada rol) usa los permisos definidos por Core.
334
 
335
- > El spec actual declara el esquema `BearerAuth` pero deja el `security` global vacΓ­o. Hay que declarar `security: [{ BearerAuth: [] }]` a nivel raΓ­z para que la protecciΓ³n sea explΓ­cita en el contrato.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
336
 
337
  ---
338
 
 
330
 
331
  ## 11. Seguridad
332
 
333
+ AutenticaciΓ³n centralizada en Core (M10), integrada (no mockeada). `app/config.py::auth_mode` conmuta entre dos modos:
334
 
335
+ - **`mock`** (default): M6 firma y valida sus propios JWT HS256 (`app/dependencies.py::create_access_token`/`decode_token`), con un claim `rol` directo. Es el comportamiento histΓ³rico, usado en dev/tests sin depender del Core.
336
+ - **`core`**: el JWT lo emite el Core real (`https://api.healthcare.cantero.ar` en el entorno compartido). Verificado en vivo: el Core firma con **RS256** y publica sus claves en `GET /.well-known/jwks.json`; el payload del token es `{exp, iat, permissions[], user_id}` β€” **no lleva `iss`/`aud` ni el nombre del rol**. `app/integrations/core_auth.py::verify_core_token` valida la firma localmente contra el JWKS cacheado (`get_signing_key`, TTL `jwks_cache_ttl_seconds`), sin round-trip a `/auth/validate` por request (ese endpoint solo devuelve `{user_id, valid}`, no roles).
337
+
338
+ **ResoluciΓ³n de rol (el token no lo trae):** `core_auth.resolve_user_roles(user_id)` consulta `GET /roles` con la cuenta de servicio de M6 (`core_service_email`/`core_service_password`), arma un Γ­ndice `user_id β†’ [nombres de rol de Core]` cacheado (TTL `core_roles_cache_ttl_seconds`), y `core_auth.map_core_roles_to_internal` lo traduce al rol interno de M6 vΓ­a la tabla `CORE_ROLE_TO_INTERNAL`:
339
+
340
+ | Rol Core | Rol interno M6 |
341
+ |---|---|
342
+ | `admin_internacion` | `ADMINISTRATIVO` |
343
+ | `Medico` | `MEDICO` |
344
+ | `limpieza` | `LIMPIEZA` |
345
+ | `admin` | `ADMINISTRATIVO` (super-admin del Core) |
346
+ | cualquier otro | sin acceso a M6 β†’ `403` |
347
+
348
+ Este mecanismo (lookup de `/roles` cacheado, no `GET /users/{id}`) se eligiΓ³ porque la cuenta de servicio de M6 hoy solo tiene el permiso `roles:read` en el Core compartido, no `users:read`. `get_current_user` (`app/dependencies.py`) devuelve la misma forma `{"sub", "rol"}` en ambos modos, asΓ­ que `require_roles`, la auditorΓ­a y los routers no distinguen modo.
349
+
350
+ **Llamadas salientes:** la misma cuenta de servicio (`core_auth.get_service_token`) autentica las llamadas de M6 a M1/M2/M7/M10 (adjuntado automΓ‘tico en `app/integrations/_base.py::_headers`), incluidas las disparadas por webhooks entrantes donde no hay usuario humano.
351
+
352
+ **Fuera de alcance de esta integraciΓ³n:**
353
+ - Permisos granulares (`camas:read`, etc.) β€” el Core no expone `permissions:manage` a la cuenta de servicio hoy; migrar `require_roles` a permisos cuando eso cambie.
354
+ - AutenticaciΓ³n de webhooks entrantes (`/webhooks/*` sigue exigiendo JWT de usuario) β€” pendiente acordar secreto compartido/firma con el Bus de Eventos.
355
 
356
  ---
357
 
documentation/roles.md CHANGED
@@ -25,7 +25,7 @@ No hay rol `SISTEMA` autenticado por JWT: los eventos disparados por webhooks en
25
  - **MEDICO es de solo lectura.** NingΓΊn endpoint de escritura (`POST`/`PATCH`/`DELETE`) sobre camas, quirΓ³fanos o solicitudes acepta el rol MEDICO. La ΓΊnica excepciΓ³n intencional es crear reservas de cirugΓ­a β€” ver Β§3.
26
  - **ADMINISTRATIVO tiene control total.** Es el ΓΊnico rol que puede dar de alta/baja camas y quirΓ³fanos, asignar pacientes, resolver solicitudes y modificar reservas.
27
  - **LIMPIEZA estΓ‘ acotado al mΓ­nimo necesario.** Ve el mapa completo de camas (para saber dΓ³nde estΓ‘ parado y planificar), pero solo puede ejecutar una transiciΓ³n de estado muy especΓ­fica. La restricciΓ³n se aplica **a nivel de servicio** (`app/services/cama_service.py`), no solo en el frontend β€” un request directo a la API con un JWT de LIMPIEZA que intente otra cosa es rechazado igual.
28
- - **La autorizaciΓ³n es por rol, no por permisos granulares.** `require_roles(*roles)` es un dependency de FastAPI que compara `payload["rol"]` contra una lista fija por endpoint. No hay un sistema de permisos (`camas:read`, `camas:write`, etc.) β€” eso es parte del plan de integraciΓ³n con el Core API de auth (M10), documentado en `documentation/M1_integration.md`, todavΓ­a no ejecutado.
29
 
30
  ---
31
 
@@ -104,11 +104,20 @@ Los endpoints bajo `/webhooks/*` (recepciΓ³n de eventos de M1 HCE, M9 Monitoreo,
104
 
105
  ## 5. Testing
106
 
107
- Los tests de autorizaciΓ³n por rol viven junto a los tests de cada router (`tests/test_camas.py`, `tests/test_quirofanos.py`, `tests/test_solicitudes.py`, `tests/test_auditoria.py`), usando los fixtures `admin_headers`, `medico_headers`, `limpieza_headers` de `tests/conftest.py`. Cada endpoint restringido tiene al menos un test que verifica `403` para el/los rol(es) sin permiso, y un test de happy path para el rol permitido.
108
 
109
  ---
110
 
111
- ## 6. Fuera de alcance / pendiente
112
 
113
- - **Permisos granulares vΓ­a Core API (M10).** El JWT del Core API real no transporta un campo `rol` sino un array `permissions[]`. Migrar `require_roles` a un modelo de permisos (o a un shim que derive el rol interno desde los permisos) es el trabajo descripto en `documentation/M1_integration.md`, todavΓ­a no ejecutado.
114
- - **AutenticaciΓ³n de webhooks entrantes.** Hoy no hay verificaciΓ³n de origen en `/webhooks/*` mΓ‘s allΓ‘ de lo que ya documente cada integraciΓ³n puntual. Pendiente acordar mecanismo (secreto compartido o firma) con el Bus de Eventos de Core.
 
 
 
 
 
 
 
 
 
 
25
  - **MEDICO es de solo lectura.** NingΓΊn endpoint de escritura (`POST`/`PATCH`/`DELETE`) sobre camas, quirΓ³fanos o solicitudes acepta el rol MEDICO. La ΓΊnica excepciΓ³n intencional es crear reservas de cirugΓ­a β€” ver Β§3.
26
  - **ADMINISTRATIVO tiene control total.** Es el ΓΊnico rol que puede dar de alta/baja camas y quirΓ³fanos, asignar pacientes, resolver solicitudes y modificar reservas.
27
  - **LIMPIEZA estΓ‘ acotado al mΓ­nimo necesario.** Ve el mapa completo de camas (para saber dΓ³nde estΓ‘ parado y planificar), pero solo puede ejecutar una transiciΓ³n de estado muy especΓ­fica. La restricciΓ³n se aplica **a nivel de servicio** (`app/services/cama_service.py`), no solo en el frontend β€” un request directo a la API con un JWT de LIMPIEZA que intente otra cosa es rechazado igual.
28
+ - **La autorizaciΓ³n es por rol, no por permisos granulares.** `require_roles(*roles)` es un dependency de FastAPI que compara `payload["rol"]` contra una lista fija por endpoint. No hay un sistema de permisos (`camas:read`, `camas:write`, etc.) β€” el Core (M10) no expone hoy `permissions:manage` a la cuenta de servicio de M6 para darlos de alta. La integraciΓ³n con el Core ya estΓ‘ ejecutada (ver Β§6): lo que queda pendiente es especΓ­ficamente migrar de rol a permisos granulares.
29
 
30
  ---
31
 
 
104
 
105
  ## 5. Testing
106
 
107
+ Los tests de autorizaciΓ³n por rol viven junto a los tests de cada router (`tests/test_camas.py`, `tests/test_quirofanos.py`, `tests/test_solicitudes.py`, `tests/test_auditoria.py`), usando los fixtures `admin_headers`, `medico_headers`, `limpieza_headers` de `tests/conftest.py` (modo mock, HS256). El flujo de integraciΓ³n real con el Core (verificaciΓ³n JWKS, resoluciΓ³n y mapeo de rol) tiene su propia suite en `tests/test_core_auth.py`. Cada endpoint restringido tiene al menos un test que verifica `403` para el/los rol(es) sin permiso, y un test de happy path para el rol permitido.
108
 
109
  ---
110
 
111
+ ## 6. IntegraciΓ³n con el Core (M10)
112
 
113
+ La integraciΓ³n con el Core real ya estΓ‘ implementada, detrΓ‘s del flag `AUTH_MODE` (`app/config.py`) β€” `mock` (default) mantiene el JWT propio descripto en este documento; `core` valida contra el Core. Detalle tΓ©cnico completo en `M6_DISEΓ‘O.md Β§11`; resumen:
114
+
115
+ - El JWT del Core (verificado en vivo contra `https://api.healthcare.cantero.ar`) **no transporta un campo `rol` ni `permissions` utilizables como rol** β€” el payload es `{exp, iat, permissions[], user_id}`, y `permissions[]` son strings de otro dominio (ej. `events:log:publish`), no permisos de M6. El rol se resuelve con una llamada aparte a `GET /roles` (`app/integrations/core_auth.py::resolve_user_roles`), cacheada.
116
+ - Mapeo Core β†’ M6 (`CORE_ROLE_TO_INTERNAL` en `core_auth.py`): roles de Core `admin_internacion` β†’ `ADMINISTRATIVO`, `Medico` β†’ `MEDICO`, `limpieza` β†’ `LIMPIEZA`, `admin` β†’ `ADMINISTRATIVO`. Estos tres roles de M6 (`admin_internacion`, `limpieza`, mΓ‘s el ya existente `Medico`) se dieron de alta en el Core compartido vΓ­a `POST /roles`.
117
+ - `require_roles`, la capa de servicio y la auditorΓ­a no cambiaron β€” `get_current_user` devuelve la misma forma `{"sub", "rol"}` en ambos modos.
118
+
119
+ ### Fuera de alcance / pendiente
120
+
121
+ - **Permisos granulares vΓ­a Core.** El Core no expone `permissions:manage` a la cuenta de servicio de M6 hoy (`POST /permissions` β†’ `403`), asΓ­ que no se pueden dar de alta permisos propios de M6 (`camas:read`, etc.). Migrar `require_roles` a un modelo de permisos queda pendiente de esa habilitaciΓ³n.
122
+ - **Lookup de rol mΓ‘s fresco (`GET /users/{id}`).** El mecanismo actual (`GET /roles` cacheado, TTL `core_roles_cache_ttl_seconds`) trae el padrΓ³n completo y un usuario reciΓ©n asignado a un rol tarda hasta el TTL en verse. `GET /users/{id}` serΓ­a mΓ‘s directo pero requiere el permiso `users:read`, no otorgado hoy a la cuenta de servicio.
123
+ - **AutenticaciΓ³n de webhooks entrantes.** Hoy no hay verificaciΓ³n de origen en `/webhooks/*` mΓ‘s allΓ‘ de lo que ya documente cada integraciΓ³n puntual β€” siguen exigiendo un JWT de usuario, que los emisores reales (M1/M9/M2) no tienen. Pendiente acordar mecanismo (secreto compartido o firma) con el Bus de Eventos de Core.
tests/test_core_auth.py ADDED
@@ -0,0 +1,252 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ Tests de la integraciΓ³n de autenticaciΓ³n con el Core (M10): verificaciΓ³n de
3
+ JWT vΓ­a JWKS, resoluciΓ³n/mapeo de rol y el flujo completo de
4
+ `get_current_user` bajo `auth_mode="core"`.
5
+
6
+ No golpean el Core real: se stubea la fuente de datos (fetch de JWKS y de
7
+ `GET /roles`), pero la verificaciΓ³n de firma RS256 corre de punta a punta
8
+ contra un keypair de test β€” no se mockea `verify_core_token` en sΓ­.
9
+
10
+ Los tests de modo mock (`admin_headers`/`medico_headers`/`limpieza_headers`
11
+ en `conftest.py`) siguen intactos y cubren el comportamiento HS256 actual;
12
+ este mΓ³dulo cubre exclusivamente el camino nuevo introducido por la
13
+ integraciΓ³n con Core.
14
+ """
15
+ import time
16
+
17
+ import pytest
18
+ from cryptography.hazmat.primitives import serialization
19
+ from cryptography.hazmat.primitives.asymmetric import rsa
20
+ from fastapi import HTTPException
21
+ from jose import jwk
22
+ from jose import jwt as jose_jwt
23
+
24
+ from app.config import settings
25
+ from app.dependencies import _get_current_user_core
26
+ from app.integrations import core_auth
27
+
28
+ _TEST_KID = "test-kid-1"
29
+
30
+
31
+ @pytest.fixture(scope="module")
32
+ def rsa_keypair():
33
+ private_key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
34
+ private_pem = private_key.private_bytes(
35
+ encoding=serialization.Encoding.PEM,
36
+ format=serialization.PrivateFormat.PKCS8,
37
+ encryption_algorithm=serialization.NoEncryption(),
38
+ ).decode()
39
+ public_pem = (
40
+ private_key.public_key()
41
+ .public_bytes(
42
+ encoding=serialization.Encoding.PEM,
43
+ format=serialization.PublicFormat.SubjectPublicKeyInfo,
44
+ )
45
+ .decode()
46
+ )
47
+ return private_pem, public_pem
48
+
49
+
50
+ def _make_token(private_pem: str, user_id: int, permissions=None, exp_delta=3600, kid=_TEST_KID):
51
+ now = int(time.time())
52
+ payload = {
53
+ "user_id": user_id,
54
+ "iat": now,
55
+ "exp": now + exp_delta,
56
+ "permissions": permissions or [],
57
+ }
58
+ return jose_jwt.encode(payload, private_pem, algorithm="RS256", headers={"kid": kid})
59
+
60
+
61
+ def _stub_jwks(monkeypatch, public_pem, kid=_TEST_KID):
62
+ jwk_dict = jwk.construct(public_pem, algorithm="RS256").to_dict()
63
+ jwk_dict["kid"] = kid
64
+ monkeypatch.setattr(core_auth, "_fetch_jwks", lambda: {"keys": [jwk_dict]})
65
+
66
+
67
+ def _stub_roles(monkeypatch, mapping: dict):
68
+ monkeypatch.setattr(core_auth, "_fetch_roles_index", lambda: mapping)
69
+
70
+
71
+ @pytest.fixture(autouse=True)
72
+ def _reset_core_caches():
73
+ """Evita que el cache de un test contamine al siguiente."""
74
+ core_auth._jwks_cache["keys_by_kid"] = {}
75
+ core_auth._jwks_cache["fetched_at"] = 0.0
76
+ core_auth._roles_index_cache["user_id_to_roles"] = {}
77
+ core_auth._roles_index_cache["fetched_at"] = 0.0
78
+ yield
79
+
80
+
81
+ @pytest.fixture
82
+ def core_mode(monkeypatch):
83
+ monkeypatch.setattr(settings, "auth_mode", "core")
84
+
85
+
86
+ # ─── verify_core_token ──────────────────────────────────────────────────────
87
+
88
+
89
+ def test_verify_core_token_ok(rsa_keypair, monkeypatch):
90
+ private_pem, public_pem = rsa_keypair
91
+ _stub_jwks(monkeypatch, public_pem)
92
+ token = _make_token(private_pem, user_id=42)
93
+
94
+ payload = core_auth.verify_core_token(token)
95
+
96
+ assert payload["user_id"] == 42
97
+
98
+
99
+ def test_verify_core_token_firma_invalida(rsa_keypair, monkeypatch):
100
+ _, public_pem = rsa_keypair
101
+ _stub_jwks(monkeypatch, public_pem)
102
+ # Firmado con una clave distinta a la publicada en el JWKS stubeado.
103
+ otra_private_pem, _ = _make_other_keypair()
104
+ token = _make_token(otra_private_pem, user_id=42)
105
+
106
+ with pytest.raises(ValueError):
107
+ core_auth.verify_core_token(token)
108
+
109
+
110
+ def _make_other_keypair():
111
+ private_key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
112
+ private_pem = private_key.private_bytes(
113
+ encoding=serialization.Encoding.PEM,
114
+ format=serialization.PrivateFormat.PKCS8,
115
+ encryption_algorithm=serialization.NoEncryption(),
116
+ ).decode()
117
+ public_pem = (
118
+ private_key.public_key()
119
+ .public_bytes(
120
+ encoding=serialization.Encoding.PEM,
121
+ format=serialization.PublicFormat.SubjectPublicKeyInfo,
122
+ )
123
+ .decode()
124
+ )
125
+ return private_pem, public_pem
126
+
127
+
128
+ def test_verify_core_token_expirado(rsa_keypair, monkeypatch):
129
+ private_pem, public_pem = rsa_keypair
130
+ _stub_jwks(monkeypatch, public_pem)
131
+ token = _make_token(private_pem, user_id=42, exp_delta=-10)
132
+
133
+ with pytest.raises(ValueError):
134
+ core_auth.verify_core_token(token)
135
+
136
+
137
+ def test_verify_core_token_kid_desconocido(rsa_keypair, monkeypatch):
138
+ _, public_pem = rsa_keypair
139
+ _stub_jwks(monkeypatch, public_pem, kid="otro-kid-publicado")
140
+ private_pem, _ = rsa_keypair
141
+ token = _make_token(private_pem, user_id=42, kid=_TEST_KID)
142
+
143
+ with pytest.raises(ValueError):
144
+ core_auth.verify_core_token(token)
145
+
146
+
147
+ def test_verify_core_token_malformado():
148
+ with pytest.raises(ValueError):
149
+ core_auth.verify_core_token("esto-no-es-un-jwt")
150
+
151
+
152
+ # ─── map_core_roles_to_internal ─────────────────────────────────────────────
153
+
154
+
155
+ @pytest.mark.parametrize(
156
+ "role_names,expected",
157
+ [
158
+ (["admin_internacion"], "ADMINISTRATIVO"),
159
+ (["Medico"], "MEDICO"),
160
+ (["limpieza"], "LIMPIEZA"),
161
+ (["admin"], "ADMINISTRATIVO"),
162
+ (["Enfermero"], None),
163
+ (["app", "role_manager"], None),
164
+ ([], None),
165
+ (["limpieza", "admin_internacion"], "ADMINISTRATIVO"), # precedencia
166
+ (["limpieza", "Medico"], "MEDICO"),
167
+ ],
168
+ )
169
+ def test_map_core_roles_to_internal(role_names, expected):
170
+ assert core_auth.map_core_roles_to_internal(role_names) == expected
171
+
172
+
173
+ # ─── get_current_user (flujo completo, auth_mode="core") ───────────────────
174
+
175
+
176
+ def test_get_current_user_core_administrativo(rsa_keypair, monkeypatch, core_mode):
177
+ private_pem, public_pem = rsa_keypair
178
+ _stub_jwks(monkeypatch, public_pem)
179
+ _stub_roles(monkeypatch, {7: ["admin_internacion"]})
180
+ token = _make_token(private_pem, user_id=7)
181
+
182
+ user = _get_current_user_core(token)
183
+
184
+ assert user["sub"] == "7"
185
+ assert user["rol"] == "ADMINISTRATIVO"
186
+
187
+
188
+ def test_get_current_user_core_medico(rsa_keypair, monkeypatch, core_mode):
189
+ private_pem, public_pem = rsa_keypair
190
+ _stub_jwks(monkeypatch, public_pem)
191
+ _stub_roles(monkeypatch, {9: ["Medico"]})
192
+ token = _make_token(private_pem, user_id=9)
193
+
194
+ user = _get_current_user_core(token)
195
+
196
+ assert user["rol"] == "MEDICO"
197
+
198
+
199
+ def test_get_current_user_core_limpieza(rsa_keypair, monkeypatch, core_mode):
200
+ private_pem, public_pem = rsa_keypair
201
+ _stub_jwks(monkeypatch, public_pem)
202
+ _stub_roles(monkeypatch, {8: ["limpieza"]})
203
+ token = _make_token(private_pem, user_id=8)
204
+
205
+ user = _get_current_user_core(token)
206
+
207
+ assert user["rol"] == "LIMPIEZA"
208
+
209
+
210
+ def test_get_current_user_core_rol_no_mapeado_403(rsa_keypair, monkeypatch, core_mode):
211
+ private_pem, public_pem = rsa_keypair
212
+ _stub_jwks(monkeypatch, public_pem)
213
+ _stub_roles(monkeypatch, {10: ["Enfermero"]})
214
+ token = _make_token(private_pem, user_id=10)
215
+
216
+ with pytest.raises(HTTPException) as exc_info:
217
+ _get_current_user_core(token)
218
+
219
+ assert exc_info.value.status_code == 403
220
+
221
+
222
+ def test_get_current_user_core_sin_rol_403(rsa_keypair, monkeypatch, core_mode):
223
+ private_pem, public_pem = rsa_keypair
224
+ _stub_jwks(monkeypatch, public_pem)
225
+ _stub_roles(monkeypatch, {}) # usuario sin roles asignados en el Core
226
+ token = _make_token(private_pem, user_id=11)
227
+
228
+ with pytest.raises(HTTPException) as exc_info:
229
+ _get_current_user_core(token)
230
+
231
+ assert exc_info.value.status_code == 403
232
+
233
+
234
+ def test_get_current_user_core_token_invalido_401(rsa_keypair, monkeypatch, core_mode):
235
+ _, public_pem = rsa_keypair
236
+ _stub_jwks(monkeypatch, public_pem)
237
+
238
+ with pytest.raises(HTTPException) as exc_info:
239
+ _get_current_user_core("token-basura")
240
+
241
+ assert exc_info.value.status_code == 401
242
+
243
+
244
+ def test_get_current_user_core_expirado_401(rsa_keypair, monkeypatch, core_mode):
245
+ private_pem, public_pem = rsa_keypair
246
+ _stub_jwks(monkeypatch, public_pem)
247
+ token = _make_token(private_pem, user_id=12, exp_delta=-10)
248
+
249
+ with pytest.raises(HTTPException) as exc_info:
250
+ _get_current_user_core(token)
251
+
252
+ assert exc_info.value.status_code == 401