# Migración de colecciones legacy (Fase 5 / Etapa 2 / sub-fase 1, fix #2)

Script: `scripts/migrate_legacy_collections.py`.

## Contexto

Al cerrar el fix #2 de la sub-fase 1 (categorías reales) se confirmó vía
Store API (2026-08-24) que los 17 productos legacy ya tenían la
`category` real correcta asignada desde una migración anterior, pero
**ningún producto tenía `collection` asignada** — el campo estaba en
`null` en los 27 productos existentes en ese momento (17 legacy + 1
Cybertron Sentinel + 9 demo). Sólo 2 colecciones existían en Medusa:
"Universo Marvel" y "Reino de Frozen" (creadas en la auditoría de
Etapa 1). Este script cierra esa brecha.

De paso asigna la categoría "Figuras de accion" a
`cybertron-sentinel-figura-de-coleccion-test-revalidate`, el único de
los 18 productos pre-existentes (no-demo) que quedó sin categoría en
la migración anterior — no es uno de los "17 legacy", es el producto
usado para validar el flujo de auto-refresh en el incidente Fase 4.

**Fuera de alcance, por decisión explícita del usuario:** `metadata`
(brand/ageRange), precios, descripciones, imágenes. Solo
`categories`/`collection_id`.

## Mapeo aplicado

| Colección | Nueva/existente | Productos (handle) |
|---|---|---|
| Toy Story | nueva | toy-story-5-rex, toy-story-5-buzz-lightyear, toy-story-5-jessie, toy-story-5-woody |
| Intensamente | nueva | intensamente-furia, intensamente-tristeza |
| Lilo & Stitch | nueva | angel-lilo-y-stitch |
| Universo Marvel | existente (`pcol_01M0PDFBDA0TXQNCX4E2AP8DJ5`) | mochilas-disney-coleccion-marvel, mochila-escolar-de-spider-man-..., disney-mochila-iron-man-..., mochila-de-disney-marvel-capitan-america-... |
| Reino de Frozen | existente (`pcol_01M0PDFBX1PT3ZA4KHJE6C9VKT`) | mochila-ligera-...-frozen-... |
| — (sin colección, por mapeo explícito del usuario) | — | minnie-y-mickey-mouse, mochila-pequena-bob-esponja, mochila-casual-...-bob-esponja-..., disney-mochila-de-poliester-..., mochila-escolar-estilo-britanico-... |

Categoría faltante: `cybertron-sentinel-figura-de-coleccion-test-revalidate`
→ "Figuras de accion" (`pcat_01M0PDF24BRVRKKMPMXCTY7QXJ`).

Las 17 categorías legacy en sí **no se tocan** — se verificaron 1:1
contra el mapeo del usuario antes de correr este script y ya
coincidían exactamente (ver memoria del proyecto
`project_fase5_etapa2_subfase1_categorias_2026_08_23.md`).

## Endpoints Admin API (Medusa v2) usados

- `GET /admin/collections?title=X` — chequear si una colección ya existe.
- `POST /admin/collections` — crear colección (`title`, `handle`).
- `POST /admin/collections/:id/products` con body `{"add": [...], "remove": []}` — asignar productos a una colección.
- `POST /admin/product-categories/:id/products` con body `{"add": [...], "remove": []}` — asignar productos a una categoría (mismo patrón confirmado en el fix #2 de categorías).

Confirmado que **no existen** en esta versión de Medusa:
`POST /admin/products/:id/categories` (404), ni `collection_id`/`category_ids`
en el body de `PATCH /admin/products/:id` (400).

## Cómo correrlo

Requiere un JWT de admin (`ADMIN_JWT`) obtenido vía
`POST /auth/user/emailpass` — no se persiste en este repo. El
bloqueo del clasificador de auto-mode sobre escrituras en lote contra
producción aplica aquí igual que en el fix #2 de categorías (ver
memoria `feedback_auto_mode_classifier_hard_blocks`), así que el
`--apply` lo corre el usuario directamente, no Claude:

```bash
export MEDUSA_BACKEND_URL=https://commerce.cruzcloud.net
export ADMIN_JWT=<token>

# 1. Verificar el plan sin escribir nada
python3 scripts/migrate_legacy_collections.py --dry-run

# 2. Ejecutar
python3 scripts/migrate_legacy_collections.py --apply
```

## Rollback

Cada asignación es aditiva (`add`) sobre relaciones many-to-many, no
destructiva de datos previos. Para revertir, llamar los mismos
endpoints con `{"remove": [...ids], "add": []}` con los mismos
product_id/collection_id/category_id documentados arriba. Las
colecciones creadas ("Toy Story", "Intensamente", "Lilo & Stitch")
se pueden borrar con `DELETE /admin/collections/:id` si hace falta
deshacer la migración por completo.