Endpoint: POST /api/visio/analyze — Iniciar conversión async de Visio

Descripción

Endpoint que inicia la conversión asíncrona de ficheros Visio modernos (.vsdx, .vsd) a masters SVG, delegando el trabajo pesado a un worker de background. Devuelve inmediatamente una sesión ID y estado processing (para .vsdx/.vsd) o done (para formatos rápidos como .vssx/.vdx).

Ruta: POST /api/visio/analyze
Content-Type: multipart/form-data
Auth: Django user + Organization RLS

Contrato de solicitud

POST /api/visio/analyze
Content-Type: multipart/form-data

file: <file upload>  # .vsdx, .vsd, .vssx, .vdx, .vss, .svg

Contrato de respuesta

Respuesta inmediata (.vsdx/.vsd)

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "masters": [],
  "message": "Conversion started. Poll GET /api/racks/visio/session/{session_id}"
}

Respuesta inmediata (formatos rápidos: .vssx/.vdx/.vss/.svg)

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "done",
  "masters": [
    {
      "name": "Switch",
      "image_path": "path/to/preview.svg",
      "u_height": 1,
      "half_width": false
    },
    {
      "name": "PDU",
      "image_path": "path/to/preview.svg",
      "u_height": 2,
      "half_width": false
    }
  ]
}

Campos:

• session_id — UUID para seguimiento de la conversión (usado en polling y confirm).
• status — "processing" (.vsdx/.vsd) o "done" (rápidos).
• masters — Lista de shapes extraídos. Vacía si status=processing (el frontend hace polling para obtenerla).
• message — Instrucciones opcionales.

Lógica de negocio

Flujo por formato

Formatos rápidos (.vssx, .vdx, .vss, .svg):

• Parsed + sanitizados en-memoria.
• Respuesta status=done con masters completo.
• Frontend renderiza grid directamente.

Formatos modernos (.vsdx, .vsd):

• Fichero subido a MEDIA_ROOT/temp/{session_id}/.
• Backend inicia Celery task convert_visio_async(session_id, filepath).
• Respuesta inmediata status=processing con session_id vacío.
• Frontend hace polling de GET /api/racks/visio/session/{session_id} cada 2.5 segundos (máx 4 minutos).
• Cuando task termina, sesión pasa a status=done con masters poblada.

Sanitización

• SVG de cada master es sanitizado con Bleach (whitelist de tags SVG seguros).
• No se persiste nada en DB en este punto — solo en confirm_visio_import().
• Ficheros temporales: limpios en background tras ~4 horas.

Seguridad

• RLS: sesión creada con organization_id=request.user.organization.id. Solo ese usuario/org puede hacer polling y confirm.
• File upload: validación de MIME type + extensión.
• Size limit: (depende de DATA_UPLOAD_MAX_MEMORY_SIZE, típicamente 2.5 MB).

Integración con tasks

Celery Task: convert_visio_async

@db_task
def convert_visio_async(session_id: str, filepath: str):
    """Convierte .vsdx/.vsd a masters SVG. Guarda sesión en cache."""
    try:
        parser = VisioParser(filepath)
        output_dir = f"temp/{session_id}"
        masters = parser.extract_masters(output_dir)
        cache.set(f"visio_session:{session_id}", {
            "status": "done",
            "masters": masters,
        }, timeout=3600)  # 1 hora
    except Exception as e:
        cache.set(f"visio_session:{session_id}", {
            "status": "error",
            "error": str(e),
        }, timeout=3600)

• Corre en worker background.
• Guarda resultado en Redis cache (clave visio_session:{session_id}).
• Frontend polling usa visio_session_status() para leer cache.

Endpoint de polling

GET /api/racks/visio/session/{session_id} (companion):

{
  "status": "processing|done|error",
  "masters": [...],
  "error": "error message (si status=error)"
}

Implementación en racks/api/library_files.py:visio_session_status().

Manejo de errores

Cambios en v1.53.0

• Ahora acepta .vsdx y .vsd (nuevos en v1.53.0; antes solo .vssx/.vdx/.vss/.svg).
• Polling asincrónico en frontend — el modal hace GET /api/racks/visio/session/{id} cada 2.5 segundos.
• Reset inmediato del input tras análisis — permite reelegir el mismo fichero si el polling fue cancelado.

Performance

• Tiempo típico: .vsdx/.vsd (ficheros de fabricante) = 10-60 segundos (depende de complejidad).
• Timeout frontend: 4 minutos → cubre la mayoría de casos reales.
• Cache: resultados en Redis expiran 1 hora post-conversión.

Véase también

• [[feature—stencils—visio-v2-ui-preview]]
• [[entity—racks—endpoint—confirm-visio-import]]
• [[entity—racks—model—stencil]]
• [[concept—saas—multi-tenancy]]