datatools-dev/docs/USER-GUIDE.es.md

> 🌐 **Idioma:** Español · [English](USER-GUIDE.md)

# Guía del usuario

**Versión**: 1.6 · **Actualizado**: 2026-05-13

## 0. Primer arranque — activación

DataTools debe activarse antes de desbloquear cualquier herramienta. En el primer arranque verás la pantalla **Activar**.

Introduce tu nombre completo y correo, pega el código de licencia del correo de compra (empieza con `DTLIC1:`) y pulsa **Activar**. La renovación funciona igual: pega el código de renovación y pulsa **Aplicar renovación**.

**Niveles**:

| Nivel | Herramientas |
|---|---|
| **Lite** | Buscar duplicados · Limpiar texto · Estandarizar formatos |
| **Core** | Las 9 herramientas |

Un usuario Lite que abra una herramienta exclusiva de Core verá un mensaje "Actualiza tu licencia". La página de inicio también muestra una marca 🔒 Bloqueado en las tarjetas de las herramientas que tu nivel no incluye. Para actualizar, pega un código Core en la página Activar.

Cada licencia dura 1 año. La barra lateral muestra tu nivel y los días restantes en todo momento; aparece un aviso de renovación 30 días antes de la caducidad. El archivo de licencia vive en `~/.datatools/license.json` (Windows: `C:\Users\<tú>\.datatools\license.json`).

Para usar la misma licencia en otro equipo: desactiva éste (página Activar → **Desactivar este dispositivo**) y vuelve a pegar tu código en el nuevo.

## 1. Instalación

No necesitas tener Python ni permisos de administrador — el paquete trae su propio intérprete y todas las dependencias. Dos formatos por sistema operativo, elige el que tu política de TI permita:

- **Instalador** — crea automáticamente acceso directo en el escritorio + entrada en el menú Inicio / Launchpad. Recomendado para la mayoría.
- **.zip portable** — descomprime y haz doble clic. No toca el registro, se ejecuta desde cualquier lugar (escritorio, USB, recurso de red). Úsalo si no puedes ejecutar instaladores, quieres una instalación de una sola carpeta que puedas copiar entre equipos, o estás evaluando antes de instalar.

Ambos formatos son idénticos por dentro: mismo Python, mismas dependencias, mismo comportamiento de arranque.

### 1.1 Windows

**Opción A — Instalador (`DataTools-<ver>-win-setup.exe`)**

1. Descarga `DataTools-<ver>-win-setup.exe` desde tu correo de licencia o GitHub Releases.
2. Doble clic en el instalador. La primera vez, Windows SmartScreen mostrará **"Windows protegió tu PC"** — pulsa **Más información** → **Ejecutar de todas formas**. (Este aviso solo aparece una vez por compilación hasta que tengamos un certificado EV de firma de código.)
3. Acepta la ruta de instalación por usuario (`%LOCALAPPDATA%\Programs\DataTools` por defecto — no pide UAC). Marca **Crear acceso directo en el escritorio** si lo quieres (activado por defecto).
4. Pulsa **Instalar** y luego **Finalizar**. El instalador te ofrece lanzar DataTools al terminar.
5. A partir de ahora ejecútalo desde: **Menú Inicio → DataTools**, el **acceso directo del escritorio**, o escribiendo `DataTools` en Ejecutar (Win+R) / cmd.

Para anclarlo a la barra de tareas, lanza la app una vez, clic derecho en su icono de la barra de tareas, y **Anclar a la barra de tareas**. Windows requiere este paso manual — ningún instalador puede anclar por programa.

**Opción B — Portable (`DataTools-<ver>-win-portable.zip`)**

