Aller au contenu principal

Application Android

Kotlin + Jetpack Compose (Material 3), minSdk 26, même API REST que le web. Aucune logique métier propre à Android : les règles (récurrence, rotation, quick add) restent côté serveur.

Aujourd'hui

1. Ce que fait l'app​

OngletContenu
Aujourd'hui« Bonjour Grace 👋 », en retard, aujourd'hui (x sur y faites), « Qui fait quoi » (7 jours × personnes, ui/today/WeekBoard.kt), 7 prochains jours, tâches sans date, répartition de la semaine (tâches partagées, non compétitive)
TâchesRecherche, filtres À faire / À venir / Sans date / Faites, « Les miennes », regroupement par jour
CoursesListe de courses permanente du foyer : ajout de plusieurs articles d'un coup (« lait, pain »), cocher au magasin, « Dans le panier (pris par Nicolas) », « Vider le panier », Mode magasin (plein écran, gros caractères, par rayon, écran allumé). Hors ligne (affiché tout de suite, envoyé au retour du réseau, sans doublon) et en temps réel (indicateur « En direct »)
CalendrierMois (lundi → dimanche, pastilles = tâches à faire), liste du jour choisi, « Ajouter ce jour-là » ; glisser-déposer : appui long sur une tâche puis la lâcher sur un jour (heure conservée, cette occurrence seulement, « Annuler » dans le message ; TalkBack : actions « jour précédent / suivant »)
Dépenses (tiroir Plus)Qui doit quoi et « Enregistrer le remboursement », totaux du mois (communes, part de chacun, mes dépenses perso), liste par jour ; ajouter, modifier, supprimer (montant, quoi, date, payé par, pour qui : commune / pour l'autre / perso, catégorie, commentaire). Parts à la main, Chaque mois (charges fixes, à arrêter depuis la liste), ticket (photo ou PDF, ouvert par l'app adaptée). « Noter la dépense » après Vider le panier dans les Courses. Budget du mois (jauge, alerte à 80 % et 100 % par notification), budgets par catégorie (jauges, Budgets par catégorie : un montant par catégorie), Sur 6 mois, Exporter (CSV partagé vers une autre app). En ligne seulement ; les proportions se règlent sur le site
Notes et dates hors ligneDernière liste lue gardée dans Room (cached_documents, base v9, migration 8 → 9) : affichée sans réseau, en lecture ; « dans N jours » des dates recalculé (DatesRemote.refreshed). Effacée à la déconnexion (clearAllTables)
Notes (tiroir Plus)Notes partagées du foyer (ui/notes/NotesScreen.kt, NotesRemote) : liste épinglées d'abord, ajouter, modifier, épingler (punaise), copier, supprimer avec « Annuler » (snackbar, la note est recréée) ; conflit de version affiché dans la feuille. En ligne seulement, mise à jour en direct (sujet notes)
Dates (tiroir Plus)Dates importantes (ui/dates/DatesScreen.kt, DatesRemote) : les plus proches d'abord, âge, rappel ; feuille d'édition (sélecteur de date, « Chaque année », « Année connue », rappel). « Bientôt » sur Aujourd'hui (14 jours). En ligne seulement, en direct (sujet dates) ; notification IMPORTANT_DATE
Plus (tiroir)Toucher « Plus » ou tirer la barre du bas vers le haut ouvre un tiroir (ui/navigation/NavDrawer.kt, ModalBottomSheet) : Dépenses, Notes, Dates importantes, Journal et corbeille, Absences, Aide, Réglages. Réglages : foyer et membres, état du calendrier partagé (Google), rappels, compte (Appareils connectés : liste, déconnexion d'un appareil ou de tous les autres, DevicesRemote, en ligne), déconnexion
  • Ajout rapide (bouton +) : « Sortir les poubelles mardi 20h Nicolas », aperçu analysé par l'API.
  • Formulaire : titre, date, heure, durée, responsables, répétition et tour de rôle (mêmes choix que sur le site, aperçu des prochaines dates), catégorie, priorité, notes, personnelle, calendrier partagé. Modifier / supprimer une tâche récurrente demande la portée (celle-ci, les suivantes, toute la série).
  • Échange de tour (ui/swaps/Swaps.kt, SwapsRemote) : « Proposer à … » sur la fiche d'une tâche partagée à faire dont je suis responsable ; demandes reçues (Je la prends / Pas cette fois) et envoyées (Annuler) en haut d'Aujourd'hui. En ligne seulement, comme les commentaires ; notifications TASK_SWAP_REQUEST et TASK_SWAP_ANSWER.
  • Rappels : notification avant chaque tâche planifiée qui me concerne (moi, à deux, à définir), délai réglable, boutons Fait, Demain et Ce week-end dans la notification (hors ligne compris : le report part dès que le réseau revient).
  • Récapitulatif du matin (8 h, désactivable dans Réglages → Notifications) : tâches du jour qui me concernent, nombre en retard et à faire cette semaine. Calculé sur le téléphone.
  • Échéance souple : une tâche sans date peut être « à faire cette semaine », « ce mois-ci » ou avant une date ; section « À faire cette semaine » sur Aujourd'hui, en retard une fois dépassée. L'ajout rapide comprend « cette semaine », « ce mois-ci », « ce week-end ».
  • Raccourcis (appui long sur l'icône) : Nouvelle tâche, Dicter, Courses, Aujourd'hui.
  • Dictée : raccourci « Dicter » ou micro dans l'ajout rapide ; la reconnaissance vocale du téléphone remplit l'ajout rapide (« Sortir les poubelles demain 19 h Grace »), à valider. Partager un texte depuis une autre app (ACTION_SEND) ouvre ui/share/ShareSheet.kt : en tâche (ajout rapide), en note (noteFromShare : sujet ou première ligne en titre ; en ligne seulement) ou aux courses (splitShoppingItems, par l'outbox, hors ligne compris). Recherche globale (loupe sur Aujourd'hui, ui/search/SearchScreen.kt, SearchRemote) : GET /households/:id/search, en ligne ; une tâche ouvre son occurrence, le reste sa page. Tuile des réglages rapides tile/QuickAddTileService : ouvre l'ajout rapide (ACTION_QUICK_ADD, déverrouillage d'abord si besoin). Google Assistant : « Ok Google, ouvre Tandem » ; la capacité App Actions CREATE_THING (« crée … dans Tandem ») est déclarée et ne fonctionne qu'avec l'app publiée sur le Play Store.
  • Widget « Semaine » : les 7 prochains jours, groupés par jour, à cocher (hors ligne compris).
  • Modèles de tâches : dans l'ajout rapide (+), choisir un modèle et le jour (aujourd'hui, demain, ce week-end, sans date) crée toutes ses tâches. Les modèles se gèrent sur le site (Réglages → Modèles de tâches). Demande une connexion.
  • Historique (tâche récurrente) : dans la fiche, les dernières fois et qui l'a faite.
  • Reporter en un geste : « Demain » / « Ce week-end » dans la fiche, la notification de rappel et le widget (« → » : à demain).
  • Widget « Aujourd'hui » (appui long sur l'écran d'accueil → Widgets → Tandem) : tâches en retard et du jour, à cocher directement (hors ligne compris, même file d'envoi que l'app), toucher une tâche l'ouvre, « + » ouvre l'ajout rapide. Mis à jour à chaque changement et au moins toutes les 30 minutes (passage à minuit).
  • Temps réel : tant que l'app est à l'écran, elle écoute le flux du foyer (GET /v1/households/:id/events, Server-Sent Events) et recharge aussitôt ce que l'autre a changé (tâches, courses, notifications) ; à chaque reconnexion, tout est rechargé.
  • Widget « Courses » : ce qu'il reste à acheter, à cocher depuis l'écran d'accueil (hors ligne compris), « + » ou le titre ouvre la liste.
  • Activité : « Nicolas vous a attribué … » en notification système (si activé dans Réglages → Notifications sur le web). Instantanée si Firebase est configuré (§4.1), sinon vérifiée au retour dans l'app et à chaque synchronisation de fond ; la première vérification après installation ne notifie rien d'ancien.
  • Listes / sous-tâches (ex. « Courses ») : dans le formulaire d'une tâche, ajouter des éléments (touche Entrée), les cocher à deux, les retirer ; progression « liste 1/3 » dans les lignes. Demande une connexion (comme modifier une tâche).
  • Suggestion de répartition : tâche partagée « à définir » → « Suggestion : Nicolas, la moins chargée cette semaine » avec un bouton pour la lui confier.

