Módulo 3: Modelos, relaciones, ORM y administración

Introducción

En los módulos anteriores construiste el recorrido web y la capa visual de una aplicación:

URL → vista → contexto → template → respuesta

Los datos todavía provenían de listas y diccionarios escritos dentro de Python. Esa solución permite practicar vistas y templates, pero no sirve para una aplicación empresarial real:

productos = [
    {"nombre": "Teclado", "precio": 25, "existencias": 8},
    {"nombre": "Monitor", "precio": 180, "existencias": 3},
]

Al detener el servidor, modificar el archivo o trabajar con cientos de registros aparecen problemas:

• la información no puede administrarse con seguridad;
• no existen relaciones confiables;
• dos registros pueden contradecirse;
• buscar o actualizar datos se vuelve difícil;
• el programa mezcla datos, lógica y presentación;
• varias personas no pueden trabajar con la misma información.

En este módulo reemplazarás los datos temporales por una estructura persistente:

Interfaz Django
      ↓
     ORM
      ↓
Modelos y relaciones
      ↓
Base de datos SQLite

El ORM de Django permite trabajar con la base de datos mediante objetos y métodos de Python. No elimina la necesidad de comprender SQL. Al contrario: los conocimientos de tablas, claves, relaciones e integridad permiten diseñar mejores modelos y comprender lo que el ORM ejecuta.

La meta no es memorizar todos los campos ni todas las consultas posibles. La meta es aprender a:

• diseñar antes de programar;
• transformar entidades en modelos;
• proteger la integridad de los datos;
• cambiar el esquema mediante migraciones;
• consultar información con intención;
• detectar consultas innecesarias;
• administrar datos desde una herramienta interna.

Al finalizar, el sitio del módulo anterior dejará de ser una demostración visual y tendrá el núcleo de datos de un sistema empresarial.

Objetivos de aprendizaje

Al finalizar este módulo podrás:

• identificar entidades, atributos y relaciones;
• crear un diagrama entidad-relación;
• convertir tablas SQL en modelos Django;
• seleccionar campos y opciones adecuados;
• distinguir null de blank;
• utilizar valores predeterminados, opciones e índices;
• definir restricciones de unicidad y validaciones básicas;
• crear relaciones uno a muchos, muchos a muchos y uno a uno;
• elegir conscientemente un comportamiento on_delete;
• comprender la integridad referencial;
• configurar un modelo de usuario personalizado desde el inicio;
• crear, leer e interpretar migraciones;
• aplicar cambios al esquema sin editar la base directamente;
• utilizar la consola de Django de forma responsable;
• crear, consultar, modificar y eliminar registros mediante el ORM;
• utilizar get, filter, exclude y order_by;
• realizar búsquedas con Q;
• actualizar valores con F;
• calcular agregaciones iniciales;
• recorrer relaciones desde ambos sentidos;
• reconocer y corregir el problema N+1;
• crear datos de prueba reproducibles;
• registrar y personalizar modelos en Django Admin;
• diferenciar el panel administrativo de la aplicación pública;
• revisar diseños y consultas con IA sin delegar decisiones críticas.

Conocimientos previos

Antes de comenzar debes poder:

• crear y ejecutar un proyecto Django;
• crear aplicaciones y conectarlas al proyecto;
• utilizar URLs, vistas y templates;
• trabajar con clases y objetos de Python;
• comprender tablas, filas y columnas;
• reconocer una clave primaria y una clave foránea;
• utilizar Git y crear commits.

Si completaste la ruta de COA, estos conocimientos provienen de Programación Orientada a Objetos, SQL y Bases de Datos, Python Práctico y los módulos anteriores de este curso.

Distribución recomendada del tiempo

El tiempo es una referencia. Si una relación o una migración no se comprende, detente y compruébala antes de avanzar. Los errores de diseño se vuelven más costosos cuando el sistema ya contiene datos.

De una necesidad empresarial a un modelo de datos

Una base de datos no comienza con models.py. Comienza con preguntas sobre el negocio.

Supón que una empresa necesita controlar inventario:

• ¿Qué productos vende?
• ¿Cómo se agrupan?
• ¿Quién los suministra?
• ¿Cuántas unidades existen?
• ¿Qué movimientos aumentan o reducen las existencias?
• ¿Quién registró cada movimiento?
• ¿Qué información debe ser única?
• ¿Qué datos pueden faltar?
• ¿Qué registros deben conservarse como historial?

Las respuestas permiten identificar entidades:

Categoría
Proveedor
Producto
Cliente
Movimiento de inventario
Usuario

Después se identifican atributos:

Producto
├── código
├── nombre
├── precio
├── existencias
├── activo
├── categoría
└── proveedor

Finalmente se definen reglas:

• el código de producto no se repite;
• el precio no puede ser negativo;
• las existencias no deben quedar por debajo de cero;
• cada producto pertenece a una categoría;
• un proveedor puede suministrar muchos productos;
• cada movimiento pertenece a un producto;
• cada movimiento registra el usuario responsable.

Estas reglas determinan campos, relaciones, restricciones y validaciones.

Antes de crear un campo, responde:

¿Qué regla del negocio representa y qué ocurriría si su valor fuera incorrecto?

Si no puedes responder, todavía falta analizar el requisito.

Entidades, atributos y relaciones

Una entidad representa algo que el sistema necesita identificar de forma independiente. Un atributo describe esa entidad. Una relación conecta entidades.

No conviertas cada palabra del requisito en un modelo. “Dirección de correo” suele ser un atributo; “Cliente” puede ser una entidad.

Una señal útil para crear una entidad independiente es que:

