6. Paso a Paso: Sistema de Boletas y Migraciones Evolutivas 🧾

1. El Reto Real: Construir una Base de Datos que Evoluciona

En los tutoriales introductorios es común ver que todos los modelos se escriben de una sola vez en un único archivo models.py y se ejecuta una única migración 0001_initial. En el mundo laboral real, ningún software se construye así.

Los sistemas crecen incrementalmente: primero lanzas un catálogo básico, luego añades el módulo de ventas, más adelante incorporas la gestión de clientes sin romper las ventas anteriores, y finalmente blindas la base de datos con restricciones de integridad y migraciones de datos.

A lo largo de esta lección construiremos el núcleo de datos de un Sistema de Punto de Venta (POS) y Facturación a través de 5 migraciones sucesivas:

Fase 1 (`0001`): Catálogo maestro con Categoria y Producto.
Fase 2 (`0002`): Transacciones de venta con Boleta y DetalleBoleta (congelando el precio histórico).
Fase 3 (`0003`): Incorporación de Cliente como relación opcional (null=True, blank=True) sobre tablas con datos previos.
Fase 4 (`0004`): Restricciones a nivel de base de datos con CheckConstraint y cálculos automáticos en save().
Fase 5 (`0005`): Migración de datos idempotente con RunPython para sembrar categorías maestras.

2. Línea de Tiempo Interactiva de la Base de Datos

Explora visualmente cómo cambia el código en Python, qué comando se ejecuta en la terminal y qué tablas se generan en la base de datos en cada una de las 5 fases:

LÍNEA DE TIEMPO EVOLUTIVA

Evolución de la Base de Datos: Sistema de Boletas POS

Avanza paso a paso viendo cómo nacen las tablas, se añaden relaciones y se aplican migraciones seguras sin pérdida de datos.

Archivo Migración:0001_initial.py

🎯 Objetivo del Paso 1:

Creación de Categoría y Producto

Establecer las entidades maestras de nuestro inventario con una relación 1 a Muchos (1 Categoría tiene N Productos).

💻 Terminal: Generar y Aplicar MigraciónBash / CMD

(venv) C:\proyectos\django\ventas> python manage.py makemigrations ventas
Migrations for 'ventas':
  ventas/migrations/0001_initial.py
    - Create model Categoria
    - Create model Producto

(venv) C:\proyectos\django\ventas> python manage.py migrate
Operations to perform:
  Apply all migrations: admin, auth, contenttypes, sessions, ventas
Running migrations:
  Applying ventas.0001_initial... OK

🐍 Código en Python (ventas/models.py)Django Models

# ventas/models.py (Fase 1)
from django.db import models

class Categoria(models.Model):
    nombre = models.CharField(max_length=50, unique=True)
    descripcion = models.TextField(blank=True)

    def __str__(self):
        return self.nombre


class Producto(models.Model):
    nombre = models.CharField(max_length=150, db_index=True)
    codigo_barra = models.CharField(max_length=30, unique=True)
    precio = models.DecimalField(max_digits=10, decimal_places=2)
    stock = models.PositiveIntegerField(default=0)
    categoria = models.ForeignKey(
        Categoria,
        on_delete=models.PROTECT,
        related_name='productos'
    )

    def __str__(self):
        return f"{self.nombre} (${self.precio})"

⚡ SQL Real Ejecutado (sqlmigrate ventas 0001)

CREATE TABLE "ventas_categoria" (
    "id" bigint NOT NULL PRIMARY KEY GENERATED BY DEFAULT AS IDENTITY,
    "nombre" varchar(50) NOT NULL UNIQUE,
    "descripcion" text NOT NULL
);

CREATE TABLE "ventas_producto" (
    "id" bigint NOT NULL PRIMARY KEY GENERATED BY DEFAULT AS IDENTITY,
    "nombre" varchar(150) NOT NULL,
    "codigo_barra" varchar(30) NOT NULL UNIQUE,
    "precio" numeric(10, 2) NOT NULL,
    "stock" integer NOT NULL CHECK ("stock" >= 0),
    "categoria_id" bigint NOT NULL REFERENCES "ventas_categoria" ("id")
);

🗄️ Esquema en Base de Datos (Tablas Resultantes):2 tablas activas

📋 ventas_categoria3 cols

Tabla maestra de familias de productos

🔑 PKidBIGINT

nombreVARCHAR(50) UNIQUE

descripcionTEXT

📋 ventas_producto6 cols

Catálogo de artículos vendibles

🔑 PKidBIGINT

nombreVARCHAR(150)

codigo_barraVARCHAR(30) UNIQUE

precioNUMERIC(10, 2)

