Módulo 4: Formularios, validaciones y CRUD profesional

Modelos → relaciones → migraciones → SQLite → ORM

Usuario
   ↓
Formulario HTML
   ↓
Validación de Django
   ↓
Reglas del negocio
   ↓
ORM
   ↓
Mensaje y redirección

Create  → crear
Read    → consultar
Update  → actualizar
Delete  → eliminar o desactivar conscientemente

1. GET /productos/nuevo/
   ↓
   Django crea formulario vacío
   ↓
   Navegador muestra campos

2. POST /productos/nuevo/
   ↓
   Django recibe datos
   ↓
   valida
   ├── inválido → muestra formulario con errores
   └── válido   → guarda, crea mensaje y redirige

GET /productos/
GET /productos/?q=teclado
GET /productos/42/

POST /productos/nuevo/
POST /productos/42/editar/
POST /productos/42/desactivar/

request.POST
request.FILES

GET /productos/42/eliminar/

from django import forms


class BusquedaProductoForm(forms.Form):
    q = forms.CharField(
        required=False,
        max_length=100,
        label="Buscar",
        widget=forms.TextInput(
            attrs={
                "class": "form-control",
                "placeholder": "Código o nombre",
            }
        ),
    )
    solo_activos = forms.BooleanField(
        required=False,
        initial=True,
        label="Mostrar solo activos",
        widget=forms.CheckboxInput(
            attrs={"class": "form-check-input"}
        ),
    )

formulario = BusquedaProductoForm(request.GET)

if formulario.is_valid():
    termino = formulario.cleaned_data["q"]
    solo_activos = formulario.cleaned_data["solo_activos"]

from django import forms

from .models import Producto


class ProductoForm(forms.ModelForm):
    class Meta:
        model = Producto
        fields = [
            "codigo",
            "nombre",
            "descripcion",
            "categoria",
            "proveedores",
            "precio",
            "existencias",
            "stock_minimo",
            "activo",
            "imagen",
        ]

fields = "__all__"

class ProductoForm(forms.ModelForm):
    class Meta:
        model = Producto
        fields = [
            "codigo",
            "nombre",
            "descripcion",
            "categoria",
            "proveedores",
            "precio",
            "existencias",
            "stock_minimo",
            "activo",
            "imagen",
        ]
        labels = {
            "codigo": "Código interno",
            "stock_minimo": "Existencias mínimas",
        }
        help_texts = {
            "codigo": "Utiliza un código único, por ejemplo TEC-001.",
        }
        widgets = {
            "codigo": forms.TextInput(
                attrs={"class": "form-control"}
            ),
            "nombre": forms.TextInput(
                attrs={"class": "form-control"}
            ),
            "descripcion": forms.Textarea(
                attrs={"class": "form-control", "rows": 4}
            ),
            "categoria": forms.Select(
                attrs={"class": "form-select"}
            ),
            "proveedores": forms.SelectMultiple(
                attrs={"class": "form-select", "size": 5}
            ),
            "precio": forms.NumberInput(
                attrs={"class": "form-control", "step": "0.01"}
            ),
            "existencias": forms.NumberInput(
                attrs={"class": "form-control", "min": 0}
            ),
            "stock_minimo": forms.NumberInput(
                attrs={"class": "form-control", "min": 0}
            ),
            "activo": forms.CheckboxInput(
                attrs={"class": "form-check-input"}
            ),
            "imagen": forms.ClearableFileInput(
                attrs={"class": "form-control", "accept": "image/*"}
            ),
        }

formulario = ProductoForm()

formulario = ProductoForm(request.POST, request.FILES)

formulario = ProductoForm(
    request.POST or None,
    request.FILES or None,
    instance=producto,
)

if formulario.is_valid():
    producto = formulario.save()

from django import forms


class ProductoForm(forms.ModelForm):
    def clean_codigo(self):
        codigo = self.cleaned_data["codigo"]
        codigo = codigo.strip().upper()

        if " " in codigo:
            raise forms.ValidationError(
                "El código no puede contener espacios."
            )

        return codigo