• tiene varios atributos propios;
• aparece en diferentes procesos;
• debe poder consultarse por separado;
• se relaciona con varios registros;
• posee una identidad o ciclo de vida propio.

Diagrama entidad-relación

El diagrama entidad-relación permite detectar errores antes de escribir migraciones.

Ejemplo simplificado:

┌──────────────┐       1          N       ┌──────────────┐
│  CATEGORÍA   │──────────────────────────│   PRODUCTO   │
├──────────────┤                          ├──────────────┤
│ id PK        │                          │ id PK        │
│ nombre UQ    │                          │ código UQ    │
└──────────────┘                          │ nombre       │
                                        │ categoría FK │
                                        └──────┬───────┘
                                               │ 1
                                               │
                                               │ N
                                        ┌──────▼───────┐
                                        │  MOVIMIENTO  │
                                        ├──────────────┤
                                        │ id PK        │
                                        │ tipo         │
                                        │ cantidad     │
                                        │ producto FK  │
                                        │ usuario FK   │
                                        └──────────────┘

Leyenda:

PK = clave primaria
FK = clave foránea
UQ = valor único
1  = un registro
N  = muchos registros

Para cada relación indica:

• cardinalidad;
• obligatoriedad;
• nombre desde cada lado;
• comportamiento al eliminar;
• razón empresarial.

Ejemplo:

Del diseño SQL al modelo Django

En SQL podrías crear una tabla:

CREATE TABLE categoria (
    id INTEGER PRIMARY KEY,
    nombre VARCHAR(80) NOT NULL UNIQUE,
    activa BOOLEAN NOT NULL DEFAULT 1
);

Su equivalente conceptual en Django es:

from django.db import models


class Categoria(models.Model):
    nombre = models.CharField(max_length=80, unique=True)
    activa = models.BooleanField(default=True)

    def __str__(self):
        return self.nombre

Django genera por defecto una clave primaria llamada id si no defines otra. En proyectos nuevos suele ser un BigAutoField, según la configuración DEFAULT_AUTO_FIELD.

El modelo no es solamente una copia de la tabla. También puede contener:

• nombres legibles;
• orden predeterminado;
• restricciones;
• índices;
• métodos relacionados con la entidad;
• reglas que ayudan a representar y administrar los datos.

Campos utilizados con mayor frecuencia

Para dinero utiliza DecimalField, no FloatField:

precio = models.DecimalField(max_digits=10, decimal_places=2)

max_digits=10 representa la cantidad total de dígitos y decimal_places=2 reserva dos posiciones decimales.

Selecciona el campo que comunique mejor la intención. Un correo podría almacenarse en CharField, pero EmailField expresa mejor la regla y aporta validación cuando se usa mediante formularios.

Opciones de los campos

Controla si un campo puede quedar vacío durante la validación de formularios y modelos:

telefono = models.CharField(max_length=25, blank=True)

Controla si la base de datos almacena NULL:

fecha_baja = models.DateField(null=True, blank=True)

En campos de texto normalmente se prefiere blank=True sin null=True, para evitar dos representaciones de “sin texto”: cadena vacía y NULL.

Texto opcional  → blank=True
Fecha opcional  → null=True, blank=True

Proporciona un valor inicial:

activo = models.BooleanField(default=True)

Para valores calculados usa una función, no su resultado:

from django.utils import timezone

fecha_registro = models.DateTimeField(default=timezone.now)

No escribas timezone.now() si deseas que la fecha se calcule al crear cada registro.

Evita valores repetidos:

codigo = models.CharField(max_length=30, unique=True)

Usa unique=True solo cuando la regla empresarial lo exige. Dos personas pueden tener el mismo nombre; dos productos no deberían tener el mismo código interno.

Limita un campo a opciones conocidas:

class Movimiento(models.Model):
    class Tipo(models.TextChoices):
        ENTRADA = "ENTRADA", "Entrada"
        SALIDA = "SALIDA", "Salida"
        AJUSTE = "AJUSTE", "Ajuste"

    tipo = models.CharField(max_length=10, choices=Tipo.choices)

El valor guardado es estable y la etiqueta puede mostrarse con:

movimiento.get_tipo_display()

Crea un índice para búsquedas frecuentes:

nombre = models.CharField(max_length=150, db_index=True)

Un índice puede acelerar lecturas, pero ocupa espacio y añade trabajo a las escrituras. No indexes todos los campos sin medir una necesidad.

Representación y metadatos

Una representación clara mejora la consola, el admin y los selectores:

def __str__(self):
    return f"{self.codigo} - {self.nombre}"

No debe realizar consultas costosas ni exponer información sensible.

class Meta:
    ordering = ["nombre"]
    verbose_name = "producto"
    verbose_name_plural = "productos"

También puede definir restricciones e índices:

class Meta:
    constraints = [
        models.CheckConstraint(
            condition=models.Q(precio__gte=0),
            name="producto_precio_no_negativo",
        ),
    ]
    indexes = [
        models.Index(fields=["activo", "nombre"]),
    ]

El nombre de una restricción debe describir la regla y mantenerse estable.

ordering es útil cuando existe un orden natural, pero cada consulta ordenada tiene un costo. También puedes ordenar únicamente cuando lo necesitas:

Producto.objects.order_by("nombre")

Claves primarias: identidad interna y código empresarial

Django crea un identificador interno:

id = 42

El negocio puede utilizar otro código:

SKU-2026-0042

No son necesariamente lo mismo.

• La clave primaria identifica internamente el registro.
• El código empresarial representa una regla visible del negocio.

Una estrategia simple:

codigo = models.CharField(max_length=30, unique=True)

Conserva el id automático y añade el código como campo único. Evita convertir un dato modificable en clave primaria sin una razón técnica sólida.

Relaciones uno a muchos

