SPB Git

Repository Public

README.md 45.1 KB

SP Chat logo



SP Chat icon

# SP Chat — iOS et iPadOS

Application native (Swift 6, SwiftUI, UIKit là où il le faut) du chat privé multi-modèles de Simon-Pierre Boucher : même compte, mêmes conversations et mêmes fichiers que chat.spboucher.ai et que l'app macOS. Aucune vue web : chaque écran est du SwiftUI.

Author: Simon-Pierre Boucher

chat.spboucher.ai version plateforme langues licence author

Swift SwiftUI UIKit SwiftMath SQLite AuthenticationServices LocalAuthentication App Intents Swift Charts Swift Testing XcodeGen Xcode

commits last commit activity language languages size branches tags clones

fichiers Swift lignes Swift appels REST événements SSE tables locales tests unitaires et intégration tests d'interface chaînes localisées vues web dépendances

bundle appareils signature TestFlight App Store Connect backend


# Sommaire


# 📖 Aperçu

SP Chat pour iOS et iPadOS est le client natif du chat privé multi-modèles (OpenAI, Anthropic, xAI en route directe, et le catalogue OpenRouter — environ 450 modèles) hébergé sur https://chat.spboucher.ai. Il parle au même backend, avec la même API REST + SSE que le site : aucune API parallèle, aucune donnée dupliquée. Le serveur reste la source de vérité ; l'app garde une copie de lecture chiffrée par iOS et une boîte d'envoi pour écrire hors ligne.

L'app est mono-propriétaire : un seul compte, protégé par des clés d'accès (passkeys). Le cahier des charges d'origine est le brief « SP Chat Native iOS » du 2026-11-17 : reconstruction native intégrale, aucune vue web, parité avec le site, passkeys, synchronisation, streaming, distribution TestFlight.

Identifiant ai.spboucher.spchat (équipe 3YM54G49SN), iPhone + iPad, iOS 18.0 et plus
Version 2.0.0 (2) « Next Generation » — prête, à envoyer après le déploiement du backend 1.0 ; sur TestFlight : 1.0.0 (1) du 2026-11-17 (App Store Connect : app 6836172251)
Langues français (langue source), anglais — 1 058 chaînes, toutes traduites
Dépendance SwiftMath 1.7.3 (composition LaTeX native, CoreText) — la seule
Code 94 fichiers Swift, 19 487 lignes ; 163 tests unitaires / d'intégration (dont 25 de bout en bout contre le vrai serveur de dev) + 13 tests d'interface, iPhone et iPad

Documents du dépôt : extension de partage (conception, en attente) · matrice de parité · état par fonction et limites connues · distribution · règles et pièges du projet

# Famille SP Chat

Dépôt Rôle Plateforme
chat-spboucher-ai Backend + site web (Next.js, PostgreSQL + pgvector), chat.spboucher.ai web
sp-chat Client natif macOS (Developer ID, notarisé) macOS
sp-chat-ios Client natif iPhone et iPad (ce dépôt) iOS / iPadOS

L'identifiant d'app ai.spboucher.spchat est partagé avec l'app macOS : voir Pièges connus.


# 🚀 Version 2.0 « Next Generation »

Mise à niveau majeure de l'app existante (même architecture, toutes les fonctions de la 1.0 conservées) pour le backend 1.0 et le système visuel V2 « Graphite & Iris · Lumen » : toile graphite, une seule lumière iris, vrais logos des créateurs.

Réponse avec sources Feuille des modèles
Réponse d'un modèle OpenRouter avec recherche web : ligne d'outil, cartes de sources, coût facturé, suggestions de suite Feuille des modèles : dock des favoris, routage, récents, vérifiés, catalogue OpenRouter
Fiche d'un modèle Arène
Explorateur → Live Model Intelligence : chaque chiffre avec sa source Arène : le même prompt à plusieurs modèles, mesures et coût
  • Catalogue unifié, trois routes : modèles directs vérifiés par le banc, catalogue OpenRouter (or:…) et inférence locale MacLustr AI (local:…, coût « local · 0 $ ») ; logo du créateur, nom exact, badge de route « OPENROUTER » ou « LOCAL », état « non testé » dit partout où c'est vrai.
  • Compositeur signature : capsule flottante, pièces jointes, dictée, outils du tour, recherche web, puce de modèle (appui long = dock), effort et options, commandes rapides /, mention @modèle, ligne lumen pendant la génération.
  • Explorateur de modèles : recherche, filtres, tri, comparaison côte à côte, fiche détaillée.
  • Fournisseurs : test des clés, clés OpenRouter et Tavily définies / remplacées / révoquées sur le serveur (jamais enregistrées ni affichées sur l'appareil).
  • Synchronisation en direct : flux d'événements du serveur, rattrapage au retour au premier plan, brouillons hors ligne.
  • Arène, lentilles de réponse, chronologie et relecture, branches, inspecteur de contexte, centre de commandes (⌘K), constellation, recherche avancée, coûts par route / facturé ou estimé, prompts à variables, édition des projets, instructions permanentes, recherche approfondie, studio d'images.

Toutes les captures (clair et sombre, iPhone et iPad) : docs/img/v2/. État vérifié, non vérifié et limites : docs/IMPLEMENTATION_STATUS.md.


# ✨ Fonctions

# Conversation

  • Envoi et streaming SSE en temps réel, avec les états de fin : complet, arrêté, incomplet, erreur.
  • Générations détachées : la réponse continue sur le serveur si la connexion tombe ; l'app se réattache à partir du dernier événement reçu, sans doublon.
  • Arrêt réel d'une génération (annulation côté serveur).
  • Régénérer, modifier un message, versions ‹ n / m ›, bifurquer vers une nouvelle conversation.
  • Approbation d'appels d'outils (implémentée ; aucun outil du serveur n'est en mode « approbation » aujourd'hui).
  • Brouillons serveur : enregistrés 1,5 s après la dernière frappe, ils suivent le compte sur le web et le Mac.

# Rendu riche, sans vue web

  • Markdown natif : titres, listes, citations, tableaux.
  • Blocs de code colorés avec bouton de copie (SyntaxHighlighter, CodeBlockView).
  • Équations LaTeX en bloc et en ligne, composées par SwiftMath (CoreText).
  • Raisonnement repliable, cartes d'outils, citations, images générées.
  • Jetons, coût et latence par réponse ; feuille de détails avec les paramètres réellement envoyés.
  • Artefacts : source colorée et partage du fichier (pas d'aperçu exécuté — choix : aucune vue web).

# Modèles

  • Feuille des modèles : dock des favoris, récents, modèles vérifiés par le banc d'essai (route directe) et catalogue OpenRouter avec recherche instantanée ; les modèles indisponibles ou non pris en charge ne sont jamais proposés (AIModel.isSelectableForChat).
  • Routeurs auto / rapide / qualité / économie, profils (presets), effort de raisonnement, outils activés ou non.

# Organisation

  • Liste des conversations en sections par date ; filtres : toutes, favoris, épinglées, archives, projet ; filtre par titre.
  • Renommer, épingler, mettre en favori, archiver, déplacer vers un projet, supprimer (avec confirmation).
  • Recherche globale plein texte + sémantique.
  • Prompts enregistrés, mémoire (lister, ajouter, activer / désactiver, supprimer), projets (filtrer, créer, classer).
  • Dépenses : limites jour / mois, graphique (Swift Charts), ventilation par modèle.
  • Export d'une conversation (Markdown / JSON) et export complet.

# Pièces jointes et voix

  • Photothèque, appareil photo, app Fichiers, glisser-déposer, collage d'image ; progression et annulation ; réduction des photos et conversion HEIC → JPEG.
  • Aperçu Quick Look, bibliothèque de fichiers.
  • Dictée (transcription par le serveur) et lecture à voix haute.

# Propre à iOS et iPadOS

Fonction Où
Lecture hors ligne des conversations déjà téléchargées (SQLite chiffré par iOS) LocalStore
Boîte d'envoi : message écrit hors ligne, marqué « non envoyé », posté une seule fois au retour du réseau ChatSession, AppEnvironment.flushOutbox
Verrouillage par Face ID / Touch ID (activé par défaut après connexion), masque dans le sélecteur d'apps AppLock, LockView
iPad : barre latérale persistante, Split View / Slide Over, glisser-déposer, raccourcis clavier MainView, SPChatApp.commands
Liens profonds spchat://c/<id>, spchat://new?text=, liens universels https://chat.spboucher.ai/c/<id> AppEnvironment.handle(url:)
Raccourcis Siri / Shortcuts : « Nouvelle conversation », « Demander à SP Chat » SystemIntegration.swift
Retours haptiques, notification locale « réponse prête », rafraîchissement en arrière-plan Haptics, AppEnvironment, BackgroundSync

# Raccourcis clavier (iPad, clavier matériel)

Raccourci Action
⌘N Nouvelle conversation
⌘⇧F Rechercher dans les messages
⌘L Écrire un message (focus sur le compositeur)
⌘. Arrêter la réponse
⌘⇧C Copier la dernière réponse
⌘R Actualiser
⌘, Réglages

La matrice complète, fonction par fonction, avec l'état (opérationnel et testé / vérification partielle / non porté) et le test qui le prouve, est dans docs/PARITY_MATRIX.md.


# 🧭 Architecture

Principes : état observable (@Observable, @MainActor), services injectés par AppEnvironment (aucun singleton de service), réseau et base derrière des acteurs, logique de flux dans un réducteur pur testable, Swift 6 en concurrence stricte (0 avertissement dans le code de l'app).

flowchart TB
  subgraph App["App iOS / iPadOS (SwiftUI)"]
    UI["Features + Components<br/>Chat, Conversations, Search, Settings, Account…"]
    ENV["AppEnvironment<br/>injection, routeur, boîte d'envoi"]
    SES["ChatSession<br/>envoi, followLoop, arrêt"]
    RED["StreamReducer (pur)"]
    SSE["SSEParser<br/>octets → événements"]
    API["ChatAPI<br/>routes REST + flux"]
    HTTP["HTTPClient (acteur)<br/>cookie de session, Origin, rotation, 401/403"]
    AUTH["AuthStore + PasskeyService"]
    KC["Trousseau<br/>jeton de session"]
    DB[("LocalStore — SQLite<br/>cache + boîte d'envoi")]
    LOCK["AppLock<br/>LocalAuthentication"]
  end
  subgraph Cluster["MacLustr"]
    TUN["MacLustr Tunnel<br/>Caddy + WireGuard"]
    BE["chat-spboucher-ai<br/>Next.js · M4M64c:8500"]
    PG[("PostgreSQL 17 + pgvector")]
    LLM["OpenAI · Anthropic · xAI"]
  end
  UI --> ENV --> SES --> API --> HTTP
  SES --> RED
  SSE --> RED
  API --> SSE
  ENV --> AUTH --> HTTP
  AUTH --> KC
  ENV --> DB
  ENV --> LOCK
  HTTP -- "HTTPS · REST + SSE" --> TUN --> BE --> PG
  BE --> LLM

# Connexion par clé d'accès

sequenceDiagram
  autonumber
  participant U as Propriétaire
  participant A as SP Chat (iOS)
  participant S as chat.spboucher.ai
  A->>S: POST /api/auth/login/options
  S-->>A: défi à usage unique (lié à un cookie de cérémonie)
  A->>U: feuille système des clés d'accès
  U-->>A: Face ID / Touch ID / code / appareil voisin / clé de sécurité
  A->>S: POST /api/auth/login/verify (assertion signée)
  S-->>A: Set-Cookie session (jeton opaque)
  A->>A: jeton rangé dans le Trousseau
  Note over A,S: à chaque vérification le serveur fait tourner le jeton, l'app remplace sa copie

# Un tour de conversation, avec reprise après coupure

sequenceDiagram
  autonumber
  participant A as ChatSession
  participant S as Backend
  A->>S: POST /api/chat (clientRequestId = clé d'idempotence)
  S-->>A: SSE run, conversation, start
  S-->>A: SSE text / reasoning / tool_call / tool_result / part…
  Note over A,S: la connexion tombe — la génération continue sur le serveur
  A->>S: GET /api/chat/stream?run=…&after=dernier id reçu
  S-->>A: SSE (suite numérotée, battement toutes les 15 s)
  S-->>A: SSE usage, status, done, end
  A->>A: StreamReducer → état final, copie locale mise à jour

# 🧰 Pile technique

Couche Technologie Version Rôle
Langage Swift 6.0, SWIFT_STRICT_CONCURRENCY: complete tout le code
Interface SwiftUI (+ UIKit ponctuel) SDK iOS 27.2 (Xcode 27.2) tous les écrans, aucune vue web
Cible iOS / iPadOS 18.0 et plus, familles 1,2 iPhone + iPad ; ni Catalyst, ni « Designed for iPad » sur Mac, ni visionOS
Mathématiques SwiftMath 1.7.3 (version exacte) composition LaTeX par CoreText
Authentification AuthenticationServices système passkeys WebAuthn
Verrouillage LocalAuthentication système Face ID / Touch ID
Session Security (Trousseau) système jeton AfterFirstUnlockThisDeviceOnly
Persistance SQLite 3 (API C) système cache de lecture + boîte d'envoi
Réseau URLSession système REST, multipart, flux SSE
Graphiques Swift Charts système écran des dépenses
Système App Intents, BackgroundTasks, notifications locales système raccourcis Siri, rafraîchissement, « réponse prête »
Projet XcodeGen project.yml génère SPChat.xcodeproj
Tests Swift Testing + XCUITest Xcode 27.2 unitaires, intégration, bout en bout, interface
Publication xcodebuild, altool, API App Store Connect — archive, IPA, TestFlight

# 📁 Arborescence du dépôt

text
sp-chat-ios/
├── project.yml                 définition XcodeGen (3 cibles : SPChat, SPChatTests, SPChatUITests)
├── SPChat.xcodeproj/           projet généré (versionné, avec Package.resolved)
├── CLAUDE.md                   règles du projet, recettes, pièges rencontrés
├── Design/                     AppIcon.svg, AppIcon-Dark.svg, AppIcon-Tinted.svg, Mark.svg
├── SPChat-iOS/
│   ├── App/            (5)  SPChatApp (scènes, commandes clavier), AppEnvironment (injection), AppConfiguration, RootView, SystemIntegration
│   ├── Core/           (17)
│   │   ├── Models/         DTO du backend (décodage tolérant), parties de message typées
│   │   ├── Networking/     HTTPClient (acteur : cookie de session, Origin, rotation, 401/403), APIError, NetworkMonitor
│   │   ├── API/            ChatAPI : toutes les routes REST + ouverture des flux
│   │   ├── Streaming/      SSEParser (octets → événements), ChatStreamEvent, StreamReducer (pur)
│   │   ├── Authentication/ PasskeyService (AuthenticationServices), AuthStore
│   │   ├── Security/       Keychain, AppLock (LocalAuthentication)
│   │   └── Persistence/    LocalStore (SQLite : cache + boîte d'envoi), Preferences
│   ├── Features/       (15) Chat, Conversations, ModelSelection, Attachments, Search, Voice, Settings, Account, Library
│   ├── Components/     (11) ChatBubble, ChatComposer, ConversationList, ModelPicker, MarkdownParser/Renderer, CodeBlockView, MathView, SyntaxHighlighter, Haptics, Theme
│   ├── Resources/           Assets.xcassets (icône claire / sombre / teintée, palette « Graphite & Iris » : 20 couleurs), Localizable.xcstrings, Info.plist, Info-Debug.plist, droits, PrivacyInfo
│   ├── Tests/          (4)  Swift Testing : cœur, sessions (serveur scénarisé), bout en bout, support
│   └── UITests/        (1)  XCUITest contre le serveur de développement
├── Scripts/
│   ├── build.sh             generate | debug | release | test | uitest
│   ├── test-live.sh         tunnel + session de dev, puis tests
│   ├── dev-session.sh       crée / renouvelle une session dans la base *_dev
│   ├── release.sh           archive | export | upload | all
│   ├── ExportOptions.plist  export « app-store-connect », signature automatique
│   └── asc.py               appels à l'API App Store Connect
└── docs/
    ├── PARITY_MATRIX.md         web ↔ iOS, fonction par fonction
    ├── IMPLEMENTATION_STATUS.md vérifié / non vérifié / limites
    ├── DISTRIBUTION.md          signature, TestFlight, nouvelle version
    └── brand/                   logo.svg, icon.png (ce README)

Lignes Swift par dossier : App 567 · Core 2 526 · Components 1 946 · Features 2 335 · Tests 965 · UITests 196.


# 🚀 Construire et tester

Prérequis : Xcode 27 et XcodeGen. Le projet Xcode est généré : après avoir ajouté un fichier, relancer Scripts/build.sh generate.

bash
Scripts/build.sh generate      # xcodegen → SPChat.xcodeproj (+ Info-Debug.plist)
Scripts/build.sh debug         # build simulateur
Scripts/build.sh release       # build Release pour simulateur générique
Scripts/build.sh test          # tests unitaires et d'intégration (serveur scénarisé)
Scripts/test-live.sh test      # + bout en bout contre le serveur de DÉVELOPPEMENT (tunnel M4M64c:8510, session de la base *_dev)
Scripts/test-live.sh uitest    # tests d'interface (SPCHAT_SIM="iPad Pro 13-inch (M5)" pour l'iPad) ; captures dans build/shots/
Scripts/release.sh all         # archive Release signée + IPA App Store ; Scripts/release.sh upload → TestFlight
  • La sortie de xcodebuild est filtrée (erreurs, suites, totaux) ; le journal complet est dans build/logs/.
  • Le simulateur par défaut est iPhone 17 Pro ; SPCHAT_SIM le remplace.
  • Les tests de bout en bout ne touchent jamais la production : Scripts/dev-session.sh refuse toute base qui n'est pas *_dev. Ils font quelques appels réels au modèle le moins cher (fraction de cent).

# 🔧 Configuration

Aucun secret dans le dépôt ni dans le binaire. Noms seulement :

Nom Où Rôle
SPChatBaseURL Info.plist origine du backend (production : https://chat.spboucher.ai)
SPCHAT_BASE_URL environnement (tests, debug) remplace l'origine, ex. le serveur de dev par le tunnel local
SPCHAT_DEBUG_SESSION environnement (tests) jeton d'une session de la base de dev, injecté sans passkey
SPCHAT_UI_TESTS environnement (XCUITest) lance l'app dans un bac isolé (dossier et UserDefaults propres)
SPCHAT_UI_MODEL, SPCHAT_UI_THEME environnement (XCUITest) modèle et thème imposés pendant un test d'interface
SPCHAT_LIVE_MODEL environnement (tests live) modèle utilisé par les tests de bout en bout
SPCHAT_SIM Scripts/build.sh nom du simulateur
SPCHAT_DEV_NODE Scripts/test-live.sh, dev-session.sh nœud qui héberge le serveur de dev (défaut M4M64c)
ASC_KEY_ID, ASC_ISSUER_ID Scripts/release.sh clé d'API App Store Connect (le fichier .p8 reste hors dépôt, dans ~/.appstoreconnect/private_keys/)

Info-Debug.plist est Info.plist avec NSAllowsLocalNetworking = true (le build Debug peut joindre le serveur de dev par http://localhost:8510) ; il est régénéré par Scripts/build.sh generate. En Release, App Transport Security interdit tout chargement arbitraire et tout réseau local.

Autres réglages du bundle : schéma d'URL spchat, tâche d'arrière-plan ai.spboucher.spchat.sync (mode fetch), scènes multiples, catégorie « productivité », ITSAppUsesNonExemptEncryption = false.


# 🔌 API consommée

Core/API/ChatAPI.swift et Core/Authentication appellent 55 opérations (méthode + chemin) du backend chat-spboucher-ai. Toute mutation porte Origin: https://chat.spboucher.ai.

Tableau des routes
Domaine Méthode et chemin Usage
Authentification GET /api/auth/state état de la session
POST /api/auth/login/options · /login/verify connexion par passkey
POST /api/auth/reauth/options · /reauth/verify ré-authentification d'une opération sensible
POST /api/auth/register/options · /register/verify ajout de cet appareil
POST /api/auth/setup code d'enrôlement ou de récupération
POST /api/auth/logout déconnexion (révocation serveur)
GET /api/auth/passkeys · PATCH/DELETE /api/auth/passkeys/:id clés d'accès : lister, renommer, révoquer
GET /api/auth/sessions · DELETE /api/auth/sessions/:id · DELETE /api/auth/sessions sessions : lister, fermer une / toutes les autres
POST /api/auth/recovery-codes générer des codes de récupération
Conversations GET /api/conversations · GET/PATCH/DELETE /api/conversations/:id liste, détail (all=1), métadonnées, suppression
POST /api/conversations/:id/branch activer une version, bifurquer
GET /api/conversations/:id/export?format= export Markdown / JSON
GET /api/search?q= recherche plein texte + sémantique
Génération POST /api/chat · /api/chat/regenerate · /api/chat/edit · /api/chat/approve démarrer un tour (flux SSE)
GET /api/chat/stream?run=&after= se réattacher à une génération
POST /api/chat/cancel arrêter
Modèles GET/PATCH /api/models · GET /api/presets catalogue, préférence, profils
Projets GET/POST /api/projects lister, créer
Réglages GET/PATCH /api/settings · GET /api/usage?from= préférences du compte, dépenses
Brouillons GET/PUT /api/drafts brouillon par portée
Pièces jointes POST /api/attachments (multipart) · GET /api/attachments · GET/DELETE /api/attachments/:id envoi, bibliothèque, octets, suppression
GET /api/artifacts/:id source d'un artefact
Voix POST /api/stt (multipart) · POST /api/tts dictée, lecture (audio/mpeg, texte limité à 4 000 caractères)
Prompts GET/POST /api/prompts · PATCH/DELETE /api/prompts/:id bibliothèque de prompts
Mémoire GET/POST /api/memories · PATCH/DELETE /api/memories/:id mémoire du compte
Export GET /api/owner export complet

# Événements du flux SSE

ChatStreamEvent décode 18 événements nommés, plus un cas unknown tolérant pour ceux que l'app ne connaît pas encore :

run · resync · conversation · start · text · reasoning · tool_call · tool_result · part · artifacts · usage · status · meta · title · warning · error · done · end

# Ce que l'audit du backend a établi

Sujet Constat Conséquence pour l'app
Architecture App Router Next, src/proxy.ts (garde de session) + guarded() sur chaque route client HTTP unique (Core/Networking/HTTPClient.swift)
Authentification passkeys WebAuthn (@simplewebauthn/server 14), userVerification: required, défi à usage unique lié à un cookie de cérémonie AuthenticationServices (PasskeyService.swift) ; mêmes routes /api/auth/*
Session cookie __Host-csa_session (jeton opaque 256 bits, haché en base), 30 j glissants / 90 j absolus, rotation après chaque vérification, révocable jeton lu dans Set-Cookie, gardé dans le Trousseau, renvoyé explicitement ; pas de HTTPCookieStorage
CSRF toute mutation exige Origin = origine publique l'app envoie Origin: https://chat.spboucher.ai
Génération runs détachés de la connexion, SSE numéroté (id:), battement 15 s, reprise par run + after, clé d'idempotence clientRequestId SSEParser, StreamReducer, ChatSession.followLoop
Fournisseurs / modèles OpenAI, Anthropic, xAI ; seuls les modèles vérifiés sont sélectionnables ; routeurs auto / rapide / qualité / économie ModelCatalog applique la même règle
Modification du backend une seule : applinks dans le fichier d'association Apple + libellé d'appareil « iPhone/iPad · SP Chat » le fichier webcredentials existait déjà (app macOS, même identifiant)

Audit fait sur chat-spboucher-ai v0.3.0 (Next.js 16, PostgreSQL 17 + pgvector, M4M64c:8500).


# 📱 Écrans

Écran Fichier Contenu
Connexion Features/Account/SignInView.swift passkey, « J'ai un code d'enrôlement ou de récupération »
Verrouillage App/RootView.swift (LockView), Core/Security/AppLock.swift Face ID / Touch ID à l'ouverture
Vue principale App/RootView.swift (MainView) barre latérale + conversation (iPad), pile de navigation (iPhone)
Liste des conversations Components/ConversationList.swift, Features/Conversations/ConversationListStore.swift sections par date, filtres, actions
Conversation Features/Chat/ChatView.swift, ChatSession.swift, Components/ChatBubble.swift, ChatComposer.swift messages, compositeur, pièces jointes, menu
Feuilles de message Features/Chat/MessageSheets.swift détails d'une réponse (MessageDetailsSheet), artefact (ArtifactSheet)
Sélecteur de modèle Components/ModelPicker.swift, Features/ModelSelection/ModelCatalog.swift modèle, routage, profil, effort, outils
Recherche Features/Search/SearchView.swift recherche globale
Bibliothèque de prompts Features/Library/PromptLibraryView.swift prompts enregistrés
Réglages Features/Settings/SettingsView.swift thème, verrouillage, accès aux écrans du compte
Dépenses, mémoire, fichiers, données Features/Settings/AccountScreens.swift (UsageView, MemoryView, FilesView, DataView) limites et graphique, mémoire, bibliothèque de fichiers, exports
Sécurité Features/Account/SecurityView.swift clés d'accès, sessions, codes de récupération

# 💾 Modèle de données local

Core/Persistence/LocalStore.swift ouvre une base SQLite (journal_mode = WAL, synchronous = NORMAL, secure_delete = ON) de 4 tables. Les objets sont stockés tels que le serveur les a renvoyés (JSON), pas remodelés.

Table Clé Colonnes Rôle
conversations id json, sort, archived liste (active et archivée), remplacée par la réponse du serveur
details id json, fetched conversation complète déjà ouverte, lisible hors ligne
outbox id json, created messages écrits hors ligne, en attente d'envoi
kv key value petites valeurs d'état
erDiagram
  conversations ||--o| details : "détail en cache"
  conversations {
    TEXT id PK
    BLOB json
    REAL sort
    INTEGER archived
  }
  details {
    TEXT id PK
    BLOB json
    REAL fetched
  }
  outbox {
    TEXT id PK
    BLOB json
    REAL created
  }
  kv {
    TEXT key PK
    BLOB value
  }

Les préférences sont dans UserDefaults (Preferences), le jeton de session dans le Trousseau, les pièces jointes consultées dans AttachmentCache. Le dossier de la base est marqué isExcludedFromBackup.


# 🔄 Synchronisation et hors ligne

Le serveur est la source de vérité. L'app garde une copie de lecture (SQLite, protégée par la protection des données d'iOS, exclue des sauvegardes).

Situation Comportement
Ouverture d'une conversation copie locale affichée tout de suite, puis version du serveur
Serveur injoignable conversations déjà téléchargées lisibles, bandeau « copie locale »
Message écrit hors ligne placé dans la boîte d'envoi, affiché en pointillé « non envoyé » — jamais comme envoyé ; posté au retour du réseau avec la même clé d'idempotence (jamais de doublon)
Envoi refusé par le serveur (limite de dépenses, conversation occupée…) le texte revient dans le compositeur avec la raison
Connexion coupée pendant une réponse la génération continue sur le serveur ; l'app se réattache à partir du dernier événement reçu
Renommer / épingler / archiver / supprimer demande le réseau ; appliqué localement après confirmation du serveur
Conflit pas de fusion locale : la version du serveur remplace la copie à chaque synchronisation ; seuls la boîte d'envoi et le brouillon sont de l'état local
Brouillon enregistré sur le serveur (1,5 s après la dernière frappe) : il suit le compte sur le web et le Mac

# 🔒 Sécurité et confidentialité

  • Connexion : POST /api/auth/login/options → feuille système des clés d'accès (Face ID, Touch ID, code de l'appareil, appareil voisin ou clé de sécurité) → POST /api/auth/login/verify. Le serveur vérifie la signature ; aucune donnée biométrique ne quitte l'appareil.
  • Domaines associés : webcredentials:chat.spboucher.ai et applinks:chat.spboucher.ai ; le serveur publie /.well-known/apple-app-site-association.
  • Session : jeton opaque émis par le serveur, conservé dans le Trousseau (AfterFirstUnlockThisDeviceOnly, jamais synchronisé), remplacé à chaque rotation. 401 locked → retour à l'écran de connexion et effacement des données locales.
  • Opérations sensibles : sur 403 reauth_required, l'app refait une cérémonie de passkey puis rejoue la requête une fois.
  • Premier appareil sans clé : « J'ai un code d'enrôlement ou de récupération » (code pnpm auth bootstrap du backend ou code de récupération).
  • Verrouillage de l'app : Face ID / Touch ID à chaque ouverture, activé par défaut après la connexion (Réglages → Verrouillage) ; contenu masqué dans le sélecteur d'apps.
  • Données au repos : droit default-data-protection = NSFileProtectionCompleteUnlessOpen ; base SQLite avec secure_delete, exclue des sauvegardes.
  • Déconnexion : révocation côté serveur puis effacement de toute trace locale (AppEnvironment.wipeLocalData).
  • Réseau : HTTPS seulement en Release (ATS strict) ; aucune clé d'API de fournisseur dans le binaire — les modèles sont appelés par le backend.
  • Règle d'affichage : un message n'est jamais présenté comme envoyé avant la confirmation du serveur ; une simulation n'est jamais présentée comme fonctionnelle.

Manifeste de confidentialité (PrivacyInfo.xcprivacy) : aucun suivi, aucun domaine de suivi ; données collectées — contenu utilisateur, audio, photos — liées au compte, pour le seul fonctionnement de l'app ; API à motif déclaré : UserDefaults (CA92.1) et horodatages de fichiers (C617.1).

Autorisation Texte affiché
Face ID « SP Chat utilise Face ID pour déverrouiller l'application sur cet appareil. »
Microphone « SP Chat enregistre ta voix uniquement pendant une dictée, pour la transcrire en texte dans le message. »
Appareil photo « SP Chat utilise l'appareil photo pour joindre une photo à un message. »

# 🧪 Tests

Suite Fichier Tests Couvre
Cœur Tests/CoreTests.swift (6 suites) 33 SSE, réducteur, décodage, Markdown, base locale, images, math
Client HTTP et sessions Tests/SessionTests.swift (2 suites) 15 serveur scénarisé par URLProtocol : cookies, rotation, 401, ré-auth, envoi, coupure + reprise, hors ligne, arrêt, cache, 600 messages
Bout en bout Tests/LiveBackendTests.swift (1 suite) 8 vrai serveur de développement : cycle de vie complet d'une conversation, arrêt, pièces jointes lues par le modèle, brouillons, prompts, mémoire
Interface UITests/SPChatUITests.swift 5 connexion, envoi + gestion, rendu riche, réglages + rotation + thème sombre, iPad côte à côte

Les 5 tests d'interface : testSignInScreenOffersPasskeyAndEnrolment, testSendMessageStreamsAnAnswerThenManageTheConversation, testRichAnswerRendersNatively, testSettingsRotationAndDarkTheme, testIPadShowsSidebarAndConversationSideBySide (4 exécutés sur iPhone, le 5ᵉ propre à l'iPad).

État vérifié pour la 1.0.0 (1), le 2026-11-17 (détail dans docs/IMPLEMENTATION_STATUS.md) :

Quoi Résultat
Compilation Swift 6, concurrence stricte 0 erreur, 0 avertissement dans le code de l'app
Interface iPhone (iPhone 17 Pro, iOS 26.5) 4 tests exécutés
Interface iPad (iPad Pro 13", iOS 26.5) 5 tests : barre latérale + conversation côte à côte, rotation, thème sombre
Rendu riche sans vue web tableau, code coloré, équation, webViews.count == 0 ; le binaire ne lie pas WebKit
Mesure 600 messages + 400 jetons traités en bien moins de 6 s avec moins de 120 publications d'interface
Signature et distribution archive signée « Apple Distribution », profil App Store, envoi accepté par App Store Connect

# 📦 Publication

Distribution TestFlight (App Store Connect) ; pas de notarisation, qui ne concerne pas une distribution iOS.

Élément Valeur
Équipe 3YM54G49SN
Identifiant d'app ai.spboucher.spchat (universel) : Associated Domains, Data Protection « protégé sauf si ouvert »
Signature automatique (CODE_SIGN_STYLE: Automatic), identité Apple Distribution gérée par Xcode
Profil « iOS Team Store Provisioning Profile: ai.spboucher.spchat » (créé par Xcode)
Export Scripts/ExportOptions.plist : méthode app-store-connect, symboles envoyés
Fiche App Store Connect SP Chat, app 6836172251, SKU spchat-ios-001, langue principale fr-CA
Outils Xcode 27.2 (27B52), SDK iOS 27.2, simulateurs iOS 26.5

Fait le 2026-11-17 : fiche créée, archive Release signée, IPA exportée (dist/export/SP Chat.ipa, 7,9 Mo), signature vérifiée (codesign --verify --deep --strict), envoi accepté, groupe TestFlight interne « Interne » avec le titulaire du compte comme testeur.

# Nouvelle version

bash
# 1. incrémenter CURRENT_PROJECT_VERSION (et MARKETING_VERSION si besoin) dans project.yml
Scripts/test-live.sh test && Scripts/test-live.sh uitest
Scripts/release.sh all && Scripts/release.sh upload

Scripts/release.sh : archive (génère le projet, archive Release pour generic/platform=iOS), export (IPA), upload (altool, validation puis envoi), all (= archive + export). Scripts/asc.py GET /v1/… interroge l'API App Store Connect.

# Avant une soumission à l'App Store (non fait)

Captures d'écran (les tests d'interface en produisent dans build/shots/), description, mots-clés, URL d'assistance et de politique de confidentialité, questionnaire de confidentialité (cohérent avec PrivacyInfo.xcprivacy), classification d'âge, et un compte de démonstration pour la revue (l'app est mono-propriétaire : sans compte de test, la revue Apple ne peut pas se connecter). TestFlight interne n'exige rien de tout cela.

# Backend

Le backend n'est pas dans ce dépôt et ne se modifie pas d'ici : il vit dans chat-spboucher-ai, déployé par l'orchestrateur mld sur le nœud M4M64c (port 8500, PM2) et exposé par le MacLustr Tunnel (Caddy + WireGuard) sous chat.spboucher.ai.


# 🩺 Pièges connus

  • Base de dev partagée : une suite e2e du backend (récupération) révoque toutes les sessions → relancer Scripts/dev-session.sh avant de tester.
  • Swift Testing : #expect(a.count == 1 && a[0]…) évalue les deux côtés ; un indice hors bornes fait planter le processus de test. Utiliser .first.
  • Brouillon : assigner composerText déclenche l'enregistrement du brouillon ; fixer lastSavedDraft avant.
  • SwiftUI : Section("Titre") { } footer: { } n'existe pas → Section { } header: { } footer: { }.
  • Protection des données : le droit default-data-protection doit correspondre au réglage de l'identifiant d'app (ici « protégé sauf si ouvert »).
  • App Store Connect : l'API publique ne crée pas de fiche d'app (apps : pas de CREATE) ; la fiche se crée dans le site.
  • Identifiant partagé avec macOS : ai.spboucher.spchat sert aussi à l'app macOS (sp-chat, profil Developer ID « SP Chat Developer ID »). Tout changement de capacité sur cet identifiant invalide ce profil (arrivé le 2026-11-17 avec Data Protection) : le projet macOS doit alors relancer son Scripts/provision.py avant sa prochaine version. Ne jamais supprimer ce profil ; garder 3YM54G49SN.ai.spboucher.spchat dans webcredentials.apps du backend.
  • Association de domaine : Apple met le fichier en cache (CDN) ; la première connexion par passkey peut répondre « pas encore associé » pendant quelques minutes à quelques heures.
  • Fichiers ajoutés : le projet Xcode est généré → Scripts/build.sh generate après tout nouveau fichier.
  • En-têtes : chaque fichier source commence par l'en-tête (fichier, description, auteur, contact) ; les textes d'interface sont en français, avec la traduction anglaise dans Localizable.xcstrings.

# 🚧 Limites connues et reste à valider

# Non portés (restent sur le web)

  • Recherche approfondie (/research), comparaison de modèles (/compare), studio d'images (/images), laboratoire des modèles (/models), journal de sécurité.
  • Suppression complète des données : volontairement laissée au web, derrière sa phrase de confirmation.
  • Projets : pas d'édition des instructions ni de la bibliothèque d'un projet.
  • Artefacts : pas d'aperçu exécuté.
  • Pas de notifications push (le serveur n'a pas d'APNs) : une réponse longue se termine sur le serveur et apparaît au retour dans l'app.
  • Pas d'extension de partage ; le partage depuis l'app, le glisser-déposer et le collage d'image existent.
  • « Arrêter » pressé avant que le serveur ait annoncé la génération d'une nouvelle conversation : l'app ne connaît pas encore son identifiant et ne peut pas l'annuler ; la réponse apparaîtra dans la liste.
  • La fiche App Store Connect ne porte que la plateforme iOS (l'app macOS est distribuée en Developer ID).

# À valider sur un appareil réel (TestFlight)

Sujet Pourquoi
Cérémonie de passkey réelle (connexion, ajout de l'appareil, ré-authentification) exige un appareil avec iCloud et une clé d'accès du domaine ; les tests utilisent une session de la base de dev
Association de domaine, liens universels https://chat.spboucher.ai/c/… cache CDN d'Apple ; spchat:// est testé
Face ID / Touch ID du verrouillage logique testée ; l'invite biométrique demande un appareil
Dictée (micro) et lecture audio pas de micro en simulateur
Appareil photo absent du simulateur (le bouton n'apparaît que s'il existe)
Raccourcis clavier matériel déclarés ; XCUITest ne sait pas les simuler sur le simulateur iPad
VoiceOver libellés, traits et regroupements posés ; pas d'audit à l'oreille
Rafraîchissement en arrière-plan, notification « réponse prête » planifiés par iOS : non observables en test
Instruments (fuites, énergie) non exécuté
iOS 18 / 19 compilé pour iOS 18.0, exécuté seulement sur iOS 26.5

# 👤 Auteur


Simon-Pierre Boucher — conception, développement, exploitation
www.spboucher.ai · git.spboucher.ai · contact@spboucher.ai


# 📄 Licence

Logiciel privé. Tous droits réservés © 2026 Simon-Pierre Boucher.

Files main
Menu

Theme