# 12 - Armadilhas Conhecidas > Cada item desta lista **já causou bug real** ou horas de depuração neste projeto. Leia antes de mexer na área correspondente. Formato: sintoma → causa → solução → prevenção. > > Relacionados: [11 - Guia de Manutenção](11-guia-de-manutencao.md), [05 - Banco de Dados](05-banco-de-dados.md), [03 - Regras de Negócio](03-regras-de-negocio.md). ## ORM / ModelInteligencia (Sondas) ### 1. `find()` sem `->fetch()` é sempre truthy - **Sintoma:** um guard `if ($sonda->find(...))` passa sempre, mesmo sem registro no banco. - **Causa:** `find()` retorna o próprio objeto (fluente), não o resultado. Só `->fetch()` materializa. - **Solução:** `if ($sonda->find(...)->fetch())`. - **Prevenção:** em code review, todo `find(` sem `fetch(` na mesma expressão é suspeito. ### 2. `findById()`/`data()` vêm embrulhados em array - **Sintoma:** acessar `$obj->campo` falha ou retorna null depois de `findById()`. - **Causa:** na Sonda V2, `findById()` e `data()` retornam `[obj]` (array com um objeto). `findAny()` e ModelDb **não** embrulham. - **Solução:** `$registro = $sonda->findById($id)[0] ?? null;` - **Prevenção:** conhecer a assimetria; não assumir consistência entre métodos de leitura. ### 3. `$required` como lista quebra o `create()` - **Sintoma:** insert de Sonda V2 falha silenciosamente ou com erro obscuro. - **Causa:** declarar `$required` com lista de campos ativa validação que conflita com o fluxo de create. - **Solução:** manter `$required` vazio na Sonda e validar no Validator do Laboratório. ### 4. `update()` retorna rowCount — use como guard CAS - **Nota:** `update()` retorna o número de linhas afetadas. Isso permite *compare-and-swap*: `UPDATE ... WHERE status = 'pendente'` e checar `rowCount === 1` para garantir transição atômica de status. Se você ignora o retorno, perde a proteção contra corrida. ### 5. Colunas JSON voltam como string crua - **Sintoma:** `$config->is_retira` é sempre truthy/errado; iterar sobre coluna JSON falha. - **Causa:** o `prepareObject` da Sonda **não** decodifica colunas JSON — elas chegam como string. - **Solução:** `json_decode($obj->configuracoes ?? '{}')` explicitamente em todo ponto de leitura. ### 6. V1 `__get` mágico - **Sintoma:** em Inteligências V1, `$obj->campo` funciona "de graça" mas `$obj->data` se comporta estranho. - **Causa:** `ModelInteligencia` tem `__get` que resolve `$this->data->$name`. Para pegar o objeto completo use o **método** `$obj->data()`. ### 7. Tabela nova sem colunas de auditoria/block quebra o `create()` - **Sintoma:** `create()` falha só em teste de integração (nunca em análise estática). - **Causa:** o framework injeta colunas de auditoria e `block_*` em todo insert. Se a tabela não as tem, o SQL quebra. - **Solução:** toda migration de tabela com escrita via Sonda espelha o conjunto completo de colunas de `wms_movimentos` (auditoria + block). - **Prevenção:** rodar teste de integração de create antes de considerar a migration pronta. As colunas `block_*` **não** levam `DEFAULT 1` — o framework injeta o valor. ## Banco de dados / ERP legado ### 8. `pedidos.comodato` é NULL em quase tudo (ERP) - **Sintoma:** filtro `comodato = 0` faz sumir praticamente todos os pedidos. - **Causa:** NULL não é igual a 0 em SQL. - **Solução:** `COALESCE(comodato, 0) = 0`. ### 9. `numero_pedido` NÃO é único (ERP) - **Sintoma:** guard ou join por `numero_pedido` pega o pedido errado. - **Causa:** o ERP reusa números entre empresas/anos. - **Solução:** cruzar sempre por `codigomd5` (ERP) ↔ `importacao_id` (Genesis). ### 10. Timestamps do ERP são UTC - **Sintoma:** horários exibidos com 3h de diferença. - **Solução:** converter com `DateTime` + timezone `America/Sao_Paulo`; **não** usar `strtotime`/`date` cru. ### 11. Nunca raw SQL para writes - **Regra:** writes em lote usam o `update()` do model, nunca `Connect::getInstance()` com SQL manual — o SQL manual pula multi-tenant, auditoria e block, e já causou dados órfãos. ## Frontend / Views ### 12. Cache de JS: dois regimes diferentes - **Sintoma:** editou o JS e o navegador continua servindo o antigo. - **Causa/Solução dupla:** - Views renderizadas por `GalaxiaRoute::visual()` — o JS pareado é versionado **automaticamente** via `filemtime`; basta salvar o arquivo. - Modais do módulo de **metas** (e outros com `