codexpi/docs/audit-interface-fonctionnel-2026-11-12.md

# Audit visuel et fonctionnel final de CodexPi

Audit initial : 12 novembre 2026  
Corrections et contre-audit : 13 novembre 2026

## Périmètre

Le contrôle couvre la maquette de référence, l’interface CodexPi actuelle, la V1 au commit `445128c`, les routes API, les droits d’accès, les parcours desktop et mobile, les dépendances et les tests automatisés. Les actions destructives ou externes — déploiement réel, arrêt de conteneur, révocation d’une machine et commandes sur l’hôte — ont été vérifiées dans le code et par tests isolés, sans être exécutées sur l’instance en service. Aucun redémarrage ni déploiement n’a été effectué.

## Verdict sur l’interface

Le principe « entreprise d’agents » est pertinent pour **Organisation**, **Activité** et **Projets** : il rend visibles le propriétaire, la coordination, les groupes, l’infrastructure et le travail en cours.

Il serait en revanche mauvais de forcer ce canevas sur le chat, le diff Git, le terminal ou l’exploitation Docker. Ces écrans demandent plus de densité et moins de décoration. CodexPi conserve donc un langage commun — navigation, couleurs, en-têtes, états — tout en gardant des surfaces spécialisées et un mode focus pour le travail profond. C’est le bon compromis entre la maquette et la V1.

## Organisation : logique finale

Le fonctionnement est désormais cohérent avec le besoin « groupe TV » :

1. **+ Groupe** ouvre une fenêtre accessible et sélectionne au moins deux projets locaux existants.
2. Les projets doivent être actifs, appartenir au même propriétaire et rester en mode SAFE.
3. Un projet peut participer à plusieurs groupes. L’ajouter à « TV » ne le retire donc pas de « Médias » ou « Salon ».
4. Un groupe peut être créé, modifié ou supprimé sans supprimer ses projets.
5. Codex SAFE reçoit les chemins des autres membres et peut lire leur code, mais seul le projet courant reste une racine d’écriture.
6. Claude et OpenCode reçoivent les noms et les comptes rendus, sans chemins inter-projets, car leur frontière d’écriture n’est pas équivalente.
7. `FULL ACCESS` est refusé avant l’entrée dans un groupe et ne peut plus être activé après l’entrée.
8. La réponse finale d’une tâche devient un compte rendu persistant consultable par les autres membres lors de leur tâche suivante.
9. Une tâche acquiert tous les verrous des groupes auxquels son projet appartient, dans un ordre stable. Les moteurs Codex, Claude et OpenCode ne peuvent donc pas travailler simultanément sur des projets qui partagent une même ressource.
10. Les groupes, membres, propriétaires, activités et états système affichés dans Organisation proviennent des API réelles.

