# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Projet

Système de **routage et traitement des emails de devis** (quotations). Des demandes
arrivent sur **plusieurs boîtes mail distinctes** ; on les centralise, on les route, et on
**assiste la rédaction** des réponses via Claude 4.5 — **brouillon généré, révision humaine
obligatoire avant tout envoi**. Brief complet : `docs/brief.md`.

Phase actuelle : **POC Zammad self-hosted (Docker)** sur un **domaine de test dédié**
(`vivacoda.com`), pour valider routage + traitement sans impacter la production. Le routage
(Postmaster Filters) et le hook IA (ADR 0002) sont **validés end-to-end** ; layout des files
d'agents = **option C hybride** choisie par ADVMFR (2 overviews : « Quote — to handle »,
« Triage — to sort »).

## Architecture (vue d'ensemble)

```
Boîtes mail (7)  ──►  Zammad (cœur)  ──►  brouillon IA  ──►  révision humaine  ──►  envoi
                      tickets +           Writing Assistant     (jamais
                      Postmaster Filters  natif (Anthropic)      d'auto-send)
```

- **Zammad self-hosted = le cœur.** Ingestion multi-mailbox → tickets. Routage et
  catégorisation via les **Postmaster Filters** (à l'ingestion, hors Elasticsearch — cf.
  `config/routing/seed_postmaster_filters.rb`). Suivi de statut = états de ticket Zammad.
- **Brouillon IA — tranché (ADR 0002)** : fonctions IA **natives** de Zammad, provider
  **Anthropic**, modèle `claude-sonnet-4-6`, surface = **Writing Assistant** (outils custom
  type « Draft quote reply »). L'agent déclenche → Claude rédige → l'agent relit et envoie.
  **Aucun envoi automatique.** Porte de sortie si besoin dépasse le natif : service externe
  webhook → ADR 0003 (non ouvert).

### Repères dossiers

| Dossier | Rôle |
|---|---|
| `infra/zammad/` | Stack Zammad (docker-compose vendoré, upstream `zammad/zammad-docker-compose`) |
| `docs/brief.md` | Brief d'origine |
| `docs/adr/` | Décisions d'architecture figées (ADR) |
| `docs/research/` | Notes de recherche encore utiles (setup local, routage mailboxes, IA différée) |
| `docs/decisions-advmfr.md` | Décisions prises par l'équipe ADVMFR (Roma…) |
| `config/routing/` + `config/zammad/` | Seeds idempotents de la config Zammad (rails console) |
| `tests/routing-sim/` | Envoi d'emails de test (Resend) + vérification du routage |

## Commandes (infra Zammad)

Depuis `infra/zammad/` :

```bash
cp .env.dist .env                                   # puis renseigner ZAMMAD_FQDN = domaine de test
docker compose up -d                                # démarre la stack
docker compose ps                                   # état des services
docker compose logs -f zammad-railsserver           # logs app
docker compose down                                 # arrêt
docker compose config                               # valider le compose sans démarrer
```

Notes infra :
- Services : `zammad-railsserver`, `zammad-nginx`, `zammad-postgresql`, `zammad-redis`,
  `zammad-elasticsearch`, `zammad-memcached`, `zammad-scheduler`, `zammad-websocket`,
  `zammad-init`, `zammad-backup`.
- **Elasticsearch est requis** par `zammad-init` (désactivable via `ELASTICSEARCH_ENABLED=false`).
- `ZAMMAD_FQDN` = domaine de test ; `VERSION` épingle la version Zammad (cf. `.env.dist`).
- Scénarios optionnels dans `infra/zammad/scenarios/` : `add-cloudflare-tunnel.yml`,
  `add-ollama.yml`, `apply-resource-limits.yml`, etc. — à charger en plus du compose de base.
  ⚠️ `add-ollama.yml` = LLM **local**, à ne pas confondre avec Claude 4.5 (API Anthropic).

## Travailler avec l'API Claude

Pour tout ce qui touche la génération de brouillons (modèles, pricing, tool use, API
Anthropic) : utiliser le skill **`claude-api`** plutôt que la mémoire. Modèle retenu pour
le POC : `claude-sonnet-4-6` (cf. ADR 0002 — bascule Opus triviale si un cas le justifie).

## Règles projet (override le comportement par défaut)

- **Non-complaisant + brainstorming** : avant tout travail créatif (feature, design,
  changement de comportement), poser des questions et passer par le brainstorming. Ne pas
  être complaisant : challenger les hypothèses.
- **Organisation des dossiers** : on organise et met à jour l'arborescence — **jamais
  directement sur la branche `main`** (travail sur `dev` ou `feature/*`).
- **Git flow** : `main` = prod, `dev` = intégration, `feature/*` /
  `fix/*` éphémères depuis `dev`, merge fast-forward puis suppression. Jamais de commit
  direct sur `main`. Merge `dev → main` uniquement sur demande explicite.
- **Conventional Commits** obligatoires (`feat:`, `fix:`, `chore:`, `docs:`, `refactor:`…).
- **Sécurité dépendances** : préfixer toute install d'une nouvelle dépendance par `sfw`
  (Socket Firewall) — ex. `sfw pnpm install <pkg>`, `sfw uv pip install <pkg>`.
- Règles globales complètes : `~/Github/Rules/global-rules.md`.