Saltar a contenido

LP2 - Producto de Unidad 1

Proyecto: Semestre Saludable UPeU Autor: Montalvo Machaca, Maykol Gabriel Curso: Lenguaje de Programación II — UPeU sede Juliaca — Sección g2 — Semestre 2026-2 Repositorio: MGMM7STA/bomerp-backend

Producto

Backend REST modular ensamblado como una sola aplicación Spring Boot, conectado a Oracle 23ai, con persistencia ORM, CRUD, una operación cabecera–detalle transaccional, consultas con filtros y agregaciones, CORS por propiedad, logs correlacionados y pruebas automáticas.

El dominio es Semestre Saludable UPeU: una campaña institucional en la que el estudiante registra evidencias diarias de hábitos saludables (alimentación, descanso, actividad física, hidratación) y acumula puntaje. El backend se organiza como monolito modular con dos módulos propios:

Módulo Tipo Contenido en U1
campanias No transaccional Catálogo maestro: categorías de hábito, hábitos y campañas con su cupo diario.
participacion Transaccional Registro de participación con sus evidencias (cabecera–detalle), consumo de cupo y consultas.

Los módulos catalogo y ventas son el ejemplo guiado que el docente desarrolló en las sesiones S1–S4; permanecen en el repositorio como referencia de aprendizaje y no forman parte del dominio de Semestre Saludable. La sustentación se realiza sobre campanias y participacion.

La autenticación JWT y la entidad Estudiante no forman parte de U1: el módulo seguridad se implementa en S10, tal como establece el brief del proyecto y la decisión registrada en ADR-004. Por eso estudianteId viaja como identificador simple, sin tabla ni clave foránea propia en este corte.

1. Alcance arquitectónico del corte

bomerp-backend/                  # un solo proyecto Maven, sin reactor multi-modulo
└── src/main/java/pe/edu/upeu/bomerp/
    ├── BomerpBackendApplication.java   # unico Spring Boot ejecutable
    ├── CorsConfig.java                 # CORS por propiedad externa
    ├── OpenApiConfig.java              # documentacion de API
    ├── filter/                         # CorrelationIdFilter (X-Trace-ID)
    ├── exception/                      # manejo global de errores
    ├── campanias/                      # MODULO PROPIO - no transaccional
    │   ├── categoriahabito/            # agregado raiz: CategoriaHabito
    │   ├── habito/                     # agregado raiz: Habito
    │   └── campania/                   # agregado raiz: Campania + CupoDiario
    ├── participacion/                  # MODULO PROPIO - transaccional
    │   └── registro/                   # agregado raiz: RegistroParticipacion + DetalleEvidencia
    ├── catalogo/                       # ejemplo guiado del docente (S1-S3)
    ├── ventas/                         # ejemplo guiado del docente (S4-S5)
    └── seguridad/                      # se implementa en S10 (aun no existe como paquete)

Cada paquete directo bajo pe.edu.upeu.bomerp es un módulo de aplicación de Spring Modulith, no un artefacto Maven separado. Dentro de cada módulo, cada subpaquete es un agregado con identidad y ciclo de vida propios, y dentro de cada agregado están las capas (entity, dto, mapper, repository, service, controller).

DetalleEvidencia no tiene paquete propio: vive dentro de registro porque no tiene ciclo de vida independiente — no se crea, consulta ni elimina sin su registro padre.

Los límites no dependen de la disciplina del programador: están declarados con @NamedInterface sobre los paquetes dto y service, y verificados automáticamente por ModularityTests. Un módulo que intente usar el repository o la entity de otro rompe la compilación de las pruebas.

2. Demo ejecutable