Una categoría puede tener muchos productos, mientras cada producto pertenece a una categoría:

class Categoria(models.Model):
    nombre = models.CharField(max_length=80, unique=True)


class Producto(models.Model):
    categoria = models.ForeignKey(
        Categoria,
        on_delete=models.PROTECT,
        related_name="productos",
    )

Recorrido directo:

producto.categoria

Recorrido inverso:

categoria.productos.all()

related_name debe ser claro, plural cuando devuelve una colección y consistente con el dominio.

Relaciones muchos a muchos

Un libro puede tener varios autores y un autor puede escribir varios libros:

class Autor(models.Model):
    nombre = models.CharField(max_length=120)


class Libro(models.Model):
    titulo = models.CharField(max_length=180)
    autores = models.ManyToManyField(
        Autor,
        related_name="libros",
    )

Uso:

libro.autores.add(autor)
autor.libros.all()

Django crea una tabla intermedia. Si la relación necesita datos propios, crea un modelo explícito:

class Participacion(models.Model):
    libro = models.ForeignKey(Libro, on_delete=models.CASCADE)
    autor = models.ForeignKey(Autor, on_delete=models.CASCADE)
    rol = models.CharField(max_length=50)
    orden = models.PositiveIntegerField(default=1)

La relación deja de ser solo “libro–autor” y se convierte en una entidad con atributos.

Relaciones uno a uno

Una relación uno a uno amplía una entidad sin permitir varios registros asociados:

from django.conf import settings


class Perfil(models.Model):
    usuario = models.OneToOneField(
        settings.AUTH_USER_MODEL,
        on_delete=models.CASCADE,
        related_name="perfil",
    )
    telefono = models.CharField(max_length=25, blank=True)

Uso:

usuario.perfil
perfil.usuario

No crees un perfil únicamente para evitar agregar campos al usuario. Utilízalo cuando la información tenga un propósito y ciclo de vida claramente separado.

Integridad referencial y on_delete

Una clave foránea no es solamente un enlace cómodo. Protege la coherencia entre registros relacionados.

Cuando se intenta eliminar el registro principal, Django necesita una política.

Ejemplo:

categoria = models.ForeignKey(
    Categoria,
    on_delete=models.PROTECT,
    related_name="productos",
)

PROTECT comunica que una categoría utilizada no puede desaparecer sin resolver primero sus productos.

Para SET_NULL, el campo debe aceptar NULL:

proveedor = models.ForeignKey(
    Proveedor,
    on_delete=models.SET_NULL,
    null=True,
    blank=True,
    related_name="productos",
)

1. ¿El registro dependiente conserva valor histórico sin su relación?
2. ¿Eliminar el principal debe borrar información empresarial?
3. ¿El usuario debe corregir dependencias antes de eliminar?
4. ¿La ausencia de relación es válida?
5. ¿Una eliminación accidental sería recuperable?

No elijas CASCADE solo porque aparece con frecuencia en ejemplos.

Modelo de usuario personalizado desde el inicio

Django recomienda considerar un modelo de usuario personalizado al comenzar un proyecto. Aunque inicialmente no tenga campos adicionales, cambiarlo después de crear tablas y relaciones puede ser complejo.

El proyecto empresarial que continuará hasta el final comienza en este módulo. Configura el usuario antes de ejecutar las primeras migraciones de este nuevo núcleo.

Estructura:

gestion_empresarial/
├── manage.py
├── gestion_empresarial/
├── cuentas/
└── inventario/

Crea la aplicación:

python manage.py startapp cuentas

cuentas/models.py:

from django.contrib.auth.models import AbstractUser


class Usuario(AbstractUser):
    pass

gestion_empresarial/settings.py:

INSTALLED_APPS = [
    # Aplicaciones de Django
    "cuentas",
    "inventario",
]

AUTH_USER_MODEL = "cuentas.Usuario"

cuentas/admin.py:

from django.contrib import admin
from django.contrib.auth.admin import UserAdmin

from .models import Usuario


@admin.register(Usuario)
class UsuarioAdmin(UserAdmin):
    pass

Para relacionar otros modelos con el usuario:

from django.conf import settings
from django.db import models


creado_por = models.ForeignKey(
    settings.AUTH_USER_MODEL,
    on_delete=models.PROTECT,
    related_name="productos_creados",
)

No importes directamente Usuario dentro de modelos de otras aplicaciones.

En un proyecto educativo sin datos importantes puedes iniciar una copia limpia y reutilizar los templates del módulo anterior. No borres bases de datos ni migraciones de un sistema real para “arreglarlo rápido”. Una migración de usuario en producción requiere un plan específico, respaldo y pruebas.

Modelos del núcleo empresarial

Una primera versión organizada puede ser:

from django.conf import settings
from django.core.validators import MinValueValidator
from django.db import models


class Categoria(models.Model):
    nombre = models.CharField(max_length=80, unique=True)
    descripcion = models.TextField(blank=True)
    activa = models.BooleanField(default=True)

    class Meta:
        ordering = ["nombre"]
        verbose_name = "categoría"
        verbose_name_plural = "categorías"

    def __str__(self):
        return self.nombre


class Proveedor(models.Model):
    nombre = models.CharField(max_length=120)
    identificacion = models.CharField(max_length=30, unique=True)
    correo = models.EmailField(blank=True)
    telefono = models.CharField(max_length=25, blank=True)
    activo = models.BooleanField(default=True)

    class Meta:
        ordering = ["nombre"]

    def __str__(self):
        return self.nombre


