---

name: orders description: >- Orders domain expert — order lifecycle, list v2 server-filters, edit-items RPCs, void/refund, realtime. Cross-app business logic (POS writes + BO management); distinct from pos-specialist (POS UI surface) and backoffice-specialist (BO UI surface). Use this skill whenever the task mentions order(s) / commande(s), statut de commande, void / annulation, refund / remboursement, pending_payment, held order / commande en attente, ardoise, complete_order_with_payment, pay_existing_order, fire_counter_order, create_tablet_order, order items / lignes de commande, totaux de commande, orders realtime — or touches apps/backoffice features/orders, POS order-history, or any supabase migration/test with order in the name. Invoke it BEFORE editing any order lifecycle RPC or status transition, even a small one. pathPatterns:

• 'apps/backoffice/src/features/orders/**'
• 'apps/backoffice/src/pages/**/Order*'
• 'apps/pos/src/features/order-history/**'
• 'supabase/migrations/order.sql'
• 'supabase/tests/order.test.sql'
• 'supabase/tests/complete_order_v10_display.test.sql' promptSignals: phrases:
  • 'order list'
  • 'order status'
  • 'edit order item'
  • 'void order'
  • 'order refund'
  • 'pending_payment'
  • 'get_orders_list'
  • 'order totals'
  • 'orders realtime'
  • 'complete_order'
  • 'add_order_item'
  • 'remove_order_item'

---

Orders — The Breakery ERP

Expert on order business logic across POS (writes) and Backoffice (management). Two use-cases:

1. Guide changes to the order lifecycle — new status transitions, edit-items flows, new filters.
2. Audit order integrity — status guards, idempotency, realtime consistency, totals recalc.

CLAUDE.md est la source de vérité pour les patterns projet (RPC versioning, REVOKE pairs, PIN header, idempotency). Ce skill ajoute uniquement la surface map ordres, les noms réels vérifiés, et les checklists préventives spécifiques.

Anti-overlap boundary : ce skill couvre la logique métier ordres (RPCs, tables, enums, guards). pos-specialist couvre l'UI POS (ProductGrid, CartSidebar, …). backoffice-specialist couvre l'UI BO (OrdersListPage, filtres, ExportButtons). Les trois coexistent sans collision.

---

Mental model — Order lifecycle

POS create                          BO management
──────────                          ─────────────
complete_order_with_payment         get_orders_list_v2
 ↓ status: paid                      ↓ cursor-paginé, 11 filtres JSONB
pay_existing_order
 ↓ draft → pending_payment → paid   add/update/remove_order_item_v1
create_tablet_order                  ↓ draft | pending_payment uniquement
 ↓ status: draft                     ↓ _recalc_order_totals atomique
create_b2b_order
 ↓ status: b2b_pending              void_order_rpc
                                     ↓ status: voided (manager PIN)
refund_order_rpc
 ↓ INSERT refunds row               useOrdersRealtime
 ↓ PIN header x-manager-pin          ↓ postgres_changes INSERT+UPDATE
 ↓ idempotency header                ↓ StrictMode-safe via useId

Les numéros de version RPC sont volontairement omis dans ce skill (versions omises — vérifier CLAUDE.md / supabase/migrations/) — ils bumpent presque chaque session ; les mentions d'historique (« Drop v9 », noms de migration) sont conservées.

order_status enum — valeurs réelles (vérifiées migrations S5/S24 + corrective S33 _023)

draft | paid | voided | pending_payment | completed | b2b_pending

PAS de valeur open — le corrective 20260618000023 a corrigé exactement ce bug dans les 3 RPCs edit-items (était IN ('draft', 'open'), doit être IN ('draft', 'pending_payment')). Ne jamais introduire 'open'.

order_type enum (vérifié migration S24)

dine_in | take_out | delivery | b2b | tablet

