F2.2: identificar health de API

F2.2: contrato seguro de autenticación Android

.github/workflows/android.yml

@@ -0,0 +1,59 @@
+name: Android APK
+
+on:
+  push:
+    branches:
+      - feature/f2-2-android-v2
+    paths:
+      - 'android-app/**'
+      - '.github/workflows/android.yml'
+  pull_request:
+    paths:
+      - 'android-app/**'
+      - 'api-v3/src/auth/**'
+      - '.github/workflows/android.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build-debug-apk:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Java 17
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '17'
+
+      - name: Android SDK
+        uses: android-actions/setup-android@v3
+
+      - name: Android API 36
+        run: sdkmanager 'platforms;android-36' 'build-tools;36.0.0'
+
+      - name: Gradle 8.13
+        uses: gradle/actions/setup-gradle@v4
+        with:
+          gradle-version: '8.13'
+
+      - name: Assemble debug
+        working-directory: android-app
+        run: gradle --no-daemon :app:assembleDebug
+
+      - name: Unit tests
+        working-directory: android-app
+        run: gradle --no-daemon :app:testDebugUnitTest
+
+      - name: Upload APK
+        uses: actions/upload-artifact@v4
+        with:
+          name: DH-Inspeccion-F2.2-0.10.0-debug
+          path: android-app/app/build/outputs/apk/debug/app-debug.apk
+          if-no-files-found: error
+          retention-days: 14

.github/workflows/f2-2-ci.yml

@@ -0,0 +1,52 @@
+name: F2.2 Integration CI
+
+on:
+  push:
+    branches:
+      - feature/f2-2-android-v2
+    paths:
+      - 'api-v3/**'
+      - 'web-v2/**'
+      - 'scripts/**'
+      - 'docker-compose.yml'
+      - '.github/workflows/f2-2-ci.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  api:
+    name: API · typecheck, tests, build
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: api-v3
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          cache: npm
+          cache-dependency-path: api-v3/package-lock.json
+      - run: npm ci
+      - run: npm run typecheck
+      - run: npm test
+      - run: npm run build
+
+  web:
+    name: WEB · typecheck, build
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: web-v2
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          cache: npm
+          cache-dependency-path: web-v2/package-lock.json
+      - run: npm ci
+      - run: npm run typecheck
+      - run: npm run build

android-app/app/build.gradle.kts

@@ -0,0 +1,77 @@
+plugins {
+    id("com.android.application")
+    id("org.jetbrains.kotlin.android")
+    id("org.jetbrains.kotlin.plugin.compose")
+}
+
+android {
+    namespace = "com.korexlabs.dhinspeccion"
+    compileSdk = 36
+
+    defaultConfig {
+        applicationId = "com.korexlabs.dhinspeccion"
+        minSdk = 26
+        targetSdk = 36
+        versionCode = 14
+        versionName = "0.10.0"
+
+        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
+        vectorDrawables.useSupportLibrary = true
+        buildConfigField("String", "API_BASE_URL", "\"https://dhv2.korexlabs.com/api/v3/\"")
+    }
+
+    buildTypes {
+        debug {
+            applicationIdSuffix = ".debug"
+            versionNameSuffix = "-debug"
+        }
+        release {
+            isMinifyEnabled = false
+            proguardFiles(
+                getDefaultProguardFile("proguard-android-optimize.txt"),
+                "proguard-rules.pro",
+            )
+            // La firma de release NO se redefine aquí. Se conservará la clave histórica.
+        }
+    }
+
+    buildFeatures {
+        compose = true
+        buildConfig = true
+    }
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+    kotlinOptions.jvmTarget = "17"
+
+    packaging.resources.excludes += "/META-INF/{AL2.0,LGPL2.1}"
+}
+
+dependencies {
+    val composeBom = platform("androidx.compose:compose-bom:2025.08.01")
+    implementation(composeBom)
+    androidTestImplementation(composeBom)
+
+    implementation("androidx.core:core-ktx:1.17.0")
+    implementation("androidx.activity:activity-compose:1.10.1")
+    implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.9.2")
+    implementation("androidx.lifecycle:lifecycle-viewmodel-compose:2.9.2")
+    implementation("androidx.compose.material3:material3")
+    implementation("androidx.compose.ui:ui")
+    implementation("androidx.compose.ui:ui-tooling-preview")
+    debugImplementation("androidx.compose.ui:ui-tooling")
+
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.10.2")
+    implementation("com.squareup.retrofit2:retrofit:2.11.0")
+    implementation("com.squareup.retrofit2:converter-moshi:2.11.0")
+    implementation("com.squareup.moshi:moshi-kotlin:1.15.2")
+    implementation("com.squareup.okhttp3:okhttp:4.12.0")
+    implementation("com.google.android.gms:play-services-location:21.3.0")
+    implementation("androidx.exifinterface:exifinterface:1.4.1")
+
+    testImplementation("junit:junit:4.13.2")
+    androidTestImplementation("androidx.test.ext:junit:1.2.1")
+    androidTestImplementation("androidx.test.espresso:espresso-core:3.6.1")
+}

android-app/app/proguard-rules.pro

@@ -0,0 +1 @@
+# DH Inspección V2. Las reglas se ampliarán cuando se habilite minificación de release.

android-app/app/src/main/AndroidManifest.xml

@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+    <uses-permission android:name="android.permission.CAMERA" />
+    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
+
+    <application
+        android:allowBackup="false"
+        android:label="@string/app_name"
+        android:supportsRtl="true"
+        android:theme="@style/Theme.DHInspeccion"
+        android:usesCleartextTraffic="false">
+        <activity
+            android:name=".MainActivity"
+            android:exported="true">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+        </activity>
+
+        <provider
+            android:name="androidx.core.content.FileProvider"
+            android:authorities="${applicationId}.files"
+            android:exported="false"
+            android:grantUriPermissions="true">
+            <meta-data
+                android:name="android.support.FILE_PROVIDER_PATHS"
+                android:resource="@xml/file_paths" />
+        </provider>
+    </application>
+</manifest>

android-app/app/src/main/java/com/korexlabs/dhinspeccion/MainActivity.kt

@@ -0,0 +1,19 @@
+package com.korexlabs.dhinspeccion
+
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.activity.enableEdgeToEdge
+import androidx.lifecycle.viewmodel.compose.viewModel
+import com.korexlabs.dhinspeccion.ui.DhApp
+
+class MainActivity : ComponentActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        enableEdgeToEdge()
+        setContent {
+            val model: MainViewModel = viewModel()
+            DhApp(model)
+        }
+    }
+}

android-app/app/src/main/java/com/korexlabs/dhinspeccion/MainViewModel.kt

@@ -0,0 +1,209 @@
+package com.korexlabs.dhinspeccion
+
+import android.app.Application
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.setValue
+import androidx.lifecycle.AndroidViewModel
+import androidx.lifecycle.viewModelScope
+import com.korexlabs.dhinspeccion.data.CreateFieldInventoryRequest
+import com.korexlabs.dhinspeccion.data.DhRepository
+import com.korexlabs.dhinspeccion.data.FieldAssetDetail
+import com.korexlabs.dhinspeccion.data.FieldInventoryItem
+import com.korexlabs.dhinspeccion.data.FieldType
+import com.korexlabs.dhinspeccion.data.StoredSession
+import com.korexlabs.dhinspeccion.data.VisitDetail
+import com.korexlabs.dhinspeccion.data.VisitSummary
+import kotlinx.coroutines.launch
+import java.io.File
+import java.time.Instant
+
+class MainViewModel(application: Application) : AndroidViewModel(application) {
+    private val repository = DhRepository(application)
+
+    var session: StoredSession? by mutableStateOf(repository.currentSession())
+        private set
+    var busy by mutableStateOf(false)
+        private set
+    var error: String? by mutableStateOf(null)
+        private set
+    var notice: String? by mutableStateOf(null)
+        private set
+
+    var visits: List<VisitSummary> by mutableStateOf(emptyList())
+        private set
+    var visit: VisitDetail? by mutableStateOf(null)
+        private set
+
+    var inventory: List<FieldInventoryItem> by mutableStateOf(emptyList())
+        private set
+    var fieldTypes: List<FieldType> by mutableStateOf(emptyList())
+        private set
+    var selectedFieldAsset: FieldAssetDetail? by mutableStateOf(null)
+        private set
+
+    init {
+        if (session != null) loadVisits()
+    }
+
+    fun clearMessages() {
+        error = null
+        notice = null
+    }
+
+    fun login(identifier: String, password: String) {
+        if (identifier.isBlank() || password.isBlank()) {
+            error = "Ingresá usuario y contraseña."
+            return
+        }
+        launchBusy {
+            session = repository.login(identifier, password)
+            notice = "Sesión iniciada."
+            loadVisitsInternal()
+        }
+    }
+
+    fun logout() {
+        viewModelScope.launch {
+            runCatching { repository.logout() }
+            session = null
+            visits = emptyList()
+            visit = null
+            inventory = emptyList()
+            fieldTypes = emptyList()
+            selectedFieldAsset = null
+        }
+    }
+
+    fun loadVisits() = launchBusy { loadVisitsInternal() }
+
+    private suspend fun loadVisitsInternal() {
+        visits = repository.visits().data
+    }
+
+    fun openVisit(id: String) = launchBusy {
+        visit = repository.visit(id)
+        inventory = emptyList()
+        fieldTypes = emptyList()
+        selectedFieldAsset = null
+    }
+
+    fun closeVisitView() {
+        visit = null
+        inventory = emptyList()
+        fieldTypes = emptyList()
+        selectedFieldAsset = null
+        loadVisits()
+    }
+
+    fun startVisit() {
+        val id = visit?.id ?: return
+        launchBusy {
+            visit = repository.startVisit(id)
+            notice = "Inspección iniciada."
+            loadVisitsInternal()
+        }
+    }
+
+    fun searchInventory(search: String, parentId: String? = null) {
+        val id = visit?.id ?: return
+        launchBusy {
+            inventory = repository.fieldInventory(id, search, parentId).data
+        }
+    }
+
+    fun loadFieldTypes(parentId: String? = null) {
+        val id = visit?.id ?: return
+        launchBusy {
+            fieldTypes = repository.fieldTypes(id, parentId).data
+        }
+    }
+
+    fun selectExisting(item: FieldInventoryItem) {
+        val visitId = visit?.id ?: return
+        launchBusy {
+            selectedFieldAsset = repository.selectFieldAsset(visitId, item.id)
+            notice = "Inventario agregado a la inspección."
+            inventory = repository.fieldInventory(visitId, null, null).data
+        }
+    }
+
+    fun createFieldAsset(
+        type: FieldType,
+        parentId: String?,
+        name: String,
+        commonName: String?,
+        attributes: Map<String, Any?>,
+        latitude: Double,
+        longitude: Double,
+        accuracyM: Double?,
+    ) {
+        val visitId = visit?.id ?: return
+        if (visit?.status != "IN_PROGRESS") {
+            error = "La inspección debe estar en curso para dar de alta Inventario."
+            return
+        }
+        launchBusy {
+            val request = CreateFieldInventoryRequest(
+                typeId = type.id,
+                parentId = parentId,
+                name = name.trim(),
+                commonName = commonName?.trim()?.takeIf { it.isNotBlank() },
+                attributes = attributes,
+                deviceLatitude = latitude,
+                deviceLongitude = longitude,
+                deviceAccuracyM = accuracyM,
+                deviceCapturedAt = Instant.now().toString(),
+            )
+            selectedFieldAsset = repository.createFieldAsset(visitId, request)
+            notice = "Inventario creado con GPS. Falta la fotografía obligatoria."
+            inventory = repository.fieldInventory(visitId, null, null).data
+        }
+    }
+
+    fun uploadFieldPhoto(
+        file: File,
+        latitude: Double,
+        longitude: Double,
+        accuracyM: Double?,
+    ) {
+        val visitId = visit?.id ?: return
+        val asset = selectedFieldAsset?.asset ?: return
+        launchBusy {
+            val response = repository.uploadFieldPhoto(
+                visitId = visitId,
+                assetId = asset.id,
+                file = file,
+                latitude = latitude,
+                longitude = longitude,
+                accuracyM = accuracyM,
+            )
+            selectedFieldAsset = selectedFieldAsset?.copy(capture = response.capture)
+            notice = if (response.capture.readyForFinding) {
+                "Captura completa: GPS y fotografía registrados."
+            } else {
+                "Fotografía registrada."
+            }
+            inventory = repository.fieldInventory(visitId, null, null).data
+        }
+    }
+
+    fun clearSelectedFieldAsset() {
+        selectedFieldAsset = null
+    }
+
+    private fun launchBusy(block: suspend () -> Unit) {
+        viewModelScope.launch {
+            busy = true
+            error = null
+            try {
+                block()
+            } catch (throwable: Throwable) {
+                error = DhRepository.humanError(throwable)
+                if (repository.currentSession() == null) session = null
+            } finally {
+                busy = false
+            }
+        }
+    }
+}