class Producto(models.Model):
    codigo = models.CharField(max_length=30, unique=True)
    nombre = models.CharField(max_length=150, db_index=True)
    descripcion = models.TextField(blank=True)
    categoria = models.ForeignKey(
        Categoria,
        on_delete=models.PROTECT,
        related_name="productos",
    )
    proveedores = models.ManyToManyField(
        Proveedor,
        related_name="productos",
        blank=True,
    )
    precio = models.DecimalField(
        max_digits=10,
        decimal_places=2,
        validators=[MinValueValidator(0)],
    )
    existencias = models.PositiveIntegerField(default=0)
    stock_minimo = models.PositiveIntegerField(default=0)
    activo = models.BooleanField(default=True)
    creado_por = models.ForeignKey(
        settings.AUTH_USER_MODEL,
        on_delete=models.PROTECT,
        related_name="productos_creados",
    )
    creado_en = models.DateTimeField(auto_now_add=True)
    actualizado_en = models.DateTimeField(auto_now=True)

    class Meta:
        ordering = ["nombre"]
        constraints = [
            models.CheckConstraint(
                condition=models.Q(precio__gte=0),
                name="producto_precio_no_negativo",
            ),
        ]

    def __str__(self):
        return f"{self.codigo} - {self.nombre}"

MinValueValidator ayuda en validaciones de Django y CheckConstraint protege la regla en la base de datos. Son capas complementarias.

class Cliente(models.Model):
    nombre = models.CharField(max_length=120)
    identificacion = models.CharField(max_length=30, unique=True)
    correo = models.EmailField(blank=True)
    telefono = models.CharField(max_length=25, blank=True)
    activo = models.BooleanField(default=True)
    creado_en = models.DateTimeField(auto_now_add=True)

    class Meta:
        ordering = ["nombre"]

    def __str__(self):
        return self.nombre


class MovimientoInventario(models.Model):
    class Tipo(models.TextChoices):
        ENTRADA = "ENTRADA", "Entrada"
        SALIDA = "SALIDA", "Salida"
        AJUSTE = "AJUSTE", "Ajuste"

    producto = models.ForeignKey(
        Producto,
        on_delete=models.PROTECT,
        related_name="movimientos",
    )
    tipo = models.CharField(max_length=10, choices=Tipo.choices)
    cantidad = models.PositiveIntegerField(
        validators=[MinValueValidator(1)]
    )
    motivo = models.CharField(max_length=180)
    registrado_por = models.ForeignKey(
        settings.AUTH_USER_MODEL,
        on_delete=models.PROTECT,
        related_name="movimientos_registrados",
    )
    registrado_en = models.DateTimeField(auto_now_add=True)

    class Meta:
        ordering = ["-registrado_en"]

    def __str__(self):
        return f"{self.get_tipo_display()} - {self.producto.codigo}"

En este módulo el modelo representa el historial. La operación transaccional que modificará existencias y creará el movimiento de forma atómica se desarrollará cuando se construyan los servicios y formularios del sistema.

Migraciones: historial del esquema

Una migración describe un cambio versionado en la estructura de la base de datos.

models.py
   ↓ makemigrations
archivo de migración
   ↓ migrate
esquema de la base de datos

Comandos principales:

python manage.py makemigrations
python manage.py migrate
python manage.py showmigrations

Proceso recomendado:

1. modifica el modelo;
2. ejecuta las comprobaciones;
3. crea la migración;
4. lee el archivo generado;
5. revisa el plan;
6. aplica la migración;
7. prueba el sistema;
8. incluye el archivo en Git.

class Migration(migrations.Migration):
    dependencies = [
        ("inventario", "0001_initial"),
    ]

    operations = [
        migrations.AddField(
            model_name="producto",
            name="stock_minimo",
            field=models.PositiveIntegerField(default=0),
        ),
    ]

dependencies indica qué cambios deben existir antes. operations describe el cambio.

Puedes revisar el plan sin aplicarlo:

python manage.py migrate --plan

Y observar el SQL aproximado:

python manage.py sqlmigrate inventario 0001

El SQL exacto depende del motor de base de datos.

Reglas profesionales para migraciones

• Incluye las migraciones en el repositorio.
• No edites una base de datos manualmente para evitar una migración.
• No elimines migraciones compartidas sin coordinar.
• No cambies una migración ya aplicada en otros entornos por comodidad.
• Revisa valores predeterminados antes de agregar campos obligatorios.
• Realiza respaldo antes de cambios de alto riesgo.
• Prueba las migraciones en una base diferente antes de producción.
• Separa cambios de esquema de cargas de datos complejas cuando convenga.

Cambiar models.py no cambia automáticamente la base:

Código actualizado + base antigua = errores

La migración mantiene ambas representaciones sincronizadas.

Consola de Django

La consola carga la configuración del proyecto y permite trabajar con los modelos:

python manage.py shell

Importación:

from inventario.models import Categoria, Producto

Úsala para:

• explorar el ORM;
• comprobar una consulta;
• crear pocos datos de prueba;
• inspeccionar una relación;
• reproducir un error.

No la utilices para cambios manuales irrepetibles en producción. Si un proceso debe ejecutarse varias veces o dejar evidencia, crea un comando de administración o una migración de datos.

Crear registros con el ORM

categoria = Categoria.objects.create(
    nombre="Periféricos",
    descripcion="Accesorios para equipos de cómputo",
)

categoria = Categoria(
    nombre="Monitores",
    descripcion="Pantallas y accesorios",
)
categoria.save()

categoria, creada = Categoria.objects.get_or_create(
    nombre="Periféricos",
    defaults={"descripcion": "Accesorios para computadoras"},
)

get_or_create es útil en procesos repetibles, siempre que los campos usados para buscar identifiquen correctamente el registro.

El objeto principal debe existir antes:

