=====================================
Endpoints de Base de Conocimiento
=====================================

El módulo de base de conocimiento (KB) expone una API REST bajo el prefijo
``/kb/api/`` para la gestión de categorías, artículos y anuncios del sistema.
Los endpoints de lectura están disponibles para todos los usuarios autenticados;
las operaciones de escritura están restringidas a administradores.

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

Categorías — ``/kb/api/categories/``
======================================

Gestión de categorías de la base de conocimiento. Las categorías públicas son
visibles para todos los usuarios autenticados. Los administradores pueden ver
también las categorías privadas y realizar operaciones de escritura.

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

   * - Método
     - Endpoint
     - Descripción
   * - ``GET``
     - ``/kb/api/categories/``
     - Listar categorías (públicas o todas para admin)
   * - ``POST``
     - ``/kb/api/categories/``
     - Crear nueva categoría (solo admin)
   * - ``GET``
     - ``/kb/api/categories/{id}/``
     - Detalle de una categoría
   * - ``PUT``
     - ``/kb/api/categories/{id}/``
     - Actualizar categoría (solo admin)
   * - ``PATCH``
     - ``/kb/api/categories/{id}/``
     - Actualizar campos parciales (solo admin)
   * - ``DELETE``
     - ``/kb/api/categories/{id}/``
     - Eliminar categoría (solo admin)

**Ejemplo — Listar categorías:**

.. code-block:: bash

   curl -X GET https://panel.example.com/kb/api/categories/ \
     -H "Authorization: Bearer $TOKEN"

**Respuesta:**

.. code-block:: json

   {
     "count": 4,
     "next": null,
     "previous": null,
     "results": [
       {
         "id": 1,
         "name": "Hosting",
         "slug": "hosting",
         "description": "Artículos sobre gestión de hosting compartido",
         "icon": "bi-globe",
         "parent": null,
         "order": 0,
         "is_public": true,
         "is_active": true,
         "articles_count": 12,
         "created_at": "2026-01-10T08:00:00Z"
       },
       {
         "id": 2,
         "name": "DNS",
         "slug": "dns",
         "description": "Guías de configuración DNS",
         "icon": "bi-diagram-3",
         "parent": 1,
         "order": 1,
         "is_public": true,
         "is_active": true,
         "articles_count": 5,
         "created_at": "2026-01-10T08:30:00Z"
       }
     ]
   }

.. note::

   El campo ``articles_count`` devuelve la cantidad de artículos publicados y
   públicos en cada categoría. El campo ``slug`` se genera automáticamente a
   partir del nombre si no se proporciona.

**Ejemplo — Crear categoría (admin):**

.. code-block:: bash

   curl -X POST https://panel.example.com/kb/api/categories/ \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Facturación",
       "description": "Guías sobre facturación y pagos",
       "icon": "bi-receipt",
       "order": 3,
       "is_public": true
     }'

Artículos — ``/kb/api/articles/``
===================================

Gestión de artículos de la base de conocimiento. El listado utiliza un
serializador reducido (sin contenido completo); el detalle incluye el contenido
Markdown, metadatos SEO y adjuntos. Al consultar el detalle de un artículo,
se incrementa automáticamente el contador de visualizaciones.

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

   * - Método
     - Endpoint
     - Descripción
   * - ``GET``
     - ``/kb/api/articles/``
     - Listar artículos (publicados para usuarios, todos para admin)
   * - ``POST``
     - ``/kb/api/articles/``
     - Crear nuevo artículo (solo admin)
   * - ``GET``
     - ``/kb/api/articles/{id}/``
     - Detalle completo de un artículo (incrementa vistas)
   * - ``PUT``
     - ``/kb/api/articles/{id}/``
     - Actualizar artículo (solo admin)
   * - ``PATCH``
     - ``/kb/api/articles/{id}/``
     - Actualizar campos parciales (solo admin)
   * - ``DELETE``
     - ``/kb/api/articles/{id}/``
     - Eliminar artículo (solo admin)
   * - ``POST``
     - ``/kb/api/articles/{id}/vote/``
     - Votar si el artículo fue útil

