efarmz-slackbot-data 1.0.0

package/Dockerfile

@@ -0,0 +1,15 @@
+FROM node:22-slim AS builder
+WORKDIR /app
+COPY package.json yarn.lock ./
+RUN yarn install --frozen-lockfile
+COPY . .
+RUN yarn build
+
+FROM node:22-slim AS runtime
+WORKDIR /app
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /app/docs ./docs
+COPY --from=builder /app/package.json ./
+ENV NODE_ENV=production
+CMD ["node", "dist/main.js"]

package/PRD.md

@@ -0,0 +1,119 @@
+---
+title: "[PRD] Bot Slack NL→SQL — efarmz-slackbot-data"
+type: prd
+status: approved
+---
+
+# PRD: Bot Slack — Interrogation en langage naturel sur les bases analytiques efarmz
+
+## Executive Summary
+
+Service Node.js/TypeScript standalone qui écoute les mentions et DM Slack, traduit les questions en langage naturel vers des requêtes SQL via un LLM (Claude Haiku 4.5) avec boucle agentique, exécute les requêtes en read-only sur les bases PostgreSQL analytiques efarmz, et renvoie les résultats formatés (texte / table monospace / CSV) en threading Slack. Architecture DDD hexagonale, sécurité SQL en 4 couches, déployé sur Clever Cloud via Docker.
+
+## Problem Statement
+
+L'équipe efarmz a besoin d'interroger ses bases analytiques PostgreSQL (commandes, clients, produits, Intercom…) sans écrire de SQL manuellement. Aujourd'hui, obtenir une statistique ad hoc nécessite de solliciter un développeur ou d'accéder directement à la base, ce qui est lent, bloquant et risqué. Un bot Slack permettrait à n'importe quel membre de l'équipe de poser une question en français et d'obtenir un résultat immédiat, sans exposition directe aux données ni risque de mutation accidentelle.
+
+## User Stories
+
+### Primary User Story
+
+En tant que membre de l'équipe efarmz, je veux poser une question en langage naturel dans Slack (mention ou DM) et recevoir la réponse tirée de la base de données en quelques secondes, sans écrire de SQL.
+
+### Additional User Stories
+
+- En tant qu'analyste, je veux recevoir un tableau monospace ou un fichier CSV pour les résultats larges, afin de pouvoir les exploiter directement.
+- En tant que développeur, je veux ajouter `--sql` à ma question pour voir la requête SQL générée et vérifier sa pertinence.
+- En tant que développeur, je veux ajouter `--debug` pour obtenir le plan d'exécution EXPLAIN et diagnostiquer les performances.
+- En tant qu'utilisateur, je veux que le bot se souvienne du contexte du thread pour poser des questions de suivi sans répéter le contexte.
+- En tant qu'administrateur, je veux recevoir des logs de chaque requête (question, SQL, durée, coût token) dans un channel admin dédié.
+
+## Functional Requirements
+
+- Le bot répond aux `app_mention` et aux DM (`message.im`)
+- Le message est parsé : strip de la mention `<@U…>`, extraction des flags `--sql`, `--debug`, `--no-context`
+- La boucle agentique traduit la question en SQL via Claude Haiku 4.5, exécute via `run_sql` tool, corrige automatiquement sur erreur SQL (max 5 tours)
+- Le SQL est validé avant exécution : SELECT/WITH uniquement, keywords mutables refusés, LIMIT forcé à 100 lignes max
+- Le format de réponse est déterministe : scalaire (1×1), table monospace (≤15 lignes), table tronquée + CSV uploadé (>15 lignes)
+- L'historique de conversation est maintenu par thread (LRU mémoire, TTL 1h, max 200 threads, max 8 messages)
+- Le flag `--no-context` ignore l'historique du thread courant
+- Le flag `--debug` ajoute le SQL + résultat EXPLAIN au message
+- Le bot log chaque requête dans le channel admin (question, sqls[], rowsCount, durationMs, tokens)
+- Le boot échoue si une variable d'environnement requise est manquante (fail-fast via zod)
+- La doc des schémas PostgreSQL est chargée depuis `docs/schemas/*.md` au démarrage
+
+## Non-Functional Requirements
+
+- **Performance** : ack Slack < 3s (200 OK immédiat, traitement async) ; timeout SQL = 30s ; réponse totale < 60s
+- **Sécurité** : utilisateur PostgreSQL read-only dédié + RegexSqlValidator + statement_timeout + SqlQuery VO (constructeur privé) — 4 couches indépendantes
+- **Fiabilité** : idempotence par `event_id` (cache 5 min) pour absorber les retries Slack
+- **Coûts** : prompt caching (`cache_control: ephemeral`) sur la doc schémas — économie ~80% tokens sur rafales ; modèle Haiku = quelques centimes/question
+- **Maintenabilité** : architecture DDD hexagonale stricte, dependency rule non-négociable, ports fins (ISP), tests unitaires sur domain + validators + formatters
+- **Extensibilité** : interface `LLMProvider` découplée — ajouter OpenAI = 1 fichier, 0 modif ailleurs
+- **Déploiement** : Dockerisé, déployable sur Clever Cloud sans friction
+
+## Success Metrics
+
+### Primary Metrics
+
+- Taux de réponse correcte (SQL valide + résultat pertinent) : > 85% des questions
+- Temps de réponse médian (de la question à la réponse Slack) : < 15s
+- Zéro mutation de données en production (garantie structurelle, pas de monitoring)
+
+### Secondary Metrics
+
+- Coût moyen par question : < 0,05€ (Haiku 4.5 + caching)
+- Taux de correction automatique SQL (boucle agentique) : mesuré via logs admin
+- Adoption : > 5 utilisateurs actifs dans les 2 premières semaines
+
+## Technical Considerations
+
+Architecture hexagonale en 3 couches strictes (`domain` ← `application` ← `infrastructure` ← `main`) avec DI manuelle via `Container`. La règle de dépendance est non-négociable : `domain` n'importe aucun SDK tiers. La boucle agentique (`AgentLoop`) est indépendante du provider LLM et du tool concret. Le prompt caching Anthropic (`cache_control: ephemeral`, TTL 5 min) est appliqué sur le bloc system contenant la doc schémas.
+
+Voir `.plans/efarmz-slackbot-data-712fe7.md` pour l'architecture complète, la structure des fichiers, les variables d'environnement et le SQL d'init du rôle read-only.
+
+## Implementation Phases
+
+### Phase 1 — Bootstrap & Domain (F1 + F2)
+
+Setup du projet (tooling, config, Docker) et implémentation de la couche domain pure : entités, value objects, erreurs typées, ports (interfaces). Tests unitaires domain.
+
+### Phase 2 — Application & Infrastructure (F3 + F4)
+
+Use cases (`ParseQuestion`, `AnswerQuestion`), boucle agentique (`AgentLoop`), formatters de réponse. Puis adapters infra : `RegexSqlValidator`, `PostgresSqlExecutor`, `InMemoryConversationRepository`, `AnthropicLLMProvider`, handlers Slack, `PinoLogger`.
+
+### Phase 3 — Config, Déploiement & Documentation (F5 + F6)
+
+Composition root (`Container`), entry point (`main.ts`), doc des schémas PostgreSQL efarmz, `Dockerfile`, déploiement Clever Cloud, README.
+
+## Risk Assessment
+
+### Technical Risks
+
+- **Qualité SQL générée** : Haiku peut générer des JOINs incorrects sur des schémas complexes → mitigation : doc schémas détaillée + boucle de correction automatique (max 5 tours)
+- **Timeout LLM** : API Anthropic down → message Slack "Service IA temporairement indisponible" + log admin
+- **Retries Slack** : event redelivery peut déclencher des doublons → mitigation : déduplication par `event_id` (cache 5 min)
+- **Explosion tokens** : historique de conversation trop long → mitigation : résumé condensé (pas les `tool_result` bruts), cap à 8 messages, TTL 1h
+
+### Business Risks
+
+- **PII dans les résultats** : les tables peuvent contenir emails/noms → mitigation : workspace Slack privé uniquement, accepté
+- **Questions hors-scope** : le LLM peut tenter des requêtes sur des tables sans documentation → mitigation : doc schémas complète obligatoire avant déploiement
+
+## Dependencies
+
+### Internal Dependencies
+
+- Doc schémas PostgreSQL efarmz (`docs/schemas/efarmz_db.md`, etc.) — fournie par l'utilisateur
+- Credentials PostgreSQL (rôle `slackbot_readonly` à créer manuellement)
+- Slack App configurée avec les bons scopes et l'URL de webhook
+
+### External Dependencies
+
+- `@slack/bolt` — HTTP receiver
+- `@anthropic-ai/sdk` — Claude Haiku 4.5, tool_use, prompt caching
+- `pg` — PostgreSQL pool
+- `zod` — validation env vars + schemas
+- `pino` — structured logging
+- `vitest` — tests unitaires
+- Clever Cloud — hébergement Docker

