CreaRack-SL

Schema: PlacementInputSchema — parámetros de creación/actualización de placements

Vista limpiaEditar
Entidadactivecreado Fri Jul 10#blueprints#schema#data-transfer#api#django-ninja#serialization#v1.48.0

Identificación

Módulo: blueprints/api/schemas.py
Clase: PlacementInputSchema
Frameworkw: Ninja (Django REST framework compatible)
Versión introducida: v1.0.0
Última modificación: v1.48.0 (2026-07-10)

Descripción

Schema (Data Transfer Object) que valida y serializa los parámetros de entrada para operaciones sobre BlueprintPlacement (colocación de objetos en el mapa). Se usa en endpoints como:

  • POST /api/blueprints/{bp_id}/rack — crear un rack real
  • POST /api/blueprints/{bp_id}/placements — crear un placement genérico
  • PUT /api/blueprints/{bp_id}/placements/{rack_id} — actualizar un placement

Estructura

class PlacementInputSchema(Schema):
    x: float                   # Coordenada X en el canvas
    y: float                   # Coordenada Y en el canvas
    rotation: int | None = 0   # Rotación en grados (0–360). Default: 0
    style_props: str | None = "{}"
                               # JSON string con propiedades visuales (color, tamaño, etc.)
                               # Ej: '{"color": "#ff9900", "width": 120, "height": 35}'
    
    # v1.48.0 (NEW)
    name: str | None = None    # Nombre inicial del objeto (para racks) o etiqueta
                               # Máx 100 caracteres tras limpieza
                               # Si se omite: default depende del endpoint

Campos

x: float (requerido)

  • Tipo: número flotante
  • Rango: típicamente 0–10000 (tamaño del canvas)
  • Significado: posición horizontal en píxeles del mapa
  • Validación: ninguna especial (frontend valida el snapToGrid)

y: float (requerido)

  • Tipo: número flotante
  • Rango: típicamente 0–8000 (tamaño del canvas)
  • Significado: posición vertical en píxeles del mapa
  • Validación: ninguna especial

rotation: int | None (opcional)

  • Tipo: entero o None
  • Default: 0
  • Rango: 0–360 (grados)
  • Significado: rotación visual del objeto en el mapa
  • Nota: Konva utiliza este valor para rotar el grupo del objeto

style_props: str | None (opcional)

  • Tipo: string JSON (no dict)
  • Default: "{}"
  • Estructura: JSON arbitrario según el tipo de objeto
  • Ejemplos:
    • Rectángulo clásico: {"color": "#1e1e1e", "width": 100, "height": 50}
    • Stencil: {"stencil": {"shapeId": "42u-rack-19-standard", "svg": "<svg>..."}, "width": 40, "height": 150}

Nota importante: se almacena como string en la BD (campo style_props: CharField en BlueprintPlacement), no como JSON serializado. El frontend es responsable de hacer JSON.stringify() antes de enviar.

name: str | None (v1.48.0 — nuevo)

  • Tipo: string o None
  • Default: None
  • Máx caracteres: 100 (tras limpieza)
  • Significado: nombre inicial del objeto al crearlo
    • Para racks: se usa como nombre del rack (Rack.name)
    • Para otros objetos: etiqueta opcional o descripción
  • Procesamiento: se limpia con .strip() y se trunca a 100 caracteres
  • Comportamiento en endpoint:
    • POST /api/blueprints/{bp_id}/rack: si no se proporciona, usa “New Rack”
    • Otros endpoints: depende del controlador específico

Validación

La validación ocurre en dos capas:

Capa Ninja/OpenAPI

  • Valida tipos (float para x/y, int para rotation, str para style_props/name)
  • Si los tipos no coinciden, devuelve 400 automáticamente

Capa de controlador

  • create_rack_in_blueprint() valida que el blueprint exista y pertenezca a la organización
  • name se limpia a máx 100 caracteres y se vacía si es todo espacios en blanco

Ejemplos de uso

Crear un rack con stencil (v1.48.0)

POST /api/blueprints/5/rack
Content-Type: application/json

{
  "x": 100.5,
  "y": 250.0,
  "rotation": 0,
  "name": "42U Rack Custom",
  "style_props": "{\"stencil\": {\"shapeId\": \"42u-rack-19-standard\", \"svg\": \"<svg>...</svg>\"}, \"width\": 40, \"height\": 150}"
}

Crear un rack clásico (rect)

POST /api/blueprints/5/rack
Content-Type: application/json

{
  "x": 300.0,
  "y": 400.0,
  "name": "Rack 2",
  "style_props": "{}"
}

→ Sin stencil, el endpoint crea el rack y el frontend lo pinta como rectángulo clásico.

Crear un placement genérico (dibujo)

POST /api/blueprints/5/placements
Content-Type: application/json

{
  "x": 50.0,
  "y": 100.0,
  "rotation": 45,
  "style_props": "{\"color\": \"#ff9900\", \"width\": 120, \"height\": 35}"
}

Cambios en v1.48.0

Lo nuevo: campo name

Motivación: El endpoint POST /api/blueprints/{bp_id}/rack necesitaba una forma de especificar el nombre inicial del rack sin hacer una llamada adicional de rename.

Impacto:

  • Los clientes antiguos que no envíen name siguen funcionando (compatibilidad regresiva)
  • Los clientes nuevos (Map Editor con stencils) envían name automáticamente
  • El campo se trunca a 100 caracteres por seguridad (evita inyección de datos enormes)

Flujo del Map Editor (v1.48.0)

  1. Usuario suelta un stencil de rack (ej: 42u-rack-19-standard)
  2. Frontend: StencilRenderer.insertRackStencil() → construye payload con:
    • name: shape.name (del catálogo de stencils)
    • x, y: posición del drop
    • style_props: JSON con stencil: { shapeId, svg }
  3. POST /api/blueprints/{bp_id}/rack con este payload
  4. Backend: crea Rack con nombre limpio (máx 100 chars) + almacena stencil en style_props
  5. Frontend: recibe la respuesta y pinta el visual con MapRacks.createRackNode()

Ubicación y referencias

  • Archivo: blueprints/api/schemas.py
  • Usado por endpoints:
    • blueprints_api_racks_create_rack_in_blueprint (POST /rack)
    • Otros endpoints de placement (si aplican)
  • Validación: Ninja realiza introspección automática

Testing

  • ✅ Valida tipos (x/y float, rotation int, name/style_props str)
  • ✅ Acepta name=None (regresivo)
  • ✅ Trunca name a 100 caracteres
  • ✅ Procesa style_props como string JSON (sin deserialización en el schema)

Notas

  • El campo style_props no se valida como JSON en el schema (la BD acepta cualquier string). El frontend es responsable de enviar JSON válido
  • name se limpia en el controlador, no en el schema (para evitar que el validador rechace un string con espacios en blanco al inicio)
  • El orden de campos en el JSON no importa (Ninja los une por nombre)

Véase también

  • [[entity—blueprints—endpoint—create-rack-in-blueprint]]
  • [[feature—blueprints—puente-rack-real]]
  • [[concept—blueprints—map-editor]]

Referenciado desde

Inicio
Yo