Estados del artículo
---------------------

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - Estado
     - Descripción
   * - ``draft``
     - Borrador (solo visible para administradores)
   * - ``published``
     - Publicado (visible para todos los usuarios)
   * - ``archived``
     - Archivado (solo visible para administradores)

**Ejemplo — Listar artículos:**

.. code-block:: bash

   curl -X GET https://panel.example.com/kb/api/articles/ \
     -H "Authorization: Bearer $TOKEN"

**Respuesta (lista):**

.. code-block:: json

   {
     "count": 25,
     "next": "https://panel.example.com/kb/api/articles/?page=2",
     "previous": null,
     "results": [
       {
         "id": 1,
         "title": "Cómo configurar DNS para tu dominio",
         "slug": "como-configurar-dns-para-tu-dominio",
         "category": 2,
         "category_name": "DNS",
         "excerpt": "Guía paso a paso para configurar registros DNS A, CNAME, MX y TXT.",
         "status": "published",
         "is_featured": true,
         "is_public": true,
         "tags": "dns, dominios, configuración",
         "views_count": 342,
         "helpful_yes": 45,
         "helpful_no": 3,
         "author": 1,
         "author_name": "admin",
         "published_at": "2026-01-15T10:00:00Z",
         "updated_at": "2026-02-01T12:00:00Z"
       }
     ]
   }

**Ejemplo — Detalle de artículo:**

.. code-block:: bash

   curl -X GET https://panel.example.com/kb/api/articles/1/ \
     -H "Authorization: Bearer $TOKEN"

**Respuesta (detalle):**

.. code-block:: json

   {
     "id": 1,
     "title": "Cómo configurar DNS para tu dominio",
     "slug": "como-configurar-dns-para-tu-dominio",
     "category": 2,
     "category_name": "DNS",
     "content": "# Configurar DNS\n\nPara configurar los registros DNS de tu dominio...",
     "excerpt": "Guía paso a paso para configurar registros DNS A, CNAME, MX y TXT.",
     "status": "published",
     "is_featured": true,
     "is_public": true,
     "tags": "dns, dominios, configuración",
     "views_count": 343,
     "helpful_yes": 45,
     "helpful_no": 3,
     "author": 1,
     "author_name": "admin",
     "meta_title": "Configurar DNS - Guía completa",
     "meta_description": "Aprende a configurar registros DNS paso a paso.",
     "attachments": [
       {
         "id": 1,
         "file": "/media/kb/attachments/2026/01/dns-diagram.png",
         "filename": "dns-diagram.png",
         "file_size": 45320,
         "uploaded_at": "2026-01-15T10:00:00Z"
       }
     ],
     "published_at": "2026-01-15T10:00:00Z",
     "created_at": "2026-01-14T09:00:00Z",
     "updated_at": "2026-02-01T12:00:00Z"
   }

.. note::

   El campo ``views_count`` se incrementa automáticamente cada vez que se accede
   al detalle del artículo. Los campos ``helpful_yes`` y ``helpful_no`` se
   modifican a través de la acción ``vote``.

**Ejemplo — Votar artículo como útil:**

.. code-block:: bash

   curl -X POST https://panel.example.com/kb/api/articles/1/vote/ \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"helpful": true}'

**Respuesta:**

.. code-block:: json

   {
     "status": "voted"
   }

Para votar que el artículo **no** fue útil, enviar ``{"helpful": false}``.

**Ejemplo — Crear artículo (admin):**

.. code-block:: bash

   curl -X POST https://panel.example.com/kb/api/articles/ \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "title": "Cómo instalar WordPress",
       "category": 1,
       "content": "# Instalar WordPress\n\nSigue estos pasos...",
       "excerpt": "Guía para instalar WordPress en tu hosting.",
       "status": "published",
       "is_public": true,
       "tags": "wordpress, cms, instalación"
     }'

