pgr/docs/rules/610-ANDROID.md

<!-- file: docs/rules/610-ANDROID.md -->
<!-- version: 2 -->

# Profil Android

## Rôle

Ce document possède les règles réutilisables propres à la plateforme Android.

Il complète [`600-PLATFORMS.md`](600-PLATFORMS.md) et, lorsqu'un projet Android utilise Java/Gradle, [`520-JAVA_MAVEN_GRADLE.md`](520-JAVA_MAVEN_GRADLE.md).

Une contrainte Android plus spécifique MAY raffiner les règles générales Java ou Gradle dans le seul scope Android lorsqu'une matrice AGP/Gradle/JDK, un SDK ou une contrainte de distribution l'impose.

Les profils Rust/JNI et Tauri ne sont pas définis ici. Ils constituent des compositions plus spécialisées et MUST NOT contaminer le profil Android général.

## Structure du projet

Pour un dépôt exclusivement Android, les conventions Android normales restent prioritaires et la racine du dépôt MAY être directement le projet Gradle.

Dans un dépôt multi-plateforme où une zone Android distincte est nécessaire, PGR SHOULD utiliser la racine :

```text
Android/
```

Cette racine est alors un chemin de plateforme stable. Elle ne doit pas être renommée arbitrairement en `android/`, `mobile/` ou autre uniquement par préférence locale.

Une structure multi-plateforme peut par exemple contenir :

```text
project/
├── VERSION
├── crates/
├── Web/
└── Android/
    ├── settings.gradle
    ├── build.gradle
    ├── gradle.properties
    ├── gradlew
    ├── gradlew.bat
    └── gradle/
```

Les noms et fichiers exacts restent soumis au projet Android réellement utilisé ; PGR ne crée pas de niveau `Android/` artificiel dans un dépôt qui est déjà exclusivement Android.

## Langage applicatif et logique de build

Java est le langage applicatif Android par défaut du profil PGR lorsqu'aucune API, framework ou contrainte réelle n'impose un autre choix.

Kotlin MAY être utilisé lorsqu'une API, un framework ou une intégration l'exige réellement.

Groovy DSL ou Kotlin DSL MAY être utilisés par Gradle comme langage de configuration. Leur présence dans le build ne transforme pas Kotlin ou Groovy en langage applicatif du projet.

Les fichiers Gradle SHOULD rester aussi déclaratifs et courts que raisonnablement possible. Une logique de build importante SHOULD être possédée par une abstraction ou un plugin identifiable plutôt que devenir du code produit caché dans un script Gradle.

Les annotations fonctionnelles Android ou de frameworks restent autorisées lorsqu'elles constituent le mécanisme officiel de l'API concernée.

## Matrice AGP / Gradle / JDK

Un projet Android MUST exprimer une chaîne de build compatible.

La matrice conceptuelle est :

```text
Android Gradle Plugin
↕
Gradle
↕
JDK LTS
```

PGR MUST NOT imposer globalement une version Gradle, AGP ou JDK uniquement parce qu'elle est utilisée par un autre projet Android.

La contrainte applicable peut être :

```text
minimum
range min..max
version exacte / pin
latest compatible
```

Le projet choisit la forme la moins restrictive qui reste réellement compatible avec sa stack.

Le JDK suit le profil Java : dernière LTS compatible par défaut, LTS plus ancienne lorsqu'une contrainte Android ou de framework l'impose, non-LTS uniquement par exception justifiée.

Lorsque le Gradle Wrapper est retenu, ses fichiers requis sont versionnés et sa version doit satisfaire la matrice réelle AGP/Gradle/JDK.

## `compileSdk`, `targetSdk` et `minSdk`

Ces trois valeurs représentent des contrats différents.

`compileSdk` définit l'API Android utilisée pour compiler. Il MAY être récent afin de permettre l'usage des APIs et outils actuels.

`targetSdk` déclare le niveau de comportement Android pour lequel l'application a été adaptée. Il MUST respecter les exigences applicables au canal de distribution réellement visé.

`minSdk` définit la plus ancienne version Android que le produit promet de pouvoir installer et exécuter.

PGR MUST NOT déduire une hausse de `minSdk` d'une hausse de `compileSdk` ou `targetSdk`.

`minSdk` SHOULD rester aussi bas que raisonnablement supportable tant que cela ne compromet pas une capacité nécessaire, une dépendance imposée, la sécurité ou une maintenance raisonnable.

