efarmz-slackbot-data 1.0.0

package/docs/schemas/efarmz_db.md

@@ -0,0 +1,759 @@
+---
+schema: efarmz_db
+sgbd: postgresql
+last_updated: 2026-05-15
+---
+
+> Schéma principal : `efarmz_db`
+
+---
+
+## Conventions globales
+
+**Gotchas PostgreSQL** — appliquables à toutes les requêtes sur ce schéma.
+
+- ⚠️ `ROUND(double precision, int)` n'existe pas → toujours caster en `::numeric` avant `ROUND(..., 2)`
+- ⚠️ `NULLIF` obligatoire sur tous les dénominateurs (division par zéro sinon)
+- ⚠️ `artid` est `char(n)` (longueur fixe) → les valeurs sont paddées avec des espaces. Pour les patterns qui ciblent la fin de la chaîne (`LIKE '%P'`, regex `$`, `SUBSTRING ... P$`), toujours utiliser `RTRIM(artid)` d'abord.
+- Tie-breaker `w_orderid ASC` dans `ROW_NUMBER() ... ORDER BY dlvdate` (pour les cas où deux commandes même client même jour)
+- Factoriser en CTE si une sous-requête est réutilisée ≥ 2×
+- Casts fréquents : `::date`, `::timestamp`, `::numeric`, `date_trunc('week', ...)`
+
+---
+
+## Tables
+
+### Commandes
+
+#### `eorderh` — En-têtes de commandes (historique)
+
+| Colonne | Type | Rôle | Description |
+|---|---|---|---|
+| `w_orderid` | `varchar` | PK | ID commande |
+| `c_uuid` | `varchar` | FK → `users.id` | Identifiant client |
+| `dlvdate` | `timestamp` | — | Date de livraison (caster en `::date`) |
+| `status` | `int` | — | Statut de la commande (voir Règles métier / Filtres) |
+| `ordertype` | `int` | — | `1` = one-shot, `2` = abonnement |
+| `s_credate` | `timestamp` | — | Date de création |
+| `totalpaid` | `numeric` | — | Montant total payé |
+
+#### `eorderd` — Lignes de commandes (détail picking)
+
+| Colonne | Type | Rôle | Description |
+|---|---|---|---|
+| `w_orderid` | `varchar` | FK → `eorderh.w_orderid` | ID commande |
+| `artid` | `char(n)` | FK → `art.artid` | ID produit (alias `product_id` selon contexte) |
+| `qty` | `numeric` | — | Quantité commandée |
+| `unitprice` | `numeric` | — | Prix unitaire de la ligne |
+| `vatpc` | `numeric` | — | Taux de TVA appliqué à la ligne (%) |
+| `boxid` | `varchar` | — | ID box (NULL si pas de box) |
+
+#### `lgrefund` — Avoirs clients
+
+| Colonne | Type | Rôle | Description |
+|---|---|---|---|
+| `pkid` | `serial` | PK | ID avoir |
+| `artid` | `char(20)` | FK → `art.artid` | Alias `product_id` — produit concerné |
+| `amount` | `double precision` | — | Montant de l'avoir |
+| `date` | `timestamp` | — | Date de l'avoir |
+| `id_product` | `int` | FK → `art` | Produit concerné |
+| `id_cust` | `int` | FK → `users.id` | Client concerné |
+| `id_order` | `int` | — | Commande concernée |
+| `comment` | `text` | — | Commentaire |
+| `refundtype` | `int` | — | `1` = caution, `2` = manquant, `3` = plainte, `9` = commun |
+| `id_order_applied` | `int` | — | Numéro de commande si avoir appliqué |
+| `status` | `int` | — | Statut de l'avoir |
+| `issend` | `int` | — | Envoi effectué |
+| `s_credate` | `timestamp` | — | Date de création |
+| `s_moddate` | `timestamp` | — | Date de modification |
+
+---
+
+### Catalogue
+
+#### `art` — Catalogue produits
+
+| Colonne | Type | Rôle | Description |
+|---|---|---|---|
+| `artid` | `char(n)` | PK | ID produit |
+| `name1` | `varchar` | — | Nom du produit |
+| `finalprice` | `numeric` | — | Prix non-abonnés |
+| `catalogue1` | `numeric` | — | Prix abonnés |
+| `unit` | `varchar` | — | Unité |
+| `a_zone` | `varchar` | — | Zone picking : `SEC`, `FRAIS`, `UFRAIS` |
+| `a_prodtype` | `varchar` | — | Type : `PRODUIT`, `PANIER`, `ADMIN`, `PLAT` |
+| `ana1` | `varchar` | FK → `anacode.code` | Catégorie 1 |
+| `ana2` | `varchar` | FK → `anacode.code` | Catégorie 2 |
+| `ana4` | `varchar` | FK → `anacode.code` | Marque/brand |
+| `buyprice` | `numeric` | — | Prix d'achat |
+| `discount` | `numeric` | — | Remise fournisseur (%) |
+| `vatid` | `numeric` | — | Taux de TVA (%) |
+| `cp_stock` | `numeric` | — | Stock physique |
+| `cp_res` | `numeric` | — | Stock réservé |
+| `stocktype` | `varchar` | — | Type de stock |
+| `a_gesttype` | `varchar` | — | Type de gestion |
+| `a_okabo` | `int` | — | Disponible en abonnement |
+| `psecotax` | `numeric` | — | Écotaxe |
+| `a_parentid` | `varchar` | FK → `art.artid` | ID produit parent (pour plats multi-portions) |
+
+#### `ARTPART` — Composition des meals (ingrédients)
+
+| Colonne | Type | Rôle | Description |
+|---|---|---|---|
+| `ARTID` | `char(n)` | FK → `art.artid` | ID meal parent |
+| `ARTPARTID` | `char(n)` | FK → `art.artid` | ID ingrédient |
+| `QTY` | `numeric` | — | Quantité ingrédient |
+| `ORDER` | `int` | — | Numéro de ligne recette |
+| `S_MODDATE` | `timestamp` | — | Date modif (pour dédupliquer via ROW_NUMBER) |
+
+#### `anacode` — Référentiel catégories / marques
+
+| Colonne | Type | Rôle | Description |
+|---|---|---|---|
+| `code` | `varchar` | PK | FK depuis `art.ana1`, `art.ana2`, `art.ana4` |
+| `name1` | `varchar` | — | Libellé |
+
+#### `artfeature` — Association produit / tag
+
+| Colonne | Type | Rôle | Description |
+|---|---|---|---|
+| `artid` | `char(n)` | FK → `art.artid` | ID produit |
+| `featureid` | `int` | FK → `feature.featureid` | ID tag |
+
+#### `feature` — Tags produits
+
+| Colonne | Type | Rôle | Description |
+|---|---|---|---|
+| `featureid` | `int` | PK | ID tag |
+| `name1` | `varchar` | — | Libellé du tag |
+
+---
+
+### Abonnements
+
+#### `subscriptions` — Abonnements
+
+| Colonne | Type | Rôle | Description |
+|---|---|---|---|
+| `id` | `int` | PK | ID abonnement |
+| `user_id` | `int` | FK → `users.id` | ID client |
+| `next_delivery_date` | `timestamp` | — | Prochaine livraison |
+| `status` | `int` | — | `1` = actif (voir Règles métier / Validité abonnement) |
+| `deleted_at` | `timestamp` | — | NULL si non supprimé |
+
+#### `subscription_items` — Produits fixes de l'abonnement
+
+| Colonne | Type | Rôle | Description |
+|---|---|---|---|
+| `subscription_id` | `int` | FK → `subscriptions.id` | ID abonnement |
+| `product_id` | `char(n)` | FK → `art.artid` | ID produit |
+| `quantity` | `numeric` | — | Quantité |
+
+#### `subscription_add_items` — Produits additionnels ponctuels
+
+| Colonne | Type | Rôle | Description |
+|---|---|---|---|
+| `subscription_id` | `int` | FK → `subscriptions.id` | ID abonnement |
+| `product_id` | `char(n)` | FK → `art.artid` | ID produit |
+| `quantity` | `numeric` | — | Quantité |
+| `delivery_date` | `timestamp` | — | Date de livraison concernée |
+
+#### `subscription_generation_status` — Statut de génération d'abonnement
+
+| Colonne | Type | Rôle | Description |
+|---|---|---|---|
+| `id` | `bigserial` | PK | — |
+| `subscription_id` | `int` | FK → `subscriptions.id` | ID abonnement |
+| `temp_order_ref` | `varchar(255)` | — | Référence commande temporaire |
+| `payment_id` | `varchar(255)` | — | ID paiement |
+| `generation_date` | `date` | — | Date de génération de l'abonnement |
+| `type` | `varchar(255)` | — | `'short'` = produits shop, `'long'` = plats (voir Règles métier / Cutoffs abonnement) |
+| `status` | `varchar(255)` | — | `IS_ON_HOLD` paused · `NO_DELIVERY_WINDOW` · `CARRIER_OFF` · `EFARMZ_OFF` · `AMOUNT_TOO_LOW` · `PAYMENT_SUCCESS` · `NO_ITEMS` · `SUBSCRIPTION_OFF` · `UNEXPECTED_ERROR` · `AMOUNT_TOO_HIGH` · `PAYMENT_FAILED` · `USER_MISSING` · `USER_DELETED` |
+| `payment_link_id` | `varchar(255)` | — | ID lien de paiement |
+| `delivery_date` | `date` | — | Date de livraison de la commande |
+| `created_at` | `timestamp` | — | Date de création |
+| `updated_at` | `timestamp` | — | Date de mise à jour |
+
+#### `subscription_missing_product` — Produits manquants lors de la génération
+
+| Colonne | Type | Rôle | Description |
+|---|---|---|---|
+| `id` | `bigserial` | PK | — |
+| `user_id` | `int` | FK → `users.id` | Client concerné |
+| `subscription_id` | `int` | FK → `subscriptions.id` | Abonnement concerné |
+| `product_id` | `varchar(255)` | FK → `art.artid` | Produit manquant |
+| `quantity_available` | `int` | — | Quantité disponible au moment de la génération |
+| `quantity_requested` | `int` | — | Quantité demandée |
+| `price` | `double precision` | — | Prix unitaire |
+| `generation_date` | `date` | — | Date de génération de l'abonnement |
+| `delivery_date` | `date` | — | Date de livraison de la commande |
+| `created_at` | `timestamp` | — | Date de création |
+| `updated_at` | `timestamp` | — | Date de mise à jour |
+
+#### `subscription_off` — Pauses d'abonnement
+
+| Colonne | Type | Rôle | Description |
+|---|---|---|---|
+| `subscription_id` | `int` | FK → `subscriptions.id` | ID abonnement |
+| `start_date` | `timestamp` | — | Date de pause (= `next_delivery_date` du jour) |
+
+#### `meals_selected` — Meals choisis par l'abonné
+
+| Colonne | Type | Rôle | Description |
+|---|---|---|---|
+| `subscription_id` | `int` | FK → `subscriptions.id` | ID abonnement |
+| `product_id` | `char(n)` | FK → `art.artid` | ID meal kit (contient `%-%`) |
+| `week` | `timestamp` | — | Semaine du meal |
+| `created_at` | `timestamp` | — | Date de création de la sélection |
+
+---
+
+### Livraison
+
+#### `delivery_windows` — Fenêtres de livraison
+
+| Colonne | Type | Rôle | Description |
+|---|---|---|---|
+| `id` | `bigserial` | PK | — |
+| `user_id` | `varchar(255)` | FK → `users.id` | Client associé |
+| `carrier_id` | `varchar(255)` | FK → `carriers.id` | Transporteur choisi |
+| `postalcode` | `varchar(255)` | — | Code postal de livraison |
+| `city` | `varchar(255)` | — | Ville de livraison |
+| `country` | `varchar(255)` | — | Code pays ISO 2 (défaut `BE`) |
+| `addressline1` | `varchar(255)` | — | Adresse de livraison |
+| `created_at` | `timestamp` | — | Date de création |
+| `updated_at` | `timestamp` | — | Date de mise à jour |
+
+#### `delivery_window_order` — Pivot commande ↔ fenêtre de livraison
+
+| Colonne | Type | Rôle | Description |
+|---|---|---|---|
+| `delivery_window_id` | `int` | FK → `delivery_windows.id` | Fenêtre de livraison |
+| `w_orderid` | `varchar(255)` | FK → `eorderh.w_orderid` | Commande associée |
+
+#### `carriers` — Transporteurs
+
+| Colonne | Type | Rôle | Description |
+|---|---|---|---|
+| `id` | `bigint` | PK | — |
+| `name` | `varchar(255)` | — | Nom du transporteur |
+| `type` | `int` | — | `0` = à domicile, `1` = point dépôt |
+| `address1` | `varchar(255)` | — | Adresse du point dépôt |
+| `postcode` | `varchar(255)` | — | Code postal du point dépôt |
+| `city` | `varchar(255)` | — | Ville du point dépôt |
+| `lat` | `varchar(255)` | — | Latitude du point dépôt |
+| `lng` | `varchar(255)` | — | Longitude du point dépôt |
+| `d1` | `boolean` | — | Livre le lundi |
+| `d2` | `boolean` | — | Livre le mardi |
+| `d3` | `boolean` | — | Livre le mercredi |
+| `d4` | `boolean` | — | Livre le jeudi |
+| `d5` | `boolean` | — | Livre le vendredi |
+| `d6` | `boolean` | — | Livre le samedi |
+| `d7` | `boolean` | — | Livre le dimanche |
+| `active` | `boolean` | — | `true` = actif |
+
+#### `areas` — Zones de livraison
+
+| Colonne | Type | Rôle | Description |
+|---|---|---|---|
+| `id` | `bigserial` | PK | — |
+| `postcode` | `varchar(255)` | — | Code postal |
+| `name` | `varchar(255)` | — | Nom |
+| `commune` | `varchar(255)` | — | Commune |
+| `province` | `varchar(255)` | — | Province |
+| `region` | `varchar(255)` | — | Code région |
+| `region_name` | `varchar(255)` | — | Nom de la région |
+| `country` | `varchar(255)` | — | Code pays ISO 2 (défaut `BE`) |
+| `lat` | `numeric(5,3)` | — | Latitude |
+| `lng` | `numeric(5,3)` | — | Longitude |
+
+#### `area_carrier` — Association zone ↔ transporteur
+
+| Colonne | Type | Rôle | Description |
+|---|---|---|---|
+| `area_id` | `bigint` | FK → `areas.id` | Zone de livraison |
+| `carrier_id` | `bigint` | FK → `carriers.id` | Transporteur actif sur la zone |
+
+---
+
+### Avis
+
+#### `feedback` — En-têtes d'avis
+
+| Colonne | Type | Rôle | Description |
+|---|---|---|---|
+| `id` | `bigserial` | PK | — |
+| `user_id` | `int` | FK → `users.id` | Client ayant donné l'avis |
+| `delivered_at` | `date` | — | Date de livraison concernée |
+| `created_at` | `timestamp` | — | Date de création |
+| `updated_at` | `timestamp` | — | Date de mise à jour |
+
+#### `feedback_entries` — Détail des avis par plat
+
+| Colonne | Type | Rôle | Description |
+|---|---|---|---|
+| `id` | `bigserial` | PK | — |
+| `feedback_id` | `int` | FK → `feedback.id` | En-tête de l'avis |
+| `meal_id` | `text` | FK → `art.artid` | Alias `product_id` — plat évalué |
+| `meal_name` | `text` | — | Nom du plat au moment de l'avis |
+| `meal_image` | `text` | — | URL image du plat |
+| `rating` | `smallint` | — | Note globale de 0 à 10 |
+| `would_order_again` | `boolean` | — | Commanderait à nouveau |
+| `ease` | `smallint` | — | Facilité de préparation (0-10) |
+| `originality` | `smallint` | — | Originalité (0-10) |
+| `quantity` | `smallint` | — | Quantité (0-10) |
+| `taste` | `smallint` | — | Goût (0-10) |
+| `comment` | `text` | — | Commentaire libre |
+| `created_at` | `timestamp` | — | Date de création |
+| `updated_at` | `timestamp` | — | Date de mise à jour |
+
+---
+
+### Clients
+
+#### `users` — Clients
+
+| Colonne | Type | Rôle | Description |
+|---|---|---|---|
+| `id` | `bigint` | PK | ID client |
+| `first_order_subscription` | `timestamp` | — | Date de première commande abonnement |
+
+---
+
+## Règles métier
+
+### Filtres standards
+
+**Commandes valides** — exclure les annulations et remboursements
+```sql
+status NOT IN (31, 32)
+```
+
+**Jours ouvrés** — lundi à vendredi
+```sql
+extract(isodow from date) BETWEEN 1 AND 5
+```
+
+**Produits picking (shop)** — exclure les génériques
+```sql
+eorderd.artid NOT LIKE 'G%'
+```
+
+**Produits shop** — catalogue standard (excluant meals)
+```sql
+a_prodtype IN ('PRODUIT', 'PANIER', 'ADMIN')
+```
+
+### Validité abonnement
+
+**Abonnement actif valide**
+```sql
+s.status = 1
+AND s.deleted_at IS NULL
+AND s.next_delivery_date::date > (CURRENT_DATE + interval '1 day')
+AND NOT EXISTS (
+    SELECT 1 FROM efarmz_db.subscription_off so
+    WHERE so.subscription_id = s.id AND so.start_date = s.next_delivery_date
+)
+```
+
+### Calculs
+
+**Marge produit** — en %
+```sql
+((finalprice / NULLIF((1 + (vatid::float / 100)), 0))
+ - (buyprice - (buyprice * COALESCE(discount, 0) / 100)))
+/ NULLIF(finalprice / NULLIF((1 + (vatid::float / 100)), 0), 0) * 100
+```
+
+**Stock disponible** — stock physique moins réservations
+```sql
+cp_stock - COALESCE(cp_res, 0)
+```
+
+**Valeur stock** — au coût d'achat net
+```sql
+(cp_stock - COALESCE(cp_res, 0)) * (buyprice - (buyprice * COALESCE(discount, 0) / 100))
+```
+
+**Rotation stock** — à partir des ventes du mois précédent
+```sql
+sells_last_month / NULLIF(stock_disponible, 0)
+```
+
+**Montant hors TVA d'une ligne** — à partir de `eorderd`
+```sql
+ROUND(CAST((eorderd.unitprice - eorderd.unitprice * eorderd.vatpc / 100) AS numeric), 2)
+```
+
+**Seuil panier picking** — montant minimum pour déclarer une commande viable
+```
+total_add_items + total_items + total_catalogue1 > 40
+```
+Calculé avec `catalogue1` (prix abonnés × qty) depuis `subscription_items` + `subscription_add_items` + `meals_selected`.
+
+### Cutoffs abonnement
+
+Une commande abonnement génère **deux entrées** dans `subscription_generation_status` pour une même `delivery_date` :
+
+| `type` | Contenu |
+|---|---|
+| `'long'` | Plats (meals) |
+| `'short'` | Produits du shop |
+
+⚠️ Ne pas agréger sans filtrer sur `type` sous peine de doublon-compter une livraison.
+
+### Frais de port
+
+**Identifier les frais de port**
+```sql
+eorderd.artid = 'COSTPORT'
+```
+
+⚠️ Toujours vérifier `SUM(price) > 0` pour confirmer qu'ils sont effectivement facturés (ils peuvent être gratuits).
+
+---
+
+## Patterns SQL
+
+### Meals vs Produits simples {#pattern-meals-vs-simples}
+
+**Quand** : distinguer un meal kit (à décomposer) d'un produit simple
+
+```sql
+WHERE product_id LIKE '%-%'      -- meal kit (2 portions, 3 portions, etc.)
+WHERE product_id NOT LIKE '%-%'  -- produit simple (1 ligne picking)
+```
+
+### ID plat — type & portion {#pattern-plat-id}
+
+**Quand** : extraire le type de plat et le nombre de portions
+
+```sql
+-- Type de plat (1ère lettre de artid)
+CASE LEFT(d.artid, 1)
+    WHEN 'L' THEN 'Légume'
+    WHEN 'V' THEN 'Viande'
+    WHEN 'P' THEN 'Poisson'
+    ELSE 'Autre'
+END AS plat_type
+
+-- Nombre de portions (chiffre avant le P final : V810-2P → 2)
+-- ⚠️ RTRIM obligatoire — artid est char(n)
+SUBSTRING(RTRIM(d.artid) FROM '-(\d+)P$') || ' portion(s)' AS portion
+
+-- Filtrer les plats portion (⚠️ RTRIM obligatoire)
+AND RTRIM(d.artid) LIKE '%-%P'
+```
+
+### Tags produit {#pattern-tags}
+
+**Quand** : récupérer les tags (features) associés à un produit
+
+```sql
+SELECT f.name1
+FROM efarmz_db.art
+LEFT JOIN efarmz_db.artfeature af ON af.artid = art.artid
+LEFT JOIN efarmz_db.feature f     ON f.featureid = af.featureid
+WHERE art.artid = 'V810'
+
+-- Pour les plats : supprimer la portion de l'artid avant le join
+LEFT JOIN efarmz_db.artfeature af
+    ON af.artid = REGEXP_REPLACE(RTRIM(d.artid), '-\d+P$', '')
+```
+
+### Décomposition ARTPART {#pattern-artpart}
+
+**Quand** : lister les ingrédients d'un meal kit
+
+**Dépend de** : Conventions globales / RTRIM, Conventions globales / deduplication
+
+```sql
+WITH ranked_artpart AS (
+    SELECT ap.ARTID AS meal_id, ap.ARTPARTID AS ingredient_id,
+           art.NAME1, art.UNIT, art.a_zone, ap.QTY, ap.ORDER,
+           ROW_NUMBER() OVER (
+               PARTITION BY ap.ARTID, ap.ORDER
+               ORDER BY ap.S_MODDATE DESC
+           ) AS rn
+    FROM efarmz_db.ARTPART ap
+    JOIN efarmz_db.ART art ON art.ARTID = ap.ARTPARTID
+    WHERE ap.ARTID IN (...)
+)
+SELECT * FROM ranked_artpart WHERE rn = 1
+```
+
+⚠️ Toujours utiliser `WHERE rn = 1` pour éviter les doublons en cas de mise à jour.
+
+### Alignement N-1 même jour de semaine {#pattern-ly-align}
+
+**Quand** : calculer la date homologue de l'année précédente (ou N-2), même jour de la semaine
+
+```sql
+-- N-1
+(
+    (delivery_date - interval '1 year')::date
+    + (((extract(isodow from delivery_date)::int
+         - extract(isodow from (delivery_date - interval '1 year'))::int
+         + 10) % 7) - 3) * interval '1 day'
+)::date AS delivery_date_ly
+
+-- N-2 (même formule, 2 ans en arrière)
+(
+    (delivery_date - interval '2 year')::date
+    + (((extract(isodow from delivery_date)::int
+         - extract(isodow from (delivery_date - interval '2 year'))::int
+         + 10) % 7) - 3) * interval '1 day'
+)::date AS delivery_date_2y
+```
+
+### Semaine ISO pour les meals {#pattern-iso-week}
+
+**Quand** : aligner les sélections de meals avec la semaine de livraison
+
+```sql
+date_trunc('week', ms.week) = date_trunc('week', s.next_delivery_date)
+```
+
+### Zones picking {#pattern-zones}
+
+**Quand** : compter les lignes par zone (SEC, FRAIS, UFRAIS)
+
+```sql
+COUNT(*) FILTER (WHERE a_zone = 'SEC')    AS sec_lines,
+COUNT(*) FILTER (WHERE a_zone = 'FRAIS')  AS frais_lines,
+COUNT(*) FILTER (WHERE a_zone = 'UFRAIS') AS ufrais_lines
+```
+
+### Génération dates ouvrées {#pattern-workdays}
+
+**Quand** : générer une liste de dates de livraison futures (lun-ven)
+
+```sql
+SELECT gs::date AS delivery_date
+FROM generate_series(
+    (current_date + interval '1 day')::date,
+    (current_date + interval '13 days')::date,
+    interval '1 day'
+) gs
+WHERE extract(isodow from gs) BETWEEN 1 AND 5
+```
+
+### Commandes 100% shop {#pattern-shop-only}
+
+**Quand** : identifier les commandes contenant exclusivement des produits shop (pas de meals)
+
+```sql
+WHERE NOT EXISTS (
+    SELECT 1
+    FROM jsonb_array_elements(items::jsonb) AS item
+    WHERE item->>'a_prodtype' NOT IN ('PRODUIT', 'PANIER', 'ADMIN')
+)
+```
+
+### Rang des commandes par client {#pattern-order-rank}
+
+**Quand** : numéroter les commandes d'un client (1ère, 2e, 3e…)
+
+**Dépend de** : Conventions globales / tie-breaker
+
+```sql
+ROW_NUMBER() OVER (
+    PARTITION BY h.c_uuid
+    ORDER BY h.dlvdate ASC, h.w_orderid ASC
+) AS order_rank
+```
+
+### Timing de sélection des meals {#pattern-meal-timing}
+
+**Quand** : mesurer l'avance avec laquelle un abonné sélectionne ses meals
+
+```sql
+CASE
+    WHEN date_trunc('week', selection_date) = date_trunc('week', dlvdate)
+        THEN 'Semaine même'
+    WHEN date_trunc('week', selection_date) = date_trunc('week', dlvdate - interval '1 week')
+        THEN '1 semaine en avance'
+    WHEN date_trunc('week', selection_date) = date_trunc('week', dlvdate - interval '2 weeks')
+        THEN '2 semaines en avance'
+    WHEN date_trunc('week', selection_date) = date_trunc('week', dlvdate - interval '3 weeks')
+        THEN '3 semaines en avance'
+    ELSE '+ de 3 semaines en avance'
+END AS timing
+```
+
+⚠️ Utiliser `MIN(ms.created_at)` pour la première sélection faite par le client.
+
+### Pourcentage avec total global {#pattern-pct-window}
+
+**Quand** : calculer un % par rapport au total de tous les groupes
+
+**Dépend de** : Conventions globales / ::numeric avant ROUND
+
+```sql
+ROUND(
+    COUNT(*)::numeric
+    / NULLIF(SUM(COUNT(*)) OVER ()::numeric, 0) * 100
+, 2) AS pct
+```
+
+### Ventes mois précédent {#pattern-last-month}
+
+**Quand** : agréger les quantités vendues au mois précédent (pour rotation, top produits, etc.)
+
+**Dépend de** : Règles métier / Filtres / Commandes valides
+
+```sql
+WITH last_month_sales AS (
+    SELECT d.artid, SUM(d.qty) AS qty
+    FROM efarmz_db.eorderd d
+    INNER JOIN efarmz_db.eorderh h ON h.w_orderid = d.w_orderid
+    WHERE h.status NOT IN (31, 32)
+      AND date_trunc('month', h.dlvdate) = date_trunc('month', CURRENT_DATE - interval '1 month')
+    GROUP BY d.artid
+)
+-- Utiliser cette CTE dans la requête principale
+```
+
+### Forecast commandes par date {#pattern-forecast}
+
+**Quand** : projeter le nombre de commandes attendues sur les 2 prochaines semaines ouvrées (abonnements + one-shot)
+
+**Dépend de** : Patterns SQL / Génération dates ouvrées, Patterns SQL / Alignement N-1 même jour de semaine, Règles métier / Validité abonnement, Règles métier / Seuil panier picking
+
+```sql
+WITH base_dates AS (
+    SELECT gs::date AS delivery_date
+    FROM generate_series(
+        (current_date + interval '1 day')::date,
+        (date_trunc('week', current_date)::date + interval '1 week' + interval '13 days')::date,
+        interval '1 day'
+    ) gs
+    WHERE extract(isodow from gs) BETWEEN 1 AND 5
+),
+items AS (
+    SELECT i.subscription_id, SUM(i.quantity * a.finalprice) AS total_items
+    FROM efarmz_db.subscription_items i
+    JOIN efarmz_db.art a ON a.artid = i.product_id
+    GROUP BY i.subscription_id
+),
+add_items AS (
+    SELECT ai.subscription_id, ai.delivery_date, SUM(ai.quantity * a.finalprice) AS total_add_items
+    FROM efarmz_db.subscription_add_items ai
+    JOIN efarmz_db.art a ON a.artid = ai.product_id
+    GROUP BY ai.subscription_id, ai.delivery_date
+),
+meals AS (
+    SELECT ms.subscription_id,
+           date_trunc('week', ms.week) AS week_start,
+           SUM(a.catalogue1) AS total_catalogue1
+    FROM efarmz_db.meals_selected ms
+    JOIN efarmz_db.art a ON a.artid = ms.product_id
+    GROUP BY ms.subscription_id, date_trunc('week', ms.week)
+),
+-- Abonnements actifs avec panier viable (voir Règles métier / Validité abonnement + Seuil panier picking)
+next_subscriptions AS (
+    SELECT s.id, s.next_delivery_date,
+           COALESCE(i.total_items, 0)      AS total_items,
+           COALESCE(ai.total_add_items, 0) AS total_add_items,
+           COALESCE(m.total_catalogue1, 0) AS total_catalogue1
+    FROM efarmz_db.subscriptions s
+    LEFT JOIN items i ON i.subscription_id = s.id
+    LEFT JOIN add_items ai ON ai.subscription_id = s.id AND ai.delivery_date = s.next_delivery_date
+    LEFT JOIN meals m ON m.subscription_id = s.id AND m.week_start = date_trunc('week', s.next_delivery_date)
+    WHERE s.status = 1 AND s.deleted_at IS NULL
+      AND s.next_delivery_date::date > (CURRENT_DATE + interval '1 day')
+      AND NOT EXISTS (SELECT 1 FROM efarmz_db.subscription_off so
+                      WHERE so.subscription_id = s.id AND so.start_date = s.next_delivery_date)
+),
+forecast_subscriptions AS (
+    SELECT DATE(next_delivery_date) AS delivery_date, COUNT(DISTINCT id) AS subscription_forecast
+    FROM next_subscriptions
+    WHERE total_add_items + total_items + total_catalogue1 > 40
+      AND extract(isodow from next_delivery_date) NOT IN (6, 7)
+    GROUP BY DATE(next_delivery_date)
+),
+forecast_by_date AS (
+    SELECT b.delivery_date, COALESCE(fs.subscription_forecast, 0) AS subscription_forecast
+    FROM base_dates b
+    LEFT JOIN forecast_subscriptions fs USING (delivery_date)
+),
+-- Dates homologues N-1 et N-2 (voir #pattern-ly-align)
+aligned AS (
+    SELECT f.delivery_date, f.subscription_forecast,
+           ((f.delivery_date - interval '1 year')::date
+            + (((extract(isodow from f.delivery_date)::int
+                 - extract(isodow from (f.delivery_date - interval '1 year'))::int + 10) % 7) - 3
+               ) * interval '1 day')::date AS delivery_date_ly,
+           ((f.delivery_date - interval '2 year')::date
+            + (((extract(isodow from f.delivery_date)::int
+                 - extract(isodow from (f.delivery_date - interval '2 year'))::int + 10) % 7) - 3
+               ) * interval '1 day')::date AS delivery_date_2y
+    FROM forecast_by_date f
+),
+-- One-shot N-1 : seulement les commandes passées avec un lead time ≤ au lead time restant actuel
+forecast_oneshot_ly AS (
+    SELECT a.delivery_date_ly, COUNT(DISTINCT h.w_orderid) AS count
+    FROM efarmz_db.eorderh h
+    INNER JOIN aligned a ON DATE(a.delivery_date_ly) = DATE(h.dlvdate)
+    WHERE h.status NOT IN (31, 32) AND h.ordertype = 1
+      AND h.s_credate::timestamp >= h.dlvdate::timestamp - (DATE(a.delivery_date)::timestamp - now())
+    GROUP BY a.delivery_date_ly
+),
+hist_oneshot AS (
+    SELECT dlvdate::date AS delivery_date, COUNT(DISTINCT w_orderid) AS oneshot
+    FROM efarmz_db.eorderh WHERE status NOT IN (31, 32) AND ordertype = 1
+    GROUP BY dlvdate::date
+),
+hist_subscription AS (
+    SELECT dlvdate::date AS delivery_date, COUNT(DISTINCT w_orderid) AS subscription
+    FROM efarmz_db.eorderh WHERE status NOT IN (31, 32) AND ordertype = 2
+    GROUP BY dlvdate::date
+)
+SELECT
+    TO_CHAR(a.delivery_date, 'YYYY/MM/DD')                                           AS delivery_date,
+    COALESCE(h0.oneshot, 0)                                                          AS oneshot,
+    COALESCE(forecast_oneshot_ly.count, 0)                                           AS oneshot_forecast,
+    COALESCE(s0.subscription, 0)                                                     AS subscription,
+    CASE WHEN a.subscription_forecast > 0
+         THEN a.subscription_forecast - COALESCE(s0.subscription, 0) ELSE 0 END     AS subscription_forecast,
+    COALESCE(h0.oneshot, 0) + COALESCE(forecast_oneshot_ly.count, 0)
+        + COALESCE(s0.subscription, 0)
+        + CASE WHEN a.subscription_forecast > 0
+               THEN a.subscription_forecast - COALESCE(s0.subscription, 0) ELSE 0 END AS total_forecast,
+    TO_CHAR(a.delivery_date_ly, 'YYYY/MM/DD')                                        AS delivery_date_ly,
+    COALESCE(h1.oneshot + s1.subscription, 0)                                        AS orders_ly,
+    TO_CHAR(a.delivery_date_2y, 'YYYY/MM/DD')                                        AS delivery_date_2y,
+    COALESCE(h2.oneshot + s2.subscription, 0)                                        AS orders_2y
+FROM aligned a
+LEFT JOIN hist_oneshot h0 ON h0.delivery_date = a.delivery_date
+LEFT JOIN hist_oneshot h1 ON h1.delivery_date = a.delivery_date_ly
+LEFT JOIN hist_oneshot h2 ON h2.delivery_date = a.delivery_date_2y
+LEFT JOIN hist_subscription s0 ON s0.delivery_date = a.delivery_date
+LEFT JOIN hist_subscription s1 ON s1.delivery_date = a.delivery_date_ly
+LEFT JOIN hist_subscription s2 ON s2.delivery_date = a.delivery_date_2y
+LEFT JOIN forecast_oneshot_ly ON forecast_oneshot_ly.delivery_date_ly = a.delivery_date_ly
+ORDER BY a.delivery_date;
+```
+
+⚠️ Le forecast one-shot (`forecast_oneshot_ly`) filtre les commandes N-1 par lead time restant : `s_credate >= dlvdate - (delivery_date - now())`. Cela évite de compter des commandes N-1 passées très tôt que les clients n'auraient pas encore passées côté J actuel — c'est un prorata temporis, pas un simple comptage brut N-1.
+
+⚠️ `subscription_forecast` représente le *delta* (abonnements prévisionnels moins ceux déjà confirmés dans `eorderh`). Il peut être 0 si tous les abonnements ont déjà généré une commande.
+
+---
+
+## Glossaire
+
+| Terme | Alias | Contexte | Notes |
+|---|---|---|---|
+| `artid` | `product_id` | Selon le contexte d'écriture — synonymes dans les queries | Type `char(n)`, toujours `RTRIM` pour patterns de fin |
+| `c_uuid` | `users.id` (jointure via `::bigint`) | `eorderh.c_uuid` ← → `users.id` | Identifiant client unifié |
+| `catalogue1` | — | Prix **abonnés** | Vs `finalprice` (prix non-abonnés) |
+| `finalprice` | — | Prix **non-abonnés** | Vs `catalogue1` (prix abonnés) |
+| Zone picking | `a_zone` | Localisation physique en entrepôt | Valeurs : `SEC`, `FRAIS`, `UFRAIS` |
+| Type produit | `a_prodtype` | Classification en catalogue | Valeurs : `PRODUIT`, `PANIER`, `ADMIN`, `PLAT` |
+| Préfixes artid plats | — | Codes de la 1ère lettre | `L` = Légume, `V` = Viande, `P` = Poisson |
+| Statuts commande | `status` | Filtre standard | `31` = annulé, `32` = remboursé (à exclure) |
+| Statut abonnement | `subscriptions.status` | Activité | `1` = actif |
+
+---