.. note::

   El campo ``author`` se asigna automáticamente al usuario autenticado que
   crea el artículo. El campo ``slug`` se genera a partir del título si no
   se proporciona explícitamente.

Anuncios — ``/kb/api/announcements/``
=======================================

Gestión de anuncios del sistema (mantenimientos, novedades, avisos críticos).
Los anuncios activos son visibles para todos los usuarios autenticados. Los
administradores pueden crear, editar y eliminar anuncios.

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

   * - Método
     - Endpoint
     - Descripción
   * - ``GET``
     - ``/kb/api/announcements/``
     - Listar anuncios (activos para usuarios, todos para admin)
   * - ``POST``
     - ``/kb/api/announcements/``
     - Crear nuevo anuncio (solo admin)
   * - ``GET``
     - ``/kb/api/announcements/{id}/``
     - Detalle de un anuncio
   * - ``PUT``
     - ``/kb/api/announcements/{id}/``
     - Actualizar anuncio (solo admin)
   * - ``PATCH``
     - ``/kb/api/announcements/{id}/``
     - Actualizar campos parciales (solo admin)
   * - ``DELETE``
     - ``/kb/api/announcements/{id}/``
     - Eliminar anuncio (solo admin)

Tipos de anuncio
-----------------

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - Tipo
     - Descripción
   * - ``info``
     - Información general
   * - ``warning``
     - Aviso importante
   * - ``critical``
     - Incidencia crítica
   * - ``maintenance``
     - Mantenimiento programado
   * - ``release``
     - Novedad o actualización del sistema

**Ejemplo — Listar anuncios:**

.. code-block:: bash

   curl -X GET https://panel.example.com/kb/api/announcements/ \
     -H "Authorization: Bearer $TOKEN"

**Respuesta:**

.. code-block:: json

   {
     "count": 2,
     "next": null,
     "previous": null,
     "results": [
       {
         "id": 1,
         "title": "Mantenimiento programado - 15 Feb 2026",
         "content": "El próximo sábado 15 de febrero realizaremos tareas de mantenimiento en los servidores de hosting. El servicio podría verse afectado entre las 02:00 y las 06:00 CET.",
         "announcement_type": "maintenance",
         "is_active": true,
         "is_pinned": true,
         "show_in_dashboard": true,
         "show_in_banner": true,
         "author": 1,
         "author_name": "admin",
         "published_at": "2026-02-08T10:00:00Z",
         "expires_at": "2026-02-16T06:00:00Z"
       },
       {
         "id": 2,
         "title": "Nueva funcionalidad: Auto-instalador de CMS",
         "content": "Ahora puedes instalar WordPress, Joomla y PrestaShop con un solo clic desde el panel de hosting.",
         "announcement_type": "release",
         "is_active": true,
         "is_pinned": false,
         "show_in_dashboard": true,
         "show_in_banner": false,
         "author": 1,
         "author_name": "admin",
         "published_at": "2026-02-05T12:00:00Z",
         "expires_at": null
       }
     ]
   }

**Ejemplo — Crear anuncio (admin):**

.. code-block:: bash

   curl -X POST https://panel.example.com/kb/api/announcements/ \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "title": "Actualización del panel v2.5",
       "content": "Hemos lanzado la versión 2.5 con mejoras de rendimiento y nuevas funcionalidades.",
       "announcement_type": "release",
       "is_pinned": false,
       "show_in_dashboard": true,
       "show_in_banner": false
     }'

.. note::

   El campo ``author`` se asigna automáticamente al usuario autenticado.
   Si se establece ``expires_at``, el anuncio se ocultará automáticamente
   después de esa fecha para los usuarios regulares (los administradores
   siguen viéndolo).