# Navegacion Rapida de API
# clinica-veterinaria
# Creado: 2026-01-16

version: "1.0.0"
proyecto: "clinica-veterinaria"

# ============================================================================
# NOTA: API Pendiente de Implementacion
# ============================================================================
# Este proyecto actualmente tiene solo DDL de base de datos.
# Los endpoints de API se implementaran en fases posteriores del backend.
# Esta documentacion describe la estructura planificada de la API.

# ============================================================================
# ENDPOINTS POR MODULO (Planificados)
# ============================================================================
por_modulo:
  # VET-001: Mascotas y Propietarios
  mascotas:
    base: "/api/v1/veterinaria/mascotas"
    endpoints:
      - { method: "GET", path: "/", descripcion: "Listar mascotas del tenant" }
      - { method: "GET", path: "/:id", descripcion: "Obtener mascota por ID" }
      - { method: "POST", path: "/", descripcion: "Crear nueva mascota" }
      - { method: "PUT", path: "/:id", descripcion: "Actualizar mascota" }
      - { method: "DELETE", path: "/:id", descripcion: "Eliminar mascota (soft delete)" }
      - { method: "GET", path: "/:id/historial", descripcion: "Historial completo de la mascota" }
      - { method: "GET", path: "/:id/vacunas", descripcion: "Cartilla de vacunacion" }
      - { method: "GET", path: "/:id/hospitalizaciones", descripcion: "Historial de hospitalizaciones" }

  propietarios:
    base: "/api/v1/veterinaria/propietarios"
    endpoints:
      - { method: "GET", path: "/", descripcion: "Listar propietarios" }
      - { method: "GET", path: "/:id", descripcion: "Obtener propietario" }
      - { method: "POST", path: "/", descripcion: "Crear propietario" }
      - { method: "PUT", path: "/:id", descripcion: "Actualizar propietario" }
      - { method: "GET", path: "/:id/mascotas", descripcion: "Mascotas del propietario" }

  especies:
    base: "/api/v1/veterinaria/catalogos/especies"
    endpoints:
      - { method: "GET", path: "/", descripcion: "Listar especies" }
      - { method: "GET", path: "/:id/razas", descripcion: "Razas de la especie" }

  # VET-002: Vacunacion
  vacunas:
    base: "/api/v1/veterinaria/vacunas"
    endpoints:
      - { method: "GET", path: "/", descripcion: "Listar vacunas disponibles" }
      - { method: "POST", path: "/aplicar", descripcion: "Registrar aplicacion de vacuna" }
      - { method: "GET", path: "/pendientes", descripcion: "Vacunas con refuerzo pendiente" }
      - { method: "GET", path: "/proximas", descripcion: "Proximos refuerzos (7 dias)" }

  # VET-003: Desparasitaciones
  desparasitaciones:
    base: "/api/v1/veterinaria/desparasitaciones"
    endpoints:
      - { method: "GET", path: "/mascota/:mascotaId", descripcion: "Historial de desparasitaciones" }
      - { method: "POST", path: "/", descripcion: "Registrar desparasitacion" }
      - { method: "GET", path: "/pendientes", descripcion: "Desparasitaciones pendientes" }

  # VET-004: Hospitalizacion
  hospitalizacion:
    base: "/api/v1/veterinaria/hospitalizacion"
    endpoints:
      - { method: "GET", path: "/activos", descripcion: "Pacientes hospitalizados actuales" }
      - { method: "POST", path: "/ingresar", descripcion: "Ingresar paciente" }
      - { method: "PUT", path: "/:id/estado", descripcion: "Actualizar estado" }
      - { method: "POST", path: "/:id/monitoreo", descripcion: "Registrar signos vitales" }
      - { method: "POST", path: "/:id/alta", descripcion: "Dar de alta paciente" }
      - { method: "GET", path: "/:id/monitoreos", descripcion: "Historial de monitoreo" }

  # VET-005: Estetica
  estetica:
    base: "/api/v1/veterinaria/estetica"
    endpoints:
      - { method: "GET", path: "/", descripcion: "Listar servicios de estetica" }
      - { method: "POST", path: "/", descripcion: "Agendar servicio de estetica" }
      - { method: "PUT", path: "/:id/estado", descripcion: "Actualizar estado del servicio" }
      - { method: "GET", path: "/agenda/:fecha", descripcion: "Agenda del dia" }

  # VET-006: Farmacia
  farmacia:
    base: "/api/v1/veterinaria/farmacia"
    endpoints:
      - { method: "GET", path: "/medicamentos", descripcion: "Listar medicamentos" }
      - { method: "GET", path: "/medicamentos/:id/lotes", descripcion: "Lotes del medicamento" }
      - { method: "POST", path: "/dispensar", descripcion: "Dispensar medicamento" }
      - { method: "GET", path: "/stock-bajo", descripcion: "Medicamentos con stock bajo" }
      - { method: "GET", path: "/proximos-caducar", descripcion: "Lotes proximos a caducar" }
      - { method: "GET", path: "/controlados/bitacora", descripcion: "Bitacora de controlados" }

# ============================================================================
# ENDPOINTS POR METODO (Resumen)
# ============================================================================
por_metodo:
  GET:
    - "/api/v1/veterinaria/mascotas"
    - "/api/v1/veterinaria/propietarios"
    - "/api/v1/veterinaria/hospitalizacion/activos"
    - "/api/v1/veterinaria/farmacia/stock-bajo"
  POST:
    - "/api/v1/veterinaria/mascotas"
    - "/api/v1/veterinaria/vacunas/aplicar"
    - "/api/v1/veterinaria/hospitalizacion/ingresar"
    - "/api/v1/veterinaria/farmacia/dispensar"
  PUT:
    - "/api/v1/veterinaria/mascotas/:id"
    - "/api/v1/veterinaria/hospitalizacion/:id/estado"
  DELETE:
    - "/api/v1/veterinaria/mascotas/:id"

# ============================================================================
# AUTENTICACION
# ============================================================================
autenticacion:
  tipo: "JWT Bearer"
  header: "Authorization"
  formato: "Bearer {token}"
  hereda_de: "erp-core (MGN-001)"
  endpoints_publicos:
    - "/api/v1/auth/login"
    - "/api/v1/auth/register"
    - "/api/v1/health"

# ============================================================================
# MULTI-TENANCY
# ============================================================================
multi_tenancy:
  header: "X-Tenant-ID"
  estrategia: "RLS (Row Level Security)"
  hereda_de: "erp-core (MGN-002)"

# ============================================================================
# ERRORES COMUNES
# ============================================================================
errores:
  400: "Bad Request - Datos invalidos"
  401: "Unauthorized - Token invalido o expirado"
  403: "Forbidden - Sin permisos"
  404: "Not Found - Recurso no encontrado"
  409: "Conflict - Mascota/Propietario ya existe"
  422: "Unprocessable Entity - Validacion fallida"
  500: "Internal Server Error"

# ============================================================================
# ERRORES ESPECIFICOS VETERINARIA
# ============================================================================
errores_veterinaria:
  VET001: "Mascota no encontrada"
  VET002: "Propietario no encontrado"
  VET003: "Vacuna no aplicable a esta especie"
  VET004: "Paciente ya hospitalizado"
  VET005: "Stock insuficiente de medicamento"
  VET006: "Lote caducado no puede dispensarse"
  VET007: "Medicamento controlado requiere receta"

# ============================================================================
# REFERENCIAS
# ============================================================================
referencias:
  swagger: "/api/docs (planificado)"
  services: "@PROJ_DEF_SERVICES"
  herencia_auth: "orchestration/00-guidelines/HERENCIA-ERP-CORE.md"