@fayz-ai/plugin-financial 0.8.0 → 0.8.3

package/src/migrations/009_agent_rpcs.sql

@@ -0,0 +1,165 @@
+-- ============================================================================
+-- plugin-financial 009: server-plane agent write RPC.
+--
+-- public.agent_financial_mark_payment_received — "marca o atendimento como
+-- pago em cartão 2x". Resolves the order (directly or via a booking id),
+-- guard-checks the actor (agent_guard, spine 015), promotes the order into an
+-- invoice + installment ledger through the EXISTING invariant function
+-- fn_invoice_from_order (004) — never re-implementing its numbering/allocation
+-- logic — then settles the installments following 008's split model (bill rows
+-- flip to paid; each cash event is its own movement_kind='payment' row).
+--
+-- fn_invoice_from_order authorizes via user_tenant_ids() (auth.uid()). This
+-- RPC runs under the broker's service key, so it impersonates the ALREADY
+-- GUARD-VERIFIED actor for the duration of the transaction by setting
+-- request.jwt.claims locally — the invariant function keeps working unchanged
+-- and the audit trail carries the real acting user.
+--
+-- Contract: (p_tenant_id, p_actor_user_id, p_payload) → jsonb
+--   payload {order_id? uuid, booking_id? uuid, method text
+--            ('cash'|'pix'|'credit_card'|'debit_card'|'transfer'),
+--            installments? int (credit_card only, 1–12), amount? numeric}
+-- ============================================================================
+
+CREATE OR REPLACE FUNCTION public.agent_financial_mark_payment_received(
+  p_tenant_id uuid,
+  p_actor_user_id uuid,
+  p_payload jsonb
+) RETURNS jsonb
+LANGUAGE plpgsql SECURITY DEFINER
+SET search_path = public
+AS $$
+DECLARE
+  v_denial jsonb;
+  v_order_id uuid;
+  v_booking_id uuid;
+  v_method text;
+  v_installments int;
+  v_amount numeric;
+  v_order record;
+  v_bill record;
+  v_paid_count int := 0;
+  v_total_paid numeric := 0;
+BEGIN
+  -- ── payload ──────────────────────────────────────────────────────────────
+  BEGIN
+    v_order_id   := (p_payload->>'order_id')::uuid;
+    v_booking_id := (p_payload->>'booking_id')::uuid;
+    v_amount     := (p_payload->>'amount')::numeric;
+    v_installments := COALESCE((p_payload->>'installments')::int, 1);
+  EXCEPTION WHEN OTHERS THEN
+    RETURN jsonb_build_object('ok', false, 'error', 'invalid payload: ' || SQLERRM);
+  END;
+  v_method := lower(COALESCE(p_payload->>'method', 'cash'));
+  IF v_method NOT IN ('cash', 'pix', 'credit_card', 'debit_card', 'transfer') THEN
+    RETURN jsonb_build_object('ok', false, 'error', 'unknown payment method');
+  END IF;
+  IF v_installments NOT BETWEEN 1 AND 12
+     OR (v_installments > 1 AND v_method <> 'credit_card') THEN
+    RETURN jsonb_build_object('ok', false, 'error', 'installments require credit_card (1-12)');
+  END IF;
+
+  -- booking → order
+  IF v_order_id IS NULL AND v_booking_id IS NOT NULL THEN
+    SELECT b.order_id INTO v_order_id
+    FROM appointments b
+    WHERE b.id = v_booking_id AND b.tenant_id = p_tenant_id;
+  END IF;
+  IF v_order_id IS NULL THEN
+    RETURN jsonb_build_object('ok', false, 'error', 'order_id or booking_id required (booking must have an order)');
+  END IF;
+
+  SELECT o.id, o.status, o.total INTO v_order
+  FROM orders o
+  WHERE o.id = v_order_id AND o.tenant_id = p_tenant_id;
+  IF NOT FOUND THEN
+    RETURN jsonb_build_object('ok', false, 'error', 'unknown order for this tenant');
+  END IF;
+  IF v_order.status = 'cancelled' THEN
+    RETURN jsonb_build_object('ok', false, 'error', 'cannot receive payment on a cancelled order');
+  END IF;
+
+  -- ── authorization ────────────────────────────────────────────────────────
+  v_denial := agent_guard(p_tenant_id, p_actor_user_id, 'financial.receivables', 'update');
+  IF v_denial IS NOT NULL THEN
+    RETURN jsonb_build_object('ok', false, 'denial', v_denial);
+  END IF;
+
+  -- already fully paid?
+  IF EXISTS (
+    SELECT 1 FROM plg_financial_movements m
+    WHERE m.invoice_id = v_order_id AND m.movement_kind = 'bill'
+  ) AND NOT EXISTS (
+    SELECT 1 FROM plg_financial_movements m
+    WHERE m.invoice_id = v_order_id AND m.movement_kind = 'bill' AND m.status <> 'paid'
+  ) THEN
+    RETURN jsonb_build_object('ok', false, 'error', 'order is already fully paid');
+  END IF;
+
+  -- ── invoice via the existing invariant function (impersonate the verified
+  --     actor so fn_invoice_from_order's user_tenant_ids() check passes) ─────
+  PERFORM set_config('request.jwt.claims',
+                     jsonb_build_object('sub', p_actor_user_id, 'role', 'authenticated')::text,
+                     true);
+  PERFORM fn_invoice_from_order(v_order_id, current_date, NULL, v_installments, 'credit');
+
+  -- ── settle: flip pending bill installments to paid + emit payment rows ───
+  FOR v_bill IN
+    SELECT m.* FROM plg_financial_movements m
+    WHERE m.invoice_id = v_order_id
+      AND m.tenant_id = p_tenant_id
+      AND m.movement_kind = 'bill'
+      AND m.status <> 'paid'
+    ORDER BY m.installment_number NULLS FIRST
+  LOOP
+    UPDATE plg_financial_movements SET
+      status = 'paid',
+      paid_amount = v_bill.amount,
+      payment_date = current_date,
+      card_installments = CASE WHEN v_method = 'credit_card' THEN v_installments ELSE NULL END,
+      metadata = COALESCE(metadata, '{}'::jsonb)
+                 || jsonb_build_object('paidVia', 'agent', 'method', v_method),
+      updated_at = now()
+    WHERE id = v_bill.id;
+
+    INSERT INTO plg_financial_movements
+      (tenant_id, invoice_id, direction, movement_kind, amount, paid_amount, status,
+       due_date, payment_date, installment_number, card_installments, metadata)
+    VALUES
+      (p_tenant_id, v_order_id, v_bill.direction, 'payment', v_bill.amount, v_bill.amount,
+       'paid', v_bill.due_date, current_date, v_bill.installment_number,
+       CASE WHEN v_method = 'credit_card' THEN v_installments ELSE NULL END,
+       jsonb_build_object('source', 'agent', 'method', v_method));
+
+    v_paid_count := v_paid_count + 1;
+    v_total_paid := v_total_paid + v_bill.amount;
+  END LOOP;
+
+  IF v_paid_count = 0 THEN
+    RETURN jsonb_build_object('ok', false, 'error', 'no open installments found to settle');
+  END IF;
+
+  INSERT INTO audit_logs (tenant_id, user_id, action, entity_type, entity_id, metadata)
+  VALUES (p_tenant_id, p_actor_user_id, 'agent.markPaymentReceived', 'order', v_order_id::text,
+          jsonb_build_object('payload', p_payload, 'installmentsSettled', v_paid_count,
+                             'totalPaid', v_total_paid));
+
+  RETURN jsonb_build_object(
+    'ok', true,
+    'id', v_order_id,
+    'record', jsonb_build_object(
+      'ref', jsonb_build_object('id', v_order_id, 'resource', 'orders',
+                                'archetype', 'order:service_order'),
+      'method', v_method,
+      'installments', v_installments,
+      'installments_settled', v_paid_count,
+      'total_paid', v_total_paid
+    )
+  );
+END;
+$$;
+
+REVOKE ALL ON FUNCTION public.agent_financial_mark_payment_received(uuid, uuid, jsonb) FROM public;
+REVOKE EXECUTE ON FUNCTION public.agent_financial_mark_payment_received(uuid, uuid, jsonb) FROM anon;
+GRANT EXECUTE ON FUNCTION public.agent_financial_mark_payment_received(uuid, uuid, jsonb)
+  TO authenticated, service_role;

package/src/migrations/010_invoice_internal.sql

@@ -0,0 +1,133 @@
+-- Financial plugin — separate WHO MAY invoice from HOW an invoice is built.
+--
+-- fn_invoice_from_order (004) mixes the two: it checks that the caller is a
+-- member of the order's tenant, then does the work. That check is right for a
+-- human clicking "Faturar" in the admin, and impossible for anything else — a
+-- storefront checkout runs as the SHOPPER, whose user_tenant_ids() is empty by
+-- definition, so an order that should raise a receivable the moment it is placed
+-- cannot raise one at all. SECURITY DEFINER does not help: auth.uid() still
+-- belongs to the caller inside the definer context.
+--
+-- So the body moves to an internal function with no authorization of its own,
+-- and fn_invoice_from_order keeps its signature, keeps its check, and delegates.
+-- Callers that exist today (CRM approveQuote, the agenda bridge) are untouched.
+-- The internal one is granted to NOBODY: it is reachable only from other
+-- SECURITY DEFINER functions and triggers that have already decided the caller
+-- is entitled — the shop's order-to-cash bridge being the first.
+--
+-- Idempotent.
+
+CREATE OR REPLACE FUNCTION public.fn_invoice_from_order_internal(
+  p_order_id uuid,
+  p_due_date date DEFAULT NULL,
+  p_status text DEFAULT NULL,
+  p_installments int DEFAULT 1,
+  p_direction text DEFAULT 'credit'
+) RETURNS uuid
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+DECLARE
+  v_order   public.orders%ROWTYPE;
+  v_ref     text;
+  v_seq     bigint;
+  v_summary text;
+  v_contact text;
+  v_existing uuid;
+  v_kind    text;
+  v_prefix  text;
+  v_n       int := GREATEST(COALESCE(p_installments, 1), 1);
+  v_total   numeric;
+  v_base    numeric;
+  v_amt     numeric;
+  v_alloc   numeric := 0;
+  v_due     date;
+  i         int;
+BEGIN
+  SELECT * INTO v_order FROM public.orders WHERE id = p_order_id;
+  IF NOT FOUND THEN RAISE EXCEPTION 'fn_invoice_from_order: order % not found', p_order_id; END IF;
+
+  -- Idempotent: an order already carrying a bill is already invoiced.
+  SELECT id INTO v_existing FROM public.plg_financial_movements
+    WHERE invoice_id = p_order_id AND movement_kind = 'bill' LIMIT 1;
+  IF v_existing IS NOT NULL THEN RETURN p_order_id; END IF;
+
+  IF p_direction = 'debit' THEN v_kind := 'invoice_payable'; v_prefix := 'PAG';
+  ELSE v_kind := 'invoice_receivable'; v_prefix := 'REC'; END IF;
+
+  SELECT public.next_sequence(v_order.tenant_id, v_kind) INTO v_seq;
+  v_ref := v_prefix || '-' || lpad(v_seq::text, 5, '0');
+
+  SELECT string_agg(name, ', ' ORDER BY sort_order) INTO v_summary
+    FROM public.order_items WHERE order_id = p_order_id;
+  SELECT name INTO v_contact FROM public.people WHERE id = v_order.party_id;
+
+  UPDATE public.orders SET
+    status = COALESCE(p_status, status),
+    stage = 'invoiced',
+    direction = p_direction,
+    reference_number = v_ref,
+    metadata = COALESCE(metadata, '{}'::jsonb) || jsonb_build_object(
+      'itemsSummary', COALESCE(v_summary, ''),
+      'contactName', v_contact,
+      'installmentCount', v_n,
+      'quoteNumber', v_order.reference_number,
+      'direction', p_direction
+    ),
+    updated_at = now()
+  WHERE id = p_order_id;
+
+  v_total := COALESCE(v_order.total, 0);
+  v_base  := round(v_total / v_n, 2);
+  v_due   := COALESCE(p_due_date, current_date);
+  FOR i IN 1..v_n LOOP
+    IF i = v_n THEN v_amt := round(v_total - v_alloc, 2);
+    ELSE v_amt := v_base; v_alloc := v_alloc + v_base; END IF;
+    INSERT INTO public.plg_financial_movements
+      (tenant_id, invoice_id, direction, movement_kind, amount, paid_amount, status, due_date, installment_number)
+    VALUES
+      (v_order.tenant_id, p_order_id, p_direction, 'bill', v_amt, 0, 'pending',
+       (v_due + ((i - 1) || ' months')::interval)::date, i);
+  END LOOP;
+
+  RETURN p_order_id;
+END;
+$$;
+
+-- Deliberately NOT granted to authenticated/anon: entry is through
+-- fn_invoice_from_order, or from another definer function that has already
+-- established the caller's right to create this receivable.
+REVOKE ALL ON FUNCTION public.fn_invoice_from_order_internal(uuid, date, text, int, text) FROM PUBLIC;
+
+-- The public entry point: unchanged signature and behaviour, now a guard around
+-- the shared body instead of a second copy of it.
+CREATE OR REPLACE FUNCTION public.fn_invoice_from_order(
+  p_order_id uuid,
+  p_due_date date DEFAULT NULL,
+  p_status text DEFAULT NULL,
+  p_installments int DEFAULT 1,
+  p_direction text DEFAULT 'credit'
+) RETURNS uuid
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+DECLARE v_tenant uuid;
+BEGIN
+  SELECT tenant_id INTO v_tenant FROM public.orders WHERE id = p_order_id;
+  IF v_tenant IS NULL THEN
+    RAISE EXCEPTION 'fn_invoice_from_order: order % not found', p_order_id;
+  END IF;
+  IF v_tenant NOT IN (SELECT public.user_tenant_ids()) THEN
+    RAISE EXCEPTION 'fn_invoice_from_order: forbidden';
+  END IF;
+
+  RETURN public.fn_invoice_from_order_internal(
+    p_order_id, p_due_date, p_status, p_installments, p_direction);
+END;
+$$;
+
+GRANT EXECUTE ON FUNCTION public.fn_invoice_from_order(uuid, date, text, int, text) TO authenticated;
+
+NOTIFY pgrst, 'reload schema';

package/src/migrations/index.ts

@@ -1,4 +1,4 @@
-// AUTO-GENERATED from 000_plg_rename.sql, 001_financial_base.sql, 002_chart_of_accounts.sql, 003_card_brands.sql, 004_order_to_cash.sql, 005_seed_defaults.sql, 006_rls_policies.sql, 006b_extract_fee_amount.sql, 007_reconciliation.sql, 007b_movement_payment_method_type.sql, 008_split_payment_movements.sql — regenerate with scripts/embed-migrations.mjs
+// AUTO-GENERATED from 000_plg_rename.sql, 001_financial_base.sql, 002_chart_of_accounts.sql, 003_card_brands.sql, 004_order_to_cash.sql, 005_seed_defaults.sql, 006_rls_policies.sql, 006b_extract_fee_amount.sql, 007_reconciliation.sql, 007b_movement_payment_method_type.sql, 008_split_payment_movements.sql, 009_agent_rpcs.sql, 010_invoice_internal.sql — regenerate with scripts/embed-migrations.mjs
 // SQL files are the source of truth; this inline copy lets the manifest declare
 // migrations as data. Do not edit by hand — run the embed script instead.
 
@@ -203,8 +203,22 @@ CREATE TABLE IF NOT EXISTS public.sequences (
   current_value bigint NOT NULL DEFAULT 0,
   PRIMARY KEY (tenant_id, kind)
 );
+-- Baseline: RLS ON, deny-all (no policies), like the salon pool. The counter is
+-- an internal, non-API table written ONLY through next_sequence() below, which is
+-- SECURITY DEFINER and so bypasses RLS as the table owner. Legacy pools that
+-- shipped this table without RLS are also remediated by packages/db 013_sequences_rls.sql.
+ALTER TABLE public.sequences ENABLE ROW LEVEL SECURITY;
+
+-- SECURITY DEFINER: next_sequence is called directly via PostgREST RPC by
+-- authenticated users (src/data/supabase.ts → createInvoice), so with deny-all
+-- RLS on public.sequences it MUST run as the table owner to write the counter.
+-- SET search_path pins schema resolution for the definer context.
 CREATE OR REPLACE FUNCTION public.next_sequence(p_tenant_id uuid, p_kind text)
-RETURNS bigint LANGUAGE plpgsql AS $$
+RETURNS bigint
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
 DECLARE v_next bigint;
 BEGIN
   INSERT INTO public.sequences (tenant_id, kind, current_value)
@@ -529,6 +543,308 @@ SET payment_date = NULL, bank_account_id = NULL, payment_method_id = NULL,
 WHERE movement_kind = 'bill';
 `
 
+export const MIGRATION_009_AGENT_RPCS = `-- ============================================================================
+-- plugin-financial 009: server-plane agent write RPC.
+--
+-- public.agent_financial_mark_payment_received — "marca o atendimento como
+-- pago em cartão 2x". Resolves the order (directly or via a booking id),
+-- guard-checks the actor (agent_guard, spine 015), promotes the order into an
+-- invoice + installment ledger through the EXISTING invariant function
+-- fn_invoice_from_order (004) — never re-implementing its numbering/allocation
+-- logic — then settles the installments following 008's split model (bill rows
+-- flip to paid; each cash event is its own movement_kind='payment' row).
+--
+-- fn_invoice_from_order authorizes via user_tenant_ids() (auth.uid()). This
+-- RPC runs under the broker's service key, so it impersonates the ALREADY
+-- GUARD-VERIFIED actor for the duration of the transaction by setting
+-- request.jwt.claims locally — the invariant function keeps working unchanged
+-- and the audit trail carries the real acting user.
+--
+-- Contract: (p_tenant_id, p_actor_user_id, p_payload) → jsonb
+--   payload {order_id? uuid, booking_id? uuid, method text
+--            ('cash'|'pix'|'credit_card'|'debit_card'|'transfer'),
+--            installments? int (credit_card only, 1–12), amount? numeric}
+-- ============================================================================
+
+CREATE OR REPLACE FUNCTION public.agent_financial_mark_payment_received(
+  p_tenant_id uuid,
+  p_actor_user_id uuid,
+  p_payload jsonb
+) RETURNS jsonb
+LANGUAGE plpgsql SECURITY DEFINER
+SET search_path = public
+AS $$
+DECLARE
+  v_denial jsonb;
+  v_order_id uuid;
+  v_booking_id uuid;
+  v_method text;
+  v_installments int;
+  v_amount numeric;
+  v_order record;
+  v_bill record;
+  v_paid_count int := 0;
+  v_total_paid numeric := 0;
+BEGIN
+  -- ── payload ──────────────────────────────────────────────────────────────
+  BEGIN
+    v_order_id   := (p_payload->>'order_id')::uuid;
+    v_booking_id := (p_payload->>'booking_id')::uuid;
+    v_amount     := (p_payload->>'amount')::numeric;
+    v_installments := COALESCE((p_payload->>'installments')::int, 1);
+  EXCEPTION WHEN OTHERS THEN
+    RETURN jsonb_build_object('ok', false, 'error', 'invalid payload: ' || SQLERRM);
+  END;
+  v_method := lower(COALESCE(p_payload->>'method', 'cash'));
+  IF v_method NOT IN ('cash', 'pix', 'credit_card', 'debit_card', 'transfer') THEN
+    RETURN jsonb_build_object('ok', false, 'error', 'unknown payment method');
+  END IF;
+  IF v_installments NOT BETWEEN 1 AND 12
+     OR (v_installments > 1 AND v_method <> 'credit_card') THEN
+    RETURN jsonb_build_object('ok', false, 'error', 'installments require credit_card (1-12)');
+  END IF;
+
+  -- booking → order
+  IF v_order_id IS NULL AND v_booking_id IS NOT NULL THEN
+    SELECT b.order_id INTO v_order_id
+    FROM appointments b
+    WHERE b.id = v_booking_id AND b.tenant_id = p_tenant_id;
+  END IF;
+  IF v_order_id IS NULL THEN
+    RETURN jsonb_build_object('ok', false, 'error', 'order_id or booking_id required (booking must have an order)');
+  END IF;
+
+  SELECT o.id, o.status, o.total INTO v_order
+  FROM orders o
+  WHERE o.id = v_order_id AND o.tenant_id = p_tenant_id;
+  IF NOT FOUND THEN
+    RETURN jsonb_build_object('ok', false, 'error', 'unknown order for this tenant');
+  END IF;
+  IF v_order.status = 'cancelled' THEN
+    RETURN jsonb_build_object('ok', false, 'error', 'cannot receive payment on a cancelled order');
+  END IF;
+
+  -- ── authorization ────────────────────────────────────────────────────────
+  v_denial := agent_guard(p_tenant_id, p_actor_user_id, 'financial.receivables', 'update');
+  IF v_denial IS NOT NULL THEN
+    RETURN jsonb_build_object('ok', false, 'denial', v_denial);
+  END IF;
+
+  -- already fully paid?
+  IF EXISTS (
+    SELECT 1 FROM plg_financial_movements m
+    WHERE m.invoice_id = v_order_id AND m.movement_kind = 'bill'
+  ) AND NOT EXISTS (
+    SELECT 1 FROM plg_financial_movements m
+    WHERE m.invoice_id = v_order_id AND m.movement_kind = 'bill' AND m.status <> 'paid'
+  ) THEN
+    RETURN jsonb_build_object('ok', false, 'error', 'order is already fully paid');
+  END IF;
+
+  -- ── invoice via the existing invariant function (impersonate the verified
+  --     actor so fn_invoice_from_order's user_tenant_ids() check passes) ─────
+  PERFORM set_config('request.jwt.claims',
+                     jsonb_build_object('sub', p_actor_user_id, 'role', 'authenticated')::text,
+                     true);
+  PERFORM fn_invoice_from_order(v_order_id, current_date, NULL, v_installments, 'credit');
+
+  -- ── settle: flip pending bill installments to paid + emit payment rows ───
+  FOR v_bill IN
+    SELECT m.* FROM plg_financial_movements m
+    WHERE m.invoice_id = v_order_id
+      AND m.tenant_id = p_tenant_id
+      AND m.movement_kind = 'bill'
+      AND m.status <> 'paid'
+    ORDER BY m.installment_number NULLS FIRST
+  LOOP
+    UPDATE plg_financial_movements SET
+      status = 'paid',
+      paid_amount = v_bill.amount,
+      payment_date = current_date,
+      card_installments = CASE WHEN v_method = 'credit_card' THEN v_installments ELSE NULL END,
+      metadata = COALESCE(metadata, '{}'::jsonb)
+                 || jsonb_build_object('paidVia', 'agent', 'method', v_method),
+      updated_at = now()
+    WHERE id = v_bill.id;
+
+    INSERT INTO plg_financial_movements
+      (tenant_id, invoice_id, direction, movement_kind, amount, paid_amount, status,
+       due_date, payment_date, installment_number, card_installments, metadata)
+    VALUES
+      (p_tenant_id, v_order_id, v_bill.direction, 'payment', v_bill.amount, v_bill.amount,
+       'paid', v_bill.due_date, current_date, v_bill.installment_number,
+       CASE WHEN v_method = 'credit_card' THEN v_installments ELSE NULL END,
+       jsonb_build_object('source', 'agent', 'method', v_method));
+
+    v_paid_count := v_paid_count + 1;
+    v_total_paid := v_total_paid + v_bill.amount;
+  END LOOP;
+
+  IF v_paid_count = 0 THEN
+    RETURN jsonb_build_object('ok', false, 'error', 'no open installments found to settle');
+  END IF;
+
+  INSERT INTO audit_logs (tenant_id, user_id, action, entity_type, entity_id, metadata)
+  VALUES (p_tenant_id, p_actor_user_id, 'agent.markPaymentReceived', 'order', v_order_id::text,
+          jsonb_build_object('payload', p_payload, 'installmentsSettled', v_paid_count,
+                             'totalPaid', v_total_paid));
+
+  RETURN jsonb_build_object(
+    'ok', true,
+    'id', v_order_id,
+    'record', jsonb_build_object(
+      'ref', jsonb_build_object('id', v_order_id, 'resource', 'orders',
+                                'archetype', 'order:service_order'),
+      'method', v_method,
+      'installments', v_installments,
+      'installments_settled', v_paid_count,
+      'total_paid', v_total_paid
+    )
+  );
+END;
+$$;
+
+REVOKE ALL ON FUNCTION public.agent_financial_mark_payment_received(uuid, uuid, jsonb) FROM public;
+REVOKE EXECUTE ON FUNCTION public.agent_financial_mark_payment_received(uuid, uuid, jsonb) FROM anon;
+GRANT EXECUTE ON FUNCTION public.agent_financial_mark_payment_received(uuid, uuid, jsonb)
+  TO authenticated, service_role;
+`
+
+export const MIGRATION_010_INVOICE_INTERNAL = `-- Financial plugin — separate WHO MAY invoice from HOW an invoice is built.
+--
+-- fn_invoice_from_order (004) mixes the two: it checks that the caller is a
+-- member of the order's tenant, then does the work. That check is right for a
+-- human clicking "Faturar" in the admin, and impossible for anything else — a
+-- storefront checkout runs as the SHOPPER, whose user_tenant_ids() is empty by
+-- definition, so an order that should raise a receivable the moment it is placed
+-- cannot raise one at all. SECURITY DEFINER does not help: auth.uid() still
+-- belongs to the caller inside the definer context.
+--
+-- So the body moves to an internal function with no authorization of its own,
+-- and fn_invoice_from_order keeps its signature, keeps its check, and delegates.
+-- Callers that exist today (CRM approveQuote, the agenda bridge) are untouched.
+-- The internal one is granted to NOBODY: it is reachable only from other
+-- SECURITY DEFINER functions and triggers that have already decided the caller
+-- is entitled — the shop's order-to-cash bridge being the first.
+--
+-- Idempotent.
+
+CREATE OR REPLACE FUNCTION public.fn_invoice_from_order_internal(
+  p_order_id uuid,
+  p_due_date date DEFAULT NULL,
+  p_status text DEFAULT NULL,
+  p_installments int DEFAULT 1,
+  p_direction text DEFAULT 'credit'
+) RETURNS uuid
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+DECLARE
+  v_order   public.orders%ROWTYPE;
+  v_ref     text;
+  v_seq     bigint;
+  v_summary text;
+  v_contact text;
+  v_existing uuid;
+  v_kind    text;
+  v_prefix  text;
+  v_n       int := GREATEST(COALESCE(p_installments, 1), 1);
+  v_total   numeric;
+  v_base    numeric;
+  v_amt     numeric;
+  v_alloc   numeric := 0;
+  v_due     date;
+  i         int;
+BEGIN
+  SELECT * INTO v_order FROM public.orders WHERE id = p_order_id;
+  IF NOT FOUND THEN RAISE EXCEPTION 'fn_invoice_from_order: order % not found', p_order_id; END IF;
+
+  -- Idempotent: an order already carrying a bill is already invoiced.
+  SELECT id INTO v_existing FROM public.plg_financial_movements
+    WHERE invoice_id = p_order_id AND movement_kind = 'bill' LIMIT 1;
+  IF v_existing IS NOT NULL THEN RETURN p_order_id; END IF;
+
+  IF p_direction = 'debit' THEN v_kind := 'invoice_payable'; v_prefix := 'PAG';
+  ELSE v_kind := 'invoice_receivable'; v_prefix := 'REC'; END IF;
+
+  SELECT public.next_sequence(v_order.tenant_id, v_kind) INTO v_seq;
+  v_ref := v_prefix || '-' || lpad(v_seq::text, 5, '0');
+
+  SELECT string_agg(name, ', ' ORDER BY sort_order) INTO v_summary
+    FROM public.order_items WHERE order_id = p_order_id;
+  SELECT name INTO v_contact FROM public.people WHERE id = v_order.party_id;
+
+  UPDATE public.orders SET
+    status = COALESCE(p_status, status),
+    stage = 'invoiced',
+    direction = p_direction,
+    reference_number = v_ref,
+    metadata = COALESCE(metadata, '{}'::jsonb) || jsonb_build_object(
+      'itemsSummary', COALESCE(v_summary, ''),
+      'contactName', v_contact,
+      'installmentCount', v_n,
+      'quoteNumber', v_order.reference_number,
+      'direction', p_direction
+    ),
+    updated_at = now()
+  WHERE id = p_order_id;
+
+  v_total := COALESCE(v_order.total, 0);
+  v_base  := round(v_total / v_n, 2);
+  v_due   := COALESCE(p_due_date, current_date);
+  FOR i IN 1..v_n LOOP
+    IF i = v_n THEN v_amt := round(v_total - v_alloc, 2);
+    ELSE v_amt := v_base; v_alloc := v_alloc + v_base; END IF;
+    INSERT INTO public.plg_financial_movements
+      (tenant_id, invoice_id, direction, movement_kind, amount, paid_amount, status, due_date, installment_number)
+    VALUES
+      (v_order.tenant_id, p_order_id, p_direction, 'bill', v_amt, 0, 'pending',
+       (v_due + ((i - 1) || ' months')::interval)::date, i);
+  END LOOP;
+
+  RETURN p_order_id;
+END;
+$$;
+
+-- Deliberately NOT granted to authenticated/anon: entry is through
+-- fn_invoice_from_order, or from another definer function that has already
+-- established the caller's right to create this receivable.
+REVOKE ALL ON FUNCTION public.fn_invoice_from_order_internal(uuid, date, text, int, text) FROM PUBLIC;
+
+-- The public entry point: unchanged signature and behaviour, now a guard around
+-- the shared body instead of a second copy of it.
+CREATE OR REPLACE FUNCTION public.fn_invoice_from_order(
+  p_order_id uuid,
+  p_due_date date DEFAULT NULL,
+  p_status text DEFAULT NULL,
+  p_installments int DEFAULT 1,
+  p_direction text DEFAULT 'credit'
+) RETURNS uuid
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+DECLARE v_tenant uuid;
+BEGIN
+  SELECT tenant_id INTO v_tenant FROM public.orders WHERE id = p_order_id;
+  IF v_tenant IS NULL THEN
+    RAISE EXCEPTION 'fn_invoice_from_order: order % not found', p_order_id;
+  END IF;
+  IF v_tenant NOT IN (SELECT public.user_tenant_ids()) THEN
+    RAISE EXCEPTION 'fn_invoice_from_order: forbidden';
+  END IF;
+
+  RETURN public.fn_invoice_from_order_internal(
+    p_order_id, p_due_date, p_status, p_installments, p_direction);
+END;
+$$;
+
+GRANT EXECUTE ON FUNCTION public.fn_invoice_from_order(uuid, date, text, int, text) TO authenticated;
+
+NOTIFY pgrst, 'reload schema';
+`
+
 export const MIGRATIONS: Array<{ id: string; sql: string }> = [
   { id: "000_plg_rename", sql: MIGRATION_000_PLG_RENAME },
   { id: "001_financial_base", sql: MIGRATION_001_FINANCIAL_BASE },
@@ -541,4 +857,6 @@ export const MIGRATIONS: Array<{ id: string; sql: string }> = [
   { id: "007_reconciliation", sql: MIGRATION_007_RECONCILIATION },
   { id: "007b_movement_payment_method_type", sql: MIGRATION_007B_MOVEMENT_PAYMENT_METHOD_TYPE },
   { id: "008_split_payment_movements", sql: MIGRATION_008_SPLIT_PAYMENT_MOVEMENTS },
+  { id: "009_agent_rpcs", sql: MIGRATION_009_AGENT_RPCS },
+  { id: "010_invoice_internal", sql: MIGRATION_010_INVOICE_INTERNAL },
 ]

package/src/views/CardsView.tsx

@@ -2,6 +2,7 @@ import React, { useEffect, useMemo, useState } from 'react'
 import { CreditCard, Plus, CalendarClock } from 'lucide-react'
 import { useFinancialConfig, useFinancialStore, formatCurrency } from '../FinancialContext'
 import { SubpageHeader } from '@fayz-ai/ui'
+import { PermissionGate } from '@fayz-ai/saas'
 import { useTranslation } from '@fayz-ai/core'
 import type { BankAccount } from '../types'
 import { QuickTransactionForm } from './QuickTransactionForm'
@@ -182,15 +183,17 @@ export function CardsView() {
                       )}
                     </div>
 
-                    {/* Add expense against this card */}
-                    <button
-                      type="button"
-                      onClick={() => openAddExpense(card.id)}
-                      className="flex w-full items-center justify-center gap-1.5 rounded-input border border-input bg-card px-3 py-2 text-xs font-medium text-foreground transition-colors hover:bg-muted/40"
-                    >
-                      <Plus className="h-3.5 w-3.5" />
-                      {t('financial.cards.addExpense')}
-                    </button>
+                    {/* Add expense against this card — gated on the role's create action */}
+                    <PermissionGate feature="financial" action="create">
+                      <button
+                        type="button"
+                        onClick={() => openAddExpense(card.id)}
+                        className="flex w-full items-center justify-center gap-1.5 rounded-input border border-input bg-card px-3 py-2 text-xs font-medium text-foreground transition-colors hover:bg-muted/40"
+                      >
+                        <Plus className="h-3.5 w-3.5" />
+                        {t('financial.cards.addExpense')}
+                      </button>
+                    </PermissionGate>
                   </div>
                 </div>
               )