La communication entre agents reste volontairement **asynchrone** : ce sont des comptes rendus persistés, pas une conversation directe entre processus. Le fonctionnement du bac à sable `workspace-write` utilisé pour Codex SAFE est décrit dans la [documentation OpenAI](https://learn.chatgpt.com/docs/sandboxing).

## Corrections issues de l’audit

| Priorité | Constat initial | Correction livrée |
|---|---|---|
| P0 | Dépendances Python et frontend vulnérables | Django, FastAPI, Uvicorn, multipart, Vite, Sharp, pytest et Setuptools mis à niveau ; audits Python et npm à zéro vulnérabilité connue ; contrôles ajoutés à la CI. |
| P0 | Lecture seule non garantie en FULL ACCESS | Combinaison groupe/FULL ACCESS refusée dans les deux sens. |
| P0 | Isolation différente selon le moteur | Chemins inter-projets réservés à Codex SAFE ; autres moteurs limités aux comptes rendus ; verrouillage de groupe appliqué à tous les moteurs. |
| P1 | Groupes indirects et appartenance unique | Tables `project_groups` et `project_group_members`, migration de l’existant et appartenance plusieurs-à-plusieurs. |
| P1 | Navigation React non reflétée dans l’URL | Routes centralisées, liens profonds, `pushState`, `popstate`, Retour, rechargement et titre de document. |
| P1 | Propriétaire ambigu en vue administrateur | Propriétaire affiché sur les groupes et projets concernés. |
| P1 | État NasPi décoratif | Statut relié aux données réelles du tableau de bord. |
| P1 | Navigation mobile trop chargée | Cinq destinations principales et menu **Plus** ; boutons tactiles de 44 px et fenêtres adaptées à 375 px. |
| P1 | Typographie trop petite | Corps, métadonnées et contrôles agrandis tout en conservant une densité desktop raisonnable. |
| P1 | Accessibilité incomplète | Icônes SVG, lien d’évitement, `aria-current`, focus piégé/restauré, fermeture Échap, fenêtres partagées et contrôle axe desktop/mobile. |
| P1 | Mélange français/anglais | Libellés de navigation, espace de travail, Git, statuts, métriques, états réseau et écrans d’exploitation harmonisés en français. |
| P1 | Lanceur limité à des raccourcis locaux | Recherche API sur projets, conversations et groupes, avec filtrage par propriétaire et déduplication des requêtes. |
| P1 | Polling redondant en arrière-plan | Cache partagé, requêtes en vol mutualisées et suspension quand l’onglet ou la zone n’est pas visible. |
| P1 | Erreurs réseau répétitives ou ambiguës | Distinction appareil/API, état persistant et notifications dédupliquées. |
| P1 | Absence de tests de parcours | Playwright desktop/mobile, création de groupe, URL/Retour/rechargement, clavier, axe et captures de non-régression. |
| P2 | Paquet principal d’environ 502 kB | Chargement dynamique par route ; paquet principal réduit à 130,89 kB brut / 36,17 kB gzip. Markdown et terminal restent dans des blocs différés. |
| P2 | Écosystème sans hiérarchie | Regroupement en **Produits**, **Exploitation** et **Construction**, avec URL interne persistante. |
| P2 | Surfaces visuelles incohérentes | Tokens communs, modes Tableau de bord/Atelier/Revue Git et mode focus persistant. |
| P2 | Écrans monolithiques et polling local | Hooks de visibilité, service API partagé, parseur de commandes et logique de routes extraits et testés. |
| P2 | Orchestrateur fragile sur les commandes citées | Parseur conservant guillemets, espaces échappés, arguments vides et chemins Windows ; erreurs d’historique affichées. |
| P2 | Agent maître peu suivi | Rafraîchissement actif pendant une exécution et distinction explicite avec l’orchestrateur. |
| P2 | Machines distantes dépendantes du projet sélectionné | Vraie vue globale des machines avec choix explicite du profil de départ. |
| P2 | Registre peu lisible sur mobile et sans historique | Tableau transformé en cartes mobiles, fenêtre accessible et historique réel des préparations/étapes. |
| P2 | App Store visuellement isolé | Branding CodexPi, fenêtre commune et repli lisible en cas d’icône absente. |

## Contre-audit par écran

| Écran | Résultat final | Point de vigilance assumé |
|---|---|---|
| Organisation | Hiérarchie claire, données réelles, groupes multiples, création/édition/suppression, propriétaires et relais visibles. | Les relais sont asynchrones afin de rester auditables et reproductibles. |
| Activité | Recherche, filtres, tableau/flux, revue et états réseau distincts. | Le tableau reste réservé aux grands écrans ; le mobile utilise le flux. |
| Projets | Recherche, tri, activité, archives, métriques traduites et fiches mobiles. | Aucun défaut bloquant identifié. |
| Atelier / Chat | Files, reprise WebSocket, pièces jointes, contexte, erreurs, lecture vocale et mode focus. | Les messages techniques renvoyés par un moteur externe peuvent conserver son vocabulaire propre. |
| Git / Revue | Diff, restauration, preuves, validation Git et personnalité Revue dédiée. | Les opérations destructives restent soumises à confirmation. |
| Navigateur / Terminal / Docker | États, reconnexion, périmètre projet et actions sensibles explicites. | Les commandes réelles n’ont pas été lancées pendant l’audit. |
| Orchestrateur | Historique sûr, états vides, arguments fiables, validations et barrières de fusion. | Une mise en production n’est jamais implicite. |
| Agent maître | Installation volontaire, indisponibilité claire et suivi actif. | Reste réservé au propriétaire de l’hôte. |
| Serveur / Pi Doctor | Statut global réel, libellés harmonisés et polling borné. | Les réparations restent désactivées hors plan validé. |
| Écosystème | Navigation hiérarchisée et liens profonds. | Chaque outil conserve sa densité métier au lieu d’imiter artificiellement Organisation. |
| App Store | Recherche, PWA, branding et repli d’icône cohérents. | Aucun défaut bloquant identifié. |
| Mise en service | Préparation distincte du déploiement, cartes mobiles et historique des plans. | L’interface ne prétend jamais qu’un plan préparé a été exécuté. |
| Dev Studio | Plan, empreinte, approbation, branche, tests et rapport restent séparés de la fusion et du déploiement. | Aucun déploiement réel durant l’audit. |
| Machines distantes | Liste globale, jumelage, révocation et consultation hors ligne. | Le profil local de départ doit être choisi pour un nouveau jumelage. |
| Réglages | Navigation compacte, icônes cohérentes et libellés français. | Aucun défaut bloquant identifié. |
| Connexion / initialisation | CSRF, sessions, clavier et erreurs contrôlés. | La disponibilité réelle du serveur dépend naturellement du réseau privé. |

## V1 : éléments remigrés

Les qualités utiles de la V1 ont été reprises :

- trois personnalités réelles — Tableau de bord, Atelier et Revue Git ;
- mode focus pour le chat, le code et le diff ;
- navigation mobile limitée et fonctions secondaires sous **Plus** ;
- flux Activité mobile ;
- revue Git centrée sur le diff et les preuves ;
- séparation nette entre navigation globale et contexte projet.

Les éléments à ne pas remigrer restent exclus : données factices, états décoratifs, barres latérales concurrentes, libellés anglais non harmonisés et plusieurs sélecteurs de projet pour la même action.

## Validation finale

- Backend : **300 tests réussis**, sans avertissement, dans l’image Docker finale.
- Frontend : **42 tests réussis**.
- Parcours navigateur : **8 tests Playwright réussis** sur 1440 × 900 et 375 × 812.
- Accessibilité : aucune violation axe sérieuse ou critique sur le parcours Organisation contrôlé.
- TypeScript et build de production : réussis.
- Paquet principal : **130,89 kB brut / 36,17 kB gzip** ; CSS global **232,51 kB brut / 43,58 kB gzip**.
- `npm audit` : **0 vulnérabilité**.
- `pip-audit --local` : **aucune vulnérabilité connue**.
- Captures de référence desktop et mobile enregistrées dans les tests E2E.

Le CSS global reste volumineux en valeur brute, mais il pèse 43,58 kB compressé et ne bloque pas l’affichage. Le prochain découpage éventuel de CSS par route relève désormais de l’optimisation continue, pas d’une anomalie fonctionnelle ou visuelle.