2. Hors ligne (ADR-007, tel qu'implémenté)​

UI (Compose) ──▶ ViewModel ──▶ AgendaRepository
│ lit : Room (cache) écrit : outbox Room
▼ ▼
SyncEngine ◀── WorkManager (réseau requis, backoff, toutes les heures)
│ 1. vérifie le compte 2. rejoue l'outbox 3. recharge le cache
▼
API /v1
  • Lectures : toujours depuis Room. Cache rechargé : occurrences de J−30 à J+60, tous les retards, toutes les tâches sans date, foyer, membres, catégories.
  • Cocher / décocher / créer / ajout rapide : immédiats à l'écran, enregistrés dans l'outbox, envoyés dans l'ordre dès que le réseau revient. Cocher est idempotent côté serveur ; les créations portent une Idempotency-Key : un rejeu après une réponse perdue ne crée jamais de doublon. Une tâche créée hors ligne peut être cochée avant son envoi (l'identifiant est remappé).
  • Modifier / supprimer : en ligne uniquement (message clair sinon). Concurrence optimiste : si la tâche a changé ailleurs, la version à jour est rechargée et affichée.
  • Refus définitif (tâche supprimée entre-temps) : l'action est abandonnée et signalée ; erreur serveur persistante : abandonnée après 10 tentatives pour ne pas bloquer la file.
  • Autre compte sur le téléphone : le compte est vérifié avant tout envoi ; l'ancien cache et ses actions sont effacés sans être envoyés. Déconnexion volontaire : tout est effacé.
  • Rappels : AlarmManager (setAndAllowWhileIdle, pas de permission d'alarme exacte), reprogrammés à chaque changement du cache ou des préférences, et après un redémarrage.

3. Décisions​

SujetChoixPourquoi
Injection de dépendancesManuelle (AppContainer)Une dizaine d'objets ; Hilt n'apporterait que du code généré
Google Calendar (connexion, choix du calendrier)Sur le site (bouton « Gérer sur le site »)Même flux OAuth sécurisé que le web, aucun secret dans l'APK
Inscription, mot de passe oubliéOuvrent le site (Custom Tab)Mêmes écrans, e-mails et protections anti-énumération
« Continuer avec Google »Custom Tab sur le site + retour app.tandem.foyer://auth?code=…, code à usage unique (2 min) échangé avec un verifier PKCE resté dans l'appAucun nouveau client OAuth ni URI dans la console Google ; une app qui intercepterait le lien ne peut rien en faire sans le verifier
Récurrence sur mobilePréréglages + « chacun son tour »Rotations avancées (séquences, jours fixes) restent sur le web
Base localeRoom, migration destructiveC'est un cache ; migrations obligatoires dès que le schéma change en production (sinon l'outbox non envoyée serait perdue)
Bord à bordThème Theme.Tandem (barres transparentes, voile de navigation avant Android 10, mode encoche shortEdges) + WindowCompat.setDecorFitsSystemWindows(false) avant Android 15 ; pas d'enableEdgeToEdge()Celui-ci appelle Window.setStatusBarColor, setNavigationBarColor et layoutInDisplayCutoutMode, obsolètes depuis Android 15 et signalés par Google Play. Vérifier : dexdump -d sur l'APK play minifié, aucune occurrence
En-tête User-AgentTandem-Android/<version> (Android <n°>)« Appareils connectés » reconnaît l'app et sa version ; pas de modèle de téléphone (donnée inutile)
Tests d'interfaceRobolectric (JVM) + émulateurRobolectric à chaque PR Android (rapide, captures) ; émulateur à la demande (SQLite, Keystore, lancement réels)

