crudactivity-mobilefix.md

CRUDACTIVITY — MobileFix

Reparaciones móviles con capas, H2, JSP, trazabilidad y commits convencionales

Contexto

Vas a construir MobileFix, una aplicación para gestionar órdenes de reparación de dispositivos móviles. Debe permitir inicio de sesión con tres roles: USER, TECH (técnico) y ADMIN. Cada rol verá y ejecutará acciones acordes a sus permisos. El objetivo es practicar flujo completo por capas: Vistas (JSP) → Controller → Service → Repository → H2, con tests, trazabilidad y disciplina de commits.

---

Requerimientos técnicos

• Lenguaje: Java 21
• Framework: Spring Boot (Web, Validation)
• Persistencia: H2 (memoria o file), Spring Data JPA
• Vistas: JSP (opcional Thymeleaf)
• Seguridad: autenticación en memoria (3 roles) o almacenamiento en H2
• Pruebas: JUnit 5 + Spring Boot Test (unitarias)
• Convenciones: ResponseEntity en todos los controladores REST
• Trazabilidad: Azure Boards
• Commits: Conventional Commits (ej.: feat: add repair order creation)
• Naming: todo en inglés (clases, endpoints, variables, vistas)

---

Requerimientos funcionales

Roles y permisos (mínimo)

• USER: crear solicitud de reparación, ver sus órdenes, cancelar si está en PENDING.
• TECH: ver órdenes asignadas, cambiar estado (IN_PROGRESS, READY, DELIVERED), añadir notas técnicas.
• ADMIN: ver todas las órdenes, asignar técnico, actualizar catálogo de dispositivos, administrar usuarios.

Entidades (modelos)

• User: id, username (único), password (hash), role ∈ {USER, TECH, ADMIN}, fullName, email, enabled.
• Device: id, brand, model, serialNumber (único opcional).
• RepairOrder: id, customer (User), device (Device), issueDescription, status ∈ {PENDING, IN_PROGRESS, READY, DELIVERED, CANCELED}, assignedTech (User? null si no asignado), createdAt, updatedAt, techNotes (opcional).

Auditoría: createdAt y updatedAt se actualizan automáticamente a nivel de entidad o servicio.

Endpoints REST (usar ResponseEntity)

• Auth (opcional si usas Security con formLogin): POST /api/auth/login, POST /api/auth/logout.

• Repair Orders

  • GET /api/orders

    • ADMIN: todas. TECH: solo asignadas. USER: solo propias.
    • Query opcional: status, page, size, sort.

  • POST /api/orders (USER)

    • Body: { "deviceId": number, "issueDescription": "string>=10" }

  • PUT /api/orders/{id}/assign/{techId} (ADMIN)

  • PUT /api/orders/{id}/status (TECH/ADMIN)

    • Body: { "status": "IN_PROGRESS|READY|DELIVERED|CANCELED", "techNotes": "string?" }

  • DELETE /api/orders/{id} (USER/ADMIN)

    • Reglas: USER sólo si PENDING y propia; ADMIN siempre.

• Devices

  • GET /api/devices (todos los roles)
  • POST /api/devices (ADMIN)
  • PUT /api/devices/{id} (ADMIN)
  • DELETE /api/devices/{id} (ADMIN)

• Users (solo ADMIN básico)

  • GET /api/users
  • POST /api/users (crear técnico/usuario/admin)

Vistas (JSP; Thymeleaf opcional)

• Login (/login): formulario de acceso.

• Dashboard:

  • USER: formulario “New Repair”, listado de mis órdenes con acciones permitidas.
  • TECH: listado de órdenes asignadas, acción “Change status”, agregar notas.
  • ADMIN: todas las órdenes, asignación a técnico, ABM de Devices y Users.

• Orders list/detail: JSPs que consumen los endpoints (fetch) o ModelAndView según prefieras.

Validaciones y errores (respuesta estándar)

• 400 → { "error": "Validation failed", "fields": { "issueDescription": "min 10" } }
• 401/403 según autenticación/rol.
• 404 → { "error": "Not found" }
• 409 → { "error": "Username already exists" } o conflictos de estado.

---

Arquitectura por capas

• view/ (JSP o Thymeleaf).
• controller/.
• service/.
• repository/.
• model/.
• config/.

---

Pruebas (mínimo)

Unitarias (JUnit 5)

• OrderService

  • create: válido → crea con PENDING; inválido → excepción/400 (título/issue corto, device inexistente).
  • assignTech: ADMIN asigna técnico válido; no-ADMIN → prohibido.
  • changeStatus: transición válida (PENDING→IN_PROGRESS→READY→DELIVERED); inválida → error.
  • delete: USER dueño con PENDING → ok; status distinto o ajena → prohibido.

• DeviceService

  • ABM básico con validaciones de campos.

(Opcional) Web layer

• Tests de controlador con @WebMvcTest para validar ResponseEntity (códigos y payloads).

---

Seguridad (mínimo para iniciar sesión)

• Spring Security con:

  • In-memory o H2 para usuarios de prueba:

    • user/user123 → ROLE_USER
    • tech/tech123 → ROLE_TECH
    • admin/admin123 → ROLE_ADMIN

  • Rutas protegidas por rol según endpoints.

  • /login form-login y /logout habilitados.

  • H2 console accesible solo en desarrollo.

---

Trazabilidad (Azure Boards) y commits

• Crea Work Items: Auth, Orders CRUD, Status Flow, Devices CRUD, Users admin, Views.

• Enlaza cada commit/PR con su Work Item ID (ej.: feat(order): create endpoint for new order #123).

• Convencional Commits (obligatorio):

  • feat:, fix:, test:, docs:, refactor:, chore:, style:
  • Ej.: feat(order): allow TECH to change status to IN_PROGRESS #127

---

Entregables

1. Proyecto ejecutable (H2 con datos de ejemplo).
2. Vistas JSP funcionales (o Thymeleaf) según rol.
3. API REST con ResponseEntity (códigos correctos y payloads claros).
4. Modelos (User, Device, RepairOrder) y repositorios.
5. Servicios con reglas de negocio y validaciones.
6. Pruebas unitarias con JUnit 5 (Service, y opcional Web layer).
7. Trazabilidad en Azure Boards.
8. README (cómo correr, usuarios de prueba, rutas principales).

---

Criterios de aceptación

• Login operativo por rol y acceso diferenciado a vistas/acciones.
• USER puede crear y ver sus órdenes; borrar solo si PENDING.
• ADMIN puede listar todas, asignar técnico y administrar catálogo de devices/users.
• TECH puede ver asignadas y cambiar estado con reglas válidas.
• Endpoints devuelven ResponseEntity con códigos y errores coherentes.
• Tests unitarios clave del OrderService pasando.

---