android-app/app/src/main/java/com/korexlabs/dhinspeccion/data/DhMobile.kt

@@ -0,0 +1,531 @@
+package com.korexlabs.dhinspeccion.data
+
+import android.content.Context
+import android.security.keystore.KeyGenParameterSpec
+import android.security.keystore.KeyProperties
+import android.util.Base64
+import com.korexlabs.dhinspeccion.BuildConfig
+import com.squareup.moshi.Moshi
+import com.squareup.moshi.kotlin.reflect.KotlinJsonAdapterFactory
+import kotlinx.coroutines.sync.Mutex
+import kotlinx.coroutines.sync.withLock
+import okhttp3.MediaType.Companion.toMediaType
+import okhttp3.MultipartBody
+import okhttp3.OkHttpClient
+import okhttp3.RequestBody.Companion.asRequestBody
+import okhttp3.RequestBody.Companion.toRequestBody
+import org.json.JSONObject
+import retrofit2.HttpException
+import retrofit2.Retrofit
+import retrofit2.converter.moshi.MoshiConverterFactory
+import retrofit2.http.Body
+import retrofit2.http.GET
+import retrofit2.http.Header
+import retrofit2.http.Multipart
+import retrofit2.http.POST
+import retrofit2.http.Part
+import retrofit2.http.Path
+import retrofit2.http.Query
+import java.io.File
+import java.security.KeyStore
+import java.time.Instant
+import java.util.UUID
+import javax.crypto.Cipher
+import javax.crypto.KeyGenerator
+import javax.crypto.SecretKey
+import javax.crypto.spec.GCMParameterSpec
+
+// ---------- Auth ----------
+
+data class LoginRequest(
+    val identifier: String,
+    val password: String,
+    val deviceLabel: String = "DH Android",
+)
+
+data class RefreshRequest(val refreshToken: String)
+
+data class MobileUser(
+    val id: String,
+    val username: String,
+    val firstName: String? = null,
+    val lastName: String? = null,
+    val email: String? = null,
+    val mustChangePassword: Boolean = false,
+    val roles: List<String> = emptyList(),
+    val permissions: List<String> = emptyList(),
+)
+
+data class MobileSessionResponse(
+    val user: MobileUser,
+    val accessToken: String,
+    val refreshToken: String,
+    val accessExpiresInSeconds: Long,
+)
+
+data class StoredSession(
+    val userId: String,
+    val username: String,
+    val displayName: String,
+    val accessToken: String,
+    val refreshToken: String,
+)
+
+// ---------- Inspections ----------
+
+data class AssetSummary(
+    val id: String,
+    val code: String,
+    val name: String,
+    val typeName: String? = null,
+)
+
+data class PersonSummary(
+    val id: String,
+    val username: String? = null,
+    val firstName: String? = null,
+    val lastName: String? = null,
+)
+
+data class VisitSummary(
+    val id: String,
+    val code: String,
+    val title: String? = null,
+    val objective: String? = null,
+    val status: String,
+    val scopeAsset: AssetSummary? = null,
+    val operationalArea: AssetSummary? = null,
+    val operatorCompany: AssetSummary? = null,
+    val leadInspector: PersonSummary? = null,
+    val plannedStartAt: String? = null,
+    val actualStartedAt: String? = null,
+    val actualClosedAt: String? = null,
+    val instructions: String? = null,
+    val checklistGeneration: Int = 0,
+    val assetCount: Int = 0,
+    val memberCount: Int = 0,
+)
+
+data class VisitMeta(
+    val page: Int,
+    val pageSize: Int,
+    val total: Int,
+    val totalPages: Int,
+)
+
+data class VisitListResponse(val data: List<VisitSummary>, val meta: VisitMeta)
+
+data class PlannedAsset(
+    val id: String,
+    val code: String,
+    val name: String,
+    val typeName: String? = null,
+    val included: Boolean = true,
+    val planningSource: String? = null,
+    val exclusionReason: String? = null,
+)
+
+data class ChecklistItem(
+    val id: String,
+    val findingId: String? = null,
+    val findingCode: String? = null,
+    val findingTitle: String? = null,
+    val findingStatus: String? = null,
+    val severity: Int? = null,
+    val itemKind: String? = null,
+    val referenceOn: String? = null,
+    val asset: AssetSummary? = null,
+    val assetIncluded: Boolean = true,
+)
+
+data class ChecklistSummary(
+    val generation: Int = 0,
+    val stale: Boolean = false,
+    val antecedents: Int = 0,
+    val companyOverdue: Int = 0,
+    val verificationOverdue: Int = 0,
+    val upcomingControls: Int = 0,
+    val actionableAssets: Int = 0,
+    val excludedAssets: Int = 0,
+    val items: List<ChecklistItem> = emptyList(),
+)
+
+data class VisitDetail(
+    val id: String,
+    val code: String,
+    val title: String? = null,
+    val objective: String? = null,
+    val status: String,
+    val operationalArea: AssetSummary? = null,
+    val operatorCompany: AssetSummary? = null,
+    val leadInspector: PersonSummary? = null,
+    val plannedStartAt: String? = null,
+    val actualStartedAt: String? = null,
+    val actualClosedAt: String? = null,
+    val instructions: String? = null,
+    val assets: List<AssetSummary> = emptyList(),
+    val planningAssets: List<PlannedAsset> = emptyList(),
+    val team: List<PersonSummary> = emptyList(),
+    val checklist: ChecklistSummary = ChecklistSummary(),
+)
+
+// ---------- Field inventory ----------
+
+data class FieldContext(
+    val visitId: String? = null,
+    val visitCode: String? = null,
+    val areaId: String? = null,
+    val areaCode: String? = null,
+    val areaName: String? = null,
+    val companyId: String? = null,
+    val companyCode: String? = null,
+    val companyName: String? = null,
+)
+
+data class FieldInventoryItem(
+    val id: String,
+    val code: String,
+    val name: String,
+    val commonName: String? = null,
+    val informationStatus: String? = null,
+    val dataOrigin: String? = null,
+    val type: AssetSummary? = null,
+    val parent: AssetSummary? = null,
+    val selectedInInspection: Boolean = false,
+    val captureRequired: Boolean = false,
+    val hasGeometry: Boolean = false,
+    val fieldPhotoCount: Int = 0,
+    val readyForFinding: Boolean = true,
+)
+
+data class FieldInventoryListResponse(
+    val context: FieldContext,
+    val data: List<FieldInventoryItem>,
+)
+
+data class FieldAttributeDefinition(
+    val id: String,
+    val code: String,
+    val name: String,
+    val dataType: String,
+    val isRequired: Boolean = false,
+    val unit: String? = null,
+    val options: Any? = null,
+    val sortOrder: Int = 0,
+)
+
+data class FieldType(
+    val id: String,
+    val code: String,
+    val name: String,
+    val description: String? = null,
+    val attributes: List<FieldAttributeDefinition> = emptyList(),
+)
+
+data class FieldTypeResponse(
+    val context: FieldContext,
+    val parent: AssetSummary,
+    val data: List<FieldType>,
+)
+
+data class CaptureStatus(
+    val captureRequired: Boolean = false,
+    val hasGeometry: Boolean = false,
+    val creationGpsCaptured: Boolean = false,
+    val fieldPhotoCount: Int = 0,
+    val readyForFinding: Boolean = true,
+)
+
+data class FieldAssetDetail(
+    val context: FieldContext? = null,
+    val asset: FieldInventoryItem,
+    val selectedInInspection: Boolean = true,
+    val capture: CaptureStatus = CaptureStatus(),
+)
+
+data class CreateFieldInventoryRequest(
+    val typeId: String,
+    val parentId: String? = null,
+    val code: String? = null,
+    val name: String,
+    val commonName: String? = null,
+    val description: String? = null,
+    val discoveryNotes: String? = null,
+    val attributes: Map<String, Any?>,
+    val deviceLatitude: Double,
+    val deviceLongitude: Double,
+    val deviceAccuracyM: Double? = null,
+    val deviceCapturedAt: String,
+    val deviceLabel: String = "DH Android",
+)
+
+data class FieldPhotoResponse(
+    val capture: CaptureStatus,
+)
+
+interface DhApi {
+    @POST("auth/mobile/login")
+    suspend fun login(@Body request: LoginRequest): MobileSessionResponse
+
+    @POST("auth/mobile/refresh")
+    suspend fun refresh(@Body request: RefreshRequest): MobileSessionResponse
+
+    @POST("auth/mobile/logout")
+    suspend fun logout(@Header("Authorization") authorization: String): Map<String, Any?>
+
+    @GET("inspection-visits")
+    suspend fun visits(
+        @Header("Authorization") authorization: String,
+        @Query("inspectorId") inspectorId: String,
+        @Query("pageSize") pageSize: Int = 100,
+    ): VisitListResponse
+
+    @GET("inspection-visits/{id}")
+    suspend fun visit(
+        @Header("Authorization") authorization: String,
+        @Path("id") id: String,
+    ): VisitDetail
+
+    @POST("inspection-visits/{id}/start")
+    suspend fun startVisit(
+        @Header("Authorization") authorization: String,
+        @Path("id") id: String,
+    ): VisitDetail
+
+    @GET("inspection-visits/{visitId}/field-inventory")
+    suspend fun fieldInventory(
+        @Header("Authorization") authorization: String,
+        @Path("visitId") visitId: String,
+        @Query("search") search: String? = null,
+        @Query("parentId") parentId: String? = null,
+        @Query("limit") limit: Int = 80,
+    ): FieldInventoryListResponse
+
+    @GET("inspection-visits/{visitId}/field-inventory/types")
+    suspend fun fieldTypes(
+        @Header("Authorization") authorization: String,
+        @Path("visitId") visitId: String,
+        @Query("parentId") parentId: String? = null,
+    ): FieldTypeResponse
+
+    @POST("inspection-visits/{visitId}/field-inventory/{assetId}/select")
+    suspend fun selectFieldAsset(
+        @Header("Authorization") authorization: String,
+        @Path("visitId") visitId: String,
+        @Path("assetId") assetId: String,
+    ): FieldAssetDetail
+
+    @POST("inspection-visits/{visitId}/field-inventory")
+    suspend fun createFieldAsset(
+        @Header("Authorization") authorization: String,
+        @Path("visitId") visitId: String,
+        @Body request: CreateFieldInventoryRequest,
+    ): FieldAssetDetail
+
+    @Multipart
+    @POST("inspection-visits/{visitId}/field-inventory/{assetId}/photos")
+    suspend fun uploadFieldPhoto(
+        @Header("Authorization") authorization: String,
+        @Path("visitId") visitId: String,
+        @Path("assetId") assetId: String,
+        @Part file: MultipartBody.Part,
+        @Part("deviceLatitude") latitude: okhttp3.RequestBody,
+        @Part("deviceLongitude") longitude: okhttp3.RequestBody,
+        @Part("deviceAccuracyM") accuracy: okhttp3.RequestBody?,
+        @Part("deviceCapturedAt") capturedAt: okhttp3.RequestBody,
+        @Part("deviceLabel") deviceLabel: okhttp3.RequestBody,
+        @Part("exifLatitude") exifLatitude: okhttp3.RequestBody?,
+        @Part("exifLongitude") exifLongitude: okhttp3.RequestBody?,
+        @Part("exifCapturedAt") exifCapturedAt: okhttp3.RequestBody?,
+    ): FieldPhotoResponse
+}
+
+class SecureSessionStore(context: Context) {
+    private val prefs = context.getSharedPreferences("dh_v2_mobile_session", Context.MODE_PRIVATE)
+    private val alias = "dh_v2_mobile_session_key"
+
+    fun load(): StoredSession? {
+        val encoded = prefs.getString("payload", null) ?: return null
+        return runCatching {
+            val parts = encoded.split('.', limit = 2)
+            require(parts.size == 2)
+            val iv = Base64.decode(parts[0], Base64.NO_WRAP)
+            val encrypted = Base64.decode(parts[1], Base64.NO_WRAP)
+            val cipher = Cipher.getInstance("AES/GCM/NoPadding")
+            cipher.init(Cipher.DECRYPT_MODE, key(), GCMParameterSpec(128, iv))
+            val json = JSONObject(String(cipher.doFinal(encrypted), Charsets.UTF_8))
+            StoredSession(
+                userId = json.getString("userId"),
+                username = json.getString("username"),
+                displayName = json.optString("displayName", json.getString("username")),
+                accessToken = json.getString("accessToken"),
+                refreshToken = json.getString("refreshToken"),
+            )
+        }.getOrElse {
+            clear()
+            null
+        }
+    }
+
+    fun save(response: MobileSessionResponse): StoredSession {
+        val displayName = listOfNotNull(response.user.firstName, response.user.lastName)
+            .joinToString(" ").trim().ifBlank { response.user.username }
+        val stored = StoredSession(
+            userId = response.user.id,
+            username = response.user.username,
+            displayName = displayName,
+            accessToken = response.accessToken,
+            refreshToken = response.refreshToken,
+        )
+        val json = JSONObject()
+            .put("userId", stored.userId)
+            .put("username", stored.username)
+            .put("displayName", stored.displayName)
+            .put("accessToken", stored.accessToken)
+            .put("refreshToken", stored.refreshToken)
+            .toString()
+        val cipher = Cipher.getInstance("AES/GCM/NoPadding")
+        cipher.init(Cipher.ENCRYPT_MODE, key())
+        val encrypted = cipher.doFinal(json.toByteArray(Charsets.UTF_8))
+        val payload = Base64.encodeToString(cipher.iv, Base64.NO_WRAP) + "." +
+            Base64.encodeToString(encrypted, Base64.NO_WRAP)
+        prefs.edit().putString("payload", payload).apply()
+        return stored
+    }
+
+    fun clear() {
+        prefs.edit().clear().apply()
+    }
+
+    private fun key(): SecretKey {
+        val keyStore = KeyStore.getInstance("AndroidKeyStore").apply { load(null) }
+        (keyStore.getKey(alias, null) as? SecretKey)?.let { return it }
+        val generator = KeyGenerator.getInstance(KeyProperties.KEY_ALGORITHM_AES, "AndroidKeyStore")
+        generator.init(
+            KeyGenParameterSpec.Builder(
+                alias,
+                KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT,
+            )
+                .setBlockModes(KeyProperties.BLOCK_MODE_GCM)
+                .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
+                .setRandomizedEncryptionRequired(true)
+                .build(),
+        )
+        return generator.generateKey()
+    }
+}
+
+class DhRepository(context: Context) {
+    private val store = SecureSessionStore(context.applicationContext)
+    private val refreshMutex = Mutex()
+    private val moshi = Moshi.Builder().addLast(KotlinJsonAdapterFactory()).build()
+    private val api: DhApi = Retrofit.Builder()
+        .baseUrl(BuildConfig.API_BASE_URL)
+        .client(OkHttpClient.Builder().build())
+        .addConverterFactory(MoshiConverterFactory.create(moshi))
+        .build()
+        .create(DhApi::class.java)
+
+    fun currentSession(): StoredSession? = store.load()
+
+    suspend fun login(identifier: String, password: String): StoredSession =
+        store.save(api.login(LoginRequest(identifier.trim(), password)))
+
+    suspend fun logout() {
+        val session = store.load()
+        if (session != null) runCatching { api.logout("Bearer ${session.accessToken}") }
+        store.clear()
+    }
+
+    suspend fun visits(): VisitListResponse = authorized { session ->
+        api.visits("Bearer ${session.accessToken}", session.userId)
+    }
+
+    suspend fun visit(id: String): VisitDetail = authorized { session ->
+        api.visit("Bearer ${session.accessToken}", id)
+    }
+
+    suspend fun startVisit(id: String): VisitDetail = authorized { session ->
+        api.startVisit("Bearer ${session.accessToken}", id)
+    }
+
+    suspend fun fieldInventory(visitId: String, search: String?, parentId: String? = null) = authorized { session ->
+        api.fieldInventory("Bearer ${session.accessToken}", visitId, search?.takeIf { it.isNotBlank() }, parentId)
+    }
+
+    suspend fun fieldTypes(visitId: String, parentId: String?) = authorized { session ->
+        api.fieldTypes("Bearer ${session.accessToken}", visitId, parentId)
+    }
+
+    suspend fun selectFieldAsset(visitId: String, assetId: String) = authorized { session ->
+        api.selectFieldAsset("Bearer ${session.accessToken}", visitId, assetId)
+    }
+
+    suspend fun createFieldAsset(visitId: String, request: CreateFieldInventoryRequest) = authorized { session ->
+        api.createFieldAsset("Bearer ${session.accessToken}", visitId, request)
+    }
+
+    suspend fun uploadFieldPhoto(
+        visitId: String,
+        assetId: String,
+        file: File,
+        latitude: Double,
+        longitude: Double,
+        accuracyM: Double?,
+        capturedAt: String = Instant.now().toString(),
+    ): FieldPhotoResponse = authorized { session ->
+        val text = "text/plain".toMediaType()
+        val body = file.asRequestBody("image/jpeg".toMediaType())
+        val part = MultipartBody.Part.createFormData("file", file.name, body)
+        api.uploadFieldPhoto(
+            authorization = "Bearer ${session.accessToken}",
+            visitId = visitId,
+            assetId = assetId,
+            file = part,
+            latitude = latitude.toString().toRequestBody(text),
+            longitude = longitude.toString().toRequestBody(text),
+            accuracy = accuracyM?.toString()?.toRequestBody(text),
+            capturedAt = capturedAt.toRequestBody(text),
+            deviceLabel = "DH Android".toRequestBody(text),
+            exifLatitude = latitude.toString().toRequestBody(text),
+            exifLongitude = longitude.toString().toRequestBody(text),
+            exifCapturedAt = capturedAt.toRequestBody(text),
+        )
+    }
+
+    private suspend fun <T> authorized(block: suspend (StoredSession) -> T): T {
+        var session = store.load() ?: throw IllegalStateException("Sesión no iniciada")
+        try {
+            return block(session)
+        } catch (error: HttpException) {
+            if (error.code() != 401) throw error
+        }
+        session = refresh(session.refreshToken)
+        return block(session)
+    }
+
+    private suspend fun refresh(previousRefreshToken: String): StoredSession = refreshMutex.withLock {
+        val latest = store.load() ?: throw IllegalStateException("Sesión no iniciada")
+        if (latest.refreshToken != previousRefreshToken) return@withLock latest
+        try {
+            store.save(api.refresh(RefreshRequest(previousRefreshToken)))
+        } catch (error: Throwable) {
+            store.clear()
+            throw error
+        }
+    }
+
+    companion object {
+        fun humanError(error: Throwable): String {
+            if (error is HttpException) {
+                val body = runCatching { error.response()?.errorBody()?.string() }.getOrNull()
+                val message = runCatching { JSONObject(body.orEmpty()).optString("message") }.getOrNull()
+                if (!message.isNullOrBlank()) return message
+                return "Error HTTP ${error.code()}"
+            }
+            return error.message ?: "Ocurrió un error inesperado"
+        }
+
+        fun newOperationId(): String = UUID.randomUUID().toString()
+    }
+}

