CAPÍTULO 1 · Un equipo, una base común
Aprender a reconocer una casa antes de entrar
Ahora que el código se comparte, sus nombres dejan de ser una preferencia individual. Quien llega a SensorHub necesita encontrar la configuración sin preguntar cómo decidimos llamarla esta vez. Si cada proyecto utiliza una estructura diferente para lo mismo, el equipo vuelve a aprender el recorrido antes de poder resolver un problema.
Por eso adoptamos config como nombre del paquete creado con startproject. Allí reconocemos la composición general de Django. Las aplicaciones del negocio llevan la convención _App seguida de su nombre, que ayuda a distinguirlas visualmente. El prefijo busca agruparlas en el explorador, aunque su orden depende de la herramienta; el verdadero acuerdo consiste en que todos sepamos qué representa cada carpeta.
Crear una app tampoco la conecta automáticamente con todo el sistema. La registramos en INSTALLED_APPS y enlazamos sus URLs desde la configuración principal. Ya podemos ubicar módulos y seguir sus entradas. Al revisar ese centro llamado config, encontramos un archivo que empieza a reunir decisiones de dos realidades distintas: el computador donde desarrollamos y el servidor donde publicaremos.
Leer esta parte dentro del relato completo →DEL RELATO A LA PRÁCTICA
Vamos a desarrollar esta decisión con su mapa, explicación, código y ejercicio.
MIRA · CONECTA · COMPRENDE
Módulos con conexiones claras
Las flechas muestran responsabilidades relacionadas; no representan un orden obligatorio de ejecución.
Selecciona una pieza para destacar su responsabilidad.
Leer la explicación del mapa
- Apps. Delimita responsabilidades
- Modelos. Gestionan persistencia
- Servicios. Coordinan casos de uso
- Vistas. Adaptan HTTP al dominio
01 / EL PROBLEMA
¿Para qué sirve?
Una app por pantalla suele duplicar modelos y servicios. Una app por responsabilidad mantiene juntas las piezas que evolucionan por la misma razón.
02 / COMPRENDER
El concepto, explicado
catalogo define las estaciones y sensores; telemetria los referencia. No debería ocurrir que catalogo necesite importar vistas de telemetria para guardar un sensor.
Una carpeta views puede convertirse en paquete con queries, commands y templates. El archivo urls.py compone las clases públicas. No mantengas a la vez views.py y una carpeta views ambigua.
startapp genera una app, no una API ni una URL publicada. Registra catalogo.apps.CatalogoConfig en INSTALLED_APPS de base.py si ambos entornos usan esa app. El registro habilita su configuración, modelos y recursos; las rutas se conectan aparte mediante include en config/urls.py.
INSTALLED_APPS, MIDDLEWARE y TEMPLATES son tres registros distintos: componentes del proyecto, procesamiento de peticiones y motor de presentación. No agregues una vista a INSTALLED_APPS.
En la convención del equipo, config es el nombre del paquete creado con django-admin startproject config .; no es un comando llamado starter project. _AppCatalogo y _AppTelemetria identifican módulos del negocio. El guion bajo busca agruparlos visualmente antes de config, aunque el orden depende del explorador. Es una convención del equipo, no un requisito de Django.
Los ejemplos anteriores usan catalogo, telemetria y cuentas como nombres cortos. Corresponden a _AppCatalogo, _AppTelemetria y _AppAuth en esta convención. Si eliges los prefijos, cambia de forma consistente imports, AppConfig.name, rutas de templates y referencias; no renombres una app con migraciones existentes sin planificar su identidad.
03 / CONSTRUIR
Implementación paso a paso
- Registra las apps en INSTALLED_APPS.
- Agrupa casos de uso por app.
- Usa imports absolutos en límites compartidos.
- Importa vistas desde urls.py y evita ciclos.
04 / APLICAR
Ejemplo en SensorHub
# PowerShell: desde la carpeta del proyecto, con el venv activo
# Al iniciar un proyecto NUEVO:
django-admin startproject config .
python manage.py startapp _AppCatalogo
python manage.py startapp _AppTelemetria
# config/settings/base.py, después de separar settings:
# INSTALLED_APPS += ["_AppCatalogo.apps.AppcatalogoConfig",
# "_AppTelemetria.apps.ApptelemetriaConfig"]
# Comprueba el nombre exacto generado en cada apps.py.
# config/urls.py
from django.urls import include, path
urlpatterns = [path("catalogo/", include("_AppCatalogo.urls"))]
# _AppCatalogo/urls.py, tras crear el paquete views:
from django.urls import path
from .views.queries import ListSensorsQuery
from .views.commands import CreateSensorCommand
urlpatterns = [
path("sensores/", ListSensorsQuery.as_view(), name="sensor-list"),
path("sensores/crear/", CreateSensorCommand.as_view(), name="sensor-create"),
]
# Esquema de composición: las clases se implementan en la lección CQS.Cómo leer el ejemplo
- Las capas son responsabilidades, no una obligación de multiplicar archivos.
- Los servicios no necesitan importar las vistas que los llaman.
- Un paquete necesita __init__.py para mantener una estructura convencional y clara.
Error habitual
Los imports circulares suelen indicar que dos responsabilidades se mezclaron. Mover el import dentro de una función puede ocultar el problema, sin resolver el diseño.
05 / PRACTICAR
Tu turno
Decide dónde debe vivir una conversión Celsius→Fahrenheit usada por dos apps.
Ver solución orientativa
En UTIL_LIB/conversiones.py: recibe un número y no depende de modelos ni de request.
06 / VERIFICAR
Cómo sabes que funciona
- Las apps arrancan sin ciclos de importación.
- Puedes localizar un caso de uso por su nombre.
CONTINUAR LA EXPERIENCIA
El siguiente paso del recorrido:
Settings: base.py, development.py y production.py →Continuar en modo relato