CreaRack-SL

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

Vista limpiaEditar
Entidadactivecreado Fri Jul 10#blueprints#endpoint#api-rest#racks#django#rest-framework#serialization#v1.48.0

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]]

Referenciado desde

Inicio
Yo