funifier-mcp 0.2.0 → 0.2.4

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

@@ -1,1096 +1,1096 @@
-# Patterns (Design Patterns)
-
-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
-
----
-
-## Signup Pattern
-
-**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.
-
-**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.
-
-### Arquitetura
-
-```
-Frontend (público) → PUT /v3/database/signup__c → Trigger before_update → Cria Player
-```
-
-> ⚠️ **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:
-
-```
-1. Concatenar: ApiKey + ":"
-2. Codificar em Base64
-3. Prefixar com "Basic "
-4. Usar no header: Authorization: Basic <token>
-```
-
-**Exemplo (JavaScript):**
-```javascript
-var BASIC_TOKEN = 'Basic ' + btoa(API_KEY + ':');
-```
-
-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:
-
-| Campo | Valor |
-|-------|-------|
-| Name | Signup Handler |
-| Entity | `signup__c` |
-| Event | `before_update` |
-
-**Script:**
-```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) {
-        entity.message = "Email deve ser informado para se cadastrar!";
-    }
-    else if(entity.name == null || entity.name.trim().length() == 0) {
-        entity.message = "Nome deve ser informado para se cadastrar!";
-    }
-    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
-            Player p = JsonUtil.fromJson(JsonUtil.toJson(entity), Player.class);
-            p.password = com.funifier.engine.util.BCrypt.hashpw(
-                entity.password, com.funifier.engine.util.BCrypt.gensalt()
-            );
-            p.setCreated(new Date());
-            manager.getPlayerManager().insert(p);
-            entity.message = "Usuário registrado com sucesso!";
-            entity.status = "OK";
-        }
-    }
-    // Remove campos sensíveis antes de salvar no signup__c
-    entity.remove("password");
-    entity.remove("email");
-}
-```
-
-### Uso no Frontend
-
-```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"
-});
-```
-
-### Extensões Comuns
-
-- **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
-
----
-
-## Email Template Pattern
-
-**Problema:** Enviar emails automáticos a partir de triggers, com conteúdo editável pelo administrador sem alterar código.
-
-**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.
-
-### Arquitetura
-
-```
-email_template__c (templates editáveis) → Trigger (busca template + parse Mustache) → SMTP (envia)
-```
-
-### 1. Estrutura do Template (`email_template__c`)
-
-Cada template é um documento na coleção `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"
-}
-```
-
-**Variáveis Mustache:** Usar `{{campo}}` no subject e content. Podem ser campos da entity, do player, ou valores calculados.
-
-### 2. Uso na Trigger
-
-```java
-// 1. Buscar template
-Object templateObj = database.findOne("email_template__c", "{_id: 'signup_welcome'}");
-org.bson.Document template = (org.bson.Document) templateObj;
-
-// 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
-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
-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
-Email email = EmailBuilder.startingBlank()
-    .from(template.getString("fromName"), template.getString("fromEmail"))
-    .to(entity.name, entity.email)
-    .withSubject(subject)
-    .withHTMLText(content)
-    .buildEmail();
-
-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);
-```
-
-### 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 |
-
-### Propriedades do MailContext
-
-- `ctx.hostName` — servidor SMTP
-- `ctx.smtpPort` — porta SMTP
-- `ctx.authUser` — usuário de autenticação
-- `ctx.authPassword` — senha de autenticação
-
-> ⚠️ O envio de email deve acontecer **antes** do `entity.remove("email")` no Signup Pattern, para ter acesso ao endereço do destinatário.
-
----
-
-### ⚠️ Notas Importantes
-
-- 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)
-
----
-
-## Payment Gateway Pattern (Asaas + Public Endpoints)
-
-**Problema:** Implementar pagamento recorrente (assinatura) em um app Funifier sem backend proprio, usando apenas o frontend e a infraestrutura Funifier.
-
-**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.
-
-### Arquitetura
-
-```
-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)
-```
-
-### 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:
-
-```json
-{
-    "_id": "FITEVOLVE20",
-    "type": "PERCENTAGE",
-    "value": 20,
-    "maxUses": 100,
-    "usedCount": 0,
-    "active": true
-}
-```
-
-Tipos: `PERCENTAGE` (desconto %) e `FIXED` (desconto em R$).
-
-O endpoint `validate_coupon` valida e retorna o desconto. O endpoint `create_subscription` aplica o desconto no `value` da subscription.
-
-### 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
-}
-```
-
-| 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 |
-
-### Gestao de Assinatura
-
-| 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. |
-
-### Webhook: Eventos Importantes
-
-| 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. |
-
-### Seguranca do Webhook
-
-- 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
-
-### Padroes Groovy para Scripts de Pagamento
-
-```groovy
-// 1. Escapar $ (MongoDB operators e API keys)
-def d = String.valueOf((char)0x24)  // = "$"
-def setCmd = '{"' + d + 'set": {"extra.plan.type": "premium"}}'
-
-// 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))
-```
-
-### 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)
-
----
-
-## Database Strict Mode Pattern (BSON Types)
-
-**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.
-
-**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.
-
-### Exemplo sem strict (JSON puro — PERIGOSO para escrita)
-
-```
-GET /v3/database/player/ricardo
-```
-```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)
-
-```
-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`.
-
-### Regras de Uso
-
-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() } }
-   ```
-
-### Tipos BSON Comuns
-
-| 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" }` |
-
-### Helper JavaScript para Frontend
-
-```javascript
-// Criar campo date no formato BSON
-function bsonDate(date) {
-    return { $date: (date || new Date()).toISOString() };
-}
-
-// 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;
-}
-```
-
-### ⚠️ Impacto de NÃO usar strict
-
-- 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
-
-### Onde se aplica
-
-- **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)
-
----
-
-## App Version Pattern
-
-**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.
-
-**Solução:** Exibir a versão no rodapé de todas as páginas e gerenciá-la de forma consistente.
-
-### Convenção de Versionamento
-
-```
-MAJOR.MINOR
-```
-
-- **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`
-
-```javascript
-var CONFIG = {
-    // ... outras configs
-    VERSION: '1.0'
-};
-```
-
-#### 2. Expor no `$rootScope` (AngularJS)
-
-```javascript
-app.run(function($rootScope) {
-    $rootScope.appVersion = CONFIG.VERSION;
-});
-```
-
-#### 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}
-```
-
-- 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.
-
-**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!
-
----
-
-## 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.
-
----
-
-## Google OAuth Login Pattern
-
-**Problema:** Implementar login com Google em app Funifier sem backend próprio.
-
-**Solução:** Google Sign-In (GSI) no frontend + Public Endpoint no Funifier para verificação do token e criação/login do player.
-
-### Arquitetura
-
-```
-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
-```
-
-### 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:
-
-### Camada 1: Limpar dados no logout
-```javascript
-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);
-        }
-    });
-    // Limpar $rootScope
-    $rootScope.player = null;
-    $rootScope.profileData = null;
-    // ... etc
-}
-```
-
-### Camada 2: Limpar dados no login (se usuário diferente)
-```javascript
-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:
-
-```
-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`:
-```javascript
-$http({
-    method: 'POST',
-    url: API + '/v3/database/collection__c/aggregate?q=userId:"' + userId + '"&strict=true',
-    headers: { 'Authorization': 'Bearer ' + token, 'Range': 'items=0-19' },
-    data: [{ $sort: { created: -1 } }]
-});
-```
-
-**Defense-in-depth:** Ainda é boa prática verificar userId client-side:
-```javascript
-results = results.filter(function(r) { return r.userId === currentUserId; });
-```
-
----
-
-## CRM Integration Pattern (Cross-Gamification)
-
-**Problema:** Integrar app de produto (gamificação A) com CRM Funifier (gamificação B) para criar leads automaticamente no signup.
-
-**Solução:** Trigger na gamificação do produto faz HTTP POST para a gamificação do CRM.
-
-### Arquitetura
-
-```
-Gamificação "Produto" (Orvya Fitness)
-    |
-    → Trigger after_create (entity: player)
-        |
-        → HTTP POST para Gamificação "CRM" (/v3/database/person + /v3/database/deal)
-```
-
-### Lições Importantes
-
-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
-
----
-
-## Player Management Pattern
-
-### Leitura e Escrita de Player
-
-```groovy
-// Ler player
-Player p = manager.getPlayerManager().findById(playerId)
-
-// Modificar
-p.extra.plan = [type: "premium"]
-
-// Salvar (upsert)
-manager.getPlayerManager().insert(p)
-```
-
-### Campos obrigatórios no POST /v3/player
-
-Ao atualizar player via `POST /v3/player` com apenas `_id` + `extra`, os campos `name` e `email` são APAGADOS. **Sempre incluir:**
-
-```json
-{
-    "_id": "user@email.com",
-    "name": "Nome do Usuário",
-    "email": "user@email.com",
-    "extra": { ... }
-}
-```
-
-### Player.image Structure
-
-Para salvar foto do player, usar a estrutura completa:
-
-```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 }
-    }
-}
-```
-
-Os campos `size`, `width`, `height`, `depth` são obrigatórios (mesmo que 0) — Funifier espera essa estrutura.
-
-### PlayerManager — Métodos Corretos
-
-| 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) |
-| `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);
-```
-
-### 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
-
----
-
-## OpenAI Realtime API — Voice/Video Call 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
-
-### 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`
-
-### ⚠️ CRITICAL: Tools DEVEM ser registradas na criação da chave efêmera
-
-**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:** Incluir `tools` no body do `POST /v1/realtime/client_secrets`:
-
-```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' } }
-        }
-    })
-});
-```
-
-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
-
-Sempre incluir uma tool `end_call` para que a IA possa desligar a ligação quando a conversa terminar naturalmente:
-
-```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: [] }
-    }
-];
-```
-
-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
-    }
-    break;
-```
-
-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.
-```
-
-### 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
-
----
-
-## Funifier API — Endpoints Corretos (CRÍTICO)
-
-**Problema:** Usar endpoints errados causa perda silenciosa de dados — campos desaparecem, queries retornam vazio, e é difícil debugar.
-
-### Player (entidade nativa)
-
-O `player` é uma entidade nativa do Funifier, **NÃO** uma collection do `/v3/database`.
-
-| 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}` | — |
-
-**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);
-});
-```
-
-**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());
-```
-
-### Database (collections customizadas `__c`)
-
-O endpoint `/v3/database` serve para collections customizadas (ex: `profile__c`, `signup__c`).
-
-| 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!) |
-
-**⚠️ 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.
-
-**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;
-    });
-}
-```
-
-### strict=true (BSON types)
-
-- 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)
-
----
-
-## Cache-Busting em SPAs (Netlify)
-
-**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).
-
-**Solução:** Query string com versão em todos os `<script>` e `<link>`:
-
-```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):
-```
-/*.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}
-```
-
-### Alteração via Trigger (server-side)
-
-Para alterar a senha via trigger (ex: admin reset), usar BCrypt:
-
-```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)
+# Patterns (Design Patterns)
+
+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
+
+---
+
+## Signup Pattern
+
+**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.
+
+**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.
+
+### Arquitetura
+
+```
+Frontend (público) → PUT /v3/database/signup__c → Trigger before_update → Cria Player
+```
+
+> ⚠️ **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:
+
+```
+1. Concatenar: ApiKey + ":"
+2. Codificar em Base64
+3. Prefixar com "Basic "
+4. Usar no header: Authorization: Basic <token>
+```
+
+**Exemplo (JavaScript):**
+```javascript
+var BASIC_TOKEN = 'Basic ' + btoa(API_KEY + ':');
+```
+
+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:
+
+| Campo | Valor |
+|-------|-------|
+| Name | Signup Handler |
+| Entity | `signup__c` |
+| Event | `before_update` |
+
+**Script:**
+```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) {
+        entity.message = "Email deve ser informado para se cadastrar!";
+    }
+    else if(entity.name == null || entity.name.trim().length() == 0) {
+        entity.message = "Nome deve ser informado para se cadastrar!";
+    }
+    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
+            Player p = JsonUtil.fromJson(JsonUtil.toJson(entity), Player.class);
+            p.password = com.funifier.engine.util.BCrypt.hashpw(
+                entity.password, com.funifier.engine.util.BCrypt.gensalt()
+            );
+            p.setCreated(new Date());
+            manager.getPlayerManager().insert(p);
+            entity.message = "Usuário registrado com sucesso!";
+            entity.status = "OK";
+        }
+    }
+    // Remove campos sensíveis antes de salvar no signup__c
+    entity.remove("password");
+    entity.remove("email");
+}
+```
+
+### Uso no Frontend
+
+```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"
+});
+```
+
+### Extensões Comuns
+
+- **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
+
+---
+
+## Email Template Pattern
+
+**Problema:** Enviar emails automáticos a partir de triggers, com conteúdo editável pelo administrador sem alterar código.
+
+**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.
+
+### Arquitetura
+
+```
+email_template__c (templates editáveis) → Trigger (busca template + parse Mustache) → SMTP (envia)
+```
+
+### 1. Estrutura do Template (`email_template__c`)
+
+Cada template é um documento na coleção `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"
+}
+```
+
+**Variáveis Mustache:** Usar `{{campo}}` no subject e content. Podem ser campos da entity, do player, ou valores calculados.
+
+### 2. Uso na Trigger
+
+```java
+// 1. Buscar template
+Object templateObj = database.findOne("email_template__c", "{_id: 'signup_welcome'}");
+org.bson.Document template = (org.bson.Document) templateObj;
+
+// 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
+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
+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
+Email email = EmailBuilder.startingBlank()
+    .from(template.getString("fromName"), template.getString("fromEmail"))
+    .to(entity.name, entity.email)
+    .withSubject(subject)
+    .withHTMLText(content)
+    .buildEmail();
+
+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);
+```
+
+### 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 |
+
+### Propriedades do MailContext
+
+- `ctx.hostName` — servidor SMTP
+- `ctx.smtpPort` — porta SMTP
+- `ctx.authUser` — usuário de autenticação
+- `ctx.authPassword` — senha de autenticação
+
+> ⚠️ O envio de email deve acontecer **antes** do `entity.remove("email")` no Signup Pattern, para ter acesso ao endereço do destinatário.
+
+---
+
+### ⚠️ Notas Importantes
+
+- 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)
+
+---
+
+## Payment Gateway Pattern (Asaas + Public Endpoints)
+
+**Problema:** Implementar pagamento recorrente (assinatura) em um app Funifier sem backend proprio, usando apenas o frontend e a infraestrutura Funifier.
+
+**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.
+
+### Arquitetura
+
+```
+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)
+```
+
+### 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:
+
+```json
+{
+    "_id": "FITEVOLVE20",
+    "type": "PERCENTAGE",
+    "value": 20,
+    "maxUses": 100,
+    "usedCount": 0,
+    "active": true
+}
+```
+
+Tipos: `PERCENTAGE` (desconto %) e `FIXED` (desconto em R$).
+
+O endpoint `validate_coupon` valida e retorna o desconto. O endpoint `create_subscription` aplica o desconto no `value` da subscription.
+
+### 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
+}
+```
+
+| 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 |
+
+### Gestao de Assinatura
+
+| 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. |
+
+### Webhook: Eventos Importantes
+
+| 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. |
+
+### Seguranca do Webhook
+
+- 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
+
+### Padroes Groovy para Scripts de Pagamento
+
+```groovy
+// 1. Escapar $ (MongoDB operators e API keys)
+def d = String.valueOf((char)0x24)  // = "$"
+def setCmd = '{"' + d + 'set": {"extra.plan.type": "premium"}}'
+
+// 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))
+```
+
+### 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)
+
+---
+
+## Database Strict Mode Pattern (BSON Types)
+
+**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.
+
+**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.
+
+### Exemplo sem strict (JSON puro — PERIGOSO para escrita)
+
+```
+GET /v3/database/player/ricardo
+```
+```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)
+
+```
+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`.
+
+### Regras de Uso
+
+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() } }
+   ```
+
+### Tipos BSON Comuns
+
+| 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" }` |
+
+### Helper JavaScript para Frontend
+
+```javascript
+// Criar campo date no formato BSON
+function bsonDate(date) {
+    return { $date: (date || new Date()).toISOString() };
+}
+
+// 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;
+}
+```
+
+### ⚠️ Impacto de NÃO usar strict
+
+- 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
+
+### Onde se aplica
+
+- **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)
+
+---
+
+## App Version Pattern
+
+**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.
+
+**Solução:** Exibir a versão no rodapé de todas as páginas e gerenciá-la de forma consistente.
+
+### Convenção de Versionamento
+
+```
+MAJOR.MINOR
+```
+
+- **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`
+
+```javascript
+var CONFIG = {
+    // ... outras configs
+    VERSION: '1.0'
+};
+```
+
+#### 2. Expor no `$rootScope` (AngularJS)
+
+```javascript
+app.run(function($rootScope) {
+    $rootScope.appVersion = CONFIG.VERSION;
+});
+```
+
+#### 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}
+```
+
+- 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.
+
+**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!
+
+---
+
+## 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.
+
+---
+
+## Google OAuth Login Pattern
+
+**Problema:** Implementar login com Google em app Funifier sem backend próprio.
+
+**Solução:** Google Sign-In (GSI) no frontend + Public Endpoint no Funifier para verificação do token e criação/login do player.
+
+### Arquitetura
+
+```
+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
+```
+
+### 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:
+
+### Camada 1: Limpar dados no logout
+```javascript
+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);
+        }
+    });
+    // Limpar $rootScope
+    $rootScope.player = null;
+    $rootScope.profileData = null;
+    // ... etc
+}
+```
+
+### Camada 2: Limpar dados no login (se usuário diferente)
+```javascript
+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:
+
+```
+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`:
+```javascript
+$http({
+    method: 'POST',
+    url: API + '/v3/database/collection__c/aggregate?q=userId:"' + userId + '"&strict=true',
+    headers: { 'Authorization': 'Bearer ' + token, 'Range': 'items=0-19' },
+    data: [{ $sort: { created: -1 } }]
+});
+```
+
+**Defense-in-depth:** Ainda é boa prática verificar userId client-side:
+```javascript
+results = results.filter(function(r) { return r.userId === currentUserId; });
+```
+
+---
+
+## CRM Integration Pattern (Cross-Gamification)
+
+**Problema:** Integrar app de produto (gamificação A) com CRM Funifier (gamificação B) para criar leads automaticamente no signup.
+
+**Solução:** Trigger na gamificação do produto faz HTTP POST para a gamificação do CRM.
+
+### Arquitetura
+
+```
+Gamificação "Produto" (Orvya Fitness)
+    |
+    → Trigger after_create (entity: player)
+        |
+        → HTTP POST para Gamificação "CRM" (/v3/database/person + /v3/database/deal)
+```
+
+### Lições Importantes
+
+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
+
+---
+
+## Player Management Pattern
+
+### Leitura e Escrita de Player
+
+```groovy
+// Ler player
+Player p = manager.getPlayerManager().findById(playerId)
+
+// Modificar
+p.extra.plan = [type: "premium"]
+
+// Salvar (upsert)
+manager.getPlayerManager().insert(p)
+```
+
+### Campos obrigatórios no POST /v3/player
+
+Ao atualizar player via `POST /v3/player` com apenas `_id` + `extra`, os campos `name` e `email` são APAGADOS. **Sempre incluir:**
+
+```json
+{
+    "_id": "user@email.com",
+    "name": "Nome do Usuário",
+    "email": "user@email.com",
+    "extra": { ... }
+}
+```
+
+### Player.image Structure
+
+Para salvar foto do player, usar a estrutura completa:
+
+```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 }
+    }
+}
+```
+
+Os campos `size`, `width`, `height`, `depth` são obrigatórios (mesmo que 0) — Funifier espera essa estrutura.
+
+### PlayerManager — Métodos Corretos
+
+| 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) |
+| `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);
+```
+
+### 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
+
+---
+
+## OpenAI Realtime API — Voice/Video Call 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
+
+### 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`
+
+### ⚠️ CRITICAL: Tools DEVEM ser registradas na criação da chave efêmera
+
+**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:** Incluir `tools` no body do `POST /v1/realtime/client_secrets`:
+
+```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' } }
+        }
+    })
+});
+```
+
+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
+
+Sempre incluir uma tool `end_call` para que a IA possa desligar a ligação quando a conversa terminar naturalmente:
+
+```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: [] }
+    }
+];
+```
+
+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
+    }
+    break;
+```
+
+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.
+```
+
+### 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
+
+---
+
+## Funifier API — Endpoints Corretos (CRÍTICO)
+
+**Problema:** Usar endpoints errados causa perda silenciosa de dados — campos desaparecem, queries retornam vazio, e é difícil debugar.
+
+### Player (entidade nativa)
+
+O `player` é uma entidade nativa do Funifier, **NÃO** uma collection do `/v3/database`.
+
+| 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}` | — |
+
+**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);
+});
+```
+
+**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());
+```
+
+### Database (collections customizadas `__c`)
+
+O endpoint `/v3/database` serve para collections customizadas (ex: `profile__c`, `signup__c`).
+
+| 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!) |
+
+**⚠️ 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.
+
+**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;
+    });
+}
+```
+
+### strict=true (BSON types)
+
+- 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)
+
+---
+
+## Cache-Busting em SPAs (Netlify)
+
+**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).
+
+**Solução:** Query string com versão em todos os `<script>` e `<link>`:
+
+```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):
+```
+/*.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}
+```
+
+### Alteração via Trigger (server-side)
+
+Para alterar a senha via trigger (ex: admin reset), usar BCrypt:
+
+```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)