SPB Git

Repository Public

IOS_ARCHITECTURE.md 12.8 KB 164 lines markdown

1<!--2VQuant iOS3File: docs/IOS_ARCHITECTURE.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->78# VQuant iOS / iPadOS 2.0 « VQuant Next » — architecture910État au 2026-11-20 (branche `next`, 2.0.0 build 2, **non publiée**). Application 100 % native (Swift 6, SwiftUI,11concurrence stricte `complete`), sans vue web. Cible iOS 18+, iPhone et iPad. Identifiants inchangés depuis 1.0 :12bundle `ai.spboucher.vquant`, extension `ai.spboucher.vquant.widgets`, groupe d'apps `group.ai.spboucher.vquant`,13domaine associé `webcredentials:vquant.spboucher.ai`, équipe `3YM54G49SN`.14152.0 est une **mise à niveau** de 1.0, pas une réécriture : tout ce que 1.0 faisait reste en place (voir16`IOS_FEATURE_PARITY.md`, colonne « 1.0 → 2.0 »). Ce document décrit ce qui change.1718## 1. Ce que devient VQuant1920VQuant est d'abord **l'agent de recherche quantitative autonome** ; marchés, Quant Lab, portefeuilles et studio sont21des surfaces autour de lui. Tout calcul s'exécute sur le serveur (backend 6, contrat22`vquant-next/docs/next/CONTRACT.md`). L'appareil **lance, suit, inspecte et reprend** : il n'exécute jamais de Python.23Les seuls calculs faits sur l'appareil sont, comme en 1.0, des statistiques descriptives légères sur des observations24reçues (moyennes mobiles, RSI, drawdown, corrélations) et l'arithmétique qui transforme un résultat de moteur en25montant (VaR en % × valeur saisie, budget de risque ÷ VaR), formule affichée.2627| Élément | 1.0 | 2.0 |28|---|---|---|29| Compte | chaque appareil pour soi (liste de suivi locale) | **un compte synchronisé** : objets `/api/v2/objects`, flux `/api/v2/sync` |30| Agent | 4 modes d'analyse, modèle par défaut | + **recherche autonome** (espace de travail, registre, contrôle de qualité), modèle au choix ou Auto, budget, jeu de données |31| Calculs | 6 moteurs | **19 moteurs** (en-tête `vquant-ios/2.0.0`), schéma `lab/1`, progression, annulation |32| Données de marché | proxy FMP par symbole | couche de données `/api/v2/data/*` avec provenance et fraîcheur ; les routes 1.0 restent en repli |33| Notifications push | aucune (pas d'APNs côté serveur) | **toujours aucune** : notifications locales, y compris pour les demandes d'autorisation |3435## 2. Vue d'ensemble3637```text38 iPhone / iPad ── HTTPS ──▶ vquant.spboucher.ai ──▶ backend 6 (Node/Express, SQLite, moteurs Python isolés)39   │ Bearer vqn_… · X-VQ-Client: vquant-ios/2.0.0 (2)40   ├─ APIClient (Core)  ── routes 1.0 : /api/native, /api/fmp, /api/chat, /api/generations, /api/sessions, /api/workspace41   └─ IOSVQTransport ──▶ VQuantKit ── /api/v2 : objects, sync (SSE), data, market, search, models, usage, projects,42        │                              reviews, research ; /api/quant (catalogue 19 moteurs, jobs, annulation)43        └─ VQSyncEngine (acteur) ── réplique chiffrée dans le conteneur du groupe d'apps + file d'écritures durable44 Widgets ◀─ instantané JSON (aucun réseau, aucun jeton, aucune clé de déchiffrement)45```4647## 3. Organisation du code4849```text50Core/                socle 1.0 sans interface, inchangé dans son rôle (compilé dans l'app et les widgets, paquet51                     SwiftPM VQuantCore, tests sur Mac). Ajouts additifs : mode `research`, `budget` / `projectId` du52                     corps de /api/chat, JSON brut de chaque événement de flux (`StreamItem.raw`).53../VQuantKit         paquet partagé avec le client macOS (dépendance locale du projet) :54                     VQuantKit (moteur de synchro, modèles v6, Quant Lab, clients de recherche),55                     VQuantUI (jetons VQTokens, composants, LabResultView, vues de recherche), VQuantKitTesting.56VQuant/57  App/               VQuantApp (scènes, commandes clavier), AppModel, Stores, AppSupport (sections, routes, routeur)58  Next/              tout ce que 2.0 ajoute :59    NextTransport    adaptateur APIClient → VQTransport, chiffrement de la réplique60    SyncCenter       moteur de synchro de la personne connectée, collections observables, migration 1.061    NextServices     magasins : terminal, modèles, Quant Lab, portefeuilles, studio ; ResearchHub (espaces, autorisations)62    ResearchViews    composition, cockpit d'étude, autorisations, étude conservée sur le serveur63    TerminalViews    vue des marchés, courbe des taux, calendrier, recherche universelle, états financiers64    LabViews, QuickCalcViews   catalogue, formulaires tactiles, jobs, résultats, calculs rapides65    StudioViews      projets, notes, revues, export, consommation, état de la synchronisation et conflits66    WorkspaceViews   espaces de travail (arbre de disposition, séparateurs, panneaux)67    ChartDrawing     tracés ancrés au temps et au prix, poste de graphique68  Features/, Charts/, Auth/, Platform/, DesignSystem/   écrans et services de 1.0, adaptés69VQuantWidgets/       quatre widgets (lient VQuantUI pour les jetons de couleur seulement)70CoreTests/, VQuantTests/ (dont NextTests), VQuantUITests/71```7273### L'adaptateur de transport7475`IOSVQTransport` remet à `APIClient.urlRequest` le chemin **décodé** (ce client encode lui-même le chemin) :76`/api/v2/data/bars/^GSPC` part bien en `%5EGSPC` (test `symbolsWithACaretAreEncodedOnce`, et appel réel dans77`dataLayerThroughTheAdapter`). Il transmet `contentType` (multipart pour le dépôt d'un jeu de données) et, sur un 40178`x-vq-locked`, déclenche le même chemin de déconnexion que 1.0.7980## 4. Un compte, synchronisé8182`SyncCenter` crée un `VQSyncEngine` par personne connectée :8384- **Réplique** dans `group.ai.spboucher.vquant/sync/<personne>/`, scellée en AES-256-GCM avec la clé du cache de 1.085  (Trousseau) par le crochet `VQSyncCipher` du paquet, exclue des sauvegardes. Démarrée à la connexion (et au86  lancement hors ligne avec la dernière personne connue), **effacée** à la déconnexion et sur session morte, comme le87  cache.88- **Écritures** : d'abord dans la file durable du moteur (affichées aussitôt), puis rejouées dans l'ordre. Hors ligne89  elles attendent ; l'état (« Synchronisé », « n modifications en attente », « Hors ligne », « Session fermée ») est90  visible sur l'accueil, dans la barre latérale de l'iPad et dans Plus › Synchronisation, avec la file et les conflits.91- **Conflits** (convention commune aux trois clients) : listes fusionnées par élément (symboles, positions, éléments de92  projet, tracés) ; pour le reste, dernière écriture gagnante **par champ** (`granularity = .field`) ; les espaces de93  travail restent en objet entier. Un conflit qui a écrasé du contenu apparaît dans l'écran de synchronisation avec les94  deux versions, « garder la mienne » ou « reprendre celle de l'autre appareil ».95- **Flux** : le moteur ouvre `/api/v2/sync/stream`, tire à chaque `change`, et relaie les `hint` (analyses, sessions,96  calculs) qui rafraîchissent les listes. iOS ferme le flux en arrière-plan : au retour au premier plan un tour97  complet est fait. `BGAppRefreshTask` fait un tour quand iOS l'accorde.9899### Migration des données de 1.0 (une fois, par personne)100101| Donnée 1.0 | Devient | Détail |102|---|---|---|103| Liste de suivi (`watchlist.json` du groupe d'apps) | un objet `watchlist` d'identifiant fixe `ios-watchlist` | Identifiant fixe : un deuxième appareil qui migre le même compte reçoit un 409 et le moteur **fusionne** (union des symboles) — ni perte ni doublon (tests à deux appareils). Le fichier est conservé en `watchlist.migrated.json`. |104| Portefeuille | objet `portfolio/main` | Fait par le serveur (pont du contrat §1.4). L'app n'écrit plus `/api/workspace/portfolio`. La confirmation explicite avant écriture est conservée. |105| Annotations de graphique (PencilKit, par symbole) | tracés `pencil` de l'objet `chart` `sym-<SYMBOLE>` | **Non convertibles automatiquement** : elles étaient liées à l'écran, sans la vue d'origine. Le poste de graphique les affiche en surimpression ; la personne choisit la période et le zoom où elles tombent juste, puis « Ancrer à cette vue » les convertit point par point en (temps, prix). Fichier gardé en `.migrated`. Sans ce geste, elles restent sur l'appareil. |106| Préférences | `preference/default` | Synchronisés : mode et modèle par défaut, budget, paire de couleurs hausse/baisse. **Non synchronisé** : le thème clair/sombre (choix par appareil), et les réglages propres à l'appareil (actualisation, notifications, haptique). |107108## 5. Recherche autonome109110- **Composition** : question, mode (recherche autonome ou les quatre modes d'analyse), modèle du registre du serveur111  avec logo du fournisseur et « Auto », budget (coût, durée), projet, image, **jeu de données** depuis Fichiers112  (vérifié comme le fera le serveur, déposé dans l'espace de travail créé pour l'étude, puis profilé : carte113  d'inspection).114- **Suivi** : `RunController` (1.0) suit le flux de la génération et le rejoue après coupure ; chaque événement brut115  alimente aussi le `VQResearchSessionStore` du paquet. `StudyCockpit` présente Rapport · Activité · Code ·116  Expériences · Figures · Fichiers avec les vues de recherche partagées : sélecteur segmenté sur iPhone, rapport +117  inspecteur redimensionnable sur iPad.118- **Reprise** : une étude lancée sur le Mac ou le web apparaît dans « Sur le serveur » (flux rejouable) et dans119  « Études autonomes » (espace de travail lu par REST, conservé pour la lecture hors ligne).120- **Autorisations** : carte proéminente (accueil, espace de recherche, étude) et notification locale avec121  « Autoriser » / « Refuser ». Sans APNs, la notification n'est émise que lorsque l'appareil apprend la demande :122  flux ouvert, relève toutes les 6 s pendant qu'une étude tourne, actualisation en arrière-plan accordée par iOS.123124## 6. iPhone et iPad125126- **iPhone** : cinq onglets (Accueil, Marchés, Recherche, Portefeuilles, Plus). L'accueil est centré sur l'agent.127- **iPad** : `NavigationSplitView` à trois colonnes par destination (barre latérale, liste, détail) pour Recherche,128  Marchés, Quant Lab, Portefeuilles, Studio, Espaces de travail, Bibliothèque ; deux colonnes ailleurs. Toute129  destination s'ouvre dans sa propre fenêtre (`WindowGroup(for: Route.self)`). Raccourcis clavier pour chaque130  destination et commande principale (menus Fichier, Aller à, Recherche, Marchés, Quant Lab, Présentation), visibles131  dans le panneau ⌘. Glisser-déposer : symboles (listes, graphique, composition, panneaux), fichiers vers la132  composition, figures et exports par Quick Look.133- **Espaces de travail** : l'arbre `layout` d'un objet `workspace` est rendu par `LayoutNodeView` (lignes et colonnes134  imbriquées, séparateurs déplaçables, tailles enregistrées en pourcentages comme le web) ; panneaux natifs :135  graphique, liste de suivi, cotation, états financiers, recherche, Quant Lab, portefeuille, note. Les autres types136  (`news`, `options`, `macro`…) sont conservés et signalés comme sans rendu natif. En fenêtre étroite (< 620 pt) les137  panneaux s'empilent.138139## 7. Graphiques140141Le rendu `Canvas` de 1.0 est conservé. Les barres viennent de `/api/v2/data/bars` (provenance affichée : fournisseur,142ajustement réellement appliqué, observations, séances manquantes) ; si la route est injoignable, la route 1.0 répond.143Une barre quotidienne de la couche de données est datée 00:00 UTC de sa séance ; l'app l'affiche à la date de séance144en heure de New York, et un point de tracé garde l'horodatage du serveur (`ChartTime`). Les tracés (ligne de tendance,145horizontale, rectangle, Fibonacci, note, mesure — mêmes types que le web — et tracé libre `pencil`) sont dans l'objet146`chart` du symbole (`sym-<SYMBOLE>`, convention du web). « Demander à l'agent » envoie le symbole, l'intervalle, les147dates exactes de la fenêtre visible, les indicateurs affichés et les niveaux tracés.148149## 8. Design150151Identité « VQuant Next » par les jetons `VQTokens` (générés depuis le dépôt web) : `Theme` n'est plus qu'une table de152correspondance vers eux. Titres en New York, interface en SF, nombres en SF Mono à chiffres tabulaires, filets,153surfaces papier, verre laissé aux barres du système. L'accent Ember (#FF6A1A) ne sert qu'en **aplat** (action154primaire, marque de l'agent) avec une encre sombre ; tout **texte** d'accent utilise `accentText` (l'audit de 1.0155avait mesuré 2,9:1 pour l'orange de marque sur fond clair). Vocabulaire de fraîcheur du contrat : jamais « en156direct » (interrogé, différé, clôture, historique, estimé).157158## 9. Limites connues159160Voir `IOS_TEST_PLAN.md` §7 (ce qui n'a jamais été vérifié sur un appareil) et `IOS_FEATURE_PARITY.md`. En bref : pas161de push, pas de Live Activities, dépôt de jeux de données en mémoire (pas de session d'arrière-plan : gros fichiers à162éviter sur réseau cellulaire), formules LaTeX rendues lisibles mais non composées, panneaux d'espace de travail163`news` / `options` / `macro` / `risk` / `table` / `notebook` sans rendu natif.164
Files main
Menu

Theme