Saltar al contenido principal

01-overview

🚀 Feature: <Nombre de la feature>​

Archivo: 01-overview.md

Este documento sirve como la especificación de alto nivel para una nueva funcionalidad del backend. Proporciona el contexto de negocio, los objetivos y los criterios de aceptación clave, actuando como la base para el desarrollo y las pruebas.

1. Resumen de la Feature​

1.1 Propósito​

Definición: Una frase o párrafo conciso que explica el porqué de esta funcionalidad. Debe responder a:

  • ¿Qué problema de negocio soluciona?
  • ¿Qué valor significativo aporta al usuario o a la organización?

Ejemplo:

“Permite a un organizador consultar la disponibilidad de recursos en tiempo real, eliminando la necesidad de llamadas manuales y mejorando la eficiencia del equipo de inventario.”

1.2 Objetivos y Métricas de Éxito​

Definición: Metas cuantificables que indican cuándo la feature cumple su propósito. Deben ser SMART (Específicos, Medibles, Alcanzables, Relevantes, con Plazo Definido). Incluye métricas (KPIs) para validar su adopción y rendimiento.

Ejemplo:

  • Objetivo 1: Reducir en un 70% las consultas manuales de stock en el primer mes post-lanzamiento.
  • Objetivo 2: Mantener la latencia de respuesta del endpoint de consulta de recursos por debajo de 100 ms en el 95% de las peticiones.
  • Métricas de Seguimiento:
    • Número de llamadas al endpoint /api/v1/resources vs. número de tickets de consulta de inventario.
    • Porcentaje de peticiones al endpoint de consulta con tiempo de respuesta inferior a 100 ms.

1.3. Contexto de Negocio​

Definición: Describe el flujo actual (manual o sistémico) y cómo esta feature se integra y transforma ese proceso. Detalla los procesos o actores previos, y cómo la implementación propuesta optimiza o cambia el flujo general.

Ejemplo:

  1. Flujo Actual: El organizador consulta la disponibilidad de recursos mediante llamadas telefónicas o emails al equipo de inventario, esperando una respuesta manual.
  2. Flujo Propuesto: El organizador utiliza la aplicación para realizar una GET /api/v1/resources y obtener una respuesta instantánea de disponibilidad.
  3. Beneficios Clave:
    • Reducción de puntos de fallo y dependencias humanas (eliminación de comunicación por email/teléfono).
    • Mejora en la trazabilidad y auditoría de las consultas a través de logs del sistema.
    • Aumento de la autonomía y eficiencia del organizador.

1.4 Alcance (In-Scope / Out-of-Scope)​

Definición: Una lista clara de lo que esta feature incluye y excluye de la entrega actual. Esto es crucial para gestionar expectativas y evitar desviaciones.

  • In-Scope: Desarrollos, integraciones y pruebas que se realizarán en esta fase.
  • Out-of-Scope: Funcionalidades, tareas o dependencias que se posponen para futuras fases o son responsabilidad de otro equipo/componente.

Ejemplo:

  • Incluye: Implementación del endpoint REST de consulta de recursos, lógica de negocio asociada, integración con la base de datos PostgreSQL, y una capa de caché en memoria de 30 segundos para las consultas.
  • No Incluye: Cambios en la interfaz de usuario (responsabilidad del frontend y documentados en docs/frontend/), la generación de reportes históricos de uso de recursos, o la gestión de conflictos de reserva.

2. Actores Involucrados​

Definición​

Definición: Un actor es un usuario o sistema externo que interactúa directamente con la feature. Los stakeholders son roles o equipos interesados en el correcto funcionamiento y éxito de la misma.

Actor / StakeholderRol en la Feature / Interés
Organizador de EventosInicia la consulta y reserva de recursos.
Administrador PrincipalSupervisa la gestión de recursos y los permisos de usuario.
Equipo de Desarrollo BackendResponsable de la implementación y mantenimiento.
Equipo de InventarioInteresado en la reducción de consultas manuales.

3. Historias de Usuario y Criterios de Aceptación​

3.1 Historia de Usuario​

Definición: Una frase concisa que describe la necesidad desde la perspectiva del usuario, enfocándose en el valor.

  • Quién (rol/actor).
  • Qué (la capacidad o acción que se desea).
  • Para qué (el valor o beneficio obtenido).

Formato:

“Como <Actor>, quiero <acción> para <beneficio>.”

Ejemplo:

“Como Organizador, quiero consultar los recursos disponibles por fecha para poder planificar eventos sin depender de comunicaciones por email.”

3.2 Criterios BDD (Given–When–Then)​

Definición: Escenarios detallados que describen el comportamiento esperado de la feature de forma estructurada. Sirven como base directa para la implementación y las pruebas automatizadas.

  • Given (Dado que): Describe las precondiciones o el contexto inicial del escenario.
  • When (Cuando): Describe la acción o el evento que desencadena la lógica de la feature.
  • Then (Entonces): Describe el resultado esperado o el cambio observable en el sistema.

Se pueden añadir escenarios alternativos para cubrir casos de borde, errores o flujos no ideales.

Ejemplo: Escenario de éxito - Consulta de recursos disponibles

  • Given un organizador autenticado con el permiso resources.read
  • And existen recursos disponibles para la fecha 2025-07-15 en el sistema
  • When el organizador llama al endpoint GET /api/v1/resources?date=2025-07-15
  • Then el sistema responde con un HTTP 200 OK
  • And el cuerpo de la respuesta contiene un array de objetos JSON con { id, name, quantity, isAvailable } para los recursos disponibles.

Ejemplo: Escenario alternativo - Fecha inválida

  • Given un organizador autenticado
  • When el organizador llama al endpoint GET /api/v1/resources?date=fecha-invalida
  • Then el sistema responde con un HTTP 400 Bad Request
  • And el cuerpo de la respuesta es un error con errorCode: "Validation.InvalidDate" y un mensaje descriptivo.

Ejemplo: Escenario alternativo - Sin recursos disponibles

  • Given un organizador autenticado con el permiso resources.read
  • And no existen recursos disponibles para la fecha 2025-07-16 en el sistema
  • When el organizador llama al endpoint GET /api/v1/resources?date=2025-07-16
  • Then el sistema responde con un HTTP 200 OK
  • And el cuerpo de la respuesta contiene un array JSON vacío o un mensaje indicando que no hay recursos.