===========================
Endpoints de Dashboard
===========================

El endpoint de dashboard proporciona estadísticas agregadas del sistema bajo
el prefijo ``/api/v1/dashboard/``. Los datos devueltos varían según el rol del
usuario: los superusuarios reciben estadísticas globales, mientras que los
usuarios regulares solo ven datos de sus propios recursos.

.. contents:: En esta página
   :local:
   :depth: 2

Estadísticas — ``/api/v1/dashboard/stats/``
=============================================

Endpoint de solo lectura que devuelve un resumen agregado de VMs, hosting,
facturación y tickets. Diseñado para alimentar los widgets del dashboard
principal del panel.

.. list-table:: Métodos
   :header-rows: 1
   :widths: 15 50 35

   * - Método
     - Endpoint
     - Descripción
   * - ``GET``
     - ``/api/v1/dashboard/stats/``
     - Obtener estadísticas agregadas

Permisos y alcance de datos
-----------------------------

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - Rol
     - Datos devueltos
   * - Superusuario
     - Estadísticas globales de todo el sistema: todas las VMs, todos los
       sitios de hosting, ingresos totales, todos los tickets.
   * - Usuario regular
     - Solo datos propios: VMs de sus pools, sitios de sus tenants,
       suscripciones de sus tenants, tickets propios.

**Ejemplo — Obtener estadísticas:**

.. code-block:: bash

   curl -X GET https://panel.example.com/api/v1/dashboard/stats/ \
     -H "Authorization: Bearer $TOKEN"

**Respuesta (superusuario):**

.. code-block:: json

   {
     "vms": {
       "total": 24,
       "running": 18
     },
     "hosting": {
       "domains": 156,
       "databases": 89,
       "email_accounts": 342,
       "ssl_active": 143
     },
     "billing": {
       "total_revenue": "12450.50",
       "pending_amount": "1230.00",
       "active_subscriptions": 78
     },
     "tickets": {
       "total": 520,
       "open": 12,
       "pending": 5
     }
   }

**Respuesta (usuario regular):**

.. code-block:: json

   {
     "vms": {
       "total": 3,
       "running": 2
     },
     "hosting": {
       "domains": 5,
       "databases": 3,
       "email_accounts": 12,
       "ssl_active": 4
     },
     "billing": {
       "active_subscriptions": 2
     },
     "tickets": {
       "total": 8,
       "open": 1,
       "pending": 0
     }
   }

Campos de la respuesta
-----------------------

.. list-table:: Sección ``vms``
   :header-rows: 1
   :widths: 25 75

   * - Campo
     - Descripción
   * - ``total``
     - Número total de máquinas virtuales
   * - ``running``
     - Número de VMs en estado ``running``

.. list-table:: Sección ``hosting``
   :header-rows: 1
   :widths: 25 75

   * - Campo
     - Descripción
   * - ``domains``
     - Número de sitios web activos
   * - ``databases``
     - Número de bases de datos
   * - ``email_accounts``
     - Número de buzones de correo
   * - ``ssl_active``
     - Número de sitios con SSL habilitado

.. list-table:: Sección ``billing`` (superusuario)
   :header-rows: 1
   :widths: 25 75

   * - Campo
     - Descripción
   * - ``total_revenue``
     - Ingresos totales de pagos completados (cadena decimal)
   * - ``pending_amount``
     - Monto total de facturas pendientes y vencidas (cadena decimal)
   * - ``active_subscriptions``
     - Número de suscripciones activas

.. list-table:: Sección ``billing`` (usuario regular)
   :header-rows: 1
   :widths: 25 75

   * - Campo
     - Descripción
   * - ``active_subscriptions``
     - Número de suscripciones activas del usuario

.. list-table:: Sección ``tickets``
   :header-rows: 1
   :widths: 25 75

   * - Campo
     - Descripción
   * - ``total``
     - Número total de tickets
   * - ``open``
     - Tickets en estado ``new`` u ``open``
   * - ``pending``
     - Tickets en estado ``pending``

.. note::

   Cada sección solo se incluye en la respuesta si el usuario tiene acceso
   al módulo correspondiente (``can_access_vps``, ``can_access_hosting``,
   ``can_access_billing``, ``can_access_ticketing``). Si un módulo no está
   disponible o genera un error, se devuelven valores por defecto (ceros).

   Los campos de billing ``total_revenue`` y ``pending_amount`` solo están
   disponibles para superusuarios.