4. Construire et installer​

Installer sur le téléphone : sur le site, Réglages → Compte → Application Android → Télécharger (ou directement https://tandem-agenda.app/v1/app/android/tandem.apk), puis Installer (autoriser Chrome à « installer des applications inconnues » la première fois).

D'où vient l'APK : à chaque mise à jour de l'app sur main, le workflow android-release.yml publie dans la release GitHub android-latest (mise à jour sur place, jamais supprimée) un APK propre à la version (tandem-46.apk, les deux derniers sont gardés), une copie tandem.apk et, en dernier, version.json, qui désigne l'APK de la version. L'API les relaie (/v1/app/android/version.json, /v1/app/android/tandem.apk?v=46, cache 5 min côté API ; l'APK part en Cache-Control: no-store pour que Cloudflare ne serve jamais une ancienne version) : l'app et le site ne parlent qu'à tandem-agenda.app, que le dépôt soit public ou privé.

Dépôt privé : créer un jeton GitHub fine-grained (GitHub → Settings → Developer settings → Fine-grained tokens) limité à ce dépôt, permission Contents : Read-only, et le renseigner dans Coolify : GITHUB_RELEASES_TOKEN (puis redéployer). Sans jeton, un dépôt privé rend le lien de téléchargement et les mises à jour indisponibles (404, sans erreur dans l'app).

Mises à jour automatiques : l'app consulte version.json au lancement, au retour dans l'app et toutes les heures (WorkManager). Nouvelle version ⇒ notification + bandeau « Nouvelle version disponible » ⇒ « Mettre à jour » : téléchargement, contrôle SHA-256, installeur Android par-dessus (données conservées). Android impose une confirmation « Installer » (pas de mise à jour silencieuse hors Play Store) et, la première fois, l'autorisation « installer des applications » pour l'app. Le numéro de version (versionCode) est celui de l'exécution du workflow + 10 : toujours croissant.

Clé de signature (secrète) : Android n'installe une mise à jour que si elle est signée par la même clé. Le dépôt étant public, la clé n'y est jamais : elle vit dans les secrets GitHub.

# Une seule fois (JDK : keytool). Conserver le fichier et le mot de passe (gestionnaire de mots de passe).
keytool -genkeypair -keystore agenda.jks -alias agenda -keyalg RSA -keysize 4096 -validity 10000 \
-storepass "MOT_DE_PASSE" -keypass "MOT_DE_PASSE" -dname "CN=Tandem"
base64 -w0 agenda.jks # → secret ANDROID_KEYSTORE_B64

GitHub → dépôt → Settings → Secrets and variables → Actions → New repository secret : ANDROID_KEYSTORE_B64 (sortie de base64) et ANDROID_KEYSTORE_PASSWORD. Sans ces secrets, le workflow échoue explicitement et ne publie rien. Perdre la clé = désinstaller / réinstaller l'app.

APK signé en local avec la même clé :

cd apps/android
./gradlew assembleRelease -Ptandem.apiBaseUrl=https://tandem-agenda.app/ \
-Ptandem.keystore=/chemin/agenda.jks -Ptandem.keyAlias=agenda \
-Ptandem.keystorePassword=… -Ptandem.keyPassword=…

Google Play : la même CI produit tandem-play.aab (build play, sans mise à jour automatique) ; publication pas à pas dans play-store.md.

Développement : ./gradlew installDebug (émulateur ; l'API locale est vue en 10.0.2.2:4000).

4.1 Notifications instantanées (Firebase, facultatif)​

Sans configuration, l'app relève ses notifications à l'ouverture et lors de la synchronisation de fond (jusqu'à ~15 min de délai). Avec Firebase Cloud Messaging (gratuit), le serveur réveille le téléphone dès qu'il y a du nouveau. Le message ne contient aucune donnée (ni titre, ni nom) : l'app relit ensuite ses notifications auprès de l'API, avec les mêmes règles et préférences.

  1. https://console.firebase.google.com → Ajouter un projet (ex. agenda-gn), Google Analytics désactivé.

  2. Ajouter une application → Android, nom du package app.tandem.foyer → télécharger google-services.json (inutile de l'ajouter au projet : on n'en reprend que 4 valeurs).

  3. GitHub → Settings → Secrets and variables → Actions → Variables (pas des secrets : ce sont des identifiants publics, déjà présents dans tout APK Firebase) :

    Recopier les valeurs (pas les chemins) depuis google-services.json :

    {
    "project_info": {
    "project_number": "123456789012", // → FCM_SENDER_ID = 123456789012
    "project_id": "agenda-gn" // → FCM_PROJECT_ID = agenda-gn
    },
    "client": [{
    "client_info": {
    "mobilesdk_app_id": "1:123456789012:android:0a1b2c3d4e5f6a7b" // → FCM_APP_ID
    },
    "api_key": [{ "current_key": "AIzaSy…" }] // → FCM_API_KEY
    }]
    }

    Le workflow Android release vérifie le format de ces valeurs et échoue avec un message clair si l'une d'elles est mal copiée.

  4. Firebase → ⚙ Paramètres du projet → Comptes de service → Générer une nouvelle clé privée (fichier JSON). Coolify → variable FCM_SERVICE_ACCOUNT = contenu du fichier (tel quel, ou en base64 sur une ligne : base64 -w0 fichier.json) → redéployer. C'est un secret : ne jamais le committer ; supprimer le fichier téléchargé une fois copié.

  5. Relancer le workflow Android release (Actions → Run workflow) : la nouvelle version de l'app est proposée automatiquement ; après la mise à jour, ouvrir l'app une fois (enregistrement du téléphone).

Vérifier : l'autre personne vous confie une tâche → la notification arrive en quelques secondes, téléphone verrouillé. En cas de doute : logs de l'API (FCM …).

5. Tests​

cd apps/android
./gradlew lintDebug testDebugUnitTest # ce que lance la CI
./gradlew testDebugUnitTest -Pscreenshots # + captures dans docs/screenshots/android
./gradlew testDebugUnitTest -PliveApi=http://localhost:4000/ # + parcours contre une vraie API locale
./gradlew connectedDebugAndroidTest # sur un émulateur / téléphone branché
  • AgendaTest, TaskPayloadsTest, RemindersTest : règles d'affichage, corps JSON conformes à packages/contracts, rappels (fuseau du foyer, qui est concerné).
  • SyncEngineTest : vraie base Room + faux serveur : cocher hors ligne puis en ligne, ordre des actions, création rejouée après réponse perdue (une seule tâche), tâche supprimée ailleurs, erreur serveur, changement de compte.
  • ViewModelsTest : fuseau du foyer, rafraîchissement au retour du réseau, ajout rapide, validations du formulaire, portées, hors ligne et conflit.
  • ScreensTest : écrans réels (FR, clair/sombre), libellés d'accessibilité, captures.
  • LiveApiTest : connexion, synchro, créations hors ligne rejouées, série « les suivantes », conflit, suppression — contre la vraie API.

Sur émulateur (app/src/androidTest, workflow android-emulator.yml, API 34 et 35) : ce que Robolectric simule seulement. Une dizaine de minutes de runner, donc à la demande : onglet Actions → Android (émulateur) → Run workflow, ou étiquette emulateur sur la PR (à poser avant une version qui touche la base, les fichiers ou le démarrage de l'app).

  • DeviceMigrationTest : base installée en v1, toutes les migrations jusqu'à la dernière sur le SQLite de l'appareil, puis ouverture par Room ; actions hors ligne conservées.
  • LaunchTest : premier lancement réel (Room, WorkManager, DataStore chiffré par le Keystore), écran de connexion, erreur réseau affichée sans plantage quand le serveur est injoignable.
  • EdgeToEdgeTest : bord à bord réel (activé par l'app en API 34, imposé par Android en 35) : l'écran occupe tout l'écran, mais le logo et le bouton de connexion restent hors des barres système.
  • NavDrawerDeviceTest : la barre du bas et le tiroir « Plus » : toucher « Plus » ou tirer la barre vers le haut l'ouvre (tirer vers le bas, non), la touche retour le referme, et ni les onglets ni les tuiles ne passent sous la barre de gestes.
  • AttachmentProviderTest : le FileProvider des pièces jointes et photos partage bien les fichiers du cache.

Les noms de tests sont en ASCII : certains environnements ne savent pas écrire les classes générées dont le nom contient des accents.

Code-barres en direct​

« Scanner en direct » utilise le scanner de codes-barres de Google Play services (play-services-code-scanner, src/codeScanner) : son propre écran de caméra, aucune permission caméra pour l'app, lecture sur le téléphone. Sans Google Play services, la photo lue par le serveur reste disponible. Pour compiler sans accès au dépôt Maven de Google (bac à sable, hors ligne) : -Ptandem.codeScanner=false remplace le scanner par une version vide (src/noCodeScanner), le bouton disparaît.

Passkeys​

Connexion par passkey et Réglages → Compte → Passkeys passent par le Credential Manager d'Android (androidx.credentials, src/passkeys), à partir d'Android 9. Le domaine des clés est celui du site (tandem-agenda.app) : une passkey créée sur le site marche dans l'app, et inversement. Android ne l'accepte que si le site déclare l'app :

  1. Relever les empreintes SHA-256 des certificats qui signent l'app : Play Console → Intégrité de l'app → Signature de l'app (clé de signature de Google Play), et pour la clé des APK directs (mise à jour automatique), la CI la lit dans l'APK signé : résumé du job Android — APK à installer et notes de la release android-latest (« Empreinte du certificat »). Sans la CI : keytool -list -v -keystore <keystore>.
  2. Les mettre dans ANDROID_CERT_SHA256 côté API (Coolify), séparées par des virgules, puis redéployer. Ce ne sont pas des secrets.
  3. Vérifier https://tandem-agenda.app/.well-known/assetlinks.json : l'app app.tandem.foyer et ses empreintes y figurent. Le serveur accepte alors l'origine android:apk-key-hash:… de ces certificats, et l'app affiche le bouton.
  4. Attendre : Android garde sa vérification du lien site ↔ app en cache jusqu'à une heure (maxAge de Google). Juste après un ajout ou un changement d'empreinte, la connexion peut échouer (« La connexion par passkey n'a pas abouti ») sans rien dans les journaux de l'API. Contrôle : https://digitalassetlinks.googleapis.com/v1/assetlinks:check?source.web.site=https://tandem-agenda.app&relation=delegate_permission/common.get_login_creds&target.android_app.package_name=app.tandem.foyer&target.android_app.certificate.sha256_fingerprint=<empreinte> doit répondre "linked": true. L'app garde aussi la liste des moyens de connexion jusqu'à sa fermeture : Forcer l'arrêt fait apparaître le bouton sans attendre.

Sans empreinte déclarée, le bouton reste masqué et les Réglages renvoient au site pour l'ajout. Hors ligne (bac à sable) : -Ptandem.passkeys=false remplace le Credential Manager par une version vide (src/noPasskeys), comme pour le scanner.

Avis Google Play​

La version Google Play (bundlePlay) demande une note avec la fenêtre d'avis de Google Play (In-App Review, com.google.android.play:review, src/review), sans quitter l'app. Elle s'ouvre au plus une fois tous les quatre mois, dans ces conditions :

  • au moins 14 jours après la première ouverture, et 5 jours d'utilisation différents ;
  • sur Aujourd'hui, sans feuille ni tiroir ouvert, après 4 secondes sans changement d'écran : jamais pendant une action.

Google décide en plus s'il l'affiche (quota) : rien ne garantit qu'elle apparaisse. Les compteurs restent sur le téléphone (DataStore), rien n'est envoyé. Debug et APK direct ont une version vide (src/noReview) : pas de bibliothèque Play à télécharger pour les compiler. Pour tester la fenêtre : piste de test interne, ou partage d'app interne de la Play Console.

6. Limites connues​

  • Les rappels sont locaux : ils couvrent les 48 h suivantes et sont replanifiés au moins toutes les heures par WorkManager (Firebase ne sert qu'aux notifications d'activité).
  • Listes, déplacement et modification demandent le réseau ; cocher une tâche et créer marchent hors ligne.
  • Pas de vérification sur appareil physique dans la CI : faire la recette §7 à chaque version.

7. Recette manuelle (téléphone réel)​

  1. Installer l'APK, se connecter, vérifier « Aujourd'hui » face au site.
  2. Mode avion : cocher 2 tâches, en créer une (formulaire) et une par l'ajout rapide ; la bannière indique « Hors ligne · 4 modifications en attente ».
  3. Réseau rétabli : la bannière disparaît, le site montre les mêmes changements, sans doublon ; l'ajout rapide a bien été analysé (date, heure, personne).
  4. Modifier une tâche récurrente « celle-ci et les suivantes » ; vérifier sur le site et dans Google Calendar.
  5. Tâche dans 20 min avec rappel à 15 min : la notification arrive, « Fait » la coche.
  6. Passkeys : Réglages → Compte → Passkeys → « Ajouter une passkey » ; se déconnecter, puis « Se connecter avec une passkey » ; la passkey apparaît aussi sur le site.