⚙️ BOS-BOURSE — Aide technique

🏗️ Architecture

BOS-BOURSE tourne intégralement sur l'edge Cloudflare. Trois briques :

Plus deux services tiers :

• Yahoo Finance (API publique query1.finance.yahoo.com) — prix EOD, fondamentaux, recherche d'instruments
• OpenFIGI / Bloomberg — résolution ISIN ↔ ticker (fallback quand Yahoo ne connaît pas)
• Anthropic Claude — OCR Vision via Haiku 4.5 (extraction de portefeuilles depuis image/PDF)

Flux principal

Browser → Cloudflare Pages (HTML/JS)
       → fetch() → Cloudflare Worker (API)
                    → D1 (queries SQL)
                    → Yahoo / OpenFIGI / Anthropic (selon endpoint)
                    → JSON response

🗄️ Données & tables D1

La base D1 contient plusieurs familles de tables :

Whitelist & sessions

• allowed_users — emails autorisés, role (admin/reader), préférences (profil de risque, cash min, broker default, dates d'ouverture PEA/PEA-PME), quotas Vision
• login_history — historique des connexions (succès/refus), source IP, user-agent
• admin_audit_log — actions admin tracées (user add/revoke, instrument upsert/delete, OCR import, etc.)

Univers d'analyse

• instruments — watchlist (ticker, ISIN, nom, type STOCK/ETF, devise, place, secteur, capi, éligibilités PEA/PEA-PME)
• instruments_prices — historique EOD (open/high/low/close/volume par ticker × date)
• fundamentals_* — vues dérivées des fondamentaux (P/E, ROE, marge, dette, croissance) avec une vue fundamentals_latest consolidée
• instruments_waiting — demandes user (tickers/ISIN cherchés mais absents de la watchlist), à valider par l'admin

Skill & analyses

• analyses — résultat du skill BOS pour chaque ticker × date (verdict, score, triggers JSON, signals JSON, argumentation)
• picks_executed — picks que l'utilisateur a réellement passés (date d'exécution, qté, prix réel), pour le suivi de perf perso

Portefeuilles users

• user_portfolios — positions chiffrées AES-256-GCM par utilisateur, avec clé dérivée par email
• user_cash — cash espèces par enveloppe (PEA, PEA-PME, CTO), chiffré idem
• user_anthropic_keys — clés Anthropic stockées (chiffrées) pour la voie OCR clé perso ou clé admin partagée

Vitrine

• showcase_portfolios — 9 portefeuilles auto-pilotés (nom, profil, devise, description)
• showcase_holdings — composition courante de chaque portefeuille
• showcase_history — valorisation historique par portefeuille (pour les courbes vs benchmark)

OCR

• claude_vision_global_quota — compteur mensuel global d'appels Vision sur la clé admin (clé = mois ISO YYYY-MM)

⏰ Processus planifiés (cron)

Plusieurs jobs tournent sur des planifications définies dans wrangler.toml du worker :

📐 Scoring & classification

Classification automatique (enveloppe / risque / horizon)

Pour chaque instrument, BOS déduit déterministe-ment :

• Enveloppe conseillée — fonction de l'éligibilité PEA / PEA-PME (selon place de cotation, capi, secteur) et de la capitalisation
• Profil de risque — fonction de la volatilité annualisée + qualité score (issu des fondamentaux pour les actions, des frais + tracking error pour les ETF)
• Horizon recommandé — fonction de la volatilité + drawdown max + score qualité

Qualité score

Pour les actions, agrégat pondéré sur 5 axes : rentabilité (ROE, ROA), efficacité (marge nette), solidité (debt/equity, current ratio), croissance (CA, EPS YoY), valorisation (P/E, P/B). Pour les ETF : frais, écart de réplication, ancienneté, encours, place de cotation.

Indicateurs techniques utilisés

• Moyennes mobiles 50 et 200 jours (tendance)
• RSI 14 jours (momentum)
• MACD (signal de retournement)
• Performances 1m / 3m / 6m / 1y / 3y / 5y
• Volatilité annualisée (écart-type des log-returns × √252)
• Drawdown max sur la fenêtre disponible

🎯 Logique du verdict

Le verdict est déterministe : aucune IA, aucun appel LLM. Il croise les signaux ci-dessus dans une logique de règles. Niveaux :

• RENFORCER — tendance positive (prix > MM50 et MM200) + momentum sain (RSI 50-70, MACD positif) + fondamentaux solides
• CONSERVER — situation neutre ou légèrement positive, pas de signal majeur
• ALLÉGER — au moins un signal de dégradation : RSI > 75 (surachat), MACD baissier, prix sous MM50
• SORTIR — plusieurs signaux dégradés : prix sous MM200 + RSI < 30 + momentum négatif

