feat(stripe-admin-override): bouton « Marquer KYC validé » comme chemin de secours webhook

Quand le webhook Stripe `account.updated` ne ramène pas le statut à `ready`
(sandbox flaky, misconfig Connect, signature mismatch, network blip), l'admin
restait coincé sur « En attente de KYC » à perpétuité même après avoir validé
le KYC IRL avec le restaurateur. Seule solution avant ce commit : patcher la
DB à la main via `convex run` — pas utilisable par Alex en prod.

Surface :
  - Backend : nouveau `kbAdminMutation` `forceStripeStatusOverride` dans
    `lib/stripe/account.ts`, args `{tenantId, status: "ready"|"disabled"|"pending"}`.
    Refuse `INVALID_STATE` si pas de `stripeAccountId` (overrider un compte
    inexistant = nonsense). Auto-audité par `kbAdminMutation` (action
    `stripe.account.forceStatusOverride`).
  - Frontend : bloc « Override admin » sur `/parametres/stripe`, visible
    seulement quand un compte existe ET `stripeStatus !== "ready"`. Couleur
    warning amber (signal d'override), confirmation native `window.confirm`
    avant le flip. Toast succès / erreur.

Tests : +6 cases (visible selon status × disabled/enabled selon
isOverriding × callback wirée). 28/28 green.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: alexpmichelet

apps/admin/src/app/(app)/t/[tenantId]/parametres/stripe/page.tsx

@@ -59,7 +59,7 @@
  */
 
 import { useState } from "react";
-import { useAction } from "convex/react";
+import { useAction, useMutation } from "convex/react";
 import { toast } from "sonner";
 
 import { api } from "@packages/backend/convex/_generated/api";
@@ -93,9 +93,18 @@ export default function StripeSettingsPage() {
     api.lib.stripe.account.createStripeAccountLink,
   );
 
+  // Backup admin override (chemin de secours quand le webhook
+  // account.updated ne ramène pas le statut à ready). Backend rejette si
+  // pas de stripeAccountId + audit-log chaque flip. Root-only via
+  // kbAdminMutation.
+  const forceStripeStatusOverride = useMutation(
+    api.lib.stripe.account.forceStripeStatusOverride,
+  );
+
   const [accountLink, setAccountLink] = useState<string | null>(null);
   const [isGenerating, setIsGenerating] = useState(false);
   const [genError, setGenError] = useState<string | null>(null);
+  const [isOverriding, setIsOverriding] = useState(false);
   // Email du restaurant — requis par Stripe `/v1/accounts` (champ `email`).
   // Saisi par l'opérateur ici parce qu'aucun « prospect » n'existe pour un
   // tenant créé hors wizard (a posteriori).
@@ -152,6 +161,22 @@ export default function StripeSettingsPage() {
     }
   };
 
+  const handleForceReady = async (): Promise<void> => {
+    if (isOverriding) return;
+    if (!window.confirm("Confirmer l'override : marquer le KYC comme validé ?"))
+      return;
+    setIsOverriding(true);
+    try {
+      await forceStripeStatusOverride({ tenantId, status: "ready" });
+      toast.success("Statut Stripe Connect forcé à « Prêt »");
+    } catch (error) {
+      const message = getConvexErrorMessage(error);
+      toast.error("Impossible de forcer le statut", { description: message });
+    } finally {
+      setIsOverriding(false);
+    }
+  };
+
   const handleCopy = async (url: string): Promise<void> => {
     try {
       if (
@@ -180,6 +205,8 @@ export default function StripeSettingsPage() {
       genError={genError}
       onGenerate={handleGenerate}
       onCopy={handleCopy}
+      onForceReady={handleForceReady}
+      isOverriding={isOverriding}
     />
   );
 }

apps/admin/src/app/(app)/t/[tenantId]/parametres/stripe/stripe-settings-view.test.tsx

@@ -205,6 +205,8 @@ function defaultProps(
     genError: null,
     onGenerate: vi.fn(),
     onCopy: vi.fn(),
+    onForceReady: vi.fn(),
+    isOverriding: false,
     ...overrides,
   };
 }
@@ -409,6 +411,86 @@ describe("StripeSettingsView — email du restaurant (a posteriori)", () => {
   });
 });
 