1. Descarga `DataTools-<ver>-win-portable.zip`.
2. Clic derecho en el .zip → **Extraer todo…** → elige una carpeta (p. ej. `C:\Tools\DataTools`).
3. Abre la carpeta `DataTools\` extraída, doble clic en `DataTools.exe`. El aviso de SmartScreen aparece solo la primera vez.
4. Para crear tu propio acceso directo en el escritorio: clic derecho en `DataTools.exe` → **Enviar a → Escritorio (crear acceso directo)**.

**Desinstalar** (solo instalador): Configuración → Aplicaciones → DataTools → Desinstalar. Portable: borra la carpeta.

### 1.2 macOS

**Opción A — DMG instalador (`DataTools-<ver>-mac.dmg`)**

1. Descarga `DataTools-<ver>-mac.dmg`.
2. Doble clic en el .dmg. Se abre una ventana de Finder con el icono **DataTools** y un alias **Aplicaciones**.
3. Arrastra **DataTools** sobre **Aplicaciones**. Espera a que termine la copia y expulsa el DMG.
4. En compilaciones sin firma, el primer arranque muestra **"No se puede abrir 'DataTools' porque no se puede verificar al desarrollador"**. Solución: clic derecho en DataTools en /Aplicaciones → **Abrir** → confirma **Abrir** en el diálogo. macOS recuerda la elección — los siguientes arranques no muestran nada.
5. Ejecútalo desde **Launchpad**, **Spotlight** (`⌘ Espacio` → escribe "DataTools"), o **Aplicaciones** en Finder.

Para mantener DataTools en el Dock: lanza la app, clic derecho en su icono del Dock → **Opciones → Mantener en el Dock**. macOS no permite que los instaladores fijen al Dock automáticamente.

**Opción B — Portable (`DataTools-<ver>-mac-portable.zip`)**

1. Descarga `DataTools-<ver>-mac-portable.zip`. Safari descomprime al descargar por defecto; en Finder verás `DataTools.app` directamente.
2. Mueve `DataTools.app` a **Aplicaciones** si quieres que aparezca en Launchpad — o déjalo en el escritorio, un USB o un recurso de red. La .app portable se ejecuta desde cualquier sitio.
3. Doble clic en `DataTools.app`. Clic derecho → **Abrir** la primera vez (misma rutina que con el DMG).

**Desinstalar**: arrastra `DataTools.app` a la Papelera. Tus archivos de datos siguen donde estén — la app no instala nada más.

### 1.3 Linux

`DataTools-<ver>-linux-x86_64.AppImage` ya es portable — no hay .zip aparte.

1. Descarga el .AppImage.
2. `chmod +x DataTools-*.AppImage`.
3. Doble clic, o ejecútalo desde la terminal.

Si tu distro no incluye FUSE 2: `sudo apt install libfuse2` (Debian/Ubuntu) o equivalente.

### 1.4 Qué pasa al arrancar por primera vez

El lanzador (llamado `DataTools.exe` / `DataTools.app` / `DataTools.AppImage`) hace tres cosas, en orden:

1. Elige un puerto TCP libre en `127.0.0.1` — normalmente el 8501; si está ocupado prueba 8502, 8503, …
2. Arranca un servidor Streamlit local en ese puerto. El servidor solo está enlazado a localhost, nunca a tu red.
3. Abre tu navegador predeterminado en `http://127.0.0.1:<puerto>/`. Si el navegador no se abre en 5 segundos, pega esa URL manualmente.

La ventana del lanzador queda abierta en segundo plano. Cerrarla detiene el servidor — la pestaña del navegador dirá "no se puede acceder a este sitio" la próxima vez.

### 1.5 Cómo funciona la GUI

- Se ejecuta localmente en tu equipo. **Sin internet, sin subidas.**
- El navegador es solo la capa de visualización. Cerrarlo NO detiene la app — cierra la ventana del lanzador (o sal de la .app de macOS desde el Dock) para terminar del todo.
- ¿Prefieres la terminal? Cada herramienta incluye también una CLI — ver Sección 3.

### 1.6 Requisitos del sistema

