🎨 Shade Finder AI - Recomendador Inteligente de Tonos para Shopify

Sistema avanzado de matching de tonos de piel basado en IA que se integra perfectamente con tu tienda Shopify

📋 Descripción

Shade Finder AI es una aplicación web que ayuda a tus clientes a encontrar el tono perfecto de maquillaje basándose en análisis científico del color y recomendaciones personalizadas generadas por inteligencia artificial. El sistema utiliza el espacio de color CIELAB y cálculos de Delta E (ΔE) para ofrecer matching preciso de tonos.

✨ Características Principales

• 🎯 Matching Preciso: Algoritmo basado en CIELAB color space con cálculo de Delta E
• 🤖 Recomendaciones IA: Explicaciones personalizadas generadas con OpenAI GPT-4o-mini
• 🛍️ Integración Shopify: Sincronización automática de productos, variantes y metafields
• 📊 Panel Administrativo: Dashboard completo con analytics y gestión de datos
• 🔧 Widget Embebible: JavaScript widget fácil de integrar en cualquier tienda Shopify
• ⚙️ Sistema de Configuración: Settings dinámicos almacenados en base de datos con caché
• 📱 Responsive Design: Interfaz adaptable a todos los dispositivos
• 🌍 Multilenguaje: Soporte para español (fácilmente extensible)

🚀 Inicio Rápido

Prerrequisitos

• PHP >= 8.2
• Composer
• Node.js >= 18.x
• npm o yarn
• SQLite (o MySQL/PostgreSQL)
• Cuenta de Shopify con acceso a Admin API
• API Key de OpenAI

Instalación

1. Clonar el repositorio

git clone <tu-repositorio>
cd shadefinder-api

2. Instalar dependencias de PHP

composer install

3. Instalar dependencias de Node.js

npm install

4. Configurar entorno

cp .env.example .env
php artisan key:generate

5. Configurar base de datos

Edita .env y configura tu conexión a base de datos:

DB_CONNECTION=sqlite
# DB_DATABASE=/ruta/absoluta/database/database.sqlite

# O si usas MySQL:
# DB_CONNECTION=mysql
# DB_HOST=127.0.0.1
# DB_PORT=3306
# DB_DATABASE=shadefinder
# DB_USERNAME=root
# DB_PASSWORD=

6. Ejecutar migraciones

php artisan migrate

7. Crear usuario administrador

php artisan tinker

User::create([
    'name' => 'Admin',
    'email' => 'admin@example.com',
    'password' => Hash::make('password123')
]);

8. Compilar assets

npm run build

9. Iniciar servidor de desarrollo

php artisan serve

Accede a: http://localhost:8000

⚙️ Configuración

1. Configuración de Shopify

