Gestion de Catalogos Maestros (Backoffice)

1. Definicion y Proposito

Este modulo administra la fuente unica de catalogos que consume toda la plataforma (registro, buscador, agenda, validaciones y dashboards).

• Evita texto libre y duplicados.
• Mantiene jerarquias consistentes entre paises y especialidades.
• Controla habilitacion/deshabilitacion sin perder historico.

2. Modelo Canonico de Catalogos

2.1 Taxonomia medica (2 niveles obligatorios)

• Nivel 0: Area medica.
• Nivel 1: Especialidad.
• No se usa tercer nivel en el modelo transaccional.

2.2 Geografia (canonico, multi-pais)

• Nivel 0: Pais (country).
• Nivel 1: Region administrativa (region) (Departamento / Estado / Provincia).
• Nivel 2: Localidad (locality) (Municipio / Ciudad / Partido / Comuna).

El backend conserva nombres tecnicos estables (level + node_type) y la UI renderiza etiquetas por pais.

2.3 Etiquetas por pais (display labels)

• GT: region=Departamento, locality=Municipio
• MX: region=Estado, locality=Municipio
• CO: region=Departamento, locality=Municipio
• AR: region=Provincia, locality=Municipio/Partido (segun catalogo cargado)

Recomendacion: exponer /api/v1/meta/location-levels?country_code=XX para que frontend no codifique reglas hardcoded.

3. Logica Visual y Procesos

3.1 Flujo (Miro)

3.1.1 Pais

3.1.2 Departamento/Region

3.1.3 Municipalidad/Localidad

3.2 Resumen textual (fallback)

• Pais: alta individual, valida ISO alpha-2 unico.
• Region/Localidad: alta individual y bulk, validando padre obligatorio.
• Geografia: Pais -> Region -> Localidad.
• Taxonomia: Area -> Especialidad.
• Borrado logico preferido (enabled=false) para no romper referencias.

4. Actores y Permisos (RBAC)

Actor	Permiso
SUPERADMIN	Control total sobre Geo, Taxonomia y Seguros
CATALOG_ADMIN	CRUD operativo de catalogos

5. Reglas de Negocio

• BR-CAT-01: No se puede eliminar nodo geo con hijos o referencias; usar enabled=false.
• BR-CAT-02: Cascada estricta en selectores (pais -> region -> localidad).
• BR-CAT-03: Solo especialidades creadas por admin.
• BR-CAT-04: country.code debe ser ISO 3166-1 alpha-2 y unico.
• BR-CAT-05: Normalizar nombre + slug para busqueda.
• BR-CAT-06: Si un pais se deshabilita, el usuario debe reconfirmar pais en la siguiente sesion.

6. Diccionario UX-Tecnico

[CAT-100] Dashboard catalogos

Elemento UI	ID tecnico	Comportamiento
Card Geografia	link_geo	Redirige a CAT-200
Card Especialidades	link_specialties	Redirige a CAT-300
Card Aseguradoras	link_insurances	Redirige a CAT-400

[CAT-200] Geografia

Elemento UI	ID tecnico	Validacion	Error
Nombre Pais	country_name	Obligatorio y unico	"Pais ya registrado"
Codigo ISO	iso_code	2 caracteres	"Formato ISO invalido"
Lista Bulk	items_array	Minimo 1 item	"La lista no puede estar vacia"
Boton eliminar item	ui_remove_item	Solo cliente antes de persistir	N/A

[CAT-300] Taxonomia (2 niveles)

Elemento UI	ID tecnico	Validacion	Error
Nombre	catalog_name	Unico en nivel	"Nombre duplicado"
Descripcion	description	Max 250 chars	"Descripcion muy larga"
Imagen portada	image_url	SVG/WebP	"Archivo no soportado"
Relacion padre	parent_id	Obligatorio para especialidad	"Debe seleccionar area"

7. Acciones Tecnicas (Backend)

1. Soft-disable por defecto (enabled=false) antes que borrado fisico.
2. Invalida cache de catalogos despues de cada mutacion.
3. Bulk transaccional para regiones/localidades.
4. No crear especialidad si su area padre esta inactiva.
5. Resolver labels por pais desde catalogo, no por condicionales hardcoded en frontend.
6. Auditoria obligatoria con trace_id, user_id, ip, user_agent.

8. Contrato API (OpenAPI)

Endpoint	Metodo	Proposito
/api/v1/admin/catalogs/geo	GET	Listar geografia por level, country_code, parent_id, enabled
/api/v1/admin/catalogs/geo	POST	Crear nodo geo generico
/api/v1/admin/catalogs/geo/countries	POST	Crear pais
/api/v1/admin/catalogs/geo/departments	POST	Crear region (individual)
/api/v1/admin/catalogs/geo/departments/bulk	POST	Crear regiones en lote
/api/v1/admin/catalogs/geo/municipalities	POST	Crear localidad (individual)
/api/v1/admin/catalogs/geo/municipalities/bulk	POST	Crear localidades en lote
/api/v1/admin/catalogs/geo/{id}	PATCH	Actualizar nombre/estado
/api/v1/admin/catalogs/geo/{id}	DELETE	Eliminar si no tiene hijos/referencias
/api/v1/admin/catalogs/specialties	GET/POST	Listar/crear taxonomia medica
/api/v1/meta/countries	GET	Lista publica de paises habilitados
/api/v1/meta/location-levels	GET	Labels de region/localidad por pais

9. NFR, Seguridad y Observabilidad

• P95 lectura catalogos < 300ms; bulk < 800ms.
• Cache hit rate > 80% para geo y taxonomia.
• Rate limit soft en bulk: 10 ops/min por usuario admin.
• Eventos: CAT_GEO_CREATED, CAT_GEO_UPDATED, CAT_SPECIALTY_CREATED, CAT_SPECIALTY_UPDATED.
• Logs minimos: trace_id, user_id, role, resource, operation, bulk_size.

10. Checklist QA

• Crear pais con ISO unico.
• Bulk region/localidad hace rollback si un item falla.
• No permite borrar nodo con hijos o referencias.
• Taxonomia bloquea especialidad cuando area padre esta inactiva.
• Selector usa labels por pais desde /meta/location-levels.
• Cache se invalida correctamente tras mutacion.

11. Trazabilidad

• Swagger UI: /swagger.html (acceso desde /swagger) y contrato YAML en /openapi.yaml.
• Relacionados: registro.md, buscador.md, localizacion.md, esquema-de-base-de-datos.md.

12. Gobernanza de catalogos (operación y control)

12.1 Flujo de cambio

1. Solicitud de cambio (ticket con motivo de negocio/regulatorio).
2. Revisión funcional (PO) y técnica (Backend Lead).
3. Ejecución por CATALOG_ADMIN o SUPERADMIN.
4. Verificación en staging y publicación controlada.
5. Registro en audit_logs y comunicación de impacto.

12.2 Controles obligatorios

• Todo cambio en catálogos debe registrar before/after, reason, approver.
• Cambios masivos (bulk) requieren doble aprobación (maker-checker).
• No se permite hard delete si hay referencias activas; usar enabled=false.
• Toda mutación crítica debe tener rollback documentado (snapshot lógico o script inverso).

12.3 Versionado de catálogo

• Cada cambio relevante incrementa catalog_version (ej. geo: 2026.02.13.1).
• Frontend puede invalidar caché por versión sin redeploy.
• Historial de versiones debe ser consultable por backoffice para auditoría.