Updated Claude code config
parent
2e315f21c3
commit
2a10f95b22
@ -0,0 +1,11 @@
|
||||
{
|
||||
"env": {
|
||||
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
|
||||
},
|
||||
"permissions": {
|
||||
"allow": [
|
||||
"Skill(update-config)",
|
||||
"Bash(jq:*)"
|
||||
]
|
||||
}
|
||||
}
|
||||
@ -1,68 +1,121 @@
|
||||
# Documentation Technique et Fonctionnelle : AI Weekly Synth
|
||||
|
||||
## 🎯 Objectif de l'application
|
||||
## Objectif de l'application
|
||||
**AI Weekly Synth** est une application web permettant de générer automatiquement des synthèses d'actualités personnalisées et thématisées. Conçue pour la veille technologique ou sectorielle (par défaut centrée sur l'Intelligence Artificielle), elle utilise l'IA générative (Google Gemini) pour rechercher, filtrer, résumer et catégoriser les actualités récentes. L'application est multi-utilisateurs, garantissant à chacun un espace de veille privé et sur-mesure.
|
||||
|
||||
## ✨ Fonctionnalités offertes
|
||||
## Fonctionnalités offertes
|
||||
* **Authentification sécurisée** : Connexion via compte Google (SSO) garantissant la protection des données personnelles.
|
||||
* **Génération de synthèses par IA** : Recherche sur le web et création de résumés structurés basés sur les paramètres de l'utilisateur.
|
||||
* **Gestion des sources personnalisées** : Possibilité d'ajouter des URLs spécifiques (blogs, sites d'actualité, flux) que l'IA doit consulter en priorité lors de la génération.
|
||||
* **Envoi par email** : Envoi direct de la synthèse via l'API Gmail (OAuth popup pour obtenir un access token).
|
||||
* **Gestion des sources personnalisées** : Ajout d'URLs spécifiques (blogs, sites d'actualité) avec import/export CSV et import en masse.
|
||||
* **Configuration sur-mesure (Paramètres)** :
|
||||
* Choix du thème de veille (ex: "Intelligence Artificielle", "Cybersécurité", "Économie").
|
||||
* Définition de la fenêtre de recherche (ex: les 7 derniers jours).
|
||||
* Personnalisation des catégories de la synthèse (ex: "Annonces majeures", "Secteur public", etc.).
|
||||
* Choix du modèle d'IA (Gemini 3.1 Pro, Flash, etc.).
|
||||
* Personnalisation des catégories de la synthèse (jusqu'à 20 catégories).
|
||||
* Choix du modèle d'IA (Gemini 3.1 Pro, 3.0 Flash, 3.1 Flash Lite, 2.5 Flash).
|
||||
* Modification du "prompt" de comportement de l'agent de recherche.
|
||||
* **Historique et consultation** : Sauvegarde de toutes les synthèses générées pour une consultation ultérieure, avec liens directs vers les articles sources.
|
||||
* Export/import des paramètres en JSON.
|
||||
* **Historique et consultation** : Sauvegarde de toutes les synthèses générées pour une consultation ultérieure, avec liens directs vers les articles sources et suppression avec double confirmation.
|
||||
|
||||
## 🔄 Principaux "User Flows" (Parcours Utilisateur)
|
||||
## Structure du projet
|
||||
|
||||
1. **Onboarding & Configuration initiale**
|
||||
* L'utilisateur arrive sur la page de connexion et s'authentifie avec Google.
|
||||
* Il se rend dans l'onglet **Paramètres** pour définir son thème de veille, ses catégories et le modèle d'IA souhaité.
|
||||
* Il se rend dans l'onglet **Sources personnalisées** pour ajouter les sites qu'il considère comme incontournables.
|
||||
```
|
||||
src/
|
||||
├── main.tsx # Point d'entrée React
|
||||
├── App.tsx # Router, Layout, ProtectedRoute, Login
|
||||
├── index.css # Import Tailwind uniquement
|
||||
├── firebase.ts # Init Firebase, helpers auth, gestion erreurs Firestore
|
||||
├── types.ts # Interfaces (NewsItem, SynthesisData, AppSettings, etc.) + DEFAULT_SETTINGS
|
||||
├── components/
|
||||
│ └── AuthContext.tsx # Provider React Context pour l'authentification
|
||||
├── pages/
|
||||
│ ├── Home.tsx # Dashboard : liste des synthèses avec apercu et suppression
|
||||
│ ├── GenerateSynthesis.tsx # Declenchement de la generation IA
|
||||
│ ├── SynthesisDetail.tsx # Lecture detaillee + envoi email + suppression
|
||||
│ ├── Sources.tsx # CRUD sources personnalisees (unitaire, CSV, masse)
|
||||
│ └── Settings.tsx # Parametres utilisateur (theme, categories, modele IA, etc.)
|
||||
└── services/
|
||||
└── geminiService.ts # Logique IA : generation 2 passes + validation/scraping URLs
|
||||
```
|
||||
|
||||
2. **Génération d'une veille hebdomadaire**
|
||||
* L'utilisateur clique sur "Nouvelle synthèse".
|
||||
* L'application récupère ses paramètres et ses sources, puis interroge l'API Gemini.
|
||||
* Un indicateur de chargement patiente pendant que l'IA effectue ses recherches sur le web et rédige le contenu.
|
||||
* Une fois terminée, la synthèse est sauvegardée et l'utilisateur est redirigé vers la vue détaillée pour lire son rapport.
|
||||
## Architecture de la solution
|
||||
L'application repose sur une architecture **Serverless (BaaS - Backend as a Service)**. Il n'y a pas de serveur backend intermediaire.
|
||||
|
||||
3. **Consultation de l'historique**
|
||||
* Depuis l'accueil (Dashboard), l'utilisateur visualise la liste chronologique de ses précédentes synthèses.
|
||||
* Il peut cliquer sur l'une d'elles pour la relire ou la supprimer s'il n'en a plus besoin.
|
||||
* **Frontend** : Application Single Page (SPA) en React 19 qui gère l'interface, le routage (`react-router-dom` v7) et l'état de l'application.
|
||||
* **Backend / Base de données** : Firebase Firestore (NoSQL) pour stocker les paramètres, les sources et les synthèses. Les requêtes sont faites directement depuis le client React.
|
||||
* **Sécurité des données** : Les `firestore.rules` garantissent le cloisonnement des données (Multi-tenant). Chaque document possède un champ `authorUid` ou `userId` vérifié à chaque requête (`isDocOwner()`).
|
||||
* **Intelligence Artificielle** : Le SDK `@google/genai` est appelé directement depuis le frontend. L'outil `googleSearch` est activé pour le "Grounding" (recherche web en temps réel).
|
||||
|
||||
## 🏗️ Architecture de la solution
|
||||
L'application repose sur une architecture **Serverless (BaaS - Backend as a Service)**. Il n'y a pas de serveur backend Node.js/Express intermédiaire géré manuellement.
|
||||
### Pipeline de generation (geminiService.ts)
|
||||
|
||||
* **Frontend** : Application Single Page (SPA) en React qui gère l'interface, le routage et l'état de l'application.
|
||||
* **Backend / Base de données** : Firebase Firestore (NoSQL) est utilisé pour stocker les paramètres, les sources et les synthèses. Les requêtes sont faites directement depuis le client React.
|
||||
* **Sécurité des données** : Les `firestore.rules` garantissent le cloisonnement des données (Multi-tenant). Chaque document possède un champ `authorUid` ou `userId` vérifié à chaque requête (`isDocOwner()`).
|
||||
* **Intelligence Artificielle** : Le SDK `@google/genai` est appelé directement depuis le frontend. L'outil `googleSearch` est activé dans la configuration du modèle pour permettre le "Grounding" (recherche web en temps réel).
|
||||
La generation s'effectue en **2 passes** :
|
||||
|
||||
1. **Passe 1 - Recherche** : Gemini avec `googleSearch` grounding produit des news brutes par categorie (JSON structure via `responseSchema`). Les categories sont dynamiques, basees sur les `settings.categories` de l'utilisateur (cles `category_0`, `category_1`, etc.).
|
||||
|
||||
2. **Validation/Scraping des URLs** : Chaque URL retournee est verifiee via 3 proxies CORS en cascade (`allorigins` -> `codetabs` -> `corsproxy.io`). Les articles sont filtres si : URL invalide/404, contenu d'erreur (soft 404), ou date de publication trop ancienne (via meta tags, JSON-LD, balise `<time>`). Le contenu textuel est extrait (max 4000 caracteres).
|
||||
|
||||
3. **Passe 2 - Reecriture** : Gemini recrit les titres et resumes en se basant sur le contenu scrape reel des articles, garantissant la fidelite des resumes.
|
||||
|
||||
### Collections Firestore
|
||||
|
||||
| Collection | Document ID | Champs cles | Acces |
|
||||
|---|---|---|---|
|
||||
| `syntheses` | auto-generated | `week`, `sections[]` (ou champs legacy), `authorUid`, `createdAt` | Owner uniquement |
|
||||
| `sources` | auto-generated | `title`, `url`, `authorUid`, `createdAt` | Owner uniquement |
|
||||
| `settings` | `{userId}` | `theme`, `categories[]`, `maxAgeDays`, `maxItemsPerCategory`, `aiModel`, `searchAgentBehavior` | Owner uniquement |
|
||||
|
||||
### Routes
|
||||
|
||||
| Path | Composant | Description |
|
||||
|---|---|---|
|
||||
| `/login` | `Login` (dans App.tsx) | Connexion Google |
|
||||
| `/` | `Home` | Dashboard des syntheses |
|
||||
| `/generate` | `GenerateSynthesis` | Lancement de la generation |
|
||||
| `/synthesis/:id` | `SynthesisDetail` | Vue detaillee d'une synthese |
|
||||
| `/sources` | `Sources` | Gestion des sources personnalisees |
|
||||
| `/settings` | `Settings` | Parametres de generation |
|
||||
|
||||
## Choix technologiques
|
||||
* **Framework UI** : React 19 avec Vite 6 (plugin `@vitejs/plugin-react`).
|
||||
* **Langage** : TypeScript 5.8 avec typage strict (`src/types.ts` centralise les interfaces).
|
||||
* **Styling** : Tailwind CSS v4 (via `@tailwindcss/vite` plugin, import unique dans `index.css`).
|
||||
* **Icônes** : `lucide-react` pour les icônes SVG.
|
||||
* **Base de données & Auth** : Firebase 12 (Firestore + Authentication avec Google provider).
|
||||
* **IA** : API Google Gemini (`@google/genai`) avec génération structurée (`responseSchema` + `Type` enum) et grounding (`googleSearch`).
|
||||
* **Utilitaires** : `date-fns` pour le formatage des dates en français.
|
||||
|
||||
## Maintenance et Evolution
|
||||
|
||||
### Points d'attention pour les developpeurs
|
||||
|
||||
1. **Rate Limiting**
|
||||
* Le `RateLimiter` dans `geminiService.ts` est configure a 29 requetes/minute. Il est in-memory et par-onglet : plusieurs onglets ouverts peuvent depasser le quota. Tout nouvel appel Gemini doit passer par `await geminiRateLimiter.acquire()`.
|
||||
|
||||
2. **Generation Structuree (JSON Schema)**
|
||||
* Le schema de reponse est genere dynamiquement a partir de `settings.categories`. Si vous modifiez la structure des donnees (ex: ajout d'un champ `imageUrl` par article), vous **devez** mettre a jour : `newsItemSchema` dans `geminiService.ts` ET l'interface `NewsItem` dans `types.ts`.
|
||||
|
||||
## 🛠️ Choix technologiques
|
||||
* **Framework UI** : React 18+ avec Vite.js pour un build ultra-rapide.
|
||||
* **Langage** : TypeScript pour le typage statique et la robustesse du code (`src/types.ts` centralise les interfaces).
|
||||
* **Styling** : Tailwind CSS pour un design utilitaire, responsive et moderne.
|
||||
* **Icônes** : `lucide-react` pour une bibliothèque d'icônes SVG légères et cohérentes.
|
||||
* **Base de données & Auth** : Firebase (Firestore + Authentication).
|
||||
* **IA** : API Google Gemini (modèles de la série 3.1 et 2.5) avec génération structurée (JSON Schema) pour garantir le formatage des catégories et des articles.
|
||||
* **Utilitaires** : `date-fns` pour le formatage lisible des dates en français.
|
||||
3. **Donnees legacy (SynthesisData)**
|
||||
* `SynthesisData` contient des champs legacy optionnels (`majorAnnouncements`, `financialSector`, etc.) ET le nouveau format `sections[]`. Le code de `Home.tsx` et `SynthesisDetail.tsx` gere les deux formats via des fallbacks. Les nouvelles syntheses utilisent uniquement `sections[]`.
|
||||
|
||||
## 💡 Divers (Maintenance et Évolution)
|
||||
4. **Cle API Gemini**
|
||||
* La cle `GEMINI_API_KEY` est injectee dans le bundle client via `vite.config.ts` (`process.env.GEMINI_API_KEY`). Elle est donc exposee dans le JavaScript du navigateur. Pour la production, il faudrait passer par un backend ou une Cloud Function.
|
||||
|
||||
Cette section regroupe des informations cruciales pour les développeurs reprenant le projet :
|
||||
5. **Proxies CORS**
|
||||
* `fetchHtmlContent` utilise 3 proxies tiers en cascade pour le scraping. Ces services sont non garantis et peuvent etre indisponibles. Si le scraping echoue, l'article est conserve avec un `scrapedContent` vide.
|
||||
|
||||
1. **Rate Limiting (Limitation de requêtes Gemini)**
|
||||
* Un limiteur de requêtes (`RateLimiter`) est implémenté dans `src/services/geminiService.ts`. Il est configuré pour éviter de dépasser les quotas de l'API Gemini (ex: 29 requêtes par minute). Si vous ajoutez des appels IA supplémentaires, assurez-vous de passer par ce limiteur (`await geminiRateLimiter.acquire()`).
|
||||
6. **Regles de securite Firestore (`firestore.rules`)**
|
||||
* Les regles sont strictes avec validation de champs (types, tailles, formats). Si vous ajoutez une nouvelle collection ou un nouveau champ, vous devez mettre a jour les regles ET les fonctions de validation (`isValidSynthesis`, `isValidSettings`, `isValidSource`).
|
||||
|
||||
2. **Génération Structurée (JSON Schema)**
|
||||
* Le service Gemini utilise la fonctionnalité `responseSchema` pour forcer l'IA à répondre avec un objet JSON strict correspondant aux catégories de l'utilisateur. Si vous modifiez la structure des données (ex: ajout d'une image pour chaque article), vous **devez** mettre à jour le schéma dans `geminiService.ts` (`newsItemSchema`) ET l'interface TypeScript dans `types.ts`.
|
||||
7. **Envoi email Gmail**
|
||||
* L'envoi utilise l'API Gmail directement depuis le client (`SynthesisDetail.tsx`). `getGmailAccessToken()` dans `firebase.ts` re-declenche un `signInWithPopup` a chaque envoi pour obtenir le scope `gmail.send`.
|
||||
|
||||
3. **Règles de sécurité Firestore (`firestore.rules`)**
|
||||
* Les règles actuelles sont très strictes. Si vous ajoutez une nouvelle collection (ex: `shared_syntheses` pour partager des veilles entre utilisateurs), vous devrez écrire de nouvelles règles spécifiques pour autoriser la lecture publique ou par groupe, tout en protégeant l'écriture.
|
||||
### Dependances inutilisees dans package.json
|
||||
* `motion`, `clsx`, `tailwind-merge` : importees mais non utilisees dans le code source actuel.
|
||||
* `express`, `@types/express`, `dotenv` : suggerent un composant serveur prevu ou supprime, aucun code serveur present.
|
||||
|
||||
4. **Évolutions possibles (Idées)**
|
||||
* **Envoi par email** : Ajouter une fonction pour envoyer la synthèse générée par email (nécessiterait une Cloud Function Firebase ou un service comme Resend/SendGrid).
|
||||
* **Génération automatique (CRON)** : Actuellement, la génération est manuelle (déclenchée par l'utilisateur). Pour la rendre 100% automatique tous les lundis matins, il faudrait déporter la logique de `geminiService.ts` dans une Google Cloud Function déclenchée par Cloud Scheduler.
|
||||
* **Export PDF/Markdown** : Ajouter un bouton sur la vue de détail pour télécharger la synthèse.
|
||||
### Evolutions possibles
|
||||
* **Securiser la cle API** : Deplacer l'appel Gemini vers une Cloud Function Firebase.
|
||||
* **Generation automatique (CRON)** : Cloud Function + Cloud Scheduler pour generer automatiquement chaque semaine.
|
||||
* **Export PDF/Markdown** : Bouton de telechargement sur la vue de detail.
|
||||
* **Error Boundary React** : Aucun error boundary n'est en place, un crash dans un composant fait tomber toute l'app.
|
||||
* **Nettoyage des donnees legacy** : Supprimer les champs `majorAnnouncements`, `financialSector`, etc. de `SynthesisData` une fois les anciennes syntheses migrees.
|
||||
Loading…
Reference in New Issue