Add bearer-authenticated subscription checkout, reconciliation and cancellation on the authority host, reuse web subscription services, and document the flow with regression tests. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
37 KiB
PostIt — Topologie, navigation, DI
Récapitulatif : PostIt est le client Avalonia du projet Yavsc. C'est un code-base unique (
src/PostIt/PostIt/PostIt.csproj) multi-cible vers trois front-ends distincts (PostIt.Desktop,Postit.Android,PostIt.Browser). Cette fiche couvre la topologie des projets, le DI, leViewLocatorcusto et la navigation — c'est-à-dire tout ce que la fiche postit-oidc.md ne détaille pas déjà (l'OIDC, le flow d'auth, la persistance des tokens). Détail dans cette page, racine de l'architecture : Architecture.md.
Surface : un code-base, trois front-ends
Le projet Android active EmbedAssembliesIntoApk par défaut, y compris en
Debug : un APK installé directement doit contenir les assemblies .NET,
sans dépendre des fichiers de Fast Deployment sous files/.__override__.
Sans elles, le runtime Android abandonne avant de charger l'interface
avec « No assemblies found ». Le Makefile conserve également ce réglage
explicite pour ses commandes de compilation.
┌────────────────────────┐
│ PostIt (lib) │
│ src/PostIt/PostIt/ │
│ Pages, ViewModels, │
│ Services, ViewLocator │
│ (aucun rendu natif) │
└──────┬───┬─────┬───────┘
│ │ │
┌───────────────┘ │ └────────────────┐
│ │ │
┌──────────▼────────┐ ┌────────▼─────────┐ ┌──────────▼────────┐
│ PostIt.Desktop │ │ PostIt.Android │ │ PostIt.Browser │
│ Avalonia.Desktop │ │ Avalonia.Android │ │ Avalonia.Browser │
│ Linux/Windows │ │ APK │ │ WASM │
│ + custom scheme │ │ + Chrome Custom │ │ (no native proc) │
│ postit:// │ │ Tabs │ │ │
│ + IBrowser custo │ │ + IBrowser custo │ │ │
└───────────────────┘ └──────────────────┘ └───────────────────┘
Le code partagé vit dans PostIt/. Chaque front-end est un
projet Satellite SDK Avalonia qui ne contient que le
Program.Main, le Platform.CreateBrowser, et les manifestes
spécifiques (IntentFilter Android, app.manifest Desktop).
Toute la logique (VM, services, navigation, settings, OIDC) est
dans le code-base partagé.
Abonnements PayPal
La page native Mon abonnement PayPal est accessible depuis l'accueil,
le profil et « À propos ». Elle utilise ResourceSubscriptionsApiClient
avec l'autorité OIDC configurée pour charger les offres, l'abonnement en
cours et le solde. Les prix HT/TTC, la TVA et les droits proviennent du serveur.
La création ou reprise de souscription utilise la session bearer de PostIt ;
seule l'approbation est ouverte dans le navigateur, sur un domaine PayPal HTTPS.
Après approbation ou abandon, l'utilisateur revient dans PostIt et utilise
Actualiser les paiements et mon solde. Ni l'ouverture du navigateur ni
la page de retour ne prouvent un paiement : seul le rapprochement serveur
des transactions vérifiées accorde les droits. La résiliation demande une
confirmation explicite et conserve les droits des périodes déjà payées.
La configuration serveur et les routes sont décrites dans INSTALL.md.
Reprise Android
IActivityApplicationLifetime.MainViewFactory crée une nouvelle MainView
pour chaque activité Android. Avant de remplacer la racine, PostIt relève
les types et les modèles de vue des pages de la pile précédente, puis
recrée ces pages dans le même ordre, sans animation. Les contrôles de
l'ancienne activité ne sont pas réutilisés ; les modèles de vue conservent
les sélections et brouillons en mémoire. Une nouvelle racine sans historique
reçoit la page d'accueil, même si l'initialisation de session a déjà eu lieu.
Le rafraîchissement silencieux de session reste unique par processus.
Cette restauration couvre la recréation d'activité dans le même processus,
pas la destruction du processus par Android.
Prévisualisation et orientation des Podcasts
« Prévisualiser la caméra » ouvre un aperçu local avant « Démarrer le direct », sans exiger de titre. Cette phase ne crée aucune émission côté serveur, n'enregistre aucun segment et n'ouvre pas le microphone. Le choix de caméra est verrouillé pendant l'aperçu ; l'arrêter pour changer de caméra. Le microphone sélectionné n'est ouvert qu'au démarrage du direct.
« Arrêter la prévisualisation », la sortie de page et la déconnexion libèrent la caméra. Le passage au direct ferme d'abord l'aperçu, puis ouvre la capture avec les périphériques sélectionnés : les images d'essai ne sont pas publiées. Sous Android, un aperçu seul s'arrête aussi au passage en arrière-plan, sans lancer de service de capture ni de notification de direct. Les Podcasts en direct conservent leur service caméra/microphone existant.
Le chemin Android partage le rendu Camera2/EGL entre aperçu seul et encodage.
L'arrêt de l'aperçu détache ses callbacks via le SurfaceHolder conservé,
avant la destruction différée du contrôle natif ; le nettoyage ne relit pas
la propriété Holder d'une SurfaceView dont le wrapper Java peut être libéré.
La rotation physique utilise l'orientation du capteur, la caméra avant/arrière
et la rotation de l'écran. Camera2 peut déjà inclure la rotation du capteur
dans la matrice SurfaceTexture, ainsi qu'un miroir pour la caméra avant :
seule la rotation restante est appliquée, dans le sens inverse si la matrice
contient un miroir, afin de ne pas tourner l'image deux fois.
Un changement de rotation d'écran recalcule ce rendu pendant la capture.
L'aperçu conserve les proportions ; les dimensions encodées restent celles
du démarrage du direct, avec des bandes noires si la nouvelle orientation
l'exige, pour ne pas modifier le format HLS/SRTP en cours d'émission.
Les tests partagés couvrent l'aperçu sans appel API, le passage au direct,
les arrêts et une sortie de page pendant l'ouverture de caméra. L'activité
Debug CameraFrameRotationTestActivity vérifie les quatre rotations avec
encodage, puis l'aperçu sans encodeur et ses changements de rotation.
Une validation physique caméra avant/arrière en portrait et paysage reste
nécessaire : les tests synthétiques ne vérifient pas le comportement du HAL
de chaque téléphone.
Administration et profil personnel
Le quota disque renvoyé par le profil est le quota effectif : Découverte donne deux fois et Premium cinq fois le quota gratuit standard durant la mensualité confirmée payée, y compris après résiliation jusqu'à son échéance UTC. Ensuite, ou après remboursement, le quota habituel reprend sans suppression des fichiers. Les téléversements dépassant l'espace disponible sont refusés avant écriture. La taille maximale par fichier et les quotas podcast restent inchangés.
L'accueil présente un seul accès Administration, visible et exécutable
uniquement pour le rôle exact Administrator. SessionStatusViewModel.RefreshAsync
lit les rôles dans GET account/me après le rafraîchissement de session ;
une erreur de lecture masque l'accès et affiche une erreur dans la bannière.
La déconnexion invalide aussi les vérifications de droits encore en vol.
AdministrationPage regroupe sept onglets : utilisateurs, usages globaux,
rôles, clients OIDC, scopes API, courriels et données. Les en-têtes se
répartissent sur plusieurs lignes sur les écrans étroits.
Le détail d'un utilisateur associe son usage par UserId, sans dépendre
du nom affiché. Les erreurs ne déclenchent pas de repli sur l'usage personnel.
Le backend réserve aussi les listes aux administrateurs, sous la
politique AdministratorOnly. Le rôle Moderator seul n'ouvre plus
l'administration de PostIt. L'autorisation serveur reste indispensable,
indépendamment de la visibilité du bouton dans PostIt.
Mon profil réutilise la page de gestion du compte existante et les
endpoints account/me pour lire et enregistrer les informations personnelles.
Elle affiche aussi resource-usage/me, sans appeler la liste des usages
globaux. Une indisponibilité de l'usage n'empêche pas la gestion du profil.
La consommation est chargée avant le profil, pour rester consultable même
si une opération de gestion reçoit un refus de quota. L'administration
charge également les usages avant ses autres outils et les conserve sur
un refus HTTP 429, tant que le rôle administrateur est toujours présent.
L'indicateur est exprimé en points selon les coefficients effectifs du
backend, présentés dans les CGU. Le stockage correspond aux volumes
instrumentés ajoutés, moins les volumes individuellement suivis supprimés
ou remplacés. Les anciens fichiers sans suivi ne sont pas remboursés.
La suppression reste disponible au seuil ; CPU, appels API et transferts
ne sont pas remboursés. Les renommages conservent le suivi individuel.
Le profil et les vues d'administration affichent le seuil effectif, le
solde et l'atteinte du quota, indépendamment de l'estimation financière.
La section serveur ResourceUsage configure les coefficients et les
seuils individuels ; voir INSTALL.md.
Le contrôle admet les coûts connus puis constate les coûts restants :
il bloque les opérations suivantes, sans interrompre strictement celles
déjà en cours.
La page À propos ouvre les CGU dédiées de PostIt et de Yavsc sur
Home/CGU auprès de l'autorité configurée, y compris sans session.
Cette page publique présente les coefficients réellement configurés,
la période cumulée, le seuil et les limites de la mesure.
Mon profil et À propos proposent aussi un lien vers
ResourceSubscription sur cette même autorité. La souscription mensuelle
et la résiliation PayPal utilisent la session Web et des formulaires
antiforgery ; PostIt ne stocke ni identifiant marchand ni secret PayPal.
Le profil affiche la consommation brute, l'usage effacé et le crédit
reporté, en plus de l'indicateur net. Les crédits Découverte/Premium ne
suppriment pas les compteurs : les paiements confirmés sont rapprochés
par Yavsc.Org et leur déduction est appliquée aussi au quota API/Blogs.
Outils d'administration du site
Les outils portés correspondent aux contrôleurs de
Yavsc.Org/Controllers/Administration ; le site web existant est conservé.
Les nouvelles routes vivent dans Yavsc.Api sous api/v1/administration.
Les données passent par des records dédiés de Yavsc.Abstract et par
AdministrationApiClient, jamais par les entités EF.
| Routes | Fonction |
|---|---|
summary, roles, roles/ensure |
Statistiques, informations du runtime, rôles standards |
roles/{id}/members[/{userId}] |
Membres, inscription et exclusion |
clients[/{id}] |
Paramètres scalaires des clients OAuth/OIDC |
clients/{id}/collections/{collection}[/{rowId}] |
Redirect URIs, post-logout URIs, scopes, grant types, CORS, restrictions IdP, claims et propriétés |
clients/{id}/secrets[/regenerate], clients/{id}/secrets/{secretId} |
Ajout, rotation et suppression des secrets |
scopes[/{id}] |
Création, consultation, modification et suppression des scopes API |
mailing-criteria, mailing-templates[/{id}] |
Critères de diffusion et modèles de courriels |
transfer |
Export par GET, import transactionnel par POST |
Les formulaires de clients, scopes et modèles sont construits à partir des propriétés de leurs DTO typés, afin de conserver tous les champs de l'interface web. Les booléens et énumérations disposent de contrôles dédiés ; les valeurs numériques et annotations de validation sont vérifiées avant l'envoi puis à nouveau côté serveur.
Un nouveau client démarre avec authorization_code, PKCE et les scopes
openid et profile. Les autres types d'autorisation restent configurables
dans ses collections. Une rotation remplace tous les secrets précédents et
expire par défaut après 90 jours. Le serveur conserve uniquement le SHA-256
du secret partagé ; les lectures ne rendent que les métadonnées.
PostIt efface la valeur nouvellement créée au changement de client, à la
prochaine opération et au détachement de la page. Une réponse de création
de secret reçue après déconnexion est ignorée ; un rafraîchissement sans
droits efface les données d'administration précédemment chargées. Supprimer un objet,
exclure un membre, remplacer les secrets ou importer demande une confirmation
explicite. Le serveur refuse l'exclusion du dernier administrateur.
Le transfert JSON version 1 comprend les informations métier des comptes (identifiant, nom, e-mail, nom complet, avatar, calendrier et limites de stockage), les billets (contenu, auteur, publication, cercles et étiquettes) et les paramètres des activités. Ce n'est pas une sauvegarde complète de la base : fichiers, sessions, mots de passe, jetons, rôles, moyens de paiement, adresses et historique d'audit ne sont pas transférés. L'e-mail d'un compte existant, clé alternative du modèle actuel, ne peut pas être changé par import. Les nouveaux comptes n'ont ni mot de passe ni e-mail confirmé.
Les identifiants des billets sont préservés et la séquence PostgreSQL est réajustée après l'import. Tous les auteurs et cercles doivent exister et les parents d'activités doivent former un graphe sans cycle. Une erreur annule l'ensemble de l'import ; aucun repli n'élargit les permissions d'un billet. Les fichiers importés et requêtes sont limités à 16 Mio ; les gros exports doivent être répartis en plusieurs transferts de même schéma. Si plusieurs étiquettes portent déjà le même nom, l'import réutilise celle ayant le plus petit identifiant sans supprimer les autres.
L'initialisation du premier administrateur reste le mécanisme web existant,
et n'est pas proposée aux utilisateurs non administrateurs par PostIt.
En développement, /openapi/administration.json décrit uniquement ces outils,
avec accès AdministratorOnly. Les requêtes de référence sont dans
Administration.http ; l'adresse
locale d'exemple est celle du serveur de tests, à adapter au déploiement.
Lecture des billets et fichiers utilisateur
La page des blogs affiche par défaut une vue de lecture : titre, login de l'auteur, date de modification et contenu Markdown dans une zone défilante de largeur limitée. Modifier ouvre l'éditeur existant et Nouveau billet initialise explicitement un brouillon. Lire affiche le contenu enregistré sans effacer les modifications non enregistrées ; un nouveau billet ne peut pas remplacer un brouillon modifié non sauvé.
La base des ressources est dérivée de Settings.Authentication.Authority
(le déploiement Yavsc.Org), jamais de BlogsApiUrl :
https://<hôte Org>/files/<Author.UserName>/. Le repli sur AuthorId
conserve la compatibilité avec les anciens DTO dépourvus d'auteur détaillé.
Un lien photo.jpg ou blogs/42/video.mp4 est relatif à ce répertoire ;
un lien /files/paul/photo.jpg conserve son chemin depuis la racine Org.
Les liens absolus ne sont pas réécrits. Les images Markdown 
sont affichées dans le billet et leur résolveur n'accepte que HTTP(S),
sans accès aux fichiers locaux du poste.
Le résolveur charge chaque image dans un flux mémoire repositionnable
initialement à la position zéro, nécessaire au décodage du lecteur Markdown.
Le lecteur utilise Markdown.Avalonia.Tight 12.0.0-a3 (version compatible
Avalonia 12) pour déléguer les hyperliens à une commande PostIt. L'éditeur
conserve MarkdownViewer.Core : son gestionnaire intégré ouvre le navigateur
avant d'émettre l'événement de lien et ne permet donc pas ce routage.
Au clic sur un fichier sous /files/<login>/... de la même origine Org
(schéma, hôte et port), BlogResourceService sonde Content-Type avec
HEAD, puis un GET limité par Range: bytes=0-0 si le serveur refuse
HEAD (405/501). Le corps n'est pas téléchargé pour la détection. Une
extension connue sert de repli uniquement en l'absence de type exploitable
(type absent ou application/octet-stream). Les erreurs HTTP/réseau sont
affichées dans la barre de statut, sans les masquer par une déduction MIME.
Les types video/* ouvrent VideoPage via App.PushPageAsync sur desktop.
Cette page contient un LibVLCSharp.Avalonia.VideoView, lecture/pause et
une action d'ouverture externe. Le lecteur et ses ressources natives sont
arrêtés et libérés à la sortie de la page. La lecture utilise directement
new LibVLC(), new MediaPlayer(libVlc) et Play(media), sans options
spécifiques à Linux ni détection VAAPI/VDPAU. Le média est libéré après
Play comme dans l'exemple officiel ; le lecteur conserve sa référence native.
LibVLC doit être installé
sur le poste (par exemple libvlc5 et les plugins VLC sur Linux ; les
bibliothèques natives adaptées sont nécessaires sous Windows/macOS).
Une absence de LibVLC ou une erreur de décodage est signalée dans la page.
Le navigateur ne s'ouvre que sur demande explicite, jamais en repli automatique.
Après la navigation, TryUpdateNativeControlPosition() synchronise la surface
native à la priorité Loaded, une fois la mise en page effectuée :
les transformations de transition ne déclenchent pas de changement de Bounds.
Le rappel est ignoré si le lecteur a été libéré ou remplacé entre-temps.
Sur Android et Browser, où ce contrôle natif desktop n'est pas disponible,
les vidéos sont ouvertes dans le navigateur, comme les autres fichiers
(images liées, PDF, téléchargements) et les liens externes.
ViewLocator custo
Le ViewLocator (cf. src/PostIt/PostIt/ViewLocator.cs) est un
IDataTemplate Avalonia explicitement câblé sur le
IServiceProvider :
public Control Build(object? data) => data switch
{
MainPageViewModel => _services.GetRequiredService<MainPage>(),
Settings => _services.GetRequiredService<SettingsPage>(),
HomePageViewModel => _services.GetRequiredService<HomePage>(),
SignaturePageViewModel => _services.GetRequiredService<SignaturePage>(),
null => new TextBlock { Text = "No view for <null>" },
_ => new TextBlock { Text = $"No view for {data.GetType().Name}" }
};
public bool Match(object? data) => data is ViewModelBase;
Pourquoi un custo, et pas le ViewLocatorBase par défaut
d'Avalonia.Mvvm ? Pour deux raisons :
- Sortie du
Activator.CreateInstance— les pages PostIt sont enregistrées dans le DI et peuvent avoir des dépendances (par construction, aujourd'hui aucune, mais l'extension future est ouverte). LeViewLocatorBasehistorique faitnew View(), ce qui rend impossible l'injection et complique les tests. - Filtrage par
ViewModelBase—Matchn'accepte que les types dérivés deViewModelBase. Toute tentative d'afficher un objet métier (par ex. un DTO de l'API Yavsc) tombe sur leTextBlock"No view for X", pas sur un crash Avalonia.
Le ViewLocator est ajouté aux DataTemplates de l'app dans
App.OnFrameworkInitializationCompleted :
DataTemplates.Clear();
DataTemplates.Add(new ViewLocator(provider));
Conséquence pratique : pour qu'une nouvelle page soit
affichée par un ContentControl qui binde un ViewModel, il
faut deux enregistrements : la page en AddTransient (ou
AddSingleton) dans le DI, et une case dans le switch
de ViewLocator.Build. Si l'un manque, l'app affiche
"No view for X" sans crash.
Podcasts : capture, direct et replay
PodcastsPageViewModel est accessible depuis l'accueil Desktop Windows/Linux.
CameraStreamer detecte les cameras DirectShow/V4L2 et les microphones
(DirectShow sous Windows, source PulseAudio par defaut sous Linux).
PodcastBroadcaster utilise uniquement LibVLC : encodage H.264/AAC, sortie
livehttp, segments MPEG-TS d'environ deux secondes. Un segment n'est
envoye que lorsque l'index local LibVLC le declare complet.
PodcastApiClient reutilise le transport bearer et son rafraichissement
des jetons. Les PUT sont numerotes a partir de zero ; une nouvelle tentative
doit avoir exactement les memes octets et la meme duree. Le client supprime
un segment local seulement apres acquittement, et envoie le dernier segment
ferme par LibVLC avant de terminer le direct. La navigation et la deconnexion
arretent la camera. Les erreurs restent visibles ; les fichiers non envoyes
restent disponibles localement pour recuperation manuelle.
ILiveProcessor est un singleton dans Yavsc.Api. Il stocke les metadonnees
et empreintes SHA-256 dans un index JSON remplace atomiquement, avec des
segments immuables accessibles uniquement via les endpoints authentifies.
Deux receptions au plus sont tamponnees en parallele ; les validations de
sequence, de proprietaire et de quota sont serialisees avant commit.
Un index ne reference jamais un segment en cours d'ecriture.
Route sous api/v1/podcasts |
Role |
|---|---|
GET /, POST / |
Catalogue ou creation d'une emission |
GET /{id} |
Metadonnees et segments ordonnes |
PUT /{id}/segments/{sequence}?duration=... |
Ingestion video/mp2t, auteur uniquement |
POST /{id}/complete |
Finalisation idempotente du replay |
GET /{id}/index.m3u8 |
Playlist HLS EVENT, ENDLIST apres fin/interruption |
GET /{id}/segments/{sequence}.ts |
Segment engage, lecture authentifiee |
DELETE /{id} |
Suppression d'une emission terminee, auteur uniquement |
Toutes les routes requierent la politique ApiScope. La lecture est ouverte
a tous les utilisateurs authentifies avec ce scope, pas seulement a l'auteur.
PodcastMediaInput alimente LibVLC en octets MPEG-TS via les requetes
authentifiees existantes, sans transmettre de jeton dans une URL ou un
processus externe. Les rappels natifs ne laissent echapper aucune exception :
l'erreur est remontee a la page de lecture.
Un direct inactif devient Interrupted lors de la prochaine lecture de
l'index ; au redemarrage, tous les anciens directs sont interrompus.
Les segments engages constituent le replay, sans transcodage serveur.
Le stockage exige un seul processus par racine et les quotas podcast sont
independants de ceux des fichiers utilisateur. Voir
INSTALL.md pour
les limites et le deploiement ; Podcast.http
pour les requetes.
Le document OpenAPI dedie est /openapi/podcasts.json, accessible en
developpement aux administrateurs comme les autres documents de l'API.
Composition root (App.axaml.cs)
App.OnFrameworkInitializationCompleted est le seul endroit où
le DI est construit. Ordre, dans cet ordre :
new Settings()+settings.Load()— lit~/.config/PostIt/postit-settings.json(ou le fallback embarqué dansPostIt.dll).new TokenStore(...)+new YavscApiClient(settings, tokenStore).new ServiceCollection()+ enregistrements en bloc.services.BuildServiceProvider().Settings.BindToServiceProvider(provider)— pose le singleton statique pour les helpers hors-DI (Settings.GetCurrent(),Settings.RequireCurrent()).DataTemplates.Add(new ViewLocator(provider)).- Branche
IClassicDesktopStyleApplicationLifetime/ISingleViewApplicationLifetime(Browser/Android).
Enregistrements DI
| Service | Lifetime | Pourquoi |
|---|---|---|
Settings |
Singleton | État partagé (Loaded, IsDirty, Authentication) — doit être unique. |
YavscApiClient |
Singleton | Porte le TokenStore et le cache de tokens ; un seul par process. |
BlogApiClient |
Singleton | Mapper stateless, partagé. |
SettingsPage |
Singleton | Une seule instance pour la vie de l'app : le DataContext est câblé une fois au boot, le push est idempotent (cf. section Garde anti-empilement ci-dessous). |
MainPage / HomePage / SignaturePage |
Transient | Résolution à la demande par le ViewLocator. |
MainPageViewModel / HomePageViewModel / SignaturePageViewModel |
Transient | VM reconstruites à chaque navigation ; pas d'état partagé à conserver. |
SessionStatusViewModel + SessionStatusBanner |
Singleton + Transient | Le VM est un singleton (survit à la navigation), le bandeau est transient (réinstancié quand la fenêtre le recrée). |
Invariant :
Settingsest uniquement un singleton. UnAddTransient<Settings>()supplémentaire (qui réécrase le singleton dans le container) ferait que chaque push deSettingsPagecrée une instance vide, casse les bindings Authority/ClientId, et perd toute édition. Si tu dois toucher à cette table, ne pas ajouter de registration pourSettingsailleurs que la ligneAddSingleton(settings).
Défilement de la page des billets
La page BlogsPage utilise une grille à hauteur contrainte : l'en-tête
et les commandes restent visibles, tandis que la liste des billets et
l'éditeur se partagent l'espace disponible. Un GridSplitter permet
de modifier cette répartition. La liste et l'article défilent séparément.
Lorsque la largeur de la fenêtre atteint ou dépasse sa hauteur, le lecteur ou l'éditeur passe à gauche (deux tiers de la largeur par défaut), et l'en-tête, la recherche et la liste passent à droite ; les commandes restent dans la barre de navigation. Le séparateur devient vertical. En portrait, la disposition verticale revient sans recréer les contrôles ni perdre le brouillon. Le seuil utilise les dimensions clientes de la fenêtre, indépendamment de la hauteur occupée par la navigation et la bannière de session.
La page applique NavigationPage.BarHeightOverride à 36 en mode large ;
le NavRoot de MainView conserve ainsi le bouton Retour, sans changer
les autres pages. En portrait, la hauteur de navigation par défaut revient.
Les commandes ont un contexte de données explicite pour conserver leurs
liaisons, y compris lorsqu'elles passent dans le menu de débordement.
Dans MarkdownEditorControl, AvaloniaEdit gère son propre défilement ;
l'aperçu Markdown est placé dans un ScrollViewer. Ne pas limiter
la hauteur du MarkdownViewer lui-même : son contenu doit pouvoir
dépasser le viewport pour que les barres automatiques s'activent.
Ne pas placer cette grille dans un StackPanel vertical ou un
ScrollViewer de page, qui lui donnerait une hauteur de mesure illimitée.
Après un redimensionnement de la zone de texte (notamment à l'ouverture du
clavier Android avec AdjustResize), l'éditeur remet le curseur dans son
viewport après la mise en page, uniquement s'il garde le focus. Un toucher
dans la zone éditable demande aussi le clavier via le pont natif Android,
sans retirer puis redonner le focus ni modifier la sélection. Les autres
plateformes conservent leur gestion habituelle du clavier.
MainView compose les marges de TopLevel.InsetsManager (barres système
et découpes) avec le recouvrement réel indiqué par TopLevel.InputPane,
car le clavier ne redimensionne pas toujours la fenêtre Android en mode
edge-to-edge. Si AdjustResize a déjà réduit la fenêtre, cette réserve
ne soustrait pas une seconde fois la hauteur du clavier. La racine gère
explicitement ces marges et désactive TopLevel.AutoSafeAreaPadding pour
éviter deux propriétaires du même padding. Ne pas remplacer les marges
système par un padding contenant uniquement la hauteur du clavier.
En disposition large, tant que le clavier est ouvert et que l'article
garde le focus, son titre et ses pièces jointes passent dans
une colonne à côté du texte. La barre de commandes, la bannière de session
et le statut restent visibles. La disposition habituelle revient à la
fermeture du clavier ou au changement de focus, sans recréer le brouillon.
Sous Android uniquement, le champ du titre est masqué pendant la saisie
compacte avec le clavier ouvert, en portrait comme en paysage ; il réapparaît à la fermeture du clavier
ou quand le focus quitte l'article. Sa valeur n'est jamais effacée.
En Debug Android, fr.pschneider.postit.MarkdownEditorTestActivity ouvre
un billet synthétique local, vérifie au moins trois lignes visibles et
le bas de l'éditeur au-dessus des insets natifs du clavier et les contrôles
en dehors des barres système,
ferme puis rouvre le clavier par toucher sans perte de focus. Le résultat
est écrit dans files/markdown-editor-test-result.txt. Ce test nécessite
Android 11 ou plus pour vérifier les insets du clavier ; il ne publie
aucun billet et retire sa page à la fin.
L'extra booléen landscape=true force le paysage pendant le test et restaure
l'orientation demandée précédemment à la fin.
Navigation
Le host de navigation est un NavigationPage x:Name="NavRoot"
posé sur MainWindow.axaml. La pile est gérée par deux
mécanismes distincts :
-
Nav utilisateur (VM-first) : un ViewModel (souvent dans une commande
[RelayCommand]) appelleawait ((App)App.Current!).PushPageAsync(targetVm).ConfigureAwait(true);.App.PushPageAsync(src/PostIt/PostIt/App.axaml.cs) résout laControlcorrespondante via leViewLocatorenregistré dansApplication.DataTemplates, l'identifie commePage, lui assigne le VM commeDataContext, et appelleNavRoot.PushAsync(page). C'est le seul chemin pour les boutons de la toolbar, lesOpenSettings/OpenCircles/ManageAcl/OpenSignatureDev, et toute autre nav déclenchée par un ViewModel. -
Signaux de cycle de vie : le
SessionStatusViewModellève des événements consommés dansApp.OnFrameworkInitializationCompletedpour orchestrer la nav de boot :Événement Effet LoginSucceededPushAsync(MainPage)au-dessus deHomePage(post-login).LogoutCompletedPopToRootAsync()(revient àHomePage).Ces events ne sont pas un canal de nav utilisateur ; ils portent une transition d'état applicatif (authentification établie / perdue) et c'est
Appqui choisit d'en faire une transition de pile.
Garde anti-empilement
NavigationPage.PushAsync n'est pas idempotent : pousser deux
fois la même instance l'empile deux fois, et l'utilisateur doit
taper Retour N fois pour sortir. La garde est implémentée
dans App.PushPageAsync (et consommée par tous les chemins
de nav utilisateur) :
var stack = window.NavRoot.NavigationStack;
if (stack.Count > 0 && ReferenceEquals(stack[stack.Count - 1], page))
{
return Task.CompletedTask; // déjà au sommet, no-op silencieux
}
return window.NavRoot.PushAsync(page);
La comparaison est par référence, pas par type : on ne veut
empêcher qu'un push de cette instance particulière, pas
celui d'une éventuelle autre SettingsPage (il n'en existe
qu'une, mais l'invariant est plus clair comme ça). La garde
repose sur le fait que SettingsPage est un singleton ; si on
repassait en Transient, ReferenceEquals resterait correct
mais la pertinence de la garde s'évaporerait (chaque push
apporterait une nouvelle instance et l'anti-empilement
reposerait sur l'invariant « la même est déjà au sommet »,
qui ne tiendrait plus).
ViewModels et invariants d'état
-
Settingsest un objet-modèle exposé commeDataContextdes pages. Il n'hérite pas deViewModelBase(c'est un POCO[ObservableProperty]-généré parCommunityToolkit.Mvvm). Le fait qu'il soit utilisé comme DataContext est un raccourci de composition acceptable ici, pas un pattern à généraliser. -
SessionStatusViewModelest le seul VM avec une durée de vie process-entière (singleton). Il survit à toutes les navigations, exposeHasValidSessionen continu, et porte les événements de cycle de vie consommés parApppour orchestrer la nav de boot (LoginSucceeded,LogoutCompleted). La nav utilisateur déclenchée par l'utilisateur passe parApp.PushPageAsync(vm), pas par un événement duSessionStatusViewModel. -
MainPageViewModel/HomePageViewModel/SignaturePageViewModelsontTransient— une nouvelle instance est créée à chaque push, l'ancienne est libérée quand la page est dépilée. Pas d'état partagé entre occurrences ; pour passer une donnée d'une page à l'autre, on passe par un singleton (souventYavscApiClientouSettings).
Bindings XAML : conventions de nommage
Pour les [RelayCommand] (cf. CommunityToolkit.Mvvm), le
binding XAML reprend le nom exact de la méthode, sans
suffixe :
| Méthode C# | Binding XAML |
|---|---|
Save() |
{Binding Save} |
SaveAsync() |
{Binding SaveAsync} |
LoginCommand() |
{Binding LoginCommand} (nom littéral, pas de suffixe ajouté) |
Clear() |
{Binding Clear} |
CaptureAsync() |
{Binding CaptureAsync} |
JAMAIS SaveCommand, SaveCmd, DoSave, etc. Le source
generator [RelayCommand] émet une propriété ICommand du
même nom que la méthode. Un binding qui pointe vers une
propriété inexistante casse l'app au moment du câblage (le
bouton ne se câble pas, et selon la version ça peut faire
planter l'init de la page).
Référence canonique : AGENTS.md, section
"Avalonia + CommunityToolkit.Mvvm : conventions de binding
pour [RelayCommand]".
Pages et leurs rôles
| Page | DataContext | Rôle |
|---|---|---|
MainWindow |
HomePageViewModel (initial) |
Host de la NavigationPage. |
SessionStatusBanner |
SessionStatusViewModel |
Bandeau persistant en haut de la fenêtre, visible sur toutes les pages. Boutons Login / Logout / Paramètres. |
HomePage |
HomePageViewModel |
Page d'accueil publique. |
MainPage |
MainPageViewModel |
Éditeur de post de blog (après login). |
SignaturePage |
SignaturePageViewModel |
Capture de signature (estimateur). |
SettingsPage |
Settings |
Édition de Authority / ClientId / Scopes / URLs API / Dark mode. Sauver via Save (RelayCommand). |
Conséquences pratiques
- Ajouter une page : créer la View + le ViewModel +
enregistrer les deux dans le DI et dans le
switchdeViewLocator.Build. Oublier leViewLocatorest silencieux (juste un TextBlock "No view for X"), pas une exception. - Ajouter un événement global de navigation (par ex.
"Push après payment success") : ne pas capturer
MainWindowniNavigationPagedepuis le VM. La nav passe parApp.PushPageAsync(vm)dans tous les cas : soit le VM appelle la méthode directement depuis une commande ([RelayCommand]), soit un handler abonné à un événement d'un singleton (cf.SessionStatusViewModel) l'appelle. Garder les VMs découplés duIClassicDesktopStyleApplicationLifetime. - Modifier l'OIDC : la fiche à lire est postit-oidc.md, pas celle-ci. Cette fiche ne ré-explique ni le flow, ni le pipe, ni le custom scheme.
- Modifier les
Settings: ne pas casser le singleton (cf. invariant ci-dessus). Toute propriété présentationnelle ajoutée (par ex.ScopeListText) doit porter[JsonIgnore]pour ne pas polluer le format sur disque.
Voir aussi
- Architecture.md — racine.
- postit-oidc.md — flow OIDC, custom scheme, silent refresh, persistance des tokens.
- decoupage-organisation.md —
place de
PostItdans le découpage global des projets .NET du repo.