Schema reality (noms de colonnes réels — diffèrent de l'intuition)

| Table | Colonne réelle | Pas | |-------|---------------|-----| | orders | total | total_amount | | orders | served_by | created_by | | order_items | name_snapshot | product_name | | order_items | modifiers (JSONB array) | modifiers_json | | refunds | total | amount | | customers | name | full_name |

orders.session_id est NULL autorisé pour order_type = 'b2b' et created_via = 'tablet' (CHECK relaxed S24 _007 + S25 _014).

---

RPCs — noms vérifiés dans supabase/migrations/

Write RPCs (JAMAIS d'INSERT direct — passe toujours par RPC)

| RPC | Fichier migration | Notes | |-----|------------------|-------| | complete_order_with_payment | 20260530190828 | Double déduction display_stock + current_stock pour is_display_item. Drop v9 in same migration. | | pay_existing_order | 20260507000005 + bumps | draft → pending_payment → paid | | create_tablet_order(p_client_uuid UUID) | 20260602000011 | p_client_uuid REQUIRED, idempotency via tablet_order_idempotency_keys. | | refund_order_rpc | 20260517000014 | PIN via header x-manager-pin. p_idempotency_key propagé par EF refund-order v7. | | void_order_rpc | 20260512000009 | Manager PIN gated (pos.sale.void). Émet JE-VOID + stock sale_void + reverse loyalty. | | create_b2b_order | 20260601000022 | Gate validate_b2b_credit_limit_v1. Status b2b_pending. | | mark_item_served | (S5) | KDS/tablet — marque l'item servi. |

List & edit RPCs (S32/S33)

get_orders_list_v2(p_start TEXT, p_end TEXT, p_filters JSONB, p_limit INT, p_cursor TIMESTAMPTZ) (migration 20260618000011, drops v1 in same file)

• Gate: orders.read
• 11 filtres JSONB : status, order_type, customer_id, served_by, total_min, total_max, customer_type, payment_method, terminal_id, hour (0-23 Asia/Makassar), refund_status (none|partial|full)
• terminal_id via JOIN pos_sessions → requiert que l'ordre ait un session_id
• Computed output : refund_status, has_modifiers, payment_method_primary (ou 'mixed'), items_count, customer_name, served_by_name, terminal_id

Edit-items (seulement sur draft | pending_payment) :

| RPC | Signature | Action clé | |-----|-----------|-----------| | add_order_item_v1 | (p_order_id, p_product_id, p_qty, p_modifiers, p_idempotency_key) | name_snapshot + retail_price (pas .price) | | update_order_item_qty_v1 | (p_order_item_id, p_qty, p_idempotency_key) | qty > 0 (sinon utiliser remove) | | remove_order_item_v1 | (p_order_item_id, p_idempotency_key) | DELETE + recalc |

Les 3 appellent _recalc_order_totals(order_id) (helper interne, non callable directement). Idempotency via table dédiée order_edit_idempotency_keys (colonnes: key UUID PK, action TEXT, order_id UUID, result JSONB). Chaque RPC a sa propre action string : 'add', 'update_qty', 'remove'.

Orchestrateur BO useEditOrderItems : séquence removes → updates → adds pour éviter les conflits de totaux.

Permissions (vérifiées migration 20260618000021)

orders.read       — MANAGER / ADMIN / SUPER_ADMIN (S31 _010)
orders.edit_open  — MANAGER / ADMIN / SUPER_ADMIN (S33 _021)
orders.void       — MANAGER / ADMIN / SUPER_ADMIN (S33 _021)

---

Critical patterns (ordres-spécifiques)

1. Jamais d'INSERT direct dans orders — toujours via RPC. Les RPCs gèrent atomiquement : JE triggers, loyalty, promotions, display_stock double-déduction, table_state.
2. Status guard sur edit-items — ('draft', 'pending_payment') uniquement. Lever P0002 sinon. Ne pas ajouter 'open' (valeur inexistante dans l'enum).
3. products.retail_price (pas .price) — vérifié dans le corrective _023. Utiliser retail_price pour unit_price dans les edit-items RPCs.
4. Idempotency keys propres par RPC — ne pas partager une même p_idempotency_key entre deux appels RPC distincts dans useEditOrderItems. Générer un UUID par call.
5. PIN en header — refund_order_rpc et void_order_rpc lisent le PIN via header x-manager-pin, jamais dans le body JSON (loggé par PostgREST/pgaudit).
6. Realtime StrictMode-safe — useOrdersRealtime utilise useId() pour nommer le channel ; pas de channel name statique (collisions StrictMode double-mount).
7. orders.session_id nullable — NULL autorisé pour b2b ET tablet via 2 CHECK distincts. Ne jamais resserrer à NOT NULL global.
8. display_stock double-déduction — complete_order_with_payment (comportement introduit en v10) décrémente à la fois display_stock.quantity ET products.current_stock pour les is_display_item=true. Non-display : current_stock seulement (comportement v9 inchangé).

---

Audit checklist

• [ ] Status transition valide — seuls les états de l'enum réel sont utilisés. Grep 'open' dans les nouvelles migrations ordres.
• [ ] Edit-items guard — les 3 RPCs vérifient status IN ('draft', 'pending_payment') (pas 'open').
• [ ] Totals cohérents — après chaque edit-item, orders.total = SUM(order_items.line_total) + tax_amount - discount_amount. Vérifiable via _recalc_order_totals.
• [ ] Idempotency replay — même p_idempotency_key + même action retourne le result JSONB stocké sans mutation.
• [ ] order_edit_idempotency_keys isolé — pas de GRANT EXECUTE exposant cette table à anon ou authenticated hors des RPCs SECURITY DEFINER.
• [ ] Refund integrity — SUM(refunds.total) <= orders.total pour un même order_id. refund_status computed par get_orders_list_v2 en découle.
• [ ] REVOKE pair complet — chaque nouveau RPC ordres a les 3 lignes (PUBLIC + anon + ALTER DEFAULT PRIVILEGES). Vérifier 20260618000012/016/018/020.
• [ ] Types regen — toute migration ordres touchant la signature d'un RPC doit déclencher generate_typescript_types → packages/supabase/src/types.generated.ts.

---

Sources de vérité (pointeurs)

Migrations (historique chronologique)
  supabase/migrations/20260503000008_init_complete_order_rpc.sql        — v1 initial
  supabase/migrations/20260530190828_bump_complete_order_v10.sql        — v10 display-stock
  supabase/migrations/20260617000013_create_get_orders_list_v1_rpc.sql  — list v1 (dropped by v2)
  supabase/migrations/20260618000011_bump_get_orders_list_v2_server_filters.sql
  supabase/migrations/20260618000013..020_*.sql                         — edit-items RPCs + REVOKE
  supabase/migrations/20260618000021_seed_orders_edit_open_perm.sql
  supabase/migrations/20260618000023_fix_edit_items_rpc_status_enum.sql — corrective 'open'→'pending_payment'

Tests (vérité comportementale)
  supabase/tests/orders_read_perm.test.sql           — S31 perm gate
  supabase/tests/orders_list_v1.test.sql             — S32 (remplacé par v2)
  supabase/tests/orders_list_v2.test.sql             — S33, 10/10 PASS
  supabase/tests/order_edit_items.test.sql           — S33, 12/12 PASS
  supabase/tests/complete_order_v10_display.test.sql — display-stock double-déduction

Docs / workplan
  CLAUDE.md — §S32 (get_orders_list_v1, schema discoveries) + §S33 (v2 server-filters, edit-items, realtime, void)
  docs/workplan/specs/2026-05-29-session-33-spec.md
  docs/workplan/plans/2026-05-29-session-33-plan.md

---

Verification before claiming complete

# Type & lint (cheap, run first)
pnpm typecheck

# pgTAP via MCP execute_sql (BEGIN/ROLLBACK envelope)
# Fichiers : orders_list_v2.test.sql, order_edit_items.test.sql, complete_order_v10_display.test.sql

# BO smoke
pnpm --filter @breakery/app-backoffice test orders

# POS smoke
pnpm --filter @breakery/app-pos test order

Baseline : ~24 BO échecs env-gated (VITE_SUPABASE_URL Required) ≠ régression (DEV-S25-2.A-02).

---

When to escalate

• Ajouter une valeur à order_status ou order_type → confirm business intent, enum ADD VALUE doit vivre dans sa propre TX, puis vérifier tous les guards existants (status IN (…)).
• Modifier la signature de complete_order_with_payment → bump obligatoire (RPC versioning monotone), DROP de l'ancienne version dans la même migration. Vérifier tous les callers POS/BO.
• Relax ou tighten la contrainte orders.session_id → peut casser les flows tablet ou B2B (cf. S25 corrective _014).
• Nouveau filtre get_orders_list_v2 impliquant un JOIN sur une table sans index → profiler d'abord.
• Changement du mécanisme PIN (ex. void-order EF sweep POST-S30 déféré) → coordonner avec security-auth skill.