Sio-Mobile/README.md

# SIO Mobile - Aplicacion Android para Operadores

## Drenax - Sistema Integral de Operaciones

---

## Informacion General

| Campo | Valor |
|-------|-------|
| Nombre App | SIO Drenax |
| Package ID | com.iesoluciones.siodrenax |
| Version | 1.00 (versionCode: 3) |
| Plataforma | Android |
| SDK Minimo | 28 (Android 9.0 Pie) |
| SDK Target | 33 (Android 13) |
| Lenguaje | Kotlin |

---

## Arquitectura del Sistema

```
┌─────────────────────────────────────────────────────────┐
│                    APP MOVIL                             │
│              Android (Kotlin)                            │
│           com.iesoluciones.siodrenax                     │
└─────────────────────┬───────────────────────────────────┘
                      │ HTTPS (REST API)
                      ▼
┌─────────────────────────────────────────────────────────┐
│                    BACKEND                               │
│               Laravel 5.5 (PHP 7.4)                      │
│        https://sio-api.consultoria-as.com                │
└─────────────────────────────────────────────────────────┘
```

---

## Estructura del Proyecto

```
SIO-Mobile/
├── app/
│   ├── build.gradle                    # Configuracion de compilacion
│   └── src/
│       └── main/
│           ├── AndroidManifest.xml     # Configuracion de la app
│           ├── java/com/iesoluciones/siodrenax/
│           │   ├── activities/         # Pantallas de la app
│           │   │   ├── SplashActivity.kt
│           │   │   ├── LoginActivity.kt
│           │   │   ├── WorkdayActivity.kt
│           │   │   ├── OrdersActivity.kt
│           │   │   ├── OrderDetailActivity.kt
│           │   │   ├── OrderProgressActivity.kt
│           │   │   ├── CameraActivity.kt
│           │   │   ├── SignatureActivity.kt
│           │   │   ├── SurveyActivity.kt
│           │   │   └── ConfirmationActivity.kt
│           │   ├── adapters/           # Adaptadores RecyclerView
│           │   ├── entities/           # Entidades ObjectBox (DB local)
│           │   ├── interfaces/         # Interfaces
│           │   ├── models/             # Modelos de datos
│           │   ├── network/            # Configuracion API (Retrofit)
│           │   ├── services/           # Servicios (notificaciones)
│           │   │   └── NotificationService.kt
│           │   └── utils/              # Utilidades
│           └── res/                    # Recursos
│               ├── layout/             # Layouts XML
│               ├── values/             # Strings, colors, styles
│               ├── drawable/           # Iconos e imagenes
│               └── mipmap/             # Iconos de app
├── gradle/
├── mylibrary/                          # Libreria auxiliar
├── build.gradle                        # Configuracion proyecto
├── settings.gradle
└── google-services.json                # Configuracion Firebase
```

---

## Pantallas de la Aplicacion

| Activity | Descripcion |
|----------|-------------|
| SplashActivity | Pantalla de inicio/carga |
| LoginActivity | Inicio de sesion |
| WorkdayActivity | Inicio/fin de jornada laboral |
| OrdersActivity | Lista de servicios asignados |
| OrderDetailActivity | Detalle de un servicio |
| OrderProgressActivity | Progreso del servicio |
| CameraActivity | Captura de fotografias |
| SignatureActivity | Captura de firma del cliente |
| SurveyActivity | Encuestas de satisfaccion |
| ConfirmationActivity | Confirmacion de servicio |
| NextServiceActivity | Servicios del dia siguiente |
| PdfViewerActivity | Visualizador de PDF |
| OperatorsActivity | Lista de operadores (supervisor) |
| WorkdayManagerActivity | Gestion de jornada (supervisor) |
| OrdersManagerActivity | Gestion de ordenes (supervisor) |
| HerramientaSurveyActivity | Encuesta de herramientas |
| MaterialSurveyActivity | Encuesta de materiales |
| RevisionSurveyActivity | Encuesta de revision |

---

## Flujos de la Aplicacion

### Flujo Operador

