Lineamientos | Análisis y Documentación

Se requiere que por cada microservicio se cuente con los siguientes elementos de documentación:

Historias de usuario

Son descripciones concisas y sencillas de una funcionalidad del sistema, escritas desde el punto de vista del usuario. Su objetivo es describir qué necesita el usuario y por qué, en un lenguaje no técnico.

info

Ejemplo:

• Como administrador del inventario
• Quiero poder registrar nuevos productos en el sistema
• Para que el inventario esté actualizado y pueda gestionar las existencias correctamente.

Criterios de Aceptación:

• El sistema debe permitir ingresar el nombre del producto (texto, campo obligatorio).
• El sistema debe permitir ingresar una descripción del producto (texto, campo opcional).
• El sistema debe permitir ingresar el código de barras del producto (texto, campo obligatorio, debe ser único).
• El sistema debe permitir ingresar el precio de compra del producto (numérico, campo obligatorio, con validación de formato).
• El sistema debe permitir ingresar el precio de venta del producto (numérico, campo obligatorio, con validación de formato, no puede ser menor al precio de compra).
• El sistema debe permitir seleccionar la categoría del producto de una lista predefinida (lista desplegable, campo obligatorio).
• El sistema debe permitir ingresar la cantidad inicial en stock (numérico entero, campo obligatorio, valor mínimo 0).
• El sistema debe mostrar un mensaje de confirmación al registrar el producto exitosamente.
• El sistema debe mostrar mensajes de error claros si algún dato ingresado no es válido o si el código de barras ya existe.

Casos de uso

Narran escenarios de interacción, incluyendo los pasos que sigue el usuario y las respuestas del sistema. Pueden incluir múltiples escenarios o rutas que el usuario puede tomar. Se enfocan en la funcionalidad del sistema desde un nivel alto.

info

Caso de Uso 1: Registrar un nuevo producto exitosamente

Actor Principal: Administrador del inventario

Objetivo: Registrar un nuevo producto en el sistema con información válida.

Precondiciones: El administrador del inventario ha iniciado sesión en el sistema y ha accedido a la sección de registro de productos.

Flujo Principal:

• 1- El sistema muestra el formulario de registro de productos con los campos: Nombre, Descripción (opcional), Código de barras, Precio de compra, Precio de venta, Categoría (lista), Cantidad inicial en stock.
• 2- El administrador ingresa un nombre válido para el producto.
• 3- El administrador ingresa una descripción para el producto (opcional).
• 4- El administrador ingresa un código de barras único para el producto.
• 5- El administrador ingresa un precio de compra válido (numérico).
• 6- El administrador ingresa un precio de venta válido (numérico), mayor o igual al precio de compra.
• 7- El administrador selecciona una categoría de la lista desplegable.
• 8- El administrador ingresa una cantidad inicial en stock válida (entero, mayor o igual a 0).
• 9- El administrador hace clic en el botón "Guardar" o similar.
• 10- El sistema valida la información ingresada.
• 11- El sistema guarda la información del nuevo producto en la base de datos.
• 12- El sistema muestra un mensaje de confirmación al administrador indicando que el producto se ha registrado exitosamente.
• 13- El sistema puede redirigir al administrador a la lista de productos o permitirle registrar otro producto.

Caso de Uso 2: Fallo al registrar un nuevo producto por datos inválidos

Actor Principal: Administrador del inventario

Objetivo: Intentar registrar un nuevo producto con información no válida.

Precondiciones: El administrador del inventario ha iniciado sesión en el sistema y ha accedido a la sección de registro de productos.

Flujo Principal:

• 1- El sistema muestra el formulario de registro de productos con los campos: Nombre, Descripción (opcional), Código de barras, Precio de compra, Precio de venta, Categoría (lista), Cantidad inicial en stock.
• 2- El administrador ingresa información no válida en uno o varios campos (por ejemplo, deja el nombre en blanco, ingresa un código de barras ya existente, ingresa un precio de venta menor al de compra, ingresa una cantidad inicial no numérica).
• 3- El administrador hace clic en el botón "Guardar" o similar.
• 4- El sistema valida la información ingresada.
• 5- El sistema detecta uno o varios errores de validación.
• 6- El sistema muestra mensajes de error claros al administrador, indicando los campos que no son válidos y la razón del error.
• 7- El sistema mantiene los datos ingresados en el formulario para que el administrador pueda corregirlos.
• 8- El administrador corrige los datos inválidos y vuelve al paso 9 del Caso de Uso 1.
• 9- Si el administrador no corrige los errores, el registro del producto no se completa.
• 10- Extensiones (podrían ser casos de uso separados, pero aquí los incluimos como variaciones):

Casos de prueba