- Windows 10/11 (64 bits), macOS 11+, Linux moderno (2020+).
- Navegador moderno (Chrome, Edge, Firefox, Safari, últimos 3 años).
- ~400 MB de espacio libre en disco (el paquete ocupa ~200 MB; el resto es espacio de trabajo para CSV grandes).

Matriz de soporte completa: [REQUIREMENTS.md](REQUIREMENTS.md) (solo en inglés).

## 2. Qué incluye

| # | Herramienta | Propósito | Estado |
|---|------|---------|--------|
| 01 | Buscar duplicados | Coincidencia exacta + difusa, 5 normalizadores, auditoría | Listo |
| 02 | Limpiar texto | Espacios, caracteres tipográficos, BOM, finales de línea, mayúsculas/minúsculas | Listo |
| 03 | Estandarizar formatos | Fechas / teléfonos / correos / direcciones / nombres / monedas / booleanos | Listo |
| 04 | Corregir valores faltantes | Nulos disfrazados, imputación, descarte por umbral | Próximamente |
| 05 | Mapear columnas | Renombrar + aplicar esquema | Próximamente |
| 06 | Detectar valores atípicos | z-score, IQR, multivariante | Próximamente |
| 07 | Combinar archivos | Combina varios archivos | Próximamente |
| 08 | Verificación de calidad | Reglas + informe PDF/Excel | Próximamente |
| 09 | Flujos automatizados | Lanzador multi-herramienta de un clic | Próximamente |

**Datos de muestra** (`samples/`): `messy_sales.csv`, `bank_export.xlsx`.

## 3. Uso

### 3.1 GUI (recomendada)

1. Inicia el paquete.
2. Selecciona una herramienta en la barra lateral.
3. Suelta tu archivo (o elige una muestra).
4. Los valores por defecto están preconfigurados — pulsa **Ejecutar** para previsualizar.
5. Pulsa **Guardar salida** para escribir el archivo limpio.

Las opciones avanzadas se encuentran en paneles desplegables. El archivo original nunca se modifica.

### 3.2 CLI

```bash
deduplicator       customers.csv [--apply]
text-cleaner       messy.csv     [--apply]
format-standardize feed.csv      [--apply]
```

Ayuda: `deduplicator --help`. Referencia completa: [CLI-REFERENCE.es.md](CLI-REFERENCE.es.md).

### 3.3 Orden de ejecución (cuando uses las herramientas manualmente)

Si no usas Flujos automatizados, sigue este orden:

1. **02 Limpiar texto** primero — normaliza espacios y caracteres especiales.
2. **03 Estandarizar formatos** — fechas, teléfonos, etc. necesitan texto limpio.
3. **04 Corregir valores faltantes** — códigos centinela se ocultan como números.
4. **05 Mapear columnas** — esquema antes que estadísticas de atípicos.
5. **06 Detectar valores atípicos** — necesita datos numéricos limpios. Calcular estadísticas con `NaN` o `-999` envenena los resultados.
6. **07 Combinar archivos**, **08 Verificación de calidad** según sea necesario.
7. **01 Buscar duplicados** es flexible en cuanto al orden (normaliza internamente para la coincidencia).

Flujos automatizados aplica este orden automáticamente.

### 3.4 Idioma

La barra lateral tiene un selector **Language / Idioma**. Se incluyen dos paquetes hoy:

- **English** (por defecto)
- **Español**

Elige el idioma una vez — la opción persiste durante la sesión y el selector es visible desde cualquier página. Cambia cuando quieras; la página se vuelve a renderizar en su sitio sin perder datos.

**Cobertura** (v1.6): página de inicio, tarjetas de herramientas, panel de carga y análisis, lista de hallazgos, indicador de la verificación de normalización CSV, selector lateral y pantalla de cierre. Los cuerpos de cada página de herramienta (etiquetas de opciones avanzadas, indicaciones del mapeador de columnas, etiquetas de revisión de duplicados) están planificados para paquetes futuros — actualmente se muestran en inglés en ambos modos. Si una cadena que esperabas ver traducida no cambia, se trata de una clave de paquete pendiente, no de un fallo del selector; escribe a soporte adjuntando una captura.