```
1. Splash Screen
   ↓
2. Login (credenciales)
   ↓
3. Checklist Vehiculo
   ↓
4. Iniciar Jornada
   ├── Seleccionar vehiculo
   ├── Registrar kilometraje inicial
   └── Capturar ubicacion GPS
   ↓
5. Ver Lista de Servicios del Dia
   ↓
6. Seleccionar Servicio
   ↓
7. Ver Detalle del Servicio
   ├── Informacion del cliente
   ├── Direccion (con mapa)
   ├── Tipo de servicio
   └── Observaciones
   ↓
8. Iniciar Servicio
   └── Registra ubicacion GPS
   ↓
9. Realizar Trabajo
   ↓
10. Capturar Evidencias
    ├── Foto antes
    ├── Foto durante
    └── Foto despues
    ↓
11. Encuestas
    ├── Herramientas utilizadas
    ├── Materiales empleados
    └── Revision general
    ↓
12. Capturar Firma del Cliente
    ↓
13. Finalizar Servicio
    ├── Registrar litraje
    └── Comentarios
    ↓
14. Siguiente Servicio o Fin de Jornada
    ├── Mas servicios → Paso 6
    └── Fin jornada → Registrar kilometraje final
```

### Flujo Supervisor

```
1. Login
   ↓
2. Iniciar Jornada Supervisor
   ↓
3. Ver Lista de Operadores
   ↓
4. Seleccionar Operador
   ↓
5. Ver Servicios del Operador
   ├── Estatus de cada servicio
   ├── Ubicacion actual
   └── Progreso del dia
   ↓
6. Monitorear en Tiempo Real
   ↓
7. Fin de Jornada
```

---

## Configuracion de API

### URLs de Conexion

```kotlin
// En app/build.gradle - buildTypes

// Produccion
buildConfigField("String", "BASE_URL", '"https://sio-api.consultoria-as.com/api/"')
buildConfigField("String", "STORAGE_URL", '"https://sio-api.consultoria-as.com/storage/"')

// Desarrollo (opcional)
buildConfigField("String", "BASE_URL", '"http://192.168.1.100:8000/api/"')
buildConfigField("String", "STORAGE_URL", '"http://192.168.1.100:8000/storage/"')
```

### Archivo de Configuracion

Ubicacion: `app/build.gradle`

```gradle
android {
    defaultConfig {
        applicationId "com.iesoluciones.siodrenax"
        minSdkVersion 28
        targetSdkVersion 33
        versionCode 3
        versionName "1.00"
    }

    buildTypes {
        debug {
            buildConfigField("String", "BASE_URL", '"https://sio-api.consultoria-as.com/api/"')
            buildConfigField("String", "STORAGE_URL", '"https://sio-api.consultoria-as.com/storage/"')
        }
        release {
            minifyEnabled false
            buildConfigField("String", "BASE_URL", '"https://sio-api.consultoria-as.com/api/"')
            buildConfigField("String", "STORAGE_URL", '"https://sio-api.consultoria-as.com/storage/"')
        }
    }
}
```

---

## API Endpoints Utilizados

### Autenticacion

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| POST | /login | Iniciar sesion |

### Operador

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /operador/checklist | Obtener checklist del vehiculo |
| GET | /operador/checklist/vehiculos | Obtener vehiculos disponibles |
| POST | /operador/checklist | Enviar checklist completado |
| POST | /operador/iniciarjornada | Iniciar jornada laboral |
| POST | /operador/finalizarjornada/{id} | Finalizar jornada |
| GET | /operador/solicitud_servicios | Obtener servicios asignados |
| GET | /operador/solicitud_servicios/{id} | Detalle de servicio |
| POST | /operador/solicitud_servicios/iniciar | Iniciar servicio |
| POST | /operador/solicitud_servicios/finalizar-new | Finalizar servicio |
| POST | /operador/solicitud_servicios/verificar/servicios | Verificar servicios |
| GET | /operador/servicios/diasiguiente | Servicios del dia siguiente |
| POST | /operador/vehiculos_incidencias | Reportar incidencia vehiculo |
| POST | /operador/vehiculos_incidencias/ultima_incidencia | Ultima incidencia |
| PUT | /operador/vehiculos_incidencias/{id}/resolver | Resolver incidencia |

### Supervisor de Operaciones

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /supervisoroperaciones/asesores | Listar operadores |
| GET | /supervisoroperaciones/asesores/{id}/servicios | Servicios de operador |
| POST | /supervisoroperaciones/iniciarjornada | Iniciar jornada supervisor |
| POST | /supervisoroperaciones/finalizarjornada/{id} | Finalizar jornada |

---

## Dependencias Principales

### Networking (Retrofit + OkHttp)

```gradle
implementation 'com.squareup.retrofit2:retrofit:2.5.0'
implementation 'com.squareup.retrofit2:converter-gson:2.4.0'
implementation 'com.squareup.retrofit2:adapter-rxjava2:2.4.0'
implementation 'com.squareup.okhttp3:logging-interceptor:3.9.1'
```

