Entrega Sprint 1 - santig005/MercampusP2 GitHub Wiki

Backlog

El backlog, lo hicimos en azure, lo puede visitar aquí: Link a backlog

P1-Primera version del plan de negocio

Sección Item
Resumen ejecutivo Mercampus es una plataforma diseñada para facilitar la compra y venta de productos y servicios dentro de entornos universitarios. Su objetivo es conectar a estudiantes emprendedores con compradores dentro del campus, optimizando la visibilidad de sus productos y facilitando la conexión de manera segura y eficiente. La nueva implementación incluye un sistema de detección de contenido sensible mediante inteligencia artificial (IA), asegurando que las publicaciones cumplan con normas de seguridad y respeto.
El equipo de Mercampus está compuesto por 4 estudiantes con experiencia en desarrollo web, inteligencia artificial, marketing y administración .

Cada miembro aporta conocimientos clave para el crecimiento y la consolidación del proyecto.
  • Venta de productos alimenticios.
  • Promoción pagada para vendedores.
  • Publicaciones segmentadas dentro de la plataforma.
  • Detección automática de contenido sensible mediante IA para garantizar la seguridad y cumplimiento de normas.
Estudiantes universitarios que buscan comprar o vender productos y/o servicios (en un futuro) dentro del campus de su universidad. Estos comprenden un rango de edad entre 16 y 25 años aproximadamente.
Aplicaciones de compraventa general (como Facebook Marketplace), grupos de WhatsApp/Telegram y tiendas locales dentro de la universidad. La principal diferenciación de Mercampus es la centralización de los productos y también su sistema de IA para garantizar un ambiente seguro y controlado.
Corto Plazo: Implementar y afinar el sistema de detección de contenido sensible para garantizar su efectividad.

Largo Plazo: Expandirse a otras universidades y diversificar los servicios ofrecidos en la plataforma, manteniendo un entorno seguro y confiable.
Descripción del Negocio Historia y Antecedentes:

Mercampus surge como una solución a la falta de visibilidad de estudiantes emprendedores dentro del campus universitario. La idea se gestó tras observar la dificultad de promocionar y vender productos en un entorno competitivo. Con el crecimiento de la plataforma, se identificó la necesidad de integrar IA para garantizar que las publicaciones cumplan con normas de seguridad y evitar contenido inapropiado.
Misión: Facilitar el comercio entre estudiantes universitarios mediante una plataforma digital accesible y confiable, con un sistema de detección de contenido sensible para garantizar un ambiente seguro.

Visión: Convertirse en la principal plataforma de compraventa y servicios para estudiantes universitarios en Latinoamérica, con tecnología de IA para la seguridad del contenido.
Valores:
  • Innovación
  • Transparencia
  • Confianza
  • Seguridad
  • Empoderamiento estudiantil
Análisis del mercado Investigación de Mercado:

Se han realizado encuestas y entrevistas con estudiantes para identificar sus necesidades y evaluar la aceptación de una plataforma digital de compraventa dentro de la universidad. Además, se analizó la preocupación por contenido inadecuado, lo que impulsó la implementación de IA para la moderación de publicaciones.
Segmentación del Mercado:

Segmento Primario: Estudiantes universitarios emprendedores.

Segmento Secundario: Estudiantes compradores y consumidores frecuentes dentro del campus.
Clientes Objetivo:

Estudiantes que buscan una alternativa fácil y accesible para vender o comprar productos sin salir de la universidad, con la garantía de un entorno seguro.
Análisis de Competencia:

Los principales competidores son los grupos en redes sociales y tiendas físicas dentro del campus. Mercampus se diferencia al ofrecer una solución específica y optimizada para el entorno universitario, con un sistema de IA que previene contenido inapropiado.
Servicio Descripción del Servicio:

Plataforma web que permite a los estudiantes publicar y buscar productos y servicios ofrecidos dentro del campus, con moderación automática mediante IA para detectar contenido sensible.
Propuesta de Valor:

Facilita la conexión entre vendedores y compradores dentro de la universidad, optimizando la experiencia de compraventa con categorías, filtros, búsqueda y un sistema de IA que garantiza publicaciones seguras.
Ciclo de Vida del Producto:

