funifier-mcp 0.2.26 → 0.2.28

package/datasource-funifier-docs/knowledge/modules/patterns.md

@@ -1,102 +1,152 @@
-# Patterns (Design Patterns)
+# Patterns — Padrões de Implementação Funifier
+
+## 1. Visão Geral
+
+### 1.1 O que é este documento
+
+Este documento descreve patterns de implementação Funifier para apps client-side sem backend próprio: cadastro em área pública, envio de email, login social, pagamento recorrente, integração entre gamificações, isolamento de dados, conversa por voz com IA e acesso correto à API de Player e Database.
+
+### 1.2 Quando consultar
+
+- Consulte ao implementar **cadastro (signup)** de jogador em área pública sem expor `/v3/player`.
+- Consulte ao **enviar email** a partir de uma trigger com conteúdo editável pelo admin.
+- Consulte ao implementar **login com Google** num app sem backend.
+- Consulte ao criar **lead no CRM** automaticamente no signup (gamificação de produto → gamificação de CRM).
+- Consulte ao implementar **pagamento/assinatura recorrente** usando Public Endpoints como proxy para um gateway (Asaas).
+- Consulte ao implementar **conversa por voz/vídeo com IA** (OpenAI Realtime + WebRTC).
+- Consulte ao corrigir **vazamento de dados entre usuários** em apps que usam `localStorage`.
+- Consulte ao ler/escrever **datas e tipos BSON** via `/v3/database`.
+- Consulte ao descobrir que **campos do player somem ao salvar** ou que **queries retornam tudo/vazio**.
+- Consulte ao implementar **alteração ou reset de senha**.
+- Consulte ao corrigir bugs de **scope, digest ou iOS** em frontends AngularJS.
+- Consulte ao tratar **cache de browser** servindo código antigo após deploy.
+
+### 1.3 Quando NÃO consultar
+
+- **NÃO** consulte para entender como um módulo de feature funciona (achievement, challenge, leaderboard, level, lottery, etc.) — use o módulo correspondente via `index.md`.
+- **NÃO** consulte para referência de campos/métodos Java — use `guides/java-entities.md` e `guides/java-managers.md`.
+- **NÃO** consulte para a mecânica interna de triggers, public endpoints ou schedulers — use `modules/trigger.md`, `modules/public.md`, `modules/scheduler.md`. Este documento usa esses recursos; não os documenta.
+- **NÃO** consulte para queries/aggregates avançados — use `guides/aggregates.md`.
+
+### 1.4 Índice de decisão
+
+| Problema / Situação | Pattern | Seção |
+|---|---|---|
+| Cadastro em área pública sem expor `/v3/player` | Signup | §2 |
+| Email a partir de trigger, conteúdo editável pelo admin | Email Template | §3 |
+| Login com Google sem backend próprio | Google OAuth | §4 |
+| Criar lead no CRM ao cadastrar jogador (cross-gamificação) | CRM Integration | §5 |
+| Assinatura/pagamento recorrente sem backend próprio | Payment Gateway (Asaas) | §6 |
+| Conversa por voz/vídeo com IA | OpenAI Realtime | §7 |
+| Vazamento de dados entre usuários (cache `localStorage`) | Cross-User Data Isolation | §8 |
+| Datas/tipos quebrando ao ler+escrever em `/v3/database` | Database Strict Mode | §9 |
+| Campos do player somem ao salvar / queries retornam tudo ou vazio | Acesso à API (Player & Database) | §10 |
+| Alterar ou resetar senha de jogador | Alteração de Senha | §11 |
+| Bugs de scope/digest/iOS em frontend AngularJS | Frontend AngularJS/iOS | §12 |
+| Browser servindo versão em cache após deploy | Versionamento & Cache-Busting | §13 |
+
+### 1.5 Restrições globais críticas
+
+Internalize estas regras **antes** de implementar qualquer pattern. Elas afetam múltiplos patterns e, quando violadas, causam perda silenciosa de dados ou scripts.
+
+> ⚠️ **PUT dispara `before_update`; POST dispara `before_create`.**
+> Consequência de errar: a trigger esperada não roda e o signup/handler é ignorado sem erro visível.
+> Correto: para acionar uma trigger `before_update` (ex: Signup §2), o frontend **deve** usar `PUT`. Eventos confirmados em `modules/trigger.md` §3.1.
+
+> ⚠️ **`POST /v3/public` é upsert COMPLETO (full replace).**
+> Consequência de enviar payload parcial (ex: `{"_id":"slug","timeout":30}`): o campo `script` é apagado e o endpoint para de funcionar.
+> Correto: sempre reenvie **todos** os campos (`active`, `method`, `timeout`, `script`) ao atualizar. Pipeline em `modules/public.md` §4 (`POST /v3/public — upsert`).
+
+> ⚠️ **Timeout de scripts difere por tipo.** O default não é o mesmo nos três runtimes.
+>
+> | Runtime | Default | Configurável via | Teto `@TimedInterrupt` (independente) |
+> |---|---|---|---|
+> | Public Endpoint | **10s** | `POST /v3/public` campo `timeout` | 5s (em loops/métodos) |
+> | Trigger | **5s** | `POST /v3/trigger` campo `timeout` | 200s |
+> | Scheduler | **30s** | `POST /v3/scheduler` campo `timeout` | 2000s |
+>
+> Valor em **segundos**; `null` ou `<= 0` usa o default. O campo `timeout` **não aparece no formulário do Studio** — só via API. O `@TimedInterrupt` é uma segunda camada independente: aumentar `timeout` não eleva o teto do `@TimedInterrupt`. Em Public Endpoints o teto (5s) é **menor** que o default do executor (10s). Fontes: `modules/public.md` §5, `modules/trigger.md` §2.8, `modules/scheduler.md`.
+
+> ⚠️ **O sandbox de Public Endpoints bloqueia classes que funcionam em Triggers/Schedulers.**
+> Consequência de assumir paridade: código que roda na trigger lança `MissingPropertyException`/`ClassCastException` no Public Endpoint.
+> Restrições aplicam-se **apenas** a Public Endpoints (mesmo `SecureASTCustomizer`/`TriggerExpressionChecker` descrito em `modules/public.md` §2). Em Triggers e Schedulers, `com.*`/`org.*` e Unirest/BCrypt **funcionam**.
+>
+> | Bloqueado em Public Endpoint | Erro / motivo | Permitido em Public Endpoint |
+> |---|---|---|
+> | `com.*` / `org.*` fully-qualified | `MissingPropertyException: No such property: com/org` | `java.net.URL` / `openConnection()` (HTTP) |
+> | `BCrypt` (qualquer forma) | indisponível no sandbox | `java.security.MessageDigest` (SHA-256) |
+> | `Class.forName()` | `ClassNotFoundException` | `java.util.Base64`, `java.net.URLEncoder` |
+> | `groovy.json.JsonSlurper` / `JsonOutput` | `ClassCastException: [B incompatible with [C` | `java.text.SimpleDateFormat` |
+> | regex `=~` | bloqueado pelo `SecureASTCustomizer` | `while` loops |
+> | `for` + `return` em sequência | parser error (`expecting '}', found 'return'`) | `String.split/replace`, `StringBuilder` |
+> | `System.currentTimeMillis()` | bloqueado | `new Date().getTime()` |
+> | `instanceof` | bloqueado | `getClass().getName()` ou try/catch |
+> | Unirest (`com.mashape.*`) | é `com.*` → bloqueado | `manager.get*Manager()`, `new Player()` |
+>
+> Implicação: para hashear senha num Public Endpoint, delegue ao trigger `before_update` de `signup__c` (que tem BCrypt). Para JSON, parseie manualmente. Para HTTP, use `java.net.URL`.
+
+> ⚠️ **Use `strict=true` em todo GET/escrita do `/v3/database`.** (Detalhe completo em §9.)
+> Consequência de omitir: campos `Date` são lidos como número/string; ao reescrever, o MongoDB grava o tipo errado e queries por data (`$gt`, `_sort=-created`) param de funcionar.
+> Não se aplica a entidades nativas (`/v3/player`, `/v3/action`, etc.), que já têm tipagem própria.
+
+> ⚠️ **No `/v3/database`, o parâmetro de filtro é `q` (sintaxe Mongo), não `_filter`.**
+> Consequência: `_filter`, `_sort`, `_limit` são **silenciosamente ignorados** — a query retorna todos os registros sem filtro. Confirmado em `modules/database.md` §4.2.
+> Correto: `?q=campo:"valor"&strict=true`. Para ordenar, use `POST /v3/database/{collection}/aggregate` com `$sort` (o GET de listagem **não** ordena).
+
+> ⚠️ **`player` é entidade nativa — nunca exponha escrita pública e nunca use `/v3/database/player`.** (Detalhe completo em §10.)
+> Consequência: `PUT /v3/database/player` faz replace e perde campos; expor `/v3/player` em token público abre escrita irrestrita.
+> O `password` enviado no `POST/PUT /v3/player` é gravado **como veio, sem hash** (`modules/player.md` §3.1) — por isso o hash é feito em trigger (§2, §11).
 
-Padrões de implementação da Funifier, criados com base na experiência em projetos reais.
-
-## Quando usar
+---
 
-- Ao implementar funcionalidades comuns em frontends Funifier
-- Como referência de boas práticas de segurança e arquitetura
-- Para garantir consistência entre projetos
+## 2. Signup Pattern
 
----
+**Quando usar:** cadastro de jogador a partir de frontend público, sem backend próprio.
+**Não usar quando:** o cadastro ocorre em área já autenticada (use `POST /v3/player` direto com token de sessão).
+**Depende de:** Custom Object (`signup__c`), Trigger `before_update`, Role `public`, restrições globais §1.5 (PUT vs POST, password não-hasheado).
+**Referências:** `modules/custom-object.md` (CRUD genérico `__c`), `modules/trigger.md` §3.1 (eventos), `guides/triggers-guide.md` (script/managers), `modules/security.md` §2.2 (role `public`, Basic público → scope da role), `modules/player.md` §3.1 (`password` gravado sem hash).
 
-## Signup Pattern
+### Problema
 
-**Problema:** Implementar cadastro de jogador em área pública (frontend) que acessa diretamente a API da Funifier, sem expor o endpoint `/v3/player` para escrita direta.
+O frontend é público, então qualquer token nele embutido é visível. Dar a esse token escrita em `/v3/player` permitiria criar/alterar qualquer jogador. Além disso, o `password` enviado a `/v3/player` é gravado sem hash — gravar senha em texto plano a partir do cliente é inaceitável.
 
-**Solução:** Usar um objeto customizado `signup__c` como intermediário, com uma trigger `before_update` que valida os dados, cria o jogador com senha criptografada, e retorna o resultado para o frontend.
+### Solução
 
-### Arquitetura
+Expor apenas escrita na coleção `signup__c`. Uma trigger `before_update` valida os dados, cria o `Player` com senha hasheada via BCrypt no servidor e devolve o resultado. O token público recebe o scope da role `public` — escrita em `signup__c` e nada mais.
 
 ```
-Frontend (público) → PUT /v3/database/signup__c → Trigger before_update → Cria Player
+Frontend (público) → PUT /v3/database/signup__c → trigger before_update → cria Player (BCrypt)
+                                                                         → grava status/message em signup__c
 ```
 
-> ⚠️ **DEVE usar PUT**, não POST! A trigger `before_update` só é disparada pelo método PUT. POST dispara `before_create`.
-
-### Vantagens
-
-- O token público só tem permissão de escrita em `signup__c` — não acessa `/v3/player`
-- A senha é criptografada no servidor via BCrypt (nunca armazenada em texto plano)
-- Validação server-side (campos obrigatórios, duplicidade de username)
-- Dados sensíveis (password, email) são removidos do registro `signup__c` após processamento
-- Permite adicionar lógica extra (e-mail de boas-vindas, atribuição de equipe, etc.)
-
-### Configuração
-
-#### 1. Criar Role "public"
-
-Em **Studio > Security > Roles**, criar:
-
-| Campo | Valor |
-|-------|-------|
-| Role | `public` |
-| Scope | `write_database_signup__c` |
-| Timeout | `1d` |
-
-#### 2. Gerar Token Basic
-
-O token Basic é gerado a partir da API Key da gamificação, sem usuário/senha:
+### Implementação
 