android-app/app/src/main/java/com/korexlabs/dhinspeccion/ui/DhApp.kt

@@ -0,0 +1,579 @@
+package com.korexlabs.dhinspeccion.ui
+
+import android.Manifest
+import android.content.Context
+import android.content.pm.PackageManager
+import android.net.Uri
+import android.os.Environment
+import androidx.activity.compose.rememberLauncherForActivityResult
+import androidx.activity.result.contract.ActivityResultContracts
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.width
+import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.foundation.lazy.LazyRow
+import androidx.compose.foundation.lazy.items
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.text.KeyboardOptions
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.material3.AssistChip
+import androidx.compose.material3.Button
+import androidx.compose.material3.Card
+import androidx.compose.material3.CardDefaults
+import androidx.compose.material3.CircularProgressIndicator
+import androidx.compose.material3.HorizontalDivider
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.OutlinedButton
+import androidx.compose.material3.OutlinedTextField
+import androidx.compose.material3.Surface
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateMapOf
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.saveable.rememberSaveable
+import androidx.compose.runtime.setValue
+import androidx.compose.runtime.rememberCoroutineScope
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.platform.LocalContext
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.text.input.KeyboardType
+import androidx.compose.ui.text.input.PasswordVisualTransformation
+import androidx.compose.ui.unit.dp
+import androidx.core.content.ContextCompat
+import androidx.core.content.FileProvider
+import androidx.exifinterface.media.ExifInterface
+import com.google.android.gms.location.LocationServices
+import com.google.android.gms.location.Priority
+import com.google.android.gms.tasks.CancellationTokenSource
+import com.korexlabs.dhinspeccion.MainViewModel
+import com.korexlabs.dhinspeccion.data.FieldAttributeDefinition
+import com.korexlabs.dhinspeccion.data.FieldInventoryItem
+import com.korexlabs.dhinspeccion.data.FieldType
+import com.korexlabs.dhinspeccion.data.VisitDetail
+import com.korexlabs.dhinspeccion.data.VisitSummary
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.suspendCancellableCoroutine
+import java.io.File
+import java.time.Instant
+import java.time.ZoneId
+import java.time.format.DateTimeFormatter
+import kotlin.coroutines.resume
+import kotlin.coroutines.resumeWithException
+
+private data class GeoSnapshot(
+    val latitude: Double,
+    val longitude: Double,
+    val accuracyM: Double?,
+)
+
+@Composable
+fun DhApp(model: MainViewModel) {
+    MaterialTheme {
+        Surface(modifier = Modifier.fillMaxSize()) {
+            when {
+                model.session == null -> LoginScreen(model)
+                model.visit == null -> VisitsScreen(model)
+                else -> VisitRouter(model)
+            }
+        }
+    }
+}
+
+@Composable
+private fun MessageStrip(model: MainViewModel) {
+    val error = model.error
+    val notice = model.notice
+    if (error != null || notice != null) {
+        Card(
+            modifier = Modifier.fillMaxWidth().padding(bottom = 12.dp),
+            colors = CardDefaults.cardColors(
+                containerColor = if (error != null) MaterialTheme.colorScheme.errorContainer
+                else MaterialTheme.colorScheme.secondaryContainer,
+            ),
+            onClick = { model.clearMessages() },
+        ) {
+            Text(
+                text = error ?: notice.orEmpty(),
+                modifier = Modifier.padding(12.dp),
+            )
+        }
+    }
+}
+
+@Composable
+private fun LoginScreen(model: MainViewModel) {
+    var identifier by rememberSaveable { mutableStateOf("") }
+    var password by rememberSaveable { mutableStateOf("") }
+
+    Box(Modifier.fillMaxSize().padding(24.dp), contentAlignment = Alignment.Center) {
+        Column(Modifier.fillMaxWidth(), verticalArrangement = Arrangement.spacedBy(14.dp)) {
+            Text("DH Inspección", style = MaterialTheme.typography.headlineMedium, fontWeight = FontWeight.Bold)
+            Text("Aplicación de campo · Dirección de Hidrocarburos")
+            MessageStrip(model)
+            OutlinedTextField(
+                value = identifier,
+                onValueChange = { identifier = it },
+                label = { Text("Usuario o email") },
+                modifier = Modifier.fillMaxWidth(),
+                singleLine = true,
+            )
+            OutlinedTextField(
+                value = password,
+                onValueChange = { password = it },
+                label = { Text("Contraseña") },
+                modifier = Modifier.fillMaxWidth(),
+                singleLine = true,
+                visualTransformation = PasswordVisualTransformation(),
+            )
+            Button(
+                onClick = { model.login(identifier, password) },
+                modifier = Modifier.fillMaxWidth(),
+                enabled = !model.busy,
+            ) {
+                if (model.busy) CircularProgressIndicator(modifier = Modifier.width(20.dp).height(20.dp))
+                else Text("Ingresar")
+            }
+            Text(
+                "El acceso móvil está reservado a usuarios con rol Inspector.",
+                style = MaterialTheme.typography.bodySmall,
+            )
+        }
+    }
+}
+
+@Composable
+private fun VisitsScreen(model: MainViewModel) {
+    val session = model.session ?: return
+    Column(Modifier.fillMaxSize().padding(top = 28.dp)) {
+        Row(
+            Modifier.fillMaxWidth().padding(horizontal = 16.dp, vertical = 10.dp),
+            verticalAlignment = Alignment.CenterVertically,
+            horizontalArrangement = Arrangement.SpaceBetween,
+        ) {
+            Column {
+                Text("Mis inspecciones", style = MaterialTheme.typography.headlineSmall, fontWeight = FontWeight.Bold)
+                Text(session.displayName, style = MaterialTheme.typography.bodySmall)
+            }
+            Row {
+                OutlinedButton(onClick = { model.loadVisits() }, enabled = !model.busy) { Text("Actualizar") }
+                Spacer(Modifier.width(8.dp))
+                OutlinedButton(onClick = { model.logout() }) { Text("Salir") }
+            }
+        }
+        Column(Modifier.padding(horizontal = 16.dp)) { MessageStrip(model) }
+        if (model.busy && model.visits.isEmpty()) {
+            Box(Modifier.fillMaxSize(), contentAlignment = Alignment.Center) { CircularProgressIndicator() }
+        } else if (model.visits.isEmpty()) {
+            Box(Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
+                Text("No tenés inspecciones asignadas.")
+            }
+        } else {
+            LazyColumn(
+                Modifier.fillMaxSize().padding(horizontal = 16.dp),
+                verticalArrangement = Arrangement.spacedBy(10.dp),
+            ) {
+                items(model.visits, key = { it.id }) { visit ->
+                    VisitCard(visit) { model.openVisit(visit.id) }
+                }
+                item { Spacer(Modifier.height(24.dp)) }
+            }
+        }
+    }
+}
+
+@Composable
+private fun VisitCard(visit: VisitSummary, onOpen: () -> Unit) {
+    Card(onClick = onOpen, modifier = Modifier.fillMaxWidth()) {
+        Column(Modifier.padding(14.dp), verticalArrangement = Arrangement.spacedBy(5.dp)) {
+            Row(Modifier.fillMaxWidth(), horizontalArrangement = Arrangement.SpaceBetween) {
+                Text(visit.code, fontWeight = FontWeight.Bold)
+                Text(visit.status)
+            }
+            Text(visit.operatorCompany?.name ?: "Operadora sin definir")
+            Text(visit.operationalArea?.name ?: "Área sin definir", style = MaterialTheme.typography.bodySmall)
+            visit.plannedStartAt?.let { Text("Prevista: ${shortDate(it)}", style = MaterialTheme.typography.bodySmall) }
+            Text("Inventario: ${visit.assetCount} · Equipo inspector: ${visit.memberCount}", style = MaterialTheme.typography.bodySmall)
+        }
+    }
+}
+
+@Composable
+private fun VisitRouter(model: MainViewModel) {
+    var inventoryMode by rememberSaveable(model.visit?.id) { mutableStateOf(false) }
+    if (inventoryMode) {
+        FieldInventoryScreen(model) { inventoryMode = false }
+    } else {
+        VisitScreen(model) { inventoryMode = true }
+    }
+}
+
+@Composable
+private fun VisitScreen(model: MainViewModel, onInventory: () -> Unit) {
+    val visit = model.visit ?: return
+    Column(
+        Modifier.fillMaxSize().verticalScroll(rememberScrollState()).padding(top = 28.dp, start = 16.dp, end = 16.dp, bottom = 30.dp),
+        verticalArrangement = Arrangement.spacedBy(12.dp),
+    ) {
+        Row(Modifier.fillMaxWidth(), horizontalArrangement = Arrangement.SpaceBetween, verticalAlignment = Alignment.CenterVertically) {
+            OutlinedButton(onClick = { model.closeVisitView() }) { Text("Volver") }
+            Text(visit.status, fontWeight = FontWeight.Bold)
+        }
+        Text(visit.code, style = MaterialTheme.typography.headlineMedium, fontWeight = FontWeight.Bold)
+        Text("${visit.operatorCompany?.name ?: "Sin operadora"} · ${visit.operationalArea?.name ?: "Sin área"}")
+        visit.instructions?.takeIf { it.isNotBlank() }?.let {
+            Card(Modifier.fillMaxWidth()) { Column(Modifier.padding(12.dp)) { Text("Instrucciones", fontWeight = FontWeight.Bold); Text(it) } }
+        }
+        MessageStrip(model)
+
+        if (visit.status == "PLANNED") {
+            Button(onClick = { model.startVisit() }, enabled = !model.busy, modifier = Modifier.fillMaxWidth()) {
+                Text("Iniciar inspección")
+            }
+        }
+        if (visit.status == "PLANNED" || visit.status == "IN_PROGRESS") {
+            OutlinedButton(onClick = onInventory, modifier = Modifier.fillMaxWidth()) { Text("Inventario de campo") }
+        }
+
+        ChecklistCard(visit)
+
+        Text("Inventario planificado", style = MaterialTheme.typography.titleMedium, fontWeight = FontWeight.Bold)
+        if (visit.planningAssets.isEmpty()) Text("Sin elementos planificados.")
+        visit.planningAssets.filter { it.included }.forEach { asset ->
+            Card(Modifier.fillMaxWidth()) {
+                Column(Modifier.padding(10.dp)) {
+                    Text(asset.name, fontWeight = FontWeight.SemiBold)
+                    Text("${asset.code} · ${asset.typeName.orEmpty()}", style = MaterialTheme.typography.bodySmall)
+                }
+            }
+        }
+    }
+}
+
+@Composable
+private fun ChecklistCard(visit: VisitDetail) {
+    val checklist = visit.checklist
+    Card(Modifier.fillMaxWidth()) {
+        Column(Modifier.padding(12.dp), verticalArrangement = Arrangement.spacedBy(6.dp)) {
+            Text("Checklist de antecedentes", fontWeight = FontWeight.Bold)
+            Text("Vencidos empresa: ${checklist.companyOverdue} · Verificaciones vencidas: ${checklist.verificationOverdue}")
+            Text("Antecedentes: ${checklist.antecedents} · Próximos controles: ${checklist.upcomingControls}")
+            if (checklist.stale) Text("El checklist requiere revisión/actualización.", color = MaterialTheme.colorScheme.error)
+            checklist.items.take(10).forEach { item ->
+                HorizontalDivider()
+                Text(item.findingTitle ?: item.findingCode ?: "Hallazgo", fontWeight = FontWeight.SemiBold)
+                Text("${item.asset?.name.orEmpty()} · Gravedad ${item.severity ?: "s/d"}", style = MaterialTheme.typography.bodySmall)
+            }
+        }
+    }
+}
+
+@Composable
+private fun FieldInventoryScreen(model: MainViewModel, onBack: () -> Unit) {
+    val context = LocalContext.current
+    val scope = rememberCoroutineScope()
+    val visit = model.visit ?: return
+    var search by rememberSaveable { mutableStateOf("") }
+    var showCreate by rememberSaveable { mutableStateOf(false) }
+    var parentId by rememberSaveable { mutableStateOf<String?>(null) }
+    var parentLabel by rememberSaveable { mutableStateOf("Área de la inspección") }
+    var name by rememberSaveable { mutableStateOf("") }
+    var commonName by rememberSaveable { mutableStateOf("") }
+    var selectedTypeId by rememberSaveable { mutableStateOf<String?>(null) }
+    val attributeValues = remember { mutableStateMapOf<String, String>() }
+
+    LaunchedEffect(visit.id) {
+        model.searchInventory("")
+        model.loadFieldTypes(null)
+    }
+    LaunchedEffect(model.fieldTypes) {
+        if (model.fieldTypes.none { it.id == selectedTypeId }) {
+            selectedTypeId = model.fieldTypes.firstOrNull()?.id
+            attributeValues.clear()
+        }
+    }
+
+    val selectedType = model.fieldTypes.firstOrNull { it.id == selectedTypeId }
+
+    val createWithLocation: () -> Unit = {
+        val type = selectedType
+        if (type != null) {
+            scope.launch {
+                runCatching { currentGeo(context) }
+                    .onSuccess { geo ->
+                        val values = buildAttributes(type, attributeValues)
+                        model.createFieldAsset(type, parentId, name, commonName, values, geo.latitude, geo.longitude, geo.accuracyM)
+                    }
+            }
+        }
+    }
+    val locationPermissionLauncher = rememberLauncherForActivityResult(ActivityResultContracts.RequestMultiplePermissions()) { result ->
+        val allowed = result[Manifest.permission.ACCESS_FINE_LOCATION] == true || result[Manifest.permission.ACCESS_COARSE_LOCATION] == true
+        if (allowed) createWithLocation()
+    }
+
+    var pendingPhotoFile by remember { mutableStateOf<File?>(null) }
+    var pendingPhotoGeo by remember { mutableStateOf<GeoSnapshot?>(null) }
+    val takePicture = rememberLauncherForActivityResult(ActivityResultContracts.TakePicture()) { success ->
+        val file = pendingPhotoFile
+        val geo = pendingPhotoGeo
+        if (success && file != null && geo != null) {
+            runCatching { writeExif(file, geo) }
+            model.uploadFieldPhoto(file, geo.latitude, geo.longitude, geo.accuracyM)
+        }
+        pendingPhotoFile = null
+        pendingPhotoGeo = null
+    }
+    val beginPhoto: () -> Unit = {
+        scope.launch {
+            runCatching { currentGeo(context) }.onSuccess { geo ->
+                val (file, uri) = newPhoto(context)
+                pendingPhotoFile = file
+                pendingPhotoGeo = geo
+                takePicture.launch(uri)
+            }
+        }
+    }
+    val photoPermissionLauncher = rememberLauncherForActivityResult(ActivityResultContracts.RequestMultiplePermissions()) { result ->
+        val camera = result[Manifest.permission.CAMERA] == true || hasPermission(context, Manifest.permission.CAMERA)
+        val location = result[Manifest.permission.ACCESS_FINE_LOCATION] == true || result[Manifest.permission.ACCESS_COARSE_LOCATION] == true || hasLocation(context)
+        if (camera && location) beginPhoto()
+    }
+
+    Column(Modifier.fillMaxSize().padding(top = 28.dp)) {
+        Row(Modifier.fillMaxWidth().padding(horizontal = 16.dp, vertical = 8.dp), horizontalArrangement = Arrangement.SpaceBetween) {
+            OutlinedButton(onClick = onBack) { Text("Volver") }
+            Text("Inventario de campo", style = MaterialTheme.typography.titleLarge, fontWeight = FontWeight.Bold)
+        }
+        Column(Modifier.padding(horizontal = 16.dp)) { MessageStrip(model) }
+
+        val selectedCapture = model.selectedFieldAsset
+        if (selectedCapture != null) {
+            CaptureCard(
+                detailName = selectedCapture.asset.name,
+                captureRequired = selectedCapture.capture.captureRequired,
+                gps = selectedCapture.capture.creationGpsCaptured,
+                photos = selectedCapture.capture.fieldPhotoCount,
+                ready = selectedCapture.capture.readyForFinding,
+                onPhoto = {
+                    val permissions = arrayOf(Manifest.permission.CAMERA, Manifest.permission.ACCESS_FINE_LOCATION, Manifest.permission.ACCESS_COARSE_LOCATION)
+                    if (hasPermission(context, Manifest.permission.CAMERA) && hasLocation(context)) beginPhoto()
+                    else photoPermissionLauncher.launch(permissions)
+                },
+                onClose = { model.clearSelectedFieldAsset() },
+            )
+        }
+
+        Row(Modifier.fillMaxWidth().padding(horizontal = 16.dp), verticalAlignment = Alignment.CenterVertically) {
+            OutlinedTextField(
+                value = search,
+                onValueChange = { search = it },
+                label = { Text("Buscar por nombre, código o atributo") },
+                modifier = Modifier.weight(1f),
+                singleLine = true,
+            )
+            Spacer(Modifier.width(8.dp))
+            Button(onClick = { model.searchInventory(search) }, enabled = !model.busy) { Text("Buscar") }
+        }
+        if (visit.status == "IN_PROGRESS") {
+            Row(Modifier.fillMaxWidth().padding(16.dp), horizontalArrangement = Arrangement.SpaceBetween) {
+                Text("Alta en campo", fontWeight = FontWeight.Bold)
+                OutlinedButton(onClick = {
+                    showCreate = !showCreate
+                    if (showCreate) model.loadFieldTypes(parentId)
+                }) { Text(if (showCreate) "Ocultar" else "Crear nuevo") }
+            }
+        }
+
+        if (showCreate && visit.status == "IN_PROGRESS") {
+            Column(
+                Modifier.fillMaxWidth().padding(horizontal = 16.dp).verticalScroll(rememberScrollState()).weight(1f, fill = false),
+                verticalArrangement = Arrangement.spacedBy(10.dp),
+            ) {
+                Text("Padre: $parentLabel", style = MaterialTheme.typography.bodySmall)
+                if (parentId != null) {
+                    OutlinedButton(onClick = {
+                        parentId = null
+                        parentLabel = "Área de la inspección"
+                        model.loadFieldTypes(null)
+                    }) { Text("Volver al Área") }
+                }
+                if (model.fieldTypes.isEmpty()) Text("No hay tipos habilitados debajo de este padre.")
+                LazyRow(horizontalArrangement = Arrangement.spacedBy(8.dp)) {
+                    items(model.fieldTypes, key = { it.id }) { type ->
+                        AssistChip(
+                            onClick = { selectedTypeId = type.id; attributeValues.clear() },
+                            label = { Text(if (type.id == selectedTypeId) "✓ ${type.name}" else type.name) },
+                        )
+                    }
+                }
+                OutlinedTextField(name, { name = it }, label = { Text("Nombre o código identificable *") }, modifier = Modifier.fillMaxWidth())
+                OutlinedTextField(commonName, { commonName = it }, label = { Text("Nombre común") }, modifier = Modifier.fillMaxWidth())
+                selectedType?.attributes?.forEach { definition ->
+                    OutlinedTextField(
+                        value = attributeValues[definition.code].orEmpty(),
+                        onValueChange = { attributeValues[definition.code] = it },
+                        label = { Text(definition.name + if (definition.isRequired) " *" else "") },
+                        supportingText = {
+                            val details = listOfNotNull(definition.unit, definition.options?.toString()).joinToString(" · ")
+                            if (details.isNotBlank()) Text(details)
+                        },
+                        keyboardOptions = KeyboardOptions(
+                            keyboardType = if (definition.dataType.uppercase() in setOf("NUMBER", "DECIMAL", "INTEGER", "FLOAT")) KeyboardType.Decimal else KeyboardType.Text,
+                        ),
+                        modifier = Modifier.fillMaxWidth(),
+                    )
+                }
+                val requiredReady = selectedType?.attributes?.filter { it.isRequired }?.all { attributeValues[it.code].orEmpty().isNotBlank() } ?: false
+                Button(
+                    onClick = {
+                        if (hasLocation(context)) createWithLocation()
+                        else locationPermissionLauncher.launch(arrayOf(Manifest.permission.ACCESS_FINE_LOCATION, Manifest.permission.ACCESS_COARSE_LOCATION))
+                    },
+                    enabled = selectedType != null && name.isNotBlank() && requiredReady && !model.busy,
+                    modifier = Modifier.fillMaxWidth(),
+                ) { Text("Capturar GPS y crear") }
+                HorizontalDivider()
+            }
+        }
+
+        Text("Resultados", modifier = Modifier.padding(horizontal = 16.dp, vertical = 8.dp), fontWeight = FontWeight.Bold)
+        LazyColumn(
+            Modifier.fillMaxSize().padding(horizontal = 16.dp),
+            verticalArrangement = Arrangement.spacedBy(8.dp),
+        ) {
+            items(model.inventory, key = { it.id }) { item ->
+                InventoryCard(
+                    item = item,
+                    canModify = visit.status == "IN_PROGRESS",
+                    onSelect = { model.selectExisting(item) },
+                    onUseParent = {
+                        parentId = item.id
+                        parentLabel = "${item.name} (${item.code})"
+                        showCreate = true
+                        selectedTypeId = null
+                        model.loadFieldTypes(item.id)
+                    },
+                )
+            }
+            item { Spacer(Modifier.height(30.dp)) }
+        }
+    }
+}
+
+@Composable
+private fun CaptureCard(
+    detailName: String,
+    captureRequired: Boolean,
+    gps: Boolean,
+    photos: Int,
+    ready: Boolean,
+    onPhoto: () -> Unit,
+    onClose: () -> Unit,
+) {
+    Card(Modifier.fillMaxWidth().padding(horizontal = 16.dp, vertical = 8.dp)) {
+        Column(Modifier.padding(12.dp), verticalArrangement = Arrangement.spacedBy(6.dp)) {
+            Row(Modifier.fillMaxWidth(), horizontalArrangement = Arrangement.SpaceBetween) {
+                Text(detailName, fontWeight = FontWeight.Bold)
+                OutlinedButton(onClick = onClose) { Text("Cerrar") }
+            }
+            Text("GPS de alta: ${if (gps) "OK" else "pendiente"} · Fotos: $photos")
+            if (captureRequired && !ready) {
+                Text("El Hallazgo permanece bloqueado hasta completar GPS + foto.", color = MaterialTheme.colorScheme.error)
+                Button(onClick = onPhoto, modifier = Modifier.fillMaxWidth()) { Text("Tomar foto obligatoria") }
+            } else if (ready) {
+                Text("Captura completa · habilitado para Hallazgos", color = MaterialTheme.colorScheme.primary)
+            }
+        }
+    }
+}
+
+@Composable
+private fun InventoryCard(item: FieldInventoryItem, canModify: Boolean, onSelect: () -> Unit, onUseParent: () -> Unit) {
+    Card(Modifier.fillMaxWidth()) {
+        Column(Modifier.padding(12.dp), verticalArrangement = Arrangement.spacedBy(4.dp)) {
+            Text(item.name, fontWeight = FontWeight.SemiBold)
+            Text("${item.code} · ${item.type?.name.orEmpty()}", style = MaterialTheme.typography.bodySmall)
+            item.commonName?.let { Text(it, style = MaterialTheme.typography.bodySmall) }
+            Text(
+                if (item.readyForFinding) "Listo" else "Captura incompleta: GPS/foto pendiente",
+                color = if (item.readyForFinding) MaterialTheme.colorScheme.primary else MaterialTheme.colorScheme.error,
+                style = MaterialTheme.typography.bodySmall,
+            )
+            if (canModify) {
+                Row(horizontalArrangement = Arrangement.spacedBy(8.dp)) {
+                    OutlinedButton(onClick = onSelect) { Text(if (item.selectedInInspection) "Abrir" else "Seleccionar") }
+                    OutlinedButton(onClick = onUseParent) { Text("Crear hijo") }
+                }
+            }
+        }
+    }
+}
+
+private fun buildAttributes(type: FieldType, values: Map<String, String>): Map<String, Any?> =
+    type.attributes.mapNotNull { definition ->
+        val raw = values[definition.code]?.trim().orEmpty()
+        if (raw.isBlank()) return@mapNotNull null
+        definition.code to coerceAttribute(definition, raw)
+    }.toMap()
+
+private fun coerceAttribute(definition: FieldAttributeDefinition, raw: String): Any = when (definition.dataType.uppercase()) {
+    "INTEGER", "INT" -> raw.toLongOrNull() ?: raw
+    "NUMBER", "DECIMAL", "FLOAT", "DOUBLE" -> raw.replace(',', '.').toDoubleOrNull() ?: raw
+    "BOOLEAN", "BOOL" -> raw.lowercase() in setOf("true", "1", "si", "sí", "yes")
+    else -> raw
+}
+
+private fun hasPermission(context: Context, permission: String): Boolean =
+    ContextCompat.checkSelfPermission(context, permission) == PackageManager.PERMISSION_GRANTED
+
+private fun hasLocation(context: Context): Boolean =
+    hasPermission(context, Manifest.permission.ACCESS_FINE_LOCATION) || hasPermission(context, Manifest.permission.ACCESS_COARSE_LOCATION)
+
+private suspend fun currentGeo(context: Context): GeoSnapshot = suspendCancellableCoroutine { continuation ->
+    if (!hasLocation(context)) {
+        continuation.resumeWithException(SecurityException("Se necesita permiso de ubicación."))
+        return@suspendCancellableCoroutine
+    }
+    val source = CancellationTokenSource()
+    val client = LocationServices.getFusedLocationProviderClient(context)
+    client.getCurrentLocation(Priority.PRIORITY_HIGH_ACCURACY, source.token)
+        .addOnSuccessListener { location ->
+            if (!continuation.isActive) return@addOnSuccessListener
+            if (location == null) continuation.resumeWithException(IllegalStateException("No se pudo obtener una ubicación GPS actual."))
+            else continuation.resume(GeoSnapshot(location.latitude, location.longitude, location.accuracy.toDouble()))
+        }
+        .addOnFailureListener { if (continuation.isActive) continuation.resumeWithException(it) }
+    continuation.invokeOnCancellation { source.cancel() }
+}
+
+private fun newPhoto(context: Context): Pair<File, Uri> {
+    val directory = context.getExternalFilesDir(Environment.DIRECTORY_PICTURES)
+        ?: throw IllegalStateException("No se pudo acceder al almacenamiento de fotografías.")
+    directory.mkdirs()
+    val file = File.createTempFile("DH_${System.currentTimeMillis()}_", ".jpg", directory)
+    val uri = FileProvider.getUriForFile(context, "${context.packageName}.files", file)
+    return file to uri
+}
+
+private fun writeExif(file: File, geo: GeoSnapshot) {
+    val now = Instant.now()
+    val exif = ExifInterface(file)
+    exif.setLatLong(geo.latitude, geo.longitude)
+    val formatter = DateTimeFormatter.ofPattern("yyyy:MM:dd HH:mm:ss").withZone(ZoneId.systemDefault())
+    exif.setAttribute(ExifInterface.TAG_DATETIME_ORIGINAL, formatter.format(now))
+    exif.setAttribute(ExifInterface.TAG_DATETIME_DIGITIZED, formatter.format(now))
+    exif.saveAttributes()
+}
+
+private fun shortDate(value: String): String = value.replace('T', ' ').take(16)