### Base de Datos Local (ObjectBox)

```gradle
implementation "io.objectbox:objectbox-kotlin:$objectboxVersion"
debugImplementation "io.objectbox:objectbox-android-objectbrowser:$objectboxVersion"
```

Permite almacenamiento offline de:
- Datos de sesion
- Servicios descargados
- Fotos pendientes de subir
- Respuestas de encuestas

### Firebase

```gradle
implementation 'com.google.firebase:firebase-messaging:22.0.0'
implementation 'com.google.firebase:firebase-crashlytics:18.2.0'
implementation 'com.google.firebase:firebase-core:19.0.0'
```

Servicios utilizados:
- **FCM:** Notificaciones push
- **Crashlytics:** Reportes de errores
- **Analytics:** Estadisticas de uso

### UI/UX

```gradle
implementation 'com.google.android.material:material:1.5.0'
implementation 'androidx.constraintlayout:constraintlayout:2.1.3'
implementation 'com.squareup.picasso:picasso:2.71828'
implementation 'com.github.bumptech.glide:glide:4.11.0'
```

### Mapas

```gradle
implementation 'com.google.android.gms:play-services-maps:18.0.2'
```

### Camara y Firma

```gradle
implementation 'io.fotoapparat:fotoapparat:2.7.0'      // Camara
implementation 'com.github.gcacace:signature-pad:1.3.1' // Firma digital
```

### PDF

```gradle
implementation 'io.github.nvest-solutions:html-to-pdf-convertor:1.0.0'
implementation 'com.github.naya-aastra:SkewPdfView:1.1'
```

---

## Permisos Requeridos

| Permiso | Uso |
|---------|-----|
| INTERNET | Conexion al API |
| CALL_PHONE | Llamar al cliente |
| FOREGROUND_SERVICE | Servicios en segundo plano |
| VIBRATE | Notificaciones |
| WAKE_LOCK | Mantener pantalla activa |
| READ_PHONE_STATE | Identificar dispositivo |
| READ_EXTERNAL_STORAGE | Leer fotos |
| WRITE_EXTERNAL_STORAGE | Guardar fotos/archivos |
| ACCESS_FINE_LOCATION | GPS preciso |
| ACCESS_COARSE_LOCATION | GPS aproximado |
| ACCESS_NOTIFICATION_POLICY | Gestionar notificaciones |
| CAMERA | Tomar fotografias |

---

## Claves y Configuracion

### Google Maps API Key

```xml
<!-- AndroidManifest.xml -->
<meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="YOUR_API_KEY_HERE"/>
```

### Firebase

Archivo de configuracion: `app/google-services.json`

**Nota:** Este archivo contiene las credenciales de Firebase y debe mantenerse privado.

---

## Compilacion

### Requisitos

- Android Studio Arctic Fox o superior
- JDK 8 o superior
- Gradle 7.x
- Android SDK 33

### Compilar Debug APK

```bash
cd SIO-Mobile
./gradlew assembleDebug
```

APK generado en: `app/build/outputs/apk/debug/app-debug.apk`

### Compilar Release APK

```bash
./gradlew assembleRelease
```

APK generado en: `app/build/outputs/apk/release/app-release.apk`

**Nota:** Para release necesitas configurar signing en `build.gradle`:

```gradle
android {
    signingConfigs {
        release {
            storeFile file("keystore.jks")
            storePassword "password"
            keyAlias "alias"
            keyPassword "password"
        }
    }
    buildTypes {
        release {
            signingConfig signingConfigs.release
        }
    }
}
```

### Instalar en Dispositivo

```bash
# Via ADB
adb install app/build/outputs/apk/debug/app-debug.apk

# O directamente desde Android Studio
# Run > Run 'app'
```

---

## Notificaciones Push (Firebase)

### Servicio

```kotlin
// com.iesoluciones.siodrenax.services.NotificationService
```

### Tipos de Notificaciones

| Tipo | Descripcion |
|------|-------------|
| Nuevo servicio | Servicio asignado al operador |
| Cambio estatus | Actualizacion de estatus de servicio |
| Recordatorio | Recordatorio de servicio proximo |
| Mensaje | Mensaje del sistema/supervisor |

### Configuracion en Backend

El token FCM se registra en el login y se actualiza automaticamente.

---

## Almacenamiento Local (ObjectBox)

### Entidades Almacenadas

