Arquitectura y estructura de carpetas - MiguelAngelMarinMejia1/ArquitecturaDeSoftware-Proyecto GitHub Wiki

Visión general

Hotel MDJ está organizado en capas concéntricas: el núcleo de negocio no conoce a quien lo consume. Sobre ese núcleo se apoyan dos capas de presentación independientes —el sitio web renderizado en servidor y la API REST en JSON— que comparten exactamente la misma lógica.

                 ┌──────────────────────────────────────────────┐
                 │            PRESENTACIÓN                      │
                 │  ┌────────────────┐    ┌──────────────────┐   │
                 │  │  app  web      │    │ reservation.api  │   │
                 │  │  HTML + Django │    │  DRF / JSON      │   │
                 │  └────────┬───────┘    └────────┬─────────┘   │
                 └───────────┼─────────────────────┼─────────────┘
                             │                     │
                             └──────────┬──────────┘
                                        ▼
                 ┌──────────────────────────────────────────────┐
                 │            APLICACIÓN                        │
                 │   services.py        selectors.py            │
                 │   (comandos)         (consultas)             │
                 └──────────────────────┬───────────────────────┘
                                        ▼
                 ┌──────────────────────────────────────────────┐
                 │            DOMINIO                           │
                 │   builders.py  policies.py  codes.py         │
                 │   exceptions.py                              │
                 └──────────────────────┬───────────────────────┘
                                        ▼
                 ┌──────────────────────────────────────────────┐
                 │   PERSISTENCIA          INFRAESTRUCTURA      │
                 │   models.py             infra/factories.py   │
                 │                         infra/notifications  │
                 │                         infra/payments.py    │
                 └──────────────────────────────────────────────┘

La regla que sostiene el diseño: las dependencias apuntan siempre hacia adentro. web/ importa de reservation, pero reservation jamás importa de web. Y dentro de reservation, solo el subpaquete api/ conoce Django Rest Framework.

Estructura

hotelMDJProject/
├── manage.py
├── requirements.txt
├── hotelMDJ/                     # configuración del proyecto
│   ├── settings.py
│   └── urls.py                   # '' → web  |  'api/v1/' → reservation.api
│
├── reservation/                  # NÚCLEO DE NEGOCIO
│   ├── models.py                 # entidades de persistencia
│   ├── services.py               # orquestación de casos de uso
│   ├── selectors.py              # consultas de lectura
│   ├── admin.py
│   ├── domain/
│   │   ├── builders.py           # ReservationBuilder
│   │   ├── policies.py           # PricingPolicy, TaxPolicy, CapacityPolicy
│   │   ├── codes.py              # ConfirmationCodeGenerator
│   │   └── exceptions.py         # errores de dominio
│   ├── infra/
│   │   ├── notifications.py      # BaseNotifier + implementaciones
│   │   ├── payments.py           # BaseGateway + implementación simulada
│   │   └── factories.py          # NotifierFactory, PaymentGatewayFactory
│   ├── api/
│   │   ├── serializers.py
│   │   ├── views.py              # APIView
│   │   ├── urls.py
│   │   └── exception_handler.py  # dominio → HTTP
│   ├── fixtures/seed.json
│   └── migrations/
│
└── web/                          # PRESENTACIÓN HTML
    ├── views.py
    ├── urls.py
    ├── templates/web/
    └── static/web/

Justificación de cada decisión

Por qué dos apps y no una

La alternativa evidente era meter todo en reservation/. Se separó web/ por una razón concreta: hace imposible, por construcción, que la lógica de negocio se filtre a la capa HTML. Si las plantillas y las vistas de página vivieran junto a los servicios, nada impediría que un día alguien calculara un precio dentro de una vista. Con dos apps, esa dependencia sería un import cruzado visible en revisión de código.

El beneficio secundario es que el núcleo queda listo para extraerse: si mañana el sitio web pasa a ser una SPA, se borra web/ y reservation/ sigue funcionando sin tocar una línea.

Por qué `domain/` separado de `models.py`

El enunciado prohíbe lógica de negocio en métodos de los modelos. Pero el problema no es solo normativo: los modelos de Django están atados al ORM, y una regla de negocio escrita dentro de un modelo solo se puede probar levantando una base de datos.

En domain/ las reglas son clases planas de Python. PricingPolicy.quote() se prueba con objetos en memoria, sin migraciones y sin base de datos.

Por qué `services.py` y `selectors.py` separados

Los comandos (que cambian estado) y las consultas (que solo leen) tienen necesidades distintas: los primeros necesitan transacciones, validaciones e invariantes; las segundas necesitan select_related y filtros eficientes. Mezclarlos produce clases que crecen sin control.

selectors.py concentra además toda la lógica de solapamiento de fechas, que es la consulta más delicada del sistema y merece un único lugar donde razonarla.

Por qué `infra/` aislado

notifications.py y payments.py son adaptadores a mundos externos (SMTP, una pasarela de pago). Son la parte del sistema con más probabilidad de cambiar por razones ajenas al negocio. Aislarlos detrás de las abstracciones BaseNotifier y BaseGateway significa que cambiar de proveedor de correo no toca ni un archivo de domain/ ni de services.py.

Por qué `api/` es un subpaquete y no un app

La API no es un contexto de negocio distinto: es otra forma de exponer el mismo. Ponerla como subpaquete deja explícito que depende de reservation, y concentra en un solo directorio todo lo que sabe de HTTP y de DRF.

Mapeo entre el diagrama de clases y el código

El diagrama UML declara operaciones dentro de las entidades. Al implementarlas se reubicaron en la capa que les corresponde, manteniendo la semántica:

Operación del diagrama	Implementación
`Reserva.calcularTotal()`	`domain/policies.py` → `PricingPolicy.quote()`
`Reserva.confirmar()` / `cancelar()`	`services.py` → `ReservationService`
`Reserva.modificarFechas()`	Entrega 2
`Habitacion.verificarDisponibilidad()`	`selectors.py` → `available_rooms()`, `is_room_available()`
`Habitacion.cambiarEstado()`	`models.Room.Status` + admin
`TipoHabitacion.calcularPrecioTemporada()`	`domain/policies.py` → `SeasonalPricingPolicy`
`Cliente.registrarse()`	`services.py` → `CustomerService.get_or_create_profile()`
`Cliente.consultarHistorialReservas()`	`reservation.customer.reservations` (related name)
`Pago.procesarPago()`	`services.py` → `PaymentService.charge()`
`Factura.generarFactura()`	`services.py` → `InvoiceService.issue()`

Modelo de datos implementado

Se implementaron las seis clases del diagrama más una tabla intermedia:

Clase	Estado
`Customer`	Completa, con flujo de negocio y API
`RoomType`	Completa, con flujo de negocio y API
`Room`	Completa, con flujo de negocio y API
`Reservation`	Completa, con flujo de negocio y API
`ReservationRoom`	Tabla intermedia que materializa el `1..*` del diagrama
`Payment`	Persistencia + `PaymentService` con pasarela simulada
`Invoice`	Persistencia + `InvoiceService`

ReservationRoom no aparece en el diagrama porque UML expresa la asociación 1..* directamente entre Reserva y Habitacion. En un modelo relacional esa asociación necesita una tabla propia, y además da un lugar natural donde congelar el precio por noche en el momento de reservar: si la tarifa cambia después, lo que el huésped aceptó pagar no cambia con ella.