# 13 - Dívidas Técnicas

> Dívidas conhecidas, classificadas por severidade e com o impacto explicado. "Crítica" = risco de segurança/perda de dados ou bloqueio de negócio; "Alta" = alto custo de manutenção ou risco latente; "Média" = atrito recorrente; "Baixa" = arrumação.
>
> Relacionados: [12 - Armadilhas](12-armadilhas-conhecidas.md) (as que já mordem), [14 - Melhorias Futuras](14-melhorias-futuras.md), [09 - Configurações](09-configuracoes.md).

## Crítica

### DT-C1. Credenciais e segredos hardcoded no código versionado
- **O quê:** senha do PostgreSQL de produção e credenciais MySQL (`MainBoth.php`, `SettingsDB`/`SettingsInteligencia`); credenciais MySQL remotas em claro em `CuradoriaAlertasTmsLab.php`; segredo do JWT (`PASSDECODELOGIN = 'g@laxiakey'`); chave JWT do Docuseal no construtor; canal + secret do Scaledrone replicados em ≥3 arquivos; tokens de bypass de API (`goldieApi789574`, `tecnosoft789574`, `connection789574`, `gnesistk`); API key do Google Maps.
- **Impacto:** qualquer pessoa com acesso ao repositório (ou a um dump dele) tem as chaves do reino — banco de produção, forjar JWT válido de qualquer usuário/tenant, publicar no realtime, chamar APIs internas.
- **Direção:** externalizar para variáveis de ambiente/secret manager; rotacionar tudo que já esteve no histórico do git.

### DT-C2. JWT sem verificação de expiração/device e com segredo estático fraco
- **O quê:** `authorization()` não valida `exp` por conta própria (só se o token trouxer), o binding de IP/OS/browser está **comentado**, e o segredo é uma string curta estática compartilhada por todo o Galaxia.
- **Impacto:** um token vazado é válido indefinidamente e de qualquer lugar; o segredo é adivinhável/uniforme entre ambientes.
- **Direção:** segredo forte por ambiente, `exp` obrigatório e curto + refresh, reativar (ou remover conscientemente) o binding.

### DT-C3. Webhooks WhatsApp inbound sem verificação de assinatura
- **O quê:** `webhooks/whatsapp/evolution/` e `Mensageria/Central/Webhook` apenas logam o payload cru e respondem 200, sem validar origem.
- **Impacto:** qualquer um pode postar eventos forjados; quando o processamento (hoje comentado) for ligado, vira vetor de injeção de mensagens/estado.
- **Direção:** migrar para a infra genérica `webhook_endpoints` + `InboundHandler` (HMAC), como a IntegracaoWms já faz.

## Alta

### DT-A1. Divergência de path `www/galaxia` vs `www/genesis`
- **O quê:** `crons/auto.sh` aponta `CRON_DIR=/home/goldie/www/galaxia/crons` e `system/o2auth.php` referencia `/home/goldie/www/galaxia/...`, enquanto o repositório é `www/genesis`.
- **Impacto:** o crontab pode estar agendando scripts de **outra cópia** do projeto; OAuth pode ler segredos de outro checkout. Comportamento em produção pode não corresponder ao código que você edita.
- **Direção:** confirmar qual árvore está de fato em produção (`crontab -l`), unificar os paths.

### DT-A2. `main` congelada e branch única de trabalho
- **O quê:** todo o desenvolvimento vive em `dev_team`; `main` está centenas de commits atrás, congelada após um revert (abril/2026). Não há ambiente de integração separado nem tag de release.
- **Impacto:** sem baseline estável para comparar/rollback; reviews não podem usar `main...HEAD`; um erro em `dev_team` vai direto para produção (deploy = pull).
- **Direção:** definir uma estratégia de release (tags ou branch de produção real) e proteger o que vai para o ar.

### DT-A3. Duas gerações (V1/V2) e duas classes `Connect`/`Session` coexistindo
- **O quê:** Inteligências V1 vs Sondas V2; `Base_config\Core\Connect` vs `Galaxia\_Controladores\Connect`; `Session` vs `SessionGalaxia`; sistema `antigo/` inteiro em paralelo.
- **Impacto:** curva de aprendizado alta, risco de usar a classe errada, comportamento sutilmente diferente entre caminhos. Este manual existe em parte por causa disso.
- **Direção:** migração incremental para V2 (já em curso); documentar claramente qual usar (feito aqui).

### DT-A4. Fallbacks de tenant hardcoded no ORM
- **O quê:** `block_empresa_id` cai em `'3'` quando a sessão não resolve; cliente `7` é global; `p_block = 22` hardcoded na chamada da fila de separação; `bcustomerid2 = 7` no filtro de leitura.
- **Impacto:** sessão incompleta grava/lê no tenant errado **sem erro**; valores mágicos espalhados dificultam auditoria de isolamento.
- **Direção:** falhar explicitamente quando o tenant não resolve, em vez de fallback silencioso; centralizar as constantes de tenant global.