producto.proveedores.add(proveedor_a, proveedor_b)
producto.proveedores.remove(proveedor_b)
producto.proveedores.set([proveedor_a])
producto.proveedores.clear()

Consultar registros

Producto.objects.all()

Producto.objects.get(codigo="TEC-001")

get() espera exactamente un resultado. Puede producir:

• Producto.DoesNotExist;
• Producto.MultipleObjectsReturned.

Utilízalo cuando la condición identifica un único registro.

Producto.objects.filter(activo=True)

Producto.objects.exclude(existencias=0)

Producto.objects.order_by("nombre")
Producto.objects.order_by("-creado_en")

Producto.objects.order_by("-creado_en")[:5]

Un QuerySet es perezoso: normalmente Django construye la consulta y la ejecuta cuando necesita los resultados.

Consultas mediante lookups

Los lookups se separan con doble guion bajo:

Producto.objects.filter(nombre__icontains="teclado")
Producto.objects.filter(precio__gte=25)
Producto.objects.filter(precio__lte=200)
Producto.objects.filter(existencias__gt=0)
Producto.objects.filter(codigo__startswith="TEC")
Producto.objects.filter(categoria__nombre="Periféricos")

Lookups frecuentes:

Puedes encadenar consultas:

Producto.objects.filter(
    activo=True,
    existencias__gt=0,
).order_by("nombre")

Consultas a través de relaciones

Productos de una categoría:

Producto.objects.filter(categoria__nombre="Periféricos")

Movimientos de productos activos:

MovimientoInventario.objects.filter(producto__activo=True)

Recorrido inverso:

Categoria.objects.filter(productos__existencias__lt=5).distinct()

distinct() evita duplicados cuando una unión puede producir varias filas para la misma categoría.

Desde una instancia:

categoria.productos.filter(activo=True)
producto.movimientos.order_by("-registrado_en")
proveedor.productos.all()

Antes de escribir una consulta relacional, dibuja el recorrido:

Movimiento → Producto → Categoría → nombre

Se traduce en:

MovimientoInventario.objects.filter(
    producto__categoria__nombre="Periféricos"
)

Búsquedas complejas con Q

Los argumentos normales de filter() se combinan con AND. Para expresar OR, negación o grupos utiliza Q:

from django.db.models import Q


Producto.objects.filter(
    Q(nombre__icontains="teclado")
    | Q(codigo__icontains="teclado")
)

Combinar condiciones:

Producto.objects.filter(
    Q(nombre__icontains="pro")
    | Q(descripcion__icontains="pro"),
    activo=True,
)

Negación:

Producto.objects.filter(~Q(existencias=0))

Usa paréntesis cuando la combinación pueda resultar ambigua:

criterio = (
    Q(nombre__icontains=termino)
    | Q(codigo__icontains=termino)
)
productos = Producto.objects.filter(criterio, activo=True)

Operaciones con F

Una expresión F hace referencia al valor de una columna dentro de la base:

from django.db.models import F


Producto.objects.filter(pk=producto_id).update(
    existencias=F("existencias") + 5
)

Esto evita leer el valor, sumarlo en Python y guardarlo en pasos separados.

Comparar columnas:

Producto.objects.filter(existencias__lte=F("stock_minimo"))

Después de asignar una expresión F a una instancia y guardarla, vuelve a cargar el objeto si necesitas el valor actualizado:

producto.refresh_from_db()

F ayuda a evitar ciertas condiciones de carrera, pero una operación empresarial con varios cambios todavía puede requerir una transacción. Esa arquitectura se desarrollará más adelante.

Modificar y eliminar

from decimal import Decimal


producto.precio = Decimal("29.90")
producto.save(update_fields=["precio", "actualizado_en"])

Producto.objects.filter(activo=False).update(existencias=0)

update() trabaja directamente en la base y no llama al método save() de cada instancia.

producto.delete()

El resultado depende de las relaciones y de on_delete.

Antes de ejecutar una actualización o eliminación masiva:

objetivo = Producto.objects.filter(activo=False)
print(objetivo.count())
print(list(objetivo.values("codigo", "nombre")[:10]))

Confirma primero el conjunto afectado. En sistemas empresariales puede ser preferible desactivar un registro y conservar el historial.

Agregaciones iniciales

Las agregaciones calculan un resultado sobre un conjunto:

from django.db.models import Avg, Count, Max, Min, Sum


resumen = Producto.objects.aggregate(
    cantidad=Count("id"),
    precio_promedio=Avg("precio"),
    precio_minimo=Min("precio"),
    precio_maximo=Max("precio"),
    unidades=Sum("existencias"),
)

Resultado aproximado:

{
    "cantidad": 18,
    "precio_promedio": Decimal("42.75"),
    "precio_minimo": Decimal("3.50"),
    "precio_maximo": Decimal("250.00"),
    "unidades": 126,
}

Agrupar con annotate:

categorias = Categoria.objects.annotate(
    total_productos=Count("productos")
).order_by("-total_productos")

Filtrar una anotación:

Categoria.objects.annotate(
    total_productos=Count("productos")
).filter(total_productos__gt=0)

No uses ciclos de Python para contar o sumar miles de filas si la base puede realizar la operación eficientemente.

Comprender el SQL generado

El ORM no es magia. Puedes inspeccionar una consulta:

consulta = Producto.objects.filter(
    categoria__nombre="Periféricos",
    activo=True,
).order_by("nombre")

print(consulta.query)

La representación ayuda a relacionar:

filter()       → WHERE
order_by()     → ORDER BY
ForeignKey     → JOIN
aggregate()    → COUNT, SUM, AVG...

El SQL puede variar entre motores. Lo importante es reconocer la intención, las uniones y los filtros.