android-app/app/src/main/res/values/strings.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <string name="app_name">DH Inspección</string>
+</resources>

android-app/app/src/main/res/values/styles.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <style name="Theme.DHInspeccion" parent="android:style/Theme.Material.Light.NoActionBar">
+        <item name="android:fontFamily">sans</item>
+        <item name="android:windowActionModeOverlay">true</item>
+        <item name="android:colorAccent">#1B5E20</item>
+        <item name="android:navigationBarColor">#FFFFFF</item>
+        <item name="android:statusBarColor">#FFFFFF</item>
+        <item name="android:windowLightStatusBar">true</item>
+    </style>
+</resources>

android-app/app/src/main/res/xml/file_paths.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
+<paths xmlns:android="http://schemas.android.com/apk/res/android">
+    <external-files-path name="inspection_photos" path="Pictures/" />
+</paths>

android-app/build.gradle.kts

@@ -0,0 +1,5 @@
+plugins {
+    id("com.android.application") version "8.13.2" apply false
+    id("org.jetbrains.kotlin.android") version "2.2.20" apply false
+    id("org.jetbrains.kotlin.plugin.compose") version "2.2.20" apply false
+}

android-app/gradle.properties

@@ -0,0 +1,4 @@
+org.gradle.jvmargs=-Xmx3g -Dfile.encoding=UTF-8
+android.useAndroidX=true
+kotlin.code.style=official
+android.nonTransitiveRClass=true