Chaque verdict d'analyse est écrit dans analyses avec un payload JSON triggers (ce qui a déclenché le verdict) et signals (les valeurs détaillées). La page Analyser et le modal historique skill exploitent ces données pour expliquer l'évolution.

🔐 Authentification & rôles

Flow JWT BOS

1. L'utilisateur clique « Se connecter avec Google »
2. Google renvoie un ID token (JWT signé par Google)
3. Le worker vérifie le token, lit l'email, regarde si l'email est dans allowed_users
4. Si autorisé, le worker émet un JWT BOS (HS256 signé avec JWT_SECRET) avec { email, role, name, iat, exp }
5. Le browser stocke ce JWT BOS dans localStorage (bos_jwt) et l'envoie en Authorization: Bearer ... sur chaque appel API
6. Le worker valide le JWT à chaque requête (signature + exp). Toute mutation passe par requireAuth(req, env, role)

Rôles

• reader — peut lire les analyses, sa propre data, importer son portefeuille
• admin — peut gérer la whitelist, valider les instruments, voir les logs, gérer Vision

Chiffrement données users

AES-256-GCM avec une clé dérivée par SHA-256(ENCRYPTION_KEY + email). Chaque user a donc sa propre clé de chiffrement effective, dérivée d'une master key serveur. Conséquence : même si la D1 est exfiltrée, lire les positions nécessite l'ENCRYPTION_KEY (qui reste dans les secrets Workers).

🔌 API endpoints

Toutes les routes sont préfixées /api/ et exposées sur le worker. Quelques exemples :

Auth

• POST /api/auth/google — échange ID token Google contre JWT BOS
• GET /api/auth/me — info user courant + préférences + quota Vision
• POST /api/auth/anthropic-key — stocke (chiffré) la clé Anthropic perso ou admin

Portefeuille perso

• GET /api/portfolio/positions — lire ses positions chiffrées
• POST /api/portfolio/positions — upsert positions (chiffrement transparent)
• POST /api/portfolio/ocr-import — extraction OCR via Vision

Skill & analyses

• GET /api/analyses/:ticker?history=N — historique des verdicts skill + prix
• GET /api/instruments/search?q=... — recherche cascade Yahoo + OpenFIGI
• GET /api/fundamentals/:ticker — récupération directe des fondamentaux

Admin

• GET /api/admin/audit-log
• GET /api/admin/instruments-waiting + POST promote / DELETE reject
• GET /api/admin/vision-quotas + POST /api/admin/users/:email/vision-grant

🖼️ OCR Claude Vision

Trois voies d'extraction :

1. Clé admin partagée — l'admin (par convention cyc.eric.57@gmail.com) stocke sa clé Anthropic. Les autres users peuvent l'utiliser, limités à 10 appels gratuits chacun. Quota mensuel global : 500 appels.
2. Clé perso — chaque user peut stocker sa propre clé. Illimité, à sa charge (~0,001 €/image).
3. Tesseract.js — OCR client-side, CDN jsdelivr, gratuit illimité. Ne lit pas les PDF natifs.

Modèle

Claude Haiku 4.5 (claude-haiku-4-5-20251001). Choix : rapide (~3s/image), peu cher (~0,001 €/image), précision excellente sur les tableaux de portefeuille de courtiers européens et US.

Confidentialité images

Zéro stockage côté serveur. Le worker reçoit l'image en base64 dans le body POST, la passe à l'API Anthropic, et ne l'écrit nulle part (ni D1, ni R2, ni KV, ni log). L'audit log enregistre uniquement le NOMBRE d'images, l'enveloppe détectée, et le nombre de positions extraites.

Support PDF

Claude Vision Haiku 4.5 accepte les PDF natifs via le content type document et le header anthropic-beta: pdfs-2024-09-25. Tesseract.js refuse le PDF (auto-désactivé côté UI dès qu'un PDF est sélectionné).

🚀 Déploiement

Worker

cd Output/v8_modules/bos-api
npx wrangler deploy

Pages

cd Output/cf_pages_setup
git add . && git commit -m "..." && git push

Cloudflare Pages se synchronise automatiquement avec le repo Git en quelques secondes.

D1

Migrations SQL appliquées via npx wrangler d1 execute ou via la console Cloudflare Dashboard → D1. Les fichiers .sql historiques sont archivés dans Output/d1_setup/.