demoMAGIC

Asistente comercial full-stack con IA, búsqueda sobre conocimiento propio y acciones de negocio.

demoMAGIC permite consultar productos y servicios, recibir recomendaciones y preparar una propuesta desde una interfaz responsive.

Combina un frontend en HTML, CSS y JavaScript con una API Spring Boot. Incluye tres escenarios empresariales, búsqueda semántica opcional mediante embeddings y un modo de respaldo que funciona sin credenciales de OpenAI.

Note

Es una demo técnica: no incorpora autenticación, base de datos ni persistencia del carrito.

Funcionalidades

• Chat comercial en español e inglés.
• Tres bases de conocimiento seleccionables:
  • A: Urbania Nexus Inmobiliaria.
  • B: LeadWave Growth Marketing.
  • C: MotoRecambio Atlas.
• Recuperación híbrida:
  • similitud vectorial mediante embeddings cuando existe OPENAI_API_KEY;
  • búsqueda léxica local cuando la API no está configurada.
• Respuestas mediante OpenAI Chat Completions o un fallback local.
• Detección de acciones ADD, REMOVE, CLEAR y SHOW.
• Carrito temporal gestionado en el navegador.
• Solicitud de propuesta por WhatsApp o correo electrónico.
• Diseño adaptado a escritorio, tablet y móvil.
• Compartición mediante código QR.
• CORS y puerto configurables por entorno.
• Health check para despliegue y monitorización básica.

Arquitectura

flowchart LR
    U[Usuario] --> F[Frontend HTML · CSS · JavaScript]
    F -->|POST /api/chat| API[API Spring Boot]
    API --> I[Detección de intención]
    API --> KB[Bases de conocimiento A · B · C]
    KB --> R[Recuperación de contexto]
    R --> M{OPENAI_API_KEY}
    M -->|Configurada| O[Embeddings + Chat Completions]
    M -->|No configurada| L[Búsqueda léxica + respuesta local]
    O --> API
    L --> API
    API --> F
    F --> C[Carrito y contacto]

Loading

Stack

Capa	Tecnología
Frontend	HTML5, CSS3 y JavaScript
Backend	Java 17 y Spring Boot 3.4.2
API	REST y Jakarta Validation
IA	OpenAI Chat Completions y Embeddings
Recuperación	Similitud coseno con fallback léxico
Testing	JUnit 5 y Spring Boot Test
Despliegue	Frontend estático y backend con puerto dinámico

Estructura

.
├── back/
│   ├── pom.xml
│   └── src/
│       ├── main/
│       │   ├── java/com/nebulasur/demomagic/
│       │   └── resources/kb/
│       └── test/
├── front/
│   ├── assets/
│   ├── data/
│   ├── i18n/
│   ├── app.js
│   ├── config.js
│   ├── index.html
│   └── styles.css
├── netlify.toml
└── start-local.bat

Requisitos

• Java 17 o superior.
• Maven 3.9 o superior.
• Python 3, Node.js u otro servidor HTTP estático para el frontend.
• Una API key de OpenAI es opcional.

Ejecución local

Inicio rápido en Windows

.\start-local.bat

Después abre:

• Frontend: http://localhost:5500
• Backend: http://localhost:8080
• Health check: http://localhost:8080/health

Inicio manual

Backend:

cd back
mvn spring-boot:run

Frontend, desde otra terminal:

cd front
python -m http.server 5500

Configuración

Variable	Obligatoria	Predeterminado	Uso
OPENAI_API_KEY	No	—	Activa embeddings y respuestas generadas
PORT	No	8080	Puerto HTTP
ALLOWED_ORIGINS	No	*	Orígenes permitidos por CORS
OPENAI_CHAT_MODEL	No	gpt-4o-mini	Modelo de chat
OPENAI_EMBEDDING_MODEL	No	text-embedding-3-small	Modelo de embeddings
CHAT_RELEVANCE_MIN_SCORE	No	0.20	Umbral mínimo de relevancia

No guardes claves reales en el repositorio.

API

Health check:

GET /health

Chat:

POST /api/chat
Content-Type: application/json

{
  "kb": "A",
  "message": "¿Qué servicios ofrecéis?",
  "cart": [],
  "lang": "es"
}

Respuesta base:

{
  "reply": "Respuesta del asistente",
  "actions": [],
  "item": null,
  "citations": []
}

Pruebas

cd back
mvn test

El proyecto incluye un replay de preguntas que comprueba que el asistente devuelve respuestas no vacías.

Build

cd back
mvn clean package
java -jar target/demomagic-back-0.0.1-SNAPSHOT.jar

Despliegue

netlify.toml publica directamente el directorio front. Antes del despliegue, configura API_BASE_URL para apuntar al backend público.

La aplicación backend respeta la variable PORT. En producción configura como mínimo los orígenes CORS y, si se utiliza OpenAI, la clave y los modelos correspondientes.

Este repositorio no declara actualmente una URL de producción: las instrucciones describen compatibilidad de despliegue, no una demo pública verificada.

Limitaciones actuales

• No existe autenticación ni gestión de usuarios.
• El carrito vive únicamente en memoria del navegador.
• No hay persistencia de conversaciones ni productos.
• La caché y el estado temporal del backend viven en memoria.
• Los datos y precios pertenecen a escenarios de demostración.
• No se ha configurado observabilidad ni rate limiting para producción.

Licencia

Este repositorio todavía no declara una licencia de uso. Para reutilizar el código fuera de fines de evaluación, contacta con el autor.

Autor

Desarrollado por Chemi90.