📚 Unidad ISS-02 · Apps client, product y sale — capa 🧠 APRENDER

🛠 Construir este bloque → · ✅ Condiciones de cierre (GATE) · 📝 Evaluación

Capa Página Para qué

🧠 Aprender esta página comprender, explicar y relacionar

🛠 Construir Apps client, product y sale ejecutar, programar y verificar

✅ GATE Cierre de la unidad condición para pasar al bloque siguiente

Mapa de correspondencias. Cada fila enlaza el mismo tema en las dos capas; los enlaces apuntan a secciones reales del material.

Tema	🧠 Aprender (esta página)	🛠 Construir (ISS técnico)
Objetivo	A. Objetivos y Requisitos de ISS-02	Objetivo
Recorrido	C. Comandos CLI Utilizados y Justificación Técnica	Construcción
Cierre	I. Criterios de Aceptación (AC)	Criterios de aceptación · GATE
Evaluación	K. Cuestionario de Preguntas de Defensa Oral Técnica	GATE

🖥 Presentación del ISS

Presentación de la unidad. Diapositivas de ISS-02 — Apps client, product y sale (15 diapositivas). Se visualiza aquí, dentro del sitio.

⛶ Ver presentación completa ⬇ Archivo editable (.pptx)

15 diapositivas · se visualiza dentro del sitio.

🎬 Video explicativo

Recorrido audiovisual de la unidad. El video recorre el ISS técnico de ISS-02 — Apps client, product y sale, bloque por bloque.

6:52 min · narración en español · subtítulos activables desde el reproductor.

Infografía

Infografía de la unidad

Mapa conceptual

Objetivo & Dominios
client: compradores
product: catálogo e inventario
sale: transacciones
CLI & Creación
mkdir -p (directorios previos)
python manage.py startapp apps/
Paquete Python
apps/init.py (convertir apps/ en paquete)
AppConfig & Propiedades
name = "apps.client" (import path completo)
label = "client" (mantiene identificador corto para migraciones)
ClientConfig, ProductConfig, SaleConfig
Registro Global
config/settings/init.py -> INSTALLED_APPS
Regla de Arquitectura
Sin modelos ni migraciones en ISS-02 (espera al Custom User de ISS-03)
Verificación & GATE
Command: python manage.py check
AC-02-01, AC-02-02, AC-02-03
EVI-02-01 (PASS)

Guía de Estudio Exhaustiva: ISS-02 — Apps client, product y sale

A. Objetivos y Requisitos de ISS-02

Objetivo Principal

Crear las tres aplicaciones de negocio centrales del proyecto (client, product y sale) utilizando la interfaz de línea de comandos (CLI) de Django y registrarlas adecuadamente dentro de la estructura del paquete modular apps/.

Requisitos Previos

ISS-01 Superado: El proyecto debe contar con la estructura de configuración modular config/settings/, la lectura de variables de entorno .env mediante python-dotenv, y el módulo de selección dinámica de motor de base de datos (config/database.py).
Terminal con Entorno Activo: La ejecución debe realizarse garantizando el entorno virtual activo (.venv).
Ausencia de Modelos de Datos: En este hito de desarrollo no se escriben modelos de base de datos. Se mantiene la norma arquitectónica de no definir modelos ni ejecutar migraciones antes de la implementación del Custom User (security.User) estipulada para el ISS-03.

B. Conceptos Esenciales y Vocabulario Técnico

