288 lines
6.5 KiB
Markdown
288 lines
6.5 KiB
Markdown
# DonConfiao - Asistente Virtual de Tienda La Ilusión
|
|
|
|
## Índice
|
|
1. [Descripción General](#descripción-general)
|
|
2. [Arquitectura](#arquitectura)
|
|
3. [Componentes Principales](#componentes-principales)
|
|
4. [Gestión de Pedidos](#gestión-de-pedidos)
|
|
5. [Catálogo de Productos](#catálogo-de-productos)
|
|
6. [Base de Datos](#base-de-datos)
|
|
7. [API y Endpoints](#api-y-endpoints)
|
|
8. [Guía de Uso](#guía-de-uso)
|
|
9. [Configuración y Despliegue](#configuración-y-despliegue)
|
|
|
|
## Descripción General
|
|
DonConfiao es un asistente virtual diseñado para Tienda La Ilusión que facilita la gestión de pedidos y la atención al cliente. Utiliza procesamiento de lenguaje natural para entender y responder a las solicitudes de los clientes de manera eficiente y amigable.
|
|
|
|
## Arquitectura
|
|
El sistema está construido utilizando una arquitectura modular basada en agentes, implementada con LangGraph y LangChain. Los principales componentes son:
|
|
|
|
- **Classifier Agent**: Clasifica las intenciones del usuario
|
|
- **Catalog Agent**: Maneja consultas relacionadas con productos
|
|
- **Order Agent**: Gestiona todo lo relacionado con pedidos
|
|
- **RAG System**: Proporciona respuestas basadas en conocimiento contextual
|
|
|
|
## Componentes Principales
|
|
|
|
### Classifier Agent
|
|
- Analiza el contexto completo de la conversación
|
|
- Categoriza las consultas en:
|
|
- `general_info`: Información general
|
|
- `catalog`: Consultas sobre productos
|
|
- `order`: Gestión de pedidos
|
|
|
|
### Catalog Manager
|
|
- Gestiona el catálogo de productos
|
|
- Funcionalidades:
|
|
- Búsqueda de productos
|
|
- Verificación de disponibilidad
|
|
- Actualización de precios
|
|
- Gestión de inventario
|
|
|
|
### Order Manager
|
|
- Sistema completo de gestión de pedidos
|
|
- Estados de Pedido:
|
|
- `in_cart`: En carrito
|
|
- `confirmed`: Confirmado
|
|
- `processing`: En proceso
|
|
- `ready`: Listo
|
|
- `delivering`: En entrega
|
|
- `delivered`: Entregado
|
|
- `cancelled`: Cancelado
|
|
|
|
- Estados de Entrega:
|
|
- `pending`: Pendiente
|
|
- `assigned`: Asignado
|
|
- `in_transit`: En tránsito
|
|
- `delivered`: Entregado
|
|
- `failed`: Fallido
|
|
|
|
## Gestión de Pedidos
|
|
|
|
### Funcionalidades Principales
|
|
1. **Gestión de Carrito**
|
|
- Agregar productos
|
|
- Remover productos
|
|
- Ver contenido
|
|
- Modificar cantidades
|
|
|
|
2. **Gestión de Pedidos**
|
|
- Confirmar pedidos
|
|
- Modificar pedidos existentes
|
|
- Combinar múltiples pedidos
|
|
- Eliminar pedidos
|
|
- Consultar estado
|
|
- Aplicar descuentos
|
|
|
|
3. **Seguimiento de Entregas**
|
|
- Actualización de estado
|
|
- Gestión de direcciones
|
|
- Notificaciones de cambios
|
|
|
|
### Herramientas Disponibles
|
|
```python
|
|
- add_to_cart
|
|
- remove_from_cart
|
|
- view_cart
|
|
- confirm_order
|
|
- view_order_history
|
|
- get_order_status
|
|
- merge_orders
|
|
- delete_order
|
|
- modify_order
|
|
- get_order_products
|
|
- update_delivery_status
|
|
- apply_discount
|
|
```
|
|
|
|
## Catálogo de Productos
|
|
|
|
### Estructura de Producto
|
|
```python
|
|
{
|
|
'producto_id': str,
|
|
'producto': str,
|
|
'precio': float,
|
|
'unidad': str,
|
|
'categoria': str,
|
|
'stock': int
|
|
}
|
|
```
|
|
|
|
### Funcionalidades
|
|
- Búsqueda por nombre
|
|
- Filtrado por categoría
|
|
- Verificación de stock
|
|
- Actualización de precios
|
|
- Gestión de inventario
|
|
|
|
## Base de Datos
|
|
|
|
### Tablas Principales
|
|
|
|
#### Orders
|
|
```sql
|
|
CREATE TABLE orders (
|
|
order_id TEXT PRIMARY KEY,
|
|
phone TEXT NOT NULL,
|
|
status TEXT NOT NULL,
|
|
total REAL DEFAULT 0,
|
|
delivery_address TEXT,
|
|
delivery_status TEXT,
|
|
payment_method TEXT,
|
|
discount_applied REAL DEFAULT 0,
|
|
notes TEXT,
|
|
created_at TIMESTAMP,
|
|
updated_at TIMESTAMP
|
|
)
|
|
```
|
|
|
|
#### Order Items
|
|
```sql
|
|
CREATE TABLE order_items (
|
|
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
|
order_id TEXT NOT NULL,
|
|
product_id TEXT NOT NULL,
|
|
quantity INTEGER NOT NULL,
|
|
price REAL NOT NULL,
|
|
unit TEXT NOT NULL,
|
|
FOREIGN KEY (order_id) REFERENCES orders (order_id)
|
|
)
|
|
```
|
|
|
|
## API y Endpoints
|
|
|
|
### Chat API
|
|
- `POST /chat`: Procesa mensajes de chat
|
|
```python
|
|
{
|
|
"message": str,
|
|
"phone": str,
|
|
"context": dict
|
|
}
|
|
```
|
|
- `GET /history`: Obtiene historial de conversación
|
|
```python
|
|
{
|
|
"phone": str
|
|
}
|
|
```
|
|
|
|
### Server API
|
|
- `GET /products`: Lista de productos
|
|
- `GET /orders`: Historial de pedidos
|
|
- `POST /orders`: Crear nuevo pedido
|
|
- `PUT /orders/{id}`: Actualizar pedido
|
|
- `DELETE /orders/{id}`: Eliminar pedido
|
|
|
|
## Guía de Uso
|
|
|
|
### Ejemplos de Interacción
|
|
|
|
1. **Consultar Productos**
|
|
```
|
|
Usuario: "¿Qué productos tienen disponibles?"
|
|
DonConfiao: [Lista productos con precios y disponibilidad]
|
|
```
|
|
|
|
2. **Crear Pedido**
|
|
```
|
|
Usuario: "Quiero 2 kilos de arroz"
|
|
DonConfiao: [Agrega al carrito y muestra confirmación]
|
|
```
|
|
|
|
3. **Modificar Pedido**
|
|
```
|
|
Usuario: "Modifica mi pedido #123"
|
|
DonConfiao: [Muestra opciones de modificación]
|
|
```
|
|
|
|
4. **Combinar Pedidos**
|
|
```
|
|
Usuario: "Combina mis pedidos #123 y #456"
|
|
DonConfiao: [Verifica y combina los pedidos]
|
|
```
|
|
|
|
### Mejores Prácticas
|
|
1. Usar número de teléfono para identificación
|
|
2. Verificar disponibilidad antes de confirmar
|
|
3. Confirmar cambios importantes
|
|
4. Mantener actualizadas las direcciones de entrega
|
|
|
|
## Configuración y Despliegue
|
|
|
|
### Requisitos
|
|
- Python 3.8+
|
|
- SQLite3
|
|
- Dependencias en `requirements.txt`
|
|
|
|
### Variables de Entorno
|
|
```env
|
|
OPENAI_API_KEY=your_api_key
|
|
DATABASE_PATH=path/to/database
|
|
```
|
|
|
|
### Estructura del Proyecto
|
|
```
|
|
app/
|
|
├── data/
|
|
│ ├── orders.db
|
|
│ └── catalog.db
|
|
├── langgraph_tools/
|
|
│ ├── tools/
|
|
│ │ ├── orders/
|
|
│ │ └── catalog/
|
|
│ ├── nodes.py
|
|
│ └── prompts.yaml
|
|
├── rag/
|
|
│ └── knowledge_base/
|
|
├── server.py
|
|
├── chat.py
|
|
└── requirements.txt
|
|
```
|
|
|
|
### Instalación
|
|
```bash
|
|
# Clonar repositorio
|
|
git clone [repository_url]
|
|
|
|
# Instalar dependencias
|
|
pip install -r requirements.txt
|
|
|
|
# Inicializar base de datos
|
|
python init_db.py
|
|
|
|
# Iniciar servidor
|
|
python server.py
|
|
```
|
|
|
|
### Testing
|
|
```bash
|
|
# Ejecutar todos los tests
|
|
python -m pytest test/
|
|
|
|
# Ejecutar tests específicos
|
|
python -m pytest test/test_catalog_db.py
|
|
python -m pytest test/test_db.py
|
|
```
|
|
|
|
## Mantenimiento y Soporte
|
|
|
|
### Logs y Monitoreo
|
|
- Los logs se guardan en `data/logs/`
|
|
- Monitoreo de errores y excepciones
|
|
- Seguimiento de uso y rendimiento
|
|
|
|
### Backup y Recuperación
|
|
- Backups automáticos diarios
|
|
- Procedimiento de recuperación documentado
|
|
- Gestión de versiones de la base de datos
|
|
|
|
### Contacto y Soporte
|
|
- Equipo de desarrollo: dev@tiendailusion.com
|
|
- Soporte técnico: support@tiendailusion.com
|
|
- Documentación adicional: [wiki_url]
|
|
|
|
---
|
|
|
|
Esta documentación está en constante evolución. Para sugerencias o correcciones, por favor contactar al equipo de desarrollo. |