funifier-mcp 0.1.0 → 0.2.0

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

@@ -0,0 +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)