startapp: Subcomando administrativo de Django CLI (python manage.py startapp) diseñado para generar automáticamente la estructura estándar de directorios y archivos base que conforman una aplicación Django.
AppConfig: Clase de configuración definida dentro de apps.py en cada aplicación. Funciona como la representación que utiliza Django para almacenar metadatos e inspeccionar las propiedades de una app instalada.
name vs label:
name: Propiedad de AppConfig que define la ruta completa de importación de Python hacia el paquete de la aplicación (por ejemplo, "apps.client"). Es obligatoria cuando la aplicación vive dentro de un subdirectorio y no en la raíz del proyecto.
label: Identificador único corto asignado a la aplicación dentro del registro de Django (por ejemplo, "client"). Evita que las migraciones, nombres predeterminados de tablas e identificación interna adopten el nombre del paquete contenedor (apps_client), manteniendo el nombre del dominio limpio e independiente de la estructura de carpetas.
INSTALLED_APPS: Lista de configuración ubicada en config/settings/__init__.py donde se declaran formalmente todas las aplicaciones activas (tanto del núcleo de Django como propias del negocio) que forman parte del proyecto.
Paquete Modular apps/: Directorio contenedor en la raíz del repositorio que agrupa las aplicaciones de dominio (client, product, sale, y posteriormente security) para evitar la dispersión de carpetas en la raíz del proyecto.
apps/__init__.py: Archivo necesario para que el intérprete de Python reconozca la carpeta apps/ como un paquete modular (package) que puede ser importado.

C. Comandos CLI Utilizados y Justificación Técnica

Secuencia de Comandos

mkdir -p apps/client apps/product apps/sale
python manage.py startapp client apps/client
python manage.py startapp product apps/product
python manage.py startapp sale apps/sale

mkdir -p apps
cat > apps/__init__.py <<'EOF'
EOF

Explicación de la Exigencia de Directorio Destino en `startapp`

Cuando se invoca el comando python manage.py startapp <nombre_app> [destino], Django toma la plantilla por defecto de una aplicación y la despliega en la ruta indicada en [destino].

A diferencia de otros generadores que crean la carpeta de destino si esta no existe, el comando startapp de Django requiere explícitamente que el directorio destino ya haya sido creado en el sistema de archivos. Si el directorio no existe al momento de ejecutar el comando, la CLI falla con un error de ruta. Por esta razón técnica, es estrictamente necesario ejecutar mkdir -p apps/client apps/product apps/sale antes de llamar a startapp.

Nota: startapp genera automáticamente los archivos models.py, admin.py, views.py, apps.py y tests.py. No crea el archivo urls.py; este aparecerá únicamente en unidades posteriores cuando la aplicación publique sus propios endpoints.

D. Árbol de Archivos ANTES y DESPUÉS de Ejecutar ISS-02

Árbol de Archivos ANTES (Estado Final de ISS-01)

.
├── .env
├── .env.example
├── .gitignore
├── manage.py
├── requirements.txt
└── config/
    ├── __init__.py
    ├── asgi.py
    ├── database.py
    ├── project_python.py
    ├── urls.py
    ├── wsgi.py
    └── settings/
        └── __init__.py

Árbol de Archivos DESPUÉS (Estado Final de ISS-02)

.
├── .env
├── .env.example
├── .gitignore
├── manage.py
├── requirements.txt
├── apps/
│   ├── __init__.py
│   ├── client/
│   │   ├── __init__.py
│   │   ├── admin.py
│   │   ├── apps.py
│   │   ├── models.py
│   │   ├── tests.py
│   │   └── views.py
│   ├── product/
│   │   ├── __init__.py
│   │   ├── admin.py
│   │   ├── apps.py
│   │   ├── models.py
│   │   ├── tests.py
│   │   └── views.py
│   └── sale/
│       ├── __init__.py
│       ├── admin.py
│       ├── apps.py
│       ├── models.py
│       ├── tests.py
│       └── views.py
└── config/
    ├── __init__.py
    ├── asgi.py
    ├── database.py
    ├── project_python.py
    ├── urls.py
    ├── wsgi.py
    └── settings/
        └── __init__.py

Responsabilidad de las Ramas Creadas

apps/client/: Dominio encargado de la gestión de compradores.
apps/product/: Dominio encargado del catálogo de productos e inventario.
apps/sale/: Dominio encargado de las transacciones y operaciones de venta.

E. Archivos Modificados y Parches Aplicados Paso a Paso

1. Parche en `apps/client/apps.py`

Ubicación: Dentro de la clase ClientConfig.

ARCHIVO: apps/client/apps.py

UBICAR:
    name = "client"