android-app/settings.gradle.kts

@@ -0,0 +1,18 @@
+pluginManagement {
+    repositories {
+        google()
+        mavenCentral()
+        gradlePluginPortal()
+    }
+}
+
+dependencyResolutionManagement {
+    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+
+rootProject.name = "DHInspeccion"
+include(":app")

api-v3/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dhv2-api",
-  "version": "0.21.0-1",
+  "version": "0.22.0-1",
   "private": true,
   "license": "UNLICENSED",
   "scripts": {
@@ -43,4 +43,4 @@
     "tsx": "^4.20.6",
     "typescript": "^5.9.0"
   }
-}
+}

api-v3/src/auth/auth.module.ts

@@ -5,6 +5,8 @@ import { AuthorizationModule } from '../authorization/authorization.module';
 import { PhaseADataModule } from '../core-data/phase-a-data.module';
 import { AuthController } from './auth.controller';
 import { AuthService } from './auth.service';
+import { MobileAuthController } from './mobile-auth.controller';
+import { MobileAuthService } from './mobile-auth.service';
 import { AccessTokenGuard } from './guards/access-token.guard';
 import { CsrfGuard } from './guards/csrf.guard';
 import { AuthConfigService } from '../common/config/auth-config.service';
@@ -18,6 +20,7 @@ const providers = [
   PasswordService,
   TokenService,
   AuthService,
+  MobileAuthService,
   AccessTokenGuard,
   CsrfGuard,
 ];