Detallan los pasos específicos para probar una función o escenario, incluyendo datos de entrada, condiciones previas y resultados esperados. Pueden incluir pruebas de diferentes tipos, como pruebas funcionales, de rendimiento o de seguridad. Se enfocan en la implementación técnica y el comportamiento del sistema.

info

Ejemplos:

Caso de Prueba 1.1: Registro exitoso con todos los campos obligatorios

Caso de Prueba: CP_REG_PROD_001

Descripción: Verificar el registro exitoso de un producto ingresando todos los campos obligatorios con datos válidos.

Precondiciones:

• El sistema está en funcionamiento.
• El administrador del inventario ha iniciado sesión y accedido a la sección de registro de productos.

Pasos:

• Ingresar un Nombre del producto: "Laptop Dell XPS 15".
• Ingresar un Código de barras: "978-1234567890".
• Ingresar un Precio de compra: "12000.00".
• Ingresar un Precio de venta: "15000.00".
• Seleccionar una Categoría: "Electrónica".
• Ingresar una Cantidad inicial en stock: "10".
• Hacer clic en el botón "Guardar".

Resultados Esperados:

• El sistema guarda la información del producto en la base de datos.
• El sistema muestra un mensaje de confirmación similar a "Producto registrado exitosamente".
• El producto registrado aparece en la lista de productos con los datos ingresados.

Caso de Prueba 1.2: Registro exitoso con campo opcional (descripción)

Caso de Prueba: CP_REG_PROD_002

Descripción: Verificar el registro exitoso de un producto ingresando todos los campos obligatorios con datos válidos y proporcionando una descripción. Precondiciones:

• El sistema está en funcionamiento.
• El administrador del inventario ha iniciado sesión y accedido a la sección de registro de productos. Pasos:
• Ingresar un Nombre del producto: "Mouse Logitech MX Master 3S".
• Ingresar una Descripción del producto: "Mouse inalámbrico de alto rendimiento con desplazamiento MagSpeed y botones personalizables.".
• Ingresar un Código de barras: "0978543210123".
• Ingresar un Precio de compra: "2500.00".
• Ingresar un Precio de venta: "3200.00".
• Seleccionar una Categoría: "Accesorios de Computadora".
• Ingresar una Cantidad inicial en stock: "25".
• Hacer clic en el botón "Guardar". Resultados Esperados:
• El sistema guarda la información del producto, incluyendo la descripción, en la base de datos.
• El sistema muestra un mensaje de confirmación similar a "Producto registrado exitosamente".
• El producto registrado aparece en la lista de productos con los datos ingresados, incluyendo la descripción.

Caso de Prueba 1.3: Registro exitoso con cantidad inicial en cero

Caso de Prueba: CP_REG_PROD_003

Descripción: Verificar el registro exitoso de un producto ingresando todos los campos obligatorios con datos válidos y una cantidad inicial en stock de cero. Precondiciones:

• El sistema está en funcionamiento.
• El administrador del inventario ha iniciado sesión y accedido a la sección de registro de productos. Pasos:
• Ingresar un Nombre del producto: "Teclado Mecánico Keychron K2".
• Ingresar un Código de barras: "1987654321098".
• Ingresar un Precio de compra: "3500.00".
• Ingresar un Precio de venta: "4500.00".
• Seleccionar una Categoría: "Accesorios de Computadora".
• Ingresar una Cantidad inicial en stock: "0".
• Hacer clic en el botón "Guardar". Resultados Esperados:
• El sistema guarda la información del producto con la cantidad inicial en stock establecida en cero.
• El sistema muestra un mensaje de confirmación similar a "Producto registrado exitosamente".
• El producto registrado aparece en la lista de productos con una cantidad en stock de 0.

Diagrama contextual

Establece el alcance del microservicio y sus interacciones con otros sistemas, usuarios y servicios. Ayuda a comprender el papel del microservicio dentro del ecosistema general.

info

Elementos:

• El microservicio representado como un rectángulo central.
• Otros sistemas, servicios o usuarios externos con los que interactúa, representados como rectángulos o figuras similares.
• Líneas con flechas que indican el flujo de información y las interacciones entre el microservicio y los elementos externos.
• Etiquetas claras que describen cada elemento y las interacciones.

Diagrama de arquitectura (diagrama de contenedor)

Ilustra la arquitectura tecnológica de un sistema de software, destacando los "contenedores" principales y sus interrelaciones. Para lograr esto de manera efectiva, se deben considerar los siguientes aspectos:

info

Identificación Clara de Contenedores:

• Los contenedores son las unidades de despliegue independientes de software, tales como aplicaciones web, bases de datos, microservicios y aplicaciones móviles. Cada contenedor debe representarse de forma individual.
• Es crucial que cada contenedor esté claramente etiquetado, indicando su nombre y la tecnología principal que utiliza (por ejemplo, "Aplicación Web (Java Spring Boot)", "Base de Datos (PostgreSQL)").