Consultas repetidas y problema N+1

Este código parece sencillo:

productos = Producto.objects.all()

for producto in productos:
    print(producto.categoria.nombre)

Puede ejecutar:

1 consulta para productos
+ 1 consulta por cada categoría accedida
= N + 1 consultas

Para una relación ForeignKey o OneToOneField:

productos = Producto.objects.select_related("categoria", "creado_por")

Para relaciones muchos a muchos o conjuntos inversos:

productos = Producto.objects.prefetch_related("proveedores")

Uso combinado:

productos = (
    Producto.objects
    .select_related("categoria", "creado_por")
    .prefetch_related("proveedores")
    .filter(activo=True)
)

No agregues optimizaciones al azar. Identifica qué relaciones utiliza la vista y comprueba la cantidad de consultas.

Django Admin: herramienta interna

El panel administrativo permite administrar modelos con poco código. Está pensado como herramienta interna para usuarios autorizados, no como interfaz pública para clientes.

Crear un superusuario:

python manage.py createsuperuser

Registrar un modelo:

from django.contrib import admin

from .models import Categoria


admin.site.register(Categoria)

Personalización:

@admin.register(Producto)
class ProductoAdmin(admin.ModelAdmin):
    list_display = (
        "codigo",
        "nombre",
        "categoria",
        "precio",
        "existencias",
        "activo",
    )
    list_filter = ("activo", "categoria")
    search_fields = ("codigo", "nombre")
    ordering = ("nombre",)
    list_select_related = ("categoria",)
    readonly_fields = ("creado_en", "actualizado_en")

Cada opción responde a una necesidad:

• list_display: columnas importantes;
• list_filter: filtros laterales;
• search_fields: búsqueda;
• ordering: orden;
• list_select_related: reduce consultas de claves foráneas;
• readonly_fields: información visible que no debe editarse manualmente.

Organización del formulario administrativo

Puedes agrupar campos:

@admin.register(Proveedor)
class ProveedorAdmin(admin.ModelAdmin):
    list_display = ("nombre", "identificacion", "correo", "activo")
    list_filter = ("activo",)
    search_fields = ("nombre", "identificacion", "correo")

    fieldsets = (
        (
            "Identificación",
            {"fields": ("nombre", "identificacion")},
        ),
        (
            "Contacto",
            {"fields": ("correo", "telefono")},
        ),
        (
            "Estado",
            {"fields": ("activo",)},
        ),
    )

Una buena pantalla administrativa:

• muestra lo necesario;
• facilita buscar;
• evita editar datos calculados;
• utiliza nombres comprensibles;
• conserva una cantidad razonable de columnas;
• no expone campos sensibles.

Acciones administrativas básicas

Una acción puede modificar varios registros seleccionados:

@admin.action(description="Marcar productos seleccionados como activos")
def activar_productos(modeladmin, request, queryset):
    actualizados = queryset.update(activo=True)
    modeladmin.message_user(
        request,
        f"{actualizados} producto(s) activado(s).",
    )


@admin.register(Producto)
class ProductoAdmin(admin.ModelAdmin):
    actions = [activar_productos]

Una acción debe:

• tener un propósito claro;
• afectar únicamente el conjunto seleccionado;
• informar el resultado;
• respetar permisos;
• evitar operaciones destructivas innecesarias.

No agregues una acción de eliminación irreversible solo porque puede programarse.

Datos de prueba reproducibles

Crear datos manualmente desde el admin es útil para comprobar pantallas, pero no permite reconstruir el escenario con facilidad.

Un comando de administración deja un proceso repetible:

inventario/
└── management/
    └── commands/
        └── cargar_datos_prueba.py

cargar_datos_prueba.py:

from decimal import Decimal

from django.contrib.auth import get_user_model
from django.core.management.base import BaseCommand

from inventario.models import Categoria, Producto, Proveedor


class Command(BaseCommand):
    help = "Crea datos de demostración para inventario"

    def handle(self, *args, **options):
        Usuario = get_user_model()
        usuario, usuario_creado = Usuario.objects.get_or_create(
            username="demo",
            defaults={"email": "demo@example.com"},
        )
        if usuario_creado:
            usuario.set_unusable_password()
            usuario.save(update_fields=["password"])

        categoria, _ = Categoria.objects.get_or_create(
            nombre="Periféricos",
            defaults={"descripcion": "Accesorios de cómputo"},
        )
        proveedor, _ = Proveedor.objects.get_or_create(
            identificacion="PROV-001",
            defaults={
                "nombre": "Distribuciones Central",
                "correo": "ventas@example.com",
            },
        )
        producto, creado = Producto.objects.get_or_create(
            codigo="TEC-001",
            defaults={
                "nombre": "Teclado ergonómico",
                "descripcion": "Teclado para oficina",
                "categoria": categoria,
                "precio": Decimal("29.90"),
                "existencias": 12,
                "stock_minimo": 4,
                "creado_por": usuario,
            },
        )
        producto.proveedores.add(proveedor)

        mensaje = "creado" if creado else "ya existía"
        self.stdout.write(
            self.style.SUCCESS(f"Producto {mensaje}: {producto.codigo}")
        )

Ejecutar:

python manage.py cargar_datos_prueba

El comando es idempotente para esos datos: ejecutarlo otra vez no debe duplicarlos.

Usa datos ficticios y evita copiar información personal real a un entorno de desarrollo.

Inteligencia Artificial para revisar datos

La IA puede encontrar posibilidades, pero no conoce por sí sola las reglas verdaderas de una empresa.

• convertir requisitos escritos en una lista inicial de entidades;
• cuestionar una relación;
• explicar una migración generada;
• proponer casos límite;
• revisar nombres de campos;
• generar datos ficticios;
• traducir una consulta ORM a SQL conceptual;
• detectar una posible consulta N+1;
• comparar un modelo con una rúbrica.