REEMPLAZAR POR:
    name = "apps.client"
    label = "client"

2. Parche en `apps/product/apps.py`

Ubicación: Dentro de la clase ProductConfig.

ARCHIVO: apps/product/apps.py

UBICAR:
    name = "product"

REEMPLAZAR POR:
    name = "apps.product"
    label = "product"

3. Parche en `apps/sale/apps.py`

Ubicación: Dentro de la clase SaleConfig.

ARCHIVO: apps/sale/apps.py

UBICAR:
    name = "sale"

REEMPLAZAR POR:
    name = "apps.sale"
    label = "sale"

4. Parche en `config/settings/init.py`

Ubicación: Al final de la lista INSTALLED_APPS.

ARCHIVO: config/settings/__init__.py

DEBAJO DE:
    "django.contrib.staticfiles",

AGREGAR:
    "apps.client.apps.ClientConfig",
    "apps.product.apps.ProductConfig",
    "apps.sale.apps.SaleConfig",

F. Explicación de las Propiedades de AppConfig

Django asume por defecto que las aplicaciones habitan en la raíz del proyecto. Al organizarlas dentro de la carpeta contenedora apps/, se deben ajustar las propiedades de la clase AppConfig:

name = "apps.client": Define la ruta de importación completa en notación de puntos de Python. Permite que el cargador de módulos de Django localice correctamente el código de la aplicación al ejecutar import apps.client.
label = "client": Mantiene la etiqueta de la aplicación de manera aislada y corta. Sin el ajuste explícito del label, Django tomaría la etiqueta por defecto como apps_client. Mantener label = "client" asegura que:
Las migraciones de base de datos se almacenen e identifiquen bajo el nombre del dominio (client, product, sale).
Las relaciones entre modelos e identificadores internos del sistema no arrastren el prefijo del paquete modular (apps_).

G. Reglas de Diseño y Estado de Desarrollo

¿Por qué AÚN NO se crean modelos de negocio en ISS-02?

En este hito de desarrollo, los archivos models.py creados por la CLI permanecen vacíos (o solo con el comentario por defecto generado por Django).

Fundamento de arquitectura: 1. El modelo de usuario personalizado (security.User) debe ser definido en el ISS-03 e indicado en el archivo de configuración mediante la directiva AUTH_USER_MODEL = "security.User" antes de ejecutar la primera migración del proyecto (makemigrations / migrate). 2. Si en el ISS-02 se definieran modelos de negocio y se ejecutara una migración, Django instalaría las tablas predeterminadas de autenticación de Django (auth_user). 3. Intentar cambiar AUTH_USER_MODEL después de haber ejecutado la migración inicial obliga a reconstruir o eliminar la base de datos por completo, rompiendo el flujo de desarrollo del laboratorio.

H. Errores Frecuentes y Cómo Evitarlos

Olvidar la creación de apps/__init__.py:
Síntoma: Error de importación ModuleNotFoundError: No module named 'apps'.
Causa: Python no reconoce la carpeta apps/ como paquete modular si carece del archivo __init__.py.
Solución: Crear el archivo explícitamente mediante cat > apps/__init__.py <<'EOF'.
Omitir la propiedad label en apps.py:
Síntoma: Django asigna nombres de aplicaciones etiquetados como apps_client, afectando la generación interna de migraciones y nombres de tablas.
Solución: Declarar siempre label = "client" (y correspondiente para product y sale) dentro de cada AppConfig.
Crear modelos o migrar antes de tiempo:
Síntoma: Conflicto irreversible con las tablas del módulo django.contrib.auth.
Solución: Mantenimiento estricto del principio de cero modelos hasta superar el ISS-03.
No crear el directorio destino antes de ejecutar startapp:
Síntoma: La CLI responde con error indicando que la ruta no existe al ejecutar python manage.py startapp client apps/client.
Solución: Crear siempre los subdirectorios previos usando mkdir -p.

I. Criterios de Aceptación (AC)