-```
-1. Concatenar: ApiKey + ":"
-2. Codificar em Base64
-3. Prefixar com "Basic "
-4. Usar no header: Authorization: Basic <token>
-```
+**1. Role `public`** (Studio → Security → Roles): scope `write_database_signup__c`, timeout `1d`. O Basic gerado só com a API Key (sem secret) recebe o scope dessa role (`modules/security.md` §2.2).
 
-**Exemplo (JavaScript):**
+**2. Token Basic público** — API Key + `":"`, em Base64:
 ```javascript
-var BASIC_TOKEN = 'Basic ' + btoa(API_KEY + ':');
+var BASIC_TOKEN = 'Basic ' + btoa(API_KEY + ':');  // só permissões da role public
 ```
 
-Este token terá apenas as permissões da role `public` — escrita em `signup__c` e nada mais. Seguro para usar em código público.
-
-#### 3. Habilitar Password Required
-
-Em **Studio > Security**, habilitar a opção **Password Required**. Isso garante que o login exija senha, já que agora as senhas são gerenciadas de forma segura via trigger.
-
-#### 4. Criar Trigger
-
-Em **Studio > Trigger**, criar:
+**3. Studio → Security:** habilitar **Password Required** (login passa a exigir senha, agora gerida via trigger).
 
-| Campo | Valor |
-|-------|-------|
-| Name | Signup Handler |
-| Entity | `signup__c` |
-| Event | `before_update` |
-
-**Script:**
+**4. Trigger** (Studio → Trigger): entity `signup__c`, event `before_update`.
 ```java
 void trigger(event, entity, player, database){
     entity.status = "Unauthorized";
     if(entity.password == null || entity.password.trim().length() == 0) {
         entity.message = "Senha deve ser informada para se cadastrar!";
-    }
-    else if(entity.email == null || entity.email.trim().length() == 0) {
+    } else if(entity.email == null || entity.email.trim().length() == 0) {
         entity.message = "Email deve ser informado para se cadastrar!";
-    }
-    else if(entity.name == null || entity.name.trim().length() == 0) {
+    } else if(entity.name == null || entity.name.trim().length() == 0) {
         entity.message = "Nome deve ser informado para se cadastrar!";
-    }
-    else {
+    } else {
         Player current = manager.getPlayerManager().findById(entity._id);
         if(current != null) {
             entity.message = "Este usuário já está cadastrado!";
-        }
-        else {
-            // Criptografa senha e salva jogador
+        } else {
             Player p = JsonUtil.fromJson(JsonUtil.toJson(entity), Player.class);
+            // hash server-side — o POST /v3/player NÃO hasheia (ver §1.5)
             p.password = com.funifier.engine.util.BCrypt.hashpw(
                 entity.password, com.funifier.engine.util.BCrypt.gensalt()
             );
@@ -106,991 +156,646 @@ void trigger(event, entity, player, database){
             entity.status = "OK";
         }
     }
-    // Remove campos sensíveis antes de salvar no signup__c
+    // signup__c vira log de tentativas sem dados sensíveis
     entity.remove("password");
     entity.remove("email");
 }
 ```
 
-### Uso no Frontend
-
+**5. Frontend** — usar `PUT` (não `POST`; ver §1.5):
 ```javascript
-// Token público — seguro para código client-side
-var BASIC_TOKEN = 'Basic ' + btoa(API_KEY + ':');
-
-// Cadastro via signup__c — DEVE usar PUT (não POST!)
-// PUT dispara a trigger before_update; POST dispara before_create
 $http.put(API + '/v3/database/signup__c', {
-    _id: username,
-    name: fullName,
-    email: email,
-    password: password
-}, {
-    headers: { 'Authorization': BASIC_TOKEN }
-}).then(function(response) {
-    // Verificar response.data.status === "OK"
-});
+    _id: username, name: fullName, email: email, password: password
+}, { headers: { 'Authorization': BASIC_TOKEN } })
+ .then(function(response) { /* checar response.data.status === "OK" */ });
 ```
 
-### Extensões Comuns
+Extensões na trigger após o `insert`: email de boas-vindas (§3), termos de uso (campo `terms` validado), atribuição de equipe, campos extras.
+
+### Armadilhas conhecidas
 
-- **E-mail de boas-vindas:** Adicionar envio de email na trigger após `insert`
-- **Termos de uso:** Adicionar campo `terms` (boolean) e validar na trigger
-- **Atribuição de equipe:** Adicionar lógica de team assignment na trigger
-- **Campos extras:** Qualquer campo adicional pode ser passado e tratado na trigger
+- **Usar POST em vez de PUT** → dispara `before_create`, não `before_update`; a trigger de signup não roda. Causa: eventos são distintos por método HTTP. Correção: usar `PUT` (ver §1.5).
+- **Hashear senha no frontend ou esperar que `/v3/player` hasheie** → senha gravada errada. Causa: `POST /v3/player` grava `password` como veio (`modules/player.md` §3.1). Correção: hash via BCrypt na trigger.
+- **Esquecer `entity.remove("password"/"email")`** → o registro `signup__c` (público) retém dados sensíveis. Correção: remover antes do retorno; remover **depois** de qualquer uso (ex: enviar email — §3).
 
 ---
 
-## Email Template Pattern
+## 3. Email Template Pattern
 
-**Problema:** Enviar emails automáticos a partir de triggers, com conteúdo editável pelo administrador sem alterar código.
+**Quando usar:** enviar email via SMTP a partir de uma trigger, com conteúdo editável pelo admin sem mexer em código.
+**Não usar quando:** basta uma notificação push/in-app — use o módulo Notification (`modules/notification.md`).
+**Depende de:** Trigger, Custom Object (`email_template__c`), SMTP da gamificação configurado.
+**Referências:** `guides/java-libraries.md` (`EmailBuilder`/SimpleJavaMail, `JsonUtil`), `modules/trigger.md` (runtime Java), `modules/custom-object.md` (coleção `__c`), `modules/studio-page.md` (página de edição opcional).
 
-**Solução:** Criar coleção `email_template__c` com templates HTML usando variáveis Mustache, e usar `MustacheUtils.parse()` + `MailContext` nas triggers para montar e enviar.
+### Problema
 
-### Arquitetura
+Hardcodar HTML de email dentro do script da trigger acopla conteúdo a código: qualquer ajuste de texto exige redeploy do script, e o admin não consegue editar.
+
+### Solução
+
+Guardar cada template como documento em `email_template__c` com variáveis Mustache. A trigger busca o template, faz `MustacheUtils.parse()` e envia via `MailContext` da gamificação. (`MustacheUtils` e `MailContext` são utilitários do runtime de trigger; não estão no guia de bibliotecas — só `EmailBuilder` está.)
 
 ```
-email_template__c (templates editáveis) → Trigger (busca template + parse Mustache) → SMTP (envia)
+email_template__c (editável) → trigger (findOne + parse Mustache) → SMTP (MailContext) → envia
 ```
 
-### 1. Estrutura do Template (`email_template__c`)
-
-Cada template é um documento na coleção `email_template__c`:
+### Implementação
 
+**Template** (`email_template__c`):
 ```json
 {
     "_id": "signup_email_confirm",
     "fromName": "Funifier Team",
     "fromEmail": "no-reply@funifier.com",
     "subject": "Funifier : Email Confirmation",
-    "content": "Hi {{user.name}}<br/><br/>Thank you for signing up. Confirm your email:<br/><br/><a href=\"{{link}}\">Confirm your Email</a><br/><br/>The Funifier Team"
+    "content": "Hi {{user.name}}<br/><br/>Confirme seu email:<br/><a href=\"{{link}}\">Confirmar</a>"
 }
 ```
 
-**Variáveis Mustache:** Usar `{{campo}}` no subject e content. Podem ser campos da entity, do player, ou valores calculados.
-
-### 2. Uso na Trigger
-
+**Na trigger:**
 ```java
-// 1. Buscar template
-Object templateObj = database.findOne("email_template__c", "{_id: 'signup_welcome'}");
-org.bson.Document template = (org.bson.Document) templateObj;
+// 1. buscar template
+org.bson.Document template = (org.bson.Document) database.findOne("email_template__c", "{_id: 'signup_welcome'}");
 
-// 2. Montar valores para substituição Mustache
-// Opção A: usar a própria entity (se já tem os campos necessários)
-// Opção B: montar um mapa de valores calculados
+// 2. valores de substituição Mustache
 Map values = new HashMap();
 values.put("name", entity.name);
-values.put("email", entity.email);
 values.put("link", "https://app.exemplo.com/confirm/" + entity._id);
 
-// 3. Parse Mustache — substitui {{variavel}} pelos valores
+// 3. parse {{variavel}}
 String subject = com.funifier.engine.util.MustacheUtils.parse(template.getString("subject"), values);
 String content = com.funifier.engine.util.MustacheUtils.parse(template.getString("content"), values);
 
-// 4. Enviar email
+// 4. enviar
 Email email = EmailBuilder.startingBlank()
     .from(template.getString("fromName"), template.getString("fromEmail"))
     .to(entity.name, entity.email)
-    .withSubject(subject)
-    .withHTMLText(content)
-    .buildEmail();
+    .withSubject(subject).withHTMLText(content).buildEmail();
 
-com.funifier.engine.mail.MailContext ctx = com.funifier.controller.Configuration.getCurrentConfiguration().getMailContext();
+com.funifier.engine.mail.MailContext ctx =
+    com.funifier.controller.Configuration.getCurrentConfiguration().getMailContext();
 MailerBuilder.withSMTPServer(ctx.hostName, ctx.smtpPort, ctx.authUser, ctx.authPassword)
-    .buildMailer()
-    .sendMail(email);
+    .buildMailer().sendMail(email);
 ```
 
-### 3. Página Customizada no Studio (opcional)
-
-Criar uma página customizada em **Studio > Pages** para que o administrador possa editar os templates de email visualmente, sem acessar a API ou o banco diretamente.
-
-### Vantagens
-
-- **Separação de responsabilidades:** conteúdo do email separado da lógica da trigger
-- **Administrável:** admin edita templates sem alterar código
-- **Reutilizável:** mesmo template pode ser usado em múltiplas triggers
-- **Flexível:** variáveis Mustache permitem personalização dinâmica
-- **Auditável:** templates ficam versionados na coleção `email_template__c`
-
-### Classes Disponíveis no Contexto
-
 | Classe | Uso |
 |--------|-----|
-| `EmailBuilder` | Construir email (Simple Java Mail) |
-| `MailerBuilder` | Construir mailer SMTP (Simple Java Mail) |
-| `com.funifier.engine.mail.MailContext` | Config SMTP da gamificação |
-| `com.funifier.controller.Configuration` | Acesso à configuração atual |
-| `com.funifier.engine.util.MustacheUtils` | Parse de templates Mustache |
+| `EmailBuilder` / `MailerBuilder` | Construir email/mailer (SimpleJavaMail — ver `guides/java-libraries.md`) |
+| `com.funifier.engine.mail.MailContext` | Config SMTP (`hostName`, `smtpPort`, `authUser`, `authPassword`) |
+| `com.funifier.controller.Configuration` | Configuração atual da gamificação |
+| `com.funifier.engine.util.MustacheUtils` | `parse(template, valuesMap)` |
 
-### Propriedades do MailContext
+Opcional: criar página em **Studio → Pages** para o admin editar os templates visualmente (`modules/studio-page.md`).
 
