SKEEN-Proyecto/docs/migracion.md

# Guía de Migración — SKEEN Derma Experts

**Versión:** 2.0  
**Fecha:** 16 de julio de 2026

---

## 1. Introducción

Esta guía describe el proceso de migración de datos desde el sistema legacy de SKEEN (`https://sistema.skeenmx.app/`) hacia el nuevo sistema basado en Odoo 17.

**Importante:** La migración requiere autorización documentada del cliente. No se ha realizado extracción masiva de datos sin permiso explícito.

---

## 2. Datos a Migrar

| Entidad | Descripción | Prioridad |
|---------|-------------|-----------|
| Pacientes | Datos personales, contacto, historial médico | Alta |
| Citas | Histórico de citas, fechas, servicios | Alta |
| Servicios | Catálogo de tratamientos, precios, paquetes | Alta |
| Ventas | Histórico de ventas, pagos, adeudos | Media |
| Monedero | Puntos de fidelidad acumulados | Media |
| Inventario | Productos y consumibles | Media |
| Médicos | Personal de la clínica | Baja |

---

## 3. Formatos de Datos

### 3.1 CSV de Pacientes

```csv
name,phone,email,birthdate,gender,blood_type,allergies,address,notes
Juan Pérez,526641234567,juan@example.com,1990-01-15,male,O+,Penicilina,"Calle 123, Rosarito","Paciente frecuente"
```

**Campos:**
- `name` (required): Nombre completo
- `phone` (required): Teléfono (formato internacional sin +)
- `email`: Email
- `birthdate`: Fecha de nacimiento (YYYY-MM-DD)
- `gender`: `male`, `female`, `other`
- `blood_type`: Tipo de sangre
- `allergies`: Alergias
- `address`: Dirección
- `notes`: Notas adicionales

### 3.2 CSV de Servicios

```csv
name,code,category,price,duration_min,package_price,package_sessions,package_notes,description,service_group,color,is_favorite
Consulta Dermatologica,CONS-DERM,consulta,800,30,0,0,,Evaluación completa,Consultas,#1abc9c,true
Depilación Laser Full Body,LASER-FUL,tratamiento,2500,90,7000,3,Ahorro de $500,Depilación full body,Corporal,#e74c3c,false
```

**Campos:**
- `name` (required): Nombre del servicio
- `code` (required): Código único
- `category`: `consulta`, `tratamiento`, `procedimiento`, `paquete`
- `price` (required): Precio por sesión
- `duration_min`: Duración en minutos
- `package_price`: Precio del paquete (0 si no aplica)
- `package_sessions`: Sesiones del paquete (0 si no aplica)
- `package_notes`: Notas del paquete
- `description`: Descripción
- `service_group`: Grupo/categoría
- `color`: Color hexadecimal
- `is_favorite`: `true`/`false`

### 3.3 CSV de Inventario

```csv
name,kind,sku,category,unit,qty,qty_optimal,qty_min,cost,expiry_date,notes
Suero Vitamina C,producto,PRD-001,Skincare,pieza,24,30,5,320,2027-06-15,Suero antioxidante
Guantes Estériles,consumible,CON-003,Instrumental,caja,8,15,3,95,,Caja de 100 unidades
```

**Campos:**
- `name` (required): Nombre del item
- `kind`: `producto` o `consumible`
- `sku`: Código SKU
- `category`: Categoría
- `unit`: Unidad de medida
- `qty`: Existencia actual
- `qty_optimal`: Nivel óptimo
- `qty_min`: Stock mínimo
- `cost`: Costo unitario
- `expiry_date`: Caducidad (YYYY-MM-DD)
- `notes`: Notas

### 3.4 CSV de Citas

```csv
patient_name,patient_phone,service_code,date,time,state,notes
Juan Pérez,526641234567,CONS-DERM,2026-07-17,10:00,confirmed,Primera visita
```

### 3.5 CSV de Ventas

```csv
patient_phone,date,service_code,qty,price,payment_method,notes
526641234567,2026-07-17,CONS-DERM,1,800,cash,Pago en efectivo
```

---

## 4. Proceso de Migración

### 4.1 Preparación

1. **Obtener autorización:** Documento firmado por SKEEN autorizando la extracción.
2. **Exportar datos:** Del sistema legacy (CSV, SQL dump, o API).
3. **Limpiar datos:** Verificar formatos, eliminar duplicados.
4. **Backup:** Respaldar base de datos actual de Odoo.

### 4.2 Ejecución

