Gestion de Permisos (RBAC)

Este documento define la fuente oficial de permisos para frontend y backend.

1. Roles oficiales

Rol	Clave	Descripcion
Paciente	PATIENT	Busca servicios, agenda citas, paga, califica y administra favoritos.
Profesional de salud	DOCTOR	Gestiona agenda/perfil profesional, cupones y contenido publico.
Administrador de entidad	ENTITY_ADMIN	Gestiona sedes, convenios, personal operativo y agenda de entidad.
Administrador de catalogos	CATALOG_ADMIN	Administra taxonomia medica y geografia (pais/departamento/municipio).
Super administrador	SUPERADMIN	Moderacion/auditoria, seguridad y acceso a operaciones criticas.

Notas:

• Los roles son acumulativos: un usuario puede tener PATIENT + DOCTOR + ENTITY_ADMIN.
• Todo usuario inicia con PATIENT; los roles adicionales se otorgan por flujo de onboarding/auditoria.

2. Matriz de acceso (alto nivel)

Dominio/Modulo	PATIENT	DOCTOR	ENTITY_ADMIN	CATALOG_ADMIN	SUPERADMIN
Auth y perfil comun (/auth/*, /profiles/me)	Own	Own	Own	Own	All
Perfil profesional (/profiles/doctor)	-	Own C/U	Read afiliados	-	All
Entidades y convenios (/entities, /insurance-agreements)	Read	Read	Own C/U	-	All
Citas (/appointments)	Own C/R/U	Own R/U	Entity R/U	-	All
Disponibilidad (/availability/*)	Read	Own C/U	Entity C/U	-	All
Reseñas (/reviews)	Own C/R	Read	Read	-	Moderar
Cupones (/professional/coupons, /coupons/*)	Validate/Apply	Own C/R/U	Own C/R/U	-	Aprobar/Rechazar
Blog profesional (/professional/posts)	Read publico	Own C/R/U	Own C/R/U	-	Moderar
Catalogos (/admin/catalogs/*, /meta/*)	Read	Read	Read	C/R/U	C/R/U
Auditoria (/admin/audits/*)	-	-	-	-	C/R/U
Soporte (/help/tickets)	C	C	C	C	C/R/U

2.1 Matriz RBAC detallada (recurso/accion/condicion)

Recurso	Accion	Roles permitidos	Condicion de autorizacion
profiles.me	read, update	Todos autenticados	subject_id == profile.user_id
profiles.doctor	create, update	DOCTOR, SUPERADMIN	Propio perfil o override admin
entities	create	ENTITY_ADMIN, SUPERADMIN	Usuario verificado + terminos aceptados
entities	update	ENTITY_ADMIN, SUPERADMIN	Scope por entity_id afiliada
catalogs.geo	create, update, disable	CATALOG_ADMIN, SUPERADMIN	No romper referencias; audit obligatorio
catalogs.taxonomy	create, update, disable	CATALOG_ADMIN, SUPERADMIN	Solo 2 niveles (area/especialidad)
appointments	create	PATIENT, SUPERADMIN	Slot disponible + convenio valido
appointments	update, cancel	PATIENT, DOCTOR, ENTITY_ADMIN, SUPERADMIN	Ownership o tenant entity
reviews	create	PATIENT	Solo cita finalizada y no duplicada
reviews	moderate	SUPERADMIN	Auditoria de decision obligatoria
coupons	create, update	DOCTOR, ENTITY_ADMIN, SUPERADMIN	Owner del coupon o tenant scope
audits	list, resolve	SUPERADMIN	reason, decision, trace_id requeridos
notifications.preferences	update	Todos autenticados	Solo preferencias propias

Convencion de acciones: create/read/update/delete/disable/moderate/resolve.
En catalogos se prioriza disable (soft-delete) sobre delete.

3. Reglas de autorizacion obligatorias

1. Least privilege: si no existe regla explicita, el acceso es denegado (403).
2. Ownership check: endpoints Own requieren validar resource.owner_id == subject_id.
3. Tenant scope: ENTITY_ADMIN solo opera recursos de sus entidades.
4. Estados de auditoria: recursos PENDING/REJECTED/SUSPENDED no son publicables en buscador.
5. Soft delete primero: para catalogos y contenido administrativo, preferir enabled=false antes de eliminar.
6. Trazabilidad: toda decision de permisos/auditoria debe registrar who/when/why en audit_logs.

4. Implementacion en Go (DDD + Clean)

4.1 Capa HTTP (interfaces/http)

• Middleware JWT: autentica, valida firma/expiracion y carga claims (sub, roles, country_code, locale).
• Middleware RBAC: valida rol requerido por endpoint.
• Guard de ownership/tenant: valida alcance de recurso antes de llamar caso de uso.

// ejemplo simplificado
func RequireRoles(allowed ...string) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            claims := auth.ClaimsFromContext(r.Context())
            if !auth.HasAnyRole(claims.Roles, allowed...) {
                http.Error(w, "forbidden", http.StatusForbidden)
                return
            }
            next.ServeHTTP(w, r)
        })
    }
}

4.2 Capa aplicacion (use cases)

• Validaciones de negocio y ownership no deben quedarse solo en middleware.
• Cada caso de uso sensible debe revalidar permisos de dominio.

4.3 Capa dominio

• Las entidades no conocen JWT ni framework HTTP.
• Las politicas de acceso se modelan como reglas/aprobaciones en aplicacion + servicios de dominio.

5. Respuesta estandar de errores de permiso

Caso	HTTP	Codigo sugerido
Sin token / token invalido	401	UNAUTHORIZED
Rol insuficiente	403	FORBIDDEN
Recurso fuera de tenant	403	TENANT_FORBIDDEN
Recurso inexistente	404	NOT_FOUND

6. Checklist de implementacion

• Todos los endpoints en OpenAPI tienen security y rol esperado documentado.
• Endpoints Own validan ownership en middleware y use case.
• Eventos sensibles (ROLE_GRANTED, ROLE_REVOKED, AUDIT_DECISION) se auditan.
• Tests de autorizacion cubren 401, 403, 404 y casos cross-tenant.
• Frontend oculta acciones por rol, pero backend sigue siendo fuente de verdad.