-- `ctx.hostName` — servidor SMTP
-- `ctx.smtpPort` — porta SMTP
-- `ctx.authUser` — usuário de autenticação
-- `ctx.authPassword` — senha de autenticação
+### Armadilhas conhecidas
 
-> ⚠️ O envio de email deve acontecer **antes** do `entity.remove("email")` no Signup Pattern, para ter acesso ao endereço do destinatário.
+- **Enviar email no Signup (§2) depois de `entity.remove("email")`** → destinatário nulo. Causa: o campo já foi removido. Correção: enviar **antes** do `remove`.
+- **Tentar enviar email a partir de um Public Endpoint** → `com.*`/`org.*` bloqueados (§1.5); `EmailBuilder` e `MailContext` não estão acessíveis. Correção: envie de trigger/scheduler, não de Public Endpoint.
 
 ---
 
-### ⚠️ Notas Importantes
+## 4. Google OAuth Login Pattern
 
-- O token Basic com apenas a API Key recebe as permissões da role `public`
-- Nunca expor o endpoint `/v3/player` para escrita em área pública
-- A trigger roda no servidor — validações client-side são complementares, não substitutas
-- O registro em `signup__c` serve como log de tentativas de cadastro (sem dados sensíveis)
-
----
+**Quando usar:** login com Google em app Funifier sem backend próprio.
+**Não usar quando:** login por usuário/senha — use `POST /v3/auth/token` grant `password` (`modules/auth.md`).
+**Depende de:** Public Endpoint (verificação de token + geração de auth token), Signup Pattern §2 (para criar player com hash), restrições §1.5 (sandbox).
+**Referências:** `modules/public.md` (runtime/sandbox), `modules/auth.md` §2.1 (`POST /v3/auth/token`).
 
-## Payment Gateway Pattern (Asaas + Public Endpoints)
+### Problema
 
-**Problema:** Implementar pagamento recorrente (assinatura) em um app Funifier sem backend proprio, usando apenas o frontend e a infraestrutura Funifier.
+A verificação do `id_token` do Google e a emissão do token Funifier precisam acontecer server-side (a API key não pode ficar exposta, e o player precisa existir com senha hasheada). Sem backend próprio, não há onde rodar essa lógica.
 
-**Solução:** Usar Public Endpoints do Funifier como proxy server-side para a API do gateway de pagamento (Asaas), evitando CORS e protegendo a API key.
+### Solução
 
-### Arquitetura
+Google Sign-In (GSI) no frontend obtém o `id_token`; um Public Endpoint `google_login` verifica o token, cria o player (via `signup__c` PUT — §2 — para obter o hash BCrypt, já que o sandbox do Public Endpoint não tem BCrypt) e emite o auth token.
 
 ```
-Frontend (SPA)
-    |
-    v
-Funifier Public Endpoints (server-side proxy)
-    |
-    v
-Asaas API (gateway de pagamento BR)
-    |
-    v (webhook async)
-Funifier Public Endpoint (webhook receiver)
-    |
-    v
-Player.extra.plan (atualiza plano do jogador via Jongo)
+Frontend (GSI renderButton) → id_token → Public Endpoint "google_login"
+   ├─ verifica token (Google tokeninfo via java.net.URL)
+   ├─ se player não existe: cria via signup__c PUT (hash BCrypt na trigger)
+   ├─ gera token (POST /v3/auth/token via java.net.URL)
+   └─ retorna token + player
 ```
 
-### Endpoints Necessarios
-
-| Endpoint | Metodo | Funcao |
-|----------|--------|--------|
-| `validate_coupon` | POST | Valida cupom de desconto em `coupon__c` |
-| `create_subscription` | POST | Cria customer + subscription no Asaas, retorna URL de pagamento |
-| `asaas_webhook` | POST | Recebe eventos de pagamento do Asaas, atualiza plano do jogador |
-| `manage_subscription` | POST | Cancel, downgrade, reactivate, status — gerencia assinatura existente |
-
-### Fluxo de Assinatura (Novo Usuario)
-
-1. Usuario completa onboarding e escolhe plano (Standard/Premium)
-2. Frontend chama `create_subscription` com: `playerId`, `planType`, `couponCode` (opcional)
-3. Endpoint cria customer no Asaas (ou reutiliza existente via `externalReference`)
-4. Endpoint cria subscription no Asaas com:
-   - `billingType: "UNDEFINED"` (cliente escolhe Pix/cartao/boleto no checkout)
-   - `nextDueDate` com trial (ex: `DateUtil.fromKeyword("+7d")`)
-   - `externalReference: playerId` (vincula ao jogador Funifier)
-5. Endpoint retorna `invoiceUrl` (checkout hospedado do Asaas)
-6. Frontend redireciona usuario para `invoiceUrl`
-7. Usuario paga no checkout Asaas
-8. Asaas envia webhook `PAYMENT_CONFIRMED` para `asaas_webhook`
-9. Webhook atualiza `player.extra.plan` via Jongo
-
-### Sistema de Cupons
-
-Colecao `coupon__c` com estrutura:
+### Implementação
 
-```json
-{
-    "_id": "FITEVOLVE20",
-    "type": "PERCENTAGE",
-    "value": 20,
-    "maxUses": 100,
-    "usedCount": 0,
-    "active": true
-}
-```
+No Public Endpoint, HTTP via `java.net.URL` (Unirest é `com.*` → bloqueado, §1.5). Properties do player em Groovy via acesso direto (`newPlayer._id = email`), não setters. Plano padrão para usuários Google: Standard.
 
-Tipos: `PERCENTAGE` (desconto %) e `FIXED` (desconto em R$).
+### Armadilhas conhecidas
 
-O endpoint `validate_coupon` valida e retorna o desconto. O endpoint `create_subscription` aplica o desconto no `value` da subscription.
+- **Usar `google.accounts.id.prompt()` (One Tap)** → falha em mobile. Causa: limitação do One Tap em browsers móveis. Correção: `google.accounts.id.renderButton()` direto no DOM.
+- **`<a href="#" ng-click="...">`** → o `#` reseta o hash antes do `ng-click` e causa redirect. Correção: `href=""` (ver §12).
+- **`$scope.$apply` em callback async do GSI** → erro "already in digest". Correção: `$scope.$applyAsync` (ver §12).
+- **Tentar hashear senha no Public Endpoint** → BCrypt indisponível no sandbox (§1.5). Correção: delegar criação ao `signup__c` PUT (§2).
 
-### Campos do Player (`extra.plan`)
+---
 
-```json
-{
-    "type": "premium",
-    "plan_status": "active",
-    "asaas_customer_id": "cus_xxx",
-    "asaas_subscription_id": "sub_xxx",
-    "plan_end_date": null,
-    "pending_plan": null,
-    "plan_downgrade_date": null,
-    "changesUsed": 0
-}
-```
+## 5. CRM Integration Pattern (Cross-Gamification)
 
-| Campo | Descricao |
-|-------|-----------|
-| `type` | `standard` ou `premium` |
-| `plan_status` | `active`, `canceled`, `pending_downgrade` |
-| `asaas_customer_id` | ID do customer no Asaas |
-| `asaas_subscription_id` | ID da subscription ativa no Asaas |
-| `plan_end_date` | Data fim do acesso apos cancelamento |
-| `pending_plan` | Plano futuro em caso de downgrade |
-| `plan_downgrade_date` | Data em que o downgrade sera efetivado |
+**Quando usar:** criar lead/deal no CRM Funifier (gamificação B) automaticamente quando um jogador se cadastra na gamificação de produto (gamificação A).
+**Não usar quando:** produto e CRM são a mesma gamificação — escreva direto nas coleções locais.
+**Depende de:** Trigger `after_create` (entity `player`), HTTP saindo da trigger, App token do CRM.
+**Referências:** `guides/java-libraries.md` (Unirest), `modules/trigger.md` (eventos/runtime), `modules/database.md` (`/v3/database`), `modules/security.md` (scope do App).
 
-### Gestao de Assinatura
+### Problema
 
-| Acao | Logica |
-|------|--------|
-| **Cancel** | Cancela subscription no Asaas. Seta `plan_status: "canceled"` e `plan_end_date` = fim do ciclo atual. Usuario mantem acesso ate `plan_end_date`. |
-| **Downgrade** | Cancela Premium no Asaas, cria nova Standard com `nextDueDate` = fim do ciclo Premium. Seta `plan_status: "pending_downgrade"`, `pending_plan: "standard"`. |
-| **Reactivate** | Cria nova subscription no Asaas (com trial). Reseta `plan_status: "active"`. Suporta cupom. |
-| **Status** | Consulta subscription no Asaas e retorna status, proximo vencimento, valor. |
+Cada gamificação é um tenant isolado. O app de produto não tem acesso direto às coleções do CRM; é preciso uma chamada autenticada de uma gamificação para a outra, no momento certo do ciclo de vida do jogador.
 
-### Webhook: Eventos Importantes
+### Solução
 
-| Evento Asaas | Acao |
-|-------------|------|
-| `PAYMENT_CONFIRMED` / `PAYMENT_RECEIVED` | Ativa plano. Se `pending_downgrade`, efetiva downgrade. |
-| `PAYMENT_OVERDUE` | Marca como inadimplente (opcional). |
-| `PAYMENT_DELETED` / `PAYMENT_REFUNDED` | Cancela plano. |
+Trigger `after_create` na gamificação de produto faz `HTTP POST` para os endpoints `/v3/database/person` e `/v3/database/deal` da gamificação de CRM, usando um App token (não-expirável) do CRM. Em trigger, `com.*` é permitido → Unirest funciona.
 
-### Seguranca do Webhook
+```
+Gamificação Produto → trigger after_create (player) → HTTP POST → Gamificação CRM (/v3/database/person + /deal)
+```
 
-- Validar `authToken` no header/body (configurado ao criar webhook no Asaas)
-- Registrar dominio do app nas configuracoes do Asaas (para callback de checkout)
-- Webhook criado via API: `POST /v3/webhooks` no Asaas
+### Implementação
 
-### Padroes Groovy para Scripts de Pagamento
+Use App token do CRM (Security → Apps → ícone do olho gera o Basic). Deals exigem `owner`, `add_time`, `visible_to` para aparecer no Kanban. Um único CRM atende vários produtos — diferencie por Pipeline.
 
-```groovy
-// 1. Escapar $ (MongoDB operators e API keys)
-def d = String.valueOf((char)0x24)  // = "$"
-def setCmd = '{"' + d + 'set": {"extra.plan.type": "premium"}}'
+### Armadilhas conhecidas
 
-// 2. Atualizar player via Jongo (PlayerManager NAO tem update)
-manager.getJongoConnection().getCollection("player")
-    .update("{_id: #}", playerId)
-    .with(setCmd)
-
-// 3. Chamar API externa (Asaas) via Unirest
-def response = Unirest.post("https://api.asaas.com/v3/subscriptions")
-    .header("Content-Type", "application/json")
-    .header("access_token", asaasApiKey)
-    .body(JsonUtil.toJson(bodyMap))
-    .asString()
-def result = new groovy.json.JsonSlurper().parseText(response.getBody())
-
-// 4. Datas com DateUtil
-def trialEnd = DateUtil.fromKeyword("+7d")  // 7 dias no futuro
-
-// 5. Ler payload do request
-def slurper = new groovy.json.JsonSlurper()
-def body = slurper.parseText(JsonUtil.toJson(payload))
-```
+- **Usar `/v3/crm/*` com Basic auth** → 404. Causa: rotas CRM não respondem a Basic. Correção: usar `/v3/database/person` e `/v3/database/deal`.
+- **Scope do App do CRM sem a palavra `database`** → writes falham silenciosamente (201 sem persistência). Causa: `AuthBean.getScope` exige `database` no scope para escrita em `/v3/database` (`modules/security.md` §2.1). Correção: incluir `database` no scope do App.
+- **Deal sem `owner`/`add_time`/`visible_to`** → não aparece no Kanban. Correção: incluir esses campos.
 
