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.

Tipo	Uso	Formato `data`
`rack_connection`	Cable entre racks	`{from: rack_id, to: rack_id}`
`drawing_line`	Línea / pared	`{points: [x1,y1,x2,y2], stroke, strokeWidth}`
`drawing_text`	Texto libre	`{x, y, text, fill, fontSize}`
`symbol`	Símbolo de red	`{x, y, symbol_type, color}`

⚠ 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

Entidad	Schema	Descripción
`racks`	`{label, type, zone, pos_x, pos_y}`	Tipo: `RACK` (verde/gris) o `NODAL` (naranja)
`connections`	`{from, to}`	Cables entre racks
`walls`	`{x1, y1, x2, y2, color, style}`	Líneas estructurales
`texts`	`{text, x, y, color}`	Etiquetas
`symbols`	`{type, x, y}`	Iconos de red

Sistema de coordenadas del prompt

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

Endpoints API

Método	URL	Propósito
`POST`	`/api/blueprints/autoplan/analyze`	Analizar imagen con IA
`POST`	`/api/blueprints/autoplan/import`	Importar datos al blueprint
`GET/POST/PUT/DELETE`	`/api/blueprints/`	CRUD blueprints (38 endpoints total)

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

Problema	Causa	Solución
Error 503 / Model Overloaded	Imagen grande o Gemini saturado	Retry automático (3 intentos) — esperar
Conexiones no se guardan	Uso del campo antiguo `parent_rack`	Usar `MapAnnotation` tipo `rack_connection`
Baja precisión de detección	Imagen de baja calidad	Mínimo 1024px, buen contraste, poco ruido
Líneas mal orientadas	Coordenadas incorrectas del modelo	El prompt v2.0 incluye sistema de coordenadas explícito

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