Une hausse de `minSdk` est un changement de compatibilité utilisateur et MUST être explicitement justifiée.

## `VERSION`, `versionName` et `versionCode`

Lorsqu'une application Android appartient au même release train que le projet, le fichier PGR `VERSION` reste la version SemVer canonique de cette unité de release.

`versionName` est un miroir technique de cette version lorsqu'elle doit représenter la même release à l'utilisateur ou au canal de distribution.

`versionCode` est un compteur Android monotone distinct du SemVer.

PGR MUST NOT confondre `versionCode` avec `VERSION` ou `versionName`.

Pour une application publiée, `versionCode` MUST NOT diminuer. Lorsqu'un dépôt publie plusieurs applications indépendantes, chaque application MAY posséder son propre compteur versionné.

Le projet MAY stocker ce compteur dans un fichier explicite tel que :

```text
Android/app/VERSION_CODE
```

si cela correspond à son architecture.

PGR SHOULD NOT imposer une formule dérivant automatiquement `versionCode` du SemVer sans décision explicite du projet.

Un futur audit read-only MAY vérifier séparément :

```text
VERSION ↔ versionName
VERSION_CODE ↔ configuration Android
```

lorsqu'un projet ou skeleton réel fournit des fichiers à contrôler. Cet audit ne doit jamais modifier les versions.

## Configuration locale

`local.properties` est un fichier local Android typique et SHOULD rester hors Git lorsqu'il contient des chemins machine tels que l'emplacement du SDK.

PGR MUST NOT utiliser `local.properties` comme source normative de configuration partagée du projet.

Si l'outil ou l'IDE régénère intégralement ce fichier, aucun fichier exemple n'est nécessaire.

Lorsqu'une propriété locale obligatoire n'est pas automatiquement reproductible, un template MAY être fourni conformément aux règles générales PGR.

La même politique s'applique aux fichiers locaux analogues tels que `keystore.properties`, `user.properties` ou des variantes `*.local.properties` lorsqu'ils contiennent des valeurs propres à la machine ou à l'utilisateur.

## Signing et secrets

L'interdiction générale de versionner ou distribuer des secrets reste possédée par `RULES.md`. Le profil Android ajoute uniquement les conséquences propres au signing de cette plateforme.

Dans le scope Android, les éléments suivants sont notamment des secrets ou artefacts privés soumis à cette interdiction :

```text
release keystore
private signing key
passwords
credentials
service account secret
```

Une configuration versionnée MAY référencer des variables ou propriétés telles que :

```text
RELEASE_KEYSTORE
RELEASE_KEY_ALIAS
```

mais MUST NOT contenir leurs valeurs privées.

Le debug keystore généré automatiquement est local.

Le signing de release ne doit pas être requis pour une validation ordinaire de développement sauf lorsque la tranche valide précisément la distribution ou la signature finale.

## Modules Android

Les modules Android SHOULD être nommés par responsabilité.

Des noms tels que :

```text
app
common
game-reflex
game-snake
```

peuvent être légitimes lorsque ces responsabilités existent réellement.

Des noms opaques tels que `module1`, `module2`, `misc` ou `utils2` SHOULD NOT servir de structure durable.

Un module partagé doit posséder une responsabilité commune réelle ; il ne doit pas devenir un dépôt générique de code sans owner.

## Dépendances Android

Les dépendances Android doivent rester minimales et explicites.

Une dépendance officielle et étroite SHOULD être préférée à un framework beaucoup plus large lorsqu'une petite capability suffit.

À l'inverse, PGR SHOULD NOT réimplémenter une API de plateforme, un protocole standard ou une primitive de sécurité uniquement pour éviter une dépendance officielle appropriée.

Une BOM ou un mécanisme officiel de gestion de versions MAY être utilisé lorsqu'il réduit réellement les incompatibilités. Il ne doit pas entraîner l'ajout automatique de toute une famille de dépendances non utilisées.

La politique d'un lockfile Android/Gradle, lorsqu'un projet en utilise un, doit être décidée selon le besoin réel de cet écosystème et du projet. Elle n'est pas déduite automatiquement d'un autre profil.

## ABI et code natif

Un projet Android purement Java peut ne posséder aucune règle ABI spécifique.

