📖 Manuel

Mobile SDK Architect (Fintech Kotlin)

Workflow en étapes

1. Analyse des besoins et périmètre

• Identifier les cas d'usage : KYC, onboarding, paiements P2P, notifications push, réconciliation offline.
• Définir la frontière SDK : ce qui est public (façade) vs interne (implémentation).
• Choisir la cible : Android natif, KMP (Kotlin Multiplatform), ou React Native bridge.

Critère de décision — KMP vs natif vs bridge :

2. Structure modulaire Gradle / KMP

sdk/
├── core/            # entités, use cases, interfaces (pas d'Android)
├── network/         # Retrofit/Ktor, Serialization
├── storage/         # Room / SQLDelight (KMP)
├── auth/            # OAuth2, JWT, token refresh
├── payments/        # logique paiement, state machine
└── sample-app/      # démo intégration

Déclaration multiplatform (build.gradle.kts) :

kotlin {
    androidTarget()
    iosX64(); iosArm64(); iosSimulatorArm64()

    sourceSets {
        val commonMain by getting {
            dependencies {
                implementation("io.ktor:ktor-client-core:2.3.12")
                implementation("app.cash.sqldelight:runtime:2.0.2")
            }
        }
        val androidMain by getting {
            dependencies {
                implementation("io.ktor:ktor-client-okhttp:2.3.12")
            }
        }
        val iosMain by getting {
            dependencies {
                implementation("io.ktor:ktor-client-darwin:2.3.12")
            }
        }
    }
}

3. API publique — design et rétrocompatibilité

• Exposer uniquement via une façade (internal pour tout le reste).
• Appliquer semver strict : MAJOR = breaking, MINOR = ajout, PATCH = fix.
• Marquer les deprecations avec @Deprecated(level = DeprecationLevel.WARNING) avant retrait.

// facade publique
class FintechSDK private constructor(private val config: SDKConfig) {
    companion object {
        fun init(config: SDKConfig): FintechSDK = FintechSDK(config)
    }
    val payments: PaymentsApi get() = PaymentsApiImpl(...)
    val kyc: KycApi get() = KycApiImpl(...)
}

// jamais exposer :
internal class PaymentsApiImpl(...) : PaymentsApi { ... }

• Versionner les endpoints : /api/v2/payments, jamais supprimer v1 sans migration guide.
• Feature flags via SDKConfig pour activer/désactiver modules sans rebuild.

4. Sécurité et conformité (fintech 2026)

• TLS 1.3 obligatoire + certificate pinning (OkHttp CertificatePinner).
• Android Keystore pour clés AES-256-GCM ; iOS Keychain côté Swift.
• Token refresh : rotation JWT avec sliding window, révocation côté serveur.
• RGPD / CNDP Maroc : anonymisation PII dans les logs, droit à l'effacement via API dédiée.

// Certificate pinning OkHttp
val client = OkHttpClient.Builder()
    .certificatePinner(
        CertificatePinner.Builder()
            .add("api.myfintech.com", "sha256/AAAA...==")
            .build()
    )
    .connectTimeout(10, TimeUnit.SECONDS)
    .readTimeout(30, TimeUnit.SECONDS)
    .build()

• Ne jamais logger de données sensibles (PAN, IBAN, token) — utiliser un SensitiveDataFilter sur le logger.
• Root/jailbreak detection (SafetyNet/Play Integrity API 2026 ; DCAppAttestService iOS).

5. Error handling standardisé

Sealed class pour erreurs métier, jamais de try/catch silencieux :

sealed class SdkResult<out T> {
    data class Success<T>(val data: T) : SdkResult<T>()
    sealed class Failure : SdkResult<Nothing>() {
        data class Network(val code: Int, val msg: String) : Failure()
        data class Business(val errorCode: String, val msg: String) : Failure()
        data class Unexpected(val cause: Throwable) : Failure()
    }
}

// codes métier exhaustifs
object ErrorCodes {
    const val KYC_FAILED       = "ERR_KYC_001"
    const val AUTH_EXPIRED     = "ERR_AUTH_002"
    const val INSUFFICIENT_BALANCE = "ERR_PAY_003"
}

6. Performance mobile

• Offline-first : Room / SQLDelight comme source de vérité locale ; sync via WorkManager.
• Pagination cursor-based (after=<id>) — jamais offset sur grandes collections.
• Cache HTTP : OkHttp Cache 10 MB pour endpoints stables ; Cache-Control: max-age côté serveur.
• Lazy init des modules lourds (ex. : caméra KYC) — ne pas tout charger au SDK.init().

// WorkManager sync périodique
val syncRequest = PeriodicWorkRequestBuilder<TransactionSyncWorker>(
    repeatInterval = 15, TimeUnit.MINUTES
).setConstraints(
    Constraints.Builder().setRequiredNetworkType(NetworkType.CONNECTED).build()
).build()
WorkManager.getInstance(context).enqueueUniquePeriodicWork(
    "tx_sync", ExistingPeriodicWorkPolicy.KEEP, syncRequest
)

7. Testing

// MockK use case test
@Test
fun `transfer fails on insufficient balance`() = runTest {
    coEvery { repository.getBalance(any()) } returns 10.0
    val result = transferUseCase(TransferRequest(amount = 500.0, ...))
    assertIs<SdkResult.Failure.Business>(result)
    assertEquals(ErrorCodes.INSUFFICIENT_BALANCE, result.errorCode)
}

8. Documentation et publication

• KDoc sur tout symbole public ; générer la référence via ./gradlew dokkaHtml.
• README avec quickstart en < 10 lignes (copier-coller prêt).
• Sample app dans sample-app/ couvrant les 3 flux principaux.
• Publier sur Maven Central ou dépôt privé (Nexus/GitHub Packages) :

// publishing block (build.gradle.kts)
publishing {
    publications {
        create<MavenPublication>("release") {
            groupId = "com.mycompany"
            artifactId = "fintech-sdk"
            version = "2.1.0"
            from(components["release"])
        }
    }
}

Garde-fous / Anti-patterns

Bonnes pratiques 2026

• Play Integrity API remplace SafetyNet depuis 2024 — migrer si pas fait.
• Predictive Back Gesture Android 15+ : tester les transitions SDK dans le back stack.
• KMP stable (Kotlin 2.x) : privilégier commonMain pour la logique métier, éviter les expect/actual inutiles.
• Kotlin Coroutines Structured Concurrency : toujours lier les coroutines à un CoroutineScope géré par le cycle de vie ; jamais GlobalScope.
• Ktor 3.x : multiplatform natif, remplace OkHttp côté KMP shared layer.
• SQLDelight 2.x : préférer à Room pour KMP, schéma vérifié à la compilation.