@polymorphism-tech/morph-spec 8.28.0 → 8.31.0

package/framework/skills/core/create-umbraco-lp/references/umbraco-lp-patterns.md

@@ -0,0 +1,598 @@
+# Umbraco 17 / .NET 10 + Next.js: Padrões e Gotchas do Sistema de Leads (Frente 4)
+
+> **Origem:** documentado a partir do código real em `MORPH_Umbraco_LP_Template` (template canônico) e validado contra `Gardim_LP_Umbraco` (implementação de referência).
+> **Natureza:** referência consultável para devs adaptando o template para novos clientes — não é um skill executável. A lógica vive no template repo; este doc é o mapa dos padrões e armadilhas.
+> **Convenção de citação:** cada padrão cita o **arquivo real** no `MORPH_Umbraco_LP_Template`. Símbolos (método/classe/alias) são âncoras estáveis; números de linha, quando aparecem, são auxiliares e podem deslizar entre versões.
+
+---
+
+## Sumário de Seções
+
+1. [Controller público no Umbraco v14+/v17](#1-controller-público-no-umbraco-v14v17)
+2. [DI via IComposer + estratégia multi-sink](#2-di-via-icomposer--estratégia-multi-sink)
+3. [Leitura de conteúdo publicado server-side](#3-leitura-de-conteúdo-publicado-server-side)
+4. [Segurança da Delivery API — DisallowedContentTypeAliases](#4-segurança-da-delivery-api--disallowedcontenttypealiases)
+5. [uSync como config-as-code](#5-usync-como-config-as-code)
+6. [GOTCHA: Dropdown Flexível armazena JSON array](#6-gotcha-dropdown-flexível-armazena-json-array)
+7. [Seeding de conteúdo programático e idempotente](#7-seeding-de-conteúdo-programático-e-idempotente)
+8. [Implicit usings: o que é grátis e o que falta](#8-implicit-usings-o-que-é-grátis-e-o-que-falta)
+9. [Frontend thin-proxy (Next.js route handler)](#9-frontend-thin-proxy-nextjs-route-handler)
+10. [Endpoint Ping — validação sem vazar segredos](#10-endpoint-ping--validação-sem-vazar-segredos)
+11. [Padrão de sink: skip silencioso em dev/staging](#11-padrão-de-sink-skip-silencioso-em-devstaging)
+12. [Build do Next.js exige backend acessível](#12-build-do-nextjs-exige-backend-acessível)
+
+---
+
+## 1. Controller público no Umbraco v14+/v17
+
+### O que / por quê
+
+`UmbracoApiController` (base de controllers públicos no Umbraco 13 e anteriores) foi removido no v14. O controller de leads é um `ControllerBase` puro do ASP.NET Core, com roteamento por atributo (`[ApiController]` + `[Route]`) — sem nenhuma herança de tipo Umbraco.
+
+### Como
+
+```csharp
+// backend/Controllers/LeadController.cs
+[ApiController]
+[Route("/api/leads")]
+public sealed class LeadController : ControllerBase
+{
+    // nenhuma herança Umbraco — só DI de serviços Umbraco no construtor
+}
+```
+
+O construtor recebe dependências Umbraco por DI (`IUmbracoContextFactory`, `IDocumentNavigationQueryService`) ao lado de serviços ASP.NET padrão (`IHostEnvironment`, `ILogger<T>`) e a coleção de sinks (`IEnumerable<ILeadSink>`).
+
+**Nota de mecanismo (verificado vs. inferido):** o pipeline em `backend/Program.cs` usa `.AddBackOffice().AddWebsite().AddDeliveryApi().AddComposers()` e, no middleware, `WithEndpoints(u => { u.UseBackOfficeEndpoints(); u.UseWebsiteEndpoints(); })`. Não há `MapControllers()` explícito; o controller é descoberto pelo pipeline MVC que o Umbraco habilita. O que é certo afirmar: `.AddComposers()` é o que registra o `IComposer` (ver seção 2) — ele **não** é "o registrador do controller". Evite afirmar o mecanismo exato de descoberta do controller além disso.
+
+**Arquivos:** `backend/Controllers/LeadController.cs` (atributos e construtor); `backend/Program.cs` (pipeline).
+
+---
+
+## 2. DI via IComposer + estratégia multi-sink
+
+### O que / por quê
+
+O ponto de extensão para registrar serviços no DI do Umbraco é `IComposer` (namespace `Umbraco.Cms.Core.Composing`). Ele recebe um `IUmbracoBuilder` que expõe `builder.Services` — o `IServiceCollection` padrão do ASP.NET Core.
+
+Para despachar o lead à integração certa (GHL, prospectPRO ou webhook genérico) sem um `switch` no controller, o template usa **strategy pattern via `IEnumerable<ILeadSink>`**: cada implementação é registrada como singleton do mesmo serviço `ILeadSink`, e o controller seleciona pelo `Key`.
+
+### Como
+
+```csharp
+// backend/Lead/ILeadSink.cs
+public interface ILeadSink
+{
+    string Key { get; } // "ghl" | "prospectpro" | "webhook"
+    Task<LeadSendResult> SendAsync(LeadInput input, LeadsConfig cfg, CancellationToken ct);
+}
+
+// backend/Lead/LeadComposer.cs
+public sealed class LeadComposer : IComposer
+{
+    public void Compose(IUmbracoBuilder builder)
+    {
+        builder.Services.AddSingleton<ILeadSink, GhlLeadSink>();
+        builder.Services.AddSingleton<ILeadSink, ProspectProLeadSink>();
+        builder.Services.AddSingleton<ILeadSink, WebhookLeadSink>();
+    }
+}
+
+// backend/Controllers/LeadController.cs (dispatch, dentro de Submit)
+var sink = _sinks.FirstOrDefault(s => s.Key == cfg.Integration);
+```
+
+O ASP.NET Core DI injeta `IEnumerable<ILeadSink>` automaticamente quando há múltiplas implementações do mesmo serviço. Adicionar uma quarta integração = nova classe `ILeadSink` + uma linha no `Compose`. O `Key` de cada sink é uma propriedade fixa (`"ghl"`, `"prospectpro"`, `"webhook"`) que deve casar com os valores do dropdown `leadIntegration` (seção 5/6).
+
+**Arquivos:** `backend/Lead/LeadComposer.cs`; `backend/Lead/ILeadSink.cs`; `backend/Controllers/LeadController.cs` (construtor `IEnumerable<ILeadSink> sinks` + dispatch em `Submit`); sinks em `backend/Lead/GhlLeadSink.cs`, `backend/Lead/ProspectProLeadSink.cs`, `backend/Lead/WebhookLeadSink.cs`.
+
+---
+
+## 3. Leitura de conteúdo publicado server-side
+
+### O que / por quê
+
+O controller precisa ler o node `leadsConfig` (que contém tokens de integração) do cache publicado — sem passar pela Delivery API pública, que exclui esse tipo (seção 4). O padrão usado em `ReadConfig()`:
+
+1. Abrir um contexto Umbraco com `using var cref = _umbracoContextFactory.EnsureUmbracoContext();` (a forma exata usada no código).
+2. Pegar o cache de conteúdo via `cref.UmbracoContext.Content`.
+3. Navegar pelas raízes com `IDocumentNavigationQueryService.TryGetRootKeys(out IEnumerable<Guid> rootKeys)`.
+4. Resolver cada raiz com `content.GetById(k)`, filtrar nulos com `.WhereNotNull()` e selecionar pelo `ContentType.Alias`.
+5. Ler valores tipados via `node.Value<T>(alias)` (extension de `Umbraco.Extensions`).
+
+### Como
+
+```csharp
+// backend/Controllers/LeadController.cs — método ReadConfig()
+private LeadsConfig? ReadConfig()
+{
+    using var cref = _umbracoContextFactory.EnsureUmbracoContext();
+    IPublishedContentCache? content = cref.UmbracoContext.Content;
+    if (content is null || !_navigationQueryService.TryGetRootKeys(out IEnumerable<Guid> rootKeys))
+        return null;
+
+    IPublishedContent? node = rootKeys
+        .Select(k => content.GetById(k))
+        .WhereNotNull()
+        .FirstOrDefault(c => c.ContentType.Alias == ConfigAlias); // ConfigAlias = "leadsConfig"
+
+    if (node is null) return null;
+
+    return new LeadsConfig
+    {
+        Integration   = (node.Value<string>("leadIntegration") ?? "none").Trim(),
+        NodeKey       = node.Key,
+        GhlToken      = (node.Value<string>("ghlApiToken")      ?? string.Empty).Trim(),
+        // ... demais campos GHL / prospectPRO / webhook
+    };
+}
+```
+
+**Nota de tipo (`UmbracoContextReference`):** use `using var cref = _umbracoContextFactory.EnsureUmbracoContext();` — a forma usada no código — e acesse `cref.UmbracoContext.Content`. O `var` infere o tipo correto sem você precisar nomeá-lo; é a forma idiomática e a que está no template.
+
+**Usings que o código importa explicitamente** (não cobertos pelos implicit usings — ver seção 8):
+```csharp
+using Umbraco.Cms.Core.Models.PublishedContent; // IPublishedContent
+using Umbraco.Cms.Core.PublishedCache;          // IPublishedContentCache
+using Umbraco.Cms.Core.Services.Navigation;     // IDocumentNavigationQueryService
+using Umbraco.Cms.Core.Web;                      // IUmbracoContextFactory
+using Umbraco.Extensions;                        // node.Value<T>() / .WhereNotNull()
+```
+
+**Arquivos:** `backend/Controllers/LeadController.cs` (método `ReadConfig` + bloco de usings no topo).
+
+---
+
+## 4. Segurança da Delivery API — DisallowedContentTypeAliases
+
+### O que / por quê
+
+A Delivery API do Umbraco exclui por **content type inteiro**, não por propriedade. A chave `DisallowedContentTypeAliases` remove um tipo da superfície pública. O template usa isso para esconder `leadsConfig` (que guarda tokens) da API pública, lendo-o só server-side pelo cache publicado (seção 3).
+
+### Como
+
+```jsonc
+// backend/appsettings.json — caminho COMPLETO da chave: Umbraco:CMS:DeliveryApi
+{
+  "Umbraco": {
+    "CMS": {
+      "DeliveryApi": {
+        "Enabled": true,
+        "PublicAccess": true,
+        "RichTextOutputAsMarkdown": false,
+        "ApiKey": "",
+        "DisallowedContentTypeAliases": [ "leadsConfig" ]
+      }
+    }
+  }
+}
+```
+
+> Atenção ao aninhamento: a chave fica sob `Umbraco:CMS:DeliveryApi`, não em um bloco `DeliveryApi` de topo. Mesma regra para `uSync` (seção 5), que **é** de topo — não confunda os dois.
+
+O `ContentType` `leadsConfig` é declarado com `AllowAtRoot=True` e descrição explícita de que não é exposto na Delivery API (ver o `.config`). O controller lê o node normalmente pelo published cache (seção 3); o frontend nunca recebe o node nem os tokens.
+
+**Arquivos:** `backend/appsettings.json` (`Umbraco:CMS:DeliveryApi:DisallowedContentTypeAliases`); `backend/uSync/v17/ContentTypes/leadsConfig.config` (a `<Description>` documenta a intenção: "NÃO é exposto na Delivery API pública — tokens ficam seguros e são lidos só server-side pelo LeadController").
+
+---
+
+## 5. uSync como config-as-code
+
+### O que / por quê
+
+uSync sincroniza DataTypes, ContentTypes, MediaTypes e Languages via arquivos versionados (`.config`, formato XML) em `backend/uSync/v17/`. `ImportAtStartup: "All"` reimporta o schema a cada boot — idempotente e replicável em ambientes limpos.
+
+### Como
+
+```jsonc
+// backend/appsettings.json — bloco uSync é de TOPO (não sob Umbraco:CMS)
+{
+  "uSync": {
+    "Sets": {
+      "Default": {
+        "DisabledHandlers": [ "MemberTypeHandler", "MacroHandler" ]
+      }
+    },
+    "Settings": {
+      "UIEnabledGroups": "Settings",
+      "ExportOnSave": "Settings",
+      "ImportAtStartup": "All",
+      "ExportAtStartup": "None",
+      "BackgroundStartup": true
+    }
+  }
+}
+```
+
+> O template **já desabilita** `MemberTypeHandler` e `MacroHandler` (em `Sets:Default:DisabledHandlers`) — handlers sem uso numa LP simples, evitando ruído no import. Não é um "pode-se desabilitar"; está feito.
+
+**Formato do DataType dropdown** (`backend/uSync/v17/DataTypes/LeadIntegrationDropdown.config`):
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<DataType Key="a3000001-0000-0000-0000-000000000001" Alias="Lead Integration" Level="1">
+  <Info>
+    <Name>Lead Integration</Name>
+    <EditorAlias>Umbraco.DropDown.Flexible</EditorAlias>
+    <DatabaseType>Nvarchar</DatabaseType>
+  </Info>
+  <Config><![CDATA[{
+  "Items": [
+    {"id": 1, "value": "none"},
+    {"id": 2, "value": "ghl"},
+    {"id": 3, "value": "prospectpro"},
+    {"id": 4, "value": "webhook"}
+  ],
+  "Multiple": false
+}]]></Config>
+</DataType>
+```
+
+**Regras do formato:**
+- `Items` é array de `{id: number, value: string}` — **sem campo `label` separado** nesta versão do editor; o `value` é o que aparece e o que é salvo.
+- `Multiple: false` → single-select (mas ainda persiste como JSON array — ver seção 6).
+- O `Config` vai dentro de `<![CDATA[ ... ]]>` e é **JSON**, não XML.
+- `Key` (GUID) e `Alias` são únicos no repositório. Use GUIDs fixos para que o import seja idempotente e replicável entre ambientes.
+
+**Arquivos:** `backend/appsettings.json` (blocos `uSync:Sets` e `uSync:Settings`); `backend/uSync/v17/DataTypes/LeadIntegrationDropdown.config`; `backend/uSync/v17/ContentTypes/leadsConfig.config`.
+
+---
+
+## 6. GOTCHA: Dropdown Flexível armazena JSON array
+
+### O que / por quê
+
+`Umbraco.DropDown.Flexible` persiste o valor como **JSON array**, mesmo com `Multiple: false`. Ou seja, `"ghl"` deve ser gravado como `["ghl"]`.
+
+O template já faz assim: o `SeedContentHandler`, ao gravar `leadIntegration`, **serializa explicitamente como array de um elemento** em vez da string crua. Isso não é preferência de estilo, é o formato que o property value converter exige na leitura. Verificado em campo: com a string crua gravada, o `FlexibleDropdownPropertyValueConverter` lança `JsonException: 'a' is an invalid start of a value` na primeira leitura, e o documento inteiro passa a devolver 500 na Delivery API.
+
+### Fix (escrita)
+
+```csharp
+// backend/Infrastructure/SeedContentHandler.cs — EnsureLeadsConfigNode()
+var leadIntegration = Environment.GetEnvironmentVariable("LEADS_INTEGRATION") ?? "none";
+node.SetValue("leadIntegration", System.Text.Json.JsonSerializer.Serialize(new[] { leadIntegration }));
+// Grava no banco: ["none"] (ou ["ghl"] etc.) — formato JSON array que o converter espera.
+```
+
+### Leitura
+
+```csharp
+// backend/Controllers/LeadController.cs — ReadConfig()
+Integration = (node.Value<string>("leadIntegration") ?? "none").Trim();
+// Com Multiple:false, Value<string>() devolve a string desembrulhada ("ghl"), não o array.
+```
+
+**Regra mnemônica:** escreva com `JsonSerializer.Serialize(new[]{ value })`, leia com `Value<string>()`. O Umbraco faz o wrap/unwrap — desde que o valor escrito esteja no formato JSON array.
+
+### O caso que mais escapa: dropdown dentro de Block List
+
+A regra acima é fácil de lembrar quando existe um `SetValue` para escrever. Dentro de um Block List não existe: o bloco é montado como **JSON literal** no seed, e aí a tentação é escrever o valor como string, que é o que qualquer outro campo do bloco usa.
+
+```jsonc
+// errado — o backoffice aceita, a leitura estoura
+"beat1CtaAcao": "ancora",
+
+// certo — array JSON, igual ao que SetValue produziria
+"beat1CtaAcao": ["ancora"],
+```
+
+**O estrago não fica no campo.** O converter roda ao montar o elemento do bloco, então a exceção sobe pelo `BlockListPropertyValueConverter` e **derruba o documento inteiro**: a Delivery API devolve **500 na home**, não um campo vazio. E como o `next build` faz SSG consultando a Delivery API, o build do frontend morre junto, reportando apenas `npm run build ... exit code 1`. O sintoma que chega ao dev ("o projeto não sobe do zero", "o build quebrou no Docker") está a três camadas da linha errada.
+
+Isso só aparece com **banco novo**. Um ambiente que já rodava continua funcionando, porque o valor foi gravado antes ou corrigido por uma edição no backoffice, que sempre grava no formato certo. Ou seja: passa despercebido até o primeiro `--reset-db`, o primeiro deploy limpo ou o primeiro colega clonando o projeto.
+
+### Diagnóstico
+
+O `JsonException` informa o **primeiro caractere** do valor ofensor, e isso basta para achá-lo:
+
+1. Ler o stack no log (`umbraco/Logs/*.json`, campo `@x`): anotar o converter que falhou e o caractere citado (`'a' is an invalid start of a value`).
+2. Isolar o documento: `GET /umbraco/delivery/api/v2/content?filter=contentType:<alias>`, um tipo por vez, até achar o que devolve 500.
+3. Listar o que exige array: `grep -rn "<Type>Umbraco.DropDown.Flexible</Type>" backend/uSync/v17/ContentTypes/` e conferir como cada propriedade é seedada.
+4. Confirmar por A/B: corrigir uma e re-seedar com banco limpo. Se o caractere do erro **mudar**, aquela foi resolvida e existe outra; se o 500 sumir, acabou.
+
+**Arquivos:** `backend/Infrastructure/SeedContentHandler.cs` (`EnsureLeadsConfigNode`, a chamada `SetValue("leadIntegration", JsonSerializer.Serialize(new[]{ leadIntegration }))`); `backend/Controllers/LeadController.cs` (`ReadConfig`, leitura de `leadIntegration` com `Value<string>()`).
+
+---
+
+## 7. Seeding de conteúdo programático e idempotente
+
+### O que / por quê
+
+O `SeedContentHandler` implementa `INotificationAsyncHandler<uSyncImportCompletedNotification>` — dispara depois que o uSync terminou de importar o schema (DataTypes + ContentTypes), garantindo que os tipos existem antes de criar nodes. É registrado em `Program.cs`.
+
+Idempotência: cada `Ensure...` guarda contra duplicata com filtro **por content type alias** sobre as root content — não uma query genérica sem filtro (que poderia pegar o node errado).
+
+```csharp
+// backend/Infrastructure/SeedContentHandler.cs
+
+// guarda da home (HandleAsync) — filtra por "empreendimentoHome"
+var existing = _contentService.GetRootContent()
+    .FirstOrDefault(c => c.ContentType.Alias == "empreendimentoHome");
+
+// guarda do config (EnsureLeadsConfigNode) — filtra por "leadsConfig"
+var existing = _contentService.GetRootContent()
+    .FirstOrDefault(c => c.ContentType.Alias == "leadsConfig");
+```
+
+> Note que são **duas guardas distintas, por alias diferente**: `empreendimentoHome` para a home, `leadsConfig` para o node de config. Filtrar por alias evita pegar o primeiro root node por acaso.
+
+### Registro e publicação
+
+```csharp
+// backend/Program.cs — no pipeline do CreateUmbracoBuilder
+.AddNotificationAsyncHandler<uSyncImportCompletedNotification,
+    MORPH.Backend.Infrastructure.SeedContentHandler>()
+
+// backend/Infrastructure/SeedContentHandler.cs — publicação (home e config)
+_contentService.Publish(content, Array.Empty<string>());
+// Array.Empty<string>() é a forma usada no código: publicação invariant (sem culturas).
+```
+
+**Variáveis de ambiente** para personalizar sem alterar código:
+```csharp
+var projectName     = Environment.GetEnvironmentVariable("PROJECT_NAME")    ?? "Meu Empreendimento";
+var leadIntegration = Environment.GetEnvironmentVariable("LEADS_INTEGRATION") ?? "none";
+var isSeedDemo      = string.Equals(Environment.GetEnvironmentVariable("SEED_DEMO_CONTENT"), "true",
+                          StringComparison.OrdinalIgnoreCase); // popula módulos demo
+```
+
+**Tokens e segredos NÃO são semeados** — ficam em branco para o editor preencher no backoffice. Isso é intencional (comentário explícito no código: "Template genérico: NÃO semear tokens/ids — ficam em branco pro editor preencher no backoffice").
+
+**Arquivos:** `backend/Infrastructure/SeedContentHandler.cs` (handler inteiro: `HandleAsync`, `EnsureLeadsConfigNode`, `PopulateDemoModules`); `backend/Program.cs` (`AddNotificationAsyncHandler<...>`).
+
+---
+
+## 8. Implicit usings: o que é grátis e o que falta
+
+### O que / por quê
+
+O projeto liga `<ImplicitUsings>enable</ImplicitUsings>` (`backend/MORPH.Backend.csproj`) sobre o `Microsoft.NET.Sdk.Web`. Isso gera um conjunto de `global using` automático. **Não confie na memória** sobre o que está incluído — o arquivo gerado é a fonte da verdade: `backend/obj/Debug/net10.0/MORPH.Backend.GlobalUsings.g.cs`.
+
+### O que JÁ é implicit (não precisa importar)
+
+Verbatim do `GlobalUsings.g.cs` gerado:
+
+| Namespace implicit | Cobre |
+|---|---|
+| `Microsoft.Extensions.Logging` | `ILogger<T>`, `ILoggerFactory` |
+| `Microsoft.Extensions.Hosting` | `IHostEnvironment`, `.IsDevelopment()` |
+| `Microsoft.Extensions.DependencyInjection` | `IServiceCollection`, `AddSingleton<>` |
+| `Microsoft.Extensions.Configuration` | `IConfiguration` |
+| `Umbraco.Cms.Core.DependencyInjection` | `IUmbracoBuilder` |
+| `Umbraco.Extensions` | `node.Value<T>()`, `.WhereNotNull()` |
+| `System.Linq`, `System.Net.Http`, `System.Threading.Tasks`, etc. | LINQ, HttpClient, Task |
+
+> Prova empírica: `backend/Lead/GhlLeadSink.cs` usa `ILogger<GhlLeadSink>?` **sem** importar `Microsoft.Extensions.Logging` e compila — porque o namespace é implicit. (Os arquivos `WebhookLeadSink.cs`/`ProspectProLeadSink.cs` repetem o `using Microsoft.Extensions.Logging;` por hábito; é redundante, não obrigatório.)
+
+### O que NÃO é implicit (precisa importar)
+
+Os namespaces **Umbraco** abaixo não estão no conjunto implicit e geram `CS0246` se faltarem. São exatamente os que `LeadController.cs` / `LeadComposer.cs` importam à mão:
+
+| Tipo | Using necessário |
+|---|---|
+| `IPublishedContent` | `using Umbraco.Cms.Core.Models.PublishedContent;` |
+| `IPublishedContentCache` | `using Umbraco.Cms.Core.PublishedCache;` |
+| `IDocumentNavigationQueryService` | `using Umbraco.Cms.Core.Services.Navigation;` |
+| `IUmbracoContextFactory` | `using Umbraco.Cms.Core.Web;` |
+| `IComposer` | `using Umbraco.Cms.Core.Composing;` |
+
+> Atenção ao par: `IUmbracoBuilder` é implicit (`Umbraco.Cms.Core.DependencyInjection`), mas `IComposer` **não** é (`Umbraco.Cms.Core.Composing`). Ao escrever um novo `IComposer`, você precisa de ambos os usings (um implicit, um explícito), como em `LeadComposer.cs`.
+
+**Dica de diagnóstico:** antes de adicionar usings por tentativa-e-erro, abra `backend/obj/Debug/net10.0/MORPH.Backend.GlobalUsings.g.cs` e confira o que já está lá. É o jeito determinístico de saber.
+
+**Arquivos:** `backend/MORPH.Backend.csproj` (`<ImplicitUsings>enable</ImplicitUsings>`); `backend/obj/Debug/net10.0/MORPH.Backend.GlobalUsings.g.cs` (lista gerada — fonte da verdade); `backend/Controllers/LeadController.cs` e `backend/Lead/LeadComposer.cs` (usings explícitos Umbraco); `backend/Lead/GhlLeadSink.cs` (prova de que `Microsoft.Extensions.Logging` é implicit).
+
+---
+
+## 9. Frontend thin-proxy (Next.js route handler)
+
+### O que / por quê
+
+A LP Next.js **não** implementa lógica de integração. O route handler só faz proxy do POST do formulário para o backend Umbraco. Motivos:
+- Tokens de integração ficam no backend Umbraco (server-side, ocultos da Delivery API — seção 4).
+- Evita CORS browser → Umbraco: o form posta same-origin para `/api/leads` (Next.js), que repassa para o Umbraco.
+
+### Como
+
+```typescript
+// frontend/src/app/api/leads/route.ts
+const BACKEND = (
+  process.env.UMBRACO_INTERNAL_URL ||   // container-to-container (ex.: http://backend:19223)
+  process.env.NEXT_PUBLIC_UMBRACO_URL || // fallback
+  'http://localhost:19223'
+).replace(/\/+$/, '')
+
+export async function POST(request: NextRequest): Promise<NextResponse> {
+  const raw = await request.text()
+  try {
+    const res = await fetch(`${BACKEND}/api/leads`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+      body: raw || '{}',
+      cache: 'no-store',
+    })
+    const text = await res.text()
+    return new NextResponse(text || '{"ok":false}', {
+      status: res.status,
+      headers: { 'Content-Type': 'application/json' },
+    })
+  } catch (err) {
+    console.error('[leads proxy] backend inalcançável:', err instanceof Error ? err.message : err)
+    return NextResponse.json({ ok: false, error: 'backend_unreachable' }, { status: 502 })
+  }
+}
+```
+
+**Variáveis de ambiente:**
+- `UMBRACO_INTERNAL_URL` — URL interna container-to-container (não exposta ao browser). Preferida.
+- `NEXT_PUBLIC_UMBRACO_URL` — URL pública do Umbraco (também usada pelo `umbraco-client.ts` para a Delivery API).
+
+O proxy repassa o body cru (`raw`) sem reinterpretar. Honeypot (`hp`), validação (nome/telefone/consent) e dispatch acontecem **no controller Umbraco**, não no proxy. O controller trata honeypot devolvendo `200 { ok: true }` sem processar quando `hp` não está vazio.
+
+**Arquivos:** `frontend/src/app/api/leads/route.ts` (handler inteiro).
+
+---
+
+## 10. Endpoint Ping — validação sem vazar segredos
+
+### O que / por quê
+
+`GET /api/leads` (método `Ping`) devolve só `{ ok, service }` em produção e diagnóstico ampliado em Development. Permite validar a config em CI/deploy sem nunca expor tokens ou URLs de integração.
+
+### Como
+
+```csharp
+// backend/Controllers/LeadController.cs — Ping()
+[HttpGet]
+public IActionResult Ping()
+{
+    if (!_env.IsDevelopment())
+        return Ok(new { ok = true, service = "leads" });
+
+    var cfg = ReadConfig();
+    bool ready = cfg?.Integration switch
+    {
+        "ghl"         => !string.IsNullOrWhiteSpace(cfg.GhlToken),
+        "prospectpro" => !string.IsNullOrWhiteSpace(cfg.PpApiUrl) && !string.IsNullOrWhiteSpace(cfg.PpApiToken),
+        "webhook"     => !string.IsNullOrWhiteSpace(cfg.WhUrl),
+        _             => false,
+    };
+    return Ok(new
+    {
+        ok          = true,
+        service     = "leads",          // presente nas DUAS respostas (prod e dev)
+        dev         = true,
+        integration = cfg?.Integration, // "ghl" | "prospectpro" | "webhook" | "none"
+        configFound = cfg is not null,
+        ready,                          // bool derivado: a integração está completa?
+        nodeId      = cfg?.NodeKey,     // GUID do node (não é segredo)
+    });
+}
+```
+
+`ready` é boolean derivado da presença dos campos — **nunca** o token em si. `nodeId` é o GUID interno (`LeadsConfig.NodeKey`), não sensível. O campo `service = "leads"` aparece em ambos os ramos (prod e dev).
+
+**Arquivos:** `backend/Controllers/LeadController.cs` (método `Ping`).
+
+---
+
+## 11. Padrão de sink: skip silencioso em dev/staging
+
+### O que / por quê
+
+Todo sink faz **early return** quando a config essencial falta, devolvendo `new LeadSendResult(true, true)` — `Ok: true, Skipped: true`. Assim a LP funciona (form dá sucesso visual) mesmo sem integração configurada — útil em dev, staging ou antes de o cliente preencher os tokens no backoffice.
+
+O controller traduz `Skipped: true` em `200 { ok: true, skipped: true }` — sem erro no form.
+
+### Como
+
+```csharp
+// LeadSendResult: backend/Lead/LeadModels.cs
+public sealed record LeadSendResult(bool Ok, bool Skipped, string? Id = null, string? Error = null);
+
+// backend/Lead/GhlLeadSink.cs — SendAsync()
+if (string.IsNullOrWhiteSpace(cfg.GhlToken))
+    return new LeadSendResult(true, true); // skip silencioso
+
+// backend/Lead/WebhookLeadSink.cs — SendAsync()
+if (string.IsNullOrWhiteSpace(cfg.WhUrl))
+    return new LeadSendResult(true, true);
+
+// backend/Lead/ProspectProLeadSink.cs — SendAsync()
+if (string.IsNullOrWhiteSpace(cfg.PpApiUrl) || string.IsNullOrWhiteSpace(cfg.PpApiToken))
+    return new LeadSendResult(true, true);
+```
+
+```csharp
+// backend/Controllers/LeadController.cs — Submit() (dispatch)
+var sink = _sinks.FirstOrDefault(s => s.Key == cfg.Integration);
+if (sink is null)
+    return Ok(new { ok = true, skipped = true }); // "none" ou integração desconhecida
+
+var r = await sink.SendAsync(body, cfg, ct);
+if (r.Skipped) return Ok(new { ok = true, skipped = true });
+return r.Ok
+    ? Ok(new { ok = true, id = r.Id })
+    : StatusCode(502, new { ok = false, error = r.Error ?? "send_failed" });
+```
+
+> Há ainda um terceiro caminho de skip: se `ReadConfig()` devolve `null` (node `leadsConfig` ausente), o controller loga warning e devolve `200 { ok: true, skipped: true }` — não bloqueia a LP.
+
+**Arquivos:** `backend/Lead/GhlLeadSink.cs`, `backend/Lead/WebhookLeadSink.cs`, `backend/Lead/ProspectProLeadSink.cs` (cada `SendAsync` com o early return); `backend/Lead/LeadModels.cs` (`LeadSendResult`); `backend/Controllers/LeadController.cs` (`Submit`, dispatch + guarda de config nula).
+
+---
+
+## 12. Build do Next.js exige backend acessível
+
+### O que / por quê
+
+`next build` chama `getHome()` (RSC) para renderizar as páginas. Se o Umbraco não estiver acessível durante o build de produção, ele **lança erro proposital** com instrução clara. Para CI sem backend, há a flag `E2E_FAKE_DATA=true` que usa a fixture.
+
+### Como
+
+```typescript
+// frontend/src/lib/umbraco-client.ts
+const UMBRACO_URL = process.env.NEXT_PUBLIC_UMBRACO_URL ?? 'http://localhost:5001'
+const API_BASE = `${UMBRACO_URL}/umbraco/delivery/api/v2`
+const USE_FAKE_DATA = process.env.E2E_FAKE_DATA === 'true'
+
+export async function getHome(): Promise<EmpreendimentoHome | null> {
+  if (USE_FAKE_DATA) return FAKE_HOME
+  try {
+    const data = await fetchApi<{ items: EmpreendimentoHome[] }>(
+      '/content?contentType=empreendimentoHome&take=1'
+    )
+    return data.items?.[0] ?? null
+  } catch (e) {
+    const message = `[umbraco-client] getHome failed at ${API_BASE}: ${...}`
+    if (process.env.NEXT_PHASE === 'phase-production-build') {
+      throw new Error(`${message}\n\nO Umbraco precisa estar acessível durante \`next build\`. Defina E2E_FAKE_DATA=true para usar fixture, ou suba o backend antes de buildar.`)
+    }
+    console.error(message)
+    return null // fora de build: degrada gracioso, página renderiza vazia
+  }
+}
+```
+
+**Opções em CI:**
+1. `E2E_FAKE_DATA=true` → usa `FAKE_HOME` de `frontend/src/lib/fake-data.ts`; não requer backend.
+2. Subir o backend Umbraco antes do `next build` → build real de produção.
+
+> Comportamento por fase: **só** em `NEXT_PHASE === 'phase-production-build'` o erro é lançado. Em runtime (request normal) a falha degrada para `null` e a página renderiza vazia em vez de quebrar.
+
+**Arquivos:** `frontend/src/lib/umbraco-client.ts` (`getHome`, `fetchApi`, `getMediaUrl`); `frontend/src/lib/fake-data.ts` (`FAKE_HOME`).
+
+---
+
+## Apêndice: fluxo do lead (end-to-end)
+
+```
+Browser form
+   │ POST /api/leads (JSON: nome, telefone, email, tipo_projeto, mensagem,
+   │                  consent, hp, utm_source, utm_medium, utm_campaign)
+   ▼
+Next.js /api/leads (frontend/src/app/api/leads/route.ts)
+   │ proxy same-origin do body cru → UMBRACO_INTERNAL_URL/api/leads
+   ▼
+LeadController.Submit (backend/Controllers/LeadController.cs)
+   │ 1. honeypot: hp preenchido → 200 { ok:true } sem processar
+   │ 2. validação: nome, telefone, consent (faltou → 422)
+   │ 3. ReadConfig() → node leadsConfig do published cache
+   │                   (oculto da Delivery API; seção 3+4)
+   │    config nula → 200 { ok:true, skipped:true }
+   │ 4. dispatch: _sinks.FirstOrDefault(s => s.Key == cfg.Integration)
+   ▼
+GhlLeadSink | ProspectProLeadSink | WebhookLeadSink (backend/Lead/*)
+   │ skip silencioso se token/URL ausente → { ok:true, skipped:true }
+   ▼
+API externa (GHL upsert / prospectPRO / webhook genérico)
+```
+
+---
+
+## Onde este doc vive no morph-spec-framework
+
+**Localização:** `framework/skills/core/create-umbraco-lp/references/umbraco-lp-patterns.md`, instalado junto com a skill em `.claude/skills/create-umbraco-lp/references/`. É referência estática carregada sob demanda, não skill executável.
+
+Justificativa: o conteúdo é consumido por humanos (devs adaptando o template para novos clientes) e potencialmente por skills futuras (ex.: um `morph-framework-infra` ou skill de setup Umbraco). Não contém lógica de execução — é mapa de padrões. Pode ser linkado do README do `MORPH_Umbraco_LP_Template`.
+
+Se o framework ganhar um skill de infraestrutura, as seções 6 (dropdown gotcha) e 3 (leitura server-side de config oculta) merecem virar notas de alerta no prompt do skill — são as armadilhas que mais custam tempo.