Entrega Sprint 1 - santig005/MercampusP2 GitHub Wiki
El backlog, lo hicimos en azure, lo puede visitar aquí: Link a backlog
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. |
|
|
|
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:
|
|
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:
|
Hitos Clave:
|
|
Recursos Necesarios:
|
|
Riesgos y contigencia |
Análisis de Riesgos:
|
Estrategias de Contingencia:
|
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
Para mantener la calidad del código y evitar errores antes de su ejecución, utilizamos herramientas de análisis estático.
- ESLint → Detecta errores en código JavaScript/React.
- Prettier → Formatea el código automáticamente para mantener un estilo consistente.
- 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.
- 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.
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.
Para mantener un código limpio y coherente, seguimos los siguientes estándares de nombramiento:
- 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/
).
- Variables y funciones en camelCase (ej:
getUser()
). - Constantes globales en UPPER_CASE (ej:
API_URL
). - Propiedades de objetos en camelCase (ej:
user.businessName
).
- 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.
- Se usa ESLint con el preset de Airbnb o Standard.
- El código debe estar formateado con Prettier para mantener consistencia.
Para mantener un flujo de trabajo ordenado, seguimos la siguiente estrategia de branching:
-
main
→ Contiene el código estable listo para producción. -
develop
→ Rama de desarrollo donde se integran las funcionalidades antes de ir amain
.
-
Cada nueva funcionalidad o corrección se desarrolla en una rama separada
-
Una vez terminada, se hace un Pull Request (PR) a
develop
.
- Un desarrollador crea una feature branch y trabaja en ella.
- Cuando está lista, hace un PR a
develop
. - Se revisa el código y, tras la aprobación, se fusiona en
develop
. -
Cuando
develop
tiene varias funcionalidades listas, se fusiona conmain
.
- No se permite hacer commits directos a
main
odevelop
. - 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.
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.
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.
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.
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.
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.
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.
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).
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
|
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: 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.
- 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.
- 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.
- 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.
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
Espacio de trabajo presencial