• qué datos puede eliminar la empresa;
• cuáles datos son sensibles;
• qué campo debe ser único;
• qué historial debe conservarse;
• qué permisos tendrá cada persona;
• si una migración es segura para producción;
• si los datos generados son legales o apropiados.

Actúa como revisor de diseño de datos para Django 5.2.
No reescribas el código todavía.

Contexto del negocio:
[reglas reales]

Modelo propuesto:
[código]

Revisa:
1. entidades y responsabilidades;
2. cardinalidades;
3. null y blank;
4. unicidad;
5. on_delete;
6. restricciones;
7. nombres inversos;
8. datos históricos;
9. posibles consultas N+1.

Clasifica cada hallazgo como crítico, importante o mejora.
No inventes reglas empresariales: formula preguntas cuando falte información.

Explica esta migración de Django operación por operación.
Indica qué cambiará en la base, qué datos podrían verse afectados
y qué comprobaciones realizarías antes y después.
No asumas que es segura solo porque fue generada automáticamente.

Compara este requisito, la consulta ORM y el modelo.
Explica si el resultado corresponde al requisito.
Señala duplicados posibles, joins, orden, evaluación del QuerySet
y consultas adicionales al recorrer relaciones.
Propón primero una prueba mínima y después una corrección, si hace falta.

Por cada intervención importante conserva:

Errores comunes y soluciones

Requisito
   ↓
Modelo
   ↓
Migración
   ↓
Esquema
   ↓
Datos
   ↓
Consulta
   ↓
Presentación

Identifica en qué capa aparece la diferencia. No cambies el template si la consulta devuelve datos incorrectos, ni edites SQLite si falta una migración.

Recomendaciones profesionales

• Diseña las entidades antes de escribir modelos.
• Conserva un diccionario de datos.
• Pregunta por las reglas de eliminación.
• Distingue identidad interna de código empresarial.
• Utiliza DecimalField para dinero.
• Evita null=True en texto sin una razón.
• Usa settings.AUTH_USER_MODEL en relaciones.
• Configura el usuario personalizado al iniciar el proyecto.
• Lee cada migración.
• Incluye migraciones en Git.
• No modifiques manualmente el esquema.
• Confirma el conjunto antes de actualizar o eliminar en masa.
• Usa el admin como herramienta interna.
• Crea datos de prueba ficticios y reproducibles.
• Inspecciona el SQL cuando una consulta no se comprende.
• Corrige N+1 según las relaciones utilizadas.
• No optimices sin observar una necesidad.
• No coloques reglas centrales en señales para ocultar su ejecución.
• Registra las decisiones sugeridas por IA.
• Conserva la base de desarrollo fuera del repositorio si contiene datos sensibles.

Videos recomendados

Los siguientes videos son apoyo práctico. La documentación oficial de Django 5.2 es la referencia principal cuando una interfaz o sintaxis difiera.

LatamCode

Video breve en español de un canal pequeño. Úsalo para reforzar el ciclo models.py → makemigrations → migrate.

OpenWebinars

Refuerza el propósito de las migraciones. Comprueba los comandos con la documentación de Django 5.2.

Raul Torres

Úsalo para observar consultas combinadas, comparación de columnas y relaciones. El video incluye temas posteriores; estudia únicamente las secciones relacionadas con este módulo.

Developer.pe

Refuerza columnas y personalización administrativa. La apariencia puede corresponder a una versión anterior, pero los principios seleccionados continúan vigentes.

Developer.pe

Úsalo para reforzar la sustitución del usuario. Sigue la documentación 5.2 para la implementación del proyecto.

1. Define qué concepto deseas reforzar.
2. Mira únicamente la sección pertinente.
3. Reproduce el ejemplo en un proyecto de prueba.
4. Comprueba la versión.
5. consulta la documentación.
6. Adapta el concepto al dominio empresarial.
7. Explica el resultado sin el video.

Documentación oficial

• 📖Modelos de Django 5.2
• 📖Referencia de campos
• 📖Opciones de `Meta`
• 📖Restricciones de modelos
• 📖Índices de modelos

• 📖Relaciones muchos a uno
• 📖Relaciones muchos a muchos
• 📖Relaciones uno a uno

• 📖Migraciones
• 📖Comandos `makemigrations`, `migrate` y `sqlmigrate`

• 📖Realizar consultas
• 📖API de `QuerySet`
• 📖Expresiones de consulta
• 📖Agregaciones
• 📖Optimización del acceso a la base de datos

• 📖Personalización de autenticación
• 📖Sitio administrativo de Django
• 📖Acciones del admin

• 📖Crear comandos de administración

• 📖Documentación oficial de SQLite
• 📖Claves foráneas en SQLite

Cómo consultar la documentación

No intentes memorizar la referencia completa de campos o QuerySet.

Ejemplo de búsqueda profesional:

Necesidad:
Evitar precio negativo incluso fuera del formulario.

Responsable:
Modelo y base de datos.

Documentación:
CheckConstraint + Q.

Prueba:
Intentar crear un registro inválido.

Resultado:
La base rechaza la operación.

Para cada consulta:

1. escribe el resultado esperado en lenguaje natural;
2. dibuja el recorrido entre modelos;
3. busca el método oficial;
4. crea tres datos controlados;
5. ejecuta la consulta;
6. compara resultado y expectativa;
7. inspecciona el SQL si existe duda;
8. agrega el caso a tu documentación.

Material complementario

Este módulo necesita pocos materiales, pero algunos documentos ayudan a evitar errores:

1. Plantilla de diagrama entidad-relación

• entidades;
• campos;
• claves;
• cardinalidades;
• obligatoriedad.

1. Plantilla de diccionario de datos

1. Lista de comprobación de migraciones

• cambio revisado;
• migración creada;
• archivo leído;
• plan inspeccionado;
• respaldo cuando corresponda;
• aplicación probada;
• migración incluida en Git.

1. Guía rápida de consultas ORM

• CRUD;
• lookups;
• relaciones;
• Q;
• F;
• agregaciones;
• precarga.

1. Plantilla de decisión `on_delete`

• registro principal;
• dependiente;
• valor histórico;
• política;
• riesgo;
• aprobación.

1. Matriz de pruebas de datos

• regla;
• dato válido;
• dato inválido;
• operación;
• resultado.

Estos recursos pueden mostrarse como páginas de consulta o PDFs breves. No es necesario crear un PDF separado para cada tema.

Glosario

Modelo: clase de Django que representa datos y su comportamiento relacionado.

Entidad: elemento del dominio con identidad propia.

Atributo: dato que describe una entidad.

Registro: instancia almacenada de un modelo.

Esquema: estructura de tablas, campos, relaciones y restricciones.

ORM: herramienta que permite consultar una base relacional mediante objetos y métodos.

Clave primaria: valor que identifica un registro de forma única.

Clave foránea: referencia a un registro de otra tabla.

Cardinalidad: cantidad de registros que pueden relacionarse entre dos entidades.

Integridad referencial: reglas que mantienen válidas las relaciones entre registros.

Restricción: regla protegida por la base de datos.

Índice: estructura que puede acelerar determinadas búsquedas.

Migración: cambio versionado en el esquema.

Dependencia de migración: cambio que debe existir antes de aplicar otro.

`QuerySet`: representación perezosa de una consulta y sus resultados.

Manager: interfaz de acceso al ORM, normalmente objects.

Lookup: operación de comparación usada en un filtro.

`Q`: objeto para combinar condiciones complejas.

`F`: referencia a un campo dentro de una expresión de base de datos.

Agregación: cálculo sobre un conjunto, como suma o promedio.

Anotación: valor calculado agregado a cada elemento de una consulta.

N+1: problema de rendimiento causado por una consulta inicial y consultas repetidas por registro.

`select_related`: precarga mediante unión para relaciones simples.

`prefetch_related`: precarga separada para colecciones y relaciones múltiples.

Django Admin: interfaz interna generada para administrar modelos.

Comando de administración: tarea ejecutable mediante manage.py.

Idempotencia: propiedad de una operación que puede repetirse sin producir duplicaciones o efectos adicionales indebidos.

Dato de prueba: información ficticia utilizada para comprobar el sistema.

Historial: registros que documentan operaciones pasadas y deben conservarse.

Resumen del módulo

En este módulo convertiste una interfaz en el núcleo de una aplicación persistente.

Aprendiste a:

• analizar necesidades empresariales;
• diseñar entidades y relaciones;
• representar el diseño mediante un diagrama;
• crear modelos y seleccionar campos;
• diferenciar validación y restricción;
• configurar relaciones y comportamientos de eliminación;
• crear un usuario personalizado desde el inicio;
• generar, leer y aplicar migraciones;
• reconstruir una base desde el historial;
• crear datos de prueba repetibles;
• realizar operaciones CRUD con el ORM;
• filtrar y recorrer relaciones;
• utilizar Q, F y agregaciones;
• relacionar el ORM con SQL;
• detectar N+1;
• personalizar Django Admin;
• conectar los datos persistentes con templates;
• usar IA como herramienta de revisión verificable.

El resultado es la base sobre la que se construirán los formularios, el CRUD, los permisos, los reportes y el proyecto final.

Lista de comprobación final

• Puedo identificar entidades, atributos y relaciones.
• Puedo explicar mi diagrama.
• Distingo blank de null.
• Sé cuándo usar DecimalField.
• Puedo justificar cada on_delete.
• Comprendo el propósito de una migración.
• Puedo explicar la evaluación perezosa.
• Distingo get de filter.
• Puedo utilizar Q, F y agregaciones.
• Comprendo select_related y prefetch_related.
• Distingo el admin de la interfaz pública.

• Configuré el usuario personalizado antes de migrar.
• Implementé los modelos requeridos.
• Agregué restricciones e índices justificados.
• Incluí todas las migraciones.
• Reconstruí una base limpia.
• Creé datos ficticios reproducibles.
• Ejecuté las consultas obligatorias.
• Personalicé Django Admin.
• Conecté el catálogo con el ORM.
• Probé estados llenos y vacíos.
• Completé los doce ejercicios.
• Completé el mini proyecto.
• Completé el proyecto principal.
• Completé la evaluación práctica.

• El repositorio no contiene secretos.
• No utilicé datos personales reales.
• El README permite ejecutar el proyecto.
• El diagrama y el diccionario están incluidos.
• Las consultas están explicadas.
• Las capturas están ordenadas.
• El uso de IA está documentado.
• La carpeta y el archivo comprimido tienen el nombre solicitado.
• Todo se envió en el único punto de entrega.

Finalización del módulo

El Módulo 3 se considera completado cuando:

• obtienes al menos 80 puntos;
• el proyecto principal es aprobado;
• corriges todas las condiciones críticas;
• el sistema puede reconstruirse desde una base vacía;
• las relaciones, migraciones y consultas funcionan;
• puedes explicar las decisiones sin depender de la IA.

Cuando recibas la aprobación, estarás preparado para construir formularios, validaciones y un CRUD profesional sobre estos modelos.

No avances al Módulo 4 hasta recibir la aprobación del proyecto.