package/docs/schemas/_guidelines.md

@@ -0,0 +1,89 @@
+# Guidelines — Mise à jour des docs schémas
+
+Directives pour créer le skill `update-schema-doc` qui modernise les fiches schéma PostgreSQL.
+
+## Entrées attendues
+
+L'utilisateur fournit en langage libre un des cas suivants :
+
+| Cas | Exemple | Cible dans le doc |
+|---|---|---|
+| Nouvelle table | "Ajoute la table `efarmz_db.coupons` avec colonnes id, code, discount, expires_at" | `## Tables / ### {domaine}` |
+| Nouvelles colonnes | "Sur `art`, ajoute `weight_kg numeric` et `origin_country varchar`" | Lignes dans le tableau de la table |
+| Suppression colonne | "Retire `psecotax` de `art`, on ne l'utilise plus" | Tableau de la table |
+| Nouvelle règle métier | "Une commande est *cadeau* si `eorderd.artid = 'GIFT'` et `totalpaid = 0`" | `## Règles métier / ### {thème}` |
+| Nouveau pattern SQL | "Voici le pattern pour calculer le délai entre commande et livraison : …" | `## Patterns SQL` (avec ancre) |
+| Nouvelle gotcha PG | "Si tu fais `SUM(qty)` sur `eorderd` sans `GROUP BY w_orderid`, ça double-compte les meals" | `## Conventions globales` |
+| Mise à jour règle existante | "Le seuil panier picking passe de 40 à 50" | Bloc existant + bump `last_updated` |
+| Nouvel alias | "On utilise aussi `cuid` pour `c_uuid` dans certains exports" | `## Glossaire` |
+
+## Algorithme
+
+1. **Lire** `docs/schemas/{schema}.md` en entier.
+2. **Classifier** l'input → un (ou plusieurs) des cas du tableau ci-dessus. Si ambigu, demander.
+3. **Détecter doublon** :
+   - Pour une règle / pattern : grep sur le nom et sur le SQL canonique avant d'ajouter. Si existe → proposer un *update* au lieu d'un *ajout*.
+   - Pour une colonne : si déjà présente, demander si on remplace la description ou non.
+4. **Choisir l'emplacement** :
+   - Table → mapper au domaine (Commandes / Catalogue / Abonnements / Clients / Référentiel). Si aucun ne colle, demander avant de créer une nouvelle sous-section.
+   - Règle métier → mapper à un thème existant (Filtres / Validité / Calculs / Frais). Sinon créer un thème.
+   - Pattern → bas de la section, avec ancre `#pattern-{slug}` cohérente.
+5. **Appliquer l'édition** via `Edit` (string replace ciblé). Jamais `Write` complet — préserve le cache Anthropic et minimise le diff.
+6. **Bumper le frontmatter** : `last_updated: {today}`.
+7. **Vérifier l'invariant de format** :
+   - Backticks autour de tout nom SQL.
+   - Tableaux avec exactement les colonnes `| Colonne | Type | Rôle | Description |`.
+   - `⚠️` pour pièges, pas d'autres emojis.
+   - Pas de numérotation `## 1`, `## 2` — titres seuls.
+8. **Retourner** un résumé : section touchée, lignes ajoutées/modifiées, alertes éventuelles (doublon détecté, ambiguïté résolue).
+
+## Règles d'or (non-négociables)
+
+- **DRY** : une règle métier vit à **un** seul endroit. Si un pattern SQL la matérialise, il **référence** la règle (`-- voir Règles métier / Validité abonnement`), il ne la duplique pas.
+- **Pas de renumérotation** : titres sans numéros. Réorganiser ne casse pas les ancres.
+- **Insertion en fin de sous-section** par défaut — préserve le cache Anthropic.
+- **Refuser le contournement de sécurité** : si l'utilisateur demande d'ajouter une règle qui implique une mutation SQL (`UPDATE`, `DELETE`…), c'est hors-scope du bot read-only. Refuser et expliquer.
+- **Demander avant de créer une nouvelle sous-section de domaine** ou un nouveau thème de règle métier — la taxonomie doit rester stable.
+- **Ne jamais éditer le schéma sans validation** : si l'utilisateur dit "ajoute la colonne X" sans préciser le type, demander le type (et idéalement, vérifier en DB, ou demander à l'utilisateur de la fournir).
+
+## Convention de tableau de colonnes
+
+```markdown
+| Colonne | Type | Rôle | Description |
+|---|---|---|---|
+| `id` | `uuid` | PK | — |
+| `user_id` | `uuid` | FK → `users.id` | — |
+| `status` | `int` | — | `1` = actif, `2` = pausé |
+```
+
+- **Rôle** : `PK`, `FK → table.col`, `unique`, ou `—`.
+- **Description** : sémantique métier seule. Pas de "FK vers X" dans description (c'est dans Rôle).
+- **Type** : type SQL réel (`varchar(255)`, `numeric(10,2)`, `timestamp`, `int`, etc.).
+
+## Convention de pattern SQL
+
+````markdown
+### {Nom court} {#pattern-{slug}}
+**Quand** : {1 phrase, cas d'usage}
+**Dépend de** : {refs aux règles métier ou autres patterns, optionnel}
+
+```sql
+-- code
+```
+
+⚠️ {piège éventuel, optionnel}
+````
+
+## Frontmatter du schéma
+
+Chaque fichier `docs/schemas/{schema}.md` doit commencer par :
+
+```yaml
+---
+schema: {nom du schéma}
+sgbd: postgresql
+last_updated: YYYY-MM-DD
+---
+```
+
+Le `last_updated` est bumé à chaque édition via le skill.