@fayz-ai/db 0.20.0 → 0.21.0

package/migrations/158_a_producao_e_do_restaurante_e_mora_no_estoque.sql

@@ -0,0 +1,129 @@
+-- ---------------------------------------------------------------------------
+-- 158_a_producao_e_do_restaurante_e_mora_no_estoque.sql
+-- ---------------------------------------------------------------------------
+-- Produção é um módulo de quem FABRICA o que vende — e, na frota de hoje, isso
+-- é o ChefControl. Uma clínica, um salão, uma escola e uma loja compilam o
+-- mesmo pacote e não têm o que produzir.
+--
+-- ── A porta é a OFERTA, não uma consulta na tela ────────────────────────────
+-- `preset.modules` é o que este ofício oferece (079): `resolvePluginRuntime`
+-- recebe a união do que os aplicativos da conta oferecem e deixa FORA todo
+-- plugin que ninguém ofereceu, mesmo o que nasce ligado. É a mesma porta que
+-- já mantém cozinha, mesa e reserva longe de um consultório — e o motivo de
+-- não haver `if (tenant.temResto)` em componente nenhum.
+--
+-- ── E o rail: «Estoque» passa a abrir em dois ───────────────────────────────
+-- Hoje o ChefControl põe o Estoque dentro de «Produtos», ao lado do Cardápio.
+-- Com a Produção ao lado, o Estoque vira rubrica própria com duas telas:
+--
+--     Estoque
+--       Geral       → /inventory
+--       Produção    → /production
+--
+-- «Produtos» fica com o Cardápio, que é o que ela sempre foi na cabeça de quem
+-- usa: o que se VENDE. Estoque é o que se GUARDA.
+--
+-- O `full` (aplicativo central) ganha a mesma rubrica por simetria, e nele ela
+-- se recolhe sozinha: sem a Produção oferecida, uma rubrica com um destino só
+-- VIRA o destino e volta a ser a linha «Estoque» de hoje (ver applyRailPreset).
+-- Nenhuma conta sem `resto` muda de menu.
+--
+-- Idempotente: recalcula rail, modules e labels a partir do que está lá.
+-- ---------------------------------------------------------------------------
+
+-- ── 1. A oferta: só o ChefControl oferece Produção ──────────────────────────
+UPDATE app.apps
+   SET preset = jsonb_set(
+         preset,
+         '{modules}',
+         (
+           SELECT to_jsonb(array_agg(m ORDER BY m))
+             FROM (
+               SELECT jsonb_array_elements_text(coalesce(preset -> 'modules', '[]'::jsonb)) AS m
+               UNION
+               SELECT 'production'
+             ) AS mods
+         ),
+         true
+       )
+ WHERE id = 'resto';
+
+-- ── 2. O vocabulário: dentro da rubrica, o Estoque chama-se «Geral» ─────────
+-- Fora dela o nome continua sendo o do plugin: a rubrica leva o próprio nome
+-- quando se recolhe, então uma conta sem Produção nunca lê «Geral» sozinho.
+UPDATE app.apps
+   SET preset = jsonb_set(
+         preset,
+         '{labels}',
+         coalesce(preset -> 'labels', '{}'::jsonb)
+           || jsonb_build_object('/inventory', 'Geral', '/production', 'Produção'),
+         true
+       )
+ WHERE id IN ('resto', 'full');
+
+-- ── 3. «Produtos» não existe: o que sobra dela é o Cardápio ─────────────────
+-- A rubrica juntava o que se VENDE (/menu) e o que se GUARDA (/inventory) sob
+-- um nome que não é nenhum dos dois. Tirado o Estoque, o que resta é uma
+-- rubrica de um destino só — e `applyRailPreset` recolhe essas, mantendo o
+-- nome da RUBRICA e não o do destino. Por isso o nome muda aqui: sem esta
+-- linha o rail leria «Produtos» apontando para o cardápio, que é o mal-entendido
+-- de partida com uma tela a menos.
+UPDATE app.apps
+   SET preset = jsonb_set(
+         preset,
+         '{rail}',
+         (
+           SELECT jsonb_agg(
+                    CASE
+                      WHEN entrada -> 'under' IS NOT NULL AND entrada ->> 'label' = 'Produtos'
+                        THEN jsonb_build_object('label', 'Cardápio', 'icon', 'BookOpen',
+                                                'under', jsonb_build_array('/menu'))
+                      ELSE entrada
+                    END
+                    ORDER BY ord
+                  )
+             FROM jsonb_array_elements(preset -> 'rail') WITH ORDINALITY AS r(entrada, ord)
+         ),
+         true
+       )
+ WHERE id = 'resto'
+   AND preset -> 'rail' IS NOT NULL;
+
+-- ── 4. A rubrica «Estoque», nos dois aplicativos ────────────────────────────
+-- Ela entra ENCOSTADA no vizinho certo, e não no fim: no ChefControl logo
+-- depois do «Cardápio» (o que se vende e o que se guarda leem-se juntos), e no
+-- aplicativo central logo depois da última rubrica antes de «Cadastros» — que
+-- é sempre a última de todo preset.
+--
+-- As posições são multiplicadas por dez para a nova caber no meio sem renumerar
+-- as vizinhas; `+5` é o «logo depois daquela».
+UPDATE app.apps a
+   SET preset = jsonb_set(
+         a.preset,
+         '{rail}',
+         (
+           WITH atual AS (
+             SELECT entrada, ord
+               FROM jsonb_array_elements(a.preset -> 'rail') WITH ORDINALITY AS r(entrada, ord)
+              WHERE entrada ->> 'label' IS DISTINCT FROM 'Estoque'
+                AND NOT (entrada ? 'under' AND entrada -> 'under' @> '["/inventory"]'::jsonb)
+           ),
+           vizinha AS (
+             SELECT coalesce(
+                      (SELECT ord FROM atual WHERE entrada -> 'under' @> '["/menu"]'::jsonb ORDER BY ord LIMIT 1),
+                      (SELECT max(ord) FROM atual WHERE entrada ->> 'label' IS DISTINCT FROM 'Cadastros')
+                    ) AS ord
+           )
+           SELECT jsonb_agg(entrada ORDER BY ord)
+             FROM (
+               SELECT entrada, ord * 10 AS ord FROM atual
+               UNION ALL
+               SELECT jsonb_build_object('label', 'Estoque', 'icon', 'Package',
+                                         'under', jsonb_build_array('/inventory', '/production')),
+                      (SELECT ord FROM vizinha) * 10 + 5
+             ) AS reordenado
+         ),
+         true
+       )
+ WHERE a.id IN ('resto', 'full')
+   AND a.preset -> 'rail' IS NOT NULL;