```kotlin
// Sesion del usuario
@Entity
data class UserSession(
    @Id var id: Long = 0,
    var userId: Int,
    var token: String,
    var nombre: String,
    var email: String
)

// Servicio en cache
@Entity
data class CachedService(
    @Id var id: Long = 0,
    var serviceId: Int,
    var jsonData: String,
    var syncStatus: Int
)

// Evidencia pendiente
@Entity
data class PendingEvidence(
    @Id var id: Long = 0,
    var serviceId: Int,
    var photoPath: String,
    var type: String,
    var uploaded: Boolean
)
```

### Sincronizacion

La app sincroniza automaticamente cuando detecta conexion a internet:
- Sube evidencias pendientes
- Descarga servicios actualizados
- Envia encuestas completadas

---

## Troubleshooting

### App no conecta al servidor

**Causa:** URL del API incorrecta o sin HTTPS

**Solucion:**
1. Verificar `BASE_URL` en `app/build.gradle`
2. Asegurar que sea HTTPS: `https://sio-api.consultoria-as.com/api/`
3. Recompilar la app

### Error de certificado SSL

**Causa:** App configurada para HTTP, servidor usa HTTPS

**Solucion:**
1. Actualizar URLs a HTTPS
2. Verificar en `AndroidManifest.xml`:
```xml
android:usesCleartextTraffic="false"
```

### Google Maps no carga

**Causa:** API Key invalida o sin permisos

**Solucion:**
1. Verificar API Key en Google Cloud Console
2. Habilitar Maps SDK for Android
3. Agregar restriccion de paquete: `com.iesoluciones.siodrenax`

### Notificaciones no llegan

**Causa:** Token Firebase no registrado

**Solucion:**
1. Verificar `google-services.json` actualizado
2. Revisar permisos en Firebase Console
3. Verificar que el token se envie al backend en login

### Fotos no se suben

**Causa:** Conexion intermitente o timeout

**Solucion:**
1. Las fotos se guardan localmente (ObjectBox)
2. Se suben automaticamente cuando hay conexion
3. Verificar en el log si hay errores de red

### App crashea al iniciar

**Causa:** Posible corrupcion de datos locales

**Solucion:**
1. Limpiar datos de la app (Settings > Apps > SIO Drenax > Clear Data)
2. Si persiste, revisar Crashlytics para el error especifico

---

## Actualizacion de la App

### Cambiar Version

En `app/build.gradle`:

```gradle
defaultConfig {
    versionCode 4          // Incrementar para cada release
    versionName "1.01"     // Version visible al usuario
}
```

### Generar APK Firmado (Android Studio)

1. Build > Generate Signed Bundle/APK
2. Seleccionar APK
3. Usar keystore existente o crear nuevo
4. Seleccionar release
5. Generar

### Distribucion

- **Play Store:** Subir AAB (Android App Bundle)
- **Distribucion interna:** Compartir APK directamente
- **Firebase App Distribution:** Para pruebas beta

---

## Estructura de Respuestas API

### Login Exitoso

```json
{
    "success": true,
    "data": {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
        "user": {
            "id": 1,
            "nombre": "Operador 1",
            "email": "operador@mail.com",
            "tipo_empleado_id": 2
        }
    }
}
```

### Lista de Servicios

```json
{
    "success": true,
    "data": [
        {
            "id": 123,
            "cliente": "Juan Perez",
            "direccion": "Calle 123, Colonia Centro",
            "servicio": "Desazolve",
            "hora": "09:00",
            "estatus_id": 4,
            "estatus_nombre": "Pendiente"
        }
    ]
}
```

### Error

```json
{
    "success": false,
    "error": "Token expirado",
    "code": 401
}
```

---

## Tecnologias Utilizadas

- **Kotlin** - Lenguaje principal
- **Android SDK 33** - Target API
- **Retrofit** - Cliente HTTP
- **ObjectBox** - Base de datos local
- **Firebase** - Notificaciones y analytics
- **Google Maps** - Mapas y geolocalizacion
- **Fotoapparat** - Camara
- **Glide/Picasso** - Carga de imagenes
- **Material Design** - Componentes UI

---

## Contacto

| Campo | Valor |
|-------|-------|
| Sistema | SIO (Sistema Integral de Operaciones) |
| Empresa | Drenax |
| Package | com.iesoluciones.siodrenax |
| Desarrollo | IE Soluciones |
| Dominio | consultoria-as.com |

---

**Version:** 1.0
**Ultima actualizacion:** 2026-01-17