1. Lanzamiento: Plataforma en una universidad piloto con sistema de detección de contenido sensible.
2. Crecimiento: Expansión a otras universidades.
3. Madurez: Consolidación como líder en el mercado universitario.
4. Diversificación: Inclusión de nuevos servicios y funcionalidades.
Implementación Cronograma:

  • Mes 1-2: Desarrollo de la plataforma con integración de IA.
  • Mes 3: Lanzamiento en una universidad piloto.
  • Mes 4-6: Evaluación del rendimiento y ajustes en la IA.
  • Mes 7 en adelante: Expansión progresiva.
Hitos Clave:

  • Desarrollo y pruebas de la plataforma con IA.
  • Primer lanzamiento y validación con usuarios.
  • Implementación de estrategias de monetización.
  • Expansión a nuevas universidades.
Recursos Necesarios:

  • Desarrollo y mantenimiento de la plataforma con tecnología de IA.
  • Estrategias de marketing y publicidad.
  • Infraestructura tecnológica (hosting, dominios, seguridad, algoritmos de IA).
Riesgos y contigencia Análisis de Riesgos:
  • Falta de adopción por parte de los usuarios.
  • Competencia con redes sociales y otras plataformas.
  • Problemas técnicos y de seguridad en la IA.
  • Falsos positivos o negativos en la detección de contenido.
Estrategias de Contingencia:
  • Estrategias de marketing enfocadas en los beneficios diferenciadores.
  • Colaboraciones con asociaciones estudiantiles y universidades.
  • Inversión en seguridad y optimización tecnológica para garantizar una plataforma estable.
  • Mejora continua del algoritmo de IA basado en retroalimentación de usuarios.

P2-Insumo de prueba de Usabilidad: Interfaz de Usuario

Prototipo Funcional

Mercampus es una plataforma completamente funcional y desplegada en producción, con una interfaz de usuario operativa que permite a los estudiantes publicar y buscar productos de manera intuitiva. La aplicación ya implementa los flujos principales, como registro, publicación, búsqueda y contacto con vendedores, asegurando una experiencia de usuario fluida. Dado que la solución está en un estado avanzado de desarrollo y disponible para pruebas reales, no es necesario un prototipo semifuncional, ya que la versión actual cumple con los requisitos para evidenciar la interacción y usabilidad esperada.

Para probar la funcionalidad debe estar logueado y registrado como vendedor y ahi si cuando suba un producto entonces saldrá la alerta. De igual manera se adjuntan algunos archivos de referencia como lo son los flujos que debe seguir el usuario para obtener esa alerta de publicación rechazada.

Video de la demostración: https://youtu.be/eezCB_V32is

Link a página desplegada

P3-Calidad del software

Análisis Estático de Código

Para mantener la calidad del código y evitar errores antes de su ejecución, utilizamos herramientas de análisis estático.

1. Herramientas utilizadas

  • ESLint → Detecta errores en código JavaScript/React.
  • Prettier → Formatea el código automáticamente para mantener un estilo consistente.

2. Configuración de ESLint

  • Se usa el preset Airbnb o Standard, con las reglas personalizadas del equipo.
  • Se ejecuta automáticamente antes de cada commit usando Husky y lint-staged.

3. Configuración de Prettier

  • Se activa en conjunto con ESLint para corregir errores de formato.
  • Se ejecuta antes de los commits para evitar código mal formateado en el repositorio.

4. Justificación

El uso de ESLint y Prettier ayuda a detectar errores antes de que el código se ejecute, garantizando consistencia en el proyecto y reduciendo problemas en producción.

Reglas de Nombramiento para el Proyecto

Para mantener un código limpio y coherente, seguimos los siguientes estándares de nombramiento:

1. Archivos y Carpetas

  • Los componentes React deben estar en PascalCase (ej: ProductCard.js).
  • Los hooks deben comenzar con use y estar en camelCase (ej: useAuth.js).
  • Las carpetas deben estar en kebab-case (ej: components/, services/).

2. Variables y Funciones

  • Variables y funciones en camelCase (ej: getUser()).
  • Constantes globales en UPPER_CASE (ej: API_URL).
  • Propiedades de objetos en camelCase (ej: user.businessName).