## 4. Verificación de Revisar y Normalizar

Cada archivo subido se analiza antes de que cualquier herramienta lo toque.

**Niveles de confianza**:
- **Alta** — seguras de ida y vuelta. El botón "Corregir automáticamente lo de alta confianza" las aplica todas con un clic.
- **Media** — normalmente correctas, con falsos positivos ocasionales. Previsualiza primero.
- **Baja** — heurística. Desactivada por defecto; opt-in por hallazgo.
- **Error** — bloquea la verificación (archivo vacío, U+FFFD, filas no reparables).

**Sustitución de codificación**: cuando el detector reporta `encoding_uncertain` o detectas mojibake (`é`) o caracteres `<60>`, elige el codepage correcto en la parte superior de la página (cp1252 para Excel occidental, KOI8-R para ruso antiguo, Big5 para chino tradicional, …) → **Re-analizar**.

**Salida avanzada**: un desplegable `⚙️` en la descarga te permite ajustar la codificación, el delimitador y el terminador de línea. El nombre del archivo descargado se ajusta automáticamente (`.tsv` para tabulador, `.csv` en los demás casos).

## 5. Salida

Cada ejecución escribe:
- **Archivo limpio** junto al original (o donde indiques).
- **Archivo de auditoría** (cambios celda por celda en herramientas de texto/formato, grupos de coincidencia en deduplicación).
- **Registro con marca de tiempo** en `logs/`.

El archivo original nunca se modifica.

## 6. Solución de problemas

- **La GUI no se abre / el navegador no se inicia** — espera 10-15 s; visita manualmente `http://127.0.0.1:8501` (o el puerto que muestre la ventana del lanzador). Error de puerto ocupado → cierra otras instancias. El lanzador recorre los puertos 8501–8550 buscando uno libre, así que una instancia colgada puede desplazar la URL.
- **¿Por qué se abre el navegador?** — patrón de aplicación web local (igual que Jupyter o RStudio). Nada sale de tu equipo.
- **Windows SmartScreen** — pulsa "Más información" → "Ejecutar de todas formas". Una sola vez por compilación hasta que tengamos un certificado EV.
- **macOS "La aplicación está dañada" / "no se puede verificar al desarrollador"** — clic derecho en la app → **Abrir** → confirma. Si el mensaje persiste, el archivo se corrompió en tránsito — vuelve a descargarlo. Último recurso: `xattr -cr /Applications/DataTools.app` limpia el atributo de cuarentena.
- **macOS — el .zip portable extraído no abre** — Safari descomprime al descargar; si ves una carpeta `__MACOSX/` o archivos `._DataTools.app` usaste otro descompresor. Vuelve a extraer con la Utilidad de Archivo integrada (clic derecho en el .zip → **Abrir con → Utilidad de Archivo**) para preservar los metadatos de la .app.
- **Windows — el antivirus pone en cuarentena `DataTools.exe` del portable** — tu antivirus no reconoce el paquete. Añade la carpeta extraída a la lista blanca. El instalador .exe activa menos antivirus porque es un envoltorio Inno Setup conocido.
- **El AppImage de Linux no se ejecuta** — `chmod +x archivo.AppImage`. Si falta FUSE → `sudo apt install libfuse2`.
- **Lento con archivos grandes** — por encima de ~100k filas tarda más; la barra de progreso lo indica. Para millones de filas → usa la CLI directamente.
- **¿Dónde guarda la app mi licencia / configuración?** — `~/.datatools/` en macOS y Linux, `C:\Users\<tú>\.datatools\` en Windows. Tus archivos de entrada y salida siguen donde los dejes; la app nunca los copia a otro sitio.
- **Necesito ayuda** — escribe al correo que aparece en tu recibo de compra.

## 7. Licencia

Usuario único. Consulta `LICENSE.txt`.