iTartanas/CHANGELOG.md

# Changelog - iTartanas

## Versión 1.0 - Implementación Completa

### 🎉 Funcionalidades Implementadas

#### ✅ Lectura NFC de Tarjeta Millennium
- **Comunicación ISO-DEP**: Implementado el protocolo completo de comunicación con tarjetas Calypso
- **Selección de red de transporte**: Comando APDU para inicializar la comunicación
- **Lectura de entorno y contrato**: Extracción de datos básicos de la tarjeta
- **Lectura de registros de eventos**: Obtención de los últimos 3 movimientos

#### 💳 Procesamiento de Datos de Tarjeta

##### Número de Tarjeta
- Decodificación BCD (Binary Coded Decimal) a decimal
- Conversión de PAN (Primary Account Number) a IEP según aplicación
- Cálculo y validación de dígito de verificación Luhn
- Enmascaramiento de primeros 8 dígitos por seguridad
- Formato visual en grupos de 4 dígitos

##### Saldo
- Lectura desde bytes 29-31 del contrato (3 bytes big-endian)
- Conversión de céntimos a euros
- Formato con 2 decimales

##### Últimos Movimientos (NUEVO)
- Lectura de registros de eventos (comando READ RECORD)
- Parseo de hasta 3 movimientos más recientes
- Extracción de información:
  - **Fecha**: Días desde 01/01/1997 (formato Calypso)
  - **Hora**: Minutos desde medianoche (convertido a HH:MM)
  - **Tipo de evento**: Carga, Validación, Operación
  - **Importe**: En euros (si aplica)
  - **Ubicación**: Línea o parada (si está disponible)

#### 🎨 Interfaz de Usuario

##### Pantalla Principal
- Diseño Material 3 con Jetpack Compose
- Tema moderno y responsivo
- Edge-to-edge UI

##### Estados de la Aplicación
1. **Estado Inicial**: Instrucciones y icono NFC
2. **Leyendo**: Indicador de progreso circular
3. **Datos Leídos**: Card con toda la información
4. **Error**: Card roja con mensaje descriptivo

##### Visualización de Datos
- **Número de tarjeta**: Tipografía destacada, parcialmente enmascarado
- **Saldo**: Display prominente en color primario, tamaño grande
- **Movimientos**: Lista compacta con diseño tipo timeline
  - Fecha y hora
  - Tipo de operación con estilo diferenciado
  - Importe con código de color (Cargas en azul, Validaciones en gris)
  - Ubicación/línea cuando está disponible

#### 🔧 Características Técnicas

##### Arquitectura
- **Patrón Repository**: Separación de lógica de negocio
- **Coroutines**: Operaciones asíncronas sin bloqueo
- **Compose State Management**: Estado reactivo de UI
- **Manejo de errores robusto**: Try-catch en múltiples niveles

##### Comandos APDU Implementados
```
SELECT Transport Network: 0x80 0x26 0x4F 0x11 0x0A
READ Environment:         0x80 0x32 0x00 0x00 0x18
READ Contract:            0x80 0x2E 0x01 0x00 0x20
READ Event Log (1-3):     0x80 0x2B 0x0N 0x05 0x1D
```

##### Seguridad y Privacidad
- ✅ Sin conexión a Internet
- ✅ Sin almacenamiento persistente
- ✅ Solo lectura (no puede modificar datos)
- ✅ Enmascaramiento de información sensible
- ✅ Validación de datos antes de mostrar

### 📋 Archivos Creados/Modificados

#### Nuevos Archivos
```
app/src/main/java/com/pjpmosteiro/itartanas/nfc/
  └── CardRepositoryImpl.kt        (270 líneas)
  
app/src/main/res/xml/
  └── nfc_tech_filter.xml

docs/
  ├── README.md
  ├── INSTALLATION_GUIDE.md
  └── CHANGELOG.md (este archivo)
```

#### Archivos Modificados
```
app/src/main/AndroidManifest.xml
  - Añadidos permisos NFC
  - Configurado intent-filter para NFC
  - Añadido launchMode="singleTop"

app/src/main/java/com/pjpmosteiro/itartanas/MainActivity.kt
  - Implementada gestión completa de NFC
  - Añadida UI de lectura de tarjeta
  - Implementado componente MovementItem
  - Gestión de estados (leyendo, éxito, error)
```

### 🛠️ Dependencias

Todas las dependencias ya estaban presentes:
- Kotlin 2.1.0
- Jetpack Compose BOM
- Material 3
- Lifecycle Runtime KTX
- Android NFC API (incluida en SDK)

### ✅ Testing y Calidad

- ✅ Build exitoso sin errores
- ✅ Código sin warnings críticos
- ✅ Uso correcto de Locale para formateo
- ✅ Manejo apropiado de excepciones
- ✅ Compatibilidad con Android 7.0+ (API 24)
- ✅ Soporte para Android 13+ (API 33) con APIs actualizadas

### 📱 Cómo Probar

1. Compilar e instalar:
   ```bash
   .\gradlew installDebug
   ```

2. Abrir la aplicación en un dispositivo con NFC

3. Acercar una Tarjeta Millennium al lector NFC

4. Verificar que se muestran:
   - Número de tarjeta enmascarado
   - Saldo actual
   - Últimos 3 movimientos con detalles

### 🎯 Objetivos Cumplidos

- ✅ Lectura de número de tarjeta
- ✅ Consulta de saldo
- ✅ Visualización de últimos movimientos (NUEVO)
- ✅ Interfaz moderna y usable
- ✅ Detección automática NFC
- ✅ Manejo robusto de errores
- ✅ Documentación completa

### 🔮 Posibles Mejoras Futuras

- Guardar historial de lecturas en base de datos local
- Gráficos de evolución de saldo
- Notificaciones de saldo bajo
- Múltiples tarjetas en una cuenta
- Exportar historial a PDF
- Widget de pantalla de inicio
- Modo oscuro/claro manual
- Soporte para otros sistemas de transporte

### 📝 Notas Técnicas

#### Formato de Fechas Calypso
Las fechas se almacenan como días transcurridos desde el 01/01/1997 (epoch Calypso).

#### Formato de Hora
Las horas se almacenan como minutos desde medianoche (0-1439).

#### Tipos de Evento
- `1`: Carga de saldo
- `2, 3`: Validación en transporte
- Otros: Operaciones diversas

#### Estructura de Registros
Cada registro de evento tiene 29 bytes útiles con la siguiente estructura aproximada:
- Bytes 0-1: Fecha (días desde epoch)
- Bytes 2-3: Hora (minutos desde medianoche)
- Byte 4: Tipo de evento
- Bytes 5-7: Importe (céntimos, big-endian)
- Bytes 8-11: Información adicional
- Bytes 10-11: Código de ubicación/línea

---

**Desarrollado por**: Pablo Mosteiro  
**Basado en**: Análisis de código decompilado de iTranvias  
**Fecha**: Marzo 2026  
**Versión**: 1.0