### DT-A5. Método `query()` inexistente chamado pelas Sondas do Central2
- **O quê:** `Central2/Sondas/*` chamam `$this->query($sql, $params)`, mas `ModelInteligencia` não tem esse método (as primitivas são `iniciarQuery`/`queryDinamica`/`executarQueryFuncao`).
- **Impacto:** essas leituras resolveriam para `null`. Só não explodiu porque Central2 é dev-only e os caminhos não foram exercitados em produção.
- **Direção:** adicionar o método/trait ausente ou corrigir as chamadas antes de promover o Central2.

## Média

### DT-M1. Sem runner de migrations nem registro de versão
- **O quê:** migrations são `.sql` aplicados à mão; não existe `schema_migrations`. A segurança depende de idempotência disciplinada.
- **Impacto:** não há como saber o que já foi aplicado num banco; risco de estado divergente entre dev e prod.
- **Direção:** um runner simples que registre versões aplicadas (mantendo a idempotência).

### DT-M2. Três implementações paralelas de WhatsApp (Evolution)
- **O quê:** webhook cru, canal OTP e Central de Mensageria, com lógicas de envio divergentes (cURL vs Guzzle, normalização diferente).
- **Impacto:** manutenção fragmentada; corrigir um bug de envio exige mexer em três lugares.
- **Direção:** consolidar no conector da Central de Mensageria e fazer o OTP consumi-lo.

### DT-M3. Testes sem framework e templates ausentes
- **O quê:** sem PHPUnit; testes são scripts standalone. A skill `genesis-tests` cita `templates/UnitTest.php.tpl`/`IntegrationTest.php.tpl` que **não existem**.
- **Impacto:** sem relatório agregado, cobertura ou CI; onboarding de teste confuso pela doc desatualizada.
- **Direção:** um runner mínimo que agregue os scripts; criar/remover a referência aos templates.

### DT-M4. Documentação interna divergente do código
- **O quê:** a skill `genesis-views-i18n` descreve `show()` com chaves snake_case, mas a implementação real usa `md5(texto PT)` com auto-harvest. `documentacoes/` mistura conceito atual e legado.
- **Impacto:** IA/dev seguindo a doc antiga escreve i18n errado.
- **Direção:** este manual é a fonte única; alinhar as skills a ele.

### DT-M5. Sem `flock` nos crons de frequência alta
- **O quê:** crons como `crompedidos_logistica.php` (a cada minuto) não têm trava de execução única.
- **Impacto:** execuções sobrepostas se um ciclo demora mais que o intervalo — trabalho duplicado.
- **Direção:** `flock` ou lock por tabela nos crons de 1 minuto.

### DT-M6. Redundâncias e duplicações de sinais
- **O quê:** `Processos/GerenciarB` vs `Gerenciar`, `Servicos/Forms` vs `Formularios`, `Servicos/Etapas` vs `ServicosEtapas`, `Galaxia/Diagramas` vs `DiagramasV1`.
- **Impacto:** dúvida sobre qual é o vivo; risco de corrigir o errado.
- **Direção:** identificar o canônico, marcar/remover o obsoleto.

### DT-M7. Notificação de falha de query acoplada
- **O quê:** toda falha de query dispara `sendFail()` (notificação para a equipe) e grava em `gc_queries_request`.
- **Impacto:** ruído; acoplamento do ORM a um canal de notificação específico.
- **Direção:** logging estruturado com níveis, desacoplado do model.

## Baixa

### DT-B1. Raiz do repositório poluída
- **O quê:** ~40 arquivos soltos (`debug_*.php`, `scratch_*.php`, `test_*.php`, dumps `.txt`/`.json`, `image.png`, `tailwind.config copy.js`, o arquivo `tash show -p stash@{5}`), pasta `super/` vazia.
- **Impacto:** confunde navegação; alguns conectam direto no `dev_gx_goldie`.
- **Direção:** mover para fora do repo ou `.gitignore`; consolidar one-offs úteis em `tests/`.

### DT-B2. Grafias herdadas em nomes de Sinal
- **O quê:** `Intinerarios`, `DistibuicaoPedidos`, `Contasbancos`.
- **Impacto:** cosmético; **não corrigir** sem migrar rotas (quebra URLs).

### DT-B3. Inconsistência de versão do Tailwind
- **O quê:** Tailwind v3 (devDep) + v4 CLI (dep) + `tailwind.config copy.js`.
- **Impacto:** build de CSS ambíguo.
- **Direção:** fixar uma versão, remover a cópia de config.

### DT-B4. `GalaxiaUser` aponta para a entity errada
- **O quê:** `GalaxiaUser` tem `entity='gx_permissoes'` (copy-paste de `GalaxiaPermissoes`).
- **Impacto:** latente; qualquer uso de `GalaxiaUser` como model de usuário está errado.
- **Direção:** corrigir a entity ou remover a classe se não usada.

### DT-B5. Débito interno já mapeado no Designacoes
- **O quê:** `Designacoes/refatorar.md` lista ~500 linhas a mover do controller para Laboratórios; `PENDENCIAS.md` tem 11 itens.
- **Direção:** seguir o plano já escrito ao evoluir o sinal.