Representación Visual de Relaciones:

• Las interacciones entre los contenedores se visualizan mediante líneas o flechas.
• Cada línea o flecha debe estar etiquetada, describiendo el protocolo o mecanismo de comunicación utilizado (por ejemplo, "HTTPS", "JDBC", "envía mensajes a una cola").
• Esta representación visual permite comprender fácilmente cómo fluyen los datos y las solicitudes entre los diferentes componentes del sistema.

Inclusión de Detalles Relevantes:

• Se pueden añadir notas o leyendas para proporcionar información adicional sobre aspectos específicos de los contenedores o sus interacciones.
• Si el sistema interactúa con sistemas externos, estos también deben incluirse en el diagrama, representando sus interacciones con los contenedores internos.
• Si es importante para la comprensión del sistema, se puede incluir información de capas de la arquitectura, por ejemplo, capa de datos, capa de aplicación y capa de presentación.

Diagramas de secuencia

• Su principal objetivo es mostrar la secuencia cronológica de las interacciones entre objetos.
• El tiempo se representa verticalmente, generalmente de arriba hacia abajo, indicando el orden en que ocurren los eventos.

info

Objetos y Líneas de Vida:

• Los objetos participantes en la interacción se representan como rectángulos en la parte superior del diagrama.
• Cada objeto tiene una "línea de vida" vertical, que muestra su existencia a lo largo del tiempo.

Mensajes:

• Las interacciones entre objetos se representan como flechas que conectan las líneas de vida.
• Estas flechas representan "mensajes" que los objetos se envían entre sí, como llamadas a métodos o solicitudes de datos.
• Los mensajes pueden ser:
  • Síncronos: el remitente espera una respuesta antes de continuar.
  • Asíncronos: el remitente no espera una respuesta inmediata.
  • De retorno: una respuesta a un mensaje síncrono.

Activación:

• La "activación" se representa como un rectángulo vertical delgado sobre la línea de vida de un objeto.
• Indica el período durante el cual el objeto está activo, procesando un mensaje.

Creación y Destrucción de Objetos:

• Los diagramas de secuencia también pueden mostrar la creación y destrucción de objetos a lo largo del tiempo.

Flujos Alternativos y Bucles:

• A través de fragmentos de combinacion como "alt" y "loop" se pueden modelar flujos alternativos y bucles dentro de la secuencia.

Claridad y Precisión:

• Los diagramas de secuencia buscan ser claros y precisos, proporcionando una visión detallada de las interacciones en un escenario específico.

Diagrama de componentes

Los diagramas de componentes sirven para ofrecer una visión detallada del funcionamiento interno de los contenedores de software.

• El diagrama de componentes se centra en desglosar un contenedor individual en sus componentes principales.
• Muestra cómo estos componentes interactúan entre sí y con otros contenedores.
• Está dirigido principalmente a desarrolladores, ya que proporciona una representación detallada de la arquitectura interna del software.

info

Representación de Componentes:

• Los componentes son las piezas de software individuales dentro de un contenedor (por ejemplo, clases, módulos, funciones).
• Cada componente debe representarse de manera clara, como un rectángulo, con su nombre y una breve descripción de su función.

Visualización de Interacciones:

• Las relaciones entre los componentes se muestran mediante líneas o flechas, indicando cómo se comunican o dependen unos de otros.
• Es crucial etiquetar estas líneas para describir el tipo de interacción (por ejemplo, llamadas a funciones, mensajes, intercambio de datos).

Diagrama de clases

Un diagrama de clases es un tipo de diagrama de estructura estática en el Lenguaje Unificado de Modelado (UML) que describe la estructura de un sistema mostrando sus clases, atributos, operaciones (métodos) y las relaciones entre los objetos.

info

Clases:

• Representan conceptos o entidades del sistema.
• Se representan como rectángulos divididos en tres secciones:
  • Nombre de la clase (obligatorio).
  • Atributos (características de la clase).
  • Operaciones (métodos o funciones de la clase).

info

Atributos:

• Describen las características de una clase.
• Indican el tipo de datos y la visibilidad (público, privado, protegido).

info

Operaciones (Métodos):

• Definen el comportamiento de una clase.
• Indican el nombre, los parámetros y el tipo de retorno.

info

Relaciones:

• Describen cómo se relacionan las clases entre sí.
• Los tipos de relaciones más comunes son:
  • Asociación: Una relación general entre clases.
  • Agregación: Una relación "tiene un" (parte-todo).
  • Composición: Una relación "parte-todo" más fuerte, donde la parte no puede existir sin el todo.
  • Herencia: Una relación "es un" (generalización-especialización).
  • Dependencia: Una relación de uso, donde una clase usa otra.