stockINTEGER (>=0)

🔗 FKcategoria_idBIGINT

💡Clave de Arquitectura en Producción:

Usamos on_delete=models.PROTECT en la relación con Categoria para evitar que un administrador borre una categoría si todavía existen productos asignados a ella, protegiendo la integridad referencial.

3. Desglose Técnico Paso a Paso

Paso 1: Catálogo Base (Migración `0001_initial.py`)

Comenzamos en la aplicación ventas creando los dos modelos fundacionales de nuestro inventario:

ventas/models.py - Fase 1

PYTHON

# ventas/models.py
from django.db import models
 
class Categoria(models.Model):
    nombre = models.CharField(max_length=50, unique=True)
    descripcion = models.TextField(blank=True)
 
    def __str__(self):
        return self.nombre
 
 
class Producto(models.Model):
    nombre = models.CharField(max_length=150, db_index=True)
    codigo_barra = models.CharField(max_length=30, unique=True)
    precio = models.DecimalField(max_digits=10, decimal_places=2)
    stock = models.PositiveIntegerField(default=0)
    categoria = models.ForeignKey(
        Categoria,
        on_delete=models.PROTECT,
        related_name='productos'
    )
 
    def __str__(self):
        return f"{self.nombre} (${self.precio})"

¿Por qué `on_delete=models.PROTECT`?
Si un empleado intenta eliminar la categoría "Bebidas", pero ya existen 20 productos registrados en ella, la base de datos lanzará un error ProtectedError impidiendo el borrado. Esto evita que los productos queden huérfanos o se borren por accidente.

Paso 2: Transacciones de Venta (Migración `0002_boleta_detalleboleta.py`)

Una venta requiere un patrón Maestro-Detalle (Master-Detail):

Boleta (Maestro): Representa la transacción global (folio único, fecha, hora, total).
DetalleBoleta (Detalle): Representa cada ítem vendido dentro de esa boleta (qué producto, cuántas unidades y a qué precio).

ventas/models.py - Fase 2

PYTHON

from django.utils import timezone
 
class Boleta(models.Model):
    folio = models.CharField(max_length=20, unique=True, db_index=True)
    fecha = models.DateField(default=timezone.now)
    hora = models.TimeField(default=timezone.now)
    total = models.DecimalField(max_digits=12, decimal_places=2, default=0.00)
 
    def __str__(self):
        return f"Boleta #{self.folio} - ${self.total}"
 
 
class DetalleBoleta(models.Model):
    boleta = models.ForeignKey(
        Boleta,
        on_delete=models.CASCADE,
        related_name='detalles'
    )
    producto = models.ForeignKey(
        Producto,
        on_delete=models.PROTECT,
        related_name='ventas_detalle'
    )
    # REGLA DE ARQUITECTURA CRÍTICA:
    precio_unitario = models.DecimalField(max_digits=10, decimal_places=2)
    cantidad = models.PositiveIntegerField(default=1)
    total_linea = models.DecimalField(max_digits=10, decimal_places=2)
 
    def __str__(self):
        return f"{self.cantidad}x {self.producto.nombre} (${self.total_linea})"

⚠️ El Principio del Snapshot (Instantánea de Precios):
Muchos desarrolladores novatos omiten el campo precio_unitario en DetalleBoleta pensando: "¿Para qué guardarlo si puedo hacer detalle.producto.precio?".
¡Esto es un error financiero grave! Si vendes un café a $2.00 hoy, y dentro de 4 meses subes el precio a $3.50, al consultar las boletas del año pasado verías que todas aumentaron su valor mágicamente. En cualquier sistema de facturación, el detalle debe congelar el precio exacto al que se vendió en ese milisegundo.

Paso 3: Incorporación de Cliente Opcional (Migración `0003_cliente_boleta_cliente.py`)

Ahora la empresa decide implementar un programa de fidelización y necesita asociar boletas a clientes registrados. Sin embargo, en una cafetería o tienda muchas ventas son anónimas (público general que no entrega sus datos).

ventas/models.py - Fase 3

PYTHON

class Cliente(models.Model):
    rut_o_dni = models.CharField(max_length=20, unique=True)
    nombre = models.CharField(max_length=120)
    email = models.EmailField(blank=True)
    telefono = models.CharField(max_length=20, blank=True)
 
    def __str__(self):
        return f"{self.nombre} ({self.rut_o_dni})"
 
 
# En el modelo Boleta agregamos la clave foránea como opcional:
class Boleta(models.Model):
    # ... campos anteriores ...
    cliente = models.ForeignKey(
        Cliente,
        on_delete=models.SET_NULL,  # Si se elimina el cliente, la boleta NO se borra
        null=True,                  # Admite NULL en la BD (ventas anónimas)
        blank=True,                 # Opcional en formularios y panel administrativo
        related_name='boletas'
    )

