Skip to main content

Historia de Usuario: API Backend y UI para Dashboard de Monitoreo

Versión: 1.0
Fecha: 2025-06-03
Autor: Arquitecto de Tecnologías

🎯 Historia de Usuario​

Como Usuario del Sistema (Operador/Administrador)
Quiero una interfaz de usuario web (Dashboard Angular) con su API Backend de soporte
Para que pueda visualizar métricas clave, el estado general del procesamiento de archivos y la tasa de éxito de pedidos, obteniendo una visión general rápida del rendimiento y salud del sistema.

✅ Criterios de Aceptación​

API Backend (Spring Boot):​

  • GET /api/v1/dashboard/metrics: Devuelve:

    • Total archivos recibidos hoy.
    • Total líneas procesadas hoy.
    • Total líneas exitosamente creadas en Oracle hoy.
    • Total líneas con fallo terminal hoy.
    • (Opcional) Otros KPIs relevantes.

  • GET /api/v1/dashboard/file-volume-trend?days=X: Datos por día de archivos recibidos durante los últimos X días.

  • GET /api/v1/dashboard/order-success-rate: Devuelve cantidad de líneas en ORACLE_CREATION_SUCCESSFUL y en estados de fallo terminal (VALIDATION_FAILED, ORACLE_CREATION_FAILED_TERMINAL) para un período configurable.

UI Angular:​

  1. Página de Dashboard que consuma los endpoints anteriores.
  2. Tarjetas visuales para mostrar datos del endpoint /metrics.
  3. Gráfico de líneas (Chart.js o similar) para volumen de archivos, seleccionable por rango de días (7, 30).
  4. Gráfico de éxito/fallo (dona o barras) para visualizar proporción del endpoint /order-success-rate.
  5. UI responsiva alineada con maqueta del HLD.
  6. Comunicación segura vía HTTPS.

🧪 Definition of Done (DoD)​

  • Endpoints API implementados, documentados (OpenAPI).
  • Componentes Angular del Dashboard creados.
  • Métricas y gráficos correctamente visualizados.
  • UI responsiva y fiel a la maqueta.
  • Código versionado con pruebas.

📦 Consideraciones Técnicas​

  • API: Spring Boot, Spring Data JPA, OpenAPI.
  • UI: Angular CLI, TypeScript, Chart.js.
  • Seguridad API y UI: OAuth2/OIDC (a definir).

🛠️ Producción​

🔐 Seguridad​

  • Autenticación/autorización robusta.
  • Protección contra OWASP Top 10.
  • Configurar correctamente CORS.

🧠 Eficiencia​

  • Consultas optimizadas con índices.
  • Considerar caché si no se requiere tiempo real.

🧪 Observabilidad​

  • Logs de solicitudes/respuestas.
  • Métricas de rendimiento.
  • Errores frontend con Sentry o similar.

Historia de Usuario: API Backend y UI para Consulta de Archivos y sus Líneas

Versión: 1.0
Fecha: 2025-06-03
Autor: Arquitecto de Tecnologías

🎯 Historia de Usuario​

Como Usuario del Sistema (Operador/Administrador)
Quiero una interfaz de usuario web (Angular) con su API Backend para consultar archivos procesados y el detalle de sus líneas
Para que pueda monitorear el estado de cada archivo y analizar el resultado del procesamiento línea por línea, incluyendo errores y reintentos.

✅ Criterios de Aceptación​

API Backend (Spring Boot):​

  • GET /api/v1/files:

    • Lista paginada de processed_files.
    • Filtros: file_name, overall_status_id, rango de received_at, source_id.
    • Campos: file_id, file_name, received_at, source_name, overall_status_name, total_lines, successful_lines, failed_lines.

  • GET /api/v1/files/{fileId}/lines:

    • Lista paginada de file_lines por fileId.
    • Campos: line_number_in_file, client_order_reference, product_sku, quantity, sm_state, retry_count, oracle_order_id, validation_error_details, oracle_api_error_details, last_oracle_attempt_at.

UI Angular:​

  1. Vista de Consulta de Archivos:

    • Tabla paginada de archivos.
    • Filtros en UI.
    • Botón/enlace para “Ver Detalles”.

  2. Vista de Detalle de Archivo (Líneas):

    • Encabezado del archivo.
    • Tabla paginada con líneas.
    • Mostrar estado, errores y reintentos.

  3. UI responsiva y alineada a la maqueta del HLD.

🧪 Definition of Done (DoD)​

  • Endpoints de API implementados, documentados.
  • Componentes Angular desarrollados.
  • Filtrado funcional.
  • Navegación y visualización de líneas funcional.
  • UI responsiva y visualmente correcta.
  • Código con pruebas y versionado.

📦 Consideraciones Técnicas​

  • API: Spring Data Pageable, Criteria API o Querydsl.
  • UI: Angular Material Table, gestión de estado para filtros y paginación.
  • Mapear IDs a nombres legibles.

🛠️ Producción​

🔐 Seguridad​

  • Igual que en el Dashboard: OAuth2/OIDC, protección OWASP, CORS.

🧠 Eficiencia​

  • Consultas indexadas para filtros.
  • Limitar tamaño de página máximo.

🧪 Observabilidad​

  • Logging de consultas.
  • Monitoreo de performance con filtros complejos.