Agente · dev-map-editor

Propósito

Desarrollo y mantenimiento del Map Editor y el sistema Auto-Plan AI de CreaRack-Pro. Cubre la app blueprints/, los 8 módulos JS del editor de mapas y el pipeline de digitalización de planos.

Módulos JS (blueprints/)

static/js/blueprints/
├── map_editor.js          # Coordinador principal — punto de entrada
├── MapRender.js           # Rendering Konva.js de todos los elementos
├── MapInteraction.js      # Interacciones usuario + handler de import Auto-Plan
├── MapCables.js           # Dibujo de cables bezier entre racks
├── MapRacks.js            # Posicionamiento y gestión de racks en el mapa
├── MapHistoryAdapter.js   # Undo/Redo para el editor de mapas
├── pathfinder.js          # Cálculo de rutas para cables
└── AutoPlansAdapter.js    # Integración Auto-Plan AI → importación al canvas

App Django: blueprints/

blueprints/
├── api.py                 # Endpoints /api/blueprints/ y /autoplan/*
├── models.py              # Blueprint, BlueprintPlacement, MapAnnotation
└── services/
    ├── autoplan.py        # AutoPlanService — lógica principal IA
    └── blueprints.py      # BlueprintService

Modelos de datos clave

Blueprint

Plano de infraestructura. Contiene la imagen origen y los metadatos.

BlueprintPlacement

Posicionamiento de un rack dentro de un blueprint (relación Blueprint ↔ Rack).

MapAnnotation

Anotaciones sobre el mapa. Tipo JSONField para datos variables.

⚠ Las conexiones entre racks usan MapAnnotation tipo rack_connection (muchos-a-muchos). NO usar el campo parent_rack (sistema antiguo v1.x, eliminado en v2.0).

Auto-Plan AI · Pipeline completo

Flujo

Imagen entrada (PNG/JPG)
    ↓
Preprocesamiento (Pillow)
  · MAX_DIMENSION: 3072px
  · Formato salida: PNG
  · Modo color: RGB
    ↓
POST /api/blueprints/autoplan/analyze
    ↓
AutoPlanService.analyze_blueprint_image()
  · Proveedor principal: Gemini Flash (gemini-3-flash-preview) — NO CAMBIAR
  · Fallback: DeepSeek V3 (API OpenAI-compatible)
  · Temperatura: 0.1 (resultados deterministas)
  · max_output_tokens: 16384
  · Reintentos: 3 (backoff incremental para 503/timeout)
    ↓
Prompt: prompts/blueprint_analyst.md
  · Sistema de coordenadas 0-1000 (origen top-left)
  · Respuesta JSON estructurada
    ↓
AutoPlanService.create_blueprint_entities()
  · Escala: img_width/1000 · img_height/1000
  · Crea: BlueprintPlacement (racks) + MapAnnotation (conexiones, paredes, textos)
    ↓
Frontend: AutoPlansAdapter.js → MapInteraction.js
  · Renderizado en canvas Konva.js

Entidades detectadas

Sistema de coordenadas del prompt

Origen (0,0) ──────────────── X (1000)
      │
      │   TOP-LEFT  = (0, 0)
      │   TOP-RIGHT = (1000, 0)
      │
      ▼
    Y (1000)

Endpoints API

Archivos del prompt

prompts/
└── blueprint_analyst.md    # Prompt principal para Gemini

Principios para modificar el prompt:

• Mantener el sistema de coordenadas explícito (0-1000)
• Pedir siempre respuesta JSON con schema explícito
• Versionar cambios — probar con plano simple (<20 racks) y complejo (60+ racks) antes de producción
• NO modificar el modelo (gemini-3-flash-preview) ni los parámetros de generación optimizados

Patrones y convenciones

• Undo/Redo: gestionado por MapHistoryAdapter.js — usar siempre este adaptador, no modificar el StateManager global directamente
• Cables: dibujo bezier en MapCables.js + routing en pathfinder.js — no mezclar lógica de ambos
• Rendering: toda modificación visual del canvas pasa por MapRender.js
• Imports: los datos de Auto-Plan entran siempre por AutoPlansAdapter.js → MapInteraction.js

Logging y debug

# Ver logs Auto-Plan en tiempo real
docker compose logs -f web | Select-String "AutoPlan"

Ejemplo de salida correcta:

[INFO] [AutoPlan] Using Gemini 3 Flash Preview for blueprint analysis
[INFO] [AutoPlan] Detection summary: 68 racks, 67 connections, 12 walls, 45 texts
[INFO] [AutoPlan] Successfully created 67 cable connections.

Troubleshooting frecuente

Restricciones críticas

• ⚠ Modelo Gemini fijo: gemini-3-flash-preview — NO cambiar sin autorización
• ⚠ No modificar parámetros de generación (temperatura 0.1, max_output_tokens 16384)
• ⚠ No usar parent_rack para conexiones — siempre MapAnnotation tipo rack_connection

Véase también

• [[concept—blueprints—map-editor]] — concepto transversal del Map Editor
• [[crearack—blueprints—que-es-map-editor]] — introducción de usuario al Map Editor
• [[crearack—blueprints—crear-plano]] — guía de creación de un plano
• [[crearack—blueprints—posicionar-racks]] — cómo colocar racks en el plano
• [[crearack—blueprints—auto-plan-ai]] — generador AI de planos
• [[crearack-tech—backend—auto-plan-technical-reference]] — referencia técnica de Auto-Plan AI
• [[crearack-tech—backend—autoplan-performance]] — rendimiento de Auto-Plan
• [[entity—blueprints—model—blueprint]] — modelo del Map Editor