Dès qu'un projet contient du code natif via NDK, C/C++, Rust ou une autre frontière native, les ABI réellement supportées MUST être déclarées explicitement.

Exemples possibles :

```text
arm64-v8a
armeabi-v7a
x86_64
```

PGR ne fixe pas une liste universelle d'ABI.

Une ABI annoncée comme supportée doit disposer d'une preuve adaptée. Une cross-compilation native seule ne prouve pas l'intégration dans l'APK, le lifecycle Android ni l'exécution sur device/AVD.

Les règles JNI elles-mêmes appartiennent à un profil spécialisé et restent hors de ce document.

## Niveaux de tests Android

PGR distingue au moins trois niveaux de preuve Android lorsqu'ils sont applicables :

```text
JVM unit
→ logique ne nécessitant pas le runtime Android

instrumented / integration
→ comportement nécessitant le framework Android

smoke device / AVD
→ application ou package réel dans un environnement Android
```

Un test JVM MUST NOT être enregistré comme preuve d'un comportement réel d'`Activity`, de lifecycle ou de device.

Un test instrumenté ne remplace pas automatiquement un smoke du package final.

Un appareil physique n'est pas obligatoire pour chaque release. Il devient nécessaire lorsqu'une propriété annoncée dépend d'un matériel ou comportement qui ne peut pas être suffisamment prouvé par AVD.

## Ordre de validation Android

Une validation Android ordinaire SHOULD progresser du ciblé vers le plus coûteux :

```text
format applicable
↓
audits read-only applicables
↓
compilation module ciblé
↓
lint Android ciblé
↓
unit tests ciblés
↓
assemble/package lorsque nécessaire
↓
install
↓
smoke
```

Les tests globaux, l'instrumentation large, les bundles de release, les matrices multi-ABI et les smokes multi-device sont sélectionnés lorsque le scope ou la phase de release l'exige réellement.

Les commandes exactes appartiennent à la matrice du projet ou du skeleton qui possède un Android build réel.

`clean` reste une opération de maintenance et ne doit pas précéder automatiquement chaque gate.

## Manifest et ressources

`AndroidManifest.xml` MUST déclarer uniquement les permissions et capabilities réellement nécessaires.

Une permission sensible ne doit pas être ajoutée « au cas où ». Son introduction constitue un changement significatif qui doit être visible dans le delta et, lorsque pertinent, dans la documentation de release.

`src/main/res/` reste la source canonique des ressources Android d'un module standard.

Dans un projet multi-plateforme, des assets réellement partagés MAY vivre dans un owner commun hors d'Android si leur consommation est définie clairement.

PGR SHOULD NOT maintenir manuellement plusieurs copies divergentes du même asset source dans des arborescences de plateforme différentes.

## APK, AAB et artefacts de distribution

PGR distingue les rôles des principaux artefacts :

```text
APK debug
→ développement et smokes ordinaires

APK release
→ validation d'un package release installable lorsque nécessaire

AAB
→ artefact de distribution lorsque le canal cible l'exige
```

La phase de release et le scope modifié déterminent l'artefact nécessaire.

Une alpha documentaire n'a pas besoin d'un package Android réel si aucun projet Android n'est concerné. Une release d'une application Android peut au contraire nécessiter un package ou smoke réel lorsque `versionName`, `versionCode`, signing ou packaging sont modifiés.

La promotion stable ne doit pas provoquer mécaniquement un full rebuild sans preuve invalidée ; elle doit toutefois revalider le packaging ciblé lorsque les métadonnées qui entrent dans l'artefact ont changé.

## Validation et futurs audits PGR

Les catégories générales et l'autorité du gate restent possédées par [`400-VALIDATION.md`](400-VALIDATION.md).

PGR lui-même ne contient actuellement aucun projet Android à compiler, installer ou exécuter. Cette tranche ne prétend donc pas valider AGP, Gradle, SDK, AVD, APK ou AAB réels.

Aucun audit Android spécialisé n'est créé uniquement pour remplir le profil.

Lorsqu'un skeleton ou projet concret fournira les fichiers nécessaires, des audits monotâches MAY vérifier des propriétés structurelles stables telles que la cohérence de version, la présence d'une configuration locale ignorée ou une matrice de compatibilité explicitement déclarée. Ces audits restent read-only et ne remplacent jamais Gradle, Android Lint, l'installation ou les smokes.