def clean_nombre(self):
    nombre = " ".join(self.cleaned_data["nombre"].split())

    if len(nombre) < 3:
        raise forms.ValidationError(
            "El nombre debe contener al menos 3 caracteres."
        )

    return nombre

def clean(self):
    datos = super().clean()
    existencias = datos.get("existencias")
    stock_minimo = datos.get("stock_minimo")
    activo = datos.get("activo")

    if (
        activo
        and existencias is not None
        and stock_minimo is not None
        and existencias < stock_minimo
    ):
        self.add_error(
            "existencias",
            "Un producto activo no puede iniciar por debajo del mínimo.",
        )

    return datos

raise forms.ValidationError(
    "La combinación de datos no es válida."
)

HTML → ayuda inmediata
Form → mensaje comprensible
Modelo → consistencia reutilizable
Base → última barrera de integridad

{% if form.non_field_errors %}
    <div class="alert alert-danger" role="alert">
        <h2 class="h6">Revisa la información general</h2>
        {{ form.non_field_errors }}
    </div>
{% endif %}

{% for field in form %}
    <div class="mb-3">
        {% if field.field.widget.input_type == "checkbox" %}
            <div class="form-check">
                {{ field }}
                {{ field.label_tag }}
            </div>
        {% else %}
            {{ field.label_tag }}
            {{ field }}
        {% endif %}

        {% if field.help_text %}
            <div class="form-text">{{ field.help_text }}</div>
        {% endif %}

        {% for error in field.errors %}
            <div class="invalid-feedback d-block">
                {{ error }}
            </div>
        {% endfor %}
    </div>
{% endfor %}

Valor inválido.
Error 500.
IntegrityError.

<form method="post">
    {% csrf_token %}
    ...
</form>

POST /productos/nuevo/
   ↓
guardar
   ↓
REDIRECT /productos/42/
   ↓
GET /productos/42/

from django.contrib import messages
from django.contrib.auth.decorators import login_required
from django.shortcuts import redirect, render


@login_required
def producto_crear(request):
    if request.method == "POST":
        formulario = ProductoForm(request.POST, request.FILES)

        if formulario.is_valid():
            producto = formulario.save(commit=False)
            producto.creado_por = request.user
            producto.save()
            formulario.save_m2m()

            messages.success(
                request,
                "El producto se registró correctamente.",
            )
            return redirect(
                "inventario:producto_detalle",
                slug=producto.slug,
            )
    else:
        formulario = ProductoForm()

    return render(
        request,
        "inventario/productos/formulario.html",
        {"form": formulario, "titulo": "Registrar producto"},
    )

messages.success(request, "El producto se actualizó.")
messages.warning(request, "El producto quedó inactivo.")
messages.error(request, "No fue posible completar la operación.")

{% if messages %}
    <div class="container mt-3" aria-live="polite">
        {% for message in messages %}
            <div
                class="alert alert-{{ message.tags|default:'info' }} alert-dismissible fade show"
                role="status"
            >
                {{ message }}
                <button
                    type="button"
                    class="btn-close"
                    data-bs-dismiss="alert"
                    aria-label="Cerrar mensaje"
                ></button>
            </div>
        {% endfor %}
    </div>
{% endif %}

def producto_lista(request):
    productos = (
        Producto.objects
        .select_related("categoria")
        .filter(activo=True)
        .order_by("nombre")
    )
    return render(
        request,
        "inventario/productos/lista.html",
        {"productos": productos},
    )

from django.shortcuts import get_object_or_404


def producto_detalle(request, slug):
    producto = get_object_or_404(
        Producto.objects.select_related("categoria"),
        slug=slug,
    )
    return render(
        request,
        "inventario/productos/detalle.html",
        {"producto": producto},
    )

@login_required
def producto_editar(request, slug):
    producto = get_object_or_404(Producto, slug=slug)
    formulario = ProductoForm(
        request.POST or None,
        request.FILES or None,
        instance=producto,
    )

    if request.method == "POST" and formulario.is_valid():
        producto = formulario.save()
        messages.success(request, "El producto se actualizó.")
        return redirect(
            "inventario:producto_detalle",
            slug=producto.slug,
        )

    return render(
        request,
        "inventario/productos/formulario.html",
        {
            "form": formulario,
            "titulo": "Editar producto",
            "producto": producto,
        },
    )