package/migrations/159_a_loja_tambem_confundia_o_que_vende_com_o_que_guarda.sql

@@ -0,0 +1,98 @@
+-- ---------------------------------------------------------------------------
+-- 159_a_loja_tambem_confundia_o_que_vende_com_o_que_guarda.sql
+-- ---------------------------------------------------------------------------
+-- A 158 separou Cardápio de Estoque no ChefControl e parou aí. Mas quem
+-- empresta o rail a uma conta é o PRIMEIRO aplicativo de `app_config()` — e
+-- numa churrascaria que roda StoreControl + FullControl + FiscalControl o
+-- primeiro é o StoreControl, porque `commerce` é ofício e `generic` não é.
+-- O menu que a Artorius lê nunca foi o do `full`.
+--
+-- E o StoreControl trazia o mesmo mal-entendido ao contrário:
+--
+--     Estoque  →  /inventory + /menu
+--
+-- O cardápio DENTRO do estoque. Vender e guardar são dois trabalhos; quem
+-- procura o que a casa oferece hoje e quem procura quanto ainda há na câmara
+-- não estão fazendo a mesma coisa.
+--
+-- Depois desta:
+--
+--     Cardápio  →  /menu
+--     Estoque   →  /inventory + /production
+--
+-- A Produção entra aqui como entrou no `full`: pela porta que já existe. Sem
+-- o app `resto` ninguém a OFERECE, `resolvePluginRuntime` a descarta, e uma
+-- rubrica de um destino só vira o destino (applyRailPreset) — a loja que não
+-- fabrica continua lendo a linha «Estoque» de sempre. Numa conta que também
+-- rode ChefControl, ela abre em Geral | Produção.
+--
+-- Idempotente: reescreve as duas rubricas a partir do que está lá.
+-- ---------------------------------------------------------------------------
+
+-- ── 1. O Estoque solta o Cardápio e recebe a Produção ───────────────────────
+UPDATE app.apps
+   SET preset = jsonb_set(
+         preset,
+         '{rail}',
+         (
+           SELECT jsonb_agg(
+                    CASE
+                      WHEN entrada ? 'under' AND entrada -> 'under' @> '["/inventory"]'::jsonb
+                        THEN jsonb_build_object('label', 'Estoque', 'icon', 'Package',
+                                                'under', jsonb_build_array('/inventory', '/production'))
+                      ELSE entrada
+                    END
+                    ORDER BY ord
+                  )
+             FROM jsonb_array_elements(preset -> 'rail') WITH ORDINALITY AS r(entrada, ord)
+         ),
+         true
+       )
+ WHERE id = 'shop'
+   AND preset -> 'rail' IS NOT NULL;
+
+-- ── 2. O Cardápio ganha rubrica própria, logo antes do Estoque ──────────────
+-- Encostado e não no fim: o que se vende e o que se guarda leem-se juntos.
+-- Posições ×10 para a nova caber no meio sem renumerar as vizinhas; `-5` é o
+-- «logo antes daquela».
+UPDATE app.apps a
+   SET preset = jsonb_set(
+         a.preset,
+         '{rail}',
+         (
+           WITH atual AS (
+             SELECT entrada, ord
+               FROM jsonb_array_elements(a.preset -> 'rail') WITH ORDINALITY AS r(entrada, ord)
+              WHERE entrada ->> 'label' IS DISTINCT FROM 'Cardápio'
+                AND NOT (entrada ? 'under' AND entrada -> 'under' @> '["/menu"]'::jsonb)
+           ),
+           vizinha AS (
+             SELECT (SELECT ord FROM atual
+                      WHERE entrada -> 'under' @> '["/inventory"]'::jsonb
+                      ORDER BY ord LIMIT 1) AS ord
+           )
+           SELECT jsonb_agg(entrada ORDER BY ord)
+             FROM (
+               SELECT entrada, ord * 10 AS ord FROM atual
+               UNION ALL
+               SELECT jsonb_build_object('label', 'Cardápio', 'icon', 'BookOpen',
+                                         'under', jsonb_build_array('/menu')),
+                      (SELECT ord FROM vizinha) * 10 - 5
+                WHERE (SELECT ord FROM vizinha) IS NOT NULL
+             ) AS reordenado
+         ),
+         true
+       )
+ WHERE a.id = 'shop'
+   AND a.preset -> 'rail' IS NOT NULL;
+
+-- ── 3. O vocabulário dentro da rubrica ──────────────────────────────────────
+UPDATE app.apps
+   SET preset = jsonb_set(
+         preset,
+         '{labels}',
+         coalesce(preset -> 'labels', '{}'::jsonb)
+           || jsonb_build_object('/inventory', 'Geral', '/production', 'Produção'),
+         true
+       )
+ WHERE id = 'shop';