Recurso URL local
Documentación interactiva de la API http://localhost:8080/swagger-ui.html
Contrato OpenAPI en JSON http://localhost:8080/v3/api-docs
Verificación de estado http://localhost:8080/actuator/health
Página de prueba de CORS origen-prueba/index.html (abierta con file://)

3. Contrato REST

Tabla 1. Contrato REST implementado

Método Endpoint Propósito Sesión
GET /api/v1/categorias-habito Listar las categorías de hábito. S2
GET /api/v1/categorias-habito/{id} Consultar una categoría. S2
POST /api/v1/categorias-habito Registrar una categoría. S2
PUT /api/v1/categorias-habito/{id} Actualizar una categoría. S2
DELETE /api/v1/categorias-habito/{id} Eliminar una categoría sin hábitos asociados. S2
GET /api/v1/habitos Listar hábitos con su categoría anidada. S3
GET /api/v1/habitos?categoriaId={id} Filtrar hábitos por categoría. S3
GET /api/v1/habitos/{id} Consultar un hábito con su categoría. S3
POST /api/v1/habitos Registrar un hábito validando que la categoría exista. S3
PUT /api/v1/habitos/{id} Actualizar un hábito y reasignar su categoría. S3
DELETE /api/v1/habitos/{id} Eliminar un hábito. S3
GET /api/v1/campanias Listar campañas. S2
GET /api/v1/campanias/activa Devolver la campaña vigente con su cupo diario. S2
POST /api/v1/campanias Registrar una campaña validando fechas y unicidad de campaña activa. S2
PUT /api/v1/campanias/{id} Actualizar una campaña. S2
DELETE /api/v1/campanias/{id} Eliminar una campaña sin participación registrada. S2
POST /api/v1/participacion/registros Registrar la participación diaria con sus evidencias, de forma atómica. S4
GET /api/v1/participacion/registros Consultar registros con cuatro filtros combinables y ordenamiento. S5
GET /api/v1/participacion/registros/resumen Devolver el reporte agregado con proyección resumida. S5
GET /api/v1/participacion/registros/{id} Consultar un registro con todas sus evidencias. S4

Códigos de estado y su significado de negocio

Tabla 2. Respuestas de error implementadas

Código Excepción Cuándo ocurre
400 Bad Request MethodArgumentNotValidException El cuerpo enviado viola una validación de formato (@NotBlank, @Positive, @Pattern).
400 Bad Request IllegalArgumentException Se pide ordenar por un campo fuera de la lista blanca, o la fecha fin no es posterior a la de inicio.
404 Not Found ResourceNotFoundException Se referencia un recurso inexistente (categoría, hábito, campaña o registro).
409 Conflict ReferenciaEnUsoException Se intenta borrar una categoría con hábitos, una campaña con participación, o activar una segunda campaña.
409 Conflict CupoDiarioExcedidoException El estudiante supera el máximo de evidencias diarias que permite la campaña.

La distinción es deliberada: 400 significa "lo que enviaste está mal escrito"; 409 significa "lo que enviaste está bien escrito, pero el estado actual del negocio no lo permite". Cada respuesta de error viaja con el mismo cuerpo (error, message, timestamp, status) y con la cabecera X-Trace-ID que la enlaza con la línea exacta del log.

4. DTO principales

Cada recurso tiene un DTO de entrada distinto del de salida. No se reutiliza uno solo porque lo que el cliente puede enviar y lo que el servidor debe devolver no coinciden: el cliente nunca envía id, fecha, estado, puntajeTotal ni subtotal — todos esos los calcula el servidor. Reutilizar un DTO abriría la puerta a que un cliente se auto-asigne el puntaje.

Entrada de la operación cabecera–detalle — POST /api/v1/participacion/registros

{
  "estudianteId": 1,
  "detalles": [
    { "habitoId": 1, "veces": 2, "descripcion": "Caminata al campus", "urlImagen": "https://ejemplo/img1.jpg" },
    { "habitoId": 2, "veces": 1, "descripcion": "Ensalada de frutas", "urlImagen": "https://ejemplo/img2.jpg" }
  ]
}

Salida de la operación cabecera–detalle — 201 Created

{
  "id": 10,
  "estudianteId": 1,
  "campaniaId": 1,
  "fecha": "2026-09-13T21:40:12",
  "estado": "ENVIADO",
  "totalEvidencias": 3,
  "puntajeTotal": 3.00,
  "detalles": [
    { "habitoId": 1, "nombreHabito": "Caminata de 30 minutos", "descripcion": "Caminata al campus", "urlImagen": "https://ejemplo/img1.jpg", "puntajeUnitario": 1.00, "veces": 2, "subtotal": 2.00 },
    { "habitoId": 2, "nombreHabito": "Consumo de frutas", "descripcion": "Ensalada de frutas", "urlImagen": "https://ejemplo/img2.jpg", "puntajeUnitario": 1.00, "veces": 1, "subtotal": 1.00 }
  ]
}

nombreHabito y puntajeUnitario se copian dentro del detalle en el momento del registro. No se leen del hábito al consultar. Si mañana el hábito cambia de nombre o de puntaje, los registros ya emitidos conservan el valor que tenían el día que ocurrieron. Es el mismo principio por el que una boleta guarda el precio del día de la venta.

Objeto relacionado — GET /api/v1/habitos

[
  {
    "id": 1,
    "nombre": "Caminata de 30 minutos",
    "descripcion": "Caminata continua de al menos 30 minutos",
    "puntajeBase": 1,
    "activo": 1,
    "categoria": { "id": 3, "nombre": "Actividad fisica" }
  }
]

La categoría viaja como CategoriaHabitoResumen — solo id y nombre — y no como la entidad completa. Eso corta la navegación en un nivel: el hábito muestra su categoría, pero la categoría no devuelve la lista de sus hábitos. Sin ese corte, serializar cualquiera de los dos entraría en un ciclo infinito.

Reporte agregado — GET /api/v1/participacion/registros/resumen

{
  "agregado": {
    "totalRegistros": 9,
    "evidenciasTotales": 22,
    "puntajeTotal": 27.00,
    "puntajePromedio": 3.00
  },
  "registros": [
    { "id": 9, "estudianteId": 3, "fecha": "2026-09-12T08:30:00", "estado": "APROBADO", "totalEvidencias": 3, "puntajeTotal": 4.00, "cantidadDetalles": 2 }
  ]
}

puntajePromedio se calcula en Java, no en la consulta. JPQL devuelve siempre Double para AVG, y un promedio de puntajes debe ser exacto: se calcula con BigDecimal y RoundingMode.HALF_UP.

5. Arquitectura backend U1

Figura 1. Módulos, esquemas y dependencias

flowchart LR
    APP[BomerpBackendApplication<br/>unico ejecutable]

    subgraph CAMP[campanias - no transaccional]
        CH[categoriahabito]
        HAB[habito]
        CAM[campania + cupodiario]
    end

    subgraph PART[participacion - transaccional]
        REG[registro<br/>RegistroParticipacion + DetalleEvidencia]
    end

    SEG["seguridad<br/>(S10 - aun no existe)"]

    SCAMP[(BOM_CAMPANIAS)]
    SPART[(BOM_PARTICIPACION)]

    APP --> CAMP
    APP --> PART
    APP -. se agrega en S10 .-> SEG
    HAB -->|servicio publico| CH
    REG -->|servicio publico| HAB
    REG -->|servicio publico| CAM
    CAMP --> SCAMP
    PART --> SPART

Todos los módulos corren en la misma JVM y comparten un solo datasource. No existe Feign ni comunicación HTTP interna. participacion llama a campanias a través de sus interfaces HabitoService y CampaniaService — nunca a sus repositorios ni a sus entidades.

Figura 2. Recorrido de una petición

flowchart TB
    CLI[Cliente: navegador, curl o Swagger] --> FIL[CorrelationIdFilter<br/>genera X-Trace-ID]
    FIL --> CTR[Controller<br/>recibe DTO, valida con @Valid]
    CTR --> SRV[Service<br/>regla de negocio y @Transactional]
    SRV --> MAP[Mapper MapStruct<br/>DTO a entidad y viceversa]
    SRV --> REP[Repository<br/>Spring Data JPA]
    REP --> ORM[Hibernate ORM]
    ORM --> BD[(Oracle 23ai)]
    SRV -. si lanza excepcion .-> GEH[GlobalExceptionHandler<br/>traduce a 400, 404 o 409]
    GEH --> CLI

El controller no sabe consultar la base de datos y el repositorio no sabe de reglas de negocio. Esa separación es la que permite cambiar Oracle por otro motor tocando una sola capa.

6. Casos de prueba

Tabla 3. Casos verificados en vivo

# Caso Acción Resultado obtenido
1 Backend operativo Arrancar con el perfil dev. Conecta con Oracle 23ai (FREEPDB1) y arranca sin errores.
2 Límites de módulos mvnw test → ModularityTests. 2 pruebas en verde: ningún módulo accede al repositorio de otro.
3 Validación de esquema ddl-auto: validate al arrancar. La aplicación se niega a arrancar si una entidad no tiene su tabla real en Oracle.
4 CRUD — crear POST /categorias-habito con datos válidos. 201 Created con el id asignado.
5 CRUD — listar GET /categorias-habito. Las 4 categorías del catálogo.
6 CRUD — eliminar libre DELETE /categorias-habito/5 (sin hábitos). 204 No Content.
7 CRUD — eliminar bloqueado DELETE /categorias-habito/1 (con hábitos). 409 Conflict: "No se puede eliminar la categoría 'Alimentacion': tiene 1 habito(s) asociado(s)".
8 Objeto relacionado GET /habitos. Cada hábito con su categoría anidada, sin ciclo de serialización.
9 Filtro por relación GET /habitos?categoriaId=1. Solo el hábito de esa categoría.
10 Referencia inválida POST /habitos con categoriaId: 999. 404 Not Found: "Categoria de habito no encontrada: 999".
11 Cabecera–detalle éxito POST /participacion/registros con dos evidencias. 201 Created: cabecera, detalles, subtotales y puntaje total consistentes.
12 Cabecera–detalle rollback POST que excede el cupo diario de la campaña. 409 Conflict y cero filas persistidas: ni cabecera, ni detalles, ni consumo de cupo.
13 Filtros combinados GET /participacion/registros?estado=APROBADO&estudianteId=1&desde=...&hasta=.... Solo los registros que cumplen los cuatro criterios a la vez.
14 Ordenamiento inválido GET /participacion/registros?ordenarPor=cantidadDetalles. 400 Bad Request con el mensaje de la lista blanca, sin filtrar detalles internos.
15 Reporte agregado GET /participacion/registros/resumen. Totales, promedio calculado en BigDecimal y proyección resumida.
16 CORS bloqueado Página file:// contra la API desde Chrome. El navegador bloquea la respuesta: el origen no está en la lista.
17 CORS permitido Misma página desde un origen autorizado por propiedad. La respuesta se entrega al JavaScript de la página.

El caso 12 es el que demuestra atomicidad. @Transactional sobre crear() hace que el fallo en la evidencia número dos revierta también la cabecera y la primera evidencia, aunque ya estuvieran escritas en la sesión de Hibernate. Sin esa anotación quedaría un registro a medias, con puntaje cobrado y evidencia faltante.

El caso 16 es el que demuestra que CORS es una restricción del navegador, no del servidor: la misma petición hecha con curl devuelve 200 y los datos completos, porque curl no aplica la política de mismo origen. El servidor siempre ejecuta la petición; lo que hace CORS es decirle al navegador si tiene permiso de entregar la respuesta al JavaScript que la pidió.

7. Trazabilidad con ADS y BD2

Tabla 4. Trazabilidad entre los tres cursos

Elemento LP2 ADS BD2
Un solo ejecutable con configuración externa por perfil (dev) Vista de despliegue: un contenedor de aplicación y uno de base de datos Credenciales fuera del código, Oracle 23ai en Docker
Monolito modular campanias / participacion con límites verificados Vista C3 de componentes: contenedor Backend API y sus componentes internos Esquemas BOM_CAMPANIAS y BOM_PARTICIPACION con propiedad funcional separada
Relación Habito → CategoriaHabito con DTO resumido Modelo de dominio: entidad Hábito clasificada por categoría FK_HABITO_CATEGORIA, ID_CATEGORIA NOT NULL, UK_CATEGORIA_HABITO_NOMBRE
Operación cabecera–detalle atómica del registro de participación Requisito funcional: el estudiante registra sus evidencias diarias REGISTROS / DETALLE_EVIDENCIAS con FK e integridad referencial
Cupo diario por estudiante y campaña Requisito no funcional: control de abuso del registro CUPOS_DIARIOS con clave única por campaña, estudiante y fecha
Filtros por estado y rango de fecha Requisito no funcional de rendimiento en consultas Índice sobre FECHA en REGISTROS
409 al borrar una categoría en uso Regla de integridad del modelo de dominio La FK de Oracle impide el borrado; el backend lo traduce a un mensaje de negocio

La última fila es la que conviene explicar en vivo: la base de datos ya impide el borrado por sí sola, pero devolvería un ORA-02292 que ningún usuario entiende. El backend consulta primero, detecta la condición y responde con una frase que dice qué pasó y qué hacer. La integridad se defiende en las dos capas, no en una sola.

8. Rúbrica de evaluación

Tabla 5. Rúbrica de la Unidad 1 y evidencia presentada

Criterio Peso Evidencia en este proyecto
1. Proyecto backend con ORM, conexión, recurso REST, DTO y documentación de API 16% Proyecto Maven único, Spring Boot 4.0.7 sobre Java 21, Hibernate contra Oracle 23ai, swagger-ui.html y /v3/api-docs vivos, versionado /api/v1.
2. CRUD REST completo con validaciones, excepciones, logs y pruebas 16% CRUD de categorias-habito y habitos (casos 4–7, 10), GlobalExceptionHandler con 5 traducciones, X-Trace-ID en cada respuesta, 7 pruebas en verde.
3. Objetos relacionados mediante ORM, DTO y reglas de asociación 16% Habito → CategoriaHabito con @ManyToOne, DTO resumido que corta el ciclo, filtro por relación y 409 al borrar una categoría en uso (casos 7–10).
4. Operación cabecera-detalle con registro atómico, cálculos, estados, commit y rollback 16% POST /participacion/registros con cálculo de subtotales y puntaje, estado ENVIADO, y rollback completo por cupo excedido (casos 11–12).
5. Consultas, filtros, ordenamiento, agregaciones, reportes y CORS 16% Cuatro filtros combinables con (:param IS NULL OR ...), orden con lista blanca, proyección por constructor, reporte agregado y CORS por propiedad externa (casos 13–17).
6. Sustentación 20% Presentación de 8 min, demo en vivo de 5 min y respuestas individuales.

9. Trazabilidad y procedencia

Los cinco primeros criterios son cita literal del resultado de aprendizaje de la Unidad I del sílabo de LP2 y corresponden a la porción de backend REST del Nivel 2 de CE023 (Programación). La otra porción de ese nivel — frontend SPA, seguridad JWT e integración full-stack — se completa en la Unidad 2. El criterio 6 corresponde a la sustentación exigida por el sílabo (sesión 6, actividad 2) y verifica competencia general, no CE023.

Alcance declarado como pendiente. Tres reglas del módulo participacion quedan documentadas y no implementadas en este corte: rechazo de hábito duplicado dentro del mismo registro, recálculo del puntaje al rechazar un registro, y validación de evidencias fuera del rango de fechas de la campaña. La entidad Estudiante y el módulo seguridad están diferidos a S10 por decisión del brief y de ADR-004, no por omisión. Se declaran aquí porque la honestidad sobre el alcance forma parte de lo que se sustenta.