MVP — Procédure “Mode Safe” (Aurora Nexus)

Date : 2025-12-23
Objectif : appliquer les priorités “Go installation client” en minimisant les risques de casse et en gardant un rollback clair.

Principes

1. Changements additifs en DB (pas de suppression de colonnes/tables).
2. Tout changement “contrat” (auth/OAuth, endpoints, schéma) est livré avec :
   • une compat temporaire si possible,
   • une recette de validation,
   • un plan de rollback.
3. Toute modif “infra” (ports/exposition) est testée en local Docker avant déploiement client.

Ordre recommandé (safe)

Phase 0 — Préflight

• docker compose ps : stack up
• API : GET /api/health retourne ok (ou degraded si dépendance non configurée)
• Export backup DB (pg_dump) et snapshot volumes si possible

Phase 1 — “No data change” (risque faible)

• Supprimer/neutraliser les logs print() diagnostics (API + tasks) sans toucher aux payloads RAGAS.
• Ajouter healthchecks API et Gateway.
• Pinner MinIO server/mc (digest) pour reproductibilité.
• Réduire l’exposition réseau (bind 127.0.0.1) pour Postgres/Qdrant/MinIO.
• Rendre le réseau sylio_default non bloquant (création automatique si absent).

Rollback : revert commit + docker compose up -d.

Phase 2 — DB “public links” (additif, compatible)

• Migration SQL additive :
  • ajouter downloads_count, last_download_at, max_downloads si manquants
  • ajouter PK(id), FK(document_id), UNIQUE(token) et index token si possible
• Alignement baseline aurora_schema.sql + docs
• Recette : créer un lien public, télécharger, vérifier incrément compteur

Rollback :

• conserver les nouvelles colonnes (pas destructif) ;
• si une contrainte pose problème : la retirer (ALTER TABLE DROP CONSTRAINT) et corriger les données, puis ré-appliquer.

Phase 3 — OAuth Google (sans token dans l’URL)

• Remplacer le redirect .../login?token=... par un mécanisme “one-time code” (idéalement via location.hash) + endpoint d’échange.
• Garder le mode Bearer JWT (header Authorization) côté UI/API.
• Recette : login Google + refresh page + navigation admin + logout.

Rollback :

• conserver les deux chemins quelques temps (ancien + nouveau) ou revert commit auth.

Phase 4 — BYOK strict (Gateway)

• Rendre LLM_CREDENTIALS_ENC_KEY obligatoire (fail-fast en prod) et supprimer les fallbacks silencieux.
• Recette : provider BYOK activé + appel LLM OK ; si clé absente → démarrage en erreur (comportement attendu).

Rollback : revert commit gateway.

Phase 5 — Cohérence embeddings (3072)

• Uniformiser scripts init Qdrant/cache pour 3072, et ajouter validation (fail-fast si dimension inattendue).
• Recette : ingestion + query + cache sémantique gateway.

Recette “Go live” (client)

1. Installation via wizard/compose
2. Login admin (password local) + OAuth Google
3. Upload 1 PDF → job done → query → citations OK
4. Public link → téléchargement OK + compteur
5. Vérifier que Postgres/Qdrant/MinIO ne sont pas exposés publiquement

Extensions “Plan A” (anti No-Go)

Phase 6 — Minimisation logs (queries_log)

• Activer la politique “logs != données” :
  • citations persistées = metadata uniquement (pas de chunks)
  • question/answer optionnels et tronqués
• Variables (voir .env.example) :
  • QUERIES_LOG_STORE_QUESTION, QUERIES_LOG_STORE_ANSWER
  • QUERIES_LOG_MAX_QUESTION_CHARS, QUERIES_LOG_MAX_ANSWER_CHARS
  • QUERIES_LOG_MAX_CITATIONS, QUERIES_LOG_MAX_CITATIONS_BYTES
• Recette :
  • faire une requête RAG
  • vérifier que queries_log.citations ne contient pas page_content

Rollback : remettre les variables sur des valeurs permissives ou revert commit.

Phase 7 — Rétention / purge (DB + cache sémantique)

• Activer la purge planifiée (Celery beat côté aurora_gateway_worker) :
  • Postgres : queries_log, llm_cache_exact, openrouter_usage_snapshots, llm_evaluation, embeddings_log, oauth_login_codes
  • Qdrant : suppression best-effort des entrées expirées dans QDRANT_CACHE_COLLECTION
• Variables :
  • RETENTION_PURGE_ENABLED, RETENTION_PURGE_INTERVAL_SECONDS
  • QUERIES_LOG_RETENTION_DAYS (+ autres durées)
• Recette :
  • mettre QUERIES_LOG_RETENTION_DAYS=1 (sur un environnement de test)
  • injecter des lignes anciennes (ou attendre) et vérifier la purge

Rollback : RETENTION_PURGE_ENABLED=false.

Phase 8 — Auth “cookie-only” (UI)

• UI : utiliser NEXT_PUBLIC_AUTH_MODE=cookie (par défaut recommandé)
• API : éviter d’exposer le JWT au JS (optionnel, recommandé) :
  • RETURN_JWT_IN_BODY=false → réponse JSON renvoie token="cookie_only" (le cookie HttpOnly reste la source de vérité)
• Recette :
  • login / refresh page / navigation admin / logout
  • vérifier qu’aucun paramètre token n’est présent dans l’URL

Rollback : NEXT_PUBLIC_AUTH_MODE=bearer et/ou RETURN_JWT_IN_BODY=true.

Phase 9 — Backup / rollback

• Préflight + backup Postgres : bash ops/preflight_safe_rollout.sh
• Doc : docs/BACKUP_RESTORE.md