from django.views.decorators.http import require_POST


@login_required
@require_POST
def producto_desactivar(request, slug):
    producto = get_object_or_404(Producto, slug=slug)
    producto.activo = False
    producto.save(update_fields=["activo", "actualizado_en"])

    messages.warning(
        request,
        "El producto fue desactivado y su historial se conservó.",
    )
    return redirect("inventario:producto_lista")

from django.views.generic import ListView


class ProductoListView(ListView):
    model = Producto
    template_name = "inventario/productos/lista.html"
    context_object_name = "productos"
    paginate_by = 10

    def get_queryset(self):
        return (
            Producto.objects
            .select_related("categoria")
            .filter(activo=True)
            .order_by("nombre")
        )

from django.views.generic import DetailView


class ProductoDetailView(DetailView):
    model = Producto
    template_name = "inventario/productos/detalle.html"
    context_object_name = "producto"
    slug_field = "slug"
    slug_url_kwarg = "slug"

from django.contrib.auth.mixins import LoginRequiredMixin
from django.contrib.messages.views import SuccessMessageMixin
from django.views.generic import CreateView


class ProductoCreateView(
    LoginRequiredMixin,
    SuccessMessageMixin,
    CreateView,
):
    model = Producto
    form_class = ProductoForm
    template_name = "inventario/productos/formulario.html"
    success_message = "El producto se registró correctamente."

    def form_valid(self, form):
        form.instance.creado_por = self.request.user
        return super().form_valid(form)

# settings.py — configuración educativa temporal
LOGIN_URL = "/admin/login/"

from django.views.generic import UpdateView


class ProductoUpdateView(
    LoginRequiredMixin,
    SuccessMessageMixin,
    UpdateView,
):
    model = Producto
    form_class = ProductoForm
    template_name = "inventario/productos/formulario.html"
    slug_field = "slug"
    slug_url_kwarg = "slug"
    success_message = "El producto se actualizó correctamente."

from django.urls import reverse_lazy
from django.views.generic import DeleteView


class CategoriaDeleteView(LoginRequiredMixin, DeleteView):
    model = Categoria
    template_name = "inventario/categorias/confirmar_eliminacion.html"
    success_url = reverse_lazy("inventario:categoria_lista")

    def form_valid(self, form):
        messages.success(
            self.request,
            "La categoría se eliminó correctamente.",
        )
        return super().form_valid(form)

path(
    "clientes/<int:pk>/",
    ClienteDetailView.as_view(),
    name="cliente_detalle",
)

path(
    "productos/<slug:slug>/",
    ProductoDetailView.as_view(),
    name="producto_detalle",
)

slug = models.SlugField(max_length=180, unique=True)

/productos/teclado-ergonomico-tec-001/

1. agregar slug temporalmente opcional
2. crear migración de datos
3. generar un slug único por registro
4. comprobar duplicados
5. convertirlo en obligatorio y único

from django.urls import reverse


def get_absolute_url(self):
    return reverse(
        "inventario:producto_detalle",
        kwargs={"slug": self.slug},
    )

from django.urls import path

from . import views


app_name = "inventario"

urlpatterns = [
    path(
        "productos/",
        views.ProductoListView.as_view(),
        name="producto_lista",
    ),
    path(
        "productos/nuevo/",
        views.ProductoCreateView.as_view(),
        name="producto_crear",
    ),
    path(
        "productos/<slug:slug>/",
        views.ProductoDetailView.as_view(),
        name="producto_detalle",
    ),
    path(
        "productos/<slug:slug>/editar/",
        views.ProductoUpdateView.as_view(),
        name="producto_editar",
    ),
    path(
        "productos/<slug:slug>/desactivar/",
        views.producto_desactivar,
        name="producto_desactivar",
    ),
]

entidad_accion
producto_lista
producto_detalle
producto_crear
producto_editar
producto_desactivar

