# 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.