@@ -29,7 +32,7 @@ const providers = [
     AuditModule,
     AuthorizationModule,
   ],
-  controllers: [AuthController],
+  controllers: [AuthController, MobileAuthController],
   providers,
   exports: [
     AuthConfigService,

api-v3/src/auth/dto/mobile-refresh.dto.ts

@@ -0,0 +1,8 @@
+import { IsString, MaxLength, MinLength } from 'class-validator';
+
+export class MobileRefreshDto {
+  @IsString()
+  @MinLength(32)
+  @MaxLength(256)
+  refreshToken!: string;
+}

api-v3/src/auth/mobile-auth.controller.ts

@@ -0,0 +1,56 @@
+import {
+  Body,
+  Controller,
+  HttpCode,
+  Post,
+  Req,
+} from '@nestjs/common';
+import { Throttle } from '@nestjs/throttler';
+import type {
+  AuthPrincipal,
+  RequestWithContext,
+} from '../common/http/request-context';
+import { CurrentAuth } from './decorators/current-auth.decorator';
+import { Public } from './decorators/public.decorator';
+import { SkipCsrf } from './decorators/skip-csrf.decorator';
+import { LoginDto } from './dto/login.dto';
+import { MobileRefreshDto } from './dto/mobile-refresh.dto';
+import { MobileAuthService } from './mobile-auth.service';
+
+@Controller('auth/mobile')
+export class MobileAuthController {
+  constructor(private readonly mobileAuth: MobileAuthService) {}
+
+  @Post('login')
+  @HttpCode(200)
+  @Public()
+  @SkipCsrf()
+  @Throttle({ default: { limit: 5, ttl: 60_000, blockDuration: 60_000 } })
+  login(
+    @Body() dto: LoginDto,
+    @Req() request: RequestWithContext,
+  ) {
+    return this.mobileAuth.login(dto, request);
+  }
+
+  @Post('refresh')
+  @HttpCode(200)
+  @Public()
+  @SkipCsrf()
+  @Throttle({ default: { limit: 20, ttl: 60_000 } })
+  refresh(
+    @Body() dto: MobileRefreshDto,
+    @Req() request: RequestWithContext,
+  ) {
+    return this.mobileAuth.refresh(dto.refreshToken, request);
+  }
+
+  @Post('logout')
+  @HttpCode(200)
+  logout(
+    @CurrentAuth() principal: AuthPrincipal,
+    @Req() request: RequestWithContext,
+  ) {
+    return this.mobileAuth.logout(principal, request);
+  }
+}

api-v3/src/auth/mobile-auth.service.ts

@@ -0,0 +1,386 @@
+import { isIP } from 'node:net';
+import {
+  ForbiddenException,
+  Injectable,
+  UnauthorizedException,
+} from '@nestjs/common';
+import { DataSource } from 'typeorm';
+import { AuditService } from '../audit/audit.service';
+import type {
+  AuthPrincipal,
+  RequestWithContext,
+} from '../common/http/request-context';
+import { AuthSessionsRepository } from '../core-data/repositories/auth-sessions.repository';
+import { RolesRepository } from '../core-data/repositories/roles.repository';
+import { UsersRepository } from '../core-data/repositories/users.repository';
+import {
+  AuditAction,
+  AuditSource,
+  AuthSession,
+  User,
+  UserStatus,
+} from '../database/entities';
+import type { LoginDto } from './dto/login.dto';
+import { PasswordService } from './services/password.service';
+import {
+  IssuedRefreshToken,
+  TokenService,
+} from './services/token.service';
+
+interface RequestMetadata {
+  ip: string | null;
+  userAgent: string | null;
+}
+
+interface SuccessfulAuthentication {
+  user: User;
+  accessToken: string;
+  refreshToken: IssuedRefreshToken;
+}
+
+type LoginOutcome = SuccessfulAuthentication | null;
+type RefreshOutcome =
+  | ({ kind: 'ok' } & SuccessfulAuthentication)
+  | { kind: 'reuse' }
+  | { kind: 'invalid' };
+
+function invalidCredentials(): UnauthorizedException {
+  return new UnauthorizedException({
+    code: 'INVALID_CREDENTIALS',
+    message: 'Credenciales inválidas',
+  });
+}
+
+function invalidSession(): UnauthorizedException {
+  return new UnauthorizedException({
+    code: 'INVALID_SESSION',
+    message: 'Sesión móvil inválida o vencida',
+  });
+}
+
+function inspectorRequired(): ForbiddenException {
+  return new ForbiddenException({
+    code: 'INSPECTION_INSPECTOR_ROLE_REQUIRED',
+    message: 'Sólo un usuario con rol inspector puede ingresar a la aplicación móvil',
+  });
+}
+
+function requestMetadata(request: RequestWithContext): RequestMetadata {
+  const candidateIp = request.ip || request.socket.remoteAddress || '';
+  const ip = isIP(candidateIp) ? candidateIp : null;
+  const rawUserAgent = request.header('user-agent')?.trim();
+  return {
+    ip,
+    userAgent: rawUserAgent ? rawUserAgent.slice(0, 2048) : null,
+  };
+}
+
+@Injectable()
+export class MobileAuthService {
+  constructor(
+    private readonly dataSource: DataSource,
+    private readonly users: UsersRepository,
+    private readonly sessions: AuthSessionsRepository,
+    private readonly roles: RolesRepository,
+    private readonly passwords: PasswordService,
+    private readonly tokens: TokenService,
+    private readonly audit: AuditService,
+  ) {}
+
+  async login(dto: LoginDto, request: RequestWithContext) {
+    const identifier = dto.identifier.trim().toLowerCase();
+    const candidate = await this.users.findForAuthentication(identifier);
+    const metadata = requestMetadata(request);
+
+    if (!candidate) {
+      await this.passwords.verifyUnknown(dto.password);
+      await this.audit.record({
+        action: AuditAction.AUTH_LOGIN_FAILED,
+        requestId: request.requestId,
+        source: AuditSource.ANDROID,
+        ...metadata,
+        metadata: { identifier, reason: 'UNKNOWN_IDENTIFIER' },
+      });
+      throw invalidCredentials();
+    }
+
+    const outcome = await this.dataSource.transaction<LoginOutcome>(
+      async (manager) => {
+        const user = await manager
+          .getRepository(User)
+          .createQueryBuilder('user')
+          .addSelect('user.passwordHash')
+          .where('user.id = :id', { id: candidate.id })
+          .setLock('pessimistic_write')
+          .getOne();
+        if (!user) return null;
+
+        const now = new Date();
+        const passwordMatches = await this.passwords.verify(
+          user.passwordHash,
+          dto.password,
+        );
+        const locked = Boolean(user.lockedUntil && user.lockedUntil > now);
+        const active = user.status === UserStatus.ACTIVE;
+
+        if (!passwordMatches || locked || !active) {
+          if (!passwordMatches && active && !locked) {
+            await manager.query(
+              `
+                UPDATE users
+                SET
+                  failed_login_attempts = failed_login_attempts + 1,
+                  locked_until = CASE
+                    WHEN failed_login_attempts + 1 >= $2
+                      THEN CURRENT_TIMESTAMP + ($3 * INTERVAL '1 second')
+                    ELSE locked_until
+                  END,
+                  updated_at = CURRENT_TIMESTAMP
+                WHERE id = $1
+              `,
+              [
+                user.id,
+                this.tokens.maxLoginAttempts,
+                this.tokens.lockoutSeconds,
+              ],
+            );
+          }
+
+          await this.audit.record(
+            {
+              actorUserId: user.id,
+              actorUsername: user.username,
+              action: AuditAction.AUTH_LOGIN_FAILED,
+              entityType: 'user',
+              entityId: user.id,
+              requestId: request.requestId,
+              source: AuditSource.ANDROID,
+              ...metadata,
+              metadata: {
+                reason: !active
+                  ? 'INACTIVE_USER'
+                  : locked
+                    ? 'LOCKED_USER'
+                    : 'INVALID_PASSWORD',
+              },
+            },
+            manager,
+          );
+          return null;
+        }
+
+        if (this.passwords.needsRehash(user.passwordHash)) {
+          user.passwordHash = await this.passwords.hash(dto.password);
+        }
+        user.failedLoginAttempts = 0;
+        user.lockedUntil = null;
+        user.lastLoginAt = now;
+        await manager.getRepository(User).save(user);
+
+        const refreshToken = this.tokens.issueRefreshToken();
+        const session = manager.getRepository(AuthSession).create({
+          id: refreshToken.sessionId,
+          userId: user.id,
+          refreshTokenHash: refreshToken.tokenHash,
+          expiresAt: this.tokens.refreshExpiresAt(now),
+          lastUsedAt: now,
+          revokedAt: null,
+          replacedBySessionId: null,
+          ip: metadata.ip,
+          userAgent: metadata.userAgent,
+          deviceLabel: dto.deviceLabel?.trim() || 'DH Android',
+        });
+        await manager.getRepository(AuthSession).save(session);
+
+        const accessToken = await this.tokens.issueAccessToken({
+          userId: user.id,
+          sessionId: session.id,
+          username: user.username,
+        });
+
+        await this.audit.record(
+          {
+            actorUserId: user.id,
+            actorUsername: user.username,
+            action: AuditAction.AUTH_LOGIN_SUCCESS,
+            entityType: 'auth_session',
+            entityId: session.id,
+            requestId: request.requestId,
+            source: AuditSource.ANDROID,
+            ...metadata,
+            metadata: { deviceLabel: session.deviceLabel },
+          },
+          manager,
+        );
+
+        return { user, accessToken, refreshToken };
+      },
+    );
+
+    if (!outcome) throw invalidCredentials();
+    return this.complete(outcome);
+  }
+
+  async refresh(rawToken: string, request: RequestWithContext) {
+    const parsed = this.tokens.parseRefreshToken(rawToken);
+    if (!parsed) throw invalidSession();
+
+    const metadata = requestMetadata(request);
+    const outcome = await this.dataSource.transaction<RefreshOutcome>(
+      async (manager) => {
+        const session = await manager
+          .getRepository(AuthSession)
+          .createQueryBuilder('session')
+          .addSelect('session.refreshTokenHash')
+          .where('session.id = :id', { id: parsed.sessionId })
+          .setLock('pessimistic_write')
+          .getOne();
+
+        if (
+          !session ||
+          !this.tokens.verifyRefreshToken(rawToken, session.refreshTokenHash)
+        ) {
+          return { kind: 'invalid' };
+        }
+
+        const user = await manager.getRepository(User).findOne({
+          where: { id: session.userId },
+        });
+
+        if (session.revokedAt) {
+          await this.sessions.revokeSessionFamily(session.id, manager);
+          await this.audit.record(
+            {
+              actorUserId: user?.id ?? null,
+              actorUsername: user?.username ?? null,
+              action: AuditAction.AUTH_REFRESH_REUSE_DETECTED,
+              entityType: 'auth_session',
+              entityId: session.id,
+              requestId: request.requestId,
+              source: AuditSource.ANDROID,
+              ...metadata,
+            },
+            manager,
+          );
+          return { kind: 'reuse' };
+        }
+
+        const now = new Date();
+        if (!user || user.status !== UserStatus.ACTIVE || session.expiresAt <= now) {
+          session.revokedAt = now;
+          session.lastUsedAt = now;
+          await manager.getRepository(AuthSession).save(session);
+          if (user?.status === UserStatus.INACTIVE) {
+            await this.sessions.revokeUserSessions(user.id, undefined, manager);
+          }
+          return { kind: 'invalid' };
+        }
+
+        const refreshToken = this.tokens.issueRefreshToken();
+        const replacement = manager.getRepository(AuthSession).create({
+          id: refreshToken.sessionId,
+          userId: user.id,
+          refreshTokenHash: refreshToken.tokenHash,
+          expiresAt: this.tokens.refreshExpiresAt(now),
+          lastUsedAt: now,
+          revokedAt: null,
+          replacedBySessionId: null,
+          ip: metadata.ip,
+          userAgent: metadata.userAgent,
+          deviceLabel: session.deviceLabel,
+        });
+        await manager.getRepository(AuthSession).save(replacement);
+
+        session.revokedAt = now;
+        session.lastUsedAt = now;
+        session.replacedBySessionId = replacement.id;
+        await manager.getRepository(AuthSession).save(session);
+
+        const accessToken = await this.tokens.issueAccessToken({
+          userId: user.id,
+          sessionId: replacement.id,
+          username: user.username,
+        });
+
+        await this.audit.record(
+          {
+            actorUserId: user.id,
+            actorUsername: user.username,
+            action: AuditAction.AUTH_REFRESH,
+            entityType: 'auth_session',
+            entityId: replacement.id,
+            requestId: request.requestId,
+            source: AuditSource.ANDROID,
+            ...metadata,
+            metadata: { replacedSessionId: session.id },
+          },
+          manager,
+        );
+
+        return { kind: 'ok', user, accessToken, refreshToken };
+      },
+    );
+
+    if (outcome.kind !== 'ok') throw invalidSession();
+    return this.complete(outcome);
+  }
+
+  async logout(
+    principal: AuthPrincipal,
+    request: RequestWithContext,
+  ) {
+    const metadata = requestMetadata(request);
+    await this.dataSource.transaction(async (manager) => {
+      await this.sessions.revokeSession(
+        principal.sessionId,
+        principal.userId,
+        manager,
+      );
+      await this.audit.record(
+        {
+          actorUserId: principal.userId,
+          actorUsername: principal.username,
+          action: AuditAction.AUTH_LOGOUT,
+          entityType: 'auth_session',
+          entityId: principal.sessionId,
+          requestId: request.requestId,
+          source: AuditSource.ANDROID,
+          ...metadata,
+        },
+        manager,
+      );
+    });
+    return { status: 'ok' };
+  }
+
+  private async complete(authentication: SuccessfulAuthentication) {
+    const [roleCodes, permissionCodes] = await Promise.all([
+      this.roles.findRoleCodesForUser(authentication.user.id),
+      this.roles.findPermissionCodesForUser(authentication.user.id),
+    ]);
+
+    if (!roleCodes.includes('inspector')) {
+      await this.sessions.revokeSession(
+        authentication.refreshToken.sessionId,
+        authentication.user.id,
+      );
+      throw inspectorRequired();
+    }
+
+    return {
+      user: {
+        id: authentication.user.id,
+        username: authentication.user.username,
+        firstName: authentication.user.firstName,
+        lastName: authentication.user.lastName,
+        email: authentication.user.email,
+        mustChangePassword: authentication.user.mustChangePassword,
+        roles: roleCodes,
+        permissions: permissionCodes,
+      },
+      accessToken: authentication.accessToken,
+      refreshToken: authentication.refreshToken.token,
+      accessExpiresInSeconds: this.tokens.accessTokenTtlSeconds,
+    };
+  }
+}

api-v3/src/database/migrations/1788652800000-reset-production-operational-data.ts

@@ -0,0 +1,173 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * One-time production reset requested before the first clean Android rollout.
+ *
+ * Keeps only structural product configuration plus the single `admin` account.
+ * Operational/business data is removed. Recovery is intentionally performed
+ * from the deploy PRE backup, not through a synthetic down migration.
+ */
+export class ResetProductionOperationalData1788652800000 implements MigrationInterface {
+  name = 'ResetProductionOperationalData1788652800000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    const adminRows: Array<{ id: string; username: string }> = await queryRunner.query(`
+      SELECT id, username
+      FROM users
+      WHERE lower(trim(username)) = 'admin'
+      ORDER BY id
+    `);
+
+    if (adminRows.length !== 1) {
+      throw new Error(
+        `Production reset aborted: expected exactly one username admin, found ${adminRows.length}`,
+      );
+    }
+
+    const adminId = adminRows[0].id;
+
+    const structuralTables = [
+      'roles',
+      'permissions',
+      'role_permissions',
+      'asset_types',
+      'asset_attribute_definitions',
+      'asset_type_parent_rules',
+      'finding_categories',
+      'finding_catalog_items',
+      'finding_catalog_item_asset_types',
+      'finding_catalog_asset_type_profiles',
+    ];
+
+    // Snapshot structural row counts so TRUNCATE ... CASCADE can never silently
+    // remove product configuration while still leaving operational tables empty.
+    const structuralCounts = new Map<string, string>();
+    for (const table of structuralTables) {
+      const safeTable = `"${table.replace(/"/g, '""')}"`;
+      const rows: Array<{ total: string }> = await queryRunner.query(
+        `SELECT count(*)::text AS total FROM ${safeTable}`,
+      );
+      structuralCounts.set(table, rows[0]?.total ?? '0');
+    }
+
+    const adminRolesBefore: Array<{ total: string }> = await queryRunner.query(
+      `SELECT count(*)::text AS total FROM user_roles WHERE user_id = $1`,
+      [adminId],
+    );
+    const adminRoleCount = adminRolesBefore[0]?.total ?? '0';
+    if (adminRoleCount === '0') {
+      throw new Error('Production reset aborted: admin has no assigned role');
+    }
+
+    // Product configuration that must survive a clean operational start.
+    const preservedTables = new Set([
+      'typeorm_migrations',
+      'users',
+      'user_roles',
+      ...structuralTables,
+    ]);
+
+    const tableRows: Array<{ table_name: string }> = await queryRunner.query(`
+      SELECT table_name
+      FROM information_schema.tables
+      WHERE table_schema = 'public'
+        AND table_type = 'BASE TABLE'
+      ORDER BY table_name
+    `);
+
+    const operationalTables = tableRows
+      .map((row) => row.table_name)
+      .filter((table) => !preservedTables.has(table));
+
+    if (operationalTables.length > 0) {
+      const quoted = operationalTables
+        .map((table) => `"${table.replace(/"/g, '""')}"`)
+        .join(', ');
+      await queryRunner.query(`TRUNCATE TABLE ${quoted} RESTART IDENTITY CASCADE`);
+    }
+
+    // Remove every user except the explicitly validated administrator.
+    // user_roles for removed users follow their FK cascade.
+    await queryRunner.query(`DELETE FROM users WHERE id <> $1`, [adminId]);
+
+    // A reset must invalidate every prior login token, including admin's.
+    // auth_sessions is operational and was truncated above; admin simply logs in again.
+    await queryRunner.query(
+      `
+      UPDATE users
+      SET failed_login_attempts = 0,
+          locked_until = NULL,
+          last_login_at = NULL,
+          updated_at = CURRENT_TIMESTAMP
+      WHERE id = $1
+    `,
+      [adminId],
+    );
+
+    const finalUsers: Array<{ total: string; admins: string }> = await queryRunner.query(`
+      SELECT
+        count(*)::text AS total,
+        count(*) FILTER (WHERE lower(trim(username)) = 'admin')::text AS admins
+      FROM users
+    `);
+
+    if (finalUsers[0]?.total !== '1' || finalUsers[0]?.admins !== '1') {
+      throw new Error('Production reset verification failed: users table is not admin-only');
+    }
+
+    const finalAdminRoles: Array<{ total: string; foreign_users: string }> = await queryRunner.query(
+      `
+      SELECT
+        count(*) FILTER (WHERE user_id = $1)::text AS total,
+        count(*) FILTER (WHERE user_id <> $1)::text AS foreign_users
+      FROM user_roles
+    `,
+      [adminId],
+    );
+
+    if (
+      finalAdminRoles[0]?.total !== adminRoleCount ||
+      finalAdminRoles[0]?.foreign_users !== '0'
+    ) {
+      throw new Error('Production reset verification failed: admin role assignments changed');
+    }
+
+    // Assert every structural table kept exactly the same number of rows.
+    for (const table of structuralTables) {
+      const safeTable = `"${table.replace(/"/g, '""')}"`;
+      const rows: Array<{ total: string }> = await queryRunner.query(
+        `SELECT count(*)::text AS total FROM ${safeTable}`,
+      );
+      const before = structuralCounts.get(table) ?? '0';
+      if (rows[0]?.total !== before) {
+        throw new Error(
+          `Production reset verification failed: structural table ${table} changed (${before} -> ${rows[0]?.total ?? 'unknown'})`,
+        );
+      }
+    }
+
+    // Assert that every operational table is empty. This makes the migration
+    // fail atomically if a table was repopulated during the reset transaction.
+    for (const table of operationalTables) {
+      const safeTable = `"${table.replace(/"/g, '""')}"`;
+      const rows: Array<{ total: string }> = await queryRunner.query(
+        `SELECT count(*)::text AS total FROM ${safeTable}`,
+      );
+      if (rows[0]?.total !== '0') {
+        throw new Error(`Production reset verification failed: ${table} is not empty`);
+      }
+    }
+
+    // Keep a concise server-side record in the migration log for deploy diagnostics.
+    // eslint-disable-next-line no-console
+    console.log(
+      `[production-reset] kept admin=${adminRows[0].username} (${adminId}); preserved ${structuralTables.length} structural tables; cleared ${operationalTables.length} operational tables`,
+    );
+  }
+
+  public async down(): Promise<void> {
+    throw new Error(
+      'ResetProductionOperationalData is irreversible by migration; restore the deploy PRE database backup instead.',
+    );
+  }
+}

api-v3/src/version.ts

@@ -1,2 +1,2 @@
-export const API_VERSION = '0.21.0-1';
-export const API_PHASE = 'F2.1';
+export const API_VERSION = '0.22.0-1';
+export const API_PHASE = 'F2.2';