package/migrations/161_vender_e_falar_com_quem_ainda_nao_comprou_sao_o_mesmo_assunto.sql

@@ -0,0 +1,73 @@
+-- ---------------------------------------------------------------------------
+-- 161_vender_e_falar_com_quem_ainda_nao_comprou_sao_o_mesmo_assunto.sql
+-- ---------------------------------------------------------------------------
+-- No rail de hoje «CRM» e «Marketing» são duas linhas vizinhas e soltas. Quem
+-- usa não separa as duas coisas: a campanha existe para gerar o lead, e o lead
+-- é o começo do funil. No V1 elas nem são dois módulos — o `CRMSidebar` do
+-- beautyplace desenha as views de venda E as de marketing na mesma barra, com
+-- os prefixos `mkt-` misturados no mesmo `CRMView`.
+--
+-- Depois desta:
+--
+--     CRM
+--       Vendas      → /sales
+--       Marketing   → /marketing
+--
+-- Onde só um dos dois está ligado, `applyRailPreset` recolhe a rubrica no
+-- destino que sobrou e ela volta a ser a linha de hoje — o `beauty`, que tem
+-- CRM no rail e não tem Marketing, não muda de menu.
+--
+-- «Vendas» e não «CRM» no filho: o pai já se chama CRM, e pai e filho com o
+-- mesmo nome é uma linha que não diz para onde leva (a mesma correção que o
+-- Funil levou no plugin, onde o modo «Funil» virou «Quadro»).
+--
+-- Idempotente: reescreve a rubrica a partir do que está lá.
+-- ---------------------------------------------------------------------------
+
+-- ── 1. O vocabulário dentro da rubrica ──────────────────────────────────────
+UPDATE app.apps
+   SET preset = jsonb_set(
+         preset,
+         '{labels}',
+         coalesce(preset -> 'labels', '{}'::jsonb)
+           || jsonb_build_object('/sales', 'Vendas', '/marketing', 'Marketing'),
+         true
+       )
+ WHERE preset -> 'rail' @> '["crm"]'::jsonb;
+
+-- ── 2. As duas linhas viram uma rubrica, no lugar da primeira delas ─────────
+-- No lugar da PRIMEIRA e não no fim: o CRM já está posicionado no rail de cada
+-- ofício (depois de Clientes no `full`, depois de Marketing no `shop`), e uma
+-- rubrica que muda de altura muda o menu de quem já sabia onde clicar.
+UPDATE app.apps a
+   SET preset = jsonb_set(
+         a.preset,
+         '{rail}',
+         (
+           WITH numerada AS (
+             SELECT entrada, ord
+               FROM jsonb_array_elements(a.preset -> 'rail') WITH ORDINALITY AS r(entrada, ord)
+           ),
+           alvo AS (
+             SELECT min(ord) AS ord
+               FROM numerada
+              WHERE entrada IN ('"crm"'::jsonb, '"marketing"'::jsonb)
+           ),
+           restante AS (
+             SELECT entrada, ord
+               FROM numerada
+              WHERE entrada NOT IN ('"crm"'::jsonb, '"marketing"'::jsonb)
+                AND entrada ->> 'label' IS DISTINCT FROM 'CRM'
+           )
+           SELECT jsonb_agg(entrada ORDER BY ord)
+             FROM (
+               SELECT entrada, ord * 10 AS ord FROM restante
+               UNION ALL
+               SELECT jsonb_build_object('label', 'CRM', 'icon', 'Filter',
+                                         'under', jsonb_build_array('/sales', '/marketing')),
+                      (SELECT ord FROM alvo) * 10 - 1
+             ) AS reordenado
+         ),
+         true
+       )
+ WHERE a.preset -> 'rail' @> '["crm"]'::jsonb;