```bash
# 1. Colocar CSVs en el directorio de migración
cd /root/migracion
mkdir -p datos
cp /ruta/a/csvs/* datos/

# 2. Ejecutar migración principal (pacientes, servicios, citas, ventas)
python3 importar_a_odoo.py

# 3. Importar servicios e inventario específicos
python3 importar_servicios_inventario.py \
  --servicios datos/servicios.csv \
  --inventario datos/inventario.csv \
  --purge-citas \
  --purge-sql \
  --generar-hermes

# 4. Verificar datos importados
python3 -c "
import xmlrpc.client
url='http://localhost:8069'
common=xmlrpc.client.ServerProxy(f'{url}/xmlrpc/2/common')
uid=common.authenticate('skeen_odoo','admin','skeen_admin_2026',{})
models=xmlrpc.client.ServerProxy(f'{url}/xmlrpc/2/object')
for m in ['res.partner','skeen.servicio','skeen.cita','skeen.inventario.item']:
    n=models.execute_kw('skeen_odoo',uid,'skeen_admin_2026',m,'search_count',[[]])
    print(m,n)
"
```

### 4.3 Validación

1. **Conteo de registros:** Comparar totales origen vs destino.
2. **Muestra aleatoria:** Verificar 10-20 registros manualmente.
3. **Pruebas funcionales:** Agendar cita, consultar saldo, redimir puntos.
4. **Reporte de errores:** Documentar registros que fallaron.

---

## 5. Scripts de Migración

### 5.1 `importar_a_odoo.py`

Script principal de migración. Importa:

- Pacientes (res.partner)
- Servicios (skeen.servicio)
- Citas (skeen.cita)
- Ventas (skeen.venta)
- Pagos (skeen.pago)
- Monederos (skeen.monedero)

**Uso:**
```bash
python3 importar_a_odoo.py
```

### 5.2 `importar_servicios_inventario.py`

Script especializado para servicios e inventario.

**Uso:**
```bash
python3 importar_servicios_inventario.py \
  --servicios servicios.csv \
  --inventario inventario.csv \
  [--purge-citas] \
  [--purge-sql] \
  [--generar-hermes]
```

**Opciones:**
- `--purge-citas`: Eliminar citas existentes antes de importar
- `--purge-sql`: Usar TRUNCATE SQL para limpieza rápida
- `--generar-hermes`: Generar catálogo JSON para skills de Hermes

### 5.3 `extraer_skeen.py`

Script de extracción del sistema legacy. Requiere credenciales y autorización.

**Nota:** Este script está disponible pero no se ha ejecutado por restricciones de autorización.

---

## 6. Limpieza de Datos Demo

Antes de migrar datos reales, se recomienda limpiar datos demo:

```bash
cd /root/migracion

# Opción 1: Script de borrado
python3 borrar_datos_demo.py

# Opción 2: SQL directo (más rápido)
python3 importar_servicios_inventario.py --purge-citas --purge-sql --servicios /dev/null --inventario /dev/null
```

---

## 7. Sincronización Post-Migración

Después de la migración, es necesario sincronizar con WACRM:

```bash
# Desde el frontend o vía API
curl -X POST http://localhost:8069/skeen/frontend/v1/wacrm/sync \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"sync_contacts":true,"sync_conversations":true,"sync_messages":true,"sync_deals":true}'
```

---

## 8. Regeneración del Catálogo Hermes

Después de importar servicios, regenerar el catálogo para Hermes:

```bash
cd /root/migracion
python3 importar_servicios_inventario.py --solo-hermes
```

Esto actualiza:
- `/root/.hermes/skills/skeen-services.json`
- `/root/skeen-roadmap-hermes/hermes/skills/skeen-services.json`

---

## 9. Problemas Comunes

### 9.1 Registros duplicados

**Problema:** Al re-ejecutar la migración, se crean duplicados.

**Solución:** Usar `--purge-citas --purge-sql` antes de importar.

### 9.2 Timeout en importación masiva

**Problema:** Miles de registros tardan demasiado.

**Solución:** Usar `--purge-sql` para limpieza rápida, y considerar dividir en lotes.

### 9.3 Campos faltantes en CSV

**Problema:** Algunos CSVs no tienen todos los campos.

**Solución:** Los scripts tienen valores por defecto. Revisar los warnings en la salida.

### 9.4 Teléfonos con formato incorrecto

**Problema:** Números de teléfono con formato local.

**Solución:** Normalizar a formato internacional sin `+` (ej. `526641234567`).

---

## 10. Checklist de Migración

- [ ] Autorización documentada del cliente
- [ ] Exportación de datos del sistema legacy
- [ ] Backup de base de datos Odoo actual
- [ ] Limpieza de datos demo
- [ ] Ejecución de scripts de migración
- [ ] Validación de conteos
- [ ] Validación de muestra aleatoria
- [ ] Pruebas funcionales
- [ ] Sincronización WACRM
- [ ] Regeneración catálogo Hermes
- [ ] Reporte de errores y resolución
- [ ] Aprobación final del cliente

---

## 11. Contacto

Para dudas sobre migración:
- **Email:** ialcarazsalazar@consultoria-as.com
- **Gitea:** https://git.consultoria-as.com/consultoria-as/SKEEN-Proyecto