+describe("StripeSettingsView — admin override (backup webhook)", () => {
+  it("no account yet → override block is HIDDEN (override sans compte = nonsense)", () => {
+    const tree = serialize(StripeSettingsView(defaultProps()));
+    expect(findBySlot(tree, "stripe-settings-override-block")).toBeNull();
+    expect(findBySlot(tree, "stripe-settings-force-ready")).toBeNull();
+  });
+
+  it("status `ready` → override block is HIDDEN (déjà ready, no-op)", () => {
+    const tree = serialize(
+      StripeSettingsView(
+        defaultProps({
+          stripeAccountId: ACCOUNT_ID,
+          stripeStatus: "ready",
+        }),
+      ),
+    );
+    expect(findBySlot(tree, "stripe-settings-override-block")).toBeNull();
+  });
+
+  it("status `pending` → override block is VISIBLE (chemin de secours)", () => {
+    const tree = serialize(
+      StripeSettingsView(
+        defaultProps({
+          stripeAccountId: ACCOUNT_ID,
+          stripeStatus: "pending",
+        }),
+      ),
+    );
+    const block = findBySlot(tree, "stripe-settings-override-block");
+    expect(block).not.toBeNull();
+    expect(allText(block)).toMatch(/Override admin/i);
+  });
+
+  it("status `disabled` → override block is VISIBLE (admin peut ré-activer)", () => {
+    const tree = serialize(
+      StripeSettingsView(
+        defaultProps({
+          stripeAccountId: ACCOUNT_ID,
+          stripeStatus: "disabled",
+        }),
+      ),
+    );
+    expect(findBySlot(tree, "stripe-settings-override-block")).not.toBeNull();
+  });
+
+  it("clicking « Marquer comme … » calls `onForceReady`", () => {
+    const onForceReady = vi.fn();
+    const tree = serialize(
+      StripeSettingsView(
+        defaultProps({
+          stripeAccountId: ACCOUNT_ID,
+          stripeStatus: "pending",
+          onForceReady,
+        }),
+      ),
+    );
+    const btn = findBySlot(tree, "stripe-settings-force-ready") as {
+      props: { onClick?: () => void };
+    } | null;
+    btn?.props.onClick?.();
+    expect(onForceReady).toHaveBeenCalledTimes(1);
+  });
+
+  it("override button is disabled while `isOverriding` is true", () => {
+    const tree = serialize(
+      StripeSettingsView(
+        defaultProps({
+          stripeAccountId: ACCOUNT_ID,
+          stripeStatus: "pending",
+          isOverriding: true,
+        }),
+      ),
+    );
+    const btn = findBySlot(tree, "stripe-settings-force-ready") as {
+      props: { disabled?: boolean };
+    } | null;
+    expect(btn?.props.disabled).toBe(true);
+  });
+});
+
 describe("StripeSettingsView — generated URL display", () => {
   it("when `accountLink` is set, renders the URL in a read-only input", () => {
     const tree = serialize(

apps/admin/src/app/(app)/t/[tenantId]/parametres/stripe/stripe-settings-view.tsx

@@ -129,6 +129,20 @@ export type StripeSettingsViewProps = {
    * Threaded as a prop so the view stays purely presentational.
    */
   onCopy: (url: string) => void;
+  /**
+   * Override manuel admin du statut Stripe — chemin de secours quand le
+   * webhook `account.updated` n'arrive pas (sandbox flaky, signature
+   * mismatch, misconfig Connect). L'admin a complété le KYC IRL avec le
+   * resto mais le badge reste « En attente » → un clic ici flippe le
+   * status à `ready`. Audit-logged côté backend.
+   *
+   * Threaded comme prop pour garder la view purement présentationnelle.
+   * Affiché uniquement quand un compte existe (`hasAccount`) ET que le
+   * status n'est pas déjà `ready` (sinon overrider à ready est un no-op).
+   */
+  onForceReady: () => void;
+  /** Disable le bouton override pendant l'in-flight mutation. */
+  isOverriding: boolean;
 };
 
 // ---------------------------------------------------------------------------
@@ -205,6 +219,8 @@ export function StripeSettingsView(
     genError,
     onGenerate,
     onCopy,
+    onForceReady,
+    isOverriding,
   } = props;
 
   const status = statusCopy(stripeAccountId, stripeStatus);
@@ -216,6 +232,9 @@ export function StripeSettingsView(
   // un compte existant — pas de re-passage par `/v1/accounts`, donc
   // l'email du tenant n'est pas relu.
   const disableGenerate = isGenerating || (!hasAccount && !isEmailValid);
+  // L'override admin n'a de sens que si un compte existe ET que le status
+  // n'est pas déjà `ready` (sinon flipper à ready est un no-op).
+  const canForceReady = hasAccount && stripeStatus !== "ready";
 
   return (
     <div
@@ -321,6 +340,38 @@ export function StripeSettingsView(
         </div>
       )}
 
+      {/* Admin override — chemin de secours si le webhook account.updated
+          n'arrive pas après un KYC validé IRL (Stripe sandbox flaky,
+          misconfig Connect, signature mismatch). Audit-logged côté backend.
+          Affiché seulement quand un compte existe ET status !== "ready". */}
+      {canForceReady ? (
+        <div
+          data-slot="stripe-settings-override-block"
+          className="rounded-md border border-amber-300/60 bg-amber-50 p-3"
+        >
+          <p className="mb-2 text-sm font-medium text-amber-900">
+            Override admin — marquer KYC validé manuellement
+          </p>
+          <p className="mb-3 text-xs text-amber-800">
+            À utiliser si le KYC a été validé avec le gérant mais que le statut
+            reste bloqué (webhook Stripe non reçu). Le changement est tracé dans
+            le journal d&apos;audit.
+          </p>
+          <Button
+            type="button"
+            variant="outline"
+            data-slot="stripe-settings-force-ready"
+            onClick={onForceReady}
+            disabled={isOverriding}
+            className="border-amber-400 bg-white hover:bg-amber-100"
+          >
+            {isOverriding
+              ? "Application…"
+              : "Marquer comme « Prêt à recevoir les paiements »"}
+          </Button>
+        </div>
+      ) : null}
+
       {/* URL display + copy button (only once we have a URL) */}
       {hasUrl ? (
         <div className="flex flex-col gap-1.5">

packages/backend/convex/lib/stripe/account.ts

@@ -7,6 +7,7 @@ import {
   kbAdminMutation,
   kbAdminQuery,
   setTenantStripeAccount,
+  setTenantStripeStatus,
 } from "../tenancy";
 
 /**
@@ -106,6 +107,51 @@ export const stampStripeAccount = kbAdminMutation({
   },
 });
 
+/**
+ * Root-only manual override of the tenant's Stripe Connect status. Backup path
+ * for when the `account.updated` webhook fails to fire / arrive (Stripe Connect
+ * webhook misconfig, sandbox flakiness, signature mismatch, network blip) — the
+ * admin completed the KYC with the resto IRL but the badge stays « En attente »
+ * forever. With this mutation, the admin can flip the status from the UI in one
+ * click instead of waiting / debugging the webhook.
+ *
+ * Auto-audited via `kbAdminMutation` so every manual override leaves a trail
+ * (who, when, from-status → to-status — the wrapper records the action + actor;
+ * we add an explicit richer `logAudit` carrying the previous status for ops
+ * reconstruction, same pattern as `tenant.activate`).
+ *
+ * Refuses if the tenant has no `stripeAccountId` yet (overriding the status of
+ * a non-existent account makes no sense — generate a Stripe Connect link first).
+ *
+ * Args:
+ *  - `tenantId` — the tenant to patch
+ *  - `status`   — `"ready" | "disabled" | "pending"` (the full union; admin can
+ *                 roll back if a misclick happened — the audit log records it).
+ */
+export const forceStripeStatusOverride = kbAdminMutation({
+  args: {
+    tenantId: v.id("tenants"),
+    status: v.union(
+      v.literal("ready"),
+      v.literal("disabled"),
+      v.literal("pending"),
+    ),
+  },
+  action: "stripe.account.forceStatusOverride",
+  handler: async (ctx, args): Promise<void> => {
+    const tenant = await getTenantById(ctx, args.tenantId);
+    if (tenant === null) throw tenantNotFound();
+    if (tenant.stripeAccountId === undefined) {
+      throw new ConvexError({
+        code: "INVALID_STATE",
+        message:
+          "Cannot force a Stripe status on a tenant with no Stripe account. Generate a Stripe Connect link first.",
+      });
+    }
+    await setTenantStripeStatus(ctx, args.tenantId, args.status);
+  },
+});
+
 /**
  * Root-only: create (or reuse) the resto's Stripe Connect Express account,
  * PRE-FILLED with its SIRET / email / first + last name, and return a fresh