package/migrations/162_o_walter_liga_a_lista_da_vez.sql

@@ -0,0 +1,71 @@
+-- The Beauty app offers the turn queue as an independent module. Walter's is
+-- the first tenant to turn it on; every other salon keeps today's behavior
+-- until an operator enables it from Settings > Modules.
+
+-- Walter's is a salon account. Keep Beauty active so app_config selects the
+-- StudioControl rail even if the tenant also owns a back-office application.
+INSERT INTO app.tenant_apps (tenant_id, app_id, status, source)
+VALUES ('c3a8f61d-742b-4e05-9d16-8b47e2f0a5c3', 'beauty', 'active', 'manual')
+ON CONFLICT (tenant_id, app_id)
+DO UPDATE SET status = 'active', source = 'manual', updated_at = now();
+
+UPDATE public.tenants
+   SET vertical_id = 'beauty', updated_at = now()
+ WHERE id = 'c3a8f61d-742b-4e05-9d16-8b47e2f0a5c3'
+   AND vertical_id IS DISTINCT FROM 'beauty';
+
+UPDATE app.apps
+   SET preset = jsonb_set(
+     preset,
+     '{modules}',
+     coalesce(preset -> 'modules', '[]'::jsonb) || '["agenda-turn-queue"]'::jsonb
+   )
+ WHERE id = 'beauty'
+   AND NOT (coalesce(preset -> 'modules', '[]'::jsonb) ? 'agenda-turn-queue');
+
+SELECT app.seed_permissions($$[
+  {"key":"agenda.turn_queue.read","plugin":"agenda-turn-queue","description":"See the live turn queue and its audit trail"},
+  {"key":"agenda.turn_queue.create","plugin":"agenda-turn-queue","description":"Enter the turn queue"},
+  {"key":"agenda.turn_queue.edit","plugin":"agenda-turn-queue","description":"Enter or leave your own turn"},
+  {"key":"agenda.turn_queue.manage","plugin":"agenda-turn-queue","description":"Record front-desk exceptions in the turn queue"}
+]$$::jsonb);
+
+SELECT app.seed_role_template_rows('salon', 'manager', 'Gerente', 1,
+  ARRAY['agenda.turn_queue.read','agenda.turn_queue.edit','agenda.turn_queue.manage']);
+SELECT app.seed_role_template_rows('salon', 'reception', 'Recepção', 2,
+  ARRAY['agenda.turn_queue.read','agenda.turn_queue.manage']);
+SELECT app.seed_role_template_rows('salon', 'professional', 'Profissional', 3,
+  ARRAY['agenda.turn_queue.read','agenda.turn_queue.edit']);
+SELECT app.seed_role_template_rows('clinic', 'manager', 'Coordenação', 1,
+  ARRAY['agenda.turn_queue.read','agenda.turn_queue.edit','agenda.turn_queue.manage']);
+SELECT app.seed_role_template_rows('clinic', 'reception', 'Recepção', 2,
+  ARRAY['agenda.turn_queue.read','agenda.turn_queue.manage']);
+SELECT app.seed_role_template_rows('clinic', 'professional', 'Profissional', 3,
+  ARRAY['agenda.turn_queue.read','agenda.turn_queue.edit']);
+
+INSERT INTO app.role_permissions (tenant_id, role_id, permission)
+SELECT r.tenant_id, r.id, p.permission
+  FROM app.roles r
+ CROSS JOIN LATERAL (
+   SELECT unnest(CASE r.key
+     WHEN 'owner' THEN ARRAY['agenda.turn_queue.read','agenda.turn_queue.create','agenda.turn_queue.edit','agenda.turn_queue.manage']
+     WHEN 'manager' THEN ARRAY['agenda.turn_queue.read','agenda.turn_queue.edit','agenda.turn_queue.manage']
+     WHEN 'reception' THEN ARRAY['agenda.turn_queue.read','agenda.turn_queue.manage']
+     WHEN 'professional' THEN ARRAY['agenda.turn_queue.read','agenda.turn_queue.edit']
+     ELSE ARRAY[]::text[] END) AS permission
+ ) p
+ WHERE r.tenant_id = 'c3a8f61d-742b-4e05-9d16-8b47e2f0a5c3'
+   AND r.key IN ('owner','manager','reception','professional')
+ON CONFLICT DO NOTHING;
+
+INSERT INTO app.tenant_plugins (tenant_id, plugin_id, facet, status, source)
+VALUES ('c3a8f61d-742b-4e05-9d16-8b47e2f0a5c3', 'agenda-turn-queue', '', 'active', 'manual')
+ON CONFLICT (tenant_id, plugin_id, facet)
+DO UPDATE SET status = 'active', source = 'manual', updated_at = now();
+
+-- Walter's must see the existing check-in entry even if the tenant previously
+-- hid it while shaping its menu. The Beauty preset already groups it in Agenda.
+INSERT INTO app.tenant_nav (tenant_id, entry_key, hidden)
+VALUES ('c3a8f61d-742b-4e05-9d16-8b47e2f0a5c3', '/checkin', false)
+ON CONFLICT (tenant_id, entry_key)
+DO UPDATE SET hidden = false, updated_at = now();