-### Licoes Aprendidas
+---
 
-1. **Asaas `billingType: UNDEFINED`** permite o cliente escolher metodo de pagamento no checkout
-2. **Asaas `billingType: CREDIT_CARD`** e obrigatorio para cobranças recorrentes automaticas; PIX requer `chargeType: DETACHED`
-3. **`externalReference`** no Asaas e essencial para vincular subscription ao playerId
-4. **Dominio deve ser registrado no Asaas** para callbacks de checkout funcionarem
-5. **Scripts Groovy no Funifier tem timeout de 5s** — chamadas HTTP devem ser rapidas
-6. **Jongo com dotted notation** (`extra.plan.type`) funciona corretamente em `$set`
-7. **Nunca usar `import`** nos scripts — ver `public.md` → Script Runtime Environment
-8. **NÃO usar `groovy.json.JsonSlurper`** para parsear responses — usar `JsonUtil.fromJsonToMap()` (evita `LazyMap` → `ClassCastException`)
-9. **Player.extra** é campo público — acessar direto, salvar com `insert()` (upsert)
-10. **`instanceof` bloqueado** pelo SecureAST — usar alternativas
-11. **Public Endpoints podem ser atualizados via API** — `POST /v3/public` com `Basic` auth (apiKey)
+## 6. Payment Gateway Pattern (Asaas + Public Endpoints)
 
----
+**Quando usar:** assinatura recorrente num app Funifier sem backend próprio, integrando o gateway Asaas.
+**Não usar quando:** pagamento avulso simples sem recorrência, ou gateway com SDK client-side seguro.
+**Depende de:** Public Endpoints (proxy server-side), Jongo (escrita em player), restrições §1.5 (sandbox, timeouts).
+**Referências:** `modules/public.md` (endpoints/sandbox/timeout), `guides/database-access.md` §3 (Jongo), `guides/java-libraries.md` (`DateUtil`, `JsonUtil`), `modules/player.md` (`extra`).
 
-## Database Strict Mode Pattern (BSON Types)
+### Problema
 
-**Problema:** O MongoDB armazena dados em formato BSON com tipos especiais (`$date`, `$oid`, `$numberLong`, etc.). O endpoint `/v3/database` por padrão retorna os dados em JSON puro, onde campos tipados perdem a informação de tipo. Se você lê dados sem tipagem e salva de volta, o MongoDB muda o tipo do campo (ex: `Date` vira `String` ou `Number`), quebrando consultas por data e ordenação.
+Chamar a API do gateway direto do frontend expõe a API key e esbarra em CORS. Sem backend próprio, falta um lugar server-side para criar customer/subscription e receber o webhook de confirmação.
 
-**Solução:** Sempre usar `strict=true` como query parameter ao consultar via `/v3/database`. Isso retorna os dados no formato BSON estendido, preservando os tipos.
+### Solução
 
-### Exemplo sem strict (JSON puro — PERIGOSO para escrita)
+Public Endpoints atuam como proxy server-side para o Asaas (escondem a key, evitam CORS) e como receptor de webhook. O plano do jogador vive em `player.extra.plan`, atualizado via Jongo.
 
 ```
-GET /v3/database/player/ricardo
+Frontend → Public Endpoint (create_subscription) → Asaas API → invoiceUrl → checkout
+Asaas → webhook PAYMENT_CONFIRMED → Public Endpoint (asaas_webhook) → player.extra.plan (Jongo)
 ```
-```json
-{
-    "_id": "ricardo",
-    "name": "Ricardo",
-    "created": 1772145212606
-}
-```
-O campo `created` aparece como número (timestamp). Se salvar isso de volta, o MongoDB armazena como `Number`, não como `Date`.
 
-### Exemplo com strict (BSON estendido — CORRETO)
+| Endpoint | Método | Função |
+|----------|--------|--------|
+| `validate_coupon` | POST | Valida cupom em `coupon__c` |
+| `create_subscription` | POST | Cria customer + subscription, retorna `invoiceUrl` |
+| `asaas_webhook` | POST | Recebe eventos de pagamento, atualiza plano |
+| `manage_subscription` | POST | Cancel / downgrade / reactivate / status |
 
-```
-GET /v3/database/player/ricardo?strict=true
-```
-```json
-{
-    "_id": "ricardo",
-    "name": "Ricardo",
-    "created": { "$date": "2026-02-26T22:33:32.606Z" }
-}
-```
-O campo `created` vem com o tipo `$date`. Ao salvar de volta, o MongoDB preserva como `Date`.
+### Implementação
 
-### Regras de Uso
+**Fluxo (novo usuário):** frontend chama `create_subscription` (`playerId`, `planType`, `couponCode?`) → endpoint cria customer no Asaas (reusa via `externalReference`) e subscription (`billingType:"UNDEFINED"`, `nextDueDate` com trial `DateUtil.fromKeyword("+7d")`, `externalReference: playerId`) → retorna `invoiceUrl` → usuário paga → Asaas dispara `PAYMENT_CONFIRMED` → webhook atualiza `player.extra.plan`.
 
-1. **Sempre usar `strict=true` em GETs do `/v3/database`** — leitura de coleções customizadas (`__c`) e coleções nativas
-2. **Ao acessar campos tipados, usar o formato BSON:** `record.created.$date` em vez de `record.created`
-3. **Ao salvar (PUT/POST), enviar os dados no formato BSON** para preservar tipos:
-   ```json
-   { "created": { "$date": "2026-02-27T10:00:00.000Z" } }
-   ```
-4. **Ao criar novos registros com datas**, formatar assim:
-   ```javascript
-   { created: { $date: new Date().toISOString() } }
-   ```
+**`player.extra.plan`:** `type` (`standard`|`premium`), `plan_status` (`active`|`canceled`|`pending_downgrade`), `asaas_customer_id`, `asaas_subscription_id`, `plan_end_date`, `pending_plan`, `plan_downgrade_date`, `changesUsed`.
 
-### Tipos BSON Comuns
+**Cupons (`coupon__c`):** `type` (`PERCENTAGE`|`FIXED`), `value`, `maxUses`, `usedCount`, `active`. `validate_coupon` valida; `create_subscription` aplica no `value`.
 
-| Tipo | Formato JSON strict | Exemplo |
-|------|-------------------|---------|
-| Date | `{ "$date": "ISO-8601" }` | `{ "$date": "2026-02-27T10:00:00.000Z" }` |
-| ObjectId | `{ "$oid": "hex" }` | `{ "$oid": "69a16149434ba01017676d07" }` |
-| Long | `{ "$numberLong": "num" }` | `{ "$numberLong": "1234567890" }` |
+**Gestão:** Cancel → cancela no Asaas, `plan_status:"canceled"` + `plan_end_date` = fim do ciclo (mantém acesso até lá). Downgrade → cancela Premium, cria Standard com `nextDueDate` = fim do ciclo Premium, `plan_status:"pending_downgrade"`. Reactivate → nova subscription com trial. Status → consulta o Asaas.
 
-### Helper JavaScript para Frontend
+**Webhook:** `PAYMENT_CONFIRMED`/`PAYMENT_RECEIVED` → ativa plano (efetiva downgrade pendente); `PAYMENT_OVERDUE` → inadimplente; `PAYMENT_DELETED`/`PAYMENT_REFUNDED` → cancela. Segurança: validar `authToken` no header/body; registrar o domínio do app no Asaas (callback do checkout).
 
-```javascript
-// Criar campo date no formato BSON
-function bsonDate(date) {
-    return { $date: (date || new Date()).toISOString() };
-}
+**Padrões Groovy (Public Endpoint):**
+```groovy
+// escapar $ (operadores Mongo / chaves)
+def d = String.valueOf((char)0x24)
+def setCmd = '{"' + d + 'set": {"extra.plan.type": "premium"}}'
 
-// Ler campo date do formato BSON
-function readDate(field) {
-    if (!field) return null;
-    if (field.$date) return new Date(field.$date);
-    if (typeof field === 'string') return new Date(field);
-    if (typeof field === 'number') return new Date(field);
-    return null;
-}
-```
+// atualizar player via Jongo (PlayerManager não tem update) — ver guides/database-access.md §3
+manager.getJongoConnection().getCollection("player").update("{_id: #}", playerId).with(setCmd)
 
-### ⚠️ Impacto de NÃO usar strict
+// trial: data no futuro
+def trialEnd = DateUtil.fromKeyword("+7d")
 
-- Campos `Date` viram `String` ou `Number` no MongoDB
-- Consultas com `$gt`, `$lt` por data param de funcionar
-- Ordenação por data (`_sort=-created`) retorna resultados incorretos
-- Dados perdem integridade progressivamente a cada leitura+escrita
+// ler payload e parsear response SEM JsonSlurper (ver §1.5)
+def body = JsonUtil.fromJsonToMap(JsonUtil.toJson(payload))
+```
 
-### Onde se aplica
+### Armadilhas conhecidas
 
-- **Apenas** no endpoint `/v3/database` (coleções customizadas `__c` e nativas via database)
-- **NÃO** se aplica a endpoints específicos como `/v3/player`, `/v3/action`, `/v3/challenge` etc. (estes já têm tipagem própria)
+- **`JsonSlurper`/`JsonOutput` no Public Endpoint** → `ClassCastException: [B incompatible with [C`. Causa: bloqueio do sandbox (§1.5). Correção: `JsonUtil.fromJsonToMap()`.
+- **Unirest no Public Endpoint** → `com.mashape.*` é `com.*` → bloqueado (§1.5). Correção: `java.net.URL`/`openConnection()`.
+- **`billingType: CREDIT_CARD` esperando PIX recorrente** → PIX exige `chargeType: DETACHED`; `CREDIT_CARD` é obrigatório para cobrança recorrente automática. Use `UNDEFINED` para o cliente escolher no checkout.
+- **Domínio não registrado no Asaas** → callback do checkout não funciona. Correção: registrar o domínio.
+- **HTTP lento no Public Endpoint** → estoura o timeout de 10s (§1.5). Correção: chamadas rápidas; aumentar `timeout` via API se necessário.
+- **`instanceof` no script** → bloqueado (§1.5). Correção: `getClass().getName()` ou try/catch.
 
 ---
 
-## App Version Pattern
+## 7. OpenAI Realtime — Voz/Vídeo Pattern
+
+**Quando usar:** conversa por voz/vídeo com IA num app Funifier (OpenAI Realtime + WebRTC).
+**Não usar quando:** basta chat por texto (use a API de Chat Completions diretamente).
+**Depende de:** Public Endpoint (dados do usuário + API key), OpenAI Realtime API.
+**Referências:** `modules/public.md` (endpoint para servir dados/key).
 
-**Problema:** Equipe de desenvolvimento e testes precisa saber se está vendo a versão correta do app, evitando trabalhar sobre versão em cache do browser.
+### Problema
 
-**Solução:** Exibir a versão no rodapé de todas as páginas e gerenciá-la de forma consistente.
+A chave efêmera do OpenAI e os dados do usuário precisam ser montados server-side, e as tools da IA precisam ser registradas no momento certo — caso contrário a IA não "vê" as ferramentas e nunca as chama.
 
-### Convenção de Versionamento
+### Solução
+
+Um Public Endpoint retorna dados do usuário + API key; o frontend gera a chave efêmera com as tools **embutidas na criação** e estabelece WebRTC.
 
 ```
-MAJOR.MINOR
+Frontend → Public Endpoint (dados + key)
+        → POST /v1/realtime/client_secrets (chave efêmera, tools incluídas)
+        → POST /v1/realtime/calls (SDP/WebRTC) → data channel "oai-events"
 ```
 