<form
    method="post"
    action="{% url 'inventario:producto_desactivar' producto.slug %}"
>
    {% csrf_token %}
    <p>
        Desactivarás <strong>{{ producto.nombre }}</strong>.
        El producto dejará de aparecer en los listados activos,
        pero su historial se conservará.
    </p>
    <button class="btn btn-warning" type="submit">
        Confirmar desactivación
    </button>
    <a
        class="btn btn-outline-secondary"
        href="{% url 'inventario:producto_detalle' producto.slug %}"
    >
        Cancelar
    </a>
</form>

from django.db.models import Q


termino = request.GET.get("q", "").strip()

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

if termino:
    productos = productos.filter(
        Q(codigo__icontains=termino)
        | Q(nombre__icontains=termino)
        | Q(descripcion__icontains=termino)
    )

<form method="get" role="search" class="row g-3">
    <div class="col-12 col-md-8">
        <label class="form-label" for="id_q">Buscar productos</label>
        <input
            class="form-control"
            id="id_q"
            name="q"
            type="search"
            value="{{ request.GET.q }}"
            placeholder="Código, nombre o descripción"
        >
    </div>
    <div class="col-12 col-md-4 align-self-end">
        <button class="btn btn-primary w-100" type="submit">
            Buscar
        </button>
    </div>
</form>

categoria = request.GET.get("categoria", "")
estado = request.GET.get("estado", "activos")

if categoria.isdigit():
    productos = productos.filter(categoria_id=int(categoria))

if estado == "activos":
    productos = productos.filter(activo=True)
elif estado == "inactivos":
    productos = productos.filter(activo=False)

<select class="form-select" name="estado">
    <option value="activos">Activos</option>
    <option value="inactivos">Inactivos</option>
    <option value="todos">Todos</option>
</select>

# Evitar
productos.order_by(request.GET.get("orden"))

ORDENES_PERMITIDOS = {
    "nombre": "nombre",
    "-nombre": "-nombre",
    "precio": "precio",
    "-precio": "-precio",
    "recientes": "-creado_en",
}

orden_solicitado = request.GET.get("orden", "nombre")
orden = ORDENES_PERMITIDOS.get(orden_solicitado, "nombre")
productos = productos.order_by(orden)

from django.core.paginator import Paginator


paginador = Paginator(productos, 10)
pagina = request.GET.get("page")
page_obj = paginador.get_page(pagina)

paginate_by = 10

{% if page_obj.paginator.num_pages > 1 %}
    <nav aria-label="Paginación de productos">
        <ul class="pagination justify-content-center">
            {% if page_obj.has_previous %}
                <li class="page-item">
                    <a
                        class="page-link"
                        href="?page={{ page_obj.previous_page_number }}&q={{ request.GET.q|urlencode }}&estado={{ request.GET.estado|urlencode }}"
                    >
                        Anterior
                    </a>
                </li>
            {% endif %}

            <li class="page-item active" aria-current="page">
                <span class="page-link">
                    Página {{ page_obj.number }} de {{ page_obj.paginator.num_pages }}
                </span>
            </li>

            {% if page_obj.has_next %}
                <li class="page-item">
                    <a
                        class="page-link"
                        href="?page={{ page_obj.next_page_number }}&q={{ request.GET.q|urlencode }}&estado={{ request.GET.estado|urlencode }}"
                    >
                        Siguiente
                    </a>
                </li>
            {% endif %}
        </ul>
    </nav>
{% endif %}

