Endpoint: POST /api/blueprints/{bp_id}/rack — crear rack en blueprint

Identificación

Operación: blueprints_api_racks_create_rack_in_blueprint
Método HTTP: POST
Ruta: /api/blueprints/{bp_id}/rack
Versión introducida: v1.0.0
Última modificación: v1.48.0 (2026-07-10)

Descripción

Crea un Rack real del inventario dentro de un blueprint, con posicionamiento en el mapa (x, y) y visual opcional de stencil. El rack se registra en la tabla racks_rack con la organización del blueprint y se retorna con su ID para sincronización frontend.

Casos de uso

1. Stencils de rack completo (desde Map Editor, panel Shapes): el frontend llama a este endpoint al soltar un stencil de rack (12U–48U) → rack real + visual de stencil en style_props
2. Herramienta Rack (tecla K): al crear un rack con la tools clásica, utiliza este endpoint con stencil de 42U por defecto
3. API externa: cualquier cliente que quiera programar racks en un blueprint

Parámetros de entrada

Schema: PlacementInputSchema (en blueprints/api/schemas.py)

{
  "name": "42U Rack Custom",        // (NEW v1.48.0) Nombre inicial del rack. Máx 100 chars. Default: "New Rack" si no se proporciona.
  "x": 100.5,                       // Coordenada X en el canvas (float)
  "y": 250.0,                       // Coordenada Y en el canvas (float)
  "rotation": 0,                    // (Opcional) Rotación en grados. Default: 0
  "style_props": "{\"stencil\": {\"shapeId\": \"42u-rack-19-standard\", \"svg\": \"<svg>...</svg>\"}, \"width\": 40, \"height\": 150}"
                                    // (Opcional) JSON string con propiedades visuales (visual de stencil, tamaño, etc.)
}

Cambios en v1.48.0

• name (nuevo): parámetro opcional que especifica el nombre del rack al crearlo
  • Si se omite o está vacío: “New Rack” (comportamiento histórico)
  • Se limpia a 100 caracteres máximo
  • El usuario puede renombrarlo después con doble clic en el Map Editor

Respuesta

HTTP 201 Created (en caso de éxito):

{
  "id": 42,
  "name": "42U Rack Custom",
  "status": "active",
  "height_u": 42,
  "organization_id": 5,
  "style_props": {
    "stencil": {
      "shapeId": "42u-rack-19-standard",
      "svg": "<svg>...</svg>"
    },
    "width": 40,
    "height": 150
  }
}

HTTP 400 Bad Request:

• Blueprint no encontrado
• Parámetros inválidos

HTTP 403 Forbidden:

• Usuario no autorizado para el blueprint

Detalles de implementación

Ubicación del código

Backend: blueprints/api/racks.py (función create_rack_in_blueprint)

def create_rack_in_blueprint(request, bp_id: int, payload: PlacementInputSchema):
    try:
        org = request.user.organization
        bp = Blueprint.objects.get(id=bp_id, organization=org)
    except Blueprint.DoesNotExist:
        return 400, {"message": "Blueprint not found"}

    # v1.48.0: usar payload.name si se proporciona
    rack_name = (payload.name or "").strip()[:100] or "New Rack"
    
    rack = Rack.objects.create(
        name=rack_name, 
        organization=org, 
        height_u=42, 
        status="active"
    )

    placement = BlueprintPlacement.objects.create(
        blueprint=bp,
        rack=rack,
        pos_x=payload.x,
        pos_y=payload.y,
        rotation=payload.rotation or 0,
        style_props=payload.style_props or "{}"
    )
    
    return 201, placement.serialize()

Flujo en Map Editor

1. Frontend: Usuario suelta un stencil de rack (ej: 42U)
2. StencilRenderer.insertRackStencil() (helpers/StencilRenderer.js):
   • Resuelve el tamaño de display del stencil (displaySize())
   • Construye styleProps = { stencil: { shapeId, svg }, width, height }
   • Llama a ApiService.post("/api/blueprints/{bp_id}/rack", { name, x, y, style_props })
3. Backend: Crea Rack + BlueprintPlacement con el stencil en style_props
4. Frontend: Recibe la respuesta y llama a MapRacks.createRackNode() para pintar el visual
5. MapRacks.createRackNode():
   • Si rackData.style_props?.stencil?.svg existe: pinta con StencilRenderer.buildImage() (imagen tintada + etiqueta)
   • Si no: pinta rect clásico (compatibilidad)

Diferencias con endpoints hermanos

• POST /api/blueprints/{bp_id}/placements: inserta objetos genéricos (shapes, servidores, etc.). No se materializa como rack
• POST /api/blueprints/{bp_id}/rack (este): siempre crea un Rack real (la versión rack de placement)

Autenticación y autorización

• Requiere usuario autenticado con organization asignada
• El blueprint debe pertenecer a la organización del usuario
• RLS (Row-Level Security) válida si está activa

Testing

• ✅ Test unitario nuevo en suite blueprints: 4/4 verde
• ✅ Verificación E2E:
  • Drop de stencil de rack → llamada POST /rack
  • Nombre del stencil se usa como nombre del rack
  • Respuesta contiene stencil en style_props
  • Visual se renderiza correctamente en el mapa

Notas

• El endpoint no valida el SVG del stencil (se asume que viene del catálogo oficial)
• height_u=42 es una constante para todos los racks creados desde el mapa (el usuario puede cambiarla en Rack Editor después)
• status="active" por defecto (sin estado “draft” o “archived”)
• Compatibilidad regresiva: versiones antiguas del cliente que no envíen name seguirán funcionando

Véase también

• [[feature—blueprints—puente-rack-real]]
• [[entity—blueprints—model—placement-input-schema]]
• [[concept—blueprints—map-editor]]