AC-02-01: Las tres aplicaciones (client, product y sale) fueron creadas utilizando el comando CLI startapp.
AC-02-02: El comando de verificación python manage.py check se ejecuta limpiamente y no reporta errores ni aplicaciones mal registradas.
AC-02-03: En este capítulo del proyecto no existe ningún modelo de negocio definido dentro de las aplicaciones.

J. Verificación, Evidencias y Tabla GATE

Comando de Verificación

Para validar que el registro de las aplicaciones y la estructura modular están correctamente configurados, se ejecuta en la terminal con el entorno virtual activo:

python manage.py check

Evidencia Asociada

EVI-02-01: Impresión en consola confirmando: System check identified no issues (0 silenced).

Tabla GATE

Criterio de Aceptación (AC)	Verificación	Evidencia	Resultado
AC-02-01	Inspección de la estructura de directorios de las apps (`apps/client`, `apps/product`, `apps/sale`).	Árbol del repositorio	PASS
AC-02-02	Verificación de configuración con el sistema de chequeo de Django.	EVI-02-01 (`python manage.py check`)	PASS
AC-02-03	Confirmación de ausencia de modelos de negocio en los archivos `models.py`.	Revisión del código en el ISS	PASS

K. Cuestionario de Preguntas de Defensa Oral Técnica

¿Por qué es necesario especificar name = "apps.client" dentro de ClientConfig en lugar de simplemente name = "client"?
Respuesta: Porque la aplicación client no reside en la raíz del proyecto, sino dentro de la carpeta contenedora apps/. La propiedad name requiere la ruta completa de importación en notación de puntos de Python para que el cargador de módulos de Django pueda localizar el paquete.
¿Cuál es la función técnica de definir de manera explícita label = "client" al modificar apps.py?
Respuesta: Al establecer name = "apps.client", Django por defecto le asignaría a la app la etiqueta apps_client. La propiedad label fuerza a que la identificación interna de la app se mantenga como client, garantizando que el nombre de las migraciones y metadatos no queden acoplados a la ruta del paquete modular.
¿Por qué el comando python manage.py startapp client apps/client exige que el directorio destino ya exista previamente?
Respuesta: Porque el comando startapp de Django está diseñado para volcar los archivos de su plantilla estándar dentro de una ruta ya existente provista en el argumento opcional de destino. Si la carpeta especificada no existe, la CLI no la crea automáticamente y aborta la ejecución con un error del sistema de archivos.
¿Qué consecuencia técnica genera omitir la creación del archivo apps/__init__.py en la estructura del proyecto?
Respuesta: Omitir apps/__init__.py provoca que el intérprete de Python no reconozca el directorio apps/ como un paquete modular. Esto resulta en errores ModuleNotFoundError al momento de importar cualquier componente declarado en INSTALLED_APPS mediante rutas como "apps.client.apps.ClientConfig".
¿Por qué está expresamente prohibido crear modelos e invocar makemigrations durante el ISS-02?
Respuesta: Porque cualquier ejecución previa de migraciones instalaría el esquema predeterminado de usuarios de Django (auth_user). El modelo de usuario personalizado (security.User) debe registrarse en el ISS-03 mediante AUTH_USER_MODEL antes de la primera migración; cambiar dicho modelo con una base de datos ya migrada genera un estado inconsistente que obliga a recrear la base de datos desde cero.
Al ejecutar startapp, ¿qué archivo de enrutamiento genera Django dentro de la estructura de la aplicación?
Respuesta: Ninguno. El comando startapp genera únicamente admin.py, apps.py, models.py, tests.py y views.py. El archivo urls.py de la aplicación no es generado automáticamente por la CLI y se escribe posteriormente a mano cuando la aplicación expone endpoints HTTP.

Navegación de la ruta: ← ISS-01 · 🛠 Construir · ↑ Ruta Django · → ISS-02 · 🛠 Construir

Capa	Página	Para qué
🧠 Aprender	esta página	comprender, explicar y relacionar
🛠 Construir	Apps client, product y sale	ejecutar, programar y verificar
✅ GATE	Cierre de la unidad	condición para pasar al bloque siguiente