class ProductoListView(ListView):
    model = Producto
    template_name = "inventario/productos/lista.html"
    context_object_name = "productos"
    paginate_by = 10

    def get_queryset(self):
        queryset = Producto.objects.select_related("categoria")

        termino = self.request.GET.get("q", "").strip()
        categoria = self.request.GET.get("categoria", "")
        estado = self.request.GET.get("estado", "activos")
        orden_solicitado = self.request.GET.get("orden", "nombre")

        if termino:
            queryset = queryset.filter(
                Q(codigo__icontains=termino)
                | Q(nombre__icontains=termino)
            )

        if categoria.isdigit():
            queryset = queryset.filter(categoria_id=int(categoria))

        if estado == "activos":
            queryset = queryset.filter(activo=True)
        elif estado == "inactivos":
            queryset = queryset.filter(activo=False)

        ordenes = {
            "nombre": "nombre",
            "-nombre": "-nombre",
            "precio": "precio",
            "-precio": "-precio",
        }
        orden = ordenes.get(orden_solicitado, "nombre")
        return queryset.order_by(orden)

    def get_context_data(self, **kwargs):
        contexto = super().get_context_data(**kwargs)
        contexto["categorias"] = Categoria.objects.filter(
            activa=True
        ).order_by("nombre")
        return contexto

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

def clean_codigo(self):
    return self.cleaned_data["codigo"].strip().upper()

if not Producto.objects.filter(codigo=codigo).exists():
    Producto.objects.create(...)

CSS, JavaScript, logotipos del sitio

fotografía del cliente, imagen del producto, documento

imagen = models.ImageField(
    upload_to="productos/%Y/%m/",
    blank=True,
)

python -m pip install Pillow

# settings.py
MEDIA_URL = "media/"
MEDIA_ROOT = BASE_DIR / "media"

from django.conf import settings
from django.conf.urls.static import static


urlpatterns = [
    # ...
]

if settings.DEBUG:
    urlpatterns += static(
        settings.MEDIA_URL,
        document_root=settings.MEDIA_ROOT,
    )

<form method="post" enctype="multipart/form-data">
    {% csrf_token %}
    {{ form }}
    <button type="submit">Guardar</button>
</form>

formulario = ProductoForm(
    request.POST or None,
    request.FILES or None,
    instance=producto,
)

{% if producto.imagen %}
    <img
        src="{{ producto.imagen.url }}"
        alt="Imagen de {{ producto.nombre }}"
        width="480"
        height="320"
        class="img-fluid rounded"
    >
{% else %}
    <div class="bg-body-tertiary rounded p-4 text-center">
        Producto sin imagen
    </div>
{% endif %}

from django.core.exceptions import ValidationError


def validar_tamano_archivo(archivo):
    limite = 2 * 1024 * 1024

    if archivo.size > limite:
        raise ValidationError(
            "El archivo no puede superar 2 MB."
        )

from django.core.validators import FileExtensionValidator


imagen = models.ImageField(
    upload_to="productos/%Y/%m/",
    blank=True,
    validators=[
        validar_tamano_archivo,
        FileExtensionValidator(
            allowed_extensions=["jpg", "jpeg", "png", "webp"]
        ),
    ],
)

from django.db import transaction


def producto_editar(request, slug):
    producto = get_object_or_404(Producto, slug=slug)
    nombre_anterior = (
        producto.imagen.name if producto.imagen else ""
    )
    almacenamiento = producto.imagen.storage

    formulario = ProductoForm(
        request.POST or None,
        request.FILES or None,
        instance=producto,
    )

    if request.method == "POST" and formulario.is_valid():
        with transaction.atomic():
            producto_actualizado = formulario.save()
            nombre_nuevo = (
                producto_actualizado.imagen.name
                if producto_actualizado.imagen
                else ""
            )

            if nombre_anterior and nombre_anterior != nombre_nuevo:
                transaction.on_commit(
                    lambda: almacenamiento.delete(nombre_anterior)
                )

        messages.success(request, "El producto se actualizó.")
        return redirect(producto_actualizado)

    return render(
        request,
        "inventario/productos/formulario.html",
        {"form": formulario, "producto": producto},
    )

class DocumentoCliente(models.Model):
    cliente = models.ForeignKey(
        Cliente,
        on_delete=models.CASCADE,
        related_name="documentos",
    )
    nombre = models.CharField(max_length=100)
    archivo = models.FileField(
        upload_to="clientes/documentos/%Y/%m/",
        validators=[
            validar_tamano_archivo,
            FileExtensionValidator(
                allowed_extensions=["pdf", "jpg", "jpeg", "png"]
            ),
        ],
    )
    creado_en = models.DateTimeField(auto_now_add=True)

    def __str__(self):
        return self.nombre

