Importar y exportar CSV y Excel

---
name: importar-exportar-csv-excel
description: migrar datos reales sin perder acentos, decimales ni una tarde corrigiendo filas.
---

# Importar y exportar CSV y Excel

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando una
persona migre desde una hoja de cálculo o necesite sacar todos sus datos.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- El cliente ya opera en Excel, Google Sheets o un CSV de otro sistema.
- Cargar registros uno por uno haría inviable el onboarding.
- Finanzas, ventas u operaciones necesitan conciliar datos fuera de la app.
- Debes ofrecer portabilidad o una salida completa de la cuenta.

No construyas un importador genérico universal. Soporta primero una entidad y dos o tres
formatos reales de clientes, con una plantilla descargable.

## Cómo armarla

Usa **csv-parse** para CSV y **ExcelJS** para `.xlsx`. Procesa el archivo en un worker,
con una tabla temporal de filas antes de tocar las tablas del producto.

1. Publica una plantilla con encabezados, ejemplos, campos obligatorios, formatos y una
   versión. Acepta también mapeo manual de columnas para archivos existentes.
2. Detecta BOM, UTF-8, delimitador y encabezados. Si la codificación es ambigua, muestra
   una vista previa y pide confirmación; no adivines acentos rotos.
3. Conserva cada valor crudo y produce un valor normalizado aparte. Fechas `03/04/2026`,
   comas decimales, teléfonos y RFC no se convierten sin locale o regla elegida.
4. Valida por fila y por lote. Muestra antes de importar: válidas, advertencias, errores,
   nuevas, actualizaciones y posibles duplicados.
5. Define la clave de coincidencia con el usuario. Correo, RFC o folio pueden cambiar o
   repetirse; nunca elijas una heurística destructiva en silencio.
6. Importa en transacción por bloques, con `importId` y llave idempotente. Permite
   reanudar y deshacer el lote sin borrar cambios posteriores de otras personas.
7. Devuelve un archivo de errores con número de fila, columna, valor original y motivo
   accionable. “Fila inválida” no ayuda a corregir mil registros.
8. En exportación usa UTF-8, encabezados estables y zona horaria explícita. Neutraliza
   celdas que empiezan con `=`, `+`, `-` o `@` para evitar inyección de fórmulas.

## En qué te vas a trabar

- **Excel mezcla tipos dentro de una columna.** Un folio puede llegar como número, texto
  o notación científica; trata identificadores como texto desde el principio.
- **Las fechas no tienen un significado universal.** Exige formato ISO en tu plantilla y
  pide locale para archivos heredados.
- **Los archivos grandes agotan memoria y timeout.** Haz streaming de CSV, limita tamaño
  y filas, y procesa XLSX pesado fuera de la petición web.
- **La fidelidad de ida y vuelta tiene límites.** Exporta datos, no prometas conservar
  macros, fórmulas, estilos y gráficas de un libro ajeno.

## Qué NO hacer

- No insertes fila por fila directamente en producción sin vista previa ni rollback.
- No aceptes macros ni ejecutes fórmulas del archivo.
- No conviertas teléfonos, códigos postales, CLABE o folios a números.
- No ocultes filas rechazadas ni las omitas silenciosamente de la cuenta final.

## Checklist

- [ ] Existe una plantilla versionada y un mapeo manual de columnas.
- [ ] Acentos, BOM, delimitadores, comas decimales y fechas ambiguas tienen pruebas.
- [ ] La vista previa separa altas, cambios, duplicados, advertencias y errores.
- [ ] Repetir el mismo archivo no duplica registros y el lote se puede deshacer.
- [ ] El archivo de errores señala fila, columna, valor y corrección esperada.
- [ ] CSV grande se procesa en streaming y XLSX tiene límites explícitos.
- [ ] La exportación neutraliza fórmulas y conserva ids como texto.