# Guía de Instalación y Uso - iTartanas

## 📱 Instalación

### Opción 1: Desde Android Studio

1. Abre el proyecto en Android Studio
2. Conecta tu dispositivo Android via USB o usa un emulador con soporte NFC
3. Haz clic en el botón "Run" (▶️) o presiona `Shift + F10`
4. Selecciona tu dispositivo y espera a que se instale

### Opción 2: Compilar APK

```bash
# Desde la terminal en la raíz del proyecto
.\gradlew assembleDebug

# El APK se generará en:
# app\build\outputs\apk\debug\app-debug.apk
```

Luego puedes transferir el APK a tu dispositivo Android e instalarlo manualmente.

## ✅ Requisitos del Dispositivo

- **Android 7.0 (API 24) o superior**
- **Hardware NFC** (obligatorio)
- **NFC activado** en la configuración del dispositivo

### Cómo activar NFC:

1. Ve a **Configuración** → **Conexiones** (o **Dispositivos conectados**)
2. Busca la opción **NFC**
3. Activa el interruptor NFC
4. También puedes activar **Android Beam** si está disponible

## 📖 Cómo usar la aplicación

### Paso 1: Abrir la aplicación

Abre iTartanas desde el cajón de aplicaciones. Verás una pantalla con el mensaje:

```
"Acerca tu Tarjeta Millennium al lector NFC"
```

### Paso 2: Acercar la tarjeta

1. Mantén tu **Tarjeta Millennium** cerca del lector NFC de tu dispositivo
2. El lector NFC suele estar en la parte trasera del teléfono, cerca de la cámara
3. Mantén la tarjeta estable durante 1-2 segundos

### Paso 3: Ver los resultados

La aplicación mostrará automáticamente:

- ✅ **Número de Tarjeta**: En formato enmascarado (ej: `**** **** 1234 5678`)
- 💰 **Saldo**: En euros con dos decimales (ej: `12.50 €`)
- 📋 **Últimos Movimientos**: Los últimos 3 movimientos con:
  - Fecha y hora de la operación
  - Tipo de operación (Carga, Validación, etc.)
  - Importe (cuando aplica)
  - Ubicación o línea (si está disponible)

## 🔍 Ubicación del lector NFC

La ubicación del lector NFC varía según el dispositivo:

- **Samsung**: Parte trasera central o superior
- **Google Pixel**: Parte trasera central
- **Xiaomi**: Parte trasera central o superior
- **OnePlus**: Parte trasera cerca de la cámara

💡 **Tip**: Puedes buscar en Internet "ubicación NFC [modelo de tu teléfono]" para encontrar la posición exacta.

## ⚠️ Solución de problemas

### La aplicación no detecta la tarjeta

**Problema**: Al acercar la tarjeta no pasa nada.

**Soluciones**:
1. Verifica que el NFC esté activado en tu dispositivo
2. Asegúrate de acercar la tarjeta a la zona correcta del lector NFC
3. Mantén la tarjeta estable durante al menos 2 segundos
4. Retira cualquier funda metálica o magnética del teléfono
5. Reinicia la aplicación

### Error: "Este dispositivo no tiene NFC"

**Problema**: Tu dispositivo no tiene hardware NFC.

**Solución**: Lamentablemente, necesitas un dispositivo con NFC para usar esta aplicación. Consulta las especificaciones de tu dispositivo.

### Error al leer la tarjeta

**Problema**: La aplicación detecta la tarjeta pero muestra un error.

**Soluciones**:
1. Intenta acercar la tarjeta de nuevo
2. Limpia suavemente la tarjeta con un paño seco
3. Asegúrate de que estás usando una Tarjeta Millennium válida
4. Verifica que la tarjeta no esté dañada
5. Intenta en una zona con menos interferencias electromagnéticas

### "Por favor, activa el NFC en configuración"

**Problema**: El NFC está desactivado.

**Solución**: Ve a Configuración → Conexiones → NFC y actívalo.

## 📊 Información mostrada

### Número de Tarjeta
- Formato: 16 dígitos en grupos de 4
- Los primeros 8 dígitos están enmascarados con asteriscos (*)
- Ejemplo: `**** **** 1234 5678`

### Saldo
- Formato: Euros con 2 decimales
- Ejemplo: `15.75 €`
- Se obtiene directamente del chip de la tarjeta

### Últimos Movimientos
- Se muestran los últimos 3 movimientos registrados
- Cada movimiento incluye:
  - **Fecha y hora**: Formato `DD/MM/YYYY HH:MM`
  - **Tipo de operación**: Carga, Validación u Operación
  - **Importe**: Si aplica, en formato `X.XX €`
  - **Ubicación**: Información de línea o parada si está disponible
- Los importes de carga se muestran en color primario
- Las validaciones y otros movimientos en color secundario

## 🔒 Privacidad y Seguridad

- ✅ La aplicación **NO** envía datos a Internet
- ✅ **NO** guarda información de tu tarjeta
- ✅ Solo lee los datos visibles en el chip NFC
- ✅ No puede modificar el saldo ni los datos de la tarjeta
- ✅ El número de tarjeta se enmascara parcialmente por seguridad

## 🛠️ Desarrollo

### Compilar desde código fuente

```bash
# Clonar el repositorio (si aplica)
git clone [URL_del_repositorio]
cd iTartanas

# Compilar
.\gradlew build

# Ejecutar tests
.\gradlew test

# Instalar en dispositivo conectado
.\gradlew installDebug
```

### Dependencias principales

- Kotlin 2.1.0
- Jetpack Compose BOM
- Material 3
- Lifecycle Runtime KTX
- Android NFC API

## 📞 Soporte

Si encuentras algún problema o tienes sugerencias, por favor:

1. Verifica que tu tarjeta Millennium sea compatible
2. Asegúrate de tener la última versión de la aplicación
3. Revisa la sección de solución de problemas de este documento

## 📝 Notas adicionales

- La aplicación solo funciona con **Tarjetas Millennium** del sistema de transporte público
- No funcionará con otras tarjetas NFC (tarjetas bancarias, pases de acceso, etc.)
- La lectura es de solo lectura, no puede modificar el saldo
- Los datos se leen en tiempo real desde el chip de la tarjeta

---

**Versión**: 1.0  
**Última actualización**: Marzo 2026