from django.forms import inlineformset_factory


class DocumentoClienteForm(forms.ModelForm):
    class Meta:
        model = DocumentoCliente
        fields = ["nombre", "archivo"]


DocumentoClienteFormSet = inlineformset_factory(
    Cliente,
    DocumentoCliente,
    form=DocumentoClienteForm,
    extra=1,
    can_delete=True,
    max_num=5,
    validate_max=True,
)

from django.db import transaction


def cliente_editar(request, pk):
    cliente = get_object_or_404(Cliente, pk=pk)
    formulario = ClienteForm(
        request.POST or None,
        instance=cliente,
    )
    documentos = DocumentoClienteFormSet(
        request.POST or None,
        request.FILES or None,
        instance=cliente,
        prefix="documentos",
    )

    if (
        request.method == "POST"
        and formulario.is_valid()
        and documentos.is_valid()
    ):
        with transaction.atomic():
            formulario.save()
            documentos.save()

        messages.success(
            request,
            "El cliente y sus documentos se actualizaron.",
        )
        return redirect("clientes:detalle", pk=cliente.pk)

    return render(
        request,
        "clientes/formulario.html",
        {"form": formulario, "documentos": documentos},
    )

<form method="post" enctype="multipart/form-data">
    {% csrf_token %}
    {{ documentos.management_form }}

    {{ form.as_p }}

    {% for documento_form in documentos %}
        <fieldset class="border rounded p-3 mb-3">
            <legend class="h6">
                Documento {{ forloop.counter }}
            </legend>
            {{ documento_form.as_p }}
        </fieldset>
    {% endfor %}

    <button class="btn btn-primary" type="submit">
        Guardar
    </button>
</form>

templates/
└── inventario/
    ├── components/
    │   ├── campo_formulario.html
    │   ├── filtros_productos.html
    │   └── paginacion.html
    ├── productos/
    │   ├── lista.html
    │   ├── detalle.html
    │   ├── formulario.html
    │   └── confirmar_desactivacion.html
    └── categorias/
        ├── lista.html
        └── formulario.html

{% extends "base.html" %}

{% block title %}{{ titulo }} | Gestión empresarial{% endblock %}

{% block content %}
<div class="container py-5">
    <div class="row justify-content-center">
        <div class="col-12 col-lg-8">
            <h1>{{ titulo }}</h1>

            <form
                method="post"
                enctype="multipart/form-data"
                class="card card-body shadow-sm"
                novalidate
            >
                {% csrf_token %}
                {% include "components/formulario_campos.html" with form=form only %}

                <div class="d-flex flex-wrap gap-2">
                    <button class="btn btn-primary" type="submit">
                        Guardar
                    </button>
                    <a
                        class="btn btn-outline-secondary"
                        href="{{ url_cancelar }}"
                    >
                        Cancelar
                    </a>
                </div>
            </form>
        </div>
    </div>
</div>
{% endblock %}

Revisa este ModelForm de Django 5.2.
Primero enumera los campos del modelo que el usuario puede modificar
y los que deben permanecer internos.

Después revisa:
- campos expuestos;
- normalización;
- validaciones de campo;
- validaciones cruzadas;
- mensajes;
- archivos;
- duplicados;
- accesibilidad del template.

No agregues reglas empresariales inventadas. Formula preguntas.

Analiza este flujo de creación:
URL, vista, formulario, modelo y template.

Síntoma:
[describe el resultado exacto]

Indica el recorrido de la solicitud, propone una hipótesis por vez
y diseña una prueba mínima. No reescribas todos los archivos.

Genera una matriz de pruebas manuales para este formulario.
Incluye casos válidos, vacíos, límites, duplicados,
archivos incorrectos, reenvío y cancelación.
Para cada caso indica precondición, pasos y resultado esperado.
No afirmes que el sistema está probado hasta ejecutar los casos.

GET → mostrar
POST → enlazar → validar
                 ├── error → mostrar
                 └── éxito → guardar → mensaje → redirect