¿Cómo afecta esto a las migraciones con datos existentes?
Si ejecutas python manage.py makemigrations sobre una tabla que ya tiene registros reales:

Si el campo no permite nulos (null=False), Django te detendrá en seco pidiéndote un valor por defecto para las filas anteriores.
Al declarar null=True, la migración ejecuta un ALTER TABLE "ventas_boleta" ADD COLUMN "cliente_id" bigint NULL; limpio e inmediato, manteniendo todas las ventas anteriores como compras anónimas sin romper el sistema.

Paso 4: Blindaje con Restricciones CheckConstraint y `save()` Automatizado

Para que el sistema sea confiable, no podemos permitir que nadie inserte un detalle con cantidad 0 o negativa, ni precios negativos. Agregamos restricciones a nivel de motor SQL en Meta.constraints:

ventas/models.py - Fase 4

PYTHON

class DetalleBoleta(models.Model):
    # ... campos ...
 
    class Meta:
        constraints = [
            models.CheckConstraint(
                check=models.Q(cantidad__gt=0),
                name='chk_cantidad_positiva'
            ),
            models.CheckConstraint(
                check=models.Q(precio_unitario__gte=0),
                name='chk_precio_unitario_positivo'
            ),
        ]
 
    def save(self, *args, **kwargs):
        # 1. Si no viene precio unitario, tomar el precio actual del producto
        if not self.precio_unitario:
            self.precio_unitario = self.producto.precio
        
        # 2. Calcular automáticamente el total de la línea
        self.total_linea = self.precio_unitario * self.cantidad
        
        super().save(*args, **kwargs)

Paso 5: Migración de Datos con `RunPython` (`0005_sembrar_categorias_iniciales.py`)

¿Cómo garantizamos que cuando un nuevo desarrollador o un servidor de despliegue clone el proyecto, existan categorías listas para usar? Creamos una migración de datos con --empty:

Crear archivo de migración vacío

CMD

1(venv) C:\proyectos\django\ventas> python manage.py makemigrations ventas --empty --name sembrar_categorias_iniciales

Luego editamos el archivo generado usando apps.get_model():

0005_sembrar_categorias_iniciales.py

PYTHON

# ventas/migrations/0005_sembrar_categorias_iniciales.py
from django.db import migrations
 
CATEGORIAS = [
    {"nombre": "Bebidas y Cafetería", "descripcion": "Café de grano, té e infusiones"},
    {"nombre": "Pastelería", "descripcion": "Tortas y pasteles del día"},
    {"nombre": "Snacks Salados", "descripcion": "Empanadas y sándwiches"},
]
 
def sembrar_categorias(apps, schema_editor):
    # REGLA CRÍTICA: Usar apps.get_model() en vez de importar el modelo
    Categoria = apps.get_model('ventas', 'Categoria')
    for cat in CATEGORIAS:
        Categoria.objects.get_or_create(
            nombre=cat["nombre"],
            defaults={"descripcion": cat["descripcion"]}
        )
 
def desempadronar_categorias(apps, schema_editor):
    Categoria = apps.get_model('ventas', 'Categoria')
    Categoria.objects.filter(nombre__in=[c["nombre"] for c in CATEGORIAS]).delete()
 
class Migration(migrations.Migration):
    dependencies = [
        ('ventas', '0004_constraints_reglas_negocio'),
    ]
 
    operations = [
        migrations.RunPython(sembrar_categorias, reverse_code=desempadronar_categorias),
    ]

Contenido

📚 Cursos de Café y Código

6. Paso a Paso: Sistema de Boletas y Migraciones Evolutivas 🧾

1. El Reto Real: Construir una Base de Datos que Evoluciona

2. Línea de Tiempo Interactiva de la Base de Datos

Evolución de la Base de Datos: Sistema de Boletas POS

Creación de Categoría y Producto

3. Desglose Técnico Paso a Paso

Paso 1: Catálogo Base (Migración `0001_initial.py`)

Paso 2: Transacciones de Venta (Migración `0002_boleta_detalleboleta.py`)

Paso 3: Incorporación de Cliente Opcional (Migración `0003_cliente_boleta_cliente.py`)

Paso 4: Blindaje con Restricciones CheckConstraint y `save()` Automatizado

Paso 5: Migración de Datos con `RunPython` (`0005_sembrar_categorias_iniciales.py`)

Ponte a prueba

¡Hecho con mucho cariño! ☕