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:

   .\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