1. Inicia sesión en el panel administrativo: http://localhost:8000/login
2. Ve a Configuración en el menú lateral
3. En la pestaña Shopify, ingresa:
   • Shopify Store URL: tu-tienda.myshopify.com (sin https://)
   • Admin API Access Token: Tu token de acceso (ver abajo cómo obtenerlo)
   • API Version: 2024-10 (recomendado)

Obtener Access Token de Shopify

1. Ve a tu admin de Shopify: tu-tienda.myshopify.com/admin
2. Navega a Configuración → Aplicaciones y canales de venta
3. Haz clic en Desarrollar aplicaciones
4. Crea una nueva aplicación personalizada
5. En Configuración de API, selecciona los permisos necesarios:
   • read_products
   • write_products
   • read_product_listings
6. Instala la aplicación y copia el Admin API access token

2. Configuración de OpenAI

1. En el panel de Configuración, pestaña OpenAI:
   • API Key: Tu clave de API de OpenAI (obtenerla aquí)
   • Model: gpt-4o-mini (recomendado) o gpt-4o
   • Max Tokens: 150-300 (según necesidad)
   • Temperature: 0.7 (creatividad media)

3. Configuración del Widget

1. En Configuración, pestaña Widget:

   • Primary Color: Color principal del widget (hex)
   • Text Color: Color del texto (hex)
   • Background Color: Color de fondo (hex)

2. Copia el código de integración generado automáticamente

🔗 Integración del Widget en Shopify

Método 1: Tema (Recomendado)

1. En tu admin de Shopify, ve a Tienda online → Temas
2. Haz clic en Acciones → Editar código
3. Abre theme.liquid o layout/theme.liquid
4. Antes del cierre de </body>, pega:

<script src="https://tu-dominio.com/widget.js"></script>
<script>
  window.ShadeFinder.init({
    apiUrl: 'https://tu-dominio.com',
    primaryColor: '#7C3AED',
    textColor: '#FFFFFF',
    backgroundColor: '#1F2937'
  });
</script>

5. Guarda los cambios

Método 2: Página de Producto

Si solo quieres el widget en páginas de productos específicos:

1. Edita la plantilla de producto (sections/product-template.liquid)
2. Agrega el script del widget antes de </body> o en la sección deseada
3. El widget se mostrará automáticamente en productos que tengan tonos configurados

📊 Sincronización de Productos

Sincronización Manual

Usa el comando Artisan para sincronizar productos desde Shopify:

php artisan shopify:sync

Este comando:

• Importa todos los productos de tu tienda
• Sincroniza variantes con sus metafields
• Detecta automáticamente tonos basados en metafields shade_name, hex_color, undertone
• Actualiza productos existentes

Sincronización Automática (Scheduler)

1. Configura el cron job en tu servidor:

* * * * * cd /ruta/a/shadefinder-api && php artisan schedule:run >> /dev/null 2>&1

2. El scheduler ejecutará automáticamente la sincronización cada 6 horas

3. Verifica que el scheduler esté funcionando:

php artisan schedule:list

📡 API Endpoints

POST /api/match

Encuentra el mejor tono para un color de piel dado.

Request:

{
  "skin_color": "#F5D0C5",
  "undertone": "warm",
  "product_id": 123
}

Parameters:

• skin_color (string, required): Color hex de la piel (#RRGGBB)
• undertone (string, optional): warm, cool, o neutral
• product_id (integer, optional): ID del producto Shopify para filtrar variantes

Response:

{
  "success": true,
  "data": {
    "variant": {
      "id": 456,
      "shopify_variant_id": "gid://shopify/ProductVariant/123456789",
      "product_id": 123,
      "title": "Medium Beige",
      "sku": "FOUND-MB-01",
      "shade": {
        "id": 10,
        "name": "Medium Beige",
        "hex_color": "#F4C2A8",
        "undertone": "warm",
        "lab_l": 75.5,
        "lab_a": 12.3,
        "lab_b": 25.1
      }
    },
    "delta_e": 8.45,
    "match_quality": "Excelente",
    "ai_explanation": "Este tono es perfecto para tu piel porque..."
  }
}

Delta E Quality Ratings:

• < 10: Excelente ✅
• 10-20: Bueno 👍
• 20-30: Aceptable ⚠️
• > 30: Pobre ❌

GET /api/products

Lista todos los productos con tonos disponibles.

Response:

{
  "success": true,
  "data": [
    {
      "id": 123,
      "shopify_product_id": "gid://shopify/Product/987654321",
      "title": "Base de Maquillaje HD",
      "handle": "base-maquillaje-hd",
      "vendor": "BeautyBrand",
      "variants_count": 12
    }
  ]
}

🎨 Algoritmo de Matching

Conversión de Color

El sistema convierte colores RGB (hex) al espacio de color CIELAB:

1. RGB → XYZ: Transformación usando matriz sRGB
2. XYZ → LAB: Conversión a CIELAB con iluminante D65

// Ejemplo simplificado
$rgb = ['r' => 245, 'g' => 208, 'b' => 197];
$lab = ColorUtils::rgbToLab($rgb);
// Resultado: ['l' => 85.2, 'a' => 8.5, 'b' => 12.3]

Cálculo de Delta E (ΔE)

Usamos la fórmula CIE76 para calcular la diferencia perceptual entre colores:

ΔE = √[(L₁ - L₂)² + (a₁ - a₂)² + (b₁ - b₂)²]

Donde:

• L: Luminosidad (0-100)
• a: Eje verde-rojo
• b: Eje azul-amarillo

Filtrado por Undertone

Si se especifica undertone, el sistema:

1. Filtra variantes por undertone coincidente
2. Calcula ΔE solo para variantes filtradas
3. Selecciona la variante con menor ΔE

Generación de Explicación IA

OpenAI GPT-4o-mini genera una explicación personalizada considerando:

• Color de piel del usuario
• Undertone preferido
• Propiedades del tono recomendado
• Calidad del match (ΔE)

🛠️ Panel Administrativo

Accede a /admin/dashboard después de iniciar sesión.

Dashboard

• 📈 Estadísticas: Productos, tonos, análisis mensuales/diarios
• 🏆 Tono más recomendado: Shade con más matches
• 📊 Distribución de subtonos: Gráfico de undertones
• 📉 Análisis de 7 días: Chart de tendencias
• 📝 Últimos matches: Tabla con detalles de color y ΔE

Gestión de Productos

• ✅ Ver todos los productos sincronizados
• 🔄 Sincronizar manualmente desde Shopify
• 📝 Editar información de productos
• 🗑️ Eliminar productos

Gestión de Variantes

• 🎨 Ver variantes por producto
• 🔗 Asociar/desasociar tonos (shades)
• ✏️ Editar SKU, título, precio
• 🗑️ Eliminar variantes

Gestión de Tonos (Shades)

• ➕ Crear tonos manualmente
• 🎨 Selector de color visual
• 🔄 Sincronización automática desde metafields
• ✏️ Editar nombre, hex, undertone
• 📊 Ver valores LAB calculados automáticamente

Logs de Matches

• 📋 Historial completo de análisis
• 🔍 Filtrar por fecha, producto, calidad
• 📊 Ver ΔE y explicaciones IA
• 📈 Analytics de uso

🚀 Deployment

Opción 1: Servidor Tradicional (VPS)

1. Configurar servidor (Ubuntu/Debian):

sudo apt update
sudo apt install php8.2 php8.2-fpm php8.2-sqlite3 php8.2-xml php8.2-mbstring nginx

2. Clonar y configurar:

cd /var/www
git clone <tu-repo> shadefinder
cd shadefinder
composer install --optimize-autoloader --no-dev
npm install && npm run build

3. Configurar Nginx:

server {
    listen 80;
    server_name tu-dominio.com;
    root /var/www/shadefinder/public;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    index index.php;

    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

4. Optimizar Laravel:

php artisan config:cache
php artisan route:cache
php artisan view:cache

5. Configurar permisos:

sudo chown -R www-data:www-data /var/www/shadefinder
sudo chmod -R 755 /var/www/shadefinder/storage

6. Configurar SSL con Let's Encrypt:

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d tu-dominio.com

Opción 2: Laravel Forge

1. Conecta tu servidor VPS a Forge
2. Crea un nuevo sitio con el repositorio Git
3. Configura variables de entorno en Forge UI
4. Configura deploy script:

cd /home/forge/tu-dominio.com
git pull origin main
composer install --no-dev --optimize-autoloader
npm install && npm run build
php artisan migrate --force
php artisan config:cache
php artisan route:cache
php artisan view:cache

5. Activa SSL automático

Opción 3: Heroku

1. Crear Procfile:

web: vendor/bin/heroku-php-nginx public/

2. Deploy:

heroku create shadefinder
heroku addons:create heroku-postgresql:mini
heroku config:set APP_KEY=$(php artisan key:generate --show)
git push heroku main
heroku run php artisan migrate --force

Opción 4: Docker

1. Dockerfile (incluido en el proyecto):

FROM php:8.2-fpm
# ... configuración Docker

2. Docker Compose:

docker-compose up -d

📁 Estructura del Proyecto

shadefinder-api/
├── app/
│   ├── Console/Commands/
│   │   └── SyncShopifyProducts.php    # Comando de sincronización
│   ├── Http/
│   │   ├── Controllers/
│   │   │   ├── Admin/                 # Controladores admin
│   │   │   └── Api/                   # API endpoints
│   │   ├── Middleware/
│   │   └── Requests/
│   ├── Models/
│   │   ├── Product.php                # Modelo de productos
│   │   ├── Variant.php                # Modelo de variantes
│   │   ├── Shade.php                  # Modelo de tonos
│   │   ├── MatchLog.php               # Logs de matches
│   │   └── Setting.php                # Sistema de configuración
│   └── Services/
│       ├── ColorUtils.php             # Utilidades de color (RGB→LAB, ΔE)
│       ├── OpenAIService.php          # Integración OpenAI
│       └── ShopifyService.php         # Integración Shopify
├── config/
│   ├── services.php                   # Configuración de APIs
│   └── cors.php                       # Configuración CORS
├── database/
│   ├── migrations/                    # Migraciones de BD
│   └── database.sqlite                # Base de datos SQLite
├── public/
│   ├── widget.js                      # Widget embebible
│   └── widget-demo.html               # Demo del widget
├── resources/
│   ├── views/
│   │   ├── admin/                     # Vistas administrativas
│   │   └── layouts/                   # Layouts Blade
│   └── js/
│       └── app.js                     # JavaScript principal
├── routes/
│   ├── web.php                        # Rutas web
│   └── api.php                        # Rutas API
├── .env.example                       # Ejemplo de configuración
└── README.md                          # Este archivo

🔒 Seguridad

• ✅ Autenticación con Laravel Breeze
• ✅ CSRF Protection en formularios
• ✅ CORS configurado para widget
• ✅ Validación de requests
• ✅ Rate limiting en API
• ✅ Variables sensibles en .env
• ✅ SQL injection protection (Eloquent ORM)

🤝 Contribuciones

Las contribuciones son bienvenidas. Por favor:

1. Fork el proyecto
2. Crea una rama para tu feature (git checkout -b feature/AmazingFeature)
3. Commit tus cambios (git commit -m 'Add some AmazingFeature')
4. Push a la rama (git push origin feature/AmazingFeature)
5. Abre un Pull Request

📝 Licencia

Este proyecto está bajo la licencia MIT. Ver LICENSE para más detalles.

💡 Soporte

Si tienes preguntas o problemas:

• 📧 Email: soporte@shadefinder.com
• 🐛 Issues: GitHub Issues
• 📖 Docs: Documentación completa

🙏 Agradecimientos

• Laravel - Framework PHP
• OpenAI - API de Inteligencia Artificial
• Shopify - Plataforma de e-commerce
• Tailwind CSS - Framework CSS
• Alpine.js - Framework JavaScript

---

Hecho con ❤️ para la industria de la belleza