package/migrations/164_checkin_e_confirmacoes_vieram_com_a_agenda.sql

@@ -0,0 +1,29 @@
+-- 164: check-in e confirmações eram opção de BUILD, nunca um item de plano —
+-- toda conta com Agenda os tinha, de graça. Virar facet (rail-preset, mesma
+-- onda que criou `requiresFacet`) sem seguir esse fato para `app.plan_grants`
+-- quebrou o teto: `plan_permits('agenda','checkin',tenant)` nega em qualquer
+-- plano que já restrinja QUALQUER OUTRA coisa (a regra é "silêncio total
+-- permite", não "silêncio por facet") — então `tenant_plugin_set` rejeitava o
+-- toggle em todo plano com ao menos uma linha em `plan_grants`, e ligar
+-- Check-in em Módulos não fazia nada.
+--
+-- A correção segue o mesmo plano que já concede a Agenda: onde a Agenda em si
+-- está `included` ou `optional`, as duas facets entram `included` — elas
+-- nunca foram um upsell, só eram invisíveis para o catálogo de planos.
+
+DO $$
+DECLARE
+  v_plan record;
+BEGIN
+  IF to_regprocedure('public.register_plan_grant(text,text,text,text,text)') IS NULL THEN
+    RAISE NOTICE '164: register_plan_grant ausente — pulado (pool sem app.plan_grants ainda)';
+    RETURN;
+  END IF;
+
+  FOR v_plan IN SELECT DISTINCT plan_id FROM app.plan_grants WHERE plugin_id = 'agenda' AND facet = '' LOOP
+    PERFORM public.register_plan_grant(v_plan.plan_id, 'agenda', 'checkin', 'included',
+      'Vem com a Agenda desde sempre — nunca foi upsell, só nunca tinha linha própria.');
+    PERFORM public.register_plan_grant(v_plan.plan_id, 'agenda', 'confirmations', 'included',
+      'Vem com a Agenda desde sempre — nunca foi upsell, só nunca tinha linha própria.');
+  END LOOP;
+END $$;

package/migrations/165_unit_address_geocoding.sql

@@ -0,0 +1,258 @@
+-- Unit coordinates must follow the address they describe. Queue an asynchronous
+-- geocode only when the normalized, location-bearing fields actually change.
+-- Saving remains available if the provider or pg_net is temporarily offline.
+
+CREATE OR REPLACE FUNCTION app.unit_address_geocode_fingerprint(
+  p_street text,
+  p_number text,
+  p_district text,
+  p_city text,
+  p_state text,
+  p_postal_code text,
+  p_country text
+) RETURNS text
+LANGUAGE sql
+IMMUTABLE
+SET search_path = ''
+AS $$
+  SELECT md5(concat_ws('|',
+    lower(regexp_replace(btrim(coalesce(p_street, '')), '\s+', ' ', 'g')),
+    lower(regexp_replace(btrim(coalesce(p_number, '')), '\s+', ' ', 'g')),
+    lower(regexp_replace(btrim(coalesce(p_district, '')), '\s+', ' ', 'g')),
+    lower(regexp_replace(btrim(coalesce(p_city, '')), '\s+', ' ', 'g')),
+    upper(regexp_replace(btrim(coalesce(p_state, '')), '\s+', ' ', 'g')),
+    regexp_replace(coalesce(p_postal_code, ''), '\D', '', 'g'),
+    upper(btrim(coalesce(p_country, 'BR')))
+  ));
+$$;
+
+REVOKE ALL ON FUNCTION app.unit_address_geocode_fingerprint(text, text, text, text, text, text, text) FROM PUBLIC;
+
+CREATE OR REPLACE FUNCTION app.trg_queue_unit_address_geocode() RETURNS trigger
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = ''
+AS $$
+DECLARE
+  v_fingerprint text;
+  v_old_fingerprint text;
+  v_request_id bigint;
+  v_coordinates_supplied boolean;
+BEGIN
+  IF NEW.owner_type <> 'unit' THEN
+    RETURN NEW;
+  END IF;
+
+  v_fingerprint := app.unit_address_geocode_fingerprint(
+    NEW.street, NEW.number, NEW.district, NEW.city, NEW.state,
+    NEW.postal_code, NEW.country
+  );
+
+  IF TG_OP = 'UPDATE' THEN
+    v_old_fingerprint := app.unit_address_geocode_fingerprint(
+      OLD.street, OLD.number, OLD.district, OLD.city, OLD.state,
+      OLD.postal_code, OLD.country
+    );
+    IF v_fingerprint = v_old_fingerprint THEN
+      RETURN NEW;
+    END IF;
+  END IF;
+
+  -- A coordinate pair edited alongside the address is an explicit answer and
+  -- wins over automatic geocoding. An unchanged old pair does not: it points
+  -- to the previous address and must be invalidated before the async lookup.
+  v_coordinates_supplied := NEW.latitude IS NOT NULL AND NEW.longitude IS NOT NULL
+    AND (TG_OP = 'INSERT'
+      OR NEW.latitude IS DISTINCT FROM OLD.latitude
+      OR NEW.longitude IS DISTINCT FROM OLD.longitude);
+
+  IF v_coordinates_supplied THEN
+    NEW.metadata := jsonb_set(
+      coalesce(NEW.metadata, '{}'::jsonb),
+      '{geocode}',
+      jsonb_build_object(
+        'status', 'manual',
+        'fingerprint', v_fingerprint,
+        'updated_at', now()
+      ),
+      true
+    );
+    RETURN NEW;
+  END IF;
+
+  NEW.latitude := NULL;
+  NEW.longitude := NULL;
+  IF to_regprocedure('net.http_get(text,jsonb,jsonb,integer)') IS NULL THEN
+    NEW.metadata := jsonb_set(
+      coalesce(NEW.metadata, '{}'::jsonb), '{geocode}',
+      jsonb_build_object('status', 'unconfigured', 'fingerprint', v_fingerprint, 'updated_at', now()), true
+    );
+    RETURN NEW;
+  END IF;
+
+  BEGIN
+    v_request_id := net.http_get(
+      url := 'https://nominatim.openstreetmap.org/search',
+      params := jsonb_strip_nulls(jsonb_build_object(
+        'format', 'jsonv2',
+        'limit', '1',
+        'street', concat_ws(' ', NEW.number, NEW.street),
+        'city', NEW.city,
+        'state', NEW.state,
+        'postalcode', NEW.postal_code,
+        'country', coalesce(nullif(NEW.country, ''), 'BR'),
+        'countrycodes', CASE WHEN coalesce(NEW.country, 'BR') ~* '^[a-z]{2}$'
+                             THEN lower(coalesce(NEW.country, 'BR')) END,
+        'email', 'support@fayz.ai'
+      )),
+      headers := jsonb_build_object(
+        'Accept', 'application/json',
+        'User-Agent', 'Fayz/1.0 (support@fayz.ai)',
+        'Referer', 'https://fayz.ai/'
+      )
+    );
+  EXCEPTION WHEN OTHERS THEN
+    v_request_id := NULL;
+  END;
+
+  NEW.metadata := jsonb_set(
+    coalesce(NEW.metadata, '{}'::jsonb),
+    '{geocode}',
+    jsonb_build_object(
+      'status', CASE WHEN v_request_id IS NULL THEN 'delivery_failed' ELSE 'pending' END,
+      'fingerprint', v_fingerprint,
+      'request_id', v_request_id,
+      'requested_at', now()
+    ),
+    true
+  );
+
+  RETURN NEW;
+END;
+$$;
+
+REVOKE ALL ON FUNCTION app.trg_queue_unit_address_geocode() FROM PUBLIC;
+
+DROP TRIGGER IF EXISTS queue_unit_address_geocode ON public.addresses;
+CREATE TRIGGER queue_unit_address_geocode
+  BEFORE INSERT OR UPDATE OF street, number, district, city, state, postal_code,
+    country, latitude, longitude
+  ON public.addresses
+  FOR EACH ROW
+  EXECUTE FUNCTION app.trg_queue_unit_address_geocode();
+
+COMMENT ON FUNCTION app.trg_queue_unit_address_geocode() IS
+  'Invalidates stale unit coordinates and asynchronously requests geocoding when the normalized address changes.';
+
+CREATE OR REPLACE FUNCTION app.process_unit_address_geocodes(p_limit integer DEFAULT 100)
+RETURNS integer
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = ''
+AS $$
+DECLARE
+  v_row record;
+  v_body jsonb;
+  v_hit jsonb;
+  v_lat numeric;
+  v_lng numeric;
+  v_processed integer := 0;
+  v_status text;
+BEGIN
+  FOR v_row IN
+    SELECT a.id,
+           a.metadata,
+           a.metadata #>> '{geocode,fingerprint}' AS fingerprint,
+           r.status_code,
+           r.error_msg,
+           r.content
+      FROM public.addresses a
+      JOIN net._http_response r
+        ON r.id = CASE
+          WHEN a.metadata #>> '{geocode,request_id}' ~ '^[0-9]+$'
+          THEN (a.metadata #>> '{geocode,request_id}')::bigint
+        END
+     WHERE a.owner_type = 'unit'
+       AND a.metadata #>> '{geocode,status}' = 'pending'
+       AND a.metadata #>> '{geocode,request_id}' ~ '^[0-9]+$'
+     ORDER BY r.created
+     LIMIT greatest(1, least(coalesce(p_limit, 100), 500))
+     FOR UPDATE OF a SKIP LOCKED
+  LOOP
+    v_status := 'failed';
+    v_lat := NULL;
+    v_lng := NULL;
+
+    IF v_row.status_code = 200 THEN
+      BEGIN
+        v_body := v_row.content::jsonb;
+        IF jsonb_typeof(v_body) = 'array' AND jsonb_array_length(v_body) > 0 THEN
+          v_hit := v_body -> 0;
+          IF v_hit ->> 'lat' ~ '^-?[0-9]+(\.[0-9]+)?$'
+             AND v_hit ->> 'lon' ~ '^-?[0-9]+(\.[0-9]+)?$' THEN
+            v_lat := (v_hit ->> 'lat')::numeric;
+            v_lng := (v_hit ->> 'lon')::numeric;
+            IF v_lat BETWEEN -90 AND 90 AND v_lng BETWEEN -180 AND 180 THEN
+              v_status := 'resolved';
+            END IF;
+          ELSE
+            v_status := 'not_found';
+          END IF;
+        ELSE
+          v_status := 'not_found';
+        END IF;
+      EXCEPTION WHEN OTHERS THEN
+        v_status := 'failed';
+      END;
+    END IF;
+
+    UPDATE public.addresses a
+       SET latitude = CASE WHEN v_status = 'resolved' THEN v_lat ELSE NULL END,
+           longitude = CASE WHEN v_status = 'resolved' THEN v_lng ELSE NULL END,
+           metadata = jsonb_set(
+             coalesce(a.metadata, '{}'::jsonb),
+             '{geocode}',
+             jsonb_strip_nulls(jsonb_build_object(
+               'status', v_status,
+               'fingerprint', v_row.fingerprint,
+               'source', CASE WHEN v_status = 'resolved' THEN 'nominatim_openstreetmap' END,
+               'precision', CASE WHEN v_status = 'resolved'
+                                 THEN coalesce(v_hit ->> 'addresstype', v_hit ->> 'type') END,
+               'updated_at', now()
+             )),
+             true
+           )
+     WHERE a.id = v_row.id
+       AND a.metadata #>> '{geocode,fingerprint}' = v_row.fingerprint;
+
+    v_processed := v_processed + 1;
+  END LOOP;
+
+  RETURN v_processed;
+END;
+$$;
+
+REVOKE ALL ON FUNCTION app.process_unit_address_geocodes(integer) FROM PUBLIC;
+
+COMMENT ON FUNCTION app.process_unit_address_geocodes(integer) IS
+  'Consumes completed pg_net geocoding responses and writes coordinates only while the address fingerprint still matches.';
+
+DO $$
+DECLARE
+  v_job_id bigint;
+BEGIN
+  IF to_regnamespace('cron') IS NULL THEN RETURN; END IF;
+
+  FOR v_job_id IN SELECT jobid FROM cron.job WHERE jobname = 'fayz-unit-address-geocode' LOOP
+    PERFORM cron.unschedule(v_job_id);
+  END LOOP;
+
+  PERFORM cron.schedule(
+    'fayz-unit-address-geocode',
+    '10 seconds',
+    'SELECT app.process_unit_address_geocodes()'
+  );
+EXCEPTION WHEN OTHERS THEN
+  RAISE WARNING 'unit address geocoding scheduler was not installed: %', SQLERRM;
+END;
+$$;

package/package.json

@@ -3,7 +3,7 @@
   "fayz": {
     "status": "beta"
   },
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Fayz SDK database layer — Drizzle schema primitives, spine references, and migration helpers shared across plugins.",
   "type": "module",
   "sideEffects": false,