3. Estilos

  • Los archivos de estilos deben llamarse igual que su componente con .module.css o .module.scss (ej: ProductCard.module.css).
  • Se recomienda usar Tailwind CSS o CSS Modules para evitar conflictos de nombres.

4. Reglas de ESLint

  • Se usa ESLint con el preset de Airbnb o Standard.
  • El código debe estar formateado con Prettier para mantener consistencia.

Estrategia de Branching en Git

Para mantener un flujo de trabajo ordenado, seguimos la siguiente estrategia de branching:

1. Ramas Principales

  • main → Contiene el código estable listo para producción.
  • develop → Rama de desarrollo donde se integran las funcionalidades antes de ir a main.

2. Ramas de Características (Feature Branches)

  • Cada nueva funcionalidad o corrección se desarrolla en una rama separada

  • Una vez terminada, se hace un Pull Request (PR) a develop.

3. Flujo de Integración

  1. Un desarrollador crea una feature branch y trabaja en ella.
  2. Cuando está lista, hace un PR a develop.
  3. Se revisa el código y, tras la aprobación, se fusiona en develop.
  4. Cuando develop tiene varias funcionalidades listas, se fusiona con main.

4. Reglas de Protección

  • No se permite hacer commits directos a main o develop.
  • Todo código debe pasar por Pull Requests con revisión de pares.
  • Solo se fusiona a main si el código pasó pruebas en GitHub Actions y tiene aprobación de al menos un revisor.

5. Justificación

Este flujo asegura que:

  • El código en main siempre esté estable.
  • Los desarrolladores trabajen en paralelo sin conflictos.
  • Se eviten errores en producción mediante revisiones y pruebas automáticas.

P4 - Pruebas unitarias

1. Manejo de Excepciones

El proyecto implementa un manejo robusto de excepciones, especialmente en la interacción con APIs. Se utilizan bloques try-catch en las solicitudes asíncronas y se gestionan los errores de forma adecuada, asegurando que cada API devuelva respuestas estructuradas y comprensibles. En caso de fallos, se capturan y registran los errores sin exponer información sensible.

2. Mensajes de Error

Los mensajes de error son claros, concisos y significativos, proporcionando información útil para la depuración sin saturar la interfaz de usuario ni los registros del servidor. Se emplean estados y toast notifications en el frontend para mostrar mensajes comprensibles al usuario cuando una acción no puede completarse.

3. Comentarios en el Código

El código está bien documentado en inglés, con comentarios detallados en cada función y componente tanto en el backend como en el frontend. Se explican las responsabilidades de cada archivo y su interacción dentro del sistema. Además, se sigue la filosofía de "comentarios útiles", evitando descripciones redundantes o innecesarias.

4. Indentación y Formato

Se mantiene una indentación consistente con ESLint y Prettier para garantizar un código limpio y bien estructurado. Además, se aplican reglas de formato adecuadas en archivos .js/.jsx, asegurando coherencia en todo el proyecto.

5. Convención de Nombres

Se sigue la convención camelCase para variables y funciones, mientras que los componentes de React utilizan PascalCase. Las rutas de las API están en camelCase para mantener uniformidad en los endpoints.

6. Organización del Proyecto

El código se organiza siguiendo una estructura modular basada en sustantivos, donde las carpetas principales agrupan funcionalidades específicas. Se aplica una arquitectura escalable con la siguiente estructura:

/src

  • /components → Componentes reutilizables
  • /app → Páginas de Next.js
  • /api → Funciones para llamadas a APIs
  • /utils → Utilidades y helpers
  • /services → servicios personalizados
  • /context → contextos globales

Las importaciones dentro de los archivos se ordenan alfabéticamente y se separan por bloques (dependencias externas, módulos internos).

7. Relación entre Código y Requerimientos

A continuación, se presenta un mapeo entre las historias de usuario y los archivos de código asociados:

Historia de Usuario Posible Ubicación del Código
H15 - Visualizar descripción /app/products/product/[id].js (Página de detalle del producto)
H14 - Visualizar Imagen /components/ProductImage.js (Componente de imagen)
H04 - Editar Descripción /components/EditDescription.js, /services/productService.js (Llamada API para editar)
H03 - Cargar Descripción /components/ProductForm.js, /services/productService.js
H02 - Borrar Imagen /components/ProductImage.js, /services/imageService.js
H09 - Deshabilitar vendedores /app/sellers/approving.js, /services/sellerService.js
H06 - Escribir a un vendedor para comentarle el caso /components/SendMessage.js, /services/messageService.js
H08 - Generar notificación de texto no adecuado /services/notificationService.js, /services/useTextModeration.js
H07 - Analizar texto de productos con IA para detectar contenido no adecuado /services/awsComprehend.js, /services/useTextModeration.js
H05 - Ver reportes de textos posiblemente inapropiados /app/admin/reports.js, /components/ReportList.js

8. Pruebas Unitarias

Cada fragmento de código ha sido sometido a pruebas unitarias utilizando Jest y React Testing Library para validar su correcto funcionamiento. Los datos de prueba incluyen diferentes escenarios de entrada y salida esperados.

Prueba #1

  • Prueba: Se verificó que la IA identifique correctamente textos ofensivos o no permitidos.
  • Input probado:
    • "Galletas rellenas de amor."
    • "Se*o." (Inapropiado)
  • Error encontrado: La IA tenía dificultades para detectar frases con jerga de Colombia.
  • Corrección: Se Implementó una blacklist.

Captura de pantalla 2025-03-16 152453

Prueba #2

  • Prueba: Se comprobó que las imágenes de los productos se muestren correctamente.
  • Input probado:
    • imagen.jpg (Formato válido)
    • imagen.tiff (Formato no soportado)
    • imagen_5MB.png (Tamaño demasiado grande)
  • Error encontrado: Las imágenes en formato TIFF o de gran tamaño no cargaban correctamente.
  • Corrección: Se añadieron validaciones para formatos soportados (jpg, png) y se implementó compresión de imágenes grandes. Captura de pantalla 2025-03-29 172259 Captura de pantalla 2025-03-16 192846

Prueba #3

  • Prueba: Se validó la eliminación de imágenes de productos.
  • Input probado:
    • imagen123.jpg
    • imagen_no_existente.png
  • Error encontrado: Algunas imágenes se eliminaban de la interfaz pero no del servidor.
  • Corrección: Se mejoró la sincronización entre la base de datos y el servidor para eliminar la imagen completamente. Captura de pantalla 2025-03-29 171159

Prueba #4 y #5

  • Prueba: Se validó que los cambios en la descripción se guarden y reflejen correctamente.
  • Input probado:
    • "Nueva descripción con más detalles sobre el producto."
    • "@#$%^&*" (Caracteres especiales)
    • "" (Descripción vacía)
  • Error encontrado: No permitía descripciones vacías.
  • Corrección: Se añadieron validaciones para evitar errores con descripciones en blanco.

  • Prueba: Se verificó que la descripción del producto se cargue correctamente en la interfaz.
  • Input probado:
    • "Galletas hechas con amor" (Texto válido)
    • "" (Vacío)
  • Error encontrado: Cuando la descripción estaba vacía, el sistema mostraba un espacio en blanco en lugar de un mensaje.
  • Corrección: Se implementó "Sin descripción disponible" cuando el campo está vacío.

Captura de pantalla 2025-03-29 170756

Ceremonias

El medio más usado para las ceremonias es informal, por medio de Whatsapp, a pesar de lo informal mediante este logramos estar al tanto de novedades, resolver problemas y fijar prioridades, representando un promedio de más de mensajes diarios incluso en fines de semana, con participación activa de todos los integrantes. Incluso a veces se realizan llamadas por este mismo canal con los mismos propósitos

Imagen de WhatsApp 2025-03-16 a las 23 45 33_6da4d9ac

Espacio de trabajo presencial

20250314_172050

Poker Planning

Captura de pantalla 2025-03-13 211407 Captura de pantalla 2025-03-13 211454 Captura de pantalla 2025-03-13 211433

⚠️ **GitHub.com Fallback** ⚠️