Repository Public
1<!--2SP Chat iOS3File: README.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->7<div align="center">89<img src="docs/brand/logo.svg" alt="SP Chat logo" width="560">1011<br><br>1213<img src="docs/brand/icon.png" alt="SP Chat icon" width="112" height="112">1415# SP Chat — iOS et iPadOS1617**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](https://chat.spboucher.ai) et que l'app macOS. Aucune vue web : chaque écran est du SwiftUI.**1819**Author: [Simon-Pierre Boucher](https://www.spboucher.ai)**2021[](https://chat.spboucher.ai)2223242526272829303132333435363738394041[](https://git.spboucher.ai/sp-chat-ios/commits)42[](https://git.spboucher.ai/sp-chat-ios/commits)43[](https://git.spboucher.ai/sp-chat-ios/insights)44[](https://git.spboucher.ai/sp-chat-ios)45[](https://git.spboucher.ai/sp-chat-ios/insights)46[](https://git.spboucher.ai/sp-chat-ios)47[](https://git.spboucher.ai/sp-chat-ios/branches)48[](https://git.spboucher.ai/sp-chat-ios/tags)49[](https://git.spboucher.ai/sp-chat-ios)5051525354555657585960616263646566676869</div>7071---7273## Sommaire7475- [Aperçu](#-aperçu)76- [Version 2.0 « Next Generation »](#-version-20--next-generation-)77- [Fonctions](#-fonctions)78- [Architecture](#-architecture)79- [Pile technique](#-pile-technique)80- [Arborescence du dépôt](#-arborescence-du-dépôt)81- [Construire et tester](#-construire-et-tester)82- [Configuration](#-configuration)83- [API consommée](#-api-consommée)84- [Écrans](#-écrans)85- [Modèle de données local](#-modèle-de-données-local)86- [Synchronisation et hors ligne](#-synchronisation-et-hors-ligne)87- [Sécurité et confidentialité](#-sécurité-et-confidentialité)88- [Tests](#-tests)89- [Publication](#-publication)90- [Pièges connus](#-pièges-connus)91- [Limites connues et reste à valider](#-limites-connues-et-reste-à-valider)92- [Auteur](#-auteur)93- [Licence](#-licence)9495---9697## 📖 Aperçu9899**SP Chat pour iOS et iPadOS** est le client natif du chat privé multi-modèles (OpenAI, Anthropic, xAI en route directe,100et le catalogue OpenRouter — environ 450 modèles) hébergé sur101**https://chat.spboucher.ai**. Il parle **au même backend, avec la même API REST + SSE** que le site : aucune API parallèle,102aucune donnée dupliquée. Le serveur reste la source de vérité ; l'app garde une copie de lecture chiffrée par iOS et une103boîte d'envoi pour écrire hors ligne.104105L'app est **mono-propriétaire** : un seul compte, protégé par des clés d'accès (passkeys). Le cahier des charges d'origine106est le brief « SP Chat Native iOS » du 2026-11-17 : reconstruction native intégrale, aucune vue web, parité avec le site,107passkeys, synchronisation, streaming, distribution TestFlight.108109| | |110|---|---|111| Identifiant | `ai.spboucher.spchat` (équipe `3YM54G49SN`), iPhone + iPad, iOS 18.0 et plus |112| 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`) |113| Langues | français (langue source), anglais — 1 058 chaînes, toutes traduites |114| Dépendance | [SwiftMath](https://github.com/mgriebling/SwiftMath) 1.7.3 (composition LaTeX native, CoreText) — la seule |115| 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 |116117Documents du dépôt : [extension de partage (conception, en attente)](docs/SHARE_EXTENSION.md) · [matrice de parité](docs/PARITY_MATRIX.md) · [état par fonction et limites connues](docs/IMPLEMENTATION_STATUS.md) ·118[distribution](docs/DISTRIBUTION.md) · [règles et pièges du projet](CLAUDE.md)119120### Famille SP Chat121122| Dépôt | Rôle | Plateforme |123|---|---|---|124| [chat-spboucher-ai](https://git.spboucher.ai/chat-spboucher-ai) | Backend + site web (Next.js, PostgreSQL + pgvector), `chat.spboucher.ai` | web |125| [sp-chat](https://git.spboucher.ai/sp-chat) | Client natif macOS (Developer ID, notarisé) | macOS |126| **[sp-chat-ios](https://git.spboucher.ai/sp-chat-ios)** | **Client natif iPhone et iPad (ce dépôt)** | iOS / iPadOS |127128> L'identifiant d'app `ai.spboucher.spchat` est **partagé avec l'app macOS** : voir [Pièges connus](#-pièges-connus).129130---131132## 🚀 Version 2.0 « Next Generation »133134Mise à niveau majeure de l'app existante (même architecture, toutes les fonctions de la 1.0 conservées) pour le backend 1.0135et le système visuel V2 **« Graphite & Iris · Lumen »** : toile graphite, une seule lumière iris, vrais logos des créateurs.136137| | |138|---|---|139| <img src="docs/img/v2/iphone-dark-chat-sources.png" width="240" alt="Réponse avec sources"> | <img src="docs/img/v2/iphone-light-model-sheet.png" width="240" alt="Feuille des modèles"> |140| 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 |141| <img src="docs/img/v2/iphone-dark-explorer-detail.png" width="240" alt="Fiche d'un modèle"> | <img src="docs/img/v2/iphone-dark-arena-done.png" width="240" alt="Arène"> |142| Explorateur → Live Model Intelligence : chaque chiffre avec sa source | Arène : le même prompt à plusieurs modèles, mesures et coût |143144- **Catalogue unifié, trois routes** : modèles directs vérifiés par le banc, catalogue OpenRouter (`or:…`) et inférence145 locale MacLustr AI (`local:…`, coût « local · 0 $ ») ; logo du créateur, nom exact, badge de route « OPENROUTER » ou146 « LOCAL », état « non testé » dit partout où c'est vrai.147- **Compositeur signature** : capsule flottante, pièces jointes, dictée, outils du tour, recherche web, puce de modèle148 (appui long = dock), effort et options, commandes rapides `/`, mention `@modèle`, ligne *lumen* pendant la génération.149- **Explorateur de modèles** : recherche, filtres, tri, comparaison côte à côte, fiche détaillée.150- **Fournisseurs** : test des clés, clés OpenRouter et Tavily définies / remplacées / révoquées **sur le serveur** (jamais151 enregistrées ni affichées sur l'appareil).152- **Synchronisation en direct** : flux d'événements du serveur, rattrapage au retour au premier plan, brouillons hors ligne.153- **Arène**, **lentilles de réponse**, **chronologie et relecture**, **branches**, **inspecteur de contexte**,154 **centre de commandes** (⌘K), **constellation**, **recherche avancée**, **coûts par route / facturé ou estimé**,155 **prompts à variables**, **édition des projets**, **instructions permanentes**, **recherche approfondie**, **studio d'images**.156157Toutes les captures (clair et sombre, iPhone et iPad) : [`docs/img/v2/`](docs/img/v2). État vérifié, non vérifié et limites :158[docs/IMPLEMENTATION_STATUS.md](docs/IMPLEMENTATION_STATUS.md).159160---161162## ✨ Fonctions163164### Conversation165166- **Envoi et streaming SSE** en temps réel, avec les états de fin : complet, arrêté, incomplet, erreur.167- **Générations détachées** : la réponse continue sur le serveur si la connexion tombe ; l'app se réattache à partir du168 dernier événement reçu, sans doublon.169- **Arrêt réel** d'une génération (annulation côté serveur).170- **Régénérer**, **modifier un message**, versions ‹ n / m ›, **bifurquer** vers une nouvelle conversation.171- **Approbation d'appels d'outils** (implémentée ; aucun outil du serveur n'est en mode « approbation » aujourd'hui).172- **Brouillons serveur** : enregistrés 1,5 s après la dernière frappe, ils suivent le compte sur le web et le Mac.173174### Rendu riche, sans vue web175176- Markdown natif : titres, listes, citations, **tableaux**.177- **Blocs de code colorés** avec bouton de copie (`SyntaxHighlighter`, `CodeBlockView`).178- **Équations LaTeX** en bloc et en ligne, composées par SwiftMath (CoreText).179- Raisonnement repliable, cartes d'outils, citations, images générées.180- Jetons, coût et latence par réponse ; feuille de détails avec les paramètres réellement envoyés.181- Artefacts : source colorée et partage du fichier (pas d'aperçu exécuté — choix : aucune vue web).182183### Modèles184185- Feuille des modèles : dock des favoris, récents, modèles **vérifiés** par le banc d'essai (route directe) et catalogue186 OpenRouter avec recherche instantanée ; les modèles indisponibles ou non pris en charge ne sont jamais proposés187 (`AIModel.isSelectableForChat`).188- Routeurs auto / rapide / qualité / économie, profils (presets), effort de raisonnement, outils activés ou non.189190### Organisation191192- Liste des conversations en sections par date ; filtres : toutes, favoris, épinglées, archives, projet ; filtre par titre.193- Renommer, épingler, mettre en favori, archiver, déplacer vers un projet, supprimer (avec confirmation).194- **Recherche globale** plein texte + sémantique.195- Prompts enregistrés, mémoire (lister, ajouter, activer / désactiver, supprimer), projets (filtrer, créer, classer).196- Dépenses : limites jour / mois, graphique (Swift Charts), ventilation par modèle.197- Export d'une conversation (Markdown / JSON) et export complet.198199### Pièces jointes et voix200201- Photothèque, appareil photo, app Fichiers, glisser-déposer, collage d'image ; progression et annulation ;202 réduction des photos et conversion HEIC → JPEG.203- Aperçu Quick Look, bibliothèque de fichiers.204- Dictée (transcription par le serveur) et lecture à voix haute.205206### Propre à iOS et iPadOS207208| Fonction | Où |209|---|---|210| Lecture hors ligne des conversations déjà téléchargées (SQLite chiffré par iOS) | `LocalStore` |211| Boîte d'envoi : message écrit hors ligne, marqué « non envoyé », posté une seule fois au retour du réseau | `ChatSession`, `AppEnvironment.flushOutbox` |212| Verrouillage par Face ID / Touch ID (activé par défaut après connexion), masque dans le sélecteur d'apps | `AppLock`, `LockView` |213| iPad : barre latérale persistante, Split View / Slide Over, glisser-déposer, raccourcis clavier | `MainView`, `SPChatApp.commands` |214| Liens profonds `spchat://c/<id>`, `spchat://new?text=`, liens universels `https://chat.spboucher.ai/c/<id>` | `AppEnvironment.handle(url:)` |215| Raccourcis Siri / Shortcuts : « Nouvelle conversation », « Demander à SP Chat » | `SystemIntegration.swift` |216| Retours haptiques, notification locale « réponse prête », rafraîchissement en arrière-plan | `Haptics`, `AppEnvironment`, `BackgroundSync` |217218### Raccourcis clavier (iPad, clavier matériel)219220| Raccourci | Action |221|---|---|222| <kbd>⌘</kbd><kbd>N</kbd> | Nouvelle conversation |223| <kbd>⌘</kbd><kbd>⇧</kbd><kbd>F</kbd> | Rechercher dans les messages |224| <kbd>⌘</kbd><kbd>L</kbd> | Écrire un message (focus sur le compositeur) |225| <kbd>⌘</kbd><kbd>.</kbd> | Arrêter la réponse |226| <kbd>⌘</kbd><kbd>⇧</kbd><kbd>C</kbd> | Copier la dernière réponse |227| <kbd>⌘</kbd><kbd>R</kbd> | Actualiser |228| <kbd>⌘</kbd><kbd>,</kbd> | Réglages |229230La matrice complète, fonction par fonction, avec l'état (opérationnel et testé / vérification partielle / non porté) et le231test qui le prouve, est dans [docs/PARITY_MATRIX.md](docs/PARITY_MATRIX.md).232233---234235## 🧭 Architecture236237Principes : état observable (`@Observable`, `@MainActor`), services injectés par `AppEnvironment` (aucun singleton de238service), réseau et base derrière des acteurs, logique de flux dans un réducteur pur testable, Swift 6 en concurrence239stricte (0 avertissement dans le code de l'app).240241```mermaid242flowchart TB243 subgraph App["App iOS / iPadOS (SwiftUI)"]244 UI["Features + Components<br/>Chat, Conversations, Search, Settings, Account…"]245 ENV["AppEnvironment<br/>injection, routeur, boîte d'envoi"]246 SES["ChatSession<br/>envoi, followLoop, arrêt"]247 RED["StreamReducer (pur)"]248 SSE["SSEParser<br/>octets → événements"]249 API["ChatAPI<br/>routes REST + flux"]250 HTTP["HTTPClient (acteur)<br/>cookie de session, Origin, rotation, 401/403"]251 AUTH["AuthStore + PasskeyService"]252 KC["Trousseau<br/>jeton de session"]253 DB[("LocalStore — SQLite<br/>cache + boîte d'envoi")]254 LOCK["AppLock<br/>LocalAuthentication"]255 end256 subgraph Cluster["MacLustr"]257 TUN["MacLustr Tunnel<br/>Caddy + WireGuard"]258 BE["chat-spboucher-ai<br/>Next.js · M4M64c:8500"]259 PG[("PostgreSQL 17 + pgvector")]260 LLM["OpenAI · Anthropic · xAI"]261 end262 UI --> ENV --> SES --> API --> HTTP263 SES --> RED264 SSE --> RED265 API --> SSE266 ENV --> AUTH --> HTTP267 AUTH --> KC268 ENV --> DB269 ENV --> LOCK270 HTTP -- "HTTPS · REST + SSE" --> TUN --> BE --> PG271 BE --> LLM272```273274### Connexion par clé d'accès275276```mermaid277sequenceDiagram278 autonumber279 participant U as Propriétaire280 participant A as SP Chat (iOS)281 participant S as chat.spboucher.ai282 A->>S: POST /api/auth/login/options283 S-->>A: défi à usage unique (lié à un cookie de cérémonie)284 A->>U: feuille système des clés d'accès285 U-->>A: Face ID / Touch ID / code / appareil voisin / clé de sécurité286 A->>S: POST /api/auth/login/verify (assertion signée)287 S-->>A: Set-Cookie session (jeton opaque)288 A->>A: jeton rangé dans le Trousseau289 Note over A,S: à chaque vérification le serveur fait tourner le jeton, l'app remplace sa copie290```291292### Un tour de conversation, avec reprise après coupure293294```mermaid295sequenceDiagram296 autonumber297 participant A as ChatSession298 participant S as Backend299 A->>S: POST /api/chat (clientRequestId = clé d'idempotence)300 S-->>A: SSE run, conversation, start301 S-->>A: SSE text / reasoning / tool_call / tool_result / part…302 Note over A,S: la connexion tombe — la génération continue sur le serveur303 A->>S: GET /api/chat/stream?run=…&after=dernier id reçu304 S-->>A: SSE (suite numérotée, battement toutes les 15 s)305 S-->>A: SSE usage, status, done, end306 A->>A: StreamReducer → état final, copie locale mise à jour307```308309---310311## 🧰 Pile technique312313| Couche | Technologie | Version | Rôle |314|---|---|---|---|315| Langage | Swift | 6.0, `SWIFT_STRICT_CONCURRENCY: complete` | tout le code |316| Interface | SwiftUI (+ UIKit ponctuel) | SDK iOS 27.2 (Xcode 27.2) | tous les écrans, aucune vue web |317| Cible | iOS / iPadOS | 18.0 et plus, familles `1,2` | iPhone + iPad ; ni Catalyst, ni « Designed for iPad » sur Mac, ni visionOS |318| Mathématiques | SwiftMath | 1.7.3 (version exacte) | composition LaTeX par CoreText |319| Authentification | AuthenticationServices | système | passkeys WebAuthn |320| Verrouillage | LocalAuthentication | système | Face ID / Touch ID |321| Session | Security (Trousseau) | système | jeton `AfterFirstUnlockThisDeviceOnly` |322| Persistance | SQLite 3 (API C) | système | cache de lecture + boîte d'envoi |323| Réseau | URLSession | système | REST, multipart, flux SSE |324| Graphiques | Swift Charts | système | écran des dépenses |325| Système | App Intents, BackgroundTasks, notifications locales | système | raccourcis Siri, rafraîchissement, « réponse prête » |326| Projet | XcodeGen | `project.yml` | génère `SPChat.xcodeproj` |327| Tests | Swift Testing + XCUITest | Xcode 27.2 | unitaires, intégration, bout en bout, interface |328| Publication | `xcodebuild`, `altool`, API App Store Connect | — | archive, IPA, TestFlight |329330---331332## 📁 Arborescence du dépôt333334```335sp-chat-ios/336├── project.yml définition XcodeGen (3 cibles : SPChat, SPChatTests, SPChatUITests)337├── SPChat.xcodeproj/ projet généré (versionné, avec Package.resolved)338├── CLAUDE.md règles du projet, recettes, pièges rencontrés339├── Design/ AppIcon.svg, AppIcon-Dark.svg, AppIcon-Tinted.svg, Mark.svg340├── SPChat-iOS/341│ ├── App/ (5) SPChatApp (scènes, commandes clavier), AppEnvironment (injection), AppConfiguration, RootView, SystemIntegration342│ ├── Core/ (17)343│ │ ├── Models/ DTO du backend (décodage tolérant), parties de message typées344│ │ ├── Networking/ HTTPClient (acteur : cookie de session, Origin, rotation, 401/403), APIError, NetworkMonitor345│ │ ├── API/ ChatAPI : toutes les routes REST + ouverture des flux346│ │ ├── Streaming/ SSEParser (octets → événements), ChatStreamEvent, StreamReducer (pur)347│ │ ├── Authentication/ PasskeyService (AuthenticationServices), AuthStore348│ │ ├── Security/ Keychain, AppLock (LocalAuthentication)349│ │ └── Persistence/ LocalStore (SQLite : cache + boîte d'envoi), Preferences350│ ├── Features/ (15) Chat, Conversations, ModelSelection, Attachments, Search, Voice, Settings, Account, Library351│ ├── Components/ (11) ChatBubble, ChatComposer, ConversationList, ModelPicker, MarkdownParser/Renderer, CodeBlockView, MathView, SyntaxHighlighter, Haptics, Theme352│ ├── Resources/ Assets.xcassets (icône claire / sombre / teintée, palette « Graphite & Iris » : 20 couleurs), Localizable.xcstrings, Info.plist, Info-Debug.plist, droits, PrivacyInfo353│ ├── Tests/ (4) Swift Testing : cœur, sessions (serveur scénarisé), bout en bout, support354│ └── UITests/ (1) XCUITest contre le serveur de développement355├── Scripts/356│ ├── build.sh generate | debug | release | test | uitest357│ ├── test-live.sh tunnel + session de dev, puis tests358│ ├── dev-session.sh crée / renouvelle une session dans la base *_dev359│ ├── release.sh archive | export | upload | all360│ ├── ExportOptions.plist export « app-store-connect », signature automatique361│ └── asc.py appels à l'API App Store Connect362└── docs/363 ├── PARITY_MATRIX.md web ↔ iOS, fonction par fonction364 ├── IMPLEMENTATION_STATUS.md vérifié / non vérifié / limites365 ├── DISTRIBUTION.md signature, TestFlight, nouvelle version366 └── brand/ logo.svg, icon.png (ce README)367```368369Lignes Swift par dossier : App 567 · Core 2 526 · Components 1 946 · Features 2 335 · Tests 965 · UITests 196.370371---372373## 🚀 Construire et tester374375Prérequis : Xcode 27 et [XcodeGen](https://github.com/yonaskolb/XcodeGen). Le projet Xcode est généré : après avoir ajouté376un fichier, relancer `Scripts/build.sh generate`.377378```bash379Scripts/build.sh generate # xcodegen → SPChat.xcodeproj (+ Info-Debug.plist)380Scripts/build.sh debug # build simulateur381Scripts/build.sh release # build Release pour simulateur générique382Scripts/build.sh test # tests unitaires et d'intégration (serveur scénarisé)383Scripts/test-live.sh test # + bout en bout contre le serveur de DÉVELOPPEMENT (tunnel M4M64c:8510, session de la base *_dev)384Scripts/test-live.sh uitest # tests d'interface (SPCHAT_SIM="iPad Pro 13-inch (M5)" pour l'iPad) ; captures dans build/shots/385Scripts/release.sh all # archive Release signée + IPA App Store ; Scripts/release.sh upload → TestFlight386```387388- La sortie de `xcodebuild` est filtrée (erreurs, suites, totaux) ; le journal complet est dans `build/logs/`.389- Le simulateur par défaut est `iPhone 17 Pro` ; `SPCHAT_SIM` le remplace.390- Les tests de bout en bout ne touchent **jamais** la production : `Scripts/dev-session.sh` refuse toute base qui n'est pas391 `*_dev`. Ils font quelques appels réels au modèle le moins cher (fraction de cent).392393---394395## 🔧 Configuration396397Aucun secret dans le dépôt ni dans le binaire. Noms seulement :398399| Nom | Où | Rôle |400|---|---|---|401| `SPChatBaseURL` | `Info.plist` | origine du backend (production : `https://chat.spboucher.ai`) |402| `SPCHAT_BASE_URL` | environnement (tests, debug) | remplace l'origine, ex. le serveur de dev par le tunnel local |403| `SPCHAT_DEBUG_SESSION` | environnement (tests) | jeton d'une session de la base de dev, injecté sans passkey |404| `SPCHAT_UI_TESTS` | environnement (XCUITest) | lance l'app dans un bac isolé (dossier et `UserDefaults` propres) |405| `SPCHAT_UI_MODEL`, `SPCHAT_UI_THEME` | environnement (XCUITest) | modèle et thème imposés pendant un test d'interface |406| `SPCHAT_LIVE_MODEL` | environnement (tests live) | modèle utilisé par les tests de bout en bout |407| `SPCHAT_SIM` | `Scripts/build.sh` | nom du simulateur |408| `SPCHAT_DEV_NODE` | `Scripts/test-live.sh`, `dev-session.sh` | nœud qui héberge le serveur de dev (défaut `M4M64c`) |409| `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/`) |410411`Info-Debug.plist` est `Info.plist` avec `NSAllowsLocalNetworking = true` (le build Debug peut joindre le serveur de dev par412`http://localhost:8510`) ; il est régénéré par `Scripts/build.sh generate`. En Release, App Transport Security interdit413tout chargement arbitraire et tout réseau local.414415Autres réglages du bundle : schéma d'URL `spchat`, tâche d'arrière-plan `ai.spboucher.spchat.sync` (mode `fetch`),416scènes multiples, catégorie « productivité », `ITSAppUsesNonExemptEncryption = false`.417418---419420## 🔌 API consommée421422`Core/API/ChatAPI.swift` et `Core/Authentication` appellent **55 opérations** (méthode + chemin) du backend423[chat-spboucher-ai](https://git.spboucher.ai/chat-spboucher-ai). Toute mutation porte `Origin: https://chat.spboucher.ai`.424425<details>426<summary><b>Tableau des routes</b></summary>427428| Domaine | Méthode et chemin | Usage |429|---|---|---|430| Authentification | `GET /api/auth/state` | état de la session |431| | `POST /api/auth/login/options` · `/login/verify` | connexion par passkey |432| | `POST /api/auth/reauth/options` · `/reauth/verify` | ré-authentification d'une opération sensible |433| | `POST /api/auth/register/options` · `/register/verify` | ajout de cet appareil |434| | `POST /api/auth/setup` | code d'enrôlement ou de récupération |435| | `POST /api/auth/logout` | déconnexion (révocation serveur) |436| | `GET /api/auth/passkeys` · `PATCH`/`DELETE /api/auth/passkeys/:id` | clés d'accès : lister, renommer, révoquer |437| | `GET /api/auth/sessions` · `DELETE /api/auth/sessions/:id` · `DELETE /api/auth/sessions` | sessions : lister, fermer une / toutes les autres |438| | `POST /api/auth/recovery-codes` | générer des codes de récupération |439| Conversations | `GET /api/conversations` · `GET`/`PATCH`/`DELETE /api/conversations/:id` | liste, détail (`all=1`), métadonnées, suppression |440| | `POST /api/conversations/:id/branch` | activer une version, bifurquer |441| | `GET /api/conversations/:id/export?format=` | export Markdown / JSON |442| | `GET /api/search?q=` | recherche plein texte + sémantique |443| Génération | `POST /api/chat` · `/api/chat/regenerate` · `/api/chat/edit` · `/api/chat/approve` | démarrer un tour (flux SSE) |444| | `GET /api/chat/stream?run=&after=` | se réattacher à une génération |445| | `POST /api/chat/cancel` | arrêter |446| Modèles | `GET`/`PATCH /api/models` · `GET /api/presets` | catalogue, préférence, profils |447| Projets | `GET`/`POST /api/projects` | lister, créer |448| Réglages | `GET`/`PATCH /api/settings` · `GET /api/usage?from=` | préférences du compte, dépenses |449| Brouillons | `GET`/`PUT /api/drafts` | brouillon par portée |450| Pièces jointes | `POST /api/attachments` (multipart) · `GET /api/attachments` · `GET`/`DELETE /api/attachments/:id` | envoi, bibliothèque, octets, suppression |451| | `GET /api/artifacts/:id` | source d'un artefact |452| Voix | `POST /api/stt` (multipart) · `POST /api/tts` | dictée, lecture (`audio/mpeg`, texte limité à 4 000 caractères) |453| Prompts | `GET`/`POST /api/prompts` · `PATCH`/`DELETE /api/prompts/:id` | bibliothèque de prompts |454| Mémoire | `GET`/`POST /api/memories` · `PATCH`/`DELETE /api/memories/:id` | mémoire du compte |455| Export | `GET /api/owner` | export complet |456457</details>458459### Événements du flux SSE460461`ChatStreamEvent` décode 18 événements nommés, plus un cas `unknown` tolérant pour ceux que l'app ne connaît pas encore :462463`run` · `resync` · `conversation` · `start` · `text` · `reasoning` · `tool_call` · `tool_result` · `part` · `artifacts` ·464`usage` · `status` · `meta` · `title` · `warning` · `error` · `done` · `end`465466### Ce que l'audit du backend a établi467468| Sujet | Constat | Conséquence pour l'app |469|---|---|---|470| Architecture | App Router Next, `src/proxy.ts` (garde de session) + `guarded()` sur chaque route | client HTTP unique (`Core/Networking/HTTPClient.swift`) |471| 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/*` |472| 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` |473| CSRF | toute mutation exige `Origin` = origine publique | l'app envoie `Origin: https://chat.spboucher.ai` |474| 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` |475| 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 |476| 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) |477478Audit fait sur `chat-spboucher-ai` v0.3.0 (Next.js 16, PostgreSQL 17 + pgvector, M4M64c:8500).479480---481482## 📱 Écrans483484| Écran | Fichier | Contenu |485|---|---|---|486| Connexion | `Features/Account/SignInView.swift` | passkey, « J'ai un code d'enrôlement ou de récupération » |487| Verrouillage | `App/RootView.swift` (`LockView`), `Core/Security/AppLock.swift` | Face ID / Touch ID à l'ouverture |488| Vue principale | `App/RootView.swift` (`MainView`) | barre latérale + conversation (iPad), pile de navigation (iPhone) |489| Liste des conversations | `Components/ConversationList.swift`, `Features/Conversations/ConversationListStore.swift` | sections par date, filtres, actions |490| Conversation | `Features/Chat/ChatView.swift`, `ChatSession.swift`, `Components/ChatBubble.swift`, `ChatComposer.swift` | messages, compositeur, pièces jointes, menu |491| Feuilles de message | `Features/Chat/MessageSheets.swift` | détails d'une réponse (`MessageDetailsSheet`), artefact (`ArtifactSheet`) |492| Sélecteur de modèle | `Components/ModelPicker.swift`, `Features/ModelSelection/ModelCatalog.swift` | modèle, routage, profil, effort, outils |493| Recherche | `Features/Search/SearchView.swift` | recherche globale |494| Bibliothèque de prompts | `Features/Library/PromptLibraryView.swift` | prompts enregistrés |495| Réglages | `Features/Settings/SettingsView.swift` | thème, verrouillage, accès aux écrans du compte |496| 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 |497| Sécurité | `Features/Account/SecurityView.swift` | clés d'accès, sessions, codes de récupération |498499---500501## 💾 Modèle de données local502503`Core/Persistence/LocalStore.swift` ouvre une base SQLite (`journal_mode = WAL`, `synchronous = NORMAL`,504`secure_delete = ON`) de **4 tables**. Les objets sont stockés tels que le serveur les a renvoyés (JSON), pas remodelés.505506| Table | Clé | Colonnes | Rôle |507|---|---|---|---|508| `conversations` | `id` | `json`, `sort`, `archived` | liste (active et archivée), remplacée par la réponse du serveur |509| `details` | `id` | `json`, `fetched` | conversation complète déjà ouverte, lisible hors ligne |510| `outbox` | `id` | `json`, `created` | messages écrits hors ligne, en attente d'envoi |511| `kv` | `key` | `value` | petites valeurs d'état |512513```mermaid514erDiagram515 conversations ||--o| details : "détail en cache"516 conversations {517 TEXT id PK518 BLOB json519 REAL sort520 INTEGER archived521 }522 details {523 TEXT id PK524 BLOB json525 REAL fetched526 }527 outbox {528 TEXT id PK529 BLOB json530 REAL created531 }532 kv {533 TEXT key PK534 BLOB value535 }536```537538Les préférences sont dans `UserDefaults` (`Preferences`), le jeton de session dans le Trousseau, les pièces jointes539consultées dans `AttachmentCache`. Le dossier de la base est marqué `isExcludedFromBackup`.540541---542543## 🔄 Synchronisation et hors ligne544545Le serveur est la source de vérité. L'app garde une **copie de lecture** (SQLite, protégée par la protection des données546d'iOS, exclue des sauvegardes).547548| Situation | Comportement |549|---|---|550| Ouverture d'une conversation | copie locale affichée tout de suite, puis version du serveur |551| Serveur injoignable | conversations déjà téléchargées lisibles, bandeau « copie locale » |552| 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) |553| Envoi refusé par le serveur (limite de dépenses, conversation occupée…) | le texte revient dans le compositeur avec la raison |554| 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 |555| Renommer / épingler / archiver / supprimer | demande le réseau ; appliqué localement **après** confirmation du serveur |556| 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 |557| Brouillon | enregistré sur le serveur (1,5 s après la dernière frappe) : il suit le compte sur le web et le Mac |558559---560561## 🔒 Sécurité et confidentialité562563- **Connexion** : `POST /api/auth/login/options` → feuille système des clés d'accès (Face ID, Touch ID, code de l'appareil,564 appareil voisin ou clé de sécurité) → `POST /api/auth/login/verify`. Le serveur vérifie la signature ; aucune donnée565 biométrique ne quitte l'appareil.566- **Domaines associés** : `webcredentials:chat.spboucher.ai` et `applinks:chat.spboucher.ai` ; le serveur publie567 `/.well-known/apple-app-site-association`.568- **Session** : jeton opaque émis par le serveur, conservé dans le Trousseau (`AfterFirstUnlockThisDeviceOnly`, jamais569 synchronisé), remplacé à chaque rotation. 401 `locked` → retour à l'écran de connexion et effacement des données locales.570- **Opérations sensibles** : sur 403 `reauth_required`, l'app refait une cérémonie de passkey puis rejoue la requête une fois.571- **Premier appareil sans clé** : « J'ai un code d'enrôlement ou de récupération » (code `pnpm auth bootstrap` du backend572 ou code de récupération).573- **Verrouillage de l'app** : Face ID / Touch ID à chaque ouverture, activé par défaut après la connexion574 (Réglages → Verrouillage) ; contenu masqué dans le sélecteur d'apps.575- **Données au repos** : droit `default-data-protection` = `NSFileProtectionCompleteUnlessOpen` ; base SQLite avec576 `secure_delete`, exclue des sauvegardes.577- **Déconnexion** : révocation côté serveur puis effacement de toute trace locale (`AppEnvironment.wipeLocalData`).578- **Réseau** : HTTPS seulement en Release (ATS strict) ; aucune clé d'API de fournisseur dans le binaire — les modèles579 sont appelés par le backend.580- **Règle d'affichage** : un message n'est jamais présenté comme envoyé avant la confirmation du serveur ; une simulation581 n'est jamais présentée comme fonctionnelle.582583Manifeste de confidentialité (`PrivacyInfo.xcprivacy`) : aucun suivi, aucun domaine de suivi ; données collectées — contenu584utilisateur, audio, photos — liées au compte, pour le seul fonctionnement de l'app ; API à motif déclaré : `UserDefaults`585(CA92.1) et horodatages de fichiers (C617.1).586587| Autorisation | Texte affiché |588|---|---|589| Face ID | « SP Chat utilise Face ID pour déverrouiller l'application sur cet appareil. » |590| Microphone | « SP Chat enregistre ta voix uniquement pendant une dictée, pour la transcrire en texte dans le message. » |591| Appareil photo | « SP Chat utilise l'appareil photo pour joindre une photo à un message. » |592593---594595## 🧪 Tests596597| Suite | Fichier | Tests | Couvre |598|---|---|---|---|599| Cœur | `Tests/CoreTests.swift` (6 suites) | 33 | SSE, réducteur, décodage, Markdown, base locale, images, math |600| 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 |601| 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 |602| Interface | `UITests/SPChatUITests.swift` | 5 | connexion, envoi + gestion, rendu riche, réglages + rotation + thème sombre, iPad côte à côte |603604Les 5 tests d'interface : `testSignInScreenOffersPasskeyAndEnrolment`,605`testSendMessageStreamsAnAnswerThenManageTheConversation`, `testRichAnswerRendersNatively`,606`testSettingsRotationAndDarkTheme`, `testIPadShowsSidebarAndConversationSideBySide` (4 exécutés sur iPhone, le 5ᵉ propre607à l'iPad).608609État vérifié pour la 1.0.0 (1), le 2026-11-17 (détail dans [docs/IMPLEMENTATION_STATUS.md](docs/IMPLEMENTATION_STATUS.md)) :610611| Quoi | Résultat |612|---|---|613| Compilation Swift 6, concurrence stricte | 0 erreur, 0 avertissement dans le code de l'app |614| Interface iPhone (iPhone 17 Pro, iOS 26.5) | 4 tests exécutés |615| Interface iPad (iPad Pro 13", iOS 26.5) | 5 tests : barre latérale + conversation côte à côte, rotation, thème sombre |616| Rendu riche sans vue web | tableau, code coloré, équation, `webViews.count == 0` ; le binaire ne lie pas WebKit |617| Mesure | 600 messages + 400 jetons traités en bien moins de 6 s avec moins de 120 publications d'interface |618| Signature et distribution | archive signée « Apple Distribution », profil App Store, envoi accepté par App Store Connect |619620---621622## 📦 Publication623624Distribution **TestFlight** (App Store Connect) ; pas de notarisation, qui ne concerne pas une distribution iOS.625626| Élément | Valeur |627|---|---|628| Équipe | `3YM54G49SN` |629| Identifiant d'app | `ai.spboucher.spchat` (universel) : Associated Domains, Data Protection « protégé sauf si ouvert » |630| Signature | automatique (`CODE_SIGN_STYLE: Automatic`), identité Apple Distribution gérée par Xcode |631| Profil | « iOS Team Store Provisioning Profile: ai.spboucher.spchat » (créé par Xcode) |632| Export | `Scripts/ExportOptions.plist` : méthode `app-store-connect`, symboles envoyés |633| Fiche App Store Connect | **SP Chat**, app `6836172251`, SKU `spchat-ios-001`, langue principale fr-CA |634| Outils | Xcode 27.2 (27B52), SDK iOS 27.2, simulateurs iOS 26.5 |635636Fait le 2026-11-17 : fiche créée, archive Release signée, IPA exportée (`dist/export/SP Chat.ipa`, 7,9 Mo), signature637vérifiée (`codesign --verify --deep --strict`), envoi accepté, groupe TestFlight interne « Interne » avec le titulaire du638compte comme testeur.639640### Nouvelle version641642```bash643# 1. incrémenter CURRENT_PROJECT_VERSION (et MARKETING_VERSION si besoin) dans project.yml644Scripts/test-live.sh test && Scripts/test-live.sh uitest645Scripts/release.sh all && Scripts/release.sh upload646```647648`Scripts/release.sh` : `archive` (génère le projet, archive Release pour `generic/platform=iOS`), `export` (IPA),649`upload` (`altool`, validation puis envoi), `all` (= archive + export). `Scripts/asc.py GET /v1/…` interroge l'API650App Store Connect.651652### Avant une soumission à l'App Store (non fait)653654Captures d'écran (les tests d'interface en produisent dans `build/shots/`), description, mots-clés, URL d'assistance et de655politique de confidentialité, questionnaire de confidentialité (cohérent avec `PrivacyInfo.xcprivacy`), classification656d'âge, et un compte de démonstration pour la revue (l'app est mono-propriétaire : sans compte de test, la revue Apple ne657peut pas se connecter). TestFlight interne n'exige rien de tout cela.658659### Backend660661Le backend n'est **pas** dans ce dépôt et ne se modifie pas d'ici : il vit dans662[chat-spboucher-ai](https://git.spboucher.ai/chat-spboucher-ai), déployé par l'orchestrateur `mld` sur le nœud663M4M64c (port 8500, PM2) et exposé par le MacLustr Tunnel (Caddy + WireGuard) sous `chat.spboucher.ai`.664665---666667## 🩺 Pièges connus668669- **Base de dev partagée** : une suite e2e du backend (récupération) révoque toutes les sessions →670 relancer `Scripts/dev-session.sh` avant de tester.671- **Swift Testing** : `#expect(a.count == 1 && a[0]…)` évalue les deux côtés ; un indice hors bornes fait planter le672 processus de test. Utiliser `.first`.673- **Brouillon** : assigner `composerText` déclenche l'enregistrement du brouillon ; fixer `lastSavedDraft` **avant**.674- **SwiftUI** : `Section("Titre") { } footer: { }` n'existe pas → `Section { } header: { } footer: { }`.675- **Protection des données** : le droit `default-data-protection` doit correspondre au réglage de l'identifiant d'app676 (ici « protégé sauf si ouvert »).677- **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.678- **Identifiant partagé avec macOS** : `ai.spboucher.spchat` sert aussi à l'app macOS679 ([sp-chat](https://git.spboucher.ai/sp-chat), profil Developer ID « SP Chat Developer ID »). Tout changement de capacité680 sur cet identifiant invalide ce profil (arrivé le 2026-11-17 avec Data Protection) : le projet macOS doit alors relancer681 son `Scripts/provision.py` avant sa prochaine version. Ne jamais supprimer ce profil ; garder682 `3YM54G49SN.ai.spboucher.spchat` dans `webcredentials.apps` du backend.683- **Association de domaine** : Apple met le fichier en cache (CDN) ; la première connexion par passkey peut répondre684 « pas encore associé » pendant quelques minutes à quelques heures.685- **Fichiers ajoutés** : le projet Xcode est généré → `Scripts/build.sh generate` après tout nouveau fichier.686- **En-têtes** : chaque fichier source commence par l'en-tête (fichier, description, auteur, contact) ; les textes687 d'interface sont en français, avec la traduction anglaise dans `Localizable.xcstrings`.688689---690691## 🚧 Limites connues et reste à valider692693### Non portés (restent sur le web)694695- Recherche approfondie (`/research`), comparaison de modèles (`/compare`), studio d'images (`/images`), laboratoire des696 modèles (`/models`), journal de sécurité.697- Suppression complète des données : volontairement laissée au web, derrière sa phrase de confirmation.698- Projets : pas d'édition des instructions ni de la bibliothèque d'un projet.699- Artefacts : pas d'aperçu exécuté.700- Pas de notifications push (le serveur n'a pas d'APNs) : une réponse longue se termine sur le serveur et apparaît au701 retour dans l'app.702- Pas d'extension de partage ; le partage **depuis** l'app, le glisser-déposer et le collage d'image existent.703- « Arrêter » pressé avant que le serveur ait annoncé la génération d'une **nouvelle** conversation : l'app ne connaît pas704 encore son identifiant et ne peut pas l'annuler ; la réponse apparaîtra dans la liste.705- La fiche App Store Connect ne porte que la plateforme iOS (l'app macOS est distribuée en Developer ID).706707### À valider sur un appareil réel (TestFlight)708709| Sujet | Pourquoi |710|---|---|711| **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 |712| Association de domaine, liens universels `https://chat.spboucher.ai/c/…` | cache CDN d'Apple ; `spchat://` est testé |713| Face ID / Touch ID du verrouillage | logique testée ; l'invite biométrique demande un appareil |714| Dictée (micro) et lecture audio | pas de micro en simulateur |715| Appareil photo | absent du simulateur (le bouton n'apparaît que s'il existe) |716| Raccourcis clavier matériel | déclarés ; XCUITest ne sait pas les simuler sur le simulateur iPad |717| VoiceOver | libellés, traits et regroupements posés ; pas d'audit à l'oreille |718| Rafraîchissement en arrière-plan, notification « réponse prête » | planifiés par iOS : non observables en test |719| Instruments (fuites, énergie) | non exécuté |720| iOS 18 / 19 | compilé pour iOS 18.0, exécuté seulement sur iOS 26.5 |721722---723724## 👤 Auteur725726<div align="center">727<img src="docs/brand/icon.png" width="64" height="64" alt="">728<br>729730**Simon-Pierre Boucher** — conception, développement, exploitation731<br>732[www.spboucher.ai](https://www.spboucher.ai) · [git.spboucher.ai](https://git.spboucher.ai) · contact@spboucher.ai733734</div>735736---737738## 📄 Licence739740Logiciel privé. Tous droits réservés © 2026 Simon-Pierre Boucher.741