-- **MINOR** — Incrementa +1 a cada alteração pequena (bug fix, ajuste visual, texto). Ex: `1.0` → `1.1` → `1.2` → ... → `1.120`
-- **MAJOR** — Incrementa +1 e zera o MINOR em mudanças grandes (refatoração, nova feature significativa, redesign). Ex: `1.120` → `2.0`
-
 ### Implementação
 
-#### 1. Definir versão no `config.js`
+Endpoints/parâmetros atuais (2026-03):
+- Chave efêmera: `POST /v1/realtime/client_secrets` (não o antigo `/v1/realtime/sessions`).
+- SDP: `POST /v1/realtime/calls` (não `/v1/realtime?model=...`).
+- Modelo: `gpt-realtime-mini` (hardcode como safety net; não o nome completo).
+- `voice` em `session.audio.output.voice` (não `session.voice`); `input_audio_transcription` não é suportado dentro de `session` no `client_secrets`.
 
-```javascript
-var CONFIG = {
-    // ... outras configs
-    VERSION: '1.0'
-};
-```
-
-#### 2. Expor no `$rootScope` (AngularJS)
+> ⚠️ **Tools DEVEM ser registradas na criação da chave efêmera.** `session.update` via data channel **não** aplica tools de forma confiável. Inclua `tools` no body do `POST /v1/realtime/client_secrets`; envie `session.update` apenas como backup.
 
 ```javascript
-app.run(function($rootScope) {
-    $rootScope.appVersion = CONFIG.VERSION;
+fetch('https://api.openai.com/v1/realtime/client_secrets', {
+    method: 'POST',
+    headers: { 'Authorization': 'Bearer ' + apiKey, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ session: {
+        type: 'realtime', model: 'gpt-realtime-mini', instructions: instructions,
+        tools: voiceTools,                 // ← obrigatório aqui
+        audio: { output: { voice: 'coral' } }
+    }})
 });
 ```
 
-#### 3. Rodapé no `index.html`
-
-```html
-<div class="version-footer">version {{appVersion}}</div>
-```
-
-#### 4. CSS
-
-```css
-.version-footer {
-    text-align: center;
-    font-size: 11px;
-    color: rgba(255,255,255,0.2);
-    padding: 8px 0 calc(env(safe-area-inset-bottom, 0px) + 80px);
-    letter-spacing: 0.5px;
-}
-```
-
-### Regras
-
-1. **Sempre incrementar a versão** ao fazer deploy — nunca fazer deploy sem mudar a versão
-2. **Checar a versão no rodapé** após deploy para confirmar que o cache foi atualizado
-3. Se a versão exibida não bate com a esperada → cache desatualizado → forçar refresh (Ctrl+Shift+R)
-4. Em caso de dúvida sobre qual versão está rodando, basta olhar o rodapé
-
-
-## Campo `timeout` em Scripts (Public Endpoint, Trigger, Scheduler)
-
-O timeout de execucao dos scripts e controlado por um executor Java (`Future.get(timeout, TimeUnit.SECONDS)`). O padrao e **10 segundos**. Para scripts que precisam de mais tempo (chamadas HTTP externas, BCrypt, etc.), o timeout pode ser customizado via API:
-
-```bash
-# Public Endpoint
-POST /v3/public  →  {"_id": "slug", "timeout": 30}
-
-# Trigger
-POST /v3/trigger  →  {"_id": "trigger_id", "timeout": 30}
-
-# Scheduler
-POST /v3/scheduler  →  {"_id": "scheduler_id", "timeout": 30}
+Incluir sempre uma tool `end_call` para a IA encerrar a ligação ao fim natural da conversa; o handler chama a mesma função do botão "Desligar", com delay para a IA terminar de falar:
+```javascript
+case 'response.function_call_arguments.done':
+    if (evt.name === 'end_call') {
+        sendToolResult(evt.call_id, { success: true });
+        setTimeout(function() { $scope.endCall(); $scope.$applyAsync(); }, 2000);
+    }
+    break;
 ```
 
-- Valor em **segundos** (30 = 30s)
-- Campo `timeout` **nao aparece no formulario do Studio** — so via API
-- `null` = usa padrao de 10 segundos
-- Fonte: classe Java `PublicEndpoint` (campo `public Long timeout`) + metodo `executor()` que usa `TimeUnit.SECONDS`
-- Nota: `@TimedInterrupt(5s)` no wrapper Groovy e uma segunda camada de protecao independente
-
-
-## CRITICO: POST parcial em /v3/public apaga o script!
-
-O endpoint `POST /v3/public` faz **upsert completo** — se voce enviar apenas `{"_id": "slug", "timeout": 30}`, o campo `script` sera apagado (setado como null/vazio) porque nao foi incluido no payload.
+### Armadilhas conhecidas
 
-**Regra:** Sempre inclua TODOS os campos importantes ao atualizar um endpoint via API:
-```json
-{
-    "_id": "slug",
-    "active": true,
-    "method": "POST",
-    "timeout": 30,
-    "script": "public Object handle(Object payload) { ... }"
-}
-```
-
-**Nunca faca update parcial** como `{"_id": "slug", "timeout": 30}` — isso apaga o script!
+- **Registrar tools só via `session.update`** → a IA pode nunca chamá-las. Causa: aplicação não confiável via data channel. Correção: incluir `tools` na criação da chave efêmera.
+- **Usar o nome completo do modelo ou endpoints antigos** → falha de criação da sessão. Correção: `gpt-realtime-mini` + endpoints 2026-03.
+- **`voice` em `session.voice`** → ignorado. Correção: `session.audio.output.voice`.
 
 ---
 
-## Public Endpoint Sandbox — Classes Bloqueadas vs Permitidas
-
-Resultado de testes extensivos no Orvya (março 2026). O sandbox Groovy do Funifier tem restrições severas via `SecureASTCustomizer`.
-
-### BLOQUEADO (não usar)
-
-| Item | Erro |
-|------|------|
-| `com.*` fully qualified names | `MissingPropertyException: No such property: com` |
-| `org.*` fully qualified names | `MissingPropertyException: No such property: org` |
-| `BCrypt` (unqualified) | Não disponível no sandbox de Public Endpoints |
-| `Class.forName()` | `ClassNotFoundException` |
-| `groovy.json.JsonSlurper` (para response) | `ClassCastException: [B incompatible with [C` |
-| `groovy.json.JsonOutput` | Mesma `ClassCastException` |
-| Regex `=~` operator | Bloqueado pelo `SecureASTCustomizer` |
-| `for` loop + `return` na sequência | Parser error (`expecting '}', found 'return'`) |
-| `System.currentTimeMillis()` | Bloqueado — usar `new Date().getTime()` |
-| `instanceof` | Bloqueado — usar `getClass().getName()` ou try/catch |
-
-### PERMITIDO (seguro para usar)
-
-| Item | Notas |
-|------|-------|
-| `java.net.URL` / `openConnection()` | Para chamadas HTTP externas |
-| `java.security.MessageDigest` (SHA-256) | Para hashing |
-| `java.util.Base64` | Encode/decode |
-| `java.net.URLEncoder` | URL encoding |
-| `java.text.SimpleDateFormat` | Formatação de datas |
-| `while` loops | Usar no lugar de `for` quando `return` segue |
-| `String.split()`, `String.replace()`, `StringBuilder` | Manipulação de strings |
-| `manager.getAuthenticationManager()` | Auth operations |
-| `manager.getPlayerManager()` | Player CRUD |
-| `new Player()` com `.id`, `.name`, `.email`, `.password`, `.extra` | Criação de player |
-
-### Implicações para Desenvolvimento
-
-- **Para HTTP em Public Endpoints:** usar `java.net.URL` (não Unirest — `com.mashape.*` é bloqueado)
-- **Para JSON em Public Endpoints:** parsear manualmente com `while` loops e `String.split()`
-- **Para hashing de senha:** delegar para `signup__c` PUT trigger (que tem acesso ao BCrypt)
-- **Em Triggers e Schedulers:** `com.*` e `org.*` FUNCIONAM normalmente (Unirest, BCrypt, etc.)
-
-> ⚠️ Essas restrições se aplicam APENAS a Public Endpoints. Triggers e Schedulers têm acesso completo às classes importadas no wrapper.
+## 8. Cross-User Data Isolation Pattern
 
----
+**Quando usar:** apps que usam `localStorage` como cache e trocam de usuário no mesmo dispositivo/browser.
+**Não usar quando:** o app não persiste estado por usuário no cliente.
+**Depende de:** §10 (queries corretas no `/v3/database`).
+**Referências:** `modules/database.md` §4.2 (`q`), `guides/aggregates.md` (`$sort` em aggregate).
 
-## Google OAuth Login Pattern
+### Problema
 
-**Problema:** Implementar login com Google em app Funifier sem backend próprio.
+Sem limpar o `localStorage` na troca de usuário, o segundo usuário vê dados em cache do primeiro. Usar o cache como fonte de verdade vaza dados entre contas.
 
-**Solução:** Google Sign-In (GSI) no frontend + Public Endpoint no Funifier para verificação do token e criação/login do player.
+### Solução
 
-### Arquitetura
+Defesa em três camadas: limpar no logout, limpar no login se o usuário mudou, e tratar o DB como fonte de verdade (cache nunca preenche o que o DB devolve vazio).
 
 ```
-Frontend: Google GSI renderButton → User clica → Google retorna id_token
-    |
-    v
-Funifier Public Endpoint "google_login"
-    |→ Verifica token via Google tokeninfo API (java.net.URL)
-    |→ Se player não existe: cria via signup__c PUT (para BCrypt hash)
-    |→ Gera auth token via POST /v3/auth/token (java.net.URL)
-    |→ Retorna token + player info ao frontend
+logout    → clearUserData() (remove chaves do app + zera $rootScope)
+login     → se localStorage.user != usuário atual → clearUserData()
+loadFromDB → DB é fonte de verdade: campo ausente no DB ⇒ limpa o cache (nunca mantém valor antigo)
 ```
 
-### Lições Importantes
-
-1. **Usar `google.accounts.id.renderButton()`** direto no DOM — o `prompt()` (One Tap) falha em mobile
-2. **Nunca usar `<a href="#">` com `ng-click` em AngularJS** — o `#` reseta o hash antes do ng-click, causando redirect. Usar `href=""`
-3. **Google users recebem plano Standard** por padrão
-4. **`$scope.$applyAsync`** em vez de `$scope.$apply` em callbacks async (evita "already in digest")
-5. **Player properties em Groovy:** usar acesso direto (`newPlayer._id = email`) não setter methods
-
----
-
-## Cross-User Data Isolation Pattern
-
-**Problema:** Em apps que usam localStorage para cache, trocar de usuário sem limpar cache causa vazamento de dados entre usuários.
-
-**Solução:** Defesa em 3 camadas:
+### Implementação
 
-### Camada 1: Limpar dados no logout
 ```javascript
+// Camada 1 — logout
 function clearUserData() {
-    // Limpar todas as chaves do app no localStorage
     Object.keys(localStorage).forEach(function(key) {
-        if (key.startsWith('fitness_') || key.startsWith('water_')) {
-            localStorage.removeItem(key);
-        }
+        if (key.startsWith('fitness_') || key.startsWith('water_')) localStorage.removeItem(key);
     });
-    // Limpar $rootScope
-    $rootScope.player = null;
-    $rootScope.profileData = null;
-    // ... etc
+    $rootScope.player = null; $rootScope.profileData = null;
 }
-```
 
-### Camada 2: Limpar dados no login (se usuário diferente)
-```javascript
+// Camada 2 — login com usuário diferente
 var lastUser = localStorage.getItem('fitness_user');
-if (lastUser && lastUser !== currentUser) {
-    clearUserData();
-}
-```
-
-### Camada 3: DB é source of truth
-- `loadFromDB()` sempre roda após login
-- Se DB não tem dados para um campo, localStorage é LIMPO (não mantém valor antigo)
-- Nunca usar localStorage como fallback quando DB retorna vazio
-
-### Lição: Parâmetro correto de filtro é `q`, não `_filter`
-
-O endpoint `/v3/database` **NÃO tem** parâmetro `_filter`. O parâmetro correto é `q` com sintaxe MongoDB:
+if (lastUser && lastUser !== currentUser) clearUserData();
 
+// Camada 3 — DB é source of truth: loadFromDB() roda após login;
+// se o DB não tem o campo, o localStorage é LIMPO (nunca mantém valor antigo).
 ```
-GET  /v3/database/body_checkin__c?q=userId:"ricardo@funifier.com"&strict=true
-POST /v3/database/body_checkin__c/aggregate?q=userId:"ricardo@funifier.com"&strict=true
-```
-
-`_filter`, `_sort`, `_limit` são **silenciosamente ignorados** pelo backend, fazendo com que a query retorne todos os registros sem filtro.
 
-Para queries com ordenação, usar o endpoint `aggregate` com pipeline `$sort`:
+Query por usuário (filtro com `q`, ordenação com aggregate — ver §1.5):
 ```javascript
 $http({
     method: 'POST',
-    url: API + '/v3/database/collection__c/aggregate?q=userId:"' + userId + '"&strict=true',
+    url: API + '/v3/database/body_checkin__c/aggregate?q=userId:"' + userId + '"&strict=true',
     headers: { 'Authorization': 'Bearer ' + token, 'Range': 'items=0-19' },
     data: [{ $sort: { created: -1 } }]
 });
 ```
+Defense-in-depth client-side: `results = results.filter(function(r){ return r.userId === currentUserId; });`
 
-**Defense-in-depth:** Ainda é boa prática verificar userId client-side:
-```javascript
-results = results.filter(function(r) { return r.userId === currentUserId; });
-```
+### Armadilhas conhecidas
+
+- **Usar `_filter`/`_sort`/`_limit` no `/v3/database`** → ignorados; a query traz todos os registros (vazamento entre usuários). Correção: `q` + aggregate `$sort` (§1.5).
+- **Usar `localStorage` como fallback quando o DB devolve vazio** → mantém dado do usuário anterior. Correção: vazio do DB limpa o cache.
 
 ---
 
-## CRM Integration Pattern (Cross-Gamification)
+## 9. Database Strict Mode Pattern (BSON Types)
 
-**Problema:** Integrar app de produto (gamificação A) com CRM Funifier (gamificação B) para criar leads automaticamente no signup.
+**Quando usar:** qualquer leitura ou escrita de campos tipados (datas, ObjectId, long) via `/v3/database`.
+**Não usar quando:** acessando entidades nativas (`/v3/player`, `/v3/action`, etc.) — já têm tipagem própria.
+**Depende de:** —
+**Referências:** `modules/database.md` §4.1–§4.2 (`strict`), `guides/database-access.md` §1.
 
-**Solução:** Trigger na gamificação do produto faz HTTP POST para a gamificação do CRM.
+### Problema
 
-### Arquitetura
+Sem `strict`, o `/v3/database` devolve JSON puro: um `Date` vira número (timestamp). Ao reescrever esse valor, o MongoDB grava o campo como `Number` — e consultas por data (`$gt`, `$lt`, `_sort=-created`) param de funcionar. A integridade degrada a cada ciclo leitura+escrita.
+
+### Solução
+
+Usar `strict=true` em GETs e enviar/ler campos no formato BSON estendido.
 
 ```
-Gamificação "Produto" (Orvya Fitness)
-    |
-    → Trigger after_create (entity: player)
-        |
-        → HTTP POST para Gamificação "CRM" (/v3/database/person + /v3/database/deal)
+GET /v3/database/player/ricardo            → "created": 1772145212606         (Number — perigoso)
+GET /v3/database/player/ricardo?strict=true → "created": { "$date": "...Z" }   (Date — correto)
 ```
 
-### Lições Importantes
+### Implementação
 
-1. **CRM endpoints `/v3/crm/*` retornam 404 com Basic auth** — usar `/v3/database/person` e `/v3/database/deal`
-2. **Deals precisam de campos específicos para Kanban:** `owner`, `add_time`, `visible_to`
-3. **CRM App scope DEVE incluir a palavra "database"** — sem ela, writes silenciosamente falham (201 sem persistência)
-4. **Usar App token (não-expirável)** da Security → Apps — gerar Basic token pelo ícone do olho
-5. **Um CRM para todos os produtos** — diferenciar por Pipeline
+| Tipo | Formato strict | Exemplo |
+|------|----------------|---------|
+| Date | `{ "$date": "ISO-8601" }` | `{ "$date": "2026-02-27T10:00:00.000Z" }` |
+| ObjectId | `{ "$oid": "hex" }` | `{ "$oid": "69a16149434ba01017676d07" }` |
+| Long | `{ "$numberLong": "num" }` | `{ "$numberLong": "1234567890" }` |
 
----
+```javascript
+function bsonDate(date) { return { $date: (date || new Date()).toISOString() }; }   // escrever
+function readDate(field) {                                                            // ler
+    if (!field) return null;
+    if (field.$date) return new Date(field.$date);
+    if (typeof field === 'string' || typeof field === 'number') return new Date(field);
+    return null;
+}
+```
+Ao acessar campo tipado, usar a forma BSON (`record.created.$date`), não `record.created`.
 
-## Player Management Pattern
+### Armadilhas conhecidas
 
-### Leitura e Escrita de Player
+- **GET sem `strict=true` seguido de PUT** → o campo `Date` é regravado como `String`/`Number`. Causa: a leitura perdeu o tipo. Correção: ler com `strict=true` e reescrever no formato `{ $date: ... }`.
+- **Aplicar strict em `/v3/player`** → desnecessário e sem efeito útil. Correção: só em `/v3/database`.
 
-```groovy
-// Ler player
-Player p = manager.getPlayerManager().findById(playerId)
+---
 
-// Modificar
-p.extra.plan = [type: "premium"]
+## 10. Acesso à API Funifier — Player & Database
 
-// Salvar (upsert)
-manager.getPlayerManager().insert(p)
-```
+**Quando usar:** ao ler/escrever Player ou coleções customizadas e os campos somem ou as queries retornam tudo/vazio.
+**Não usar quando:** operações cobertas por um módulo específico (use o módulo).
+**Depende de:** §9 (strict), restrições §1.5 (`player` nativo, `q` vs `_filter`).
+**Referências:** `modules/player.md` (entidade, `insert` único ponto de escrita), `modules/database.md` (CRUD/`q`/aggregate), `guides/java-managers.md` (PlayerManager), `modules/custom-object.md` (`__c`).
 
-### Campos obrigatórios no POST /v3/player
+### Problema
 
-Ao atualizar player via `POST /v3/player` com apenas `_id` + `extra`, os campos `name` e `email` são APAGADOS. **Sempre incluir:**
+`player` é entidade **nativa**, não uma coleção do `/v3/database`. Misturar os dois endpoints, ou enviar objetos parciais, causa perda silenciosa: campos somem, queries voltam vazias e o bug é difícil de rastrear.
 
-```json
-{
-    "_id": "user@email.com",
-    "name": "Nome do Usuário",
-    "email": "user@email.com",
-    "extra": { ... }
-}
+### Solução
+
+Endpoints distintos por tipo de recurso, e escrita de player sempre via **read-merge-write** (objeto completo).
+
+```
+GET /v3/player/{id} → objeto completo → muta só os campos alvo → POST /v3/player (objeto completo)
+                                          (extra/name/email preservados)
 ```
 
-### Player.image Structure
+| Recurso | Ler | Salvar | Errado |
+|---------|-----|--------|--------|
+| Player (nativo) | `GET /v3/player/{id}` | `POST /v3/player` (objeto completo) | `GET/PUT /v3/database/player` (404 / replace) |
+| Database (`__c`) | `GET /v3/database/{c}?strict=true&q=_id:'{id}'` | `PUT /v3/database/{c}` (objeto completo) | `GET /v3/database/{c}/{id}` (não existe) |
+| Aggregate | `POST /v3/database/{c}/aggregate?strict=true` | — | `POST /v3/database/{c}` (CRIA documento!) |
 
-Para salvar foto do player, usar a estrutura completa:
+### Implementação
 
+**Read-merge-write do player** (preserva `extra`, `image`, etc.):
+```javascript
+ApiService.getPlayer(playerId).then(function(res) {
+    var player = res.data;
+    player.image = imageObj;                 // muda só o que precisa; extra fica intacto
+    $http.post(API + '/v3/player', player, authHeader);
+});
+```
+Ao salvar player com `extra`, **sempre** inclua `name` e `email` (senão são apagados):
 ```json
-{
-    "image": {
-        "small": { "url": "https://...", "size": 0, "width": 0, "height": 0, "depth": 0 },
-        "medium": { "url": "https://...", "size": 0, "width": 0, "height": 0, "depth": 0 },
-        "original": { "url": "https://...", "size": 0, "width": 0, "height": 0, "depth": 0 }
-    }
-}
+{ "_id": "user@email.com", "name": "Nome", "email": "user@email.com", "extra": { } }
 ```
 
-Os campos `size`, `width`, `height`, `depth` são obrigatórios (mesmo que 0) — Funifier espera essa estrutura.
+**`player.image`** exige a estrutura completa (`size`/`width`/`height`/`depth` obrigatórios, mesmo `0`):
+```json
+{ "image": { "small": {"url":"…","size":0,"width":0,"height":0,"depth":0},
+             "medium": {…}, "original": {…} } }
+```
 
-### PlayerManager — Métodos Corretos
+**Query por ID em `__c` retorna ARRAY** — normalizar:
+```javascript
+$http.get(API + "/v3/database/profile__c?strict=true&q=_id:'" + userId + "'", authHeader)
+ .then(function(res){ res.data = (Array.isArray(res.data) && res.data[0]) || null; return res; });
+```
 
+**PlayerManager em Groovy** (triggers/schedulers/endpoints — `guides/java-managers.md`):
 | Correto | Errado |
 |---------|--------|
 | `pm.findById(id)` | — |
-| `pm.find()` (sem args) | `pm.find("{}")` (signature não existe) |
-| `pm.insert(player)` | `pm.save(player)` |
-| `player.id` (em Groovy) | `player._id` (não funciona em Groovy) |
+| `pm.find()` (sem args) | `pm.find("{}")` (signature inexistente) |
+| `pm.insert(player)` (upsert; único ponto de escrita) | `pm.save(player)` |
+| `player.id` | `player._id` (não funciona em Groovy) |
 | `player.extra` (acesso direto) | `player.getExtra()` (não existe) |
 
----
-
-## AngularJS Patterns (Frontend)
-
-Lições aprendidas em projetos AngularJS 1.x com Funifier:
-
-### ng-if cria child scope
-`ng-model="varName"` dentro de `ng-if` escreve no child scope, não no controller. **Fix:** usar `$parent.varName`:
-
-```html
-<div ng-if="editing">
-    <input ng-model="$parent.editName">  <!-- correto -->
-    <input ng-model="editName">           <!-- BUG: escreve no child scope -->
-</div>
-```
-
-### $q.reject() em vez de Promise.reject()
-Dentro de `$http.then()` chains, nunca usar `Promise.reject()` — o digest cycle do AngularJS não detecta. Usar `$q.reject()`.
-
-### input[type="time"] requer Date object
-AngularJS `<input type="time">` não aceita strings `"07:00"`. Converter para `Date` ao carregar:
-
-```javascript
-var parts = timeStr.split(':');
-var d = new Date(1970, 0, 1, parseInt(parts[0]), parseInt(parts[1]), 0);
-```
+### Armadilhas conhecidas
 
-### href="#" causa redirect
-`<a href="#" ng-click="fn()">` reseta hash antes de ng-click → causa redirect. **Fix:** usar `href=""`
-
-### iOS Safari limitations
-- `navigator.vibrate` não funciona — usar `new Audio('audio/beep.mp3')`
-- `Notification` API não disponível (non-PWA) — `'Notification' in window` é false
-- `beforeinstallprompt` não existe — Apple usa Share → Add to Home Screen
-- `google.accounts.id.prompt()` falha em mobile — renderizar botão oficial
+- **`POST /v3/player` com só `_id` + `extra`** → `name`/`email` apagados. Causa: o save persiste o objeto enviado. Correção: read-merge-write com objeto completo.
+- **`PUT /v3/database/{c}` parcial** → replace total apaga campos não enviados. Correção: enviar objeto completo.
+- **`POST /v3/database/{c}` esperando query** → cria um documento novo. Correção: usar `GET ?q=` para filtrar, `POST .../aggregate` para pipeline.
+- **Tratar a resposta de `?q=_id:` como objeto** → é array. Correção: pegar `[0]`.
 
 ---
 
-## OpenAI Realtime API — Voice/Video Call Pattern
+## 11. Alteração de Senha Pattern
 
-### Arquitetura
-Stack: OpenAI Realtime API + WebRTC. Fluxo:
-1. Frontend chama Funifier Public Endpoint para obter dados do usuário + API key
-2. Frontend gera chave efêmera via `/v1/realtime/client_secrets`
-3. Frontend estabelece WebRTC via `/v1/realtime/calls` (SDP exchange)
-4. Data channel `oai-events` para controle bidirecional
+**Quando usar:** trocar ou resetar a senha de um jogador (área logada, "esqueci a senha", ou reset administrativo).
+**Não usar quando:** o jogador ainda não existe — use Signup §2.
+**Depende de:** BCrypt (server-side, em trigger), template de email da gamificação (fluxo "esqueci").
+**Referências:** `modules/auth.md` (autenticação), `modules/player.md` §3.1 (`password` não-hasheado no POST/PUT), `modules/security.md`, `modules/trigger.md`.
 
-### Endpoints OpenAI (atualizados 2026-03)
-- **Chave efêmera:** `POST /v1/realtime/client_secrets` (NÃO usar o antigo `/v1/realtime/sessions`)
-- **SDP exchange:** `POST /v1/realtime/calls` (NÃO usar o antigo `/v1/realtime?model=...`)
-- **Modelo:** `gpt-realtime-mini` (NÃO usar nome completo `gpt-4o-realtime-mini-2025-01-21`)
-- `input_audio_transcription` NÃO é suportado dentro do objeto `session` no endpoint `client_secrets`
-- `voice` deve estar em `session.audio.output.voice`, NÃO em `session.voice`
+### Problema
 
-### ⚠️ CRITICAL: Tools DEVEM ser registradas na criação da chave efêmera
+A senha é armazenada com BCrypt; não pode ser trocada gravando o campo `password` direto (o `POST/PUT /v3/player` grava sem hash — §1.5). Cada cenário (lembra/esqueceu/admin) usa um caminho distinto.
 
-**Problema:** `session.update` via data channel NÃO aplica tools de forma confiável. A IA pode não "ver" as ferramentas e nunca chamá-las.
+### Solução
 
-**Solução:** Incluir `tools` no body do `POST /v1/realtime/client_secrets`:
+Usar os endpoints nativos de senha; para reset administrativo server-side, hashear com BCrypt numa trigger.
 
-```javascript
-fetch('https://api.openai.com/v1/realtime/client_secrets', {
-    method: 'POST',
-    headers: { 'Authorization': 'Bearer ' + apiKey, 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-        session: {
-            type: 'realtime',
-            model: 'gpt-realtime-mini',
-            instructions: instructions,
-            tools: voiceTools,  // ← CRITICAL: incluir aqui!
-            audio: { output: { voice: 'coral' } }
-        }
-    })
-});
+```
+Lembra a senha   → PUT /v3/player/password?old_password=…&new_password=…
+Esqueceu         → GET /v3/player/password/change (email c/ código) → PUT …?code=…&new_password=…
+Reset admin      → PUT /v3/database/change_password__c → trigger BCrypt → PlayerManager.insert
 ```
 
-O `session.update` via data channel pode ser enviado como **backup**, mas NÃO como fonte primária de configuração.
-
-### Tool end_call — Finalização automática de ligação
+### Implementação
 
-Sempre incluir uma tool `end_call` para que a IA possa desligar a ligação quando a conversa terminar naturalmente:
+**Jogador lembra a senha (área logada):**
+```
+PUT /v3/player/password?player={id}&old_password={atual}&new_password={nova}
+Authorization: Basic {token}
+```
 
-```javascript
-var voiceTools = [
-    // ... outras tools ...
-    {
-        type: 'function',
-        name: 'end_call',
-        description: 'Encerra a ligacao quando o usuario disser tchau, que ja entendeu, ou quando a conversa terminar. Sempre se despeca antes de chamar.',
-        parameters: { type: 'object', properties: {}, required: [] }
-    }
-];
+**Esqueceu a senha (área pública):**
+```
+# 1. solicitar código (enviado por email — usa o template configurado na gamificação)
+GET /v3/player/password/change?player={id}
+# 2. definir nova senha com o código
+PUT /v3/player/password?player={id}&code={código}&new_password={nova}
 ```
 
-No handler de eventos:
-```javascript
-case 'response.function_call_arguments.done':
-    if (evt.name === 'end_call') {
-        sendToolResult(evt.call_id, { success: true });
-        setTimeout(function() {
-            $scope.endCall();  // mesma função do botão "Desligar"
-            $scope.$applyAsync();
-        }, 2000);  // delay para IA terminar de falar
+**Reset via trigger (admin):**
+```groovy
+void trigger(event, entity, player, database) {
+    Player p = manager.getPlayerManager().findById(entity._id);
+    if (entity.password != null) {
+        p.password = com.funifier.engine.util.BCrypt.hashpw(
+            entity.password, com.funifier.engine.util.BCrypt.gensalt());
+        entity.remove("password");
     }
-    break;
+    manager.getPlayerManager().insert(p);
+}
 ```
-
-Nas instruções, mencionar a tool explicitamente:
 ```
-Voce tem a ferramenta end_call para encerrar a ligacao.
-Quando o usuario disser tchau ou pedir para desligar, despeca-se e chame end_call.
+PUT /v3/database/change_password__c   { "_id": "playerId", "password": "novaSenha" }
 ```
 
-### Checklist para implementar conversa por voz
-1. [ ] Criar Public Endpoint no Funifier para retornar dados do usuário + API key
-2. [ ] Incluir **todas as tools** (incluindo `end_call`) na criação da chave efêmera
-3. [ ] Usar modelo `gpt-realtime-mini` (hardcode no frontend como safety net)
-4. [ ] Usar `voice` em `session.audio.output.voice`
-5. [ ] Implementar handler para `response.function_call_arguments.done`
-6. [ ] Tool `end_call` deve chamar a mesma função do botão manual "Desligar"
-7. [ ] Enviar `session.update` via data channel como backup (não como fonte primária)
-8. [ ] Incluir instruções em português com contexto completo do usuário
+Observações: `player` aceita `_id` ou `email`; o `code` expira após uso/timeout; Basic auth é suficiente.
+
+### Armadilhas conhecidas
+
+- **Gravar `password` direto via `POST /v3/player`** → fica em texto plano (não hasheado, §1.5) e o login falha. Correção: usar os endpoints de senha ou hashear em trigger.
+- **Esquecer `entity.remove("password")` na trigger** → senha em texto plano fica no `change_password__c`. Correção: remover após hashear.
 
 ---
 
-## Funifier API — Endpoints Corretos (CRÍTICO)
+## 12. Frontend AngularJS / iOS Pattern
 
-**Problema:** Usar endpoints errados causa perda silenciosa de dados — campos desaparecem, queries retornam vazio, e é difícil debugar.
+**Quando usar:** apps frontend Funifier em AngularJS 1.x, especialmente em iOS Safari.
+**Não usar quando:** o frontend não usa AngularJS.
+**Depende de:** —
+**Referências:** —
 
-### Player (entidade nativa)
+### Problema
 
-O `player` é uma entidade nativa do Funifier, **NÃO** uma collection do `/v3/database`.
+AngularJS 1.x tem armadilhas de scope/digest que produzem bugs silenciosos (binding no scope errado, promises não detectadas), e o iOS Safari não suporta APIs comuns de PWA.
 
-| Operação | ✅ Correto | ❌ Errado (não funciona) |
-|----------|-----------|--------------------------|
-| **Ler por ID** | `GET /v3/player/{id}` | `GET /v3/database/player/{id}` (404 ou vazio) |
-| **Salvar/Atualizar** | `POST /v3/player` (com objeto completo) | `PUT /v3/database/player` (faz REPLACE, perde campos) |
-| **Deletar** | `DELETE /v3/player/{id}` | — |
+### Solução
 
-**Padrão correto para atualizar player (read-merge-write):**
-```javascript
-// 1. Ler player completo
-ApiService.getPlayer(playerId).then(function(res) {
-    var player = res.data;
-    
-    // 2. Merge apenas os campos que mudaram
-    player.image = imageObj;   // ex: atualizar foto
-    // player.extra permanece intacto!
-    
-    // 3. Salvar objeto completo via POST /v3/player
-    $http.post(API + '/v3/player', player, authHeader);
-});
-```
+Aplicar as correções abaixo nos pontos onde cada armadilha aparece.
 
-**Exemplo do fitness (funciona):**
-```javascript
-$http.post(API + '/v3/player', {
-    _id: userId,
-    name: $rootScope.player.name,
-    email: $rootScope.player.email,
-    image: imgObj,
-    extra: $rootScope.player.extra  // SEMPRE incluir extra!
-}, AuthService.authHeader());
-```
+### Implementação
 
-### Database (collections customizadas `__c`)
+- **`ng-if` cria child scope:** `ng-model` dentro de `ng-if` escreve no child scope. Use `$parent`:
+  ```html
+  <div ng-if="editing"><input ng-model="$parent.editName"></div>
+  ```
+- **`$q.reject()` (não `Promise.reject()`)** dentro de `$http.then()` — o digest do Angular não detecta `Promise.reject()`.
+- **`<input type="time">` exige `Date`**, não string `"07:00"`:
+  ```javascript
+  var p = timeStr.split(':'); var d = new Date(1970,0,1, +p[0], +p[1], 0);
+  ```
 
-O endpoint `/v3/database` serve para collections customizadas (ex: `profile__c`, `signup__c`).
+### Armadilhas conhecidas
 
-| Operação | ✅ Correto | ❌ Errado (não funciona) |
-|----------|-----------|--------------------------|
-| **Ler por ID** | `GET /v3/database/{collection}?strict=true&q=_id:'{id}'` | `GET /v3/database/{collection}/{id}` (padrão não existe) |
-| **Salvar** | `PUT /v3/database/{collection}` (com objeto completo) | — |
-| **Listar/Filtrar** | `GET /v3/database/{collection}?q={mongo-query}&strict=true` | — |
-| **Aggregate** | `POST /v3/database/{collection}/aggregate?strict=true` | `POST /v3/database/{collection}` (CRIA documento!) |
+- **`<a href="#" ng-click="fn()">`** → reseta o hash antes do `ng-click` e causa redirect. Correção: `href=""`. (Também relevante no §4.)
+- **`$scope.$apply` em callback async** → "already in digest". Correção: `$scope.$applyAsync`. (Também no §4 e §7.)
+- **iOS Safari (non-PWA):** `navigator.vibrate` não funciona (use `new Audio('audio/beep.mp3')`); `Notification` indisponível (`'Notification' in window` é `false`); `beforeinstallprompt` não existe (Apple usa Share → Add to Home Screen); `google.accounts.id.prompt()` falha (renderizar botão — §4).
 
-**⚠️ CUIDADO:** `POST /v3/database/{collection}` com um body JSON **CRIA** um novo documento em vez de fazer query!
+---
 
-**⚠️ `PUT /v3/database/{collection}` faz REPLACE:** Substitui o documento inteiro. Se não enviar `extra`, `password`, etc., esses campos são apagados.
+## 13. Versionamento & Cache-Busting Pattern
 
-**Query por ID retorna ARRAY — normalizar:**
-```javascript
-getProfile: function(userId) {
-    return $http.get(
-        API + "/v3/database/profile__c?strict=true&q=_id:'" + userId + "'",
-        authHeader
-    ).then(function(res) {
-        // q= retorna array, pegar primeiro elemento
-        res.data = Array.isArray(res.data) && res.data.length > 0 ? res.data[0] : null;
-        return res;
-    });
-}
-```
+**Quando usar:** SPAs hospedadas (ex: Netlify) onde o browser serve JS/CSS de cache após deploy.
+**Não usar quando:** o host já faz hash de assets por build (ex: bundlers com fingerprint).
+**Depende de:** —
+**Referências:** —
 
-### strict=true (BSON types)
+### Problema
 
-- Sempre usar `?strict=true` no `/v3/database` para preservar tipos BSON
-- Datas: ler como `field.$date`, escrever como `{ $date: "ISO-8601" }`
-- Sem strict, datas viram strings/números e quebram queries
-- **Não se aplica** a `/v3/player`, `/v3/action`, etc. (entidades nativas)
+O browser serve `app.js`/`api.js`/CSS do cache mesmo após deploy. O usuário vê a versão nova no rodapé (porque `config.js` mudou) mas executa código antigo — bugs "impossíveis" que não reproduzem.
 
----
+### Solução
 
-## Cache-Busting em SPAs (Netlify)
+Versão visível no rodapé + query string de versão em todos os assets + headers anti-cache.
 
-**Problema:** Browser serve arquivos JS/CSS do cache, ignorando deploys novos. Usuário vê versão nova no rodapé (config.js atualizado) mas executa código antigo (api.js, controllers do cache).
+### Implementação
 
-**Solução:** Query string com versão em todos os `<script>` e `<link>`:
+**Versão (`MAJOR.MINOR`)** — incrementar MINOR a cada ajuste pequeno; MAJOR (zera MINOR) em mudança grande. Definir em `config.js` e expor:
+```javascript
+var CONFIG = { VERSION: '1.0' };
+app.run(function($rootScope){ $rootScope.appVersion = CONFIG.VERSION; });
+```
+```html
+<div class="version-footer">version {{appVersion}}</div>
+```
 
+**Cache-busting** — `?v=` em todos os `<script>`/`<link>` e headers Netlify:
 ```html
-<script src="app.js?v=0.20.2"></script>
 <script src="services/api.js?v=0.20.2"></script>
 <link rel="stylesheet" href="css/style.css?v=0.20.2">
 ```
-
-**Complemento:** Arquivo `_headers` na raiz do projeto (Netlify):
 ```
+# _headers (raiz)
 /*.js
   Cache-Control: no-cache, must-revalidate
 /*.css
   Cache-Control: no-cache, must-revalidate
 ```
 
-**Regra:** A cada deploy, atualizar o `?v=` em todos os tags do `index.html` para a versão nova. Isso garante que o browser baixa os arquivos atualizados.
-
-**Checklist de deploy:**
-1. [ ] Bumpar VERSION nos dois `config.js` (`app/config.js` e `config.js` raiz)
-2. [ ] Atualizar `?v=` em todos os `<script>` e `<link>` do `index.html`
-3. [ ] `git add -A && git commit && git push`
-4. [ ] Deploy via API Netlify (zip)
-5. [ ] Informar versão ao Ricardo
-
-
-## Alteração de Senha
-
-A senha do jogador é armazenada criptografada (BCrypt). Não pode ser alterada simplesmente editando o campo password diretamente.
-
-### Jogador lembra a senha atual (área logada)
-
-```
-PUT /v3/player/password?player={playerId}&old_password={senhaAtual}&new_password={novaSenha}
-Authorization: Basic {token}
-```
-
-### Jogador esqueceu a senha (área pública — "Forgot Password")
-
-**Passo 1:** Solicitar código de recuperação (enviado por email):
-```
-GET /v3/player/password/change?player={playerId}
-Authorization: Basic {token}
-```
-
-**Passo 2:** Usar o código recebido por email para definir nova senha:
-```
-PUT /v3/player/password?player={playerId}&code={codigoRecebido}&new_password={novaSenha}
-Authorization: Basic {token}
-```
+**Checklist de deploy:** (1) bumpar `VERSION` em todos os `config.js`; (2) atualizar `?v=` em todos os assets do `index.html`; (3) commit + push; (4) deploy; (5) conferir a versão no rodapé.
 
-### Alteração via Trigger (server-side)
+### Armadilhas conhecidas
 
-Para alterar a senha via trigger (ex: admin reset), usar BCrypt:
+- **Deploy sem bumpar versão / `?v=`** → browser serve assets antigos; o rodapé não confirma a atualização real do código. Correção: seguir o checklist por completo.
+- **Versão no rodapé não bate com a esperada** → cache desatualizado. Correção: forçar refresh (Ctrl+Shift+R) e revisar `?v=`.
 
-```groovy
-void trigger(event, entity, player, database) {
-    Player p = manager.getPlayerManager().findById(entity._id);
-    if (entity.password != null) {
-        p.password = com.funifier.engine.util.BCrypt.hashpw(
-            entity.password, com.funifier.engine.util.BCrypt.gensalt()
-        );
-        entity.remove("password");
-    }
-    manager.getPlayerManager().insert(p);
-}
-```
-
-Chamada:
-```
-PUT /v3/database/change_password__c
-{"_id": "playerId", "password": "novaSenha"}
-```
+---
 
-### Observações
-- O endpoint `GET /v3/player/password/change` envia email automaticamente usando o template de email configurado na gamificação
-- O `player` param aceita tanto o `_id` quanto o `email` do jogador
-- O `code` tem validade limitada (expira após uso ou timeout)
-- Basic auth é suficiente (não precisa de Bearer/session token)
+## Fontes consultadas
+
+Arquivos lidos/inspecionados em `datasource-funifier-docs/knowledge/` durante a Etapa 1. "Inspecionado via grep" significa que confirmei headings e âncoras específicas (não li o arquivo inteiro).
+
+| Arquivo | Como foi usado | O que contribuiu |
+|---------|----------------|------------------|
+| `index.md` | Lido | Router da base; confirmou nomes de módulos/guias para as linhas de **Referências**. |
+| `modules/patterns.md` (original) | Lido integral | Fonte de todo o conteúdo experiencial reescrito. |
+| `modules/public.md` | Inspecionado (grep) | **Referenciado.** Confirmou: timeout default 10s + `@TimedInterrupt` 5s (§5), upsert completo do `POST /v3/public` (§4), sandbox `SecureASTCustomizer`/`TriggerExpressionChecker` (§2), vazamento de threads no `executor()`. Base das restrições §1.5 e patterns §4/§6/§7. |
+| `modules/trigger.md` | Inspecionado (grep) | **Referenciado + correção incorporada.** Confirmou eventos `before_create`/`before_update` por método (§3.1) e timeout default **5s** (§2.8) — corrigi o original, que dizia 10s para triggers. |
+| `modules/scheduler.md` | Inspecionado (grep) | **Correção incorporada.** Timeout default **30s** (não 10s) e `@TimedInterrupt` 2000s — corrigiu a tabela de timeouts em §1.5. |
+| `modules/database.md` | Inspecionado (grep) | **Referenciado.** Confirmou `strict` (§4.1/§4.2), `q` como fragmento Mongo cru, GET de listagem **não ordena** (usar aggregate), PUT = full replace. Base de §9, §10 e restrições §1.5. |
+| `modules/player.md` | Inspecionado (grep) | **Referenciado + incorporado.** Confirmou que `password` é gravado **sem hash** no POST/PUT (§3.1) — fundamenta §2, §11 e a restrição §1.5; `extra`/`image` como campos; `insert()` como único ponto de escrita. |
+| `modules/security.md` | Inspecionado (grep) | **Referenciado.** Confirmou role `public`, Basic público (só apiKey) → scope da role, e exigência de `database` no scope para escrita em `/v3/database`. Base de §2 e §5. |
+| `modules/custom-object.md` | Inspecionado (grep) | **Referenciado.** Confirmou que `__c` é só convenção sobre o `DatabaseRest` genérico. Contextualiza `signup__c`, `email_template__c`, `coupon__c`. |
+| `modules/auth.md` | Inspecionado (grep) | **Referenciado.** Confirmou `POST /v3/auth/token` e grants. Base de §4 e §11. |
+| `guides/java-libraries.md` | Inspecionado (grep) | **Referenciado.** Confirmou `JsonUtil.fromJsonToMap`, `DateUtil.fromKeyword`, `EmailBuilder` (SimpleJavaMail) e que Unirest é `com.mashape.*` (→ bloqueado em Public Endpoint). Base de §3, §6 e restrição do sandbox. |
+| `guides/triggers-guide.md` | Inspecionado (grep) | **Referenciado.** Tabela de eventos×entidades e managers — base das triggers de §2, §5, §11. |
+| `guides/database-access.md` | Inspecionado (grep) | **Referenciado.** Acesso Jongo via `manager.getJongoConnection()` — base do update de player em §6. |
+| `guides/aggregates.md` | Não lido | **Referenciado** (via `index.md`) para `$sort`/relatórios em §8. Não inspecionado em detalhe; citado apenas como ponteiro de aprofundamento. |
+| `guides/java-managers.md` / `guides/java-entities.md` | Não lidos | **Referenciados** (via `index.md`) em §10 para métodos de manager e campos de entidade. Citados como ponteiros. |
+| `modules/studio-page.md` | Não lido | **Referenciado** em §3 (página opcional de edição de templates). Citado como ponteiro. |
+| `modules/notification.md` | Não lido | **Ignorado como referência primária.** O Email Template Pattern envia SMTP via trigger (caminho distinto do módulo Notification). Mencionado em §3 apenas como alternativa. |
+| Demais `modules/*.md` (achievement, action, action-log, avatar, backup, challenge, compact, competition, crossword, csv-data, folder, kpi-formulas, lastmile, leaderboard, level, lottery, marketplace, mystery, point, question, quiz, story, swap, team, upload, virtual-good, webhook, websocket, widget, staging, static-repo) | Listados (não lidos) | **Ignorados.** São módulos de feature sem sobreposição com os patterns de implementação deste documento. |
+
+### Decisões de classificação (Etapa 1 → Etapa 2)
+
+- **Restrições movidas para §1.5** (eram seções/sub-itens soltos no original): `POST /v3/public` upsert, campo `timeout`, sandbox de Public Endpoints, `strict=true`, `q` vs `_filter`, PUT vs POST, `player` nativo + `password` sem hash. Motivo: afetam múltiplos patterns; centralizar evita repetição (regra "sem redundância").
+- **Consolidações:** "Player Management" + "Funifier API Endpoints Corretos" → §10; "App Version" + "Cache-Busting" → §13. Motivo: tratavam do mesmo problema em seções separadas.
+- **Deduplicações:** `strict` agora só em §9 (one-liner em §1.5); BCrypt em §2/§11 sem repetir a explicação do sandbox (que vive em §1.5); endpoints `/v3/player` vs `/v3/database` só em §10/§1.5; sandbox só em §1.5 (patterns referenciam).
+- **Mantidos como patterns** (decisão de não reduzir): App Version/Cache-Busting (§13) e AngularJS/iOS (§12), embora sejam convenções de frontend e não recursos exclusivos do Funifier.