# Débitos técnicos e de segurança Registro dos itens conhecidos que foram deliberadamente adiados, com o motivo e o momento previsto para tratá-los. Um item só sai desta lista quando resolvido em produção — não quando corrigido no código. Atualizado em 16/08/2026. > ## DECISÃO PERMANENTE de 11/09/2026: nada mais é feito em produção até a migração final > > *"nao faremos nenhuma modificação no servidor de produção, pule estas etapas e > faremos apenas na mingração final, apos todas as validações"* > > Isto responde, de uma vez, a **todo** item deste registro cuja única pendência é > "falta aplicar em produção" — são **doze**, e nenhum deles precisa ser trazido > de volta como pergunta. Eles ficam prontos no código, validados aqui, e entram > **juntos** na migração final. > > **A ordem é essa de propósito:** validar primeiro, aplicar depois. Produção está > congelada desde 23/08/2026, e o que mudou hoje é que o congelamento deixou de > ser "até alguém decidir" e passou a ter um destino — a janela da migração. > > **O que isso NÃO muda:** o que está ativo em produção continua ativo, e o > registro continua dizendo qual é. Em particular a rota > `/autenticacao/migrar-senhas`, as oito credenciais em texto claro no código > implantado, e o `local.php` inexistente. Adiar com data não é resolver, e este > parágrafo não existe para fazer parecer que resolveu. > > **Para quem for executar a janela:** `docs/dia0-remediacao-producao.md` tem os > passos 3 a 7, na ordem, com a dependência `local.php` antes do deploy. Os passos > 1 e 2 já foram executados em 21/08/2026. --- ## Adiados para a Fase 1 (migração MySQL → PostgreSQL) Decisão do responsável pelo projeto em 15/08/2026: tratar junto com a migração de banco, em vez de numa janela separada agora. ### D1 — Arquivos com dados pessoais expostos no webroot — PREPARADO, lido em 05/10/2026 > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito sem marca de estado, e o corpo diz que ele está pronto no código, à espera só do passo em produção na janela da migração final. Falta: o deploy do passo 4 do dia 0 na migração final; até lá, a próxima exportação do Relatório de Clientes recria o arquivo em public/. `public/clientes.txt` (nomes e telefones de clientes), `public/log_scripts.txt`, `public/logs/` e `public/phpinfofile.php` ficam dentro do webroot e são alcançáveis por URL pública no servidor de produção. *Correção de 15/08/2026:* a primeira versão deste registro atribuía a exposição ao `RewriteCond %{REQUEST_FILENAME} -s` do `public/.htaccess`. Está errado — a produção usa **nginx**, que não lê `.htaccess`. O mecanismo real é o `try_files $uri ... /index.php` da configuração do nginx, que serve qualquer arquivo existente antes de cair no PHP. A conclusão não muda: os arquivos são públicos. **Situação:** corrigido no código (as exportações não gravam mais em disco e os logs foram para `data/logs/`) **e a exposição foi estancada em produção em 21/08/2026** — os quatro arquivos estão em `~/quarentena-dia0/20260821-141226`, as URLs devolvem 404, e a apuração do passo 2 achou **zero acesso externo** no período retido pelos logs (14 dias). > **Correção de 11/09/2026:** esta linha dizia *"pendente em produção — o deploy > ainda não foi feito, então os arquivos continuam no servidor"*, e isso deixou de > ser verdade em 21/08. Duas fontes independentes registram a remoção com data: > o quadro de estado de `docs/dia0-remediacao-producao.md` e a lista > `$explicadas` de `scripts/conferir-referencias-docs.php`, que diz *"removido da > producao (D1)"* para os quatro caminhos. Só este parágrafo não tinha sido > atualizado. **E por isso ele não fecha:** a limpeza foi de uma vez, e o código **implantado** continua sendo o antigo — aquele que grava a exportação em `public/`. Enquanto o passo 4 não acontecer, a próxima exportação do Relatório de Clientes recria o arquivo. A quarentena de 21/08 estancou o que estava exposto; ela não torna a correção durável. **Ao resolver:** os passos 1 e 2 de `docs/dia0-remediacao-producao.md` estão feitos. O que falta é o deploy do passo 4, e ele entra na migração final por decisão de 11/09/2026 — ver o aviso no topo deste documento. **Ao resolver:** seguir `docs/dia0-remediacao-producao.md`, passos 1 e 2. O passo 2 apura nos logs do nginx se houve acesso externo, o que define se existe dever de notificação à ANPD. ### D2 — Endpoint público de migração de senhas — PREPARADO, lido em 05/10/2026 > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito sem marca de estado, e o corpo diz que ele está pronto no código, à espera só do passo em produção na janela da migração final. Falta: o deploy na migração final, com o bloqueio de nginx do passo 6 do dia 0; até lá, a rota continua ativa em produção. `/autenticacao/migrar-senhas` responde sem autenticação e sobrescreve o hash de senha de todos os usuários ativos de uma vez. Era um script de uso único da migração para PHP 8.3 que ficou publicado. **Situação:** rota e ação removidas do código (commit `3a07943`), **ativa em produção** até o deploy. **Ao resolver:** o deploy já elimina. Há um bloqueio de nginx pronto no passo 6 do documento de remediação, e ele entra na **migração final** por decisão de 11/09/2026 — até lá a rota continua ativa, e este débito é o registro disso. Ver o aviso no topo deste documento. ### D3 — Rotação das oito credenciais — PARCIAL em 03/10/2026: a chave do Asaas saiu do código; a rotação das oito continua sendo do dono — PREPARADO, lido em 05/10/2026 — PREPARADO em 10/10/2026: o OneSignal já usa a chave nova quando ela vier > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito como parcial, e o corpo diz que ele está pronto no código, à espera só do passo em produção na janela da migração final. Falta: rotacionar as credenciais no passo 5 do dia 0 e pôr a chave nova do Asaas no local.php de produção; Yungas, OneSignal e SMS adiados. Estavam em texto claro no código e portanto existem em todo backup e snapshot anterior a 15/08/2026. Movê-las para `config/autoload/local.php` não as torna secretas retroativamente. | Credencial | Observação ao rotacionar | |---|---| | Senha MySQL (`franquiabv`) | Mapear consumidores antes (`SHOW PROCESSLIST`): o sistema de BI acessa o banco direto e vai quebrar | | OneSignal — app mobile | | | OneSignal — web push | | | SMTP `franquiabv@barbeariavip.com.br` | | | Bearer token Zoomtec | O JWT não tem `exp`; não expira sozinho, precisa ser reemitido pelo fornecedor | | Usuário/senha da API iAgente SMS | Trafegam na query string da URL, então estão também nos logs do provedor | | **Chave de API do Asaas** | `module/ISBase/src/Util/Asaas.php`, no construtor -- até 03/10/2026; desde então, o `asaas.api_key` do `local.php` (ver "O conserto", abaixo). É a de **produção** (`api.asaas.com`), não sandbox — move dinheiro | | **API key, e-mail e senha do Yungas** | `module/ISApi/src/Service/CronJobService.php`, em `yungasAutenticacao`. A senha está em texto puro, ao lado de um e-mail nominal do fornecedor | **Eram seis até 31/08/2026, e são oito.** As duas últimas apareceram ao aplicar os tempos limite do **D67** — não por uma varredura de segredos, mas por abrir os arquivos por outro motivo. Nenhuma das duas estava no passo 5 do documento de remediação, que agora as traz. Vale a diferença de natureza: a do Asaas é a de **produção de um meio de pagamento**, e a do Yungas inclui **uma senha**, não só um token — se ela for reaproveitada em outro lugar pelo fornecedor, o estrago passa do Yungas. #### A do Yungas: DECIDIDO em 03/09/2026 — adiada, e talvez desnecessária > *"colocar yungas como débito técnico, não é prioritário e talvez seja > descontinuado"* A oitava linha sai da fila do que precisa acontecer antes do corte. A integração pode ser descontinuada, e trocar credencial de um serviço que vai sair é trabalho jogado fora. **O código já foi limpo no mesmo dia** (**D89**): os três valores saíram do `CronJobService` para `config/autoload/local.php`, e a rotina passou a registrar no log quando não há credencial — em vez de rodar em silêncio sobre nenhuma unidade. *Isso impede cópias novas; não desfaz as antigas.* Os valores continuam válidos no fornecedor e continuam no histórico do git. **Se a integração for descontinuada, o certo é revogar a conta** — melhor que rotacionar, porque credencial revogada não vale nem no histórico. As outras sete continuam como estavam. E há uma discrepância que fica registrada em vez de corrigida em silêncio: a tabela do passo 5 do dia 0 tinha **cinco** linhas contra as seis daqui — faltava lá a do iAgente SMS. Pode ser deliberado, já que o SMS está congelado por instrução sua; não presumi, e a acrescentei dizendo de onde veio. #### O conserto, em 03/10/2026: a chave do Asaas saiu do código (SEGREDOS) `ISBase\Util\Asaas` passou a receber a url e a chave no construtor, e quem as passa é a fábrica do `FranquiaService`, lendo a seção `asaas` do `local.php` (`api_key`, e `url`, que vazia vale a de produção, `https://api.asaas.com/v3/`). As duas rotinas de faturas constroem o cliente num lugar só, `FranquiaService::asaas()`. **Sem chave, a construção lança** -- antes de qualquer `curl`, com a mensagem dizendo qual chave falta. Era a última das oito ainda escrita no código: o portão de segredos, agora sem diferenciar maiúscula, não acha outra. **O efeito em cada ambiente:** a máquina de desenvolvimento, o CI e o ambiente de teste deixaram de falar com a conta de produção do Asaas -- nenhum `local.php` deles tem a chave, e nenhum deve ter. Em produção, o `local.php` precisa dela, e é a **rotacionada**: o passo 3 do dia 0 e o passo 7 do corte dizem como, e o `verificar-local-php.php` a acusa como `grave` quando falta. **Provado:** `SegredosForaDoCodigoTest`, nos dois bancos -- a construção sem chave (vazia e só de espaços) lança; a fábrica passa a url e a chave da configuração; a url vazia vale a de produção; sem a seção, o serviço não constrói o cliente. Três mutantes, todos mortos: a construção sem a exceção, a fábrica sem a seção e o serviço ignorando a url. **As rotinas de faturas não foram executadas em caso nenhum** -- a prova para no `asaas()`, e é por isso que ela não alcança o laço das rotinas. **O que continua:** o literal está no histórico do git e vale no Asaas até a rotação, que é sua (a linha 7 do passo 5 do dia 0). E os dois portões de segredo não viam esta chave -- o nome em camelCase escapava, e o valor começa com `$`, que o padrão excluía de qualquer aspa. O conserto do portão está no D4; desde a revisão de 03/10 ele procura esta chave também **pelo valor** (o prefixo `$aact_`), em qualquer forma. E o token das rotinas, que esta tabela nunca listou, entrou na rotação do dia 0 como **linha 9** (ver o D4). **Decidido pelo dono em 06/10/2026** (lote de perguntas, pergunta 2): a opção (a), "Deixar como está até a migração" -- o `VisagismoController` fica com o valor escrito, e na rotação o token das rotinas ganha um valor novo: o valor escrito passa a abrir só o visagismo. A rotação é a linha 9 do passo 5 do dia 0, e no corte ela acontece nos passos 7 e 9 da janela (o 7 sorteia o valor no `local.php`, o 9 refaz o crontab com ele; a pergunta 5, no D331). Nada muda no código; o que este débito espera continua sendo a rotação das credenciais na janela. #### O OneSignal, em 10/10/2026 (PUSH-FCM-ENVIO) O dono decidiu trocar o OneSignal pelo Firebase (a opção A de `docs/notificacoes-push-comparativo.md`), e a ordem de ignorar o OneSignal cedeu para esta migração. Duas linhas da tabela mudam: - **O app mobile.** O envio (`ISBase\Push\OneSignalEnviador`) lê `onesignal.app.app_api_key`, a App API Key nova: com ela no `local.php`, o pedido vai a `api.onesignal.com/notifications?c=push` com o cabeçalho `Key`; sem ela, segue a legada, como hoje. O OneSignal não cria mais chave legada, então a rotação desta linha é **criar a App API Key, pô-la no `local.php` de produção e revogar a legada**, e não trocar uma legada por outra. - **O web push** saiu do código (era código morto, e o `verificar-local-php.php` não o pede mais): a chave dele não é lida por nada, e o certo é **revogá-la**, e não rotacioná-la. **Provado** no `EnvioDePushTest`: com a chave nova, o endereço e o cabeçalho novos e o mesmo corpo; sem ela (ou só de espaços), o pedido byte a byte da classe velha. **Não provado contra o OneSignal de verdade**: nenhum teste fala com ele, e a API nova só foi lida na documentação. O que segue do dono: criar a chave nova, revogar as duas antigas e, depois, apagar o backup do D457. A migração inteira está no D461. #### A conta de serviço do Firebase de teste, em 11/10/2026 (PUSH-TERCEIRA-RODADA: a resposta 74) O servidor de teste foi preparado para falar com o Google, com um projeto Firebase **só de teste** (o D461). A credencial nova é a conta de serviço desse projeto, e **é do dono**: ela vai do console do Firebase direto ao BVIP, em `/etc/franquiabv-teste/firebase-conta-de-servico.json` (0640, dono root, grupo do php-fpm), montada só para leitura no app pelo `docker-compose.teste-firebase.yml`, e o `local.php` do teste guarda só o caminho. Nada dela entra no repositório, e o `ContaDeServico` recusa o arquivo de dentro dele. Não é uma das oito desta tabela: é de um projeto de teste, que não manda a cliente de verdade, e se vazar o certo é revogá-la no console e gerar outra. A conta de serviço do projeto da produção, quando vier, segue o mesmo caminho em `/etc/franquiabv/` (o "Como ligar" do D461). ### D4 — Autenticação fraca nos endpoints de cron — CORRIGIDO em 03/10/2026 no código: o token saiu do código, a recusa é 401 e o token vale pelo cabeçalho; a produção recebe na migração final, e o crontab passar ao cabeçalho é pergunta do lote (D331) — PARCIAL, lido em 05/10/2026 > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito como fechado, e o corpo diz que ele está parcial: uma parte está consertada, e a outra não. Falta: a escolha do dono sobre as três unidadeVendas*, que recusam com 200; o cron.token no local.php no corte; o crontab no cabeçalho é o D331. > > **06/10/2026:** o dono respondeu (lote de perguntas, perguntas 5 e 6): as três `unidadeVendas*` ficam como estão até se saber quem as chama (a 6), e o crontab passa ao cabeçalho no passo 9 do corte (a 5, o D331). Falta: o `cron.token` no `local.php` e o passo 9, na janela; e a conta de quem chama as `unidadeVendas*`, que a resposta 6 pressupõe e nenhum roteiro faz (pergunta no lote) -- ver o fim deste registro. > > **08/10/2026:** a conta de quem chama as `unidadeVendas*` existe (pergunta 33 da página do lote: `scripts/medir-chamadas-unidade-vendas.sh`, o 9 de "O que hoje bloqueia" do procedimento de corte). Falta: rodá-la no dia 0 e levar o número ao dono, o `cron.token` no `local.php` e o passo 9 -- ver o fim deste registro. *Corrigido em 16/08/2026.* O registro anterior dizia que estas rotas não tinham proteção nenhuma. **Estava errado** — a conclusão vinha de as rotas responderem 200 sem credencial, mas o 200 é a resposta fixa `{"sucesso": true}`; o trabalho em si só executa com a credencial correta. A auditoria das 29 ações mostrou: | Ações | Proteção | |---|---| | 26 rotas `/api/cronjobs/*` | Token estático na query string, comparado com `$tokenPadrao` | | 3 rotas `/api/unidade/vendas*` | `hash` por unidade, conferido contra `unidades.hash` | Ou seja, há autenticação. O que resta é a **fragilidade** dela: 1. O token está **fixo no código** (`CronJobController:18`) e é o mesmo do `AplicativoController`. Não é rotacionável sem alterar o código. 2. Viaja na **query string**, então aparece nos logs de acesso do nginx, em proxies e no histórico de quem já o usou. 3. Sem token, a rota devolve `{"sucesso": true}` — resposta de sucesso para uma requisição que não fez nada. Um cron mal configurado silenciosamente nunca executa, e ninguém percebe. **Ao resolver:** mover o token para `local.php`, enviá-lo por cabeçalho em vez de query string, e responder 401 quando ausente. O item 3 é o mais barato e o de maior retorno — é o que impede um cron quebrado de passar despercebido. #### Medido em 30/08/2026, e o item 3 tem data São **30 ações** hoje, não 29: **27 respondem `{"sucesso": true}` com o token errado**, e 3 se autenticam por `hash` da unidade. **Nenhuma das 27 recusa.** Algumas por deixarem o `return` fora do `if`; outras de forma explícita, como a de royalties: ```php if ($token != $this->tokenPadrao) { return new JsonModel(['sucesso' => true]); } ``` **As 3 exceções são as únicas honestas, e pelo mecanismo mais tosco:** `unidadeVendas`, `V2` e `V3` terminam em `die("Acesso negado.")`. **O item 3 deixou de ser hipotético, porque a rotação de credenciais está planejada** — é o passo 5 da remediação dia 0. Rotacionar o token sem atualizar o crontab **para as 27 rotinas de uma vez** — royalties, dashboards, NPS, envios de marketing — e todas continuam respondendo sucesso. Qualquer monitoramento que olhe a resposta HTTP vê verde para sempre. #### O defeito se espalhou, e pela nossa mão A auditoria de 16/08 contou 29 ações. A 30ª é `conveniosAtualizarVencimentoAction`, criada por **este projeto** em 28/08 (`50cde07`) — e ela **copiou o padrão das vizinhas**, porque copiar a vizinha é o que se faz ao acrescentar uma rotina. Por isso existe `scripts/conferir-resposta-cron.php`. Ele **não exige o conserto das 27**: consertar é mudar o contrato de 27 rotas em produção de uma vez, e isso é decisão de quem opera. As 27 estão numa linha de base; **uma ação nova com o defeito faz o roteiro sair com código 1**. Provado que acusa, em 30/08: uma ação forjada com o padrão apareceu como "nova", e o arquivo foi restaurado em seguida. O roteiro também avisa quando uma das 27 é **consertada**, para que saia da linha de base — a lista encolhe por conserto, nunca por conveniência. #### O conserto, em 03/10/2026: o token saiu do código (SEGREDOS) -- os itens 2 e 3 restam O item 1 do "Ao resolver" está feito: a fábrica lê `cron.token` do `local.php` e o passa ao controlador, e o literal saiu do construtor. **E a decisão mora num método só**, `CronJobController::tokenConfere($token)`, chamado pelas 26 ações -- eram 26 cópias da mesma comparação. **O vazio recusa antes de comparar, e não é detalhe.** `hash_equals('', (string) null)` é verdadeiro: com o token vindo da configuração, um `local.php` sem `cron.token` abriria as 26 rotinas para quem chamasse **sem token nenhum** -- um defeito que o literal no código tornava impossível e que a mudança criaria. A recusa responde o que a do token errado já respondia, `{"sucesso": true}`. Responder 401 (o item 3) e mandar o token por cabeçalho (o item 2) são o próximo trabalho: mudam o contrato com o crontab. **O que isso exige da produção:** `cron.token` com o mesmo valor que o crontab manda -- o de hoje, ou o novo, se a **linha 9 do passo 5 do dia 0** já o rotacionou (crontab e `local.php` no mesmo passo) --, ou as 26 param **em silêncio**. O valor de hoje está no repositório (no histórico do controlador e escrito no `VisagismoController`), e é por isso que ele entrou na rotação. Está no passo 3 do dia 0 e no passo 7 do corte, e o `verificar-local-php.php` acusa a ausência como `grave` (junto com `asaas.api_key` e as três do Yungas, do D89, que ele também não conhecia -- falsificado com as cinco vazias, que aparecem, e preenchidas, que não). **Provado:** `SegredosForaDoCodigoTest`, nos dois bancos (11 casos, 349 asserções; com os vizinhos que tocam o `CronJobService`, o controlador e o `FranquiaService` -- doze arquivos --, 224 casos, 2.344 asserções e 1 pulado declarado, iguais nos dois, rodados de novo depois da queda da máquina e da revisão). O controlador nasce pela **fábrica de verdade**, com um contêiner dublê cujo serviço e gerenciador são espiões: todas as ações do controlador -- menos as três do `hash`, lidas do código -- recusam com `cron.token` vazio e sem a seção, com o pedido sem token e com token vazio; o token configurado abre a rotina, e outro valor não abre. **Nenhuma rotina de verdade roda, nem sob mutante**, e por isso os casos podem despachar as 26. Quatro mutantes, todos mortos: sem a recusa do vazio (os dois casos de recusa vermelhos), a fábrica sem o token, a comparação que sempre confere, e uma ação que volta a comparar por conta própria. **A revisão de 03/10 achou duas lacunas, e as fechou.** (1) Um **valor-padrão** na fábrica -- `['cron']['token'] ?? ''`, ou `?: ''` -- passava pelos casos: o pedido deles é nulo, vazio ou o token de teste, todos diferentes do valor-padrão, e todos recusavam igual. É a regressão mais provável (as 26 paradas em silêncio, e alguém "conserta" a fábrica com o token antigo, que o `VisagismoController` ainda traz). O caso novo pergunta o que o controlador **guardou** sem a seção, por reflexão: a cadeia vazia, e nada mais. (2) O token **só de espaços** abria as 26 para `?token=%20`, e o verificador o dava como preenchido -- o `Asaas` já recusava a chave só de espaços. Agora o `tokenConfere` e o `verificar-local-php.php` também recusam, e um caso roda o verificador de verdade sobre um `local.php` escrito pelo teste: as cinco chaves (Asaas, cron e as três do Yungas) aparecem como `grave`, o valor só de espaços como ausente, e o valor nunca é impresso. Cinco mutantes, todos mortos, cada um só pelo caso novo: a fábrica com `?? ''` e com `?:`; o `tokenConfere` sem o `trim`; o verificador sem o `trim`; o verificador sem o `cron.token` na lista. **Os dois roteiros que dependiam da forma antiga.** `scripts/medir-cron-no-postgres.php` tirava o token do controlador por expressão regular sobre o literal; agora lê `CRON_TOKEN` ou o `cron.token` do `local.php`, e o CI sorteia um token só do job e o grava no `local.php` dele (o passo simulado numa cópia: o token entra uma vez, e os dois hosts continuam trocados). Numa árvore de rascunho com um `cron.token`, contra uma porta morta, o medidor achou o token e seguiu para as 20 rotinas; sem o token, sai com 2. `scripts/conferir-resposta-cron.php` procurava `tokenPadrao` no corpo de cada ação -- com a chamada nova, **leu as 29 como honestas e saiu com 0, calado**, porque a ação conhecida que caía naquele ramo não entrava nas consertadas. Agora ele reconhece as duas formas, e a conhecida que deixar de mencionar o token sai com 1. Falsificado numa cópia: só com `tokenPadrao` na primeira busca, sai 1 apontando as 26; sem o ramo novo também, sai 0 com "0 mentem" -- a cegueira de antes; só com `tokenPadrao` na condição, sai 2; com uma ação forjada com o defeito, sai 1 com o nome dela. A saída de hoje é idêntica, byte a byte, à de antes do conserto. **E a revisão achou mais dois.** O medidor das rotinas, com o token vindo do ambiente, **não distinguia a recusa da execução**: com um `CRON_TOKEN` diferente do `cron.token` que a aplicação lê, as 20 respondiam `{"sucesso": true}` sem rodar, e ele saía 0 com "Nenhuma rotina quebrou". Agora sai 2 quando os dois divergem, e sai 2 quando **nenhuma** rotina registra nada. E o `medir-telas-no-postgres.sh` -- logo o `comparar-relatorios-nos-dois-bancos.sh`, que o chama duas vezes -- **morria no passo do cron**: nenhum dos dois `local.php` que ele monta tem o token, o medidor saía 2 e o `set -e` derrubava a corrida antes de `/adm/api` e dos relatórios. Agora ele sorteia um token só da corrida (`scripts/sortear-token-cron.sh`) e o grava no `local.php` que o `trap` devolve no fim. **Os dois foram provados contra um dublê**, dentro do contêiner, que responde como o controlador -- `{"sucesso": true}` rodando ou recusando, e uma linha no log só quando o token confere --, porque o medidor das rotinas chama `relatoriosRoyaltiesAtualizar`, que não se roda aqui: com o medidor de antes, o token divergente e o configurado vazio saíam 0 com "0 de 20"; com o de agora, saem 2, e o token certo sai 0 com "20 de 20". Cada conferência desligada sozinha deixa passar o seu cenário. Com o `local.php` como o medir-telas o monta (dos dois jeitos), o medidor sai 2 ("NAO ACHEI O TOKEN"); depois do sorteio, `php -l` passa, o resto do array fica igual, e ele roda as 20 e sai 0. #### O portão de segredos não via nenhuma das duas, e agora vê (SEGREDOS) Medido com os dois literais no HEAD: o passo do CI e o `pre-push` saíam com **0**. O nome `apiKey` não casa `api_?key` sem ignorar maiúscula, o `tokenPadrao` não estava na lista, e o valor do Asaas começa com `$`, que o padrão excluía de qualquer aspa. E as duas cópias já tinham divergido: o conserto do **D89** nunca chegou ao `pre-push` -- o único dos dois rodando, com o CI parado desde 13/09. O padrão passou a morar em `scripts/conferir-segredos.sh`, que o CI, o `pre-push` (sobre cada commit que o push leva) e o `conferir-tudo.sh` chamam. Ignora maiúscula, conhece `tokenPadrao` e a chave `token` entre aspas (a do `cron.token`), aceita `$` dentro de aspa simples, lê também os arquivos ainda não adicionados, e **imprime só `arquivo:linha`** -- o passo antigo imprimia a linha inteira no log do CI, isto é, a credencial que acabava de achar. **Medido antes de ligar:** 7 linhas no HEAD -- os 3 literais (Asaas, cron e visagismo) e 4 falsos positivos, que viraram 3 exceções declaradas com o motivo: o `PASSWORD` do psql em `postgres/papeis.sql.modelo` (uma variável), um ternário de mensagem em `scripts/ensaiar-sessao-do-erp.php`, e a constante `SENHA` inventada de dois testes (a convenção da casa). O `token` solto ficou de fora: acrescentava duas constantes de teste. **A quarta exceção é a do visagismo, e é a que importa.** O `VisagismoController` fica como está, porque o visagismo é futuro por decisão sua -- e **o valor do token dele é o mesmo do token das rotinas**. O token saiu do `CronJobController`, mas o valor continua no código por ali, e no histórico do git. A rotação não o tira do repositório: faz esse valor deixar de abrir as rotinas -- e por isso o token entrou na rotação do dia 0 como **linha 9**, que nenhuma lista tinha. O que fazer com o visagismo ficou como pergunta no lote de 03/10. **Pelo valor, e não só pelo nome (revisão de 03/10).** O padrão pega a atribuição a um nome conhecido. Medido com linhas inventadas, deixava passar as formas que uma regressão de verdade usaria: o valor-padrão na fábrica (`?? '...'`, `?: '...'`), o literal como argumento (`new Asaas('...')`, `hash_equals('...', $t)`), uma constante de outro nome, o cabeçalho escrito inline, `.env`, JSON e YAML. Para os dois segredos que estavam no código o valor é conhecido, e o portão passou a procurá-los por ele: a chave do Asaas pelo prefixo fixo (`$aact_` seguido de 20 ou mais caracteres, que não casa quem só menciona o prefixo), e o token das rotinas pelo valor lido **em memória** do `VisagismoController` da mesma árvore ou revisão, que não pode aparecer em nenhum outro arquivo (`git grep -F`). Sobre as 13 formas, num repositório de rascunho com valores inventados: só pelo nome, 0 de 13; com os dois, 13 de 13; sem o prefixo do Asaas, escapam as 8 do Asaas; sem a busca pelo valor, escapam as 5 do token. Na árvore de hoje, nenhuma linha a mais; sobre o HEAD, as mesmas duas. O que nenhum portão textual pega continua fora: um segredo NOVO, de valor desconhecido, num nome que não está na lista. **O `pre-push` passou a conferir o que o push leva, e não o HEAD.** Um commit que põe o literal e outro que o tira iam juntos, o HEAD estava limpo, e o segredo chegava ao histórico do remoto; o mesmo com `git push origin `. Agora ele lê do git as referências empurradas e confere **cada** commit que o remoto ainda não tem (cerca de um segundo por commit); chamado a mão, sem stdin, confere o HEAD como antes. Falsificado num repositório de rascunho: o literal posto e tirado, o ramo novo com os dois commits e o um `.txt` em `public/` posto e tirado passavam com o hook de antes e bloqueiam com o de agora, citando o commit; nada novo, apagar ramo e um commit limpo passam. **Falsificado:** com cada literal devolvido ao arquivo novo, o roteiro sai 1 apontando o arquivo, e 0 depois de restaurar; sobre o HEAD de hoje, sai 1 com os dois. Cada peça arrancada numa cópia do roteiro deixa passar o que ela pega: sem `-i`, o HEAD sai 0; sem `token_?padrao`, escapa o cron; sem o `$` na aspa simples, escapa o Asaas; sem o colchete do D89, escapa uma atribuição a índice forjada num arquivo de rascunho; sem cada exceção, o arquivo dela aparece; e a exceção que não perdoa nada é avisada. O `pre-push` chamado a mão sobre o HEAD de hoje **bloqueia** -- o HEAD ainda tem os literais, e a busca pelo valor aponta o `CronJobController` também --; o push do commit deste trabalho leva só ele, que não os tem. **O que ficou para depois da cópia do teste:** o `conferir` do deploy de teste não exige as duas chaves vazias, e três comentários do ambiente de teste ainda as dão como escritas no código. Os arquivos estão congelados enquanto a cópia sobe no BVIP: é o **D330**. #### O conserto, em 03/10/2026: a recusa é 401, e o token vale pelo cabeçalho (itens 2 e 3) **O item 3.** Toda recusa -- token ausente, token que não confere, `cron.token` vazio ou só de espaços no servidor -- responde **401** em JSON, na forma da convenção (`{"erro": {"codigo": "nao_autenticado", "mensagem": ...}}`, o `erroAutenticacao` do `RespostaApi`, o mesmo do `/api/v4`), com `WWW-Authenticate: Bearer realm="rotinas"`. **Uma recusa só para as três causas:** dizer qual seria contar a quem não apresentou credencial como o servidor está configurado; o `verificar-local-php.php` já acusa o vazio. **O sucesso não mudou** -- `{"sucesso": true}` com 200, ou o que a rotina devolve. Em cada uma das 26 ações a guarda é a primeira coisa (`if (!$this->tokenConfere()) { return $this->tokenRecusado(); }`), e a rotina só vem depois -- antes, 25 delas deixavam o `return` de sucesso fora do `if`. **O item 2.** O token vale por `Authorization: Bearer` -- o cabeçalho que o `/api/v4` já lê e que a convenção decidiu para quem fala por token, e não um nome inventado -- e **continua valendo por `?token=`**, que é o que as 25 linhas do crontab de produção mandam hoje: tirar a query junto pararia as rotinas no corte. **Uma credencial por pedido:** com `Bearer`, a query nem é lida, e `Bearer` errado com a query certa recusa; outro esquema no cabeçalho (`Basic`, de um proxy) não é credencial das rotinas, e a query vale. **O cabeçalho ilegível recusa com 401**: o `getHeader` do Laminas lança exceção para byte de controle ou fora do ASCII (medido no `Request` puro e no do ambiente), e sem a captura seria 500. A query que não é cadeia (`?token[]=`) é ausência. **O portão (`scripts/conferir-resposta-cron.php`) perdeu a linha de base** e passou a exigir a forma: a guarda como primeira coisa, o ramo da recusa só com `return $this->tokenRecusado();`, nada de comparar `tokenPadrao` no corpo, e o `tokenRecusado` começando pelo `erroAutenticacao`. Ação que não confere token nem hash **reprova** -- até hoje ela passava como "honesta", e era justamente a rotina nova que esquecesse a guarda. Lê o código **sem comentários** (pelo tokenizador). Falsificado numa árvore de rascunho: o controlador de antes sai 1 com as 26 e o "a recusa não é 401"; cada um destes sai 1 com a ação dele -- a guarda arrancada, arrancada com um comentário que a cita, a recusa com sucesso, a rotina antes da guarda, a comparação por conta própria, a ação nova sem guarda --; o `tokenRecusado` devolvendo sucesso, antes ou no lugar do `erroAutenticacao`, sai 1; o arquivo vazio sai 1. E a leitura sem comentários é carregante: uma ação sem guarda com um comentário citando `unidadeAutorizada` sai 1 com ela e sai **0** com o portão que lê comentário. **O medidor das rotinas** (`scripts/medir-cron-no-postgres.php`) manda o token no cabeçalho -- na URL ele ia para o log de acesso, uma linha por rotina -- e lê o 401: na primeira recusa ele para e sai 2 dizendo que a aplicação recusou o token. Provado contra um dublê da aplicação dentro do contêiner, que responde como o controlador (401, ou sucesso e uma linha no log): token certo, 20 de 20 e saída 0, com **0 de 20** pedidos com o token na URL (o de antes: 20 de 20); a aplicação com outro token, ou sem `cron.token`, sai 2 no **primeiro** pedido (o de antes fazia os 20 e saía 2 por "nenhuma registrou nada"); e uma rotina recusada no meio das outras sai 2 -- **o de antes saía 0** com "19 de 20", e o de agora sem a leitura do 401 também. O valor do token não aparece na saída em cenário nenhum. **E os irmãos.** `scripts/coletar-producao.sh` redigia só o `?token=` do crontab: uma linha com `-H "Authorization: Bearer ..."` sairia na coleta em claro (medido com valores inventados: o sed de antes deixa o valor visível; o de agora redige os 4 formatos e deixa intacta a linha sem segredo). A `rotas-publicas.php` dizia das 26 "token fixo no código -- D5"; agora diz o que as guarda. O `verificar-local-php.php` dizia que, sem `cron.token`, as rotinas "respondem sucesso". **Provado:** `SegredosForaDoCodigoTest`, **16 casos e 5.016 asserções, iguais nos dois bancos** (eram 11): as 26 ações, despachadas pela fábrica de verdade contra espiões, recusam com 401 em dez formas de não trazer o token certo e com o configurado vazio, ausente ou só de espaços, sem rodar nada; o `Bearer` certo abre (também `bearer` e com espaços a mais), tem precedência sobre a query, e a query certa segue abrindo -- com `{"sucesso": true}` como sempre. **As que cobram ou enviam vêm por último** em toda volta pelas ações: sob um mutante que abra todas, o caso para na primeira, que é inofensiva. **Oito mutantes, todos mortos, cada um aplicado sozinho e restaurado** (o controlador conferido byte a byte com a cópia limpa depois de cada um): a guarda arrancada de uma ação; a recusa de volta a `{"sucesso": true}`; a query ganhando do cabeçalho; sem a captura do cabeçalho ilegível (o caso dele estoura com a exceção do Laminas); o cabeçalho não lido; o token nu no cabeçalho aceito; sem o `WWW-Authenticate`; a comparação que sempre confere -- nenhuma das que cobram ou enviam apareceu na saída de mutante nenhum. **Por HTTP, na aplicação de pé**, só pedidos sem token ou com token errado, e só contra o controlador limpo (conferido igual à cópia limpa, com as 26 guardas, antes dos pedidos). **O que os tornava seguros era isso, e não a falta de `cron.token` no `local.php` de desenvolvimento** -- esta frase dizia o contrário até a revisão de 03/10/2026, e estava invertida: com a guarda arrancada a ação roda sem consultar token nenhum; e sem a recusa do vazio no `tokenConfere` é justamente a falta de `cron.token` que abre as 26 ao pedido sem token (`hash_equals('', '')` é verdadeiro). Sem token, com a query errada, com `Bearer` errado e com o cabeçalho ilegível, 401 em JSON com o `WWW-Authenticate`, também numa rota-filha (`/api/cupons/cuponsValidarVencimento`); o `log_scripts.txt` não ganhou linha; e `/api/unidade/vendas` sem hash segue respondendo "Acesso negado.". Que o nginx desta pilha passa o `Authorization` ao PHP já era provado pelo `ApiV4Test`; o `php -S` do CI também passa (medido). **O que isto exige da produção, e o que fica:** o crontab tem de mandar o token certo -- o mesmo `cron.token` do `local.php` --, ou as rotinas **param com 401**. Hoje ele o manda na query, e a query continua valendo: **nada no crontab precisa mudar para o corte**. Está no passo 7 do dia 0 e nos passos 7 e 9 do corte. O token segue na URL -- e no log do nginx -- até alguém trocar as 25 linhas para o cabeçalho; e o crontab chama por `curl -s` e não lê a resposta (a linha modelo do `crontab-a-aplicar.md` a joga em `/dev/null`), então o 401 só aparece no log de acesso. As duas coisas são da produção e suas: o **D331**, com a pergunta no lote. As três `unidadeVendas*` (o `die("Acesso negado.")` com 200) ficaram como estavam: são o contrato com quem consome o faturamento (D9), e mudá-las é escolha sua -- também no lote. #### A revisão do conserto, em 03/10/2026: sete achados, todos consertados Uma revisão adversarial do conserto acima achou sete coisas verdadeiras (nove relatos, dois em dobro). Nenhuma abria rotina a quem não tinha o token; duas eram a **conferência do corte** dizendo "tudo bem" com as rotinas paradas. - **A conta de 401 no log, que o passo 9 do corte e o passo 7 do dia 0 usavam como prova, dava 0 com as 25 rotinas recusadas.** Lia só `/var/log/nginx/access.log`, e o site tem log próprio por vhost (o D36: a coleta que olhou só `access.log*` achou zero pedidos a `/api/versao/app`); e não tinha controle positivo -- o 0 do sucesso e o 0 do arquivo errado eram o mesmo número. Também somava os 401 de antes de um conserto. **Agora** o passo 9 marca quantas linhas cada `*.log` do nginx tem **antes** de religar o cron (`wc -l`, só contagens) e, 10 minutos depois, mostra o código HTTP de cada pedido do crontab feito **depois da marca**, em todos os logs: tem de mostrar só `" 200 "`, e mais de zero; nada impresso quer dizer "não vi o crontab -- não siga". O passo 7 do dia 0 aponta para lá, sem segunda cópia. Ensaiado com logs inventados: token certo em dois logs de vhost, `3 " 200 "`; errado, `2 " 401 "`; sem pedido, nada; a conta antiga dava 0 no `access.log` com o token errado no log do vhost. - **`Authorization: Bearer` vazio (ou `Bearervalor`) caía para a query**, contra o "uma credencial por pedido" escrito. O `tokenDoPedido` procurava o prefixo `Bearer ` com espaço, e o `trim` o comia. **Agora** o esquema é a primeira palavra do valor: `Bearer` sozinho é credencial vazia e recusa, e o TAB separa como o espaço. Não abria nada a mais (a query certa já abria), mas o contrato não era o que o código fazia. - **O portão `conferir-resposta-cron.php` não via ação fora do molde, e isentava quem só CITASSE `unidadeAutorizada`.** O recorte textual perdia `public static function`, `final public function`, `function` sem visibilidade, `xAction ()` e o recuo de 8 espaços, e o portão saía 0; e a ação copiada da `unidadeVendas` sem o `die()` passava como guardada. **Agora** os métodos vêm do tokenizador (do `{` ao `}` que o fecha), a leitura é conferida pela contagem textual das declarações, "ação" é todo método terminado em `Action` em qualquer caixa, e pela unidade só passa quem começa pela guarda inteira. Falsificado com 20 variantes, o portão recebendo o caminho da variante: o novo sai 1 nas 18 defeituosas e 0 nos 2 controles; o de antes saía **0 em 9 delas**. O teste ganhou a mesma regra na sua exclusão (`GUARDA_DA_UNIDADE`): com a exclusão de antes, a ação que só cita o nome passava verde; com a de agora, fica vermelha. - **A página `/api/docs/cronjobs` só falava do `?token=` e do `{"sucesso": true}`** -- as 26 entradas. **Agora** cada uma traz o `Authorization: Bearer` e a query como "um dos dois", o exemplo de envio das duas formas, e o 401 com `nao_autenticado` no exemplo de retorno; a rota já não ensina o token na URL. Um caso novo confere cada entrada **e** que toda rota de rotina do roteador (lida do `router` da configuração) tem página. - **A abertura com o token certo só era provada em 1 das 26 ações.** O caminho de sucesso das 26 foi reescrito por roteiro, e uma ação que devolvesse a recusa de novo depois da guarda, ou perdesse a chamada ao serviço, passava no teste e no portão -- e pararia com 401 na produção, com o token certo. **Agora** um caso abre as 22 inofensivas (lidas do código, as quatro que cobram ou enviam de fora e nunca despachadas) pela query **e** pelo `Bearer`, e confere que cada uma chamou o serviço dela. - **A frase "o `local.php` de desenvolvimento não tem `cron.token`, então nem a guarda caída abriria"**, no parágrafo "Provado" acima, estava invertida -- foi reescrita ali mesmo. **Provado:** `SegredosForaDoCodigoTest`, **18 casos e 6.256 asserções, iguais nos dois bancos**; com os 10 vizinhos, **225 casos e 8.240 asserções**, iguais nos dois. **Seis mutantes novos, todos mortos**, cada um aplicado sozinho e restaurado (controlador e página conferidos byte a byte com as cópias limpas): o esquema de volta ao prefixo `Bearer ` (morre no "Bearer vazio com a query certa", na primeira ação, que é inofensiva, e no `Bearer`); uma ação que recusa de novo depois da guarda; uma que perde a chamada ao serviço; a página de volta ao `?token=` só; uma rotina sem página; e a ação nova que só cita `unidadeAutorizada` (e, com a exclusão de antes no teste, esse mesmo mutante passa verde). Por HTTP, só sem token ou com token errado, contra o controlador limpo: `Bearer` sem credencial com a query errada e `Bearer` errado dão 401 em JSON com o `WWW-Authenticate`; o `log_scripts.txt` não ganhou linha. A página das rotinas fica atrás do login do ERP neste ambiente: foi renderizada em processo, com o template de verdade. **Achado de passagem, fora do D4:** o mesmo `access.log*` está na apuração do incidente LGPD (passo 2 do dia 0 e `scripts/remediacao-dia0.sh`) -- o **D332**. **Decidido pelo dono em 06/10/2026** (lote de perguntas, perguntas 2, 5 e 6): na 2, a opção (a), "Deixar como está até a migração" -- o visagismo guarda o valor escrito, e a rotação (a linha 9 do passo 5 do dia 0) faz esse valor deixar de abrir as rotinas; na 5, a opção (b), "curl -fsS com o token no cabeçalho, e MAILTO" -- é o D331, e já está no passo 9 do corte; na 6, a opção (a), "Não mexer até o inventário do D9 dizer quem as chama" -- as três `unidadeVendas*` continuam recusando com `Acesso negado.` e 200. **Uma ressalva sobre a 6:** o inventário do D9 era o das consultas do Power BI, e morreu com ele em 09/09/2026; o consumidor das três rotas por `hash` é desconhecido (`docs/f3-relatorios.md`), e só o log de acesso da produção diz quem as chama -- conta que nenhum roteiro do repositório faz (procurado por `unidade/vendas` em `scripts/` e `docs/`). Foi ao lote como pergunta, no item DECISOES-NO-REGISTRO-E-NO-CORTE. O que resta deste débito: o `cron.token` no `local.php` da janela (o passo 7) e as três `unidadeVendas*`. **Decidido pelo dono em 07/10/2026** (pergunta 33 da página do lote): a opção (a), "Eu escrevo a conta, para rodar no dia 0" -- "Só leitura e só contagens, por rota e por dia, sem hash nem IP; a sua 6 volta a você com o número." Escrita em 08/10/2026: `scripts/medir-chamadas-unidade-vendas.sh` lê os logs de acesso do nginx (os arquivos dados, `.gz` também, ou a entrada padrão) e conta, por dia, os pedidos a `/api/unidade/vendas`, `vendasV2` e `vendasV3` -- de qualquer método, com a query cortada antes de qualquer conta, e também com o `/index.php/` na frente e com a URL inteira no pedido, que chegam à exportação --, os "parecidos" (a barra no fim, a barra dobrada, outra caixa, outra versão, contados e não impressos) e o controle `/api/versao/app` (o D36): com o controle em zero, sai com 2 e diz que não mediu, porque o zero das três num log que não é o do site não quer dizer nada. Não imprime IP, `hash`, query string, user-agent nem referer. É o 9 de "O que hoje bloqueia" do `docs/procedimento-de-corte.md`: no dia 0, pelo `ssh` e sem pôr arquivo no servidor (o roteiro vai pela entrada do `sh -s`), sobre todos os `*.log` e `*.log.*` de `/var/log/nginx/`, com a tabela do que fazer com o número -- ele vem para este registro e para o D9, e a pergunta 6 volta ao dono. **Provado** com um log inventado (IPs dos blocos de documentação, um `hash` que diz que é inventado) por `sh scripts/ensaiar-medir-chamadas-unidade-vendas.sh`, no Git Bash (bash e gawk) e no contêiner da aplicação (dash e mawk): as contagens de quatro dias em dois arquivos, um deles `.gz`, e pela entrada padrão; ficam de fora a rota dentro do referer, do user-agent e da query de outra rota, a `vendedores`, a linha do log de erro e o pedido "-"; o dia sem o controle sai marcado; nenhum IP, `hash`, user-agent ou valor de query na saída; saída 2 sem o controle, só com o log de erro, com o glob sem arquivo e com um `.gz` quebrado; e o procedimento ainda manda rodar a conta. A forma do `ssh` (o roteiro pela entrada do `sh -s`, os logs pelos argumentos, os girados e o `.gz` junto) rodou no contêiner, com um log inventado. O ensaio roda no `conferir-tudo.sh` e no CI. **A revisão de 08/10/2026 achou dois buracos, e os dois estão fechados.** (1) O `/index.php/` na frente e a URL inteira no pedido (`GET http:///api/unidade/vendas`, a forma absoluta, que o nginx aceita e grava assim) iam a "parecidos": as três saíam em zero com alguém chamando, e a pergunta 6 voltaria ao dono com um zero falso. Medido no nginx daqui (o mesmo `docker/nginx/default.conf`), só com GET sem `id` e sem `hash` -- o `unidadeAutorizada` devolve nulo antes de qualquer consulta: `/index.php/api/unidade/vendas`, `/index.php/api/unidade/vendasV2`, `/index.php/api/versao/app` e a forma absoluta da `vendasV3` dão 200 (o "Acesso negado." da action: a exportação rodou); `/api/unidade/vendas/`, `//api/unidade/vendas` e `/index.php/api/unidade/vendas/` dão 404. A conta tira o esquema e o host da forma absoluta e o `/index.php` da frente antes de comparar, e o controle também. (2) O ensaio dizia provar que "o procedimento manda rodar a conta" procurando o nome do roteiro na seção inteira, e a célula da tabela o satisfazia: apagar o bloco do `ssh` não deixava nada vermelho. Agora ele tira a linha do `ssh` dos blocos `bash` da seção, sem comentário e com a continuação junta, e a RODA: o que vai entre aspas para a produção, num `sh -c`, com `/var/log/nginx/` trocado por um diretório com o log inventado, um girado em texto e um `.gz`, tem de dar o mesmo que a conta chamada direto sobre os três (8 do controle, 5, 2 e 2 das três, 5 parecidos). **Falsificado**, um mutante por vez em cópias (os arquivos de verdade não mudaram): a conta sem as duas formas, sem só o `/index.php/` e sem só a forma absoluta (5 vermelhos cada: o dia 07, o total, a linha AS TRES, a entrada padrão e a conta direta do diretório); o procedimento sem o bloco do `ssh`, com o `sh -s` sem os logs, sem os girados (`*.log.*`), e com o comando só num comentário HTML (1 cada); e o controle, o procedimento sem a linha 9 da tabela e com o comando, verde. Verde no Git Bash e no contêiner (dash e mawk). **Não provado:** o log da produção, que só o dia 0 lê -- os nomes dos arquivos e o formato `combined` são deduzidos (o D332) --, e quem é o chamador, que a conta não diz de propósito. O que resta deste débito: o `cron.token` no `local.php` da janela (o passo 7), e as três `unidadeVendas*`, que esperam o número. --- ## Adiados para a migração do aplicativo móvel ### D5 — Token fixo da API do aplicativo #### O parque de aplicativos, medido em 19/08/2026 Em 14 dias de log, **236.785 requisições** à API: | Cliente | Requisições | O que é | |---|---:|---| | CFNetwork (várias versões) | ~110.000 | iOS | | okhttp/4.12.0 | 24.582 | Android nativo | | Dart/3.5 | 6.232 | Flutter | | Mozilla/5.0 | 4.080 | navegador | O iOS domina, com cerca de 78% das chamadas. E aparecem **três pilhas de cliente distintas** — `okhttp` é Android nativo, `Dart` é Flutter. Ou existem dois aplicativos Android em campo, ou há uma migração de tecnologia em curso que não está documentada neste repositório. **Vale esclarecer**, porque muda o que significa "atualizar o aplicativo". #### O User-Agent NÃO diz qual versão do app está em campo Correção de uma expectativa minha. `CFNetwork/3860.600.12`, `okhttp/4.12.0` e `Dart/3.5` são versões da **biblioteca HTTP** — do iOS, do Android e do Flutter. Dizem o sistema operacional, não a geração do aplicativo. Quem responde isso são as **rotas versionadas**, que existem por causa deste próprio débito: ``` /api/agendas/agendar <- geração mais antiga /api/v2/agendas/agendar /api/v3/agendas/agendar <- mais recente /api/v2/agendas/getAgenda /api/v2/agendas/getUnidade/:id ``` Quem chama `/api/v3/...` roda a geração 3; quem chama a rota sem prefixo roda a mais antiga. O `coletar-producao.sh` passa a contar cada uma — **é essa contagem que decide qual contrato pode ser aposentado**, e ela ainda não foi coletada. #### Hipótese em aberto sobre as três pilhas Levantada pelo responsável em 19/08: seria versão antiga do aplicativo ainda chamando, nunca bloqueada por estar instalada em celulares velhos. **Dois números complicam essa leitura, sem derrubá-la.** As versões de biblioteca são recentes — `Dart/3.5` é de meados de 2024 e `okhttp/4.12.0` do fim de 2023 —, e um aplicativo parado há anos não carregaria nenhuma das duas. E o volume vai no sentido contrário do esperado: `okhttp` tem 24.582 chamadas contra 6.232 de `Dart`, ou seja, o suposto antigo com quatro vezes mais tráfego que o novo. Duas explicações alternativas cabem igualmente bem: 1. **Um aplicativo Flutter só, com dois caminhos HTTP.** `dart:io` produz `Dart/3.5`; plugins que descem para a plataforma produzem `okhttp` no Android. Mesmo binário, duas assinaturas. 2. **Aplicativo Android nativo antigo convivendo com o Flutter novo** — a hipótese acima, com dependências atualizadas ao longo do tempo. **O que decide:** tráfego relevante em `/api/agendas/agendar` sem prefixo confirma a hipótese, e aquele contrato não pode ser aposentado. Tudo concentrado em `/api/v3/...` significa que as gerações antigas já morreram, e o D5 encolhe para o problema do token, sem o agravante do parque. `AplicativoController` autentica com um token estático embutido no código. Não foi rotatado de propósito: trocá-lo derruba o aplicativo na mão dos clientes. **Ao resolver:** junto com a versão do app que adotar autenticação por token rotacionável. Ver também o versionamento improvisado dos endpoints (`V2`, `V3`), que indica versões antigas ainda ativas no parque. --- ## Débitos técnicos descobertos no levantamento ### D6 — Banco em utf8mb3 (não armazena emoji) — PREPARADO, lido em 05/10/2026 > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito sem marca de estado, e o corpo diz que ele está pronto no código, à espera só do passo em produção na janela da migração final. Falta: o corte para PostgreSQL, na migração final, e antes dele conferir se já existem dados corrompidos por truncamento. As 82 tabelas usam `utf8mb3`, o charset de 3 bytes. **Emoji e vários caracteres Unicode não cabem** — mensagens de WhatsApp e nomes com esses caracteres são truncados ou rejeitados pelo MySQL hoje. **Ao resolver:** a migração para PostgreSQL resolve naturalmente (UTF-8 completo), mas é preciso verificar antes se existem dados já corrompidos por truncamento. Se a migração demorar, `ALTER TABLE ... CONVERT TO CHARACTER SET utf8mb4` resolve no MySQL. #### O modelo que o setup instala nao tinha `charset` — corrigido em 02/09/2026 Descoberto por acidente, e por um erro meu. Em 01/09 eu perdi o `local.php` da maquina de desenvolvimento (um `kill -9` impediu o `trap` de `scripts/rodar-caracterizacao.sh` de restaura-lo) e o reconstrui a partir de `docker/config/local.php.docker`, que e o que `scripts/setup-dev.sh:31` instala. Ao comparar o arquivo reconstruido com o original, faltavam cinco linhas. Eram estas: ```php 'charset' => 'utf8mb4', ``` **E elas nao estavam no modelo.** `config/autoload/local.php.dist` tem o `charset`; `docker/config/local.php.docker` nao tinha. Quem montasse o ambiente pelo caminho documentado ja recebia um `local.php` sem ele. O cabecalho de `ISBase\Doctrine\Charset` avisa exatamente sobre isto: > o `local.php` que vale em producao NAO e versionado: se ele subir sem > `charset`, a conexao volta a nascer em utf8mb3 e os 18 pontos deixam de > proteger justamente o texto do cliente. **Nao houve corrupcao de dado.** A classe `Charset` continua elevando a conexao nos 18 pontos que tocam texto de cliente — ela existe como rede para este caso. O que faltava era a protecao de base, deixando tudo pendurado na rede. Corrigido nos dois: no modelo versionado e no `local.php` desta maquina. Conferido depois: `character_set_client = utf8mb4` na conexao. **A licao nao e sobre charset.** Eu reconstrui um arquivo a partir de um modelo e assumi que o modelo estava completo. O jeito de nao repetir e o que fiz aqui por sorte: comparar o reconstruido com o que se sabe do original — no caso, os numeros de linha que eu tinha visto antes de perde-lo. ### D7 — `usuarios.senha_php83` removida — e a remoção deixou dois estragos (ver D78 e D79) *Resolvido em 17/08/2026, na F1.3.* A coluna saiu do schema PostgreSQL, e o mapeamento e os dois acessores saíram da entidade `Usuario`. Nada fora da própria entidade os chamava — só o proxy gerado pelo Doctrine, que se regenera. Os 67 testes de caracterização continuam passando. **O que só apareceu ao remover, e vale registrar:** a coluna guardava senha com criptografia **reversível e chave fixa no código**: ```php openssl_encrypt($senha, 'AES-128-CBC', '0', 0, '0123456789101112') ``` Chave `'0'`, vetor de inicialização literal, ambos versionados. Qualquer pessoa com o código e um dump recuperava as senhas em texto claro. Era pior que o D2, e estava classificado aqui como faxina de coluna órfã. Duas coisas atenuam: o `anonimizar.sql.modelo` já zerava a coluna, então os dumps que circulam nunca a levaram; e o deploy da F1.1 a elimina de produção. ~~**Resta uma:** `usuarios.salt` usa a mesma chave e o mesmo vetor. Salt não é segredo por definição, então o impacto é menor.~~ > ### DUAS CORREÇÕES, de 01/09/2026, e as duas são graves > > **A primeira: a frase riscada acima está errada, e errou pelo nome da > coluna.** `usuarios.salt` **não guarda um salt** — guarda a **senha**, cifrada > com a mesma chave `'0'` e o mesmo vetor. `getSalt()` chama `openssl_decrypt` e > **devolve a senha em texto claro**, e é contra ela que `autenticacao()` compara > o que o usuário digita. > > O impacto não é menor: é o mesmo do `senha_php83`, e essa coluna **não foi > removida**. Virou o **D78**. > > **A segunda: a remoção quebrou a troca de senha, e está quebrada desde > 17/08/2026.** Este débito afirma que *"nada fora da própria entidade os > chamava"*. Fora, não — **dentro** chamava: `criptografarSenha()` faz > `$this->setSenhaPhp83($senha)` na linha seguinte ao `setSalt()`. O commit > `8f95f86` removeu o método e **manteve a chamada**. > > `setSenha()` lança `Error: Call to undefined method` — conferido executando. > Virou o **D79**. > > **Os 67 testes continuaram passando** porque nenhum deles define uma senha. É o > mesmo desenho de falha do D55: verde que não cobria o caminho. ### D8 — Proteção de branch indisponível no GitHub Repositório privado em conta pessoal não permite proteção de branch sem plano pago. Hoje a proteção equivalente roda no CI (servidor, não burlável) e no hook `pre-push` (local, burlável com `--no-verify`). **Ao resolver:** quando houver duas pessoas commitando — GitHub Pro ou uma organização com plano Team. ### D9 — Credencial do sistema de BI — REDUZIDO A UM RESÍDUO em 09/09/2026 — PREPARADO, lido em 05/10/2026 — PREPARADO, e o papel do PostgreSQL local apagado em 12/10/2026 > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito como fechado, e o corpo diz que ele está pronto no código, à espera só do passo em produção na janela da migração final. Falta: revogar no MySQL de produção o usuário que servia ao BI e apagar a funcionalidade 61 e suas concessões, na janela da migração. O sistema de BI externo acessa o MySQL de produção diretamente. Não se sabe qual usuário utiliza nem se tem permissão de escrita. **Ao resolver:** inventariar as queries, criar usuário **somente leitura** e, na Fase 1, apontá-lo para uma réplica de leitura do PostgreSQL em vez do banco de produção. **Situação em 27/08/2026 (F1.9): metade feito.** O usuário somente leitura existe e está provado — `bvip_bi`, sem permissão de escrita (cinco tentativas recusadas), com escopo por inquilino (com contraprova) e lendo de réplica (onde nem o superusuário escreve). Ver `f1-9-bi-e-papeis.md`. **A outra metade não avançou, e as duas partes dependem de produção:** 1. **O inventário das consultas.** Continua sem saber-se o que o Power BI lê nem com que usuário. Por isso `bvip_bi` recebe `SELECT` em **todas** as tabelas — que é o menor privilégio *possível sem o inventário*, e não o menor privilégio. A diferença importa: `clientes` tem 242.587 linhas com dado pessoal, e um painel de faturamento não precisa de nenhuma delas. 2. **Repontar o Power BI.** Os relatórios vivem no serviço da Microsoft e são embutidos por unidade (`unidades.iframe_bi`). Trocar a fonte exige abrir o modelo no Desktop, trocar o conector, instalar o provedor Npgsql no gateway, republicar e reconfigurar credenciais. Não é trabalho de banco. #### O Power BI foi REMOVIDO em 09/09/2026 Por decisão do dono: *"Remover Power BI, não será mais utilizado."* Saiu em três commits — a tela do painel e o item de menu, a coluna `unidades.iframe_bi`, e o papel `bvip_bi` do modelo de papéis. **As duas metades em aberto morreram com ele.** Não há consultas a inventariar nem ferramenta a repontar. Inventariar o que ninguém vai executar seria produzir documento para arquivar. #### O que NÃO morreu, e é o resíduo deste débito **A credencial em produção continua lá.** Remover o consumidor não revoga o usuário: o MySQL de produção segue com o usuário que o Power BI usava — ainda sem nome conhecido, ainda sem permissões conhecidas — e agora **ninguém o usa**. Credencial que ninguém usa não é credencial que não existe. É a que menos chama atenção no dia em que for usada: não há mais painel legítimo cujo tráfego se pareça com o dela, e também não há mais ninguém que note se ela parar de funcionar. **Isso torna o débito menor e mais claro do que era.** Não é mais "inventariar e repontar", que dependia da Microsoft e de produção descongelada. É **revogar**, que é um `DROP USER` e depende só de produção. **Ao resolver:** listar os usuários do MySQL de produção, identificar por `host` de origem e por `SHOW GRANTS` qual servia ao BI, e revogá-lo. Enquanto a produção estiver congelada por decisão de 23/08, este débito fica aberto **por isto** — e não mais pelo inventário. #### E um segundo resíduo, que eu mesmo deixei Ao remover a tela do painel eu tirei do `SessaoAcl` as três menções a `dashboardUnidades`. **A linha da tabela ficou.** A funcionalidade #61, `Relatórios dashboard unidades`, segue com **145 concessões e 1 molde**, apontando para uma tela que não existe mais — uma caixinha que o operador marca e desmarca na tela de privilégios, e que não muda nada. Isso não dá erro, não gera log, e ninguém notaria. Foi medido por `scripts/medir-funcionalidades-orfas.php`, escrito por causa disto: das 63 funcionalidades, **esta é a única órfã, e não há nenhum fantasma** (nome citado no código que a tabela não tenha). O resto da ACL está íntegro. **A primeira versão daquele medidor mediu errado, e vale registrar por quê.** Ela acusou 37 órfãs e 36 fantasmas — quase toda a ACL. O defeito era de codificação: os nomes são acentuados, o fonte é UTF-8 e o cliente do MySQL devolvia latin1, então tudo com acento "não casava". Faltava `--default-character-set=utf8mb4`. *Medida que compara texto precisa comparar o mesmo texto* — e um número absurdo é mais fácil de desconfiar que um plausível. **Ao resolver:** `DELETE FROM privilegios_usuarios WHERE funcionalidade = 61;`, o mesmo em `privilegios`, e então a linha de `funcionalidades`. É escrita em produção, que está congelada — entra na mesma janela do resíduo acima. **Decidido pelo dono em 06/10/2026** (lote de perguntas, pergunta 6): a opção (a), "Não mexer até o inventário do D9 dizer quem as chama" -- as três exportações `unidadeVendas*`, que autenticam pelo `hash` da unidade, ficam como estão (o D4). Este débito não tem mais inventário: o das consultas morreu com o Power BI em 09/09/2026 (acima). O que a decisão espera é saber quem chama `/api/unidade/vendas*`, e isso só o log de acesso da produção diz, em todos os logs de vhost (o D36); nenhum roteiro o conta, e a pergunta de escrevê-lo está no lote. O resíduo deste débito continua o mesmo: revogar o usuário do BI e apagar a funcionalidade 61, na janela. **Decidido pelo dono em 07/10/2026** (pergunta 33 da página do lote): a opção (a), "Eu escrevo a conta, para rodar no dia 0" -- "Só leitura e só contagens, por rota e por dia, sem hash nem IP; a sua 6 volta a você com o número." A conta existe desde 08/10/2026, `scripts/medir-chamadas-unidade-vendas.sh`, e é o 9 de "O que hoje bloqueia" do procedimento de corte (o D4 diz o que ela conta e como foi provada). Com o número do dia 0, a pergunta 6 volta ao dono. O resíduo deste débito não muda: revogar o usuário do BI e apagar a funcionalidade 61, na janela. #### E um terceiro resíduo, no PostgreSQL da cópia local (achado em 11/10/2026) O papel `bvip_bi` saiu do modelo de papéis em 09/09/2026, mas **não saiu do PostgreSQL desta máquina**: ele segue lá, com login (sem `BYPASSRLS`), e a cópia (`franquiabv_dev`, esquema `bvip`) ainda lhe dá `SELECT` nas 89 tabelas e no privilégio padrão do esquema (`pg_default_acl` do `franquiabv`: `bvip_app=arwd`, `bvip_bi=r`) — o padrão de antes de 09/09, que a `clientes_aparelhos` herdou ao ser criada em 11/10/2026 (o **D461**, a verificação). Medido só com leitura nos sete bancos do servidor local: só a cópia dá algo ao papel, e ele não é dono de objeto nenhum. A homologação, o teste e o laboratório do BVIP não foram medidos daqui. Tirá-lo (os `REVOKE`, ou o `DROP OWNED BY` e o `DROP ROLE`) é escrita na cópia: a pergunta foi ao lote (PUSH-TERCEIRA-RODADA, a verificação), e a recomendação é apagar o papel. #### O terceiro resíduo, apagado em 12/10/2026 (a resposta 150, a opção (c); item ESQUEMA-NAS-COPIAS) **A resposta do dono** (a 150 do lote, 12/10/2026, 02:30): a opção (c), apagar o papel `bvip_bi` do PostgreSQL desta máquina. **Conferido antes, só com leitura, às 05:35:** o papel com login, sem superusuário nem `BYPASSRLS`, **nenhuma sessão aberta** (`pg_stat_activity`, em banco nenhum) e **nenhum objeto próprio** (nenhuma dependência de dono no `pg_shdepend`); o que o servidor guardava dele era só privilégio, e só na `franquiabv_dev`: o `CONNECT` do banco, o `USAGE` do esquema `bvip`, o `SELECT` em 89 tabelas e o privilégio padrão do `franquiabv` no esquema (`bvip_bi=r`), além de uma configuração do próprio papel (`search_path`, inquilino 1, só leitura e tempo limite de 10 min), que o `DROP ROLE` leva junto. Nenhum privilégio concedido POR ele a outro papel, e ele não era membro de papel nenhum nem tinha membro. Os outros seis bancos do servidor (`postgres`, `franquiabv_pgtestes`, `franquiabv_pgcontrato`, `franquiabv_pgwtd237`, `d45_refutacao`, `fx_teste`) não o citavam em lista de privilégio nenhuma. **Os comandos**, na `franquiabv_dev`, como `franquiabv`, pelo `psql` do contêiner, numa transação só, com as três conferências dentro dela -- sem sessão, sem objeto próprio, nada em outro banco; qualquer uma falsa e o roteiro desfaz e para (`docker exec -i franquiabv-postgres-1 psql -U franquiabv -d franquiabv_dev < `), começada às 05:40:18,88 e encerrada às 05:40:18,90: ```sql DROP OWNED BY bvip_bi; DROP ROLE bvip_bi; ``` Saída 0, e `pg_roles` sem o papel. Nada mais foi escrito: nem dado, nem esquema, nem `ANALYZE`. **A conferência depois, só leitura:** a lista de privilégios inteira de cada um dos sete bancos -- o banco, os esquemas, os privilégios padrão, toda tabela, sequência e visão, toda coluna com privilégio próprio, toda função e toda política --, tirada antes e depois. Na `franquiabv_dev`, 92 linhas mudaram, **todas só pela saída do `bvip_bi`** (o banco, o esquema, o padrão e as 89 tabelas); nos outros seis, nenhuma. Os privilégios do `bvip_app` ficaram os mesmos, e os da cópia ficaram iguais, linha a linha, aos do banco da suíte (`franquiabv_pgtestes`), menos a lista do próprio banco (a cópia dá `CONNECT` ao `bvip_app` explicitamente; o banco da suíte usa o padrão). A tabela nova que nascer na cópia não herda mais o `SELECT` do papel aposentado, que foi o que a `clientes_aparelhos` herdou em 11/10/2026 (o **D461**). **Nada no repositório usa o papel:** as citações são histórico (`docs/`) e os comentários de `scripts/criar-papeis.sh` e `scripts/conferir-papeis.sh`, que dizem que ele saiu em 09/09/2026; o `criar-papeis.sh` só cria o `bvip_app` (de `postgres/papeis.sql.modelo`), e não o recria. **O portão dos papéis**, `scripts/conferir-papeis.sh`, rodou depois, com "TUDO CONFERE" (o `bvip_app` não é superusuário nem tem `BYPASSRLS`, o RLS vale para ele sem e com inquilino, e o dono o atravessa) -- **num banco descartável**, `med_papeis_d9`, clonado do banco da suíte e apagado no fim (conferido: nenhum `med_*`), porque o roteiro grava e apaga uma unidade e um inquilino de prova no banco que mede, e na `franquiabv_dev` isso seria escrita fora da autorização. A propriedade do papel que ele confere é do servidor, e não do banco; o RLS, ele o mediu no clone. Os casos da suíte no PostgreSQL rodam como `bvip_app`, e os dos cupons e das comandas ficaram verdes depois (o **D271**). **Refeito na verificação (12/10/2026), num clone da própria cópia.** O clone do banco da suíte media um estado que o `DROP` não tocou: os privilégios só mudaram na `franquiabv_dev`. Então, sem sessão nenhuma aberta nela, a cópia foi clonada por `CREATE DATABASE med_papeis_copia TEMPLATE franquiabv_dev STRATEGY FILE_COPY` (17 s, 2.862 MB), com o `search_path` e o fuso dela, e o `CONNECT` do banco dado como ela o dá (`REVOKE ALL ... FROM PUBLIC` e `GRANT CONNECT ... TO bvip_app`, só no clone). A lista de privilégios inteira do clone, pela mesma consulta de antes, ficou **igual à da cópia, linha a linha** (289 linhas, trocado só o nome do banco), sem nenhuma citação ao `bvip_bi` e com as 179 do `bvip_app`; e a da cópia, igual à tirada depois do `DROP`. O `scripts/conferir-papeis.sh` contra o clone: **"TUDO CONFERE"**, saída 0 (o `bvip_app` com inquilino lê as 64 unidades da cópia). O mutante, no clone: `REVOKE SELECT ON bvip.unidades FROM bvip_app` -- saída **1**, com "COM inquilino declarado le" e "nao ve a linha do inquilino 2" em FALHOU: o portão mede os privilégios do banco que lhe dão. O clone foi apagado no fim (nenhum `med_*` no servidor), e a cópia não recebeu a unidade nem o inquilino de prova (0 linhas com o id 999001 e o inquilino 2). **O que resta deste débito** é o de antes, e é de produção, na janela: revogar o usuário do MySQL de produção que servia ao BI e apagar a funcionalidade 61 e as suas concessões. A homologação, o teste e o laboratório do BVIP não foram medidos daqui (o terceiro resíduo era desta máquina); se algum deles tiver o papel, ele veio de lá, e não desta cópia. ### D11 — `laminas-cache` trava a atualização do PHP — PREPARADO em 08/11/2026: o lock aceita do 8.1 ao 8.3 e a suíte passou no 8.2; o `vendor/` novo sobe na janela, e trocar o PHP do servidor é do corte O projeto está preso ao **PHP 8.1**: `laminas/laminas-cache` está fixado em 3.6.0 no `composer.lock`, versão que aceita no máximo PHP 8.1. O `composer.json` declara aceitar até 8.3, mas o `composer install` falha em 8.2 e 8.3. Pelo mesmo motivo o Composer precisa ser da linha 2.2: o `laminas-dependency-plugin` exige `plugin-api < 2.3`. O PHP 8.1 saiu do suporte de segurança em dezembro de 2025. **Ao resolver:** atualizar `laminas-cache` e `laminas-dependency-plugin` antes de subir a versão do PHP. Como o backend continua em Laminas na estratégia adotada, isso não é descartável pela migração para React — é manutenção que segue necessária. **Preparado em 08/11/2026 (a fatia 130, PREPARO-DO-PHP-E-DO-ARMAZENAMENTO).** O `composer.json` pede `laminas/laminas-cache` `~3.13.0` (era `3.6.0` fixo), e o `composer update laminas/laminas-cache laminas/laminas-cache-storage-adapter-filesystem`, rodado **dentro do contêiner** (o Composer 2.2 dele), mudou só três pacotes no `composer.lock`: `laminas-cache` 3.6.0 → 3.13.0 (PHP 8.1 a 8.4), `laminas-cache-storage-adapter-filesystem` 2.3.0 → 2.5.0 (8.1 a 8.4), e saiu o `stella-maris/clock` (o 3.13 usa o `psr/clock`, que já estava). O `laminas-cache-storage-adapter-memory` 2.4.0, o que o Doctrine usa (`doctrine.cache.array`), já aceitava até o 8.4 e não mudou. O `vendor/` do host foi recopiado do contêiner e conferido (os 4.901 arquivos com o mesmo sha1 dos dois lados). **O que prova que a trava saiu:** `composer prohibits php 8.2.0` e `8.3.0` acusavam o `laminas-cache` 3.6.0 (e o adaptador 2.3.0, no 8.3) e agora não acusam ninguém; o `composer install` do lock antigo numa imagem à parte com `PHP_VERSION=8.2` recusa ("laminas/laminas-cache 3.6.0 requires php ~7.4.0 || ~8.0.0 || ~8.1.0"), e o do lock novo instala, com o `check-platform-reqs` verde; e a suíte de caracterização inteira passou nessa imagem (PHP 8.2.35), nos dois bancos: 7.211 casos no MySQL (24 pulados) e 7.211 no PostgreSQL (17 pulados), saída 0. **Um aviso do 8.2, e não é nosso:** uma depreciação no `doctrine/dbal` 2 (`PostgreSqlPlatform.php:874`, `${var}` em texto), num caso do PostgreSQL (`AcertoDoConvenioDasVendasTest`); é aviso, não erro, e só pesa no PHP 9. O `RegrasDaCotaParteTest` (o **D673**, o `round` do 8.1) passou no 8.2. A imagem, o contêiner e o volume do ensaio foram apagados no fim. **O que fica para o corte:** o `vendor/` novo sobe na janela, no pacote da release (`procedimento-de-corte-etapa-1.md`, a leitura 8 e o passo 2 de "A release, montada fora da produção"): o da produção saiu do lock antigo e não serve ao código novo. Trocar o PHP do servidor (o 8.1 sai do suporte de segurança) não é desta fatia nem da etapa 1. **Segue de pé:** o Composer 2.2, porque o `laminas-dependency-plugin` (hoje 2.7.0) ainda exige `plugin-api < 2.3`; e o lock não aceita o 8.4 (o `composer.json` e uma dúzia de pacotes param no 8.3). O padrão do `docker/php/Dockerfile` segue `PHP_VERSION=8.1`, o da produção. PREPARADO. *Na correção da fatia 130 (08/11/2026):* a prova de cima foi feita à mão, uma vez, e a suíte, o contrato, os ensaios e o CI rodam todos no 8.1 -- o lock podia voltar ao `laminas-cache` 3.6.0 e tudo seguiria verde. **A guarda agora é um caso**, o `D11LockAceitaOPhpNovoTest`: lê o `composer.json` e o `composer.lock` e confere, pelo `composer/semver`, que a restrição de PHP do `composer.json`, da `platform` do lock e de cada pacote (os da aplicação e os de desenvolvimento) aceita o 8.1, o 8.2 e o 8.3 (o `.0` e o `.99` de cada linha); um segundo caso prova que o leitor nomeia o `laminas-cache` 3.6.0. Com o `composer.json` e o `composer.lock` do commit `281c9c0a` no lugar, ele fica vermelho e nomeia o `laminas-cache` 3.6.0 e o adaptador 2.3.0. O que ele não prova: que o código RODA no 8.2 ou no 8.3 -- isso segue pedindo a suíte numa imagem com `PHP_VERSION=8.2`, como acima. ### D12 — Configuração do nginx em produção não verificada O `public/.htaccess` presente no projeto é inerte, já que a produção usa nginx. Toda a proteção de caminho depende da configuração do servidor, que ainda não foi inspecionada. Duas perguntas em aberto, ambas com impacto de segurança: 1. **Execução de PHP em diretórios de upload.** O sistema grava arquivos enviados por usuários em `public/arquivos`, `public/contratos`, `public/banners`, `public/assistentes`, `public/vip-class` e `public/layout/img/avatar`. Se o nginx de produção não bloquear `.php` nesses caminhos, um arquivo enviado como "contrato" é executado pelo servidor — o que é execução remota de código. 2. **Arquivos de dado soltos na raiz do webroot.** Uma regra por categoria (`.txt`, `.log`, `.sql`) teria contido o problema D1 sozinha. O `docker/nginx/default.conf` deste repositório implementa as duas e foi testado (ver `ambiente-desenvolvimento.md`). Serve de referência para o servidor. ### D13 — API do aplicativo não tinha autenticação nenhuma — FECHADO em 04/09/2026 > **Leia junto com o D59**, que é o mesmo assunto medido depois e por outro > caminho — lá está a demonstração com `curl` e o achado de que > `getCliente?telefone=` devolve o CPF sem cabeçalho nenhum. Os dois ficam > separados de propósito: este registra *por que* não há autenticação (o token > declarado e nunca comparado); o D59 registra *o que se alcança* sem ela. > Conferido em 30/08/2026 que não são duplicata. `AplicativoController` declara `$tokenPadrao` no construtor, mas **o valor nunca é lido**. O único listener de autenticação (`ISConfiguracao\Module::handleAuthRedirect`) protege apenas rotas com `admin` no nome, a rota `home` e as rotas `isapi-docs-*`. Verificado no ambiente: os 22 endpoints do aplicativo respondem sem credencial. *Correção de 16/08/2026:* a versão anterior deste registro estendia a afirmação às 29 rotas de cron. **Não vale para elas** — os crons verificam token ou hash; ver D4. O problema é específico do `AplicativoController`, onde o token é declarado e nunca comparado. Isso é mais grave do que o token estar fixo no código (D5). Entre o que fica aberto: `/api/cliente/agenda/:id` e `/api/agendas/getConsumoCliente` expõem dados de clientes por enumeração de id, e `/api/agendas/cancelar` permite cancelar agendamentos de terceiros. **Ao resolver:** exige mudança coordenada com uma versão nova do aplicativo, já que hoje ele não envia credencial alguma. Fecha junto com D5. O teste `testApiRespondeSemAutenticacao` falha quando isso for corrigido — é o sinal de que o app precisa sair na mesma entrega. #### RESOLVIDO em 03 e 04/09/2026 **As duas rotas que este registro nomeia foram fechadas**, e mais sete: `getConsumoCliente` e `agendas/cancelar` estão entre as nove ações que passaram a exigir sessão. O detalhe do que cada uma expunha está no **D59** (as cinco de leitura) e no **D91** (as quatro de escrita). *E vale registrar como elas voltaram à tona:* eu as reencontrei varrendo o código, e as reportei como achado — sem reler este débito, que as nomeia desde 16/08/2026. Aconteceu duas vezes no mesmo dia, e nas duas foi um portão que me corrigiu. **Quem varre código sem reler o registro da área encontra o que já era sabido e chama de novo.** **O `$tokenPadrao` do `AplicativoController` saiu**, e ele era o "token declarado e nunca comparado" que dá nome a este débito: 42 caracteres com cara de credencial, atribuídos no construtor e **nunca lidos** em nenhuma das 22 ações. Código morto com forma de segredo é pior que código morto — quem lê supõe que há uma verificação em algum lugar. **A autenticação veio por outro caminho**, e não por aquele campo: sessão do ERP nas nove ações congeladas que expunham dado de pessoa, e `Authorization: Bearer` no `/api/v4`, com prova de posse do telefone por código no WhatsApp. **O `testApiRespondeSemAutenticacao` continua verde**, e está certo: ele exercita `/api/agendas/getUnidades`, que é catálogo público e continua sem exigir credencial. O sinal que este registro esperava veio por outros nove testes, que congelam a recusa. #### O que continua deste débito O `$tokenPadrao` do `CronJobController` — **esse é usado**, em 26 ações, e é o token fixo do **D5**. As comparações passaram a ser `hash_equals` em 04/09; o valor continua no código, e rotacioná-lo exige coordenar com quem chama os crons. ### D14 — Rota V1 de agendamento aponta para ação inexistente — PARCIAL em 07/10/2026: a raiz `/mod-vendas` leva à lista de vendas; ficam a V1, que espera os logs, e 12 `//index` que caem no `indexAction` do Laminas — PARCIAL em 07/11/2026: os 12 `//index` dão 404 (a fatia 115); fica só a V1, que espera os logs da produção `/api/agendas/agendar` está declarada em `module/ISApi/config/module.config.php` apontando para a ação `agendaSalvar`, que **não existe** no `AplicativoController` — só existem `agendaSalvarV2` e `agendaSalvarV3`. A rota retorna 404. Ou seja: qualquer versão do aplicativo que ainda use o endpoint original **não consegue agendar**. Como não há inventário das versões em uso (depende dos logs do servidor), não dá para saber quantos clientes são afetados. **Ao resolver:** decidir entre implementar a V1 de volta ou confirmar pelos logs que ninguém mais a chama e remover a rota. O teste `testAgendaSalvarV1EstaQuebrada` congela o 404 atual e falha quando o comportamento mudar. #### Não era uma. Eram três (medido em 30/08/2026) A varredura de todas as rotas contra os controllers achou mais duas: | Rota | Situação | |---|---| | `/api/agendas/agendar` → `agendaSalvar` | a deste débito; espera os logs | | `/convenios/atualizarVencimento` → `ConveniosController::atualizarVencimento` | **órfã por nossa mão** — removida em 30/08 | | `/mod-vendas` → `VendasController::index` | a raiz do módulo cai numa ação que nunca existiu | **A do meio foi criada por este projeto.** Ao mover a rotina de vencimento de convênio para o cron (**D50**), a ação de admin foi removida em 28/08 e **a rota ficou para trás**, apontando para o nada por dois dias. Nada a referenciava — conferido — e ela saiu. **A de `/mod-vendas` é mais antiga e continua de pé:** a URL raiz do módulo de vendas tem `'action' => 'index'` como padrão, e `VendasController` tem `indexVendasAction` e `indexComandasAction`, mas nunca teve `indexAction`. Quem digitar `/mod-vendas` sem caminho recebe erro; o menu sempre apontou para as ações completas, então ninguém tropeçou. `scripts/conferir-rotas-orfas.php` guarda as duas restantes numa linha de base e acusa qualquer rota órfã nova. #### Três armadilhas nesse roteiro, e as três me pegaram 1. **Nome curto não identifica controller.** Há dois `VendasController`, em `ISRelatorio` e em `ISVenda`. Indexar por nome curto faz um sobrescrever o outro. A primeira versão acusou **11**; resolvendo por módulo, são 3. 2. **PHP não diferencia caixa em nome de método.** A rota `'action' => 'cadastroconcluido'` alcança `cadastroConcluidoAction()` sem problema — verificado por execução. Comparar caixa exata acusava duas rotas perfeitamente sadias. 3. **Guardar o nome do método com o sufixo `Action`** e comparar com a ação sem ele fez a terceira versão acusar **90 de 92**. Número absurdo o bastante para se denunciar sozinho — e é por isso que o roteiro imprime a contagem antes do veredito. #### O conserto da raiz `/mod-vendas` (07/10/2026, o item CODIGO-MORTO-E-DOCS) **O "recebe erro" estava certo, e o "nunca teve `indexAction`" só pela metade.** O controller nunca DECLAROU o seu, e o PHP achava o herdado: o `AbstractActionController::indexAction` do Laminas, o de marcador, que devolve "Placeholder page" para o molde `is-venda/vendas/index` -- que não existe. Medido em processo: o resolvedor de moldes devolve `false` para ele, e desenhá-lo dá *Unable to render template*. O roteiro das órfãs lê só o arquivo do controller, e por isso a contava como órfã -- o que, para quem abria a URL, ela era. **`VendasController::indexAction` leva à lista de vendas realizadas** (`/mod-vendas/vendas/indexVendas`, o mesmo endereço do menu) e pede o mesmo privilégio que ela, `vendas/realizadas/ler`. Sem ele, responde o 404 da lista, sem redirecionamento: a raiz não abre nada que a lista não abra, e não manda ninguém por um 302 até um 404. Quem pode `comandasListar` e não `realizadas` recebe o 404 na raiz, como recebia o erro antes -- não há uma raiz que sirva aos dois, e escolher outra seria escolha de tela. Sem sessão, a raiz cai no login como o resto do ERP (`RotaPublica::exigeSessao('isvenda-admin')`). **Provado** por `tests/Caracterizacao/D14RaizDoModuloDeVendasTest.php` (4 casos, em processo, nos dois bancos): o roteador leva `/mod-vendas` a uma ação **declarada** em `VendasController` (e não à herdada -- `method_exists` dizia que sim antes do conserto, e foi o primeiro mutante que mostrou isso); quem enxerga a lista recebe 302 para `/mod-vendas/vendas/indexVendas`, que o roteador resolve para `indexVendas`; quem não enxerga recebe 404 na raiz, sem `Location`, e 404 na lista pedida direto; e a raiz faz à sessão exatamente a pergunta que a lista faz. **Mutantes, um de cada vez:** sem o `indexAction`, 4 vermelhos e o `conferir-rotas-orfas.php` com saída 1; sem a guarda, 2 vermelhos e o `conferir-guarda-do-erp.php` com saída 1 (35 sem guarda, a ação nomeada); com a guarda de `comandasListar`, 2 vermelhos. A entrada saiu de `$conhecidas` do `conferir-rotas-orfas.php`, que fica com uma: a V1 de agendamento, que espera os logs. Por HTTP, só o pedido anônimo: `GET /mod-vendas` sem sessão devolve o formulário de entrada (200, com o campo `login` e o de senha). O caminho com sessão não foi aberto no navegador. #### Os irmãos da raiz ficam de pé (verificação de 07/10/2026) **A raiz era um caso de uma classe de URL, e o conserto cobriu só ela.** As seis rotas curinga do ERP -- `/mod-vendas/[:controller[/:action[/:id]]]` e as de `/mod-cadastros`, `/mod-configuracoes`, `/mod-financeiro`, `/mod-marketing` e `/mod-relatorios` -- aceitam no `:controller` **qualquer** apelido do `ControllerManager` (os apelidos são da aplicação, e não do módulo), e `///index` despacha o `indexAction`. Nos controllers que não declaram o seu, responde o de marcador do Laminas, com a mesma falha ao desenhar que a raiz dava. **Medido em processo, pelo `ControllerManager`, e não de memória: 12 apelidos** -- `aplicativo`, `appconfiguracoes`, `caixas`, `cronJob`, `enderecos`, `fidelidade`, `pesquisaNps`, `rel-franquias`, `testeEstilo`, `vendasPagamentos`, `vendasProdutos` e `whatsapp`. Três são do próprio módulo de vendas (`/mod-vendas/caixas/index`, `/mod-vendas/vendasProdutos/index`, `/mod-vendas/vendasPagamentos/index`: em `view/is-venda/caixas/` só há `abrir.phtml` e `fechar.phtml`, e as pastas dos outros dois nem existem). Há 22 classes registradas que herdam o de marcador; as outras 10 não têm apelido que caiba no `:controller`, e nenhuma rota tem `:action` sem `:controller`: a elas só se chega pelas rotas que nomeiam a ação, e essas o `conferir-rotas-orfas.php` lê. Não é regressão, nada no menu aponta para essas URLs, e todas exigem sessão (`RotaPublica::exigeSessao`). Nenhum dado sai: quem abre recebe o erro do molde. O `conferir-rotas-orfas.php` não vê essa classe, porque lê só as rotas que declaram `action` em `defaults`, e não o que a curinga alcança. **O que cada uma deveria mostrar é escolha de tela** -- redirecionar para a lista do módulo, como a raiz, ou um 404 --, e fica aqui: não foi decidido. **Fixado** por um quinto caso em `D14RaizDoModuloDeVendasTest` (`testOsApelidosQueAindaCaemNoIndexDeMarcadorSaoOsRegistradosNoD14`), que deriva a lista do `ControllerManager`, compara com os 12 e confere que o roteador leva `/mod-vendas//index` a cada um, atrás da sessão. **Mutante:** com um `indexAction` declarado em `CaixasController`, o caso fica vermelho (`caixas` sai da lista medida); restaurado, o arquivo volta igual ao do HEAD. E com o `indexAction` da raiz arrancado de novo, agora são os **cinco** casos vermelhos (eram 4 antes deste). Verde nos dois bancos: a classe e as 14 vizinhas, 178 testes e 985 asserções. Um apelido novo no de marcador também deixa o caso vermelho -- e quem consertar um destes tira-o do caso e daqui. #### O ciclo pegou o link morto do D105 redirecionando (07/10/2026) **A primeira versão da raiz ressuscitou um link morto.** O apelido `vendas` é da aplicação, e por isso `/mod-relatorios/vendas/index` -- a curinga dos relatórios -- também chega a `VendasController::indexAction`. É justamente o link que o D105 tirou da tela inicial do grupo 9, e o `ensaiar-links-consertados-do-erp.php` (caso 5) exige que ele dê 404. Com a raiz nova ele passou a responder **302 para a lista de vendas**: o ensaio saiu com 1 no MySQL, no ciclo de 07/10/2026, enquanto os 2.532 testes, o contrato e os 59 portões estavam verdes. Nenhum caso do D14 o pegaria -- todos despachavam a ação sem parâmetro de rota. **O conserto:** a ação só redireciona quando o pedido chega pelas rotas `isvenda-admin`, cujo default `module` é `ISVenda` (a curinga do módulo o herda); fora delas, o 404 de sempre, **antes** de qualquer pergunta de privilégio. Dois casos novos: o primeiro caso agora confere que o ROTEADOR põe `module => ISVenda` em `/mod-vendas` e em `/mod-vendas/vendas/index` (os outros casos o injetam, e sem essa linha a raiz poderia dar 404 com tudo verde), e `testPelaCuringaDosRelatoriosARaizContinuaDando404` despacha a ação com os parâmetros que o roteador põe em `/mod-relatorios/vendas/index`, por quem enxerga a lista: 404, sem `Location`, sem pergunta de privilégio. **Mutante:** a guarda do `module` trocada por `if (false)` deixa só esse caso vermelho; restaurada, verde. MySQL: 6 testes, 89 asserções; PostgreSQL, com as vizinhas de vendas: 40 testes, 258 asserções. A lição é a do D14 inteiro: o apelido é da aplicação, e qualquer ação nova num controller com apelido curto vale em seis curingas. #### Os 12 apelidos dão 404 (07/11/2026, a fatia 115, ROTAS-404-E-401) **O que faltava dos irmãos da raiz foi fechado junto com o D424.** O `CrudController` declara o seu `indexAction`, que é `return $this->notFoundAction()->setTerminal(true)` -- o mesmo 404 da ação que não existe, e o mesmo que a raiz dá fora do módulo de vendas --, sem redirecionar para lugar nenhum e antes de qualquer pergunta de privilégio. Os 12 controllers (`aplicativo`, `appconfiguracoes`, `caixas`, `cronJob`, `enderecos`, `fidelidade`, `pesquisaNps`, `rel-franquias`, `testeEstilo`, `vendasPagamentos`, `vendasProdutos` e `whatsapp`) herdam do `CrudController` -- conferido por classe, e não de memória --, e `///index` deixa de ser o 500 de "Unable to render template". Responder 404 não era escolha de tela (redirecionar seria): nada aponta para essas URLs. **Provado** por `D14RaizDoModuloDeVendasTest::testNenhumApelidoCaiNoIndexDeMarcadorETodoIndexSemTelaE404`, que substitui o caso que fixava os doze como estavam: deriva do `ControllerManager` todo nome que cabe no `:controller`, exige que nenhum caia no `indexAction` do Laminas, que os doze respondam o do `CrudController`, e despacha cada um pelo `index` -- 404, sem `Location`, com o modelo terminal e sem pergunta de privilégio. Os outros cinco casos (a raiz, o link do D105 pela curinga dos relatórios) seguem como estavam. **Por HTTP**, o caso 6 novo do `ensaiar-links-consertados-do-erp.php`, com a sessão que abre o relatório de vendas: `/mod-vendas/caixas/index`, `/mod-configuracoes/whatsapp/index`, `/mod-relatorios/rel-franquias/index` e `/mod-cadastros/enderecos/index` dão 404 -- e o caso 5 passou a exigir o 404 do link morto, sem aceitar mais o 500. **Mutante:** sem o `indexAction` do `CrudController`, o caso em processo fica vermelho nos dois bancos, e o ensaio HTTP mede os quatro em **500**. **Fica a V1 de agendamento** (`/api/agendas/agendar` -> `agendaSalvar`, a única órfã conhecida do `conferir-rotas-orfas.php`, agora pelo nome da rota, `isapi-aplicativo-agenda-salvar`): continua esperando os logs da produção, e isso é do corte. ### D15 — RESOLVIDO: o schema estava apenas desatualizado no meu lado **Fechado em 16/08/2026** com o dump de estrutura tirado do servidor de produção. O registro dizia que faltavam 2 tabelas e 4 colunas, e levantava a hipótese de o dump entregue estar velho. A hipótese estava certa e o alarme era maior do que precisava: o `mysql.sql` original era um retrato de **02/04/2026**, e entre abril e agosto a produção recebeu a migração da funcionalidade de indicações. O dump de 16/08 confirma que `indicacoes`, `clientes_validacoes_cadastrais` e as quatro colunas (`clientes.data_ultimo_envio_nps`, `clientes.bloqueio_agendamento_app`, `clientes.indicacao`, `unidades.indicacao_comissao`) **existem em produção**. Uma tabela de backup, `pontuacoes_historicos_bkp`, foi removida no mesmo período. `scripts/verificar-schema.php` agora reporta **zero divergências**, e o `schema-patch-d15.sql` foi descartado por não ser mais necessário. Os 95 testes passam contra o schema real. **Fica a lição de método:** durante meses o repositório teria carregado um schema que não correspondia à produção, e só um dump datado resolveu. Vale repetir a verificação antes de iniciar a Fase 1, já que o schema pode evoluir de novo. ### D16 — Endpoints retornam 500 em vez de erro tratado — CORRIGIDO em 14/09/2026 — PREPARADO, lido em 05/10/2026 > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito como fechado, e o corpo diz que ele está pronto no código, à espera só do passo em produção na janela da migração final. Falta: conferir na janela do corte o display_errors do PHP de produção e desligá-lo se estiver ligado, como item do procedimento. Endpoints do aplicativo devolvem uma página de erro HTML com stack trace quando a consulta falha, em vez de um JSON com `sucesso: false`. O aplicativo não tem como distinguir "não encontrado" de "servidor quebrado". #### Medido em 30/08/2026, e é pior do que estava escrito **O texto dizia "os três endpoints acima", e a referência ficou órfã** quando o D15 foi reescrito como resolvido. Os três eram `/api/cliente/agenda/:id`, `/api/cliente/indicacoes/:id` e `/api/agendas/getServicos/:id`, e eles falhavam por causa do schema desatualizado — problema que acabou. **Mas o defeito nunca foi dos três**: é de toda rota `/api/*`. | | | |---|---:| | Ações em `AplicativoController` | **20**, com **0** `try` | | Ações em `CronJobController` | **29**, com **0** `try` | **E a condição "se `display_errors` estiver ligado" está errada — não é condicional.** Quem manda aqui é o `display_exceptions` do Laminas, e ele está `true` em `module/ISBase/config/module.config.php`, que é config de módulo e **carrega sempre**. Nenhum arquivo em `config/autoload/` o desliga. O `development.local.php.dist` também o liga, mas esse só entra em modo de desenvolvimento — ou seja, a página de erro mostra o rastro **por padrão, em qualquer ambiente**. `module/ISBase/view/error/index.phtml` imprime, nessa ordem: a classe da exceção, `arquivo:linha`, a mensagem, o rastro completo, e repete tudo para a exceção anterior. **O que a mensagem carrega, verificado por execução e não por suposição:** ``` An exception occurred while executing 'SELECT nome FROM ... WHERE telefone = ?' with params ["(11) 98765-4321"] ``` O Doctrine põe **o SQL e os parâmetros ligados** dentro de `getMessage()`, e o template imprime `getMessage()`. Numa consulta de cliente que falhe, **o telefone do cliente vai para a página de erro** — junto com o caminho absoluto do arquivo e a pilha inteira. **O único tratador de erro que existe não resolve isto.** `ISConfiguracao\Module` escuta `EVENT_DISPATCH_ERROR`, mas só chama `setTerminal(true)`: tira o layout, e continua renderizando a mesma página de erro. Não há nada que faça `/api/*` responder JSON. **Ao resolver:** três coisas, e a primeira é de uma linha. 1. **Tirar `display_exceptions` do config de módulo** e deixá-lo só no arquivo de desenvolvimento, que é onde ele já está. Desenvolvimento mantém o rastro; produção para de publicá-lo. 2. Um tratador de exceção que responda JSON nas rotas `/api/*`, junto com a reescrita da API. 3. Conferir o `display_errors` do PHP em produção — que é assunto separado, e continua valendo. #### O passo 1 foi aplicado em 30/08/2026, por decisão sua `display_exceptions` e `display_not_found_reason` saíram de `module/ISBase/config/module.config.php` e passaram a viver em `config/autoload/local.php`, **que está no `.gitignore`** — é arquivo por máquina. Desenvolvimento liga; produção, que copia de `local.php.dist`, simplesmente não liga. **Verificado nos dois sentidos**, e é o que dá confiança na mudança: | | `display_exceptions` | |---|---| | Com a chave do ambiente (desenvolvimento) | `true` | | Sem ela (produção) | **AUSENTE** | O template guarda com `if (! empty($this->display_exceptions))`, então ausente não imprime nada. Medir só o lado ligado não provaria coisa alguma — foi preciso remover a chave e conferir que o valor some. `local.postgres.php.dist` recebeu o mesmo bloco, porque o ensaio de corte também é ambiente local e continua precisando do rastro. **O que continua pendente:** os passos 2 e 3 — o tratador que responde JSON nas rotas `/api/*`, junto com a reescrita da API, e o `display_errors` do PHP em produção, que é assunto separado e não se confere daqui. #### O PASSO 2 SAIU EM 14/09/2026, e não esperou a reescrita da API O registro previa o tratador *"junto com a reescrita da API"*. Não precisou: são cinquenta linhas num ouvinte, e a reescrita pode levar meses durante os quais aparelho instalado continua recebendo HTML. **Medido antes**, contra o servidor local: ``` GET /api/agendas/getAgenda/999999999?data[]=1 → HTTP 500, Content-Type: text/html →

An error occurred

``` **Medido depois:** ``` → HTTP 500, Content-Type: application/json → {"sucesso":false,"mensagem":"Não foi possível atender a este pedido."} ``` E a rota que não existe passou a responder **404** em JSON, e não 500 — a diferença é o que um aplicativo velho usa para distinguir *"o endereço sumiu"* de *"deu erro"*. #### O QUE ELE NUNCA PÕE NO CORPO **Nem `getMessage()`, nem o rastro.** É o mesmo motivo que tirou `display_exceptions` do config de módulo em 30/08: o Doctrine põe o SQL **e os parâmetros ligados** dentro da mensagem, e uma consulta de cliente que falhasse publicaria o telefone dele. Pôr a mensagem aqui desfaria aquele conserto por outra porta. A exceção vai para o log do servidor, que é onde quem opera a lê sem que o cliente a receba. #### MEIO ENSAIO AFIRMA QUE HTML CONTINUA HTML Um ouvinte guloso demais transformaria em JSON a página de erro do ERP e a documentação da própria API — entregando um objeto a um navegador. Por isso metade dos dez casos de `ensaiar-erro-json-da-api.php` mede o outro lado. **E a primeira versão desses casos era verde pelo motivo errado.** Eles pediam `/api/docs` e `/mod-cadastros/agendas`, que respondem **200** — e o ouvinte só dispara em **erro**. Ficavam verdes com o ouvinte, sem ele, e com o recorte arrancado. Agora pedem `/api/docs/naoexiste` e `/rota/que/nao/existe`, que dão 404 de verdade. #### FALSIFICADO EM QUATRO SENTIDOS | o que se estraga | o que o ensaio faz | |---|---| | o ouvinte sai do bootstrap | vermelho nos casos **1 e 2** — volta o HTML | | a documentação deixa de ser excluída | vermelho no **3** | | o recorte `/api/` some, e ele pega o ERP | vermelho no **3** | | a mensagem passa a carregar `getMessage()` | vermelho no **1** — é a asserção do vazamento | #### UMA ARMADILHA QUE CUSTOU DUAS RODADAS, e vale para toda falsificação por HTTP As duas primeiras tentativas deram resultados **contraditórios entre si**: a mesma falsificação saiu vermelha numa rodada e verde na seguinte. A causa é `opcache.revalidate_freq = 2` no PHP-FPM. Escrever o arquivo e pedir a URL no mesmo segundo mede o **bytecode antigo**. Toda falsificação que atravessa HTTP neste projeto precisa esperar mais de dois segundos entre a escrita e a medição — senão ela mede o passado e chama isso de resultado. #### E UM `attach` POR EVENTO `EventManager::attach` desta versão do Laminas recusa lista de nomes e estoura em `InvalidArgumentException`. Como o `onBootstrap` roda no arranque, o erro derruba a **aplicação inteira**, não só a API — medido ao escrever o ouvinte, com o ERP respondendo *Fatal error* em toda rota. #### O QUE CONTINUA ABERTO: o passo 3 **O `display_errors` do PHP em produção não se confere daqui.** No contêiner de desenvolvimento ele está ligado (`docker/php/php.ini`), e por isso um pedido com data inválida responde **200** com quatro `Warning` do PHP colados na frente do JSON — incluindo o caminho absoluto do arquivo. Se produção o tem ligado, o mesmo acontece lá. Produção não está sob controle de versão (**D37**) e não se toca até a janela do corte. Fica como item do procedimento, e não como código a escrever. **Ressalva:** o ensaio está no CI e **ainda não executou lá** — o CI está parado por cobrança da conta desde 13/09 (**D187**). Foi rodado à mão, 10 de 10, e a falsificação também. ### D17 — Mapeamento Doctrine divergente do banco — CORRIGIDO `orm:schema-tool:update --dump-sql` propõe **260 comandos**, dos quais **114 são destrutivos**. A causa é que muitas relações estão anotadas como `@ORM\OneToOne` quando na realidade são `ManyToOne`: o Doctrine então acha que precisa criar índice único onde hoje há índice comum. Exemplos do que a ferramenta proporia: `ALTER TABLE clientes ... ADD UNIQUE INDEX (unidade)` (um cliente por unidade), `ALTER TABLE agendas ... ADD UNIQUE INDEX (cliente)` (um agendamento por cliente), `ALTER TABLE logradouros DROP tipo`. **Rodar `orm:schema-tool:update --force` contra a produção destruiria o banco.** Nunca executar. O comando é sugerido em vários tutoriais de Doctrine, então vale o aviso explícito para quem entrar no projeto. **Medido em 30/08/2026, e o número é redondo demais para ser coincidência:** `scripts/conferir-relacoes-doctrine.php` confronta cada anotação com o índice que a coluna realmente tem, e o resultado é **114 de 114**. Nenhuma `@ORM\OneToOne` do sistema tem índice único que a sustente. Não é um subconjunto a triar: são todas. E 114 é exatamente o número de comandos destrutivos que o `schema-tool` propõe — os dois números são o mesmo fato visto de dois lados. **O critério é objetivo, e é de propósito.** A ferramenta não julga o domínio, que seria opinião: ela pergunta se o banco garante unicidade sobre a coluna. Uma relação é `OneToOne` de verdade quando há índice único; sem ele, a coluna aceita repetição e a anotação está mentindo. É a mesma medida que o `schema-tool` usa para propor o que propõe. #### CORRIGIDO em 30/08/2026, e a verificação achou uma segunda forma As 114 anotações viraram `ManyToOne` — 114 linhas trocadas em 59 arquivos, uma substituição de um para um. Antes de trocar, conferi que nenhuma tinha `mappedBy`, `cascade`, `orphanRemoval` ou `fetch`: as 114 eram idênticas em forma, o que tornava a troca segura de fazer em bloco. **O `schema-tool` continuou propondo quatro `ADD UNIQUE INDEX` depois disso**, e foi assim que a segunda forma apareceu. Não vinham de anotação de relação e sim de `unique=true` dentro do próprio `@ORM\JoinColumn`, em `Privilegio` e `PrivilegioUsuario` — a mesma afirmação de unicidade escrita de outro jeito, e portanto invisível a um roteiro que procurasse só por `OneToOne`. As quatro eram falsas do mesmo modo: `privilegios.grupo` e `privilegios.funcionalidade` têm índice **comum**, e a unicidade real do domínio é a do par — que existe no schema PostgreSQL como `UNIQUE (inquilino_id, grupo, funcionalidade)`. Afirmar unicidade em cada coluna separadamente diria "um privilégio por grupo", que é outra coisa. O roteiro passou a procurar as duas sintaxes. **Procurar por uma sintaxe encontra uma sintaxe, e não o problema** — foi o `schema-tool` quem me corrigiu aqui. **O resultado, medido nos dois estados:** | | Antes | Depois | |---|---:|---:| | `ADD UNIQUE INDEX` propostos | **114** | **0** | | Comandos totais propostos | 269 | 269 | Os 269 comandos totais não mudaram, e isso é esperado: eles são a divergência inteira entre mapeamento e banco, que inclui tipos de coluna, tamanhos e outras coisas fora do escopo deste débito. > **Correção de 30/08/2026, e é a mais importante desta página.** Este parágrafo > terminava assim: *"o que mudou é que nenhum deles destrói dados agora — os que > restam alteram definição, não unicidade"*. > > **É falso, e medido.** Dos 269, **quatro apagam coluna**, e três delas têm > conteúdo: > > | Comando | Linhas | Preenchidas | > |---|---:|---:| > | `ALTER TABLE usuarios_acessos DROP local` | 1.880.078 | **1.804.389** | > | `ALTER TABLE logradouros DROP tipo` | 709.440 | **709.440** | > | `ALTER TABLE vendas DROP desconto_motivo` | 2.269.212 | 425 | > | `ALTER TABLE usuarios DROP senha_php83` | 2.430 | 0 — sai no deploy da F1.1 (**D7**) | > > São **2.514.254 valores** que um `--force` destruiria hoje. E `logradouros DROP > tipo` está nomeado como exemplo **quatro parágrafos acima**, no texto original > deste mesmo débito — a frase corrigida contradizia a própria página. > > **DUAS CORREÇÕES DE 31/08/2026, e a segunda muda o sentido do número.** > > A primeira: `logradouros.tipo` **saiu da lista**. Não porque a coluna sumiu, > mas porque foi **mapeada** na entidade (**D74**) — o `schema-tool` parou de > querer apagá-la. São 3 comandos agora, não 4. > > A segunda: **o número está certo e engana.** Das colunas contadas, duas são > constantes — medido: > > | Coluna | Preenchidas | Valores **distintos** | > |---|---:|---:| > | `usuarios_acessos.local` | 1.804.389 | **1** — sempre `web` | > | `logradouros.tipo` | 709.440 | **1** — sempre `1` | > | `vendas.desconto_motivo` | 425 | vários | > > Ou seja: dos 2.514.254 valores, **2.513.829 são duas constantes**. A > informação que um `--force` destruiria de verdade são os **425** de > `vendas.desconto_motivo`. > > **O aviso não muda** — nunca rodar `--force` —, mas a razão muda: não é o > volume, é que um comando desses não distingue o que vale do que não vale, e > ninguém quer descobrir a diferença depois. > > O que caiu a zero foi o `ADD UNIQUE INDEX`, que é o defeito do D17 e é o que a > tabela acima mede. Generalizar de "os 114 índices únicos" para "nada destrói > dados" foi um salto que ninguém verificou. > > **O aviso continua inteiro: nunca rodar `--force`.** E `vendas.desconto_motivo` > merece nota, porque o nome engana: a coluna que o relatório de descontos usa é > `vendas_produtos.desconto_motivo`, que é outra, e está mapeada. A de `vendas` > tem 425 valores em 2,2 milhões de linhas e ninguém a lê. **Verificação em tempo de execução:** 106 testes de caracterização passam no MySQL e no PostgreSQL, e 35 de contrato — os mesmos números de antes da troca. Confirma o que a análise previa: as 114 eram lado proprietário, e para esse lado o Doctrine usa carregamento tardio nos dois tipos, gerando o mesmo SQL. **Uma coisa que o `orm:validate-schema` acusa e NÃO é desta mudança:** relações bidirecionais sem `inversedBy`, entre elas `Venda#pagamentos` e `Venda#pontuacaoHistorico`. Conferi rodando a validação com a mudança guardada: o erro é idêntico antes e depois. É pré-existente e de outra natureza. > **Correção de 30/08/2026:** este parágrafo dizia "**duas** relações", e são > muitas mais. Contadas: **19 entidades reprovadas, 31 queixas**. As duas de > `Venda` eram as que apareciam na leitura daquele dia, não o total. Ver > **D64**. ### D18 — Regras de negócio presas a ids fixos de banco — CORRIGIDO em 31/08/2026 `VendaPagamentoService` compara ids literais de `formas_pagamentos`: o 5 é tratado como crédito do cliente e o 6 como crédito do programa de fidelidade (linhas 64, 65 e 359). **Ao resolver:** preservar os ids na migração é o mínimo; o correto é substituir a comparação por uma coluna de tipo ou uma constante de configuração. Ver `docs/anomalias-calculo.md`. #### Medido em 30/08/2026, e o quadro mudou nos dois sentidos O débito dizia: **"impacto direto na Fase 1 — se a carga reatribuir chaves primárias, o sistema passa a debitar o crédito errado em silêncio"**. Essa frase saiu daqui, porque **não é o caso desta migração**, e isso se confere no roteiro: - as **83 tabelas** da carga trazem `id` explícito na lista de colunas do `\copy` — nenhuma exceção, conferido uma a uma; - e as sequências são reajustadas depois, com um `setval` que percorre **toda** coluna de identidade do schema. Chave preservada, sequência ajustada. O cenário de reatribuição silenciosa não existe aqui. **Mas a contagem estava curta, e para menos.** O débito nomeia três pontos, num serviço só. São **seis**, em dois: | Onde | O quê | |---|---| | `VendaPagamentoService:65,66` | formas **5** e **6** | | `VendaPagamentoService:359` | forma **6** | | `VendaPagamentoService:544` | formas **2** e **6** | | `VendaService:201,206` | formas **5** e **6** | A forma **2** — Permuta — não estava registrada em lugar nenhum. **E há um id fixo que o débito não menciona, maior que todos os outros juntos:** ```php // VendaPagamentoService:192 if ($venda->getCliente()->getId() != 1) { $this->salvarPacotes($venda); $this->salvarPontuacao($venda, $sessao); $this->gerarCupons($venda, ...); $this->agendaCheckout($venda); } ``` **Uma comparação com o id 1 governa o programa de fidelidade inteiro** — pacotes, pontuação, cupons e o checkout da agenda. O cliente 1 é o avulso, e a regra "avulso não pontua" existe só aqui, escrita como um número. **O que sobra do débito, então**, não é risco de corte: é opacidade. Seis comparações que só quem conhece a tabela consegue ler, e uma sétima que é a regra mais importante do programa de fidelidade disfarçada de `!= 1`. Continua valendo corrigir — mas por legibilidade e por resistência a quem um dia reordenar a tabela, e não porque a migração vá quebrá-las. #### CORRIGIDO em 31/08/2026, por decisão sua: as sete viraram constantes O que pesou na escolha: **a Fase 2 mantém o backend Laminas** — é fachada REST, não reescrita. Este código não vai embora; vai ser lido e mexido por quem construir a fachada. Diferente do D68, onde o argumento de "o legado está de saída" valia, aqui ele não vale. | Constante | Valor | Nome na tabela | |---|---|---| | `FormaPagamento::PERMUTA` | 2 | Permuta | | `FormaPagamento::CREDITO_CLIENTE` | 5 | Crédito Cliente | | `FormaPagamento::CREDITO_PROGRAMA_FIDELIDADE` | 6 | Crédito Prog. Fidelidade | | `Cliente::AVULSO` | 1 | — | **Os nomes vieram da tabela, não do comentário.** Consultei `formas_pagamentos` em 31/08/2026 antes de batizar: batizar constante a partir do que um comentário afirma seria repetir o erro que ela corrige. **O cliente 1 é a exceção, e vale dizer como foi confirmado.** Na cópia anonimizada ele se chama "Cliente 1" — o nome real foi apagado, então a tabela não confirma nada. Quem confirma é `ClienteAvulsoTest`, que afirma em asserção que *"o cliente de id 1 é o avulso e não entra no programa de fidelidade"* e falha se isso mudar. **Nenhuma mudança de comportamento**: os valores são os mesmos, e a suíte de caracterização — que existe justamente para registrar o comportamento de hoje, certo ou errado — passa com as mesmas 203 asserções. Uma varredura larga por `getFormaPagamento()->getId() == ` e `getCliente()->getId() != ` no `module/` inteiro não achou um oitavo caso. **O que NÃO foi feito, e continua sendo o certo de verdade:** uma coluna de tipo em `formas_pagamentos`, para a comparação não depender de id nenhum. Constante nomeada resiste ao leitor distraído; só a coluna resiste a quem reordenar a tabela. É mudança de schema — entra no `mysql.sql`, no `postgres/schema.sql` e na carga —, e schema se mexe no corte. ### D19 — `module/ISApi/src/Entity` não existia — CORRIGIDO em 11/09/2026 O `module.config.php` do ISApi declarava um driver Doctrine apontando para um diretório de entidades que não existe no projeto. Qualquer comando que enumere o mapeamento completo falha com `MappingException`. Foi criado um `.gitkeep` para destravar as ferramentas. **Ao resolver:** o módulo não tem entidades próprias; o certo é remover a declaração do driver do `module.config.php`. Não foi feito na hora por ser alteração de configuração sem cobertura de teste. #### O `.gitkeep` calou o sintoma e deixou a causa Ele fazia as ferramentas pararem de reclamar, e por isso ninguém voltou: a configuração seguiu **afirmando que o módulo tem entidades**, com um diretório vazio existindo só para sustentar a afirmação. O ISApi é controlador, serviço e rota — e nada mais. #### A cobertura veio ANTES da remoção, e era vermelha com ela no lugar `tests/Caracterizacao/MapeamentoDoctrineTest.php`. A afirmação que importa não é "o mapeamento enumera" — com o `.gitkeep`, enumerava. É **todo namespace declarado mapear ao menos uma entidade**. Medido antes de mexer: | namespace do driver | entidades | |---|---:| | **`ISApi\Entity`** | **0** | | `ISBase\Entity` | 4 | | `ISCadastro\Entity` | 15 | | `ISConfiguracao\Entity` | 44 | | `ISFinanceiro\Entity` | 4 | | `ISMarketing\Entity` | 5 | | `ISRelatorio\Entity` | 5 | | `ISVenda\Entity` | 6 | Oito namespaces, 83 entidades, e um driver que não mapeia nada — o único. Com o teste escrito e o driver ainda declarado, a suíte deu **423 testes, 1 vermelho**, e o vermelho nomeava `ISApi\Entity`. Depois da remoção: **423 verdes**. Não é teste de desejo — ele nasceu reprovando o que existia. A cadeia de drivers vem do `EntityManager` (`getConfiguration()->getMetadataDriverImpl()`, um `MappingDriverChain`), e não da leitura do arquivo de configuração: assim o teste prova o que está **em uso**, e não o que está escrito. #### O que saiu, e o que o sintoma original faz agora Saíram o bloco `doctrine` do `module/ISApi/config/module.config.php` — com uma lápide no lugar, explicando por que este é o único módulo sem ele —, o `use` do `AnnotationDriver`, que era o único uso no arquivo, e o diretório com seu `.gitkeep`. **Provado por execução, sem o diretório:** `orm:validate-schema` responde *"The mapping files are correct"* e `orm:info` lista as 83 entidades com `[OK]`. A `MappingException` que motivou o `.gitkeep` não acontece mais — o que a evitava era o diretório; o que a resolveu foi tirar quem a pedia. O `orm:validate-schema` continua saindo com 1 por causa da seção **Database** (*"not in sync with the current mapping"*), que é outro assunto — as 98 colunas do **D65** — e o portão `conferir-schema-tool.sh` confirma *"igual à linha de base"* depois desta mudança. **E o portão de referências da documentação reprovou, com razão:** o título deste débito cita o caminho que acabou de deixar de existir. A citação fica — ela é o assunto do débito —, e o caminho entrou em `$explicadas` de `scripts/conferir-referencias-docs.php` **com o motivo**, que é a porta de saída que aquele roteiro projetou para exatamente este caso. ### D20 — A sangria acima do saldo era aceita — CORRIGIDO; restam 56 caixas negativos Em `ISVenda\Controller\CaixasController::validarFormRetirada` (linha 129): ```php } else if (empty($caixa) && $caixa->getValorFinal(false) < $valor) { $validacao .= "Valor indiponível."; } ``` A condição deveria ser `!empty($caixa)`. Como está, há dois defeitos: 1. **Quando o caixa existe**, `empty($caixa)` é falso e o curto-circuito descarta a comparação de saldo. **A retirada acima do saldo é aceita** e o caixa fica negativo. Confirmado por `CaixaTest::testRetiradaMaiorQueOSaldoDeixaOCaixaNegativo`: saldo de 100,00, retirada de 250,00, caixa em −150,00. 2. **Quando não há caixa aberto**, `empty($caixa)` é verdadeiro e o PHP avalia `$caixa->getValorFinal(false)` sobre `null` — erro fatal em vez da mensagem "Caixa fechado" que a função pretendia exibir. `CaixaService::retirada` não valida nada por conta própria, então não há segunda barreira. **O motivo de adiar era a caracterização, e ele expirou.** Escrevi aqui que corrigir durante a caracterização invalidaria a comparação entre o sistema atual e o novo. A caracterização está feita: os 89 testes são a linha de base, e `CaixaTest::testRetiradaMaiorQueOSaldoDeixaOCaixaNegativo` congela justamente este comportamento — ele falhar é o sinal combinado de que a correção foi aplicada, não um acidente. **O que faltava era um número, e ele está medido** (29/08/2026, na cópia anonimizada — a anonimização reescreve dado pessoal, não valor financeiro): | | | |---|---:| | Caixas negativos | **56** | | De um total de | 125.771 — **0,04%** | | Pior saldo | **−R$ 1.036,80** | | Soma dos negativos | −R$ 6.736,65 | E a distribuição diz mais que o total: | Ano | Negativos | |---|---:| | 2016–2017 | 6 | | **2018** | **41** | | 2019–2020 | 2 | | 2021–2023 | 0 | | 2024–2026 | 7 | **73% estão em 2018.** Foi um episódio, não um regime — e desde então acontece umas duas ou três vezes por ano. O mais recente é de 23/05/2026. **A correção foi aplicada em 29/08/2026**, por decisão sua — e não foi de um caractere só, porque um caractere não bastava. **O `!empty` no controller conserta a tela.** Os dois defeitos de uma vez: a retirada acima do saldo passa a ser recusada, e o caso "caixa fechado" exibe a mensagem em vez de chamar um método sobre `null`. **Mas o serviço não validava nada, e é por ele que os testes passam.** Foi assim que este defeito atravessou a caracterização inteira: `CaixaTest` fala com `CaixaService::retirada()`, nunca com o controller — corrigir só a tela deixaria a correção sem cobertura nenhuma, e o serviço seguiria aceitando. Então a trava foi para o **serviço**, pelo mesmo motivo do D58: protege qualquer chamador, inclusive um endpoint REST da Fase 2 que chame o serviço direto e passe por cima da tela. Devolve `false`, e o controller já atribuía esse retorno a `sucesso` — a recusa chega à tela sem mudança nenhuma lá. **Retirada igual ao saldo continua permitida**, e isso tem teste próprio: é a sangria de fim de expediente, e recusá-la transformaria a correção numa regressão de operação — o caixa não conseguiria fechar em zero. **Dois testes mudaram, e por motivos diferentes:** `CaixaTest::testRetiradaMaiorQueOSaldoDeixaOCaixaNegativo` virou `testRetiradaMaiorQueOSaldoERecusada`. Ele existia para congelar o defeito, e trazia o aviso *"se esta asserção falhar, alguém corrigiu a validação de saldo"*. Foi o que aconteceu. `CaixaAberturaFechamentoTest::testReconciliacaoSubtraiAsRetiradas` zerava o caixa e retirava 30,00 — **uma premissa que só funcionava porque a regra não era cumprida**. O `valor_final` inicial passou de 0 para 100. O que o teste mede não mudou, porque `atualizar()` recalcula do início: 100 + 500 − 30 = 570, igual a antes. #### Os 56 já negativos — DECIDIDO em 31/08/2026: ficam **Por decisão sua, os 56 caixas negativos ficam como estão.** São registro histórico do que de fato aconteceu no caixa, e corrigi-los reescreveria exercícios fechados — o que costuma ter implicação fiscal e é assunto de contabilidade, não de código. O tamanho sustenta a escolha: **0,04% dos caixas**, R$ 6.736,65 acumulados em dez anos, e 73% deles concentrados num único episódio de 2018. A trava que foi para o `CaixaService` em 29/08 impede que a lista cresça, e é ela que fecha o débito de engenharia. **Este débito está encerrado nos dois lados**: o defeito foi corrigido, e o resíduo foi decidido. ### D21 — RETIRADO: os pontos de fidelidade acumulam normalmente **Este débito foi registrado por engano em 16/08/2026 e está cancelado.** O registro afirmava que o saldo de pontos não acumulava a partir da segunda compra, com base em `salvarPontuacao()` só atribuir pontos ao criar o registro de crédito. A observação sobre o serviço estava certa; **a conclusão sobre o sistema estava errada**. O que faltou verificar: `VendasPagamentosController` chama `ClienteService::atualizarPontuacao()` logo depois de `finalizar()`, e essa função **recalcula o saldo somando o histórico válido**. O saldo, portanto, se mantém correto a cada venda. Confirmado por `FidelidadePontuacaoTest::testOrquestracaoCompletaAcumulaOSaldoCorretamente`: duas compras de 90 pontos resultam em saldo 180. O erro veio de caracterizar o serviço isoladamente e concluir sobre o sistema inteiro. `atualizarPontuacao()` é chamada em quatro pontos — o fechamento de venda, o cancelamento, a tela de clientes e o cron de vencimento. **Não há passivo de pontos a acertar.** A orientação anterior de comparar `clientes_creditos.pontuacao` com a soma do histórico para medir divergência não se aplica. O que **permanece válido** como observação de projeto: o serviço de fechamento não mantém o saldo sozinho, e depende de o chamador executar o segundo passo. Uma API REST nova que chame apenas `finalizar()` reproduziria exatamente o defeito que este débito descrevia. Está caracterizado em `testFinalizarSozinhoNaoAtualizaOSaldoNaSegundaCompra` e registrado em `anomalias-calculo.md`. ### D22 — Campos de Lava VIP gravados cruzados nos royalties — CORRIGIDO Em `FranquiaService::royaltiesAtualizar()`, ao persistir a linha de royalties: ```php $royalties->setRetLavavip($faturamento['fat_lavavip']); // Ret recebe FAT $royalties->setFatLavavip($faturamento['ret_lavavip']); // Fat recebe RET ``` Todos os outros pares seguem `setFatX(fat_x)` / `setRetX(ret_x)`. **Só o Lava VIP está invertido.** Com alíquota de 5%, uma lavagem de 40,00 grava faturamento 2,00 e retenção 40,00 — os valores trocados de lugar. Confirmado por `RoyaltiesTest::testCamposDeLavaVipSaoGravadosCruzados`. **Escopo do estrago — a cobrança NÃO é afetada.** A fatura (`RoyaltiesFatura.valor`) usa `ret_total`, que é somado dentro de `royaltiesCalcular()` **antes** do cruzamento, a partir dos valores corretos. O que fica errado é a tabela `royalties` persistida, lida pelo relatório de franquias em `FranquiasController` (por volta da linha 216) — nesse caminho, as colunas de Lava VIP aparecem trocadas. O mesmo controller tem um segundo caminho (linhas 144–191) que **recalcula tudo do zero**, com os valores corretos. Ou seja, o relatório pode mostrar números diferentes para o mesmo período dependendo de qual caminho é exercitado. **Corrigido em 29/08/2026**, e a parte mais útil foi o que a medição prévia mostrou: **não havia histórico a recalcular.** | | | |---|---:| | Linhas de royalties | 32.544 | | **Com valor de Lava VIP** | **0** | | Produtos do tipo `lavavip` | 20, dos quais **19 inativos** | | Itens Lava VIP vendidos na história | **7** | | Último deles | 2022 — a tabela de royalties começa em 2024 | A categoria está praticamente aposentada: sobra **um produto ativo, numa unidade**. O cruzamento existia no código e nunca teve dado para cruzar. Corrigir é prevenção, não reparo. **Um achado de brinde, e ele não é sobre o cruzamento.** Entre os sete itens vendidos como Lava VIP estão três de **"CHOCOLATE TRENTO"** e um produto "AMENDOIM" cadastrado na mesma categoria. O `tipo` do produto é o que define a alíquota de royalty aplicada, então **um produto mal classificado manda receita para o balde errado** — chocolate rendendo alíquota de lava-jato. Os dois estão inativos hoje, e o estrago foi de R$ 15,00 em 2022. Fica registrado porque a causa continua possível: nada impede classificar um chocolate como lavagem. O teste `testCamposDeLavaVipSaoGravadosCruzados` virou `testCamposDeLavaVipVaoParaAColunaCerta`. ### D23 — Cálculo de royalties duplicado entre serviço e controller — CORRIGIDO A mesma lógica de apuração existe em `FranquiaService::royaltiesCalcular()` e, copiada, em `ISRelatorio\Controller\FranquiasController` (linhas 144–191). Foi essa duplicação que permitiu ao D22 passar despercebido: um dos caminhos grava cruzado, o outro recalcula certo. **Corrigido em 30/08/2026.** O controller passou a chamar o serviço, e as duas cópias saíram — **84 linhas**, de 237 para 153 no arquivo. **Conferi por diff antes de remover**, em vez de confiar na palavra "copiada": as únicas diferenças entre as duas versões eram uma linha em branco e a palavra `private`. Eram cópias byte a byte, e eram **duas**, não uma — o controller duplicava também o `royaltiesCalcularCache()`. **Uma imprecisão deste débito e do D22, corrigida ao medir.** Os dois diziam que o relatório "pode mostrar números diferentes para o mesmo período dependendo do caminho". Não pode: a escolha é **por ano** — de 2024 em diante lê o cache, antes disso recalcula —, e a tabela `royalties` começa justamente em 2024. Um período não sorteia caminho. Isso não torna a duplicação inofensiva; torna-a **mais duradoura**. Como os dois caminhos nunca respondem à mesma pergunta, ninguém vê as duas respostas lado a lado — e a divergência do D22 podia durar indefinidamente sem que nada a denunciasse. **Ficou um teste amarrando os dois:** `RoyaltiesTest::testOsDoisCaminhosDoRelatorioConcordam` compara campo a campo o que cada apuração devolve para o mesmo período. Conferi que ele acusa: reintroduzindo o cruzamento do D22, falha. Divergirem de novo passa a ser falha de teste, e não descoberta de alguém meses depois olhando um relatório estranho. ### D24 — Consultas com `GROUP BY` incompatíveis com o PostgreSQL — ZERADO em 05/09/2026 O código tem consultas que projetam colunas não agregadas fora do `GROUP BY`. Isso é aceito porque a produção roda **sem `ONLY_FULL_GROUP_BY`** — confirmado por evidência: o `sql_mode` gravado nos dois eventos do banco (ver D26) não inclui esse modo. **O PostgreSQL sempre exige agrupamento completo e não tem modo permissivo.** Não é ajuste de dialeto; é reescrita de consulta. #### Inventário (auditoria de 16/08/2026) `scripts/auditar-group-by.php` varre os repositórios por método e classifica as **71 consultas** com `GROUP BY`: | Classe | Qtd. | Significado | |---|---:|---| | **RISCO ALTO** | 4 | Projetam a entidade inteira agrupando por algo que não é a chave primária dela. Quebram com certeza. | | **REVISAR** | 29 | Projetam campos de outros aliases fora do agrupamento. Cada uma precisa de decisão. | | OK | 38 | Só agregações, ou dependência funcional da chave primária — o PostgreSQL aceita. | As quatro de risco alto: - `ISCadastro/Entity/AgendaRepository.php:172` — `SELECT age ... GROUP BY pro.id` - `ISRelatorio/Entity/DashboardColaboradorRepository.php:87` — `GROUP BY col.id` - `ISRelatorio/Entity/DashboardColaboradorRepository.php:134` — `GROUP BY das.colaborador` - `ISVenda/Entity/VendaProdutoRepository.php:291` — `GROUP BY pro.id` #### Confirmação por execução (navegação no ERP, 17/08/2026) Com o modo estrito ligado, logado no ERP sobre a base real anonimizada, foram varridos os 18 relatórios e as telas de agenda, clientes e comandas. Resultado: | Confirmado quebrando | Como | |---|---| | `VendaProdutoRepository:291` | geração de cupons no fechamento de venda (suíte) | | `DashboardColaboradorRepository:87` | **relatório Dashboard de Colaboradores devolve HTTP 500** | O segundo é o mais eloquente: `SELECT` da entidade do dashboard com `GROUP BY u1_.id`. É uma tela que o franqueado usa, e que **deixaria de abrir** no PostgreSQL. As outras duas de risco alto (`AgendaRepository:172` e `ClienteRepository:410`, além de `UnidadeRepository:290` e `VendaRepository:781`) não foram alcançadas: vivem em ações que exigem parâmetros específicos ou em telas cujo `/index` só mostra o formulário de filtro, executando a consulta pesada apenas na submissão. **Isso não as inocenta** — significa que a varredura por navegação é rasa por natureza. A análise estática continua sendo o inventário; a navegação serve para confirmar e para medir o impacto visível. Um achado lateral da varredura: `/mod-relatorios/rel-franquias/index` devolve 500 por template de view ausente — o controller tem apenas as ações `potenciais` e `royalties`. Não é problema de SQL, mas é uma rota morta publicada. #### Como reproduzir e acompanhar O auditor roda no CI a cada push, sem falhar o build — é inventário de trabalho, não regressão. Para ver o detalhe de cada consulta: ```bash docker compose exec app php scripts/auditar-group-by.php --detalhe ``` Para o teste dinâmico, que pega o que a análise estática não vê, comente a linha `command:` do serviço `mysql` no `docker-compose.yml` (ou rode `SET GLOBAL sql_mode='ONLY_FULL_GROUP_BY,...'`) e exercite o sistema. A cobertura melhora bastante com a base anonimizada carregada, porque muitos relatórios só executam a consulta pesada quando há dados. **Ao resolver:** as 4 de risco alto primeiro, depois triar as 29. A regra do PostgreSQL é simples — ou o campo está no `GROUP BY`, ou está dentro de uma agregação, ou depende funcionalmente de uma chave primária que está no `GROUP BY`. #### ZERADO, e o inventário virou portão — 05/09/2026 | | | |---|---:| | consultas com agrupamento | 105 | | **que o PostgreSQL recusa** | **0** | | suprimidas, com motivo escrito | 4 | | aprovadas | 101 | **O passo do CI deixou de ser tolerado.** Ele nascera com `continue-on-error` porque era *inventário*: havia quebras, e o número servia para acompanhar a redução da lista. Inventário que chegou a zero vira guarda — a partir daqui uma consulta nova incompatível **derruba o build** em vez de virar mais uma linha de relatório que ninguém lê. *Posto à prova antes de confiar:* quebrei uma consulta de propósito (`IndicacaoRepository::listarPorClienteIndicador`, com `GROUP BY ind.unidade` e colunas nuas ao lado) e o passo saiu com **1**; restaurada, voltou a **0**. ##### A quarta supressão, e o alarme falso que ela desfaz A quarta linha não é uma quebra dispensada: é a **única consulta do sistema montada por `QueryBuilder`**, e por isso o auditor não conseguia fatiá-la — ele lê DQL em texto. Ela aparecia sob o cabeçalho *"NÃO FOI POSSÍVEL LER — não estão aprovadas, estão fora da análise, o que é pior"*, sendo um `COUNT(vis.id)` com quatro filtros, **sem `GROUP BY` nenhum** e sem outra coluna projetada. Agregado sozinho é válido nos dois bancos: risco zero. **Alarme falso num portão ensina a ignorar o portão.** O auditor passou a honrar a marcação `@agrupamento-conferido` também no ramo em que desiste de ler — a justificativa já era exigida com no mínimo 40 caracteres, e agora vale nos dois ramos. *A marcação ficou dentro do método, e não no bloco de documentação:* o auditor lê o trecho a partir da linha da assinatura, então um comentário acima dela não é visto. Descobri isso porque a primeira tentativa não surtiu efeito nenhum. *O visagismo continua fora de qualquer trabalho de migração, por decisão sua* — o que entrou ali foi um comentário, e nenhuma linha de código. ### D25 — `expirarPontuacao()` depende de quem rodou antes — CORRIGIDO em 30/08/2026 `PontuacaoHistoricoRepository::expirarPontuacao()` monta um DQL com `DATE(his.dataCriacao)` mas **não registra** a função customizada `ISBase\Doctrine\DateFunction`. Quem registra é o método irmão `selecionarCientesPontuacaoVencida()`. O vencimento de pontos só funciona hoje porque o cron chama os dois nessa ordem: ```php $clientes = $rep->selecionarCientesPontuacaoVencida(); // registra DATE $rep->expirarPontuacao(); // depende do registro ``` O registro fica na **configuração do EntityManager, que é global e persistente** no processo. Por isso a falha é intermitente: depende do que mais rodou antes na mesma requisição. Inverter as duas linhas, ou chamar a expiração de qualquer outro ponto, quebra o vencimento com `QueryException`. Descoberto porque o teste isolado falhava e o mesmo teste passava na suíte completa — outro caso já havia registrado a função. **Corrigido em 30/08/2026 pelo caminho mais amplo**, que era o certo: as oito funções de DQL do sistema passaram a ser declaradas em `config/autoload/doctrine.global.php`. A ordem de chamada deixou de ser fator — elas existem desde a criação do EntityManager, para todo mundo. A auditoria sugerida aqui deu o tamanho do padrão: **154 chamadas de `addCustomDatetimeFunction()` em 30 arquivos**, para oito funções distintas. Nenhuma registrava classe diferente para o mesmo nome, o que tornou a centralização segura. **As 154 chamadas foram removidas em seguida**, em mudança separada — 227 linhas a menos em 29 arquivos. A separação se pagou: a remoção fez cair um teste, e ter sido a única mudança daquele commit tornou a causa imediata. O teste que caiu era `testApenasUmDosDoisMetodosRegistraAFuncaoDate`, em `FidelidadeResgateVencimentoTest`, e ele **congelava este próprio débito** — afirmava que um método registra a função DATE e o outro não. Foi invertido em vez de apagado: agora garante que **nenhum dos dois** registre, porque reintroduzir o registro em tempo de execução traria de volta o padrão em que a ordem de chamada importa. A declaração global passou a ser a fonte única, e esse teste é o que impede a volta silenciosa da outra. A remoção não foi um não-evento, portanto. Foi verificada por um teste que existia justamente para notá-la. **Cobertura:** `tests/Caracterizacao/FuncoesDqlDeclaradasTest.php`. Seis casos exercitam cada função em DQL real, e um sétimo chama `expirarPontuacao()` **sozinha** — que é o sintoma original deste débito. Vale registrar o que tornava esse sintoma tão difícil: **o caso isolado falhava e o mesmo caso passava na suíte completa**, porque outro teste já havia registrado a função. Uma falha que some quando se roda tudo é a falha que ninguém investiga. #### O TÍTULO FICOU SEM MARCA POR QUINZE DIAS — e a régua o contava como aberto O corpo deste registro diz **"Corrigido em 30/08/2026"** desde o dia do conserto. O título não dizia, e `scripts/contar-debitos.php` lê o título. Resultado: um débito fechado em agosto contado entre os abertos até 14/09/2026. Não é detalhe de contabilidade. É a mesma família do **D186** — *o número que a régua dá depende de onde ela olha* —, e a lição prática é curta: **fechar um débito inclui marcar o título**, porque o corpo não é lido por régua nenhuma. #### E A GUARDA ERA MAIS ESTREITA DO QUE A FRASE QUE ELA DEFENDE `testNenhumDosDoisMetodosRegistraFuncaoDeDql` diz, no próprio comentário, que protege contra *"alguém reintroduzir o registro em tempo de execução"*. A afirmação é sobre o sistema; a checagem lia **um arquivo** — `PontuacaoHistoricoRepository.php`. As 154 chamadas removidas em 30/08 vinham de dezenas de repositórios, e **34 arquivos de `module/` usam função de data em DQL**. Qualquer um deles podia reintroduzir o registro, e o padrão *"a ordem de chamada importa"* voltaria inteiro sem aquele teste ver. Agora há `testNenhumArquivoDoSistemaRegistraFuncaoDeDqlEmTempoDeExecucao`, que varre `module/` inteiro. **Ele lê por token, e não por texto:** `ClienteCreditoRepository.php:59` tem a chamada dentro de um método **comentado**, e uma varredura por `grep` acusaria código morto. **Falsificado:** reintroduzir a chamada em `VendaRepository.php` — um arquivo que a guarda antiga não alcançava — deixa a suíte vermelha nomeando o arquivo. E a varredura tem piso: menos de 500 arquivos e ela falha, porque verde por ausência de arquivo não é verde. #### O QUE O DEFEITO CUSTAVA, medido `expirarPontuacao()` tocaria **4.388 linhas, de 3.902 clientes, somando 368.274 pontos** — medido em 14/09/2026. As 64 unidades têm todas o mesmo prazo, 365 dias, então formam **um único grupo**: uma só exceção derrubava a rotina inteira. Não é "os pontos não expiram para alguns": é a expiração inteira parada. **E o número cresce todo dia, por construção.** O corte é `DATE(NOW() - INTERVAL 365 DAY)`, então cada virada de meia-noite traz mais um dia de pontuação de um ano atrás para dentro da faixa vencida. Medindo a mesma consulta na véspera dava 3.426 linhas; **962 linhas entraram em um dia**. Enquanto a rotina não roda, a fila não fica parada — ela engorda. ### D26 — Dois eventos agendados dentro do banco — PREPARADO em 07/11/2026: as duas limpezas viraram rotinas O dump completo de 16/08/2026 revelou dois `EVENT` do MySQL, invisíveis para o código da aplicação: | Evento | Frequência | O que faz | Estado | |---|---|---|---| | `limpar_push_app_24h` | a cada 1 hora | `DELETE FROM push_app WHERE data < NOW() - 24h` | `ENABLE` | | `evt_agendas_exclusoes_limpar` | a cada 1 dia | `DELETE FROM agendas_exclusoes WHERE data_exclusao < NOW() - 60 dias` | `DISABLE ON SLAVE` | Não há trigger, procedure, function nem view — só estes dois. **Por que importa na Fase 1:** o PostgreSQL **não tem event scheduler**. Não há tradução automática; é preciso `pg_cron`, um agendador externo ou mover a rotina para a aplicação. Como ambos fazem retenção de dados, perdê-los na migração faz as duas tabelas crescerem sem limite — silenciosamente, porque nada quebra. Dois detalhes que o dump também entregou: - O `DEFINER` de ambos é **`andre`@`%`**, um usuário de banco que não aparecia em nenhum inventário. Entra na apuração do D3 e do D9 (quem tem acesso ao banco). - O `sql_mode` gravado nos eventos é `STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION`, **sem `ONLY_FULL_GROUP_BY`**. Isso confirma por evidência o que o D24 até então apenas inferia, e valida a configuração adotada no ambiente de desenvolvimento. **Apurado em 19/08/2026.** O `@@event_scheduler` está **ON**, mas os dois eventos não estão no mesmo estado: | Evento | Estado | Intervalo | Última execução | |---|---|---|---| | `limpar_push_app_24h` | `ENABLED` | 1 hora | 19/08/2026 09:35 | | `evt_agendas_exclusoes_limpar` | **`SLAVESIDE_DISABLED`** | 1 dia | **nunca** | #### Apurado em 19/08: a causa está na própria definição O responsável confirmou que este servidor é o **master**, com slaves ligados a ele, e que nunca foi promovido. A explicação não é linhagem de réplica — está escrita no evento: ```sql EVENT `evt_agendas_exclusoes_limpar` ON SCHEDULE EVERY 1 DAY ... DISABLE ON SLAVE DO DELETE FROM agendas_exclusoes WHERE data_exclusao < DATE_SUB(NOW(), INTERVAL 60 DAY) ``` A cláusula `DISABLE ON SLAVE` foi escrita de propósito. E o outro evento, `limpar_push_app_24h`, **não a tem** — é justamente ele que está `ENABLED` e executando de hora em hora. A diferença entre os dois é essa linha. **O efeito independe da causa: a limpeza nunca rodou.** Está agendada desde 26/03/2026, e `agendas_exclusoes` acumula desde então. #### Cuidado ao ligar: são três réplicas do outro lado Habilitar é uma linha: ```sql ALTER EVENT evt_agendas_exclusoes_limpar ENABLE; ``` **Mas não faça isso antes de contar.** A primeira execução apagaria de uma vez tudo que passou de 60 dias desde março — num único `DELETE`, que vira um único evento de binlog e atravessa as três réplicas. `DELETE` grande em master com réplicas é causa clássica de atraso de replicação, e o atraso aqui atinge o modo degradado de contingência. Contar primeiro: ```sql SELECT COUNT(*) AS seriam_apagadas, MIN(data_exclusao) AS mais_antiga FROM agendas_exclusoes WHERE data_exclusao < DATE_SUB(NOW(), INTERVAL 60 DAY); ``` Se o número for grande, apagar em lotes **antes** de habilitar o evento — assim a primeira execução automática já encontra pouca coisa: ```sql DELETE FROM agendas_exclusoes WHERE data_exclusao < DATE_SUB(NOW(), INTERVAL 60 DAY) LIMIT 5000; -- repetir até zerar, observando o atraso das réplicas ``` #### A contagem foi feita em 30/08/2026, e ela contradiz este débito Rodada na cópia anonimizada — que é um retrato de **16/08/2026**, não a produção de hoje: | | | |---|---:| | Linhas em `agendas_exclusoes` | 20.608 | | Com mais de 60 dias | 4.105 | | **Mais antiga** | **2026-06-17 15:44** | | Mais recente | 2026-08-16 18:57 | **O débito diz que a tabela "acumula desde 26/03/2026". Não acumula:** não há uma única linha anterior a 17/06. E a data não é qualquer uma — é **exatamente sessenta dias** antes de 16/08 às 15:44. **Não é a funcionalidade estreando em junho**, e a distribuição por dia mostra por quê: ``` 2026-06-17 105 <- dia parcial, cortado as 15:44 2026-06-18 334 2026-06-19 503 2026-06-20 337 ``` Estreia teria rampa de adoção. Aqui o primeiro dia é **truncado** e o segundo já está em volume pleno. É a assinatura de um `DELETE` de retenção que rodou, e não de uma tabela que começou a encher. **Também não é a coleta que filtrou:** `anonimizar.sql.modelo` só anula `observacao` nessa tabela, e não há recorte por data na extração. E o código da aplicação apenas **insere** — `AgendaService::arquivarAgendaExclusao()` é a única escrita, e não há `DELETE` em lugar nenhum. **A conclusão que a evidência sustenta:** alguma coisa apagou as linhas com mais de 60 dias, em 16/08 por volta das 15:44. **O que não dá para saber daqui é o quê** — o evento continua `SLAVESIDE_DISABLED`, então ou alguém o executou à mão, ou existe um `cron` no sistema operacional fora do inventário. **Ao ler a produção de novo, conferir primeiro:** ```sql SELECT MIN(data_exclusao), MAX(data_exclusao), COUNT(*) FROM agendas_exclusoes; SHOW EVENTS; -- LAST_EXECUTED de evt_agendas_exclusoes_limpar ``` Se o mínimo continuar colado nos 60 dias, a limpeza está acontecendo por um caminho que este projeto não mapeou — e **um apagador não inventariado é pior que um apagador desligado**, porque some na migração sem que ninguém saiba que existia. **O que isso NÃO muda:** o PostgreSQL continua sem event scheduler, e a retenção das duas tabelas continua precisando de dono explícito depois do corte. A pergunta que mudou é se hoje ela já tem um, e qual. O primeiro roda de verdade e a F1.6 precisa migrá-lo. **O segundo nunca executou** — a limpeza de `agendas_exclusoes` que ele deveria fazer não acontece desde que foi criado. E o estado dele diz mais: `SLAVESIDE_DISABLED` é o que o MySQL marca num evento que **chegou por replicação**. Ou seja, este banco tem linhagem de réplica — foi promovido, restaurado a partir de uma, ou ainda replica de algum lugar. **Vale esclarecer qual é o caso**, porque isso toca diretamente o desenho de redundância da F1.7. **Ao resolver:** decidir o destino de cada rotina antes da virada. #### A resposta 127 do dono (12/10/2026), e a 168 que a cruza na fila (14/10/2026) **Decidido pelo dono em 12/10/2026** (a pergunta 127 do lote, a opção (a), a recomendada): *"As duas viram rotinas do crontab, com os prazos de hoje -- 24 h para a fila e 60 dias para o arquivo."* Ainda não feito: nenhuma rotina do código apaga a `push_app` por idade nem a `agendas_exclusoes` (lido em 14/10/2026). **A resposta 168 (14/10/2026, o D478) a cruza na fila:** a mensagem de WhatsApp que falhou sai depois de 7 dias -- e a limpeza de 24 h, a deste evento e a da rotina da 127, a apaga antes. Se a rotina da 127 poupa a falhada (a `cronjob` que começa por `falhou:`) foi ao lote (WHATSAPP-E-APLICATIVO, a verificação de 14/10/2026); quem fizer a rotina da fila lê a resposta antes. E a sobra das 100 linhas por dia das filas do parabéns e do "sentimos sua falta" é apagada por este evento antes de ser mandada (o **D489**). #### As duas rotinas, escritas em 07/11/2026 (a fatia 113, ROTINAS-NOVAS-E-CRONTAB) — PREPARADO Pelas respostas do dono 127 (a) (*"As duas viram rotinas do crontab, com os prazos de hoje"*), 184 (a) (a de 24 h poupa a mensagem que falhou, que sai em 7 dias), 185 (a) (os 7 dias contam do pedido, como estão) e 195 (a) (as duas na etapa 1, e o evento de hora em hora desligado na mesma janela, reversível). Conferido antes: nenhuma ação do `CronJobController` apagava a `push_app` por idade nem a `agendas_exclusoes`; só o `PushAppRepository::apagarFalhasAntigas` (a falhada de 7 dias, o D478) existia. - **`/api/cronjobs/pushAppLimpar`** (`CronJobService::pushAppLimpar`, `PushAppRepository::apagarPendentesAntigas`): apaga a linha da fila com a `data` mais antiga que agora menos `PushApp::HORAS_DA_PENDENTE_NA_FILA` (24) horas, com o `<` estrito do evento, **menos a falhada** (`cronjob` começando por `falhou:`). De hora em hora, aos 35 minutos, como o evento — e a sobra do parabéns e do "sentimos sua falta" sai antes do envio das 10:00, como hoje (o D489; a 186 (c)). - **`/api/cronjobs/agendasExclusoesLimpar`** (`CronJobService::agendasExclusoesLimpar`): apaga o horário desmarcado com `data_exclusao` de mais de `CronJobService::DIAS_DO_ARQUIVO_DE_EXCLUSOES` (60) dias. Uma vez por dia, às 02:40. Pelo DBAL, porque a tabela não tem entidade. - **No molde das outras:** a guarda do token primeiro (o 401 do D4), a trava (`TravaDeExecucao`, com a conexão no PostgreSQL) com `{"sucesso": false, "mensagem": "Processo já em execução."}`, e a linha no log das rotinas (a da fila só quando apagou alguma; a do arquivo todo dia, com zero também). **Em lotes de 5.000**, pelo id, e não num DELETE só: o aviso das três réplicas deste débito. As rotas sem login na `rotas-publicas.php` e no `conferir-rotas-sem-login.php`, as páginas em `/api/docs/cronjobs`, o inventário de ações regerado, e as duas no `--conhecidas=` do `conferir-agendamento.php` no `scripts/conferir-tudo.sh` (como a dos convênios: esperam a janela). - **As linhas** em `docs/crontab-a-aplicar.md`, na forma do crontab novo (o D331: o cabeçalho, o `-fsS`, o domínio raiz e o `|| logger -t rotinas`); **o passo 12 da etapa 1** as põe no crontab e desliga o `limpar_push_app_24h`. - **O `ALTER EVENT`, medido num banco descartável** (o MySQL 8.4.13 local, apagado no fim): o `DISABLE` e o `ENABLE` mudam o estado, e **trocam o `DEFINER` pela conta que os roda** (`franquiabv@%` virou `root@localhost`); com `ALTER DEFINER= EVENT ...`, o `DEFINER` fica. O passo 12 e a volta da etapa 1 passaram a essa forma. - **A cláusula sem o privilégio (a verificação da 113, medido no mesmo dia, de novo num descartável do 8.4.13, com duas contas descartáveis apagadas no fim):** uma conta só com o banco, diante do evento de outra (como o do `andre`), recebe `ERROR 1227 ... SUPER or SET_ANY_DEFINER` no `ALTER DEFINER=... EVENT ... DISABLE`, e nada muda (`ENABLED`, o mesmo `DEFINER`); sem a cláusula, a mesma conta desliga **e vira a dona**; e a volta com a cláusula, pela mesma conta, também recusa — só uma conta com o privilégio devolveu o dono. No 8.4 o privilégio é o `SET_ANY_DEFINER` (o `SET_USER_ID` do 8.0 não existe mais). O passo 12 dizia "sem ele, o `ALTER EVENT` sem a cláusula, e o `DEFINER` novo anotado": trocar o dono de um objeto do banco de produção como recurso do roteiro. Agora o privilégio se confere antes da janela, e, recusada a cláusula na janela, a linha PARA com o evento ligado, como hoje (nada se perde além do de hoje: a falhada sai em 24 h até ele se desligar); o que fazer nesse caso foi ao lote (TELAS-RESTANTES [corte], 07/11/2026; recomendada a (a), o evento ligado até uma conta com o privilégio). **Provado** (`tests/Caracterizacao/D26LimpezasNoCrontabTest.php`, 9 casos, nos dois bancos): a fronteira de cada prazo dos dois lados (24 h e um segundo sai, 24 h exatas fica; 60 dias e um segundo sai, 60 dias exatos fica), a falhada poupada (de ontem e de dezembro), a conta devolvida igual à do banco, a segunda rodada sem nada e sem linha no log, 5.001 linhas saindo todas (os lotes), a desistência com a trava detida, e a linha do log do arquivo com zero; e, desde a verificação da 113, **a resposta das duas rotas** (`testAsRotasDizemQueDesistiram`, com um serviço de mentira): `{"sucesso": false, "mensagem": "Processo já em execução."}` com a trava detida, `{"sucesso": true}` com uma conta (o zero também), e o 401 sem o token certo, sem chamar a rotina — antes, a rota que respondia sempre `sucesso: true` passava (o espião do `SegredosForaDoCodigoTest` nunca devolve `false`; os mutantes R1 a R5, vermelhos nos dois bancos). A guarda do token e a página da documentação vêm também do `SegredosForaDoCodigoTest`, que lê as ações e as rotas sem lista. **Não provado:** as rotinas na produção ou no BVIP, e o `ALTER EVENT` na produção (o item 11 de "O que falta" da etapa 1); quem apara hoje a `agendas_exclusoes` aos 60 dias (a leitura 11 da etapa 1). **O que resta:** a janela da etapa 1 — as linhas no crontab e o evento desligado. ## Sem prazo definido ### D10 — Cobertura de testes limitada ao núcleo financeiro — REENQUADRADO em 11/09/2026: deixou de ser verdade, e o que falta é o VALOR dos relatórios — PARCIAL, lido em 05/10/2026 — PARCIAL em 05/10/2026 > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito como fechado, e o corpo diz que ele está parcial: uma parte está consertada, e a outra não. Falta: o par Visagismo::listagemIndexRelatorio, adiado pelo dono; e uma venda de cenário com mais de um item descontado, para distinguir o enraizamento no item. > **05/10/2026, depois da nota:** a venda de dois itens descontados entrou, com caso e mutante (a seção "A VENDA DE DOIS ITENS DESCONTADOS", no fim deste débito). Falta só o Visagismo, adiado pelo dono. *Atualizado em 17/08/2026.* O registro anterior dizia que o sistema não tinha nenhum teste. Deixou de ser verdade: as frentes W3 e W4 entregaram **95 testes** — 67 de caracterização sobre venda, caixa, fidelidade, royalties, convênios e cupons, e 28 de contrato congelando o formato da API do aplicativo. O que **permanece** em aberto é a cobertura fora desse núcleo. Agenda, cadastros, marketing, financeiro e os 18 relatórios não têm teste nenhum. A escolha foi deliberada: caracterizar primeiro o que envolve dinheiro, porque é onde um erro silencioso durante a migração custa mais caro. **Ao resolver:** conforme cada módulo for reescrito na Fase 3, o teste de caracterização do comportamento atual vem antes da reescrita — não depois. #### O parágrafo acima envelheceu, e o inventário de 11/09/2026 o desmente Ele é de 17/08/2026 e diz duas coisas que deixaram de ser verdade: que são **95 testes**, e que agenda, cadastros, marketing e financeiro **não têm teste nenhum**. Medido hoje, contando arquivos de teste que tocam cada namespace: | | arquivos de teste | | |---|---:|---| | `ISCadastro` | **28** | cliente, agenda, fidelidade, indicação, endereço | | `ISConfiguracao` | **28** | produto, unidade, usuário, convênio, pacote | | `ISVenda` | **19** | comanda, caixa, pagamento, fiado | | `ISBase` | 12 | utilitários, busca, data, monetário | | `ISApi` | 6 | os endpoints do aplicativo | | **`ISRelatorio`** | **4** | e é aqui que a frase original ainda acerta | | **`ISFinanceiro`** | **3** | o mais magro, junto com marketing | | **`ISMarketing`** | **3** | cupom, sorteio, NPS | E o total: **66** arquivos de caracterização com **423 testes**, mais **3** de contrato com **67**. Não 95. **A agenda não tem módulo próprio** — a entidade mora em `module/ISCadastro/src/Entity/Agenda.php`, e é por isso que a cobertura dela está contada dentro dos 28 do `ISCadastro`: `AgendaApiTest`, `AgendamentoCriadoTest`, `CheckinDaAgendaTest`, `DesmarcarAgendamentoTest`, `FecharAgendaTest`, `RegraDeAgendamentoTest` e `ValidacaoDeAgendamentoTest`. #### E os relatórios não são 18, nem estão descobertos do jeito que a frase sugere São **19 controladores** e **36 ações vivas** no inventário (`docs/inventario-acoes.csv`, nenhuma marcada `MORTA`) — e as 36 são exercitadas em toda execução do CI por `scripts/medir-relatorios-no-postgres.php`, cujo critério é *"nenhum pode quebrar"*. Isso é cobertura de **fumaça**, e não de valor: ela prova que o relatório responde sem erro do servidor nos dois bancos, e não que o número que ele imprime está certo. A distinção importa, e é o que sobra de verdade deste débito: | o que existe | o que falta | |---|---| | as 36 ações respondem sem quebrar, nos dois bancos, a cada execução do CI | nenhuma caracterização do **valor** que elas calculam | As exceções são `DashboardFaturamentoAnosTest` e `RoyaltiesTest`, que caracterizam número de relatório de verdade — e nasceram de defeito encontrado, não de plano de cobertura. **O que continua valendo sem mudança:** a ordem do *"ao resolver"* acima. O teste de caracterização vem antes da reescrita, e não depois. #### E o primeiro de valor existe, desde 12/09/2026 `tests/Caracterizacao/FluxoDeMovimentoTest.php`, seis casos sobre `DashboardMovimentoRepository::selecionarPorMesAnoUindade()` — o relatório de fluxo de movimento, que não tinha teste nenhum. **Por que este primeiro:** ele é o mais sensível à migração entre os descobertos. `FluxoMovimentoController` monta as duas datas como **texto** (`"$ano-$mes-01"` e o último dia do mês) e a consulta compara `dataInicio >= :inicio AND dataFim <= :fim` — com as colunas sendo `date` nos dois bancos e a anotação dizendo `datetime`, que é um dos 70 desacordos que o D65 agora vigia. Cada lado da comparação é de um tipo diferente do declarado, e o parâmetro chega como string: **coerção é onde os dois motores divergem**, e é a família do D42. **O que ele afirma, e o que deliberadamente não afirma.** Nenhum número absoluto é congelado — a regra que o `DashboardFaturamentoAnosTest` já escreveu, porque os números vêm da cópia e mudam a cada coleta. O que está fixo é a relação: | | | |---|---| | a faixa **igual** à linha a inclui | o `>=` e o `<=` na igualdade, nas duas bordas | | um dia depois do início | a linha sai | | um dia antes do fim | a linha sai | | filtrando pela unidade dela | continua achando | | filtrando por outra unidade | não acha | | qualquer linha devolvida | está dentro da faixa pedida | A faixa vem do **valor lido da própria linha**, e não de um literal: a fixture grava `CURRENT_DATE` nos dois campos (`fixtures.sql:919-923`), então ler é o que faz o teste continuar valendo amanhã. E ele **não escreve nada** — só consulta, então não há resíduo a restaurar. **Falsificado:** trocando `>=` por `>` no repositório, exatamente as duas afirmações de inclusividade falham, nomeando a linha `4178`, e as outras quatro continuam verdes — porque tratam de exclusão e de recorte. É o sinal de que o teste mede a fronteira, e não o caminho geral. **E a resposta que a migração precisava:** **429 testes verdes nos dois bancos.** A inclusividade da borda se comporta igual em MySQL e PostgreSQL — o relatório não perde o primeiro nem o último dia do mês no corte. Isso não era sabido antes; era suposto. #### E o que falta deixou de ser "os 18 relatórios": são 37 métodos, com nome "Os relatórios não têm cobertura de valor" não diz a ninguém o que fazer. Medido em 12/09/2026, o vão tem nome e tamanho. Os controladores de relatório chamam **58** métodos de repositório, e **37 distintos não aparecem em teste nenhum**. Eles não moram no `ISRelatorio` — moram onde o dado mora: | módulo do repositório | métodos sem teste | |---|---:| | `ISConfiguracao` | 15 | | `ISVenda` | 10 | | `ISRelatorio` | 7 | | `ISCadastro` | 5 | | `ISFinanceiro` | 1 | **Os onze que calculam dinheiro, que são por onde começar:** | método | relatório | |---|---| | `totalDescontoPorCaixa` | Caixas | | `totalTrocoPorCaixa` | Caixas | | `selecionarPagamentosPorCaixa` | Caixas | | `totalDescontoPeriodo` | Vendas | | `selecionarGorjetasPorColaboradorPeriodo` | Vendas | | `selecionarVendasProdutosPorColaboradorPeriodo` | Vendas | | `selecionarUsuariosComVendas` | Vendas | | `listagemIndexRelatorioDescontos` | Descontos | | `relatorioVendasProduto` | Produtos | | `radarTemperaturaFaturamento` | RadarTemperatura | | `selecionarTotalizadoresPorColaboradorMesAno` | PesquisasNps | **Os 37 são um PISO, e não um total** — duas razões, ditas porque o número sem elas valeria menos. Primeiro: "aparece em teste" é casamento de **substring** no corpo dos testes, que é positivo fraco — um teste que menciona o nome não necessariamente exercita o método, então há métodos contados como cobertos que não estão. Segundo: a detecção de chamada é `$var->metodo(` mais `getRepository(...)->metodo(`, filtrada pelos nomes que existem como `public function` em algum `*Repository.php` — ela não vê chamada que passe por um serviço no meio. **A ordem que isto sugere, e que não é decisão de ninguém:** os de dinheiro primeiro, porque erro silencioso ali sai do bolso de alguém; e dentro deles, os de `Caixas` e `Vendas`, que são onde o D49 (dinheiro em ponto flutuante) e o D65 (tipo da coluna) se encontram. #### A LISTA FECHOU — e fechou num número que a própria medida não sabia contar **12/09/2026.** Quatro arquivos novos e um estendido, 30 casos, verdes nos dois motores. Pela medida do inventário, **43 de 43**: nenhum método da lista sem teste. | arquivo | o que passou a ter teste | |---|---| | `ServicosDoFiltroNoRelatorioTest` | `ProdutoRepository::selecionarProdutos` | | `PesquisasNpsNoRelatorioTest` (estendido) | `unidadeDetalhes`, `colaboradorDetalhes`, `selecionarUnidadesRelatorioNps`, `selecionarUsuariosRelatorio` | | `ComboDeConveniosNoRelatorioTest` | `ConvenioRepository::popularCombobox` | | `AtendimentosNoRelatorioTest` | `DashboardFaturamentoRepository::selecionarPorUnidadeMesAno` | ##### E OS DOIS ÚLTIMOS DA TABELA NÃO ESTAVAM NA LISTA — o nome já contava como coberto A medida casa por **nome de método**, e o registro acima já avisava que isso é positivo fraco. Hoje deu para medir **quanto** fraco. Dos 43 nomes, **oito existem em mais de uma classe de repositório**: | nome | classes que o definem | as que os relatórios realmente chamam | |---|---:|---:| | `popularCombobox` | **13** | 3 — `Unidade`, `Grupo`, `Convenio` | | `relatorioSelecionarAniversariantes` | 3 | 3 | | `listagemIndexAdmin` | 3 | 1 — `VipClass` | | `listagemIndexRelatorio` | 2 | 2 — `Cliente`, `Visagismo` | | `popularComboboxAnos` | 2 | 1 — `DashboardFaturamento` | | `selecionarPorUnidadeMesAno` | 2 | 1 — `DashboardFaturamento` | | `selecionarTotalizadoresPorColaboradorMesAno` | 2 | 1 — `NpsResultadoColaborador` | | `selecionarTotalizadoresPorUnidadeMesAno` | 2 | 1 — `NpsResultadoUnidade` | Resolvendo cada chamada para a classe de verdade — inclusive as quatro que passam por variável, como `$repositoryNpsColaborador` —, a lista deixa de ter 43 nomes e passa a ter **48 pares (classe, método)**. Medindo par a par, com teste que cite a classe **e** o método, **três** estavam abertos: | par | situação | |---|---| | `Convenio::popularCombobox` | vão real — **fechado hoje** | | `DashboardFaturamento::selecionarPorUnidadeMesAno` | vão real — **fechado hoje** | | `Visagismo::listagemIndexRelatorio` | **fora de escopo por decisão do dono** — "ignorar tudo do onesignal, visagismo e sms", anotado como débito futuro | Então o fechamento honesto é **47 dos 48**, e o que falta é o que foi mandado não fazer. ##### O CASO MAIS FEIO FOI O DO NPS, e ele tinha a forma exata do falso positivo `selecionarTotalizadoresPorColaboradorMesAno` existe em `NpsItemRepository` e em `NpsResultadoColaboradorRepository`. A lista do D10 é "métodos chamados pelos controllers de relatório", o nome aparece em `PesquisasNpsController:243`, e por isso entrou. Mas a chamada dali resolve para a **segunda** classe — e varrendo `module/`, `public/`, `config/` e `data/`, a primeira tem **um único chamador, o `CronJobService`**, que não é relatório nenhum. Os cinco primeiros casos do arquivo de NPS, escritos horas antes, cobriram a classe do **cron**. No instante em que ficaram verdes, o nome passou a contar como coberto — e a classe que a tela usa seguiu sem um teste, com `grep -rl NpsResultadoColaborador tests/` devolvendo vazio. É a **quarta** colisão da série, e a pior: nas outras três o nome repetido era comportamento parecido em classes parecidas; aqui são respostas diferentes, e o teste de uma atestou a outra. O caso `testOsDoisHomonimosRespondemNumerosDiferentes` transforma isso em asserção: com o mesmo colaborador, mês e ano, um devolve **2 avaliações / soma 18** e o outro **3 linhas / soma 20**. Fica vermelho no dia em que alguém unificar as duas — e nesse dia o registro precisa ser relido, não atualizado. ##### TRÊS ACHADOS DE COMPORTAMENTO, e cada um saiu de um caso que precisou existir **1. O cabeçalho e o detalhe do NPS discordam sobre o `contabilizado`.** Dois métodos do mesmo arquivo, na mesma tela: o dos totalizadores filtra `nps.contabilizado`, e o `colaboradorDetalhes` não. Cabeçalho diz 2 avaliações e soma 18; o detalhe calcula a média sobre 3 respostas e dá 6,67. A divergência vive na janela entre responder a pesquisa e o cron consolidá-la, a cada 10 minutos. Está em `docs/anomalias-calculo.md`, com a medição e a falsificação. **2. A ordem alfabética muda entre os dois bancos.** Saiu de um caso meu escrito errado — eu comparei a ordem do banco com o `sort()` do PHP, que é byte a byte. O vermelho levou a comparar os dois motores: **376 das 616 posições** trazem nome diferente, por causa de espaço e hífen, não de acento. Virou o **D175**. **3. A regra da linha mais antiga nunca tinha sido medida.** `dashboard_faturamento` não tem restrição de unicidade (D29), e o `ORDER BY das.id ASC` com `setMaxResults(1)` é o que decide qual linha a tela mostra quando o par (unidade, mês, ano) duplica. A cópia tem **zero** pares repetidos em 4.019 linhas, então o caso cria o par dentro da transação. Falsificado: trocando `ASC` por `DESC`, só esse caso fica vermelho. **E um quarto achado que não é de relatório:** `npsContabilizar` divide por zero se a primeira pesquisa do mês de uma unidade não tiver item. Virou o **D176**. ##### DUAS SUSPEITAS QUE NÃO SOBREVIVERAM À MEDIÇÃO Escritas porque custaram tempo e para ninguém refazer o caminho. | suspeita | medição | veredito | |---|---|---| | a média anual de NPS é média de médias, não ponderada | 2 de **1.427** pares colaborador/ano divergem; maior diferença **0,024** em escala de 0 a 10 | imaterial | | a consolidação sobrescreve a linha a cada item da pesquisa | **0** pesquisas com dois itens do mesmo colaborador, em 37.957 | não alcançável | ##### E TRÊS LACUNAS DE CENÁRIO, cada uma destravando um filtro que não se media Nos três casos o cenário de fixtures não tinha o dado que torna o filtro observável, e a linha foi criada **dentro da transação** — não no `fixtures.sql` —, porque é dado de caso e não de cenário. Nada sobra depois, e foi conferido nos dois bancos: zero linhas remanescentes. | o que faltava | o que destravou | |---|---| | nenhum produto **desativado** na unidade (0 de 6) | o `pro.status = :status` de `selecionarProdutos` | | nenhum convênio **inativo**, e o único do cenário sem unidade | o `con.status = true` e os dois ramos do `OR` de unidade | | nenhum par **duplicado** em `dashboard_faturamento` | o `ORDER BY das.id ASC` | E um caso precisou de **sessão**: `ConvenioRepository::popularCombobox` não recebe a unidade por argumento — lê de `SessaoAcl`, e concatena o valor na DQL (sítio do D73). Sem sessão, `getUnidade("id")` devolve `null`, a DQL fica com `conuni.unidade = ` e o analisador recusa. O teste monta o `Container` da sessão à mão; é o único arquivo da série que precisa disso, e com ele ficou provado que o recorte por unidade **funciona** — o que nenhum teste tinha mostrado. ##### O ESTADO MEDIDO NO FIM | | | |---|---:| | caracterização, espelho MySQL do CI | **587** testes, 11 pulados, exit 0 | | caracterização, espelho PostgreSQL do CI | **587** testes, 11 pulados, exit 0 | | contrato | **67** testes, exit 0 | | portões | **33**, sendo 1 vermelho conhecido (D50, espera produção) | Os arquivos novos **não têm nenhuma chamada de pulo** — nem `markTestSkipped` nem `exigeHistoricoDaProducao` —, então os 30 casos executaram nos dois espelhos. Os 11 pulados são de arquivos anteriores, que dependem da cópia de produção. #### E MAIS TRÊS RELATÓRIOS, todos com achado — ainda em 12/09/2026 `ComboboxDeAnosNoRelatorioTest`, `VendasCanceladasNoRelatorioTest` e `AniversariantesNoRelatorioTest`. **Sobram 19 dos 37.** ##### O INVENTÁRIO CASA POR NOME, e dois "métodos" eram cinco O mesmo nome existe em classes diferentes, e o inventário conta uma vez só: | nome | onde mora, de verdade | |---|---| | `popularComboboxAnos` | `DashboardFaturamentoRepository` (o do relatório) **e** `SaidaParcelaRepository` (o da tela de saídas) | | `relatorioSelecionarAniversariantes` | `UnidadeRepository`, `UnidadeSocioRepository` **e** `UsuarioRepository` — três consultas diferentes | Os dois arquivos cobrem **todas** as implementações, e dizem no cabeçalho por quê. E uma suspeita foi derrubada: o `DashboardFaturamentoAnosTest`, apesar do nome, testa `relatorioUnidades` e não o combo — a ausência era real. ##### A ASSIMETRIA DOS TRÊS `:status` ESTÁ CERTA, e agora tem guarda Os três irmãos de aniversariantes passam tipos diferentes no mesmo parâmetro, e os dois de `Usuario` carregam um comentário sobre o **D97**. Medido: | coluna | MySQL | PostgreSQL | o que o método passa | |---|---|---|---| | `unidades.status` | `tinyint(1)` | `boolean` | `true` | | `unidades_socios.status` | `tinyint(1)` | `boolean` | `true` | | `usuarios.status` | `int` | `integer` | `1` | Cada um passa o tipo da **sua** coluna. Uniformizar os três — a coisa mais natural ao ver o mesmo nome três vezes — derruba a tela no PostgreSQL e não quebra nada no MySQL. **Falsificado:** trocando os dois `1` por `true`, três casos ficam vermelhos com a mensagem exata que o comentário previa — *invalid input syntax for type integer: "t"*. O conserto do D97 tinha comentário e não tinha guarda. ##### E UM FILTRO QUE ALGUÉM COMENTOU EM VEZ DE APAGAR `listagemIndexCanceladas` filtra `ven.status = 0`. **(Corrigido em 28/10/2026, o D636: a redação de antes dizia que esse zero "é também o estado de comanda aberta", e não é -- a comanda aberta é o status 3, `RegraDaVendaNoPdv.php:31`; o 0 só sai de `VendaService::cancelar` e da rotina `comandasCancelar`.)** O filtro comentado era para separar a rotina do cancelamento à mão: WHERE ven.status = :status //AND ven.canceladoMotivo != :motivo A intenção de separar cancelamento automático de manual ficou pela metade. O teste **grava o comportamento de hoje** e registra o porquê. ##### DUAS LINHAS DE CENÁRIO, e as duas destravam mais de um filtro | o que entrou | o que destrava | |---|---| | uma parcela de saída **desativada e de 2025** | o filtro `par.status` e a diferença entre um ano e dois no combo | | `data_contratacao` em **dois** usuários, mesmo mês e dias 08 e 25 | o método da contratação inteiro, a ordenação por `DAY()`, e — porque o dia difere do dia de nascimento do mesmo usuário — a distinção entre as duas colunas | ##### E DOIS ERROS MEUS, achados pela execução e não por revisão O primeiro: escrevi `CAST(... AS INTEGER)` no SQL do teste, que é PostgreSQL — o MySQL quer `SIGNED` e respondeu *You have an error in your SQL syntax*. O segundo: passei `false` sem tipo e o PostgreSQL respondeu *invalid input syntax for type boolean: ""*. **É a mesma família que estes arquivos vigiam no código de produção, encontrada no SQL dos próprios testes** — e só apareceu porque a suíte roda nos dois motores. E um terceiro, de raciocínio: afirmei "nada em julho" **sem filtrar unidade**, e a cópia tem 61 unidades e 2.432 usuários. Afirmação de vazio só vale dentro do recorte do cenário. #### TREZE dos 37, e a lista de dinheiro FECHOU menos uma — em 12/09/2026 Seis arquivos novos, 41 casos, verdes nos dois motores: | arquivo | métodos | |---|---| | `VendasNoRelatorioTest` | `totalDescontoPeriodo`, `selecionarUsuariosComVendas`, `selecionarColaborador` | | `PagamentosDoCaixaNoRelatorioTest` | `selecionarPagamentosPorCaixa`, `selecionarPorPeriodoUnidade` | | `DescontosNoRelatorioTest` | `listagemIndexRelatorioDescontos` | | `RadarDeTemperaturaNoRelatorioTest` | `radarTemperatura`, `radarTemperaturaFaturamento` | | `ProdutosNoRelatorioTest` | `relatorioVendasProduto` | | `PesquisasNpsNoRelatorioTest` | `selecionarTotalizadoresPorColaboradorMesAno` | **A LISTA DE ONZE FECHOU.** O último — as **gorjetas** — exigiu acrescentar linha ao cenário: até 12/09/2026 a tabela tinha zero linhas na faixa 9000xxxx, e as 11.938 do banco são todas da cópia, que o CI não carrega. Entraram **três**, e o `fixtures.sql` explica por que três: uma para contar, outra para contar em mês diferente, e uma em venda não finalizada para o filtro de status poder ser distinguido. Com o filtro: 2 gorjetas, R$ 19,80. Sem ele: 3, R$ 118,80. **E A LISTA DE ONZE TINHA UM ERRO DE CLASSIFICAÇÃO:** `selecionarTotalizadoresPorColaboradorMesAno` soma `item.nota`, que é nota de pesquisa e não valor. São **dez de dinheiro e um de nota**. **O ÚLTIMO DELES PRECISOU ESCREVER, e é o único da série que escreve:** o cenário tem **zero** linhas em `nps` e em `nps_itens`. Sem dado não há afirmação, e usar a cópia anonimizada não roda no CI. Ele monta três pesquisas dentro da transação que o `CaracterizacaoTestCase` reverte — o que `ConsolidacaoNpsTest` já faz na mesma tabela. **SOBRAM 23, e agora os 23 são 23.** Por algumas horas foram 23 pela medição e 24 de verdade, e a diferença era minha: a detecção de cobertura é casamento de **substring** no corpo dos testes, e `selecionarGorjetasPorColaboradorPeriodo` tinha saído da lista porque eu escrevi o nome dele num docblock **explicando por que ele NÃO estava testado**. O inventário passou a contá-lo como coberto — o falso positivo que o próprio D10 avisava existir, com um exemplo concreto e, agora, resolvido pelo lado certo: escrevendo o teste. **E a lacuna das gorjetas fechou junto**, com três linhas de cenário e uma décima primeira exclusão na limpeza — `gorjetas.venda` aponta para `vendas` com `NO ACTION`, então sem ela as gorjetas bloqueariam o `DELETE` das vendas, que é o mesmo defeito corrigido horas antes. ##### O RELATÓRIO DE VENDAS NÃO TINHA COBERTURA NENHUMA, nem de fumaça O portão `medir-relatorios-no-postgres.php` lista `rel-vendas/index` entre as ações `SEM_TABELA_PROPRIA`, com esta justificativa: *"formulario; o dado sai em rel-vendas/exportar"*. A justificativa está certa — o `index` é mesmo só o formulário. Mas **`rel-vendas/exportar` não é chamado em lugar nenhum**: procurar por ele em `scripts/`, `tests/` e `.github/` devolve **uma** ocorrência, que é a própria linha da justificativa. O mesmo vale para `rel-atendimentos/index`, que aponta para `rel-atendimentos/gerar`. As outras duas exclusões da lista apontam para endereços que **são** medidos, e a diferença é verificável contando ocorrências: **duas** para as que valem, **uma** para as que não. Quatro métodos passavam por ali sem nunca ter rodado contra PostgreSQL em conferência automática nenhuma. ##### E TRÊS LACUNAS DE CENÁRIO, ditas em vez de disfarçadas Cada uma está escrita no cabeçalho do arquivo que a encontrou, com o que faltaria: | o que não se distingue hoje | o que faltaria | |---|---| | as **gorjetas** por colaborador | o cenário tem **zero** linhas em `gorjetas`; o banco inteiro tem 11.938, todas da cópia | | *"a listagem é enraizada no ITEM"*, a decisão central do relatório de descontos | nenhuma venda do cenário tem **mais de um** item descontado; com um item por venda, enraizar no item ou na venda dá a mesma contagem | | `SUM` contra `AVG` no radar, filtrado pela unidade | `dashboard_colaboradores` tem **uma** linha do cenário, e com uma linha as três agregações coincidem | A terceira foi contornada medindo **sem** o filtro de unidade, sobre as milhares de linhas da cópia. As duas primeiras esperam linha de cenário. #### TRÊS dos onze de dinheiro, e o terceiro é o que mais valia `tests/Caracterizacao/VendasPorColaboradorNoRelatorioTest.php` cobre `selecionarVendasProdutosPorColaboradorPeriodo`. **Sobram 34 dos 37.** Aquele método carrega um comentário de vinte linhas sobre um defeito **já corrigido em 26/08/2026** — e nada testava a correção. O comentário mede o estrago (380 grupos no relatório de avulso, 380 no de pacote, erro de até **R$ 1.240** numa linha) e enuncia a invariante que o conserto restabelece: *"com a média ponderada, `valorUnitario × quantidade` volta a ser exatamente `SUM(quantidade × valorUnitario)`"*. Conserto feito, medido à mão, e deixado **sem guarda** por dezessete dias. **O cenário consegue distinguir média de escolha arbitrária, e isso foi conferido antes de escrever** — é o que dá força à afirmação. Medido nas fixtures: colaborador 90001000, produto 90001000, duas linhas de `89,90` e `110,00`, média ponderada **99,95**, que não é nenhum dos dois. **Falsificado, e a falsificação reproduz o defeito original com números:** trocando a expressão de volta por `venpro.valorUnitario`, o MySQL escolhe `89,90`, e `89,90 × 2 = 179,80` contra os `199,90` reais — **R$ 20,10 de erro num grupo de duas linhas**. Os dois casos ficam vermelhos, e o segundo nomeia o preço escolhido. Os quatro casos do arquivo: a invariante do comentário; o valor devolvido não é nenhum preço cru; a quantidade é a soma e não a contagem; e nenhum grupo devolvido é insumo (`pro.tipo != 'proins'`, filtro que ninguém guardava). **439 testes verdes nos dois bancos.** #### Dois dos onze de dinheiro, feitos no mesmo dia — e o que eles acharam `tests/Caracterizacao/TotaisDoCaixaNoRelatorioTest.php` cobre `totalDescontoPorCaixa` e `totalTrocoPorCaixa`, os dois primeiros da lista de dinheiro. Com ele, sobravam 35 dos 37. Cada afirmação compara o método com uma **soma independente em SQL** sobre as mesmas linhas — é isso que prova que o DQL seleciona o conjunto certo, e não uma repetição do mesmo cálculo. **Falsificado:** neutralizando o `WHERE ven.status` do método, três casos ficam vermelhos nomeando `35.0` contra `30.0`, e um deles é o do formato, o que mostra que ele não é redundante. **E a medição achou uma diferença real entre os bancos.** Os dois métodos somam coluna `double precision` e devolvem o resultado cru do DQL: | | MySQL | PostgreSQL | |---|---|---| | `totalDescontoPorCaixa(55927)` | `double` `8084.0` | **`string`** `'8084'` | | `totalTrocoPorCaixa(78458)` | `double` `440.0` | **`string`** `'440'` | | caixa inexistente | `integer` `0` | `integer` `0` | Mesmo caixa, mesmo valor, **tipo de PHP diferente**. É inofensivo **neste caminho**, e isso foi conferido e não suposto: a tela passa os dois por `Monetario::applyMask()` (`is-relatorio/caixas/index.phtml:82-83`), que devolve saída idêntica para os dois tipos em dez pares de entrada, inclusive com centavos — `8084.5` e `'8084.5'` dão `8.084,50`. **Deixaria de ser inofensivo** num consumidor que usasse `removeMask()` ou comparação estrita: `Monetario::removeMask('8084.5')` devolve **`'80845'`**, porque o ponto é separador de milhar no formato brasileiro — a armadilha que o D49 registra. Por isso o último caso do arquivo afirma o **formato** e não o tipo: o tipo pode mudar sem consequência, e é a consequência que interessa. **435 testes verdes nos dois bancos.** #### E a pergunta seguinte era se isso é sistêmico — varrido, e não é Se `SUM()` volta `string` no PostgreSQL e `double` no MySQL, a pergunta que importa não é "quantos métodos", é **quantos consumidores se machucariam com isso**. Varrido em 12/09/2026: | | | |---|---:| | métodos de repositório que agregam `SUM`/`AVG` | **44** | | … em `ISVenda` | 21 | | … em `ISCadastro` | 15 | | … em `ISConfiguracao`, `ISRelatorio`, `ISFinanceiro` | 3, 3, 2 | | **consumidos perto de `Monetario::removeMask()`** | **0** | | consumidos perto de comparação estrita | 5, **todos falso positivo** | Os cinco são chamadas a `listagemIndex`, que é nome genérico — **19** repositórios têm um, e só o do `ClienteRepository` agrega. O `===` que a janela pegou é `$estado === 'ativo'` montando um argumento, e não o resultado da agregação sendo comparado. **Então a diferença de tipo não machuca ninguém hoje**, e isso é medida e não suposição: nenhum dos 44 resultados de agregação passa pela função que transformaria `'8084.5'` em `'80845'`. O que sobra é latência — e o teste dos dois totais do caixa é o primeiro lugar onde ela fica vigiada. #### A VENDA DE DOIS ITENS DESCONTADOS — 05/10/2026, e a raiz da listagem ganha guarda própria A segunda metade do que a nota de 05/10/2026 dava como faltando, e que o cabeçalho do `DescontosNoRelatorioTest` admitia: nenhuma venda do cenário tinha mais de um item descontado, e com um item por venda "enraizado no item" e "enraizado na venda" contam igual. **Medido antes de escrever, e o registro estava meio certo.** Devolvendo a raiz de antes de 26/08/2026 — `FROM Venda ven JOIN ven.produtos pro` com `GROUP BY ven.id ORDER BY ven.dataCriacao DESC`, o código de antes do d4f83a52 —, o arquivo NÃO ficava todo verde: no MySQL caía um caso, `testALitagemRepeteOItemUmaVezPorPagamentoDaVenda` (2 linhas onde esperava 3). Mas esse caso caracteriza um DEFEITO, a linha repetida por pagamento, e quem consertar o defeito muda o caso junto; se o conserto fosse um `GROUP BY ven.id`, a raiz voltaria para a venda e o caso seria "atualizado" sem vermelho nenhum que dissesse o que se perdeu. A guarda da decisão de 26/08 morava, por acaso, no caso de um defeito. (Com o desempate `pro.id DESC` do D47, que veio depois, a raiz na venda nem roda: o paginador recusa ordenar por coluna de associação a-muitos. Por isso o mutante usa a ordem de antes.) **O que entrou:** | | | |---|---| | `tests/Caracterizacao/fixtures.sql` | a venda **90001610**, finalizada, na unidade 90001000, com **dois** itens descontados e motivos diferentes (5,00 e 3,00; 52,00 no total, um pagamento). O bloco diz o que ela evita: o dia 14/02 (os R$ 200,00 que o `ReceitaParaYungasTest` crava), o par colaborador/produto da média de 99,95 do `VendasPorColaboradorNoRelatorioTest`, e um segundo pagamento | | `DescontosNoRelatorioTest::testAListagemTemUmaLinhaPorItemDescontadoENaoPorVenda` | conta no SQL os itens descontados distintos e as vendas deles (4 e 3), exige mais itens que vendas, os 4 itens distintos na listagem e os **dois** motivos da venda de dois | O caso conta itens DISTINTOS de propósito: ele fala da raiz, e não da repetição por pagamento, e continua valendo no dia em que ela for consertada. **Falsificado** com a raiz de antes, um mutante só, restaurado byte a byte: no MySQL o caso novo fica vermelho (3 itens onde há 4), junto com o da repetição (3 linhas onde há 5); no PostgreSQL a consulta nem roda — o `GROUP BY ven.id` com colunas do item fora do agrupamento —, e cinco casos do arquivo caem com erro. A suíte inteira, nos dois bancos, rodou depois da fixture nova (os números estão no roadmap): nenhum outro caso contava as linhas que ela acrescenta. **O que resta, e por isso o título continua PARCIAL:** o par `Visagismo::listagemIndexRelatorio`, adiado pelo dono ("ignorar tudo do onesignal, visagismo e sms"). É o 48º dos 48 pares; os outros 47 têm teste. ### D34 — O inventário de diretórios de upload estava incompleto — PARCIAL em 14/09/2026: o repositório fechou e ganhou vigia, a regra em produção espera o Dia 0 — PREPARADO, lido em 05/10/2026 > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito como parcial, e o corpo diz que ele está pronto no código, à espera só do passo em produção na janela da migração final. Falta: levar ao nginx de produção, no Dia 0, a regra que recusa PHP em public/visagismo, que lá ainda não existe. Descoberto em 19/08/2026, ao migrar os pontos de chamada da F1.5. O levantamento do Dia 0 catalogou seis diretórios de upload, porque partiu dos que apareciam no **D1**. Mas o código escreve em mais lugares, e dois ficaram de fora: | Diretório | O que grava | Estava protegido? | |---|---|---| | `public/visagismo` | **foto enviada pelo cliente** | **NÃO** | | `public/app.json` | configuração do aplicativo | n/a (é arquivo, não diretório) | **O `visagismo` é o grave.** Recebe imagem enviada por cliente através da geração de visagismo por IA, e ficou fora da regra de nginx que impede execução de PHP em diretório de upload — a lista cobria `arquivos`, `contratos`, `banners`, `assistentes`, `vip-class`, `logs` e `layout/img/avatar`. Um `.php` enviado ali seria **executado pelo servidor**. É exatamente o cenário do D12, num diretório que eu mesmo deixei de fora ao escrever a configuração. **Corrigido no `docker/nginx/default.conf`** e provado: `/visagismo/teste.php` devolve 403 sem executar. **Pendente em produção**, como todo o resto do Dia 0 — e agora com um item a mais para conferir na configuração do servidor. **A lição, que vale além deste item:** o inventário partiu de um débito em vez de partir do código. O certo é derivar a lista de `grep -rn "public/" module/`, que é o que a migração acabou fazendo por acidente. *Conferido em 31/08/2026, rodando essa varredura:* o código cita `public/visagismo`, `public/vip-class`, `public/arquivos`, `public/layout`, `public/app.json` e `public/global`. **Nenhum diretório de upload novo apareceu.** Os dois últimos não são diretório de upload e não precisam da regra: `public/app.json` é o arquivo de configuração do **D36**, e `public/global` só é **lido**, para o logo do cabeçalho dos PDFs. *O portão de referências acusou este parágrafo* — a primeira versão escrevia **public/app** (sem crases aqui de propósito: é citação de um erro, não referência a arquivo), recortado de um caminho maior, e nenhum diretório com esse nome existe. O caminho real é `./public/app.json`, em `AplicativoController:76`. Vale como exemplo do que o portão pega: prosa que cita um caminho que não existe. E vale como aviso do que ele **não** pega — ele confere existência, não se a frase ao redor está certa. A verificação confirmou em vez de acusar, e fica registrada para a próxima pessoa não precisar refazê-la. #### O arquivo que PROVOU o conserto entrou versionado — fechado em 14/09/2026 Varrendo os sete diretórios de upload atrás de coisa versionada, apareceu um arquivo só, e era meu: public/visagismo/teste.php guardar($tmp, 'banners/' . $x)`) e a escrita direta que o visagismo ainda usa (`'./public/visagismo/' . $x`), que não foi migrada por decisão registrada no D35. Vigia que conhecesse só uma seria verde sobre a outra. Ele **conta separado o que não conseguiu resolver**: chamada cujo caminho é variável que ele não rastreou sai pelo nome e derruba o portão. Somar não-resolvido com resolvido já mentiu nesta casa, e o remédio está escrito no D186. Medido hoje: **8** diretórios na regra, **2** executáveis permitidos no webroot, **31** escritas do código caindo dentro da lista, **12** citações fora de escopo declaradas (`public/app.json`, que é o D36, e `public/global`, que só é lido), **0** não resolvidas. #### A falsificação, que é o que separa portão de enfeite Cada pergunta foi quebrada de propósito e o arquivo restaurado byte a byte: | O que foi quebrado | Saída | |---|---| | o estado real, antes do conserto | 1 — acusou o `teste.php` **e** o `.gitignore`, em linhas separadas | | um `.php` versionado em `public/logs/` | 1 — nomeou o arquivo | | um `.php` versionado em `public/global/` (fora de upload) | 1 — "o nginx serve, o PHP executa, e nada do ERP passa por ele" | | um permitido da lista deixou de existir | 1 — acusou o permitido órfão **e** o `index.php` que virou intruso | | `/public/visagismo/` fora do `.gitignore` | 1 — "o git não ignora public/visagismo" | | `'./public/visagismo/'` virou `'./public/recibos/'` | 1 — apontou arquivo e linha | | `'assistentes/'` virou `'recibos/'` na abstração | 1 — apontou arquivo, linha e método | | o caminho virou variável não rastreada | 1 — **NÃO RESOLVIDA**, não verde | | a regra do nginx encolheu para 7 diretórios | **2 — recusou medir** | A última é a que eu mais queria ver: piso furado não vira verde nem vermelho, vira recusa. Portão que mede errado é pior que portão que não existe. #### Um efeito que eu não tinha previsto, e quem o achou foi outro portão O `git rm` levou junto o **diretório**. `teste.php` era o único arquivo versionado dentro de `public/visagismo`, e sem ele o diretório some de todo checkout novo — inclusive o do CI. O portão de referências acusou na mesma rodada: três citações na documentação a um caminho que deixara de existir. Não é regressão, e isso foi conferido antes de ser explicado: os **quatro** lugares que gravam ali fazem `mkdir($diretorio, 0775, true)` antes de escrever — três em `module/ISApi/src/Service/VisagismoService.php` e um em `module/ISCadastro/src/Service/VisagismoService.php`. O código nunca dependeu de o diretório vir do git. Ele vinha por acidente, de carona no arquivo que não devia estar lá. Na mesma rodada o portão também acusou uma sujeira **minha**: a falsificação tinha criado `public/logs/` para plantar um executável ali, apagou o arquivo e deixou o diretório vazio para trás. Falsificação que não restaura o terreno inteiro é falsificação pela metade. #### O que continua de pé A regra em produção. O `docker/nginx/default.conf` deste repositório tem `visagismo` desde agosto; o servidor não tem, porque nada foi mexido lá — e isso é o D12, onde o assunto mora. Enquanto for assim, o valor de hoje é que o repositório parou de **carregar** o problema junto. ### D38 — Integrações externas sem credencial na homologação Decisão do responsável em 23/08/2026, ao subir o BVIP: seguir sem as chaves de OneSignal, Zoomtec e SMS por ora. | Integração | O que para de funcionar | Gravidade | |---|---|---| | `onesignal.app` | Push para o aplicativo do cliente | grave | | `onesignal.webpush` | Push no navegador | médio | | `zoomtec.bearer_token` | Visagismo — geração de texto e imagem | médio | | `sms.usuario` / `sms.senha` | Envio de SMS | médio | **Em homologação isso é o comportamento correto, não um problema.** As chaves ficam vazias de propósito para que as integrações **falhem de forma visível** em vez de disparar mensagem de verdade para cliente real. Um cron de marketing rodando por acidente com credencial de produção manda push e SMS para 242 mil pessoas. **O que fica pendente de fato:** quando alguma dessas telas precisar ser validada em homologação, a credencial usada tem que ser **de sandbox do próprio fornecedor**, nunca a de produção. Vale confirmar com cada um se oferecem ambiente de teste — OneSignal oferece aplicativo separado, e para SMS costuma haver conta de teste. Enquanto isso, as telas que dependem delas simplesmente não são exercitáveis ali, e isso precisa constar do plano de validação da Fase 3 para ninguém descobrir na hora. *Atualizado em 11/10/2026 (o item RESPOSTAS-SEM-RODADA):* **o push tem a sua credencial de teste decidida.** Pela pergunta 74 da página do lote (10/10/2026), a opção (a), o servidor de teste fala com os dois endereços do Google, com um projeto Firebase só de teste -- é a credencial "de sandbox do próprio fornecedor" que este débito pede, para o push novo por FCM (o D461, a troca do push pelo Firebase). O servidor de teste está pronto para isso desde o `2dd3ffa` (o R23): um arquivo que abre só o Google, ligado pelo dono com a conta de serviço do projeto de teste, que é dele e fica fora do repositório. **Continuam congelados, pela decisão de 23/08:** o OneSignal (o `onesignal.webpush` inclusive), o Zoomtec do visagismo e o SMS -- sem credencial de teste, e com as telas deles não exercitáveis no teste. Nada mudou no código aqui; o título continua sem marca. ### D40 — O dashboard de colaboradores tem linhas duplicadas e divergentes — PREPARADO em 15/09/2026 Descoberto em 26/08/2026, ao analisar as consultas da F1.4 contra dados reais. A tabela `dashboard_colaboradores` deveria ter **uma linha por colaborador, mês e ano**. Tem mais: | | | |---|---| | Linhas na tabela | 18.364 | | Combinações repetidas | **107** | | Repetidas com valores **divergentes** | **84** | | Maior divergência observada | R$ 1.658 contra R$ 42.251,50 | E não é divisão legítima por unidade. O pior caso, colaborador 200 em abril de 2023, tem as duas linhas com a **mesma unidade** e o mesmo `data_criacao` até o segundo — `2023-04-01 23:01:23`. São duas gravações do mesmo lote, com números diferentes. **A consequência hoje:** `DashboardColaboradorRepository::dadosRelatorio` agrupa por `col.id` projetando a entidade inteira. Quando há duas linhas, o MySQL devolve **uma arbitrária** — e o relatório mostra R$ 1.658 ou R$ 42.251,50 sem que ninguém saiba qual, nem que havia escolha. O mesmo vale para `extratoPlanosCarreira` e `planosCarreiras`. Não é problema criado pela migração. É problema que a migração **encontrou**, porque o PostgreSQL recusa a consulta e obriga a dizer qual linha se quer. As datas afetadas incluem 12/2025, então não é sujeira histórica — a geração ainda duplica. **A mesma corrida aconteceu em `royalties`, e lá deu o contrário: ver o D71.** A origem é idêntica — ler-e-criar-se-não-existe sem restrição de unicidade —, mas a consequência se inverte pela forma como cada relatório lê. Aqui a consulta agrupa e o banco **devolve uma linha arbitrária**, então o número exibido pode estar errado hoje. Lá o relatório **soma**, e como um lado de cada par está zerado, o número está certo — por acidente. Os dois ficam separados porque o conserto e a urgência são diferentes; a remissão é para quem investigar um e precisar do outro. #### ENCERRADO em 27/08/2026 sem causa confirmada, e por que isso basta Investigado até o fim do que a evidência alcança. O resultado: | | | |---|---| | Requisições ao endpoint, na janela retida | **14, de um único IP** — uma por dia | | Registro de 01/12/2025 | **uma execução**, às 23:00:01 | | Entradas no crontab | **uma**, hoje às 23:30 | | **Última duplicata criada** | **16/12/2025** | | Linhas criadas até | 14/08/2026 | **São oito meses sem duplicata nova, com a rotina rodando todo dia.** O problema parou. **Por que a causa não será confirmada:** os logs do servidor web retêm cerca de catorze dias, e as duplicatas são de 2023 e do fim de 2025. A evidência que decidiria já foi rotacionada. O correlato mais plausível é a mudança de horário, de 23:00 para 23:30, que aconteceu em algum momento entre dezembro e agosto — mas isso é correlação, não prova, e vai ficar assim. **Por que encerrar mesmo assim:** 1. O efeito está protegido nos dois lados — as órfãs foram limpas e o schema PostgreSQL tem chave única em `(inquilino_id, colaborador, unidade, mes, ano)`. 2. O problema não se manifesta há oito meses. 3. Continuar investigando consome tempo sem poder chegar a lugar nenhum. **O que fica valendo, e não depende da causa:** a limpeza pré-migração precisa rodar **imediatamente antes do dump**, não semanas antes. Se a causa voltar, ela aparece como violação de chave única no PostgreSQL — alto e claro, em vez de silenciosa. Uma limitação minha, registrada: **a base de desenvolvimento não serve mais para remedir isto**, porque a limpeza foi testada nela e as duplicatas foram apagadas. Os números acima vêm da medição de 26/08, antes do teste. #### O caminho até aqui, e a hipótese que caiu O crontab de produção foi lido, e o registro de 01/12/2025 mostra **uma única execução, às 23:00:01** — batendo com as duplicatas daquele dia, que nasceram entre 23:00:02 e 23:01:05. Há **uma entrada só** no crontab, e o horário mudou depois para 23:30. A hipótese de "duas execuções simultâneas vindas do agendador" cai. **O que o registro não prova:** a linha é escrita pelo `echo` do crontab **antes** do `curl`, então atesta que **este servidor** chamou uma vez — não que o endpoint foi chamado uma vez. Com três réplicas no parque, outra máquina com crontab apontando para a mesma URL produziria exatamente o que se vê. **Fecha com o log do servidor web**, que registra toda requisição: ```bash zgrep -h relatoriosDashboardColaboradoresAtualizar /var/log/nginx/access.log.*.gz | awk '{print $1}' | sort | uniq -c | sort -rn | head ``` Mais de um IP de origem, ou duas requisições no mesmo minuto, confirma. **O que muda na prática: nada do que já foi feito.** A limpeza das órfãs e a chave única no PostgreSQL protegem contra o efeito de qualquer causa. Mas enquanto a causa não for confirmada, **novas duplicatas podem continuar aparecendo no MySQL**, e a limpeza precisa rodar imediatamente antes do dump da migração. O texto abaixo é o raciocínio original, mantido porque a parte mecânica dele continua válida — o que caiu foi a origem das execuções simultâneas, não a explicação de como elas produzem duplicata. #### O raciocínio original, de 26/08/2026 `CronJobService::relatoriosDashboardColaboradoresAtualizar` faz **ler-e-criar-se- não-existe**, sem atomicidade: ```php $dashboard = $repoDashboard->selecionarPorMesAnoColaborador($colaborador->getId(), $mes, $ano); if (empty($dashboard)) { $dashboard = new \ISRelatorio\Entity\DashboardColaborador(); ... ``` Duas execuções simultâneas leem "não existe" e ambas criam. E os dados dizem exatamente isso: | | | |---|---| | Quando as duplicatas nascem | **sempre entre 23:00 e 23:05** — a janela do cron | | Os dois picos | **01/04/2023 (64 linhas) e 01/12/2025 (116)** — dia 1º do mês | | Nos demais dias | pares esparsos, 2 a 6 linhas | O dia 1º concentra porque **nenhum colaborador tem linha do mês novo ainda**: todos entram no ramo "criar" e toda sobreposição vira duplicata. Nos outros dias a linha já existe, o ramo é "atualizar", e só duplica quem ainda não tinha linha. **Por que os valores divergem** — e esta é a parte que explica R$ 1.658 contra R$ 42.251,50: Criada a duplicata, `selecionarPorMesAnoColaborador` usa `setMaxResults(1)` e passa a devolver **sempre a mesma das duas**. Todo dia seguinte do mês atualiza essa, e a outra **congela no valor do dia 1º**: | id | `total_vendas` | `data_alteracao` | |---|---|---| | 9867 | R$ 42.251,50 | 2023-04-30 | | 9868 | R$ 1.658 | **NULL** | No conjunto todo: **109 nunca atualizadas contra 105 atualizadas** — um órfão por par. A linha órfã não é um número concorrente: é o retrato do primeiro dia, esquecido. **Como é disparado, e por que sobrepõe.** São endpoints HTTP em `/api/cronjobs/...`, protegidos por um token fixo no código. O trabalho é longo — cerca de 180 colaboradores, dezenas de consultas cada — e no dia 1º é o mais lento, porque tudo é inserção. Um agendador que expire e repita a chamada produz exatamente este padrão: a primeira execução continua no servidor, a segunda começa, e as duas criam. Ter o cron instalado em mais de uma máquina apontando para o mesmo banco produz o mesmo efeito. #### DECIDIDO em 26/08/2026, e o que ficou feito **1. Unicidade — aprovada e implementada.** A chave é `(inquilino_id, colaborador, unidade, mes, ano)`, emitida por `gerar-ddl-postgres.php`. O `inquilino_id` vem primeiro de propósito: sem ele a unicidade valeria entre inquilinos, e o primeiro cliente a gravar impediria o segundo. É a **primeira restrição de unicidade do schema** — até aqui não havia nenhuma, que é o D29 por extenso. **A carga no PostgreSQL passa a FALHAR se ainda houver duplicatas.** É de propósito: falhar é melhor que migrar o problema. **2. Limpeza — aprovada e implementada**, em `pre-migracao-limpeza.sql`. A regra decidida pelo responsável: > Fica a linha que vinha sendo atualizada. A sobrevivente **herda a `data_criacao` > mais antiga** do grupo, para o registro guardar quando aquele mês começou a ser > medido, e não quando a duplicata nasceu. Quando nenhuma das duas foi atualizada > — não há dado que distinga —, fica a de menor id, que é a que a aplicação já lia. Provado contra a base real: 107 grupos, 107 linhas removidas, 18.364 para 18.257, a linha viva de cada par preservada, e idempotente na segunda execução. Dos 107 grupos, 2 tinham as duas linhas **idênticas** — mesmos valores, mesma data — então o caso de *fallback* é inócuo por construção. **3. A consulta.** Com as órfãs fora, `GROUP BY das.id` resolve as três consultas do Dashboard sem escolha de negócio nenhuma. Sai da lista de decisões da F1.4. #### RESOLVIDO em 30/08/2026, e por um caminho melhor que o previsto **A rotina passou a usar a trava** que o próprio arquivo oferece vinte linhas abaixo — `acquireLock('relatoriosDashboardColaboradores')`, liberada em `finally`. Duas execuções deixam de se sobrepor, e a corrida some na origem. **O caminho que este débito previa era pior.** Eu havia escrito que a geração precisaria *tolerar* a violação de unicidade: capturar, reler a linha do outro processo e seguir. Isso esbarra num detalhe do Doctrine que só aparece ao tentar — **um `flush()` que falha fecha o EntityManager** —, então "capturar e reler" não é uma linha: exige recriar o gerenciador no meio de um laço sobre a base inteira. Evitar a corrida é mais simples, e mais seguro, do que sobreviver a ela. **E o teste não precisava de dois processos**, ao contrário do que este débito afirmava. A concorrência é como a situação *aparece*; o que se verifica é o comportamento **sob contenção** — e esse se produz segurando a trava e chamando a rotina, porque um `flock` já detido responde igual venha de outro processo ou do próprio teste. Está em `tests/Caracterizacao/CronTravaSimultaneaTest.php`. **A primeira versão desse teste não acusava**, e vale registrar por quê: ela contava linhas da tabela. A rotina **atualiza** as linhas do mês corrente em vez de inserir, então o total não muda quando ela roda — a asserção era verdadeira nos dois mundos e provava nada. Passou a observar `data_alteracao`, que é o que distingue "rodou" de "desistiu". Conferido: com a trava desligada, o teste falha. **Um número que apareceu ao verificar:** a rotina completa leva **21 minutos** na base local. Rodando diariamente às 23h30, qualquer segundo disparo dentro dessa janela colidia — o que explica por que a corrida acontecia de verdade, e não só em teoria. **O que continua valendo:** a trava é de arquivo e não protege entre máquinas (D44), e a limpeza `scripts/pre-migracao-limpeza.sql` ainda precisa rodar imediatamente antes do dump — produção acumulou duplicatas e a cópia local só está limpa porque a limpeza já rodou nela. **O que este parágrafo dizia até 15/09/2026, e não diz mais.** Ele afirmava que "a corrida continua acontecendo no MySQL" e que "novas duplicatas aparecem todo dia 1º". Era texto ANTERIOR à trava de 30/08/2026, e ficou posicionado depois da seção RESOLVIDO como se descrevesse o estado de hoje — contradizendo a medição da própria entrada, três telas acima: última duplicata criada em 16/12/2025, oito meses sem duplicata nova com a rotina rodando todo dia. O que resta verdadeiro: produção pode ter acumulado duplicatas ATÉ 30/08/2026, e por isso `scripts/pre-migracao-limpeza.sql` roda imediatamente antes do dump. **Vale conferir quantos agendadores chamam `/api/cronjobs/...` e com que tempo limite.** É a única peça que os dados não contam, e reduzir para um único disparador elimina a causa sem esperar pelo resto. É o **D29** — nenhuma restrição de unicidade em todo o banco — cobrando a conta. Uma chave única em `(colaborador, unidade, mes, ano)` teria impedido a segunda gravação em 2023. #### A chave única que encerrou este débito não tinha portão nenhum — 15/09/2026 Este débito foi dado por encerrado porque *"o efeito está protegido nos dois lados"*: a trava de um lado, a chave única do outro. Os dois existem mesmo — a trava em `CronJobService.php:711`, a chave em `postgres/schema.sql:1755` e no PostgreSQL vivo. **E nada guardava a chave.** Varri `scripts/`, `tests/` e o `ci.yml` atrás de qualquer asserção sobre unicidade. As únicas ocorrências de `UNIQUE` falam do problema **oposto** — o `schema-tool` propondo índice indevido, que era o D17. O `verificar-schema-postgres.php` compara tabela, coluna e **tipo** contra o banco vivo, e não olha restrição. O `conferir-unicidade.php` mede **dados**, não DDL. **A contraprova, medida e não suposta.** Comentei a linha 562 de `gerar-ddl-postgres.php` — a que declara a unicidade do D40 — e rodei o conjunto inteiro **sem** o portão novo: ``` CONTRAPROVA: os 38 anteriores, com a chave do D40 ARRANCADA -> EXIT 0 1 vermelho(s) conhecido(s), com motivo escrito acima. Nenhuma falha inesperada. ``` Trinta e oito portões verdes com a proteção arrancada. É o vão, em uma linha. #### O portão: `scripts/conferir-unicidade-do-schema.php` São **quatro** restrições de unicidade no schema PostgreSQL, de **duas origens** — e essa distinção é o que torna o portão necessário: | tabela | colunas | forma | origem | débito | |---|---|---|---|---| | `clientes_sessoes` | `(token_hash)` | índice | traduzida do `mysql.sql` | F1.5 | | `dashboard_colaboradores` | `(inquilino_id, colaborador, unidade, mes, ano)` | restrição | `$unicidades` do gerador | **D40** | | `privilegios` | `(inquilino_id, grupo, funcionalidade)` | restrição | `$unicidades` do gerador | D24 | | `royalties` | `(inquilino_id, unidade, data)` | restrição | `$unicidades` do gerador | D71 | A primeira vem traduzida do MySQL — e é a **única** `UNIQUE KEY` de todo o esquema herdado, que é a medida exata do D29. As outras três nós é que acrescentamos, e **não existem em banco nenhum hoje**: só passam a valer no dia do corte. Por isso apagá-las era barato e invisível — nenhum banco de hoje reclamaria. **A ordem das colunas faz parte da declaração.** Em tabela com escopo a chave começa por `inquilino_id`; sem isso a unicidade valeria *entre* inquilinos, e o primeiro cliente a gravar impediria o segundo. Uma chave com `inquilino_id` no meio guarda outra coisa, e o portão recusa a troca de ordem pelo mesmo motivo que recusa a ausência. Ele confere as **duas** fontes: a saída do gerador e o `postgres/schema.sql` comitado — porque o arquivo é *saída* do gerador e pode ficar para trás dele. #### A falsificação: quatro mutações | | o que mudou | esperado | obtido | |---|---|---|---| | U1 | a linha do D40 comentada no gerador | vermelho | 1, nomeando a tabela e o débito | | U1b | **os 38 portões anteriores, no mesmo estado** | **verdes** | **exit 0 — o vão** | | U2 | só a ORDEM: `…unidade, ano, mes` | vermelho | 1, *"declarado (…mes, ano), achado (…ano, mes)"* | | U3 | a linha apagada só do `schema.sql` | vermelho | 1, *"ficou para trás do gerador"* | | U4 | piso acima do medido | 2 | 2, *"devolveu 2393 linhas, o piso é 9000"* | **A U2 é a que separa um portão que guarda de um que parece guardar.** Um que aceitasse a troca de ordem estaria verde sobre uma chave que não protege o que o D40 decidiu proteger. #### Três consertos nesta própria entrada 1. **Um cabeçalho órfão** — `#### O que ainda falta, e por que não foi feito agora`, seguido de linha em branco e do cabeçalho seguinte. Sem corpo nenhum. Saiu. 2. **Um parágrafo que se contradizia com a própria entrada.** Ele afirmava, já *depois* da seção RESOLVIDO, que *"a corrida continua acontecendo no MySQL… Novas duplicatas aparecem todo dia 1º"* — enquanto três telas acima a mesma entrada mede *"oito meses sem duplicata nova, com a rotina rodando todo dia"* e *"última duplicata criada: 16/12/2025"*. Era texto anterior à trava de 30/08/2026, posicionado como se fosse o estado de hoje. Reescrito para o que resta verdadeiro. 3. **O título não tinha marca**, e por isso `contar-debitos.php` contava o D40 entre os 41 *"aberto — sem marca nenhuma no título"*, enquanto o corpo dizia ENCERRADO e RESOLVIDO. É o D179 de novo, com um agravante: lá a régua não conhecia o verbo; aqui não havia verbo. Passou a **PREPARADO**, e a escolha não é de gosto: o glossário de `contar-debitos.php` define preparado como *"o conserto está pronto e desligado, esperando a janela do corte"* — que é exatamente o estado da chave única, que existe no schema PostgreSQL e só passa a valer no corte. #### O que este portão NÃO prova Nada sobre os **dados**, nem aqui nem em produção. Ele lê DDL. Quem mede duplicata é o `conferir-unicidade.php` — e aquele, apontado para a cópia local, é **verde por limpeza**: a cópia só está limpa porque `pre-migracao-limpeza.sql` já rodou nela. Responder se produção acumulou duplicatas depois de 30/08/2026 exige apontá-lo para a réplica, e é acesso que este repositório não tem. --- ### D43 — `yungasNpsAtualizar` estava desligada — REMOVIDA em 31/08/2026 **Reescrito em 28/08/2026.** O registro anterior dizia que a rotina existe, é alcançável e ninguém a agenda — e concluía que faltava agendá-la. Faltava olhar dentro dela primeiro. **O corpo do método tem 27 linhas, e as 27 estão comentadas.** Ela não faz nada. Agendá-la seria pior que não agendar: produziria um `sucesso: true` a cada execução, fecharia este débito na aparência, e não sincronizaria um único NPS. É a mesma família do relatório que erra para menos — o que não existe manda perguntar; o que finge responder, não. **A integração Yungas está viva.** `yungasFaturamentoAtualizar` tem 49 linhas ativas e roda às 23:40; `yungasAutenticacao` funciona. Foi só a metade do NPS que alguém desligou, comentando o corpo e deixando a rota para trás. O código que a desligou não está no repositório: o histórico começa na importação inicial, então não há o que datar nem por que. **A decisão é de negócio, não de engenharia:** | Se | Então | |---|---| | a Yungas ainda espera receber o NPS | descomentar, testar contra a API deles, e só então agendar | | não espera mais | remover o método, a ação do controller e a rota | Hoje é superfície sem função: uma rota que responde sucesso e não faz nada. Nenhuma das duas saídas é cara; o que custa é continuar sem escolher. *Correção de 30/08/2026:* este parágrafo dizia "rota **pública**". Não é — ela confere o token do cron como as outras 26. O que a faz responder sucesso a qualquer chamador é outra coisa, e vale para 27 das 30 ações: o `sucesso: true` sai mesmo quando o token não confere (**D4**, item 3). A rota não está aberta; a resposta é que não distingue. #### A DECISÃO, tomada em 31/08/2026: removida **Por decisão sua, a Yungas não espera mais o NPS.** Saíram o método `CronJobService::yungasNpsAtualizar` (29 linhas, das quais 27 comentadas), a ação `CronJobController::yungasNpsAtualizarAction`, a rota `/api/cronjobs/yungasNpsAtualizar` e a entrada correspondente no `ApiDocsController`. **Uma conferência valeu a pena antes de apagar.** O inventário classificava esta ação como **CONTRATO-APP** — *"versões antigas em campo; os 28 testes seguram"* —, o que teria sido motivo para não tocar nela. Não era evidência: esse veredito é atribuído em bloco a **toda** ação do módulo `ISApi`, e a suíte de contrato não cobre rota de cron nenhuma. Conferido antes, não depois. **Se um dia a Yungas voltar a querer NPS**, reconstruir é barato: `yungasAutenticacao` e `yungasFaturamentoAtualizar` continuam de pé e servem de molde — inclusive já com o tempo limite que o **D67** lhes deu. **O que os portões passaram a dizer:** | Portão | Antes | Agora | |---|---|---| | `conferir-agendamento.php` | 2 rotinas sem agendamento | **1** — só o D50, que espera produção | | `conferir-rastro-das-rotinas.php` | 12 rotinas mudas de 27 | **11 de 26** | E `conferir-rastro-das-rotinas.php` fez o que foi desenhado para fazer, desta vez de verdade e não numa prova fabricada: acusou que `yungasNpsAtualizarAction` estava na lista conhecida e não existia mais. **Lista desatualizada esconde a próxima** — foi para isso que aquele ramo existe. --- ### D48 — A aplicação conecta como superusuário, e isso desliga o RLS inteiro — PREPARADO, lido em 05/10/2026 > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito sem marca de estado, e o corpo diz que ele está pronto no código, à espera só do passo em produção na janela da migração final. Falta: rodar `scripts/criar-papeis.sh` no corte, depois do schema e antes da carga, e apontar o `local.php` de produção para `bvip_app`. Descoberto em 27/08/2026, ao começar a F1.9. A F1.3 escreveu **75 políticas de isolamento por inquilino**, com `ENABLE` e `FORCE ROW LEVEL SECURITY`. A F1.8 carregou 16 milhões de linhas e provou que o comportamento financeiro não mudou. Nada disso valia o que parecia valer: **quem conecta é `franquiabv`, que é superusuário — e superusuário está acima de qualquer política.** Medido, sessão nova, sem declarar inquilino: | Quem consulta | Resultado | |---|---| | `franquiabv` (superusuário) | **61 unidades** — o RLS nem é avaliado | | papel comum | `ERROR: unrecognized configuration parameter "app.inquilino_id"` | `FORCE` faz a política valer para o **dono da tabela**, que sem ele escaparia. Não faz — nem poderia — valer para superusuário. **Já está resolvido no ambiente**, e provado: `postgres/papeis.sql.modelo` cria `bvip_app` (comum, lê e escreve), e os 67 testes de caracterização passam com a aplicação conectando como `bvip_app`, com o RLS em vigor. (Havia um segundo papel, `bvip_bi`, somente leitura, para o Power BI; saiu em 09/09/2026 com ele — ver **D9**.) `scripts/conferir-papeis.sh` prova as propriedades tentando violá-las. **O que continua em aberto é produção.** Lá a aplicação segue com a credencial de dono, e a troca precisa entrar no procedimento de corte — não depois, porque carregar dados de um segundo inquilino com o isolamento desligado é o cenário em que o vazamento não deixa rastro. **Por que isso é pior que parece:** o sintoma de RLS desligado é *nenhum sintoma*. Tudo funciona, todas as telas respondem, todos os testes passam. A falha só aparece quando existe um segundo inquilino — e aí ela aparece como dado de um cliente na tela de outro. **Ao resolver:** rodar `scripts/criar-papeis.sh` no corte, **depois** do schema (um `DROP SCHEMA ... CASCADE` leva as permissões junto) e antes da carga, e apontar o `local.php` de produção para `bvip_app`. --- ### D49 — Todo o dinheiro do sistema está em ponto flutuante Descoberto em 27/08/2026, ao revisar a conferência da migração. > **O D30 é este mesmo defeito**, registrado dez dias antes e mais magro. Foi > reduzido a remissão em 30/08/2026. Os dois já tinham divergido na escala > recomendada — `numeric(12,2)` lá, `numeric(14,2)` aqui —, e 14 é a certa. As **85 colunas numéricas** do sistema são `double` no MySQL e `double precision` no PostgreSQL. **Nenhuma é `decimal`.** Isso inclui `vendas.valor_total`, `vendas.valor_recebido`, `vendas.desconto_total`, `vendas_produtos.comissao`, `vendas_produtos.valor_unitario`, `royalties_faturas.valor` e `saidas_parcelas.valor_pago`. `double` é binário: 0,10 e 0,01 **não têm representação exata**. O erro é minúsculo por linha e se acumula por soma. Num relatório que soma 2,2 milhões de vendas, a precisão absoluta do tipo já está na casa da unidade — ou seja, **alguns reais**, não centavos. **Isto é anterior à migração e não foi introduzido por ela.** A conversão é fiel: `double` de um lado, `double precision` do outro, e a conferência prova que os valores atravessaram idênticos. O defeito é do modelo de dados, e tem a idade do sistema. **Onde já apareceu:** as somas dos dois bancos divergiam na 16ª casa decimal (`155232205,08550483` contra `155232205,08552286`) porque somar doubles depende da ORDEM da soma, e as duas engines não somam na mesma ordem. Não é divergência de dado — é o tipo fazendo o que o tipo faz. **Consequência prática que já mordeu:** a primeira versão de `scripts/conferir-migracao.php` comparava as somas em ponto flutuante com tolerância de meio centavo, e eu havia escrito que "a diferença aceita é zero, porque as somas vêm de tipos decimais exatos". Não vêm. Numa soma de 155 milhões, meio centavo está **abaixo do que o tipo distingue**: a prova passava por sorte, e uma divergência real de alguns centavos passaria junto. Corrigido — a soma agora é feita em decimal exato dos dois lados e comparada como texto. **Ao resolver:** migrar as colunas de valor para `numeric(14,2)` (ou a escala que cada uma pedir). No PostgreSQL isso é um `ALTER TABLE ... TYPE numeric USING round(col::numeric, 2)`, que reescreve a tabela — em `vendas_produtos` são 3,78 milhões de linhas, então é trabalho de janela. **Não faça isso junto com o corte.** O corte tem como portão "o comportamento financeiro não mudou"; trocar o tipo do dinheiro no mesmo movimento torna esse portão impossível de ler, porque os dois efeitos ficam misturados. Depois do corte, com os 67 testes de caracterização servindo de rede, é uma mudança mensurável. --- ### D50 — A rotina que sinaliza contratos a renovar não é agendada, e o filtro devolve sempre vazio — PREPARADO, lido em 05/10/2026 — PARCIAL em 07/10/2026: a regra está escrita junto do campo; faltam a linha do crontab em produção e o nome novo > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito sem marca de estado, e o corpo diz que ele está pronto no código, à espera só do passo em produção na janela da migração final. Falta: aplicar em produção a linha do crontab (01:30), pronta em `crontab-a-aplicar.md`; renomear o campo e documentar a regra seguem como recomendação. Descoberto em 28/08/2026, lendo as exceções do inventário de ações. **Reescrito no mesmo dia**, depois de a regra de negócio ser informada — a primeira versão deste registro tirava a conclusão errada, e o erro vale ser mostrado porque é o erro que a Fase 3 corre o risco de repetir. **A regra, dita por quem decide:** o convênio tem data de vencimento de contrato, mas **a vigência segue até que alguma parte cancele**. A data é referência comercial, não corte automático. **Então o sistema está certo.** `VendaProdutoService` concede o desconto olhando `status`, tipo do produto e unidade/dia da semana — e **não** olha `contratoVencido`. Isso não é uma verificação faltando: é a regra implementada. Os R$ 649,50 concedidos nos últimos 12 meses por convênios com data ultrapassada são desconto legítimo, sob contratos em vigor. **O defeito é um só, e é de acompanhamento comercial.** A rotina `ConveniosController::atualizarVencimento` marca quais contratos passaram da data. Ninguém a agenda — não está nas 25 entradas do crontab, nada no sistema a referencia. Resultado: | | | |---|---:| | Convênios ativos | 616 | | Com data de contrato ultrapassada | **18** | | Marcados pela rotina | **0** | | O mais antigo, ultrapassado há | **1.933 dias** | O único consumidor do sinalizador é o **filtro da listagem de convênios**. Como nada nunca marca ninguém, filtrar por "contrato vencido" devolve **lista vazia** — e quem procura contratos a renovar conclui que está tudo em dia, quando há 18 para revisitar, um deles de mais de cinco anos atrás. Relatório que erra para menos é pior que relatório que não existe: o que não existe manda perguntar; o que mente responde. ## O risco vai na direção contrária da intuição Este é o ponto que importa para as Fases 2 e 3. Olhando o código, `contratoVencido` parece um controle de validade que alguém esqueceu de ligar. **Um desenvolvedor bem-intencionado, reconstruindo a tela, tende a "consertar" isso** — ligando o sinalizador ao desconto, achando que corrige um esquecimento. Isso **quebraria a regra do negócio**: cancelaria na hora o desconto de 18 convênios em vigor, e de todos os que passassem da data dali em diante. Sem ninguém decidir, e com aparência de correção de bug. **O nome é a armadilha.** `contrato_vencido` lê-se como validade; o que ele significa é "passou da data de referência, vale revisitar". ## Situação: a rotina existe e está pronta para agendar (28/08/2026) **Ela deixou de ser ação de admin.** Era `ConveniosController::atualizarVencimento` — sem view, terminando em `die("FIM")`, alcançável por URL só porque o módulo tem rota curinga. Virou `/api/cronjobs/conveniosAtualizarVencimento`, com a mesma forma das outras 25: verificação de token, log ao final, e entrada na documentação da API. A ação de admin foi removida, e com ela uma escrita alcançável pelo curinga sem motivo. **E um defeito foi corrigido no caminho.** A rotina lia `selecionarConvenios()`, que devolve **só os ainda não marcados**. O ramo que desmarca em `ConvenioService::atualizarVencimento()` era, por isso, código morto: renove um contrato, estenda a data, e ele fica na lista de "a renovar" para sempre. **Uma lista que só cresce deixa de ser lista.** Agora processa todos os ativos. Quatro testes de caracterização cobrem os dois sentidos — marca quem passou da data, **desmarca quem foi renovado** —, e o de desmarcar foi verificado voltando à consulta antiga: ele falha. Um quinto guarda a regra de negócio: marcar não mexe no `status`, que é o que o desconto lê. **Falta aplicar a linha no crontab**, e produção está congelada. A linha está pronta em `crontab-a-aplicar.md`, com o horário escolhido (01:30) e o porquê. **Aviso para quando entrar no ar:** os 18 convênios com data ultrapassada aparecem de uma vez na primeira execução. É o esperado, não defeito — vale avisar quem cuida dos contratos, para o salto não ser lido como erro. **O que continua valendo:** 1. **Aplicar a linha do crontab.** É o único passo que falta, e é em produção. 2. **Renomear na API e no schema novo** para algo que diga o que é: `contrato_a_renovar`, `contrato_data_ultrapassada`. Nome que descreve o estado não convida a ser ligado ao preço. 3. **Documentar a regra junto do campo**, para que a próxima pessoa não precise perguntar: a vigência segue até cancelamento por uma das partes. Ver `inventario-acoes-excecoes.md`. **Ele está sozinho.** O levantamento em `campos-regra-ou-referencia.md` varreu os 80 campos do sistema cuja forma sugere controle — todo booleano, mais prazos e limites — e `contrato_vencido` é **o único** com forma de regra e função de referência. Dos 10 que aparecem em `WHERE`, os outros nove são filtrados por métodos que decidem; só este é filtrado apenas por um relatório e pela própria rotina que o alimenta. Não há uma safra de armadilhas esperando a reconstrução. #### O item 3 feito, em 07/10/2026 (o item CODIGO-MORTO-E-DOCS) **A regra está escrita junto do campo**, no docblock de `Convenio::$contratoVencido` (`module/ISConfiguracao/src/Entity/Convenio.php`): a vigência segue até uma das partes cancelar, a data é referência comercial, quem marca e desmarca é `ConvenioService::marcarVencimento` (no cadastro, na alteração e na rotina do cron), quem lê, e o aviso -- não ligar o campo ao desconto, que a venda concede pelo `status` e pelo vínculo com a unidade. Só comentário: nenhum comportamento muda, e não há o que testar. O arquivo é CRLF desde a importação, e as linhas novas também (o `.gitattributes` pede não renormalizar `*.php`). **Os leitores, completados na verificação do mesmo dia:** a primeira versão do docblock dava só "o filtro da lista e a API". São também o selo "Vencido" da lista antiga (`is-configuracao/convenios/index.phtml`) e o da tela nova, pela API; e `ConvenioRepository::selecionarConvenios()`, que a rotina deixou de ler em 01/09 (acima) e ficou **sem chamador** -- e que devolve os ativos **não** marcados, justamente a forma que o aviso proíbe. Quem procurar ali "os convênios ativos" para a venda cai nela. O docblock agora o nomeia; apagá-lo é o mesmo gesto do código morto do D73, e não foi feito aqui. **Fica de pé:** o item 1, a linha do crontab em produção (pronta em `crontab-a-aplicar.md`, para a janela do corte), e o item 2, o nome novo na API e no esquema novo, que segue recomendação. --- ### D51 — `vendas.comanda_temp` é fóssil, e está dentro do maior índice da tabela Descoberto em 28/08/2026, ao procurar o correlato de `comanda_temp` no schema. **Não existe `vendas.comanda`.** A comanda é uma venda, e o estado dela está codificado em `vendas.status`: `NULL` é venda temporária, `3` é comanda aberta, `1` concluída, `0` cancelada. A substituição está escrita no código, com comentário: `$venda->setStatus(null); //null = venda temp`. `comanda_temp` foi a marcação anterior, e **o que ela marcava tem nome na operação**: a *comanda fantasma*. > Uma comanda temporária é a que foi aberta — o cliente esteve na unidade — e não > foi fechada, por falta de pagamento. O caso comum é o caixa abrir uma comanda > nova e finalizar essa, deixando a primeira órfã. Os motivos de cancelamento gravados à mão confirmam: além dos 11.718 automáticos, há **243 "duplicado"** e **159 "abriu duas vezes"**. O sinalizador durou **21 meses** — de 2018-06-06 a 2020-03-21 — e nesse período marcava quase toda comanda cancelada (98,8% em 2018). Depois parou. A rotina `comandasCancelar`, que é de 2017, seguiu rodando sem ele até hoje: 2.021 cancelamentos em 2026. Hoje **nada lê e nada escreve** o campo, exceto o construtor da entidade, que grava `false` em toda venda nova. **O custo é um índice de 91 MB** — o maior de `vendas`, maior que a chave primária (49 MB): ``` vendas_idx_vendas_data_status (inquilino_id, data_criacao, status, comanda_temp) ``` A quarta coluna é o fóssil, e nenhuma consulta do sistema cita `comandaTemp`. O índice serve pelas três primeiras; a última é peso morto em 2,2 milhões de linhas e em cada escrita nova. **Ao resolver — depois do corte, nunca durante.** O portão do corte é "o comportamento não mudou", e mexer no schema no mesmo movimento torna esse portão ilegível. 1. Confirmar com quem sabe o que a "comanda temporária" de 2018–2020 significava. Cinco anos de silêncio é forte indício, não prova — e o código que a escrevia não está no repositório. 2. `DROP COLUMN comanda_temp` e recriar o índice com três colunas. **Ao lado:** a entidade declara `nullable=true` e o MySQL diz `NOT NULL`. A divergência nunca apareceu porque o construtor sempre grava `false`. O gerador de DDL seguiu o MySQL, então o PostgreSQL ficou fiel à origem — mas a anotação continua mentindo, e é ela que o Doctrine usa. --- ### D52 — O cancelamento automático não distinguia fantasma de abandonada, e a lente que mediria a separação estava cega por charset — CORRIGIDO em 14/09/2026 Descoberto em 28/08/2026, ao entender o que `comanda_temp` marcava. **A operação distingue dois casos; o sistema, não.** > Uma comanda temporária é a que foi aberta — o cliente esteve na unidade — e não > foi fechada, por falta de pagamento. O caso comum é o caixa abrir uma comanda > nova e finalizar essa, deixando a primeira órfã. A rotina `comandasCancelar` cancela toda comanda aberta há mais de dois dias e grava **a mesma frase em todas**: *"Comanda aberta a mais de dois dias (cancelamento automático)"*. Fantasma e abandonada recebem o mesmo tratamento e ficam indistinguíveis depois. **Medido, de 01/01/2025 até 16/08/2026 — só as que tinham item lançado:** | | Comandas | Valor na comanda | |---|---:|---:| | Venda fechada no **mesmo dia** — a fantasma clássica | 2.662 | R$ 302.598 | | Venda em até 3 dias — registrada depois | 382 | R$ 35.037 | | **Nenhuma venda por perto** | **2.017** | **R$ 176.126** | As 2.662 do primeiro grupo são ruído operacional: o serviço foi cobrado na outra comanda. **As 2.017 do último não são** — cerca de **1.200 por ano**, com serviço selecionado e sem nenhuma venda daquele cliente em três dias. **O que o número é e o que não é.** `valor_total` numa comanda aberta acompanha a soma dos itens — foi verificado. Então R$ 176 mil é o valor que estava na comanda quando ela foi abandonada. **Não é prova de receita perdida**: item selecionado não é serviço prestado, e a comanda pode ter sido aberta por engano com item já escolhido. É o teto do que estava em aberto, e o piso de quanto vale investigar. **O mecanismo da fantasma continua no código.** `VendaService::comandaAbrir()` procura comanda existente **pelo usuário** e só com `status IS NULL`; uma comanda já aberta para aquele cliente, com `status = 3`, não é encontrada — e uma segunda é criada. É exatamente o caso descrito pela operação, e ele não foi fechado. ## Situacao: as duas primeiras acoes estao implementadas (28/08/2026) **1. O cancelamento diz qual dos dois casos e.** `CronJobService::comandasCancelar()` pergunta, para cada comanda, se o cliente teve venda finalizada no mesmo dia, e grava uma de duas frases -- `COMANDA_DUPLICADA` ou `COMANDA_ABANDONADA`, constantes da classe porque relatorio vai procura-las. O log passou a trazer as duas contagens separadas. **2. A segunda abertura deixou de criar comanda nova.** `VendaService::comandaAbrir()` e `comandaAbrirAgenda()` consultam `selecionarComandaCliente()` -- que ja existia e ja era usada pela agenda e pela listagem de clientes -- antes de criar. Se o cliente ja tem comanda aberta **na mesma unidade**, ela e devolvida, e a tela avisa: *"Este cliente ja tinha uma comanda aberta nesta unidade."* O escopo e por cliente E unidade, nao so por cliente: comanda nao tem unidade propria, ela vem do usuario que a abriu, e um cliente atendido em duas unidades no mesmo dia tem direito a duas comandas. **Seis testes de caracterizacao** cobrem as duas mudancas (`tests/Caracterizacao/ComandaFantasmaTest.php`), e foram verificados DESLIGANDO cada guarda de proposito: com a guarda da comanda desligada, o teste de reaproveitamento falha; com a classificacao desligada, o da frase falha. Passam nos dois bancos -- 73 testes, 136 assercoes. **3. A terceira acao e uma decisao sua, e agora ela tem numeros.** `scripts/medir-comandas-abandonadas.sql` reclassifica o historico pela mesma pergunta que a rotina passou a fazer, e mostra por ano e por unidade: | Ano | Abandonadas | Duplicadas | Valor abandonado | |---|---:|---:|---:| | 2023 | 1.165 | 1.446 | R$ 84.897 | | 2024 | 1.619 | 1.674 | R$ 130.875 | | 2025 | 1.542 | 1.720 | R$ 130.423 | | 2026 (ate 16/08) | 857 | 942 | R$ 80.740 | E a concentracao por unidade nao e aleatoria -- nos ultimos 12 meses, Itapema Meia Praia tem 144 comandas abandonadas contra 41 de Itajai Centro. Isso e sinal de processo, nao de acaso, e e o tipo de coisa que so aparece quando o numero existe. ## DECIDIDO em 31/08/2026: o historico fica, e o roteiro e a lente **Por decisao sua, nada e reescrito.** Os registros historicos mantem a frase unica com que foram cancelados, e quem precisar da separacao roda `scripts/medir-comandas-abandonadas.sql`, que classifica **na leitura** pela mesma pergunta que a rotina passou a fazer. **Por que isso e melhor que regravar**, e nao so mais barato: a classificacao continua auditavel. Da para ver a regra que produziu cada numero, e se a regra mudar, o numero muda junto. Um `UPDATE` no historico congelaria a versao de hoje da regra em dez mil linhas, sem deixar rastro de qual versao foi. **O preco, e ele e real:** quem quiser o corte precisa saber que o roteiro existe. Por isso ele fica citado aqui e no roadmap -- e por isso esta frase existe, em vez de a decisao ficar so no historico do git. **O que continua sem dono, e isto e operacao, nao codigo:** a concentracao por unidade. Itapema Meia Praia com 144 comandas abandonadas contra 41 de Itajai Centro nos ultimos 12 meses e sinal de processo. O numero existe agora; olhar para ele todo mes seria uma tela, e tela e materia da Fase 2. **O que este debito NAO decide:** cobrar ou nao as ~1.500 por ano. Isso nunca foi pergunta de engenharia, e o valor de R$ 130 mil ao ano e teto do que estava em aberto, nao receita perdida -- item selecionado nao e servico prestado. --- #### A lente que a decisão de 31/08 nomeou estava cega — corrigida em 14/09/2026 A decisão registrada acima diz: *o histórico fica, e quem precisar da separação roda `scripts/medir-comandas-abandonadas.sql`*. Esse roteiro tem três blocos. O terceiro — o único que responde **"a classificação nova subiu?"** — vinha **vazio**, e o comentário ao lado dizia que vazio era o esperado: *"quando parar de vir vazio, a classificação está no ar"*. O único indicador que diria "subiu" estava preso em "não subiu", e o comentário ensinava o leitor a não desconfiar. **A causa é de charset, não de dado.** O bloco filtrava com `IN` sobre dois literais **acentuados**, e o cliente `mysql` deste contêiner negocia `character_set_client = latin1` — medido em 14/09/2026. Rodado exatamente como o cabeçalho do próprio arquivo mandava, os bytes UTF-8 são remendados na entrada e a comparação casa zero linhas. Sem erro e sem aviso. Os blocos 1 e 2 nunca sofreram disso porque filtram com `LIKE 'Comanda%cancelamento autom%'` — ASCII puro, o acento fica depois do `%`. **As quatro combinações, medidas uma a uma na cópia local:** | Predicado | Invocação | Bloco 3 devolve | |---|---|---| | `IN` acentuado | como o arquivo documentava | **vazio** | | `IN` acentuado | com `--default-character-set=utf8mb4` | 43 | | `LIKE` ASCII | como o arquivo documentava | 43 | | `LIKE` ASCII | com a opção | 43 | A linha que importa é a terceira: **o predicado ASCII acerta independentemente de quem invoca**, e a opção de charset só acerta quando alguém lembra dela. As duas entraram — a opção no cabeçalho, com o porquê escrito ao lado —, mas é o predicado que faz o roteiro parar de depender de memória. As 43 são **22 abandonadas + 21 duplicadas**, todas de 08/09/2026, de alguém rodar a rotina contra a cópia local. **Produção não tem nenhuma**: lá seguem 32.640 linhas com a frase única antiga, a última de 15/08/2026 — o servidor continua rodando o código velho, como manda a decisão de 11/09. #### E o portão cobria metade da correção O D52 diz ter corrigido a abertura de comanda duplicada. Corrigiu — nos **dois** caminhos que abrem comanda. Mas só **um** deles tinha teste. | O que foi arrancado | Quem acusava antes | Quem acusa agora | |---|---|---| | a guarda de `comandaAbrirAgenda()` | **ninguém** | 1 falha, e só no caso novo da agenda | | `AND uni.id = :unidade` de `selecionarComandaCliente()` | **ninguém** | 1 falha, e só no caso novo da unidade | Medido em 14/09/2026, arrancando uma de cada vez e restaurando os bytes: em cada rodada este arquivo fica com **uma** falha, e os outros sete casos continuam verdes — que é o que separa buraco real de redundância. `comandaAbrirAgenda()` é o caminho da **agenda** — o que responde ao botão da tela e produz o aviso *"este cliente já tinha uma comanda aberta nesta unidade"*. `grep -rn comandaAbrirAgenda tests/` não devolvia nada. Arrancar a guarda dele deixava tudo verde. O escopo **por cliente E unidade** é decisão escrita neste próprio registro — *um cliente atendido em duas unidades no mesmo dia tem direito a duas comandas* — e não estava preso por teste nenhum. Sem a cláusula, o caixa da segunda franquia recebe a comanda aberta na primeira, **com os itens da outra loja dentro**. O teste que parecia cobrir isso (`testComandaDeOutroClienteNaoEReaproveitada`) só prova que a guarda não é por caixa. Os dois casos novos estão em `tests/Caracterizacao/ComandaFantasmaTest.php`, e a falsificação mostra que **cada um acusa o seu**, com os cinco testes antigos continuando verdes — que é o que prova que o buraco era real e não redundância. #### O que continua sem dono, e é da operação A concentração por unidade. Nos últimos 12 meses, só abandonadas: **Itapema Meia Praia 148 (R$ 19.839) contra Itajaí Centro 41 (R$ 5.065)**. Isso não é dívida de código — é matéria da Fase 2, como este registro já dizia. ### D53 — `clientes_creditos.pontuacao_validade` é fóssil da implementação anterior da mesma regra, e a previsão desta entrada se cumpriu: a API passou a publicá-lo — PARCIAL em 15/09/2026: fora da resposta e com portão; a coluna espera o corte Descoberto em 28/08/2026, ao ensinar `scripts/campos-regra-ou-referencia.php` a ignorar comentários. **Reescrito no mesmo dia**, depois de a regra de negócio ser enunciada e de eu medir o que o sistema faz hoje. **A regra, dita por quem decide:** > A data de validade da pontuação deve ser respeitada. No dia seguinte a > validade ter expirado, a pontuação deve ser subtraída do cliente. **Ela é cumprida.** Não por essa coluna, e sim pelo razão: `expirarPontuacao()` marca como `expirada` todo lançamento de `pontuacoes_historicos` com mais de um ano, e o saldo em `clientes_creditos.pontuacao` — que é **derivado**, soma dos lançamentos ativos — é recalculado na mesma execução do cron das 23:00. **Medido, e o número prova o "dia seguinte":** | | | |---|---:| | Lançamentos `expirada` | 285.275 | | Lançamentos `ativa` com mais de um ano | 1.801 | | **Atraso máximo entre esses** | **1 dia** | Um dia é exatamente a defasagem de uma rotina diária das 23:00 contra uma base tirada durante o dia. A comparação é `DATE(dataCriacao) < hoje - 1 ano`, então o dia do aniversário ainda vale e a subtração acontece no dia seguinte — o que a regra pede, na letra. Está coberto por `FidelidadeResgateVencimentoTest`, **nos dois lados da fronteira**: `testPontosComMaisDeUmAnoSaoExpirados` e `testPontosExatamenteNoLimiteDeUmAnoNaoExpiram`. **A coluna é o fóssil da implementação anterior da mesma regra**, e o dado diz isso com clareza: | Intervalo entre validade e criação do crédito | Créditos | |---|---:| | **365 dias** | 9.255 | | **366 dias** | 7.393 | | 0 dias (o padrão do construtor, nunca ajustado) | 44.922 | | cauda de 393 a 428 dias | ~1.700 | Um ano. A mesma regra, materializada por crédito em vez de calculada sobre o razão — e a cauda sugere que a data era prorrogada a cada novo ponto. O código que a escrevia não está no repositório. #### Medido em 30/08/2026: a coluna não parou. Piorou. Ao contar os nulos do **D65** apareceu uma data que este registro não tinha: **06/09/2024**. | | Até 06/09/2024 | Depois | |---|---|---| | Linhas com `pontuacao_validade` **nula** | existem | **nenhuma** | | Valor típico quando preenchida | **365 ou 366 dias**, mais cauda de 393 a 428 | **0 dias**, em 44.922 linhas | | Com 365/366 depois da virada | — | 445 | São 153.135 nulas e 103.849 preenchidas em 256.984 créditos reais. **"Fóssil" descreve o que a coluna significa, e não o que acontece com ela.** Ela continua sendo escrita — a última é de 16/08/2026 —, só que com a data de criação do próprio crédito. Como *validade*, isso diz "venceu no instante em que nasceu". **Isso é pior que uma coluna abandonada.** Coluna vazia manda perguntar; coluna preenchida com o padrão do construtor **responde**, e responde errado. Qualquer relatório, endpoint ou tela nova que leia `pontuacao_validade` como "quando estes pontos vencem" concluirá que 44.922 créditos venceram no dia em que foram criados. **O que mudou em 06/09/2024 não está no repositório** — o histórico começa na importação inicial. O que se pode dizer é que, a partir dali, o caminho que deixava a coluna nula deixou de existir, e todo crédito novo passou a nascer com o padrão de zero dia. **Isso reforça a remoção, não a enfraquece.** Enquanto a coluna existir, ela é uma resposta errada esperando por quem pergunte. **Não há regra quebrada, e não há o que implementar.** O que resta é limpeza, junto com o **D51**, depois do corte: remover a coluna e o método comentado `ClienteCreditoRepository::selecionarPontuacoesVencidas()`. **Remova o método comentado também.** Código comentado que sobrevive a uma limpeza é o que faz a próxima pessoa acreditar que existe uma segunda regra de vencimento — foi o que aconteceu comigo. **Um conserto feito no caminho:** o prazo de um ano estava escrito **duas vezes**, em `selecionarCientesPontuacaoVencida()` e em `expirarPontuacao()`. Os dois precisam concordar — o primeiro escolhe quem tem o saldo recalculado, o segundo decide o que expira. Divergindo, pontos expirariam sem o saldo ser refeito, e o cliente veria um saldo que já não existe, sem erro em lugar nenhum. Agora vêm de uma constante só, com teste que guarda a fonte única. #### A previsão se cumpriu em oito dias, dentro deste repositório O parágrafo acima dizia, em 30/08/2026: > Qualquer relatório, endpoint ou tela nova que leia `pontuacao_validade` como > "quando estes pontos vencem" concluirá que 44.922 créditos venceram no dia em > que foram criados. Em **07/09/2026**, oito dias depois, o commit `d8f7c9f` acrescentou a `FidelidadeJson::credito()`: ```php 'pontuacaoValidade' => self::dia($credito->getPontuacaoValidade()), ``` A coluna passou a sair em cinco pontos de `/adm/api` — `GET /adm/api/clientes/:id/creditos`, o detalhe e as duas respostas de resgate. **Nada ficou vermelho**, porque nada vigiava a porta: o único ensaio que tocava no campo o AFIRMAVA, medindo a Regra 6 sobre ele. Medido em 15/09/2026 na cópia anonimizada, só leitura: | | | |---|---:| | créditos reais | 256.984 | | coluna nula | 153.135 | | preenchida | 103.849 | | validade = data de criação | **44.922** | | **com `pontuacao > 0` e validade no passado** | **47.319** | Os 47.319 são o dano: para cada um deles a API respondia que a validade dos pontos já passou, enquanto o razão — que é quem manda — dizia o contrário. #### O que foi feito em 15/09/2026 1. **A linha saiu do `FidelidadeJson`.** Era a única leitura do fóssil fora da própria entidade, e é ela que transformava coluna morta em resposta errada. 2. **O ensaio mudou de alvo em vez de sumir.** `testAValidadeSaiComoDiaESemFuso` media a Regra 6 sobre o fóssil; passou a medi-la sobre a validade DE VERDADE, a do pacote contratado, formatada pelo mesmo `self::dia()`. E entrou o ensaio que faltava em 07/09: `testOCreditoNaoPublicaOFossilDaValidadeDePontuacao`. 3. **O método comentado `selecionarPontuacoesVencidas()` foi apagado**, como esta entrada já pedia. 4. **Nasceu `scripts/conferir-fosseis.php`**, o 38º portão, ligado ao `conferir-tudo.sh` na linha `fósseis lidos`. #### O portão, e a armadilha que ele quase teve A regra dele é uma só: um fóssil declarado só pode ser citado por quem está na licença, e cada permissão carrega o motivo escrito. Hoje são duas — a própria entidade (anotação, propriedade, construtor, getter, setter) e o ensaio que impede a chave de voltar. **A licença vale nas duas direções.** Arquivo novo lendo o fóssil reprova, e permissão que sobrou também: se um permitido parar de citar a coluna, a permissão virou letra morta e sai no mesmo commit — senão fica autorizando uma leitura futura que ninguém discutiu. **E a armadilha do nome quase me pegou.** O fóssil se chama `pontuacao_validade`; a regra de verdade se chama `pontuacao_validade_dias`, e o método que a aplica se chama `selecionarPontuacaoValidadePorClienteUnidade`. **O nome do fóssil é prefixo do nome da regra e está dentro do nome do método que a implementa.** A primeira versão do portão casava por substring e acusava **oito** arquivos — seis eram a regra de verdade. Com fronteira de identificador dos dois lados, são dois. É a mesma lição do D177, apertado no dia anterior: substring não identifica nada. Lá ela creditava cobertura que não existe; aqui ela **acusa defeito que não existe**, que é o erro caro na outra direção. #### A falsificação: cinco mutações | | o que mudou | esperado | obtido | |---|---|---|---| | G1 | a linha volta ao `FidelidadeJson` | portão vermelho | 1, nomeando o arquivo | | T1 | a mesma linha | ensaio vermelho | 1 falha, em `testOCreditoNaoPublicaOFossil…` | | G2 | uma permissão que não cita mais | vermelho | 1, *"permissão que sobrou"* | | G3 | o nome da **regra de verdade** num arquivo qualquer | **verde** | 0 | | G3 | o nome do **fóssil** no MESMO arquivo | vermelho | 1 | | G4 | piso acima do medido | 2 | 2, *"li 1012, o piso é 2000"* | **A G3 é a que vale**: mesmo arquivo, o nome da regra de verdade deixa o portão verde e o nome do fóssil o deixa vermelho. É a prova de que a fronteira separa os dois, e não uma suposição de que separa. #### Uma correção de rota nesta própria entrada O último parágrafo dizia que o prazo de um ano "agora vem de uma constante só". **Já não é verdade, e a mudança é melhoria:** o prazo virou configuração por unidade (`unidades.pontuacao_validade_dias`, com `0` = não expira), lida por `PontuacaoHistoricoRepository::unidadesPorPrazo()`. A preocupação original — que `selecionarCientesPontuacaoVencida()` e `expirarPontuacao()` concordem — continua atendida, porque os dois chamam aquela mesma função. O que mudou é que a fonte única deixou de ser uma constante e passou a ser uma tabela. Isso afasta a coluna `clientes_creditos.pontuacao_validade` **ainda mais** da regra: ela não é nem a versão velha do prazo atual, é a versão velha de um prazo que também já mudou de forma. #### O que continua aberto **O `DROP COLUMN`**, que é DDL em produção congelada — decisão do dono, junto com o D51, depois do corte. Até lá a coluna continua `NOT NULL` no banco e continua sendo escrita pelo construtor da entidade, e é por isso que a entidade está na licença do portão em vez de ser limpa. O que mudou é que ela deixou de ser **alcançável**: sai do banco para lugar nenhum, e a porta por onde ela escapou está vigiada. --- ### D54 — A coluna `pontuacao_validade_dias` precisa existir em produção ANTES do corte — PREPARADO, lido em 05/10/2026 > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito sem marca de estado, e o corpo diz que ele está pronto no código, à espera só do passo em produção na janela da migração final. Falta: aplicar `migracao-pontuacao-validade-unidade.sql` em produção e só então atualizar o `mysql.sql` com a estrutura de produção, no passo 1 do corte. Criada em 28/08/2026, ao tornar a validade da pontuação configurável por unidade. **Não é dívida de código — é dívida de sequência**, e o erro que ela previne é caro. `scripts/migracao-pontuacao-validade-unidade.sql` acrescenta `unidades.pontuacao_validade_dias` (INT NOT NULL DEFAULT 365). Foi aplicada ao ambiente local e ao `mysql.sql` versionado, e a aplicação já depende dela. **Produção ainda não tem a coluna**, porque está congelada. **A armadilha está no passo 1 do procedimento de corte:** *"atualizar `mysql.sql` com a estrutura de produção"*. Se esse passo rodar antes da migração, o dump refeito **não terá a coluna** — e como é dele que `scripts/gerar-ddl-postgres.php` parte, o schema PostgreSQL nasceria sem ela. A aplicação sobe, e morre na primeira tela de unidade e na primeira execução da rotina de vencimento. **A ordem que resolve, e não tem alternativa:** 1. Aplicar `migracao-pontuacao-validade-unidade.sql` em produção. É aditiva, idempotente, e a tabela tem 61 linhas — é das mudanças mais seguras que existem. 2. **Só então** atualizar o `mysql.sql` com a estrutura de produção. 3. Seguir o corte normalmente. **Se a decisão for não tocar em produção antes do corte**, então esta mudança precisa ser revertida e refeita depois — e é mais barato aplicar o `ALTER` do que reverter o código, os testes e o schema. **Já aconteceu, em miniatura, no ambiente local — e vale como aviso.** Ao terminar esta mudança, o `postgres/schema.sql` foi regerado com a coluna, mas o banco PostgreSQL local não foi recarregado a partir dele. O arquivo tinha a coluna; o banco, não. A suíte passou inteira no MySQL (84 testes) e quebrou 44 testes no PostgreSQL, todos por `column unidades.pontuacao_validade_dias does not exist`. Um `ALTER TABLE ... ADD COLUMN IF NOT EXISTS` resolveu. O erro local custou uma execução de suíte. O mesmo erro em produção, no corte, derruba a aplicação — e a diferença entre os dois casos é só a hora em que ele aparece. **Regerar o schema não é o mesmo que aplicá-lo**: sempre que uma coluna nascer aqui, ela precisa existir nos três lugares — no `mysql.sql` versionado, no `postgres/schema.sql` gerado, e nos bancos que estiverem de pé. --- ### D55 — Dez snapshots de contrato não descreviam carga nenhuma — RESOLVIDO Descoberto em 28/08/2026 ao conferir os números do roadmap; resolvido no mesmo dia. Fica registrado porque a causa se repete sozinha, e a trava que a impede precisa ser entendida por quem mexer nos testes depois. **O sintoma.** Quatro testes de contrato falhavam: `unidade-selecionar`, `unidade-selecionar-v2`, `servicos-selecionar` e `banners-selecionar`. Não era regressão — o código desses endpoints não é tocado desde a importação inicial (`eaf1fca`). O que mudou foi o banco local ter ganhado a cópia anonimizada da produção, e os endpoints passarem a devolver estrutura de verdade. **A causa, e ela não era a que eu supus primeiro.** Minha primeira leitura foi "os snapshots foram gravados contra banco vazio, e regravar exige a réplica de produção". Estava errada na segunda metade, e medir mostrou por quê. O CI monta o banco com `mysql.sql` (estrutura) mais `tests/Caracterizacao/fixtures.sql` (cenário). As fixtures povoavam oito tabelas — e **nenhuma delas era `app_banners`, `agendas`, `cupons`, `sorteios`, `areas_atuacao` ou `indicacoes`**. Pior: os testes pediam `/api/.../1`, e as fixtures criam a unidade e o cliente **90001000**. O id 1 nunca existiu ali. Montando o banco do CI e batendo nos endpoints, os dez devolviam exatamente as estruturas vazias que os snapshots guardavam. **O CI estava verde, e o verde não significava nada.** Não faltava acesso a produção: faltava cenário. **Dez, não quatro.** Quatro acusavam. Os outros seis passavam: | Snapshot | O que guardava | Situação antes | |---|---|---| | `unidade-selecionar` | `sucesso` | falhava | | `unidade-selecionar-v2` | `sucesso` | falhava | | `servicos-selecionar` | `sucesso` | falhava | | `banners-selecionar` | `banners: "(vazio)"` | falhava | | `agenda-selecionar` | `sucesso` | **passava** | | `cliente-agenda` | `agenda: "(vazio)"` | **passava** | | `cupons-selecionar` | `cupons: "(vazio)"` | **passava** | | `indicacoes-listar` | `indicacoes: "(vazio)"` | **passava** | | `sorteios-selecionar-cupons` | `sorteios: "(vazio)"` | **passava** | | `unidades-selecionar` | 4 campos como `null` | **passava** | O último é o mais instrutivo, e não estava na varredura inicial: gravava `estado`, `latitude`, `longitude` e `telefone` com o tipo **`null`**, porque a unidade das fixtures os tinha vazios. Produção manda texto nos quatro. O teste passava afirmando um contrato que o aplicativo nunca recebe. `(vazio)` merece uma palavra: o gerador de snapshot, sem elemento para inspecionar numa lista, escrevia **a ausência como se fosse um tipo**. `{"banners": "(vazio)"}` diz que existe uma lista chamada banners e não diz nada sobre o que há dentro de um — que é a única coisa que o aplicativo lê. **O que foi feito.** 1. `fixtures.sql` ganhou o cenário do contrato: banner, duas agendas, área de atuação com serviço, cupom válido, sorteio já realizado e indicação já rendida — e a unidade teve os quatro campos vazios preenchidos. 2. Os dez testes passaram a pedir os ids que as fixtures criam. 3. Os snapshots foram regravados **contra o banco do CI**, não contra a base anonimizada — para isso existe `scripts/montar-banco-contrato.sh`. 4. `ContratoTestCase::assertContrato()` ganhou uma trava: **estrutura sem carga não é mais gravável nem aceitável**, a menos que o snapshot se declare um caso de vazio pelo sufixo `-sem-dados`. Resultado: 28 de 28 verdes, com 177 linhas de contrato onde antes havia invólucro. As duas suítes passam nas duas ordens de execução. **Três coisas que o caminho ensinou, e que valem mais que o conserto:** **O cenário do contrato e o cenário do cálculo precisam de sujeitos diferentes.** O cupom foi parar no cliente 90001000 e três testes financeiros quebraram — `CupomTest::cuponsDoCliente()` conta `cupons_clientes WHERE cliente = 90001000` e afirma quantidades exatas. O cupom mudou para o cliente convidado. **As fixtures precisam apagar filho antes de pai.** As agendas novas apontam para um produto, e `DELETE FROM produtos WHERE id >= 90001000` passou a falhar por chave estrangeira — o que faz o mysql **abortar o arquivo inteiro naquela linha**, deixando as fixtures pela metade. A limpeza dos filhos agora vem antes. **E o carregador precisa saber falhar.** A primeira versão de `montar-banco-contrato.sh` filtrava a saída com `| grep -v ... || true` para esconder o aviso de senha do mysql — e escondia os erros junto. O banco carregou pela metade e o script disse que estava tudo bem; os snapshots quase foram regravados contra ele. É o mesmo defeito que já apareceu na conferência da carga (D49) e no comparador de ensaios: **uma verificação que não consegue acusar é pior que nenhuma**, porque ocupa o lugar de uma que conseguiria. **O que continua valendo para quem vier depois:** um snapshot só vale o dado que existia quando foi gravado. A trava impede o caso extremo — gravar o vazio — mas não impede um cenário pobre. Se um endpoint novo entrar, o cenário dele entra junto. --- ### D56 — O `status` do sorteio chegava nulo ao aplicativo — CORRIGIDO Descoberto em 28/08/2026 ao povoar as fixtures do contrato (D55), corrigido no mesmo dia por decisão sua. Só apareceu porque o endpoint passou a devolver carga: enquanto a lista vinha vazia, não havia campo para estar errado. **O defeito eram dois erros empilhados**, e o de cima escondia o de baixo: 1. `AplicativoController::sorteiosSelecionarCuponsAction()` chamava `Arrays::marketingSorteiosStatus($sorteio['nome'], false)` — passava o **nome** do sorteio onde a função espera a *chave* do status (`ativo`, `aguardandoSorteio`, `finalizado`, `cancelado`). Nenhum nome casa, então caía fora de todos os ramos e devolvia nulo. 2. Mesmo corrigindo a chamada, não haveria o que passar: `SorteioVendaRepository::selecionarSorteiosPorCliente()` não selecionava `sor.status`. O campo nem existia no array — trocar só a chamada teria substituído o nulo por aviso de índice indefinido. **A correção são duas linhas:** `sor.status` entrou no SELECT da DQL, e a ação passa `$sorteio['status']`. Um detalhe do PostgreSQL que valia conferir e foi conferido: a DQL agrupa por `sor.id` e seleciona outras colunas da mesma entidade. Isso é legal nos dois bancos — ambos reconhecem a dependência funcional da chave primária — então acrescentar mais uma coluna não recria o problema do D24. **O impacto, medido contra a cópia anonimizada da produção:** | | | |---|---| | Sorteios cadastrados | 4, entre out/2023 e out/2025 | | Participações | 7.214 | | **Clientes que veem sorteio no app** | **5.002** | | Última atividade | out/2025 — **a função está dormente há 10 meses** | | Valores de status na base | `finalizado`, `cancelado`, `aguardandoSorteio` | Os valores da base **são** as chaves que a função conhece, então a correção produz rótulo de verdade: um cliente que antes recebia `null` agora recebe `"Finalizado"`. **A mudança de contrato é de uma linha:** `status` passa de `null` para `string`. Nenhum campo entra, nenhum sai, nenhum muda de nome. Um aplicativo antigo que tratava o nulo como "sem informação" passa a receber texto no lugar de nada — que é a intenção da tela. O risco é baixo justamente por causa do estado da função: **não há sorteio em andamento desde out/2025**. Os 5.002 clientes alcançados veem sorteios encerrados, e o rótulo que passam a ver é "Finalizado" — informação correta onde antes não havia nenhuma. Ver `funcionalidades-sem-uso.md` para onde os sorteios se encaixam entre as funções vivas, dormentes e nunca ligadas. **Uma coisa que a correção trouxe de brinde:** a fixture do contrato usava `status = 'aberto'`, valor que **o sistema não produz**. Passou a usar `finalizado`. Cenário de teste com valor inventado é um contrato que descreve um mundo que não existe — e teria escondido este mesmo defeito de novo. --- ### D57 — A função "assistentes" fica FORA da Fase 2 — DECIDIDO em 31/08/2026 — ABERTO, lido em 05/10/2026 — DECIDIDO em 15/10/2026 pela resposta 144 (a): o uso entra na tela nova, e a administração fica na tela antiga > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito como fechado, e o corpo diz que ele está aberto: o defeito segue sem conserto no código. Falta: a resposta à P14 do consolidado sobre os assistentes, refeita sobre a premissa corrigida pelo D343: vínculo vazio quer dizer todas as unidades. Registrada em 28/08/2026, por decisão sua ao avaliar `funcionalidades-sem-uso.md`: *"VIP Class sim, assistentes anote como débito e revistaremos no futuro"*. **O estado, medido na cópia anonimizada da produção:** | | | |---|---| | `assistentes` | 4 cadastrados | | `assistentes_grupos` | 11 | | **`assistentes_unidades`** | **0 — nenhuma das 62 unidades tem acesso** | | Ações no inventário | **7** (`AssistentesAdminController` 5, `AssistentesUsuariosController` 2) | Não é função pela metade: é função inteira, com conteúdo cadastrado e a chave nunca girada. Alguém construiu, alguém cadastrou, e nenhuma unidade foi vinculada. **Correção de registro (03/10/2026):** o "0 -- nenhuma das 62 unidades tem acesso" desta tabela leu o vínculo vazio como função desligada, e o código lê o contrário: `assistentes_unidades` vazia quer dizer **todas** as unidades (`module/ISConfiguracao/src/Entity/AssistenteRepository.php:57-60`, `uni.unidade IS NULL OR ...`). Os 4 assistentes estão no menu de 211 pessoas, em 31 das 32 unidades ativas. E o "como conferir" abaixo mede a coisa errada: a tabela deixar de estar vazia quer dizer que alguém **restringiu** os assistentes, e não que os ligou. É o **D343**, que registra o erro e o conserto do texto (este débito, o `docs/roadmap.md` e o `docs/funcionalidades-sem-uso.md`). A decisão de 31/08 foi tomada sobre esta premissa, e o desenho dos assistentes a leva de novo ao dono (a P14 de `docs/f3-telas-restantes/telas-consolidado.md`). **O que NÃO precisa ser decidido, porque já está resolvido:** As três tabelas migram junto com as outras 82 — estão em `migrar-dados.sh`, têm `inquilino_id` e RLS ligado no `postgres/schema.sql`. **Adiar a decisão não custa nada no corte**, e é por isso que dá para adiá-la com tranquilidade. O dado atravessa inteiro, ligada ou não. **O que precisa ser decidido, e só na Fase 2:** Se as 7 ações viram endpoint REST e tela React. São 2% do inventário de 360 — o suficiente para valer a pergunta, pequeno o bastante para não travar nada. #### A DECISÃO, tomada em 31/08/2026 **Por decisão sua, as 7 ações ficam FORA da Fase 2.** Nenhum endpoint REST, nenhuma tela React. O raciocínio: o dado atravessa o corte de qualquer jeito, então nada se perde. E se a função vier a ser desejada um dia, nascer na plataforma nova é mais barato que portar telas que ninguém nunca usou — portar tela sem usuário é como uma função morta vira permanente. **O que isso cria, e não é para agora:** a remoção das três tabelas e do código legado vira tarefa **depois do corte**, junto com as outras limpezas pós-corte. Antes disso não se mexe — enquanto o sistema atual estiver de pé, o código precisa continuar existindo. **O que isso NÃO muda:** `migrar-dados.sh` e o `postgres/schema.sql` continuam como estão. As três tabelas migram, com `inquilino_id` e RLS. Tirá-las agora seria decidir a remoção antes do corte, que é exatamente o que esta decisão adiou. **A ressalva que fica de pé:** a decisão foi tomada sobre o retrato local. Se a consulta abaixo devolver algo diferente de zero quando a produção voltar a ser lida, alguém ligou a função e a decisão merece ser revista antes da limpeza. **Como conferir se algo mudou:** se `assistentes_unidades` deixar de estar vazia, alguém ligou a função e a decisão já foi tomada na prática. ```sql SELECT COUNT(*) FROM assistentes_unidades; ``` *Correção de registro (04/10/2026, o D343):* a consulta acima mede a coisa errada -- a tabela deixar de estar vazia quer dizer que alguém **restringiu** os assistentes. O que diz se a função está ligada é quem vê o cartão: a pessoa ativa, numa unidade ativa, com um assistente ativo do seu grupo e da sua unidade, e o vínculo vazio quer dizer todos e todas (a regra de `AssistenteRepository::listagemIndexUsuarios`). Medido no `franquiabv_dev` em 04/10/2026: **215 pessoas, em 31 unidades** (sem contar o privilégio do menu, que é o Dβ do desenho; com ele, as 211 do Q12). ```sql SELECT COUNT(DISTINCT u.id) AS pessoas, COUNT(DISTINCT u.unidade) AS unidades FROM usuarios u JOIN unidades un ON un.id = u.unidade AND un.status = 1 JOIN assistentes a ON a.status = 1 WHERE u.status = 1 AND u.id < 90001000 AND (NOT EXISTS (SELECT 1 FROM assistentes_grupos ag WHERE ag.assistente = a.id) OR EXISTS (SELECT 1 FROM assistentes_grupos ag WHERE ag.assistente = a.id AND ag.grupo = u.grupo)) AND (NOT EXISTS (SELECT 1 FROM assistentes_unidades au WHERE au.assistente = a.id) OR EXISTS (SELECT 1 FROM assistentes_unidades au WHERE au.assistente = a.id AND au.unidade = u.unidade)); ``` *Conferido em 30/08/2026:* segue **4 assistentes, 11 grupos, 0 unidades**. Nada mudou, e a decisão continua aberta com o mesmo custo de antes. **A ressalva importa:** a conferência foi feita na cópia anonimizada local, que é um retrato da produção — não a produção de hoje, que está congelada. Se alguém ligou a função desde a última leitura, isto não veria. Vale repetir a consulta no servidor quando ele voltar a ser lido. > **Conferido em 07/10/2026 (o item CODIGO-MORTO-E-DOCS):** a premissa desta decisão -- > "nenhuma unidade vinculada" como função desligada -- está errada, e o D343 a corrigiu > aqui e nos dois guias; o `docs/roadmap.md` e o `docs/funcionalidades-sem-uso.md` ainda > tinham duas frases da mesma leitura ("as funções desligadas", "não há usuário hoje" > para a VIP Class), corrigidas hoje ao lado delas. A P14 do consolidado, que leva a > decisão de volta ao dono, segue sem resposta: nem no consolidado, nem entre as 47 > respostas da página do lote lidas nesta data. **Decidido pelo dono em 08/10/2026 (pergunta 49 da página do lote, com o D343):** a opção (a), *"Manter a ordem de 27/09"* -- "A tela antiga segue em uso, para os alunos e para quem administra, até a nova chegar." A VIP Class fica em 8º de 9 na ordem das telas, depois de contas a pagar, sabendo que ela tem gente usando. A pergunta era só sobre a posição da VIP Class; o que este débito espera -- se a administração dos assistentes (e a da VIP Class) entra na tela nova, a P14 do consolidado -- segue sem resposta, e ele continua ABERTO. **Decidido pelo dono em 11/10/2026, registrado em 15/10/2026 (a pergunta 144 da página do lote, a P14 do consolidado; a fatia PONTE-PARA-A-ANTIGA):** a opção (a), *"A VIP Class inteira; dos Assistentes, só a tela de uso"* -- "A administração dos Assistentes fica na tela antiga, consertada." É a opção B da P1 de `docs/f3-telas-restantes/tela-assistentes.md`. O que ela fecha aqui: a função não fica fora da tela nova -- o USO entra (a F1b, a F2, a F3 e a F7 do desenho, a lista da opção B; a F1 já foi feita; as fatias 86 a 88 da fila das telas) --, e a ADMINISTRAÇÃO fica na tela antiga, já consertada pela F1 de 04/10/2026 (o D340, o D341, o D342 na parte dos assistentes, e do D407 ao D412). A F6 do desenho, as páginas públicas, não é do uso nem desta resposta: espera a P15 do consolidado (a P2 do desenho), e é a fatia 89 da fila. No menu novo, o "Configurações › Assistentes VIP" abre a tela antiga em aba nova desde 15/10/2026 (`novaAba`, com o motivo em `frontend/src/telas/menu-do-erp.teste.ts`), e não cai mais na tela que prometia "o conteúdo entra quando for migrado". O painel do Zapier era condição da RECOMENDAÇÃO da pergunta, e não do dono: ela pedia "(a), depois de você olhar o painel do Zapier", e abria a desativação dos bots se ele dissesse, na observação, que quase ninguém conversou com eles em 2026. O dono marcou (a) e deixou a observação vazia: não pediu a desativação, e a resposta não a deixa em aberto. A remoção das três tabelas depois do corte, que a decisão de 31/08 anotava, caiu com ela: o uso migra, e as tabelas ficam. --- ### D58 — Desativar a pesquisa derrubava o cadastro do programa de fidelidade — CORRIGIDO Descoberto e corrigido em 28/08/2026, ao examinar a função "pesquisas" para decidir se entra na Fase 2. **Um clique numa tela de administração quebrava um fluxo público de 25 mil usuários** — sem aviso, sem erro visível para quem clicou, e numa tela diferente daquela em que se clicou. **O caminho, inteiro:** 1. `PesquisaRepository::selecionarPorFidelidade()` busca a pesquisa **ativa** com `programaFidelidade = 1` e devolve `getOneOrNullResult()` — pode ser nula. 2. `PesquisasController::ativarRemoverAction()` desativava **qualquer** pesquisa sem conferir se era a da fidelidade. `removerPesquisasPlanoFidelidade()` garante que nunca haja duas marcadas, mas nada garantia que houvesse uma. 3. Com nenhuma ativa, `FidelidadeController::cadastroAction()` passava o nulo adiante e a view fazia `$pesquisa->getPerguntas()` (`fidelidade/cadastro.phtml:216`) **sem conferir**. Resultado: a página do cadastro de fidelidade deixava de renderizar — desde a abertura, não só a etapa 5. Na submissão o mesmo nulo reaparecia em `FidelidadeController:83`. **Por que importava tanto:** | | | |---|---| | Clientes no programa de fidelidade | **25.455** | | Respostas acumuladas da pesquisa | **25.471** | | Pontuação de cadastro mais recente | **2026-08-16** | A diferença de 16 respostas para 25.455 cadastros confirma o que o código já dizia: a pesquisa é a **etapa 5 obrigatória** da adesão. **A correção, nas duas camadas:** **1. Impedir a causa.** `PesquisaService::alterStatus()` recusa desativar a pesquisa marcada como do programa de fidelidade, devolvendo `false`. O controller passou a olhar esse retorno e explica o motivo em vez de anunciar sucesso. A trava ficou no **serviço, não no controller** — protege qualquer chamador, inclusive os que ainda não existem, e pode ser testada sem subir HTTP. **2. Sobreviver ao efeito.** Sem pesquisa ativa, a etapa 5 passa em branco em vez de derrubar a página: o controller monta lista vazia de perguntas, e a view percorre lista vazia. A validação não encontra pergunta por responder, e `FidelidadeService` ainda marca `programaFidelidade` — que é o que a etapa faz de essencial. **O cliente adere; só não responde pesquisa.** Vale notar por que a camada 2 continua necessária mesmo com a camada 1: a trava impede *desativar*, mas a marcação pode sumir por outro caminho — uma edição, uma carga de dados, um banco novo antes de cadastrar a primeira pesquisa. **Nada muda no estado de hoje.** Com a pesquisa 2 ativa e marcada, as duas camadas são inertes: o fluxo público continua idêntico. São mudanças defensivas. **Cobertura:** `tests/Caracterizacao/PesquisaFidelidadeTest.php`, 5 testes. Conferi que eles acusam — removendo a trava do serviço, o primeiro falha com "Failed asserting that true is false". O teste dos dois pontos que derrubavam a página verifica **por leitura do código**, não por execução, e a razão é registrada nele: exercitar a adesão exigiria um cliente com hash de 8 caracteres, e a anonimização reescreveu os hashes para 32. É mais um ponto cego conhecido da base anonimizada. --- ### D59 — A API do aplicativo não autentica, e um telefone devolve o CPF — PARCIAL, lido em 05/10/2026 — PARCIAL em 11/10/2026: a sessão V4 renova — PARCIAL em 12/10/2026: o código sai pelo WhatsApp central; falta a credencial, do dono — PARCIAL em 14/10/2026: o número será novo — ANOTADO em 14/10/2026: a 189 (b) > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito sem marca de estado, e o corpo diz que ele está parcial: uma parte está consertada, e a outra não. Falta: as rotas trancadas só sobem com o aplicativo novo em `/api/v4`, após o inventário de versões (W3); WhatsApp nas oito unidades; token de renovação. > **Leia junto com o D13**, que é o mesmo assunto visto do lado do código — lá > está a causa: `AplicativoController` declara `$tokenPadrao` e nunca o compara. > Este registra o que se alcança sem autenticação; aquele, por que ela não > existe. Conferido em 30/08/2026 que não são duplicata. Registrado em 29/08/2026, ao desenhar a autenticação da Fase 2. **Confirmado por você:** *"hoje não faz autenticação, apenas identificação de telefone"*. **O que isso significa na prática**, demonstrado contra o ambiente local: ``` $ curl http://localhost:8080/api/cliente/agenda/149612 {"sucesso":true,"agenda":[{"id":5409814,"data":"04/09/2026 09:00:00", "colaborador":"Colaborador 2425", ... ``` Nenhum cabeçalho, nenhum segredo — **o id sequencial do cliente é a credencial**. As rotas recebem `:id` direto, não há endpoint de login, e o módulo não tem listener de autenticação. O único `bearer_token` do código é da Zoomtec, para o visagismo, e não tem relação com o cliente. Vale dizer o que isso **não** é: não é um defeito introduzido, nem uma regressão. É o desenho original, de quando o aplicativo era menor e o risco era outro. **A porta de entrada é o telefone, e ela é mais larga do que o id.** `GET /api/agendas/getCliente?telefone=47999999999`, sem cabeçalho nenhum, devolve: ``` id 90004000 nome Alvo Da Demonstracao cpf 111.222.333-44 rg MG-11.222.333 telefone +55 (47) 99999-9999 email alvo@exemplo.test ``` Demonstrado no ambiente local com um cliente criado só para isso e removido em seguida — a base anonimizada reescreve o formato do telefone, então não havia como casar com dado existente. **Um número de telefone devolve o CPF e o RG da pessoa.** É a "identificação por telefone" que sustenta o aplicativo, e ela entrega documento de identidade a quem apenas pergunta. **E devolve o `id`, que destrava o resto:** | Rota | O que devolve a quem tem o id | |---|---| | `/api/cliente/agenda/:id` | próximos agendamentos, unidade, colaborador | | `/api/cupons/selecionar/:id` | cupons ativos e onde valem | | `/api/sorteios/selecionarCupons/:id` | participações em sorteios | | `/api/cliente/indicacoes/:id` | **nome e telefone de terceiros indicados** | A última linha é diferente das outras: as três primeiras expõem dados de quem tem o id; **esta expõe dados de quem nem sequer é o dono do id** — a pessoa convidada, que não participou daquela chamada e não escolheu estar ali. Os ids também são inteiros sequenciais, e são 243 mil clientes — de modo que há duas formas de chegar: pelo telefone, uma pessoa por vez, ou pelo id, em sequência. Registrado como matéria de LGPD, junto dos demais itens já marcados como dívida futura. **Por que não corrigi:** Corrigir aqui é **mudar o contrato do mundo congelado** (D5). Exigir token nas rotas atuais derruba todo aplicativo instalado na hora, e não há como atualizar o parque de uma vez — é exatamente o que os 28 testes de contrato existem para impedir que aconteça por acidente. **O caminho que funciona, e a ordem importa:** 1. **Saber quais versões do aplicativo estão em uso.** É a pendência da W3 que nunca foi resolvida, e sai dos logs do nginx. Sem isso não há como definir prazo de aposentadoria para nada — só chute. 2. **Endpoints novos, autenticados, em versão nova** (`/api/v4/...`), enquanto os atuais seguem funcionando. 3. **Aplicativo novo passa a usá-los**, e o parque roda naturalmente. 4. **Aposentar os antigos** quando o número do passo 1 disser que dá. O passo 1 é o único que não depende de decisão nenhuma — é leitura de log, e destrava os outros três. Ele já estava pendente por outro motivo: sem ele também não se sabe quais contratos podem ser aposentados com segurança. **A ferramenta do passo 1 está pronta:** `scripts/inventariar-versoes-app.php`. Roda com `--dir=/var/log/nginx`, aceita `.gz`, não escreve nada e não toca em banco — é leitura pura, e por isso pode rodar em produção sem cerimônia. Cruza os três sinais de versão (`?versao=`, prefixo da rota, User-Agent) e lista as rotas declaradas que não apareceram. Duas coisas nela são deliberadas. Ela classifica rota sem chamada como **SUSPEITA e nunca como morta**, e imprime a janela observada em destaque: *"não apareceu no log" não é "está morto", é "não apareceu na janela"* — um cliente que vai à barbearia a cada dois meses é invisível num log de sete dias. E ela **nunca copia valor de parâmetro para o relatório**, porque a query string traz telefone; conta quantas requisições carregam dado pessoal, e só. **Duas contenções que NÃO quebram o parque instalado**, se a espera pelo caminho completo parecer longa demais: 1. **Limite de taxa no nginx** para `/api/agendas/getCliente`. A colheita em massa depende de repetição; o uso legítimo é uma consulta por abertura de aplicativo. Não toca no contrato, porque não muda resposta nenhuma. 2. **Mascarar `cpf` e `rg` na resposta.** E há um detalhe que torna isso mais barato do que parece: **o snapshot de contrato registra o TIPO, não o valor** — `cpf` continua sendo `string`. A suíte não acusa, e nenhum aplicativo que apenas repassa o campo quebra. O que pode quebrar é uma tela que exiba o CPF inteiro, e saber se existe tal tela exige olhar o aplicativo. Nenhuma das duas substitui a autenticação. As duas encurtam a janela enquanto ela não vem, e nenhuma delas espera pelo inventário de versões. **Um efeito colateral bom:** resolver isto resolve junto o **D45** — o inquilino é fixo na configuração porque não há de onde tirá-lo; com autenticação de verdade, ele passa a vir de quem está autenticado. #### O ALCANCE É MAIOR DO QUE ESTE REGISTRO DIZIA — medido em 03/09/2026 A consulta é `appSelecionarClientesPorTelefone`, e ela **não tem limite**: um `getResult()` sem `setMaxResults`. O controller percorre tudo o que voltar (`AplicativoController:290`) e monta um item por cliente. **Uma requisição pode devolver o documento de muitas pessoas**, e o número já estava medido — no **D41**, sobre a réplica de produção: | | | |---|---:| | Telefones com mais de um cliente ativo | **5.670** | | Clientes envolvidos | 13.379 | | **Pior caso, num único número** | **354 clientes** | Este registro dizia *"um número de telefone devolve o CPF e o RG da pessoa"*. Devolve o de **até 354 pessoas** — e quem pergunta não precisa ser nenhuma delas. *Isso muda a ordem das duas contenções.* Limite de taxa reduz **quantas vezes** se pergunta; não reduz **quanto volta em cada resposta**. Contra a amplificação, mascarar vale mais. #### CONTENÇÃO 1 APLICADA em 03/09/2026 — limite de taxa `docker/nginx/default.conf`: zona `busca_cliente`, 30 requisições por minuto por endereço, com `burst=20 nodelay` e `429` como recusa. Só em `/api/agendas/getCliente`; as outras rotas não foram tocadas. **Não muda resposta nenhuma**, então não toca no contrato (**D5**) — conferido: a suíte de contrato passa com o limite ativo, 35 de 35. *Posto à prova, e o primeiro teste não provou nada.* Quarenta requisições sequenciais passaram todas — porque cada `curl` demora o bastante para o balde reabastecer. Só com **60 em paralelo** a recusa apareceu: 36 servidas, 24 com 429. Com um limite absurdo (1/min) a terceira já era recusada, o que confirmou que o mecanismo funcionava e que o problema era a minha medição. **O valor ainda não é o certo, e está escrito no arquivo.** A conta possível hoje: ~800 clientes/dia em 32 unidades, ~3 requisições por minuto somando todo mundo; 30 por endereço deixa dez vezes de folga. O que ela não cobre é o **CGNAT** — milhares de clientes legítimos saem do mesmo endereço numa operadora móvel. O número definitivo sai do log do nginx, que é a pendência **W3**. **E ele não resolve o D59.** A 30 por minuto ainda se colhe muito, e uma única requisição já pode trazer 354 pessoas. Limite encurta a janela; quem fecha a porta é a autenticação. #### DECIDIDO em 03/09/2026: a rota passa a exigir autenticação > *"o /api/agendas/getCliente deve responder apenas com autenticação, seja do > próprio cliente, seja de algum usuário do sistema logado."* Implementado. Sem sessão, a rota responde **401**; com sessão do ERP, responde como antes. Medido contra a aplicação de pé. **Das duas autenticações, só uma existe hoje.** O ERP tem sessão, e é ela que está sendo conferida. **O cliente não tem credencial nenhuma** — não há login de cliente, não há token, e o `$tokenPadrao` da classe é declarado e nunca comparado (**D13**). A metade do cliente continua por construir, e não é trabalho só de código: exige uma **prova de identidade** que hoje não existe. As duas candidatas naturais — SMS e e-mail — esbarram numa decisão sua anterior, de ignorar tudo de SMS por enquanto. **O QUE ISSO CUSTA, e é preciso dizer sem rodeio.** O aplicativo instalado **não consegue se autenticar**. No instante do deploy, a busca por telefone deixa de responder a ele — em todo o parque, de uma vez. Não há meio-termo: exigir credencial de quem não tem nenhuma é negar. Por isso o deploy depende do **passo 2** deste débito (aplicativo novo em campo), que depende do **passo 1** (saber quais versões estão em uso, W3). A ordem não mudou; o que mudou é que o destino agora está decidido. **A suíte de contrato acusou, e o vermelho era verdadeiro.** Dois testes — `testClienteSelecionarSemDados` e `testClienteSelecionarComDados` — e só eles. Os snapshots foram regravados de propósito, e o diff mostra o que o contrato antigo era: ``` - "cpf": "string", "email": "string", "nome": "string", - "rg": "string", "telefone": "string" + "status": 401 ``` *O contrato antigo era o da exposição.* A suíte existe para impedir quebra por **acidente**; esta é por decisão, e está escrita no próprio teste para o próximo leitor não confundir as duas. **Guardado por `conferir-autorizacao-privilegiada.php`**, sexta entrada. Ela é de natureza diferente das outras cinco — não reconfirma senha, só exige que exista sessão —, mas o risco é o mesmo: é uma linha que, apagada, não quebra teste nenhum, e a suíte passaria a gravar a exposição de volta como se fosse o contrato certo. #### E A ROTA DE INDICAÇÕES, no mesmo dia — a que expõe terceiros `/api/cliente/indicacoes/:id` passou a exigir sessão também. Ela era a mais grave das quatro alcançáveis pelo `id` sequencial, e por um motivo de **natureza**: as outras três expõem dado de quem *tem* o id; esta devolve `convidado_nome` e `convidado_telefone` — dado de **terceiro**, que não participou da chamada e não tem como saber que está ali. **Nenhum campo precisou sair, e vale dizer por quê:** o telefone do convidado foi **digitado pelo próprio indicador** ao convidar (`FidelidadeService:75`). Devolvê-lo a ele não revela nada que ele não saiba. O defeito nunca foi o campo — era responder a qualquer um que soubesse um número inteiro. **Um agravante que não estava registrado, medido em 03/09:** essa ação manda `Access-Control-Allow-Origin: *`, e **19 ações** desta classe fazem o mesmo (mais uma no `VisagismoController`, 20 no total). Com `*`, qualquer página em qualquer navegador lia a resposta entre origens — a colheita não precisava nem de servidor próprio, podia pegar carona no navegador de quem visitasse a página. *Exigir sessão fecha isso pelo próprio protocolo:* navegador não envia credencial para resposta com `Access-Control-Allow-Origin: *`. As outras 18 ações continuam como estão, e o CORS aberto nelas fica registrado aqui como coisa a decidir. #### O PREÇO DESTA DECISÃO: duas cargas ficaram sem contrato — **pago em 03/09** Exigir sessão tirou dois endpoints da proteção da suíte de contrato, porque **ela não sabia autenticar**: não havia porta-cookies em `ContratoTestCase`, e o usuário das fixtures do banco de contrato tinha um bcrypt de mentira, então não fazia login. O que a suíte alcançava nessas rotas era a **recusa**, e não a carga. O formato entregue a um chamador autenticado deixou de ser congelado — em `cliente-selecionar` e em `indicacoes-listar`. **A suíte ganhou login no mesmo dia**, e as duas cargas voltaram a ser congeladas: `cliente-selecionar-autenticado` (10 campos) e `indicacoes-listar-autenticado` (9 campos). São 37 testes, e cada rota agora tem **dois**: um prova que anônimo é recusado, o outro prova o formato que quem tem credencial recebe. Só o primeiro deixaria a porta fechada sem ninguém olhar o que há atrás dela. **O HASH não é versionado — e a distinção não é cosmética.** O texto claro está no `scripts/definir-senha-contrato.php`, e não adianta fingir o contrário. O que muda é *onde ele passa a valer*: um bcrypt dentro do `fixtures.sql` valeria em TODO banco montado a partir das fixtures, e o de desenvolvimento é um deles — o que tem a cópia anonimizada da produção, com 243 mil clientes. O usuário de fixture ganharia lá uma senha que funciona, sem ninguém pedir. O roteiro **recusa qualquer banco com mais de 10 unidades**, e o de contrato nasce só das fixtures. É esse guarda que faz a senha ser inofensiva, não o segredo dela. Ele é chamado de dois lugares — o `scripts/rodar-contrato.sh` e um passo do CI —, porque o CI monta o banco só com `mysql.sql` mais `fixtures.sql`, sem passar pelo roteiro. Os dois precisam existir. ##### Três defeitos que só um login faria aparecer **1. O ACL lança exceção para funcionalidade que não existe.** O banco de contrato nasce de um dump de ESTRUTURA: `funcionalidades` estava vazia, e `Acl::isAllowed()` não devolve `false` para recurso desconhecido — ele *lança*. O login respondia 500 sem dizer por quê. Marcar o grupo como `administrador` não resolve: foi medido. As 63 funcionalidades que o `SessaoAcl::setAcl` pede por nome passaram a ser fixture. **2. O `fixtures.sql` entrava em latin1.** O cliente `mysql` do contêiner abre a conexão em latin1; o `mysql.sql` se protege com um `SET NAMES` do próprio `mysqldump`, e o `fixtures.sql` não tinha nenhum. Os 61 nomes acentuados entraram DOBRADOS, e o ACL — que compara nome por nome — não achava nenhum deles. A declaração ficou dentro do arquivo, e não no roteiro que o carrega, porque o CI carrega o arquivo direto, com outro cliente e outro padrão: corrigir só o roteiro deixaria os dois bancos diferentes, que é a pior forma de estar errado. *E a medição do estrago quase mentiu de volta:* contei os nomes dobrados com `LIKE '%Ã%'`, e a coluna é `utf8mb3_general_ci` — **insensível a acento**. O `LIKE` casava com qualquer nome que tivesse a letra "a", e disse "60 dobrados" depois da correção já estar feita. A contagem honesta é sobre `HEX()`. **3. O porta-cookies estático poluiu os snapshots públicos.** A primeira versão mandava sessão sempre que o login já tivesse acontecido *alguma vez*. Como o campo é estático, o primeiro login valia para o resto da classe: `cliente-selecionar` — que existe para provar que a rota recusa anônimo — foi regravado com 200 e a carga inteira. O interruptor passou a ser um parâmetro de cada requisição, e a suíte roda verde também com `--order-by=reverse`, que é exatamente a condição que a quebrou. *E a própria suíte me obrigou a nomear isso corretamente.* Tentar gravar o 401 sob o nome antigo falhou, com a mensagem certa: *"gravar assim daria um teste que passa sem proteger o formato entregue ao aplicativo (D55)"*. O sufixo `-sem-dados` existia para forçar a declaração de que o vazio é proposital; agora há dois motivos distintos para um corpo vazio, e o segundo ganhou sufixo próprio — `-sem-autenticacao`. Chamar recusa de "sem dados" seria descrever a causa errada, e sufixo que mente é pior que sufixo nenhum. #### A METADE DO CLIENTE FOI CONSTRUÍDA — 03/09/2026 > *"ataque a autenticação do próprio cliente no D59"* O cliente final passou a ter credencial. Não era só código: exigia uma **prova de identidade** que este sistema não tinha — e a busca por ela encontrou uma que já existia. ##### O canal já estava em produção, e isso poupou a decisão que travava tudo O registro anterior dizia que as duas candidatas naturais eram SMS e e-mail, e que as duas esbarravam em decisão sua. **Havia uma terceira, e ela já roda:** o resgate do programa de fidelidade manda um código de seis dígitos por WhatsApp (`ClienteService::programaFidelidadeResgatarPontuacaoGerarCodigo`), pela fila `push_app`, com as credenciais da unidade. A autenticação do cliente usa exatamente esse caminho. Nenhum canal novo, nenhuma decisão sua, nenhuma dependência do SMS que você excluiu. *E a cobertura de e-mail continua immensurável aqui, o que reforça a escolha:* a anonimização reescreve `clientes.email` para **todos** os clientes, incondicionalmente (`anonimizar.sql.modelo:53`). Localmente 100% têm e-mail e todos são únicos — nenhum desses dois números diz nada sobre a produção. ##### O sujeito da sessão é o TELEFONE, e não o cliente A tentação é amarrar a sessão a um `cliente_id`. Está errada por dois motivos, e o segundo é mais forte que o primeiro. O primeiro é medido: **5.670 telefones da base têm mais de um cliente ativo**, e o pior caso tem **354** (**D41**). Uma família compartilha o número, e o aplicativo sempre listou todos para a pessoa escolher. O segundo é de honestidade: um código entregue no WhatsApp prova **posse do número**, e nada além disso. Dizer que ele prova "sou o cliente 149612" seria afirmar mais do que se mediu. A sessão vale para os clientes daquele telefone porque é exatamente isso que o código demonstrou. ##### O que foi construído | | | |---|---| | `clientes_sessoes` | tabela nova, em `mysql.sql` e `postgres/schema.sql` | | `POST /api/v4/sessoes` | pede o código; **202 sempre** | | `POST /api/v4/sessoes/confirmacao` | troca o código pelo token; 201 ou 401 | | `GET /api/v4/clientes` | os clientes do telefone autenticado | | `GET /api/v4/clientes/:id/indicacoes` | só se o `:id` for daquele telefone | **Nada disso toca nas rotas congeladas.** Versão nova, endereços novos, os antigos vivos — é o passo 2 escrito neste débito desde 29/08. Os 46 testes de contrato passam, e os 37 que já existiam não mudaram uma linha. ##### As três decisões que sustentam a segurança disto **1. O endereço de pedir código não conta se o número existe.** Cadastrado e desconhecido recebem **a mesma resposta, byte a byte** — há teste que compara os dois corpos crus, e não a estrutura: `{"mensagem":"enviado"}` e `{"mensagem":"nao encontrado"}` têm estrutura idêntica e entregam tudo. Sem isso, este endereço seria um descobridor de clientes mais barato que a colheita que este débito registra: um bit por número, em vez de uma resposta inteira. **2. Seis dígitos só são defensáveis com teto.** São 10⁶ possibilidades, que sem limite se esgotam em minutos. Cinco tentativas erradas matam a sessão — e depois disso **nem o código certo passa**, que é o detalhe que faz o teto ser teto. Dez minutos de validade, uso único. **3. Nenhum dos dois segredos fica em claro.** O código é `password_hash`; o token é `sha256` de 32 bytes de `random_bytes`. Algoritmos diferentes de propósito: 10⁶ possibilidades precisam do custo do bcrypt, e 2²⁵⁶ não precisam — ali o bcrypt só impediria a busca por índice. ##### O que o `/api/v4` deixou para trás, de propósito **`cpf` e `rg` não vêm.** A contenção 2 deste débito discutia mascará-los na rota antiga, e esbarrava em não saber se alguma tela do aplicativo instalado os exibe. Aqui não há esse dilema — **este endereço não tem consumidor nenhum**. Acrescentar um campo depois é aditivo; removê-lo seria quebra. **Sem `Access-Control-Allow-Origin: *`.** Com `*` o navegador nem envia credencial; as duas coisas são mutuamente exclusivas. As 19 ações da classe antiga continuam com o cabeçalho aberto, e isso segue registrado abaixo. **Datas em ISO 8601 com fuso**, e não `dd/mm/aaaa hh:mm:ss` — regra 6 da convenção. Num aplicativo que roda no telefone de quem viaja, data sem fuso é data ambígua. ##### Onde a prova está, e por que em dois lugares - **`tests/Caracterizacao/AutenticacaoDoClienteTest.php`** — 12 testes, com `EntityManager` e a fila para ler. Prova o fluxo de **obter** o token: pedir código, ler da fila, confirmar, e o teto de tentativas. Inclui o que mais importa: a sessão alcança **todos** os clientes daquele telefone e **nenhum** de outro. - **`tests/Contrato/ApiV4Test.php`** — por HTTP, o que vem **depois** do token. *Snapshot de recusa não é preciosismo:* um endereço que devia responder 401 e passa a responder 200 continua parecendo saudável em qualquer medição que olhe só para "a API respondeu". ##### AS CARGAS ficaram sem congelamento por dois dias, e isso foi corrigido Ao criar o `/api/v4` eu escrevi que o caminho feliz **não podia** ser provado pela suíte de contrato — ela fala HTTP e não toca no banco, e o código de seis dígitos não aparece em resposta nenhuma. Era verdade sobre *obter* o token, e eu estendi a conclusão para o que vem depois dele. **O resultado é que seis rotas tiveram suas cargas provadas à mão, com `curl`, e mais nada.** Prova à mão não volta a rodar amanhã. A saída não foi dar banco à suíte nem abrir atalho na aplicação: a **sessão de cliente é criada na montagem do banco**, por `scripts/definir-senha-contrato.php`, exatamente como já era feito com a senha do gerente — e pelo mesmo motivo o token **não está versionado**. A suíte continua sem tocar no banco; ela só conhece o valor. As seis cargas estão congeladas desde 05/09/2026, e com elas duas asserções que snapshot nenhum daria: - **a lista tem DOIS clientes.** O snapshot congela tipo, e uma lista de um tem a mesma estrutura de uma lista de dois — a promessa "a sessão vale para a linha" não estaria verificada por ninguém. - **um id de outro telefone responde 403 com token válido.** Até então essa regra era provada pelo serviço e vigiada pelo portão; agora é exercitada pela porta. ##### O QUE FALTA PARA ISTO ENTRAR EM CAMPO, e é seu **1. O aplicativo novo.** Nada disto vale enquanto nenhum cliente falar `v4`. O passo 1 (a W3 — quais versões estão em uso, que sai do log do nginx) continua sendo o que destrava o resto. **2. Oito unidades sem WhatsApp ativo.** Medido em 03/09: das 34 unidades ativas, **26** têm `whatsapp_ativo`. Um cliente cuja unidade não tem canal **não consegue autenticar** — o código não é enfileirado, e a sessão nem nasce, porque uma linha ali seria promessa que ninguém cumpre. Ou se liga o WhatsApp nas oito, ou se decide um segundo canal para elas. **3. O par token de acesso + renovação não foi construído.** A convenção o recomenda; aqui há um token só, de 30 dias. Sem aplicativo em campo não havia o que exercitar, e a tabela tem espaço para o segundo. É acréscimo, não reforma. #### AS TRÊS ÚLTIMAS, FECHADAS no mesmo dia > *"ataque as três rotas restantes do D59"* `/api/cliente/agenda/:id`, `/api/cupons/selecionar/:id` e `/api/sorteios/selecionarCupons/:id` passaram a exigir sessão, e ganharam sucessor autenticado em `/api/v4/clientes/:id/{agenda,cupons,sorteios}` — com a mesma regra de propriedade: o `:id` só é aceito se pertencer ao telefone do token, e um id de outro telefone responde **403**. **A lista das quatro está encerrada.** Nenhuma rota da API do aplicativo aceita mais um inteiro sequencial como credencial. ##### A DA AGENDA ERA DE OUTRA NATUREZA, e a diferença não é de grau As outras expõem cadastro, cupom ou sorteio. Esta responde **onde uma pessoa vai estar, e quando**: data, hora, o colaborador que vai atendê-la e a unidade com estado, cidade e bairro. É localização futura de alguém, entregue a quem escrevesse um número inteiro na URL. Medido na cópia local em 03/09/2026: **77 pessoas** tinham agendamento futuro, somando 615 marcações, a mais distante em 2030. Na produção o número é outro; a forma é a mesma. *O registro anterior chamava as três de "menos graves que as duas já fechadas".* Para cupons e sorteios isso se sustenta. Para a agenda, não: dado de localização não é da mesma família que dado de cadastro. ##### A carga não mudou, e isso foi conferido Os três snapshots autenticados são **idênticos, byte a byte**, aos contratos que existiam antes — só a porta mudou. O que se comparou foi o arquivo antigo contra o novo, e não a impressão de que nada mudou. ##### O que o `/api/v4` corrigiu de passagem | | rota antiga | `/api/v4` | |---|---|---| | dinheiro | `"R$ 89,90"` | `"89.90"` — regra 7 | | data e hora | `24/12/2026 09:00:00` | ISO 8601 com fuso | | data sem hora | `31/12/2030` | `2030-12-31` | | endereço | uma string montada | campos separados | | relógio | `date()` no meio da consulta | lido uma vez, e daqui | *Validade de cupom e data de sorteio ficaram sem fuso, de propósito:* são **dias**, não instantes, e carimbar fuso neles inventaria uma precisão que o dado não tem. ##### UMA COLISÃO QUE SÓ O CENÁRIO DO CI PODIA ACUSAR As fixtures novas criaram uma venda com id `90001200` — e `AutorizacaoFiadoTest` cria a venda **dele** com esse mesmo id. Localmente a suíte de caracterização roda contra o banco de desenvolvimento, onde as fixtures **não** estão carregadas: a colisão era invisível aqui e certa no CI. Duas correções, e a segunda vale mais que a primeira: 1. **Uma faixa declarada.** `90001000–90001199` é das fixtures; de `90001200` para cima é dos testes, que inserem linhas próprias na transação revertida. O cenário novo mudou para `9000115x`, e a regra está escrita no `fixtures.sql`. 2. **`scripts/rodar-caracterizacao-como-ci.sh`.** Monta o mesmo banco que o CI monta — `mysql.sql` mais as fixtures, e nada mais — e roda a suíte contra ele. Foi ele que achou a colisão, depois de a execução normal passar 184 de 184. *Ele não substitui a execução normal:* contra fixtures, os testes que dependem do histórico da produção se declaram pulados, e são justamente os que a execução normal cobre. São dois cenários, e um defeito que aparece num não aparece no outro. #### E HAVIA UMA QUINTA, que esta lista nunca teve Encontrada em 03/09/2026, logo depois de fechar as quatro — ao varrer as ações que mandam `Access-Control-Allow-Origin: *`. `GET /api/agendas/getConsumoCliente?id=` devolvia, **sem cabeçalho nenhum**: CPF e RG, nome, telefone, e-mail, convênio o HISTÓRICO DE COMPRAS inteiro -- data, unidade, serviço, o colaborador que atendeu e o valor de cada venda a pontuação do programa de fidelidade É tudo o que o `getCliente` entregava, **mais** para onde a pessoa vai, com quem se atende e quanto gasta. Medido contra a aplicação de pé. ##### O D13 JÁ A LISTAVA, e eu não olhei antes de chamá-la de achado Antes de qualquer explicação: **isto não foi uma descoberta.** O **D13**, escrito em 16/08/2026, diz textualmente que *"`/api/cliente/agenda/:id` e `/api/agendas/getConsumoCliente` expõem dados de clientes por enumeração de id"*. Estava lá o tempo todo, com o nome da rota. O que aconteceu é que eu varri o código e reportei o resultado sem reler o débito que cobre a área. **É a segunda vez no mesmo dia** — a primeira foi o D89, que registrei como descoberta quando já era a oitava linha do D3. Nos dois casos foi um portão, e não eu, que corrigiu o registro. ##### POR QUE A LISTA DO D59 NÃO A TINHA, que é outra pergunta A lista *deste* débito foi montada a partir das rotas com **`:id` no caminho**. Esta recebe o id na **query string**. Forma diferente, mesmo defeito — o inventário procurava uma forma, não uma propriedade. *A varredura de agora foi por propriedade*, e não por forma: **toda ação que recebe um identificador de quem chama**. Deu nove, e o veredito de cada uma está medido: | | | |---|---| | já trancadas | 5 | | **a trancar** | **1** — `clienteConsumoSelecionar` | | catálogo público (unidade, serviços) | 3 | `agendaSelecionar` merecia o exame e passou: recebe id de **colaborador**, não de cliente, e com `$app = true` devolve **só os horários livres** — sem nome, sem telefone. Grade de disponibilidade não é dado de pessoa. ##### O que foi feito A rota exige sessão, e ganhou sucessor em `GET /api/v4/clientes/:id/consumo`, com a mesma barreira das outras quatro. **`cpf` e `rg` não vão na carga nova**: uma tela de histórico não precisa do documento de quem já está autenticado. A carga autenticada da rota antiga é **idêntica, byte a byte**, ao contrato que existia — conferido, e não presumido. ##### Um teste que passou a provar outra coisa `testClienteConsumoSemDados` congelava a resposta de um POST sem parâmetro. Agora a recusa acontece **antes** de olhar parâmetro nenhum, então o corpo é o mesmo do `-sem-autenticacao`. O que ele ainda prova não é nada: **a recusa não depende do verbo** — um guarda posto só no ramo do GET deixaria o POST passar. Fica registrado no próprio teste, que é onde quem o lê está olhando. #### O CORS: DECIDIDO ação por ação, em 03/09/2026 O registro tratava as vinte ações como um bloco — *"o CORS aberto nas outras 18"*. Olhadas uma a uma, elas são três grupos com vereditos diferentes, e o raciocínio que separa os grupos corrige uma frase deste próprio débito. **O que `Access-Control-Allow-Origin: *` faz, com precisão:** ele diz ao navegador que qualquer origem pode **ler a resposta**. Ele **não** decide se o pedido é enviado. Um POST de formulário é "requisição simples": o navegador manda de qualquer jeito, e o CORS só esconde a resposta do script. Isso importa porque a frase que este débito repetia — *"com `*`, qualquer página lia a resposta entre origens"* — é verdadeira para **leitura**. Para **escrita**, o risco não é ler. ##### Grupo 1 — as nove autenticadas: o cabeçalho SAIU `*` e credencial são mutuamente exclusivos: o navegador se recusa a mandar cookie para uma resposta que diz `*`. Manter os dois era anunciar "qualquer um pode ler" ao lado de um guarda que exige sessão. Não quebra nada: um chamador de navegador já estava impedido, e o aplicativo nativo não olha CORS. ##### Grupo 2 — as sete de catálogo: o cabeçalho FICA `unidades`, `unidade`, `unidadeV2`, `servicos`, `banners`, `paises`, `versao` e a grade de horários livres devolvem dado público — é exatamente para isso que `*` existe. Tirá-lo não protegeria nada e quebraria qualquer página que consulte unidades. ##### Grupo 3 — as duas escritas abertas: CORS não era a pergunta `POST /api/clientes/novo` cria linha na tabela de 243 mil clientes. `POST /api/clientes/sac` dispara e-mail para a unidade. As duas **não podem** exigir credencial — quem se cadastra ainda não é cliente, e o SAC é formulário de contato. Tirar o `*` delas seria teatro, pelo motivo acima: o navegador manda o POST assim mesmo. **O que faltava não era CORS, era teto de taxa** — e não havia nenhum. **Contenção aplicada**, mesmo desenho do `getCliente`: zona `escrita_publica`, 10 por minuto por endereço, `burst=5 nodelay`, `429` na recusa. Não muda resposta nenhuma, então não toca no contrato. *Posto à prova:* 30 POSTs em paralelo no cadastro — **6 atendidos, 24 recusados**. Um pedido isolado logo depois: 200. E a ressalva de sempre continua sendo o **CGNAT** — o teto encurta a janela, não fecha a porta. #### O que continua aberto neste débito Nada da lista original. O que ficou é trabalho de construção, registrado no **D91**: os sucessores autenticados de *marcar* e *indicar*, que dependem de reescrever regra de negócio de verdade na superfície nova. #### CONTENÇÃO 2 — mascarar `cpf` e `rg`: superada pela decisão acima *Ficou sem efeito prático para esta rota*: quem não se autentica não recebe resposta nenhuma, mascarada ou não. Ela volta a fazer sentido se um dia a rota precisar responder a um cliente autenticado com menos do que responde a um operador — que é uma pergunta para quando a metade do cliente existir. O que estava medido a favor dela, e continua valendo como registro: Não apliquei, e o motivo é que ela muda o que o aplicativo instalado recebe. **O que está medido a favor:** o snapshot de contrato registra `"cpf": "string"` e `"rg": "string"` — **tipo, não valor**. A suíte não acusaria, e nenhum aplicativo que apenas repassa o campo quebra. **O que não dá para medir aqui:** se alguma tela do aplicativo exibe o CPF inteiro. Isso exige olhar o aplicativo, e ele não está neste repositório. **Um argumento a favor que não estava escrito:** máscara parcial preserva a função que o campo tem nesse fluxo. Quando várias pessoas dividem o telefone — e são 5.670 números —, a tela precisa que o cliente se reconheça na lista; alguns dígitos bastam para isso, e o documento completo não é necessário para escolher. **Também não dá para medir aqui quantos clientes reais têm CPF e RG preenchidos:** a anonimização gera CPF para todos e zera o RG (`anonimizar.sql.modelo`, linhas 47 e 48). Qualquer contagem local seria artefato — a mesma razão pela qual `medir-senhas-producao.sql` existe. #### O APARELHO DO PUSH, em 10/10/2026 — mais uma sub-rota de `:id`, e a primeira para o aplicativo novo `POST` e `DELETE /api/v4/clientes/:id/aparelhos` (PUSH-FCM-APARELHOS, **D461**): o aplicativo novo registra e retira o aparelho do Firebase com a sessão deste débito, e o `:id` passa pela mesma `barreira()` (401 sem token, 403 para o id de outro telefone). O aparelho vai para o cliente da rota, e não para todos do telefone. **E o aparelho segue a regra deste débito no tempo** (achado da verificação, 10/10/2026): a sessão alcança o cliente só enquanto o telefone dele for o dela, e o aparelho só recebe o push do cliente enquanto o telefone dele for o da sessão que o registrou (a linha o guarda). O telefone errado que a unidade corrige deixava o aparelho de quem tinha o número com o push do cliente para sempre — o `DELETE` dele já é 403 depois da correção. Não muda o estado deste débito: as rotas congeladas continuam abertas até o aplicativo novo, e **o aplicativo instalado não tem este login** -- a pergunta de adotá-lo no aplicativo novo, com a recomendação (sim), está no lote. Nada de rota sem autenticação para o aparelho: com o id valendo como credencial, qualquer um poria o próprio aparelho no lugar do de outra pessoa. #### A RENOVAÇÃO DA SESSÃO V4, em 11/10/2026 (PUSH-TERCEIRA-RODADA: a resposta 71 do dono) **Decidido pelo dono** (a resposta 71, a opção (a)): o aplicativo novo adota o login V4. O que era o item 3 de "O que falta para isto entrar em campo" -- "o par token de acesso + renovação não foi construído" -- ficou assim, **no molde da V4 que existe e sem tabela nova**: `POST /api/v4/sessoes/renovacao`, com o `Authorization: Bearer` de agora e sem corpo, troca o token que ainda vale por um novo, de mais 30 dias **a partir do pedido**, e devolve 201 com a forma da confirmação (`token`, `tipo`, `expiraEmDias`). O de antes morre na troca: é a mesma linha de `clientes_sessoes`, com o `token_hash` e o `token_expira_em` novos, e o telefone, a confirmação e o teto de tentativas como estavam. Sem token, sem o prefixo `Bearer`, noutro esquema, com o vencido, o encerrado ou o inventado: 401 mudo, como em toda a V4. **A troca é uma conta condicionada no banco** (`ClienteSessaoRepository::trocarToken`: o `UPDATE` só acha a linha com o hash de antes, não encerrada e não vencida): dois pedidos com o mesmo token renovam uma vez só, e o que perde recebe 401 -- regravar a entidade lida daria um token aos dois, e só o último gravado valeria. O aplicativo instalado não muda: ele não fala V4. O guia (`docs/push-guia-do-aplicativo.md`, "O login") diz quando renovar e o que fazer com a resposta perdida (o token de antes já não vale: o caminho é o login). **Provado** no `RenovacaoDaSessaoTest` (9 casos, nos dois bancos): o token que vale renova, o novo abre a mesma sessão e os mesmos dois clientes do telefone, e o de antes não abre mais; a validade conta do pedido (renovada no 20º dia, vale no 45º e vence no 51º); o vencido, o encerrado, o inventado, o vazio e o ausente não renovam, e a linha fica como estava; dois pedidos com o mesmo token trocam uma vez só, pelo repositório e pelo serviço que perde a corrida; a troca não alcança a vencida nem a encerrada; e a rota, pela fábrica e pela entrada do ERP (`api-v4-sessoes/renovacao/ renovar`), 201 com o token novo e 401 para o de antes, já trocado, e para as cinco credenciais que não valem. No `ApiV4Test`, pela porta HTTP: o 401 sem token (o snapshot `v4-sessoes-renovar-sem-autenticacao`), o token inventado e o da suíte sem o `Bearer` ou noutro esquema, e o GET que não casa rota; a carga não, porque trocaria o token de que as outras cargas dependem. Os mutantes e os portões estão no roadmap de 11/10/2026. **O que segue, e é do dono** (as perguntas estão no lote, PUSH-TERCEIRA-RODADA): **as unidades sem WhatsApp**, que não mandam o código -- medido na cópia em 11/10/2026, **6 das 32 unidades ativas** (ids 22, 25, 32, 58, 60 e 61), com 18.735 clientes ativos; o "oito" de 03/09 contava as duas unidades de fixture sem WhatsApp, e se as 26 restantes têm a chave preenchida a cópia não diz (o anonimizador apaga as chaves). As rotas congeladas seguem abertas até o aplicativo novo, como antes. **O prazo máximo da sessão renovada, decidido pelo dono** (a pergunta 148, respondida em 11/10/2026, às 14:39, com a opção (a), *"Sem prazo máximo, como está"*): **a sessão renovada fica sem prazo máximo, por decisão dele.** Ela renova sem fim, 30 dias a partir de cada pedido, como o `RenovacaoDaSessaoTest` prova; o código não mudou. O que essa escolha aceita, e foi dito na pergunta: o número que a operadora repassa a outra pessoa mantém o aparelho antigo, que segue renovando, alcançando os clientes daquele telefone -- inclusive o da pessoa nova, se ela se cadastrar com ele. Se um dia o prazo vier, ele sai da `confirmado_em`, sem mudar a tabela. #### O CÓDIGO PELO WHATSAPP CENTRAL DA FRANQUEADORA, em 12/10/2026 (o item WHATSAPP-F0-E-CENTRAL: a resposta 147 do dono) **Decidido pelo dono** (a pergunta 147, "as unidades sem WhatsApp não mandam o código de entrada do aplicativo novo", respondida sem opção, com a observação): *"Para o envio de codigo, utilizar um WhatsApp centralizado, da franqueadora e nao da unidade"*. **Só o código de entrada muda de canal:** o código do resgate, o parabéns, o aviso e as campanhas seguem pelo WhatsApp da unidade. - **A franqueadora não é uma unidade** no banco: na cópia, nenhuma unidade marcada nem com nome de franqueadora, matriz ou escritório, e a 1 é uma barbearia como as outras; no código ela aparece como configuração (o destino do SAC é uma constante). Por isso **a credencial central mora na configuração do ambiente**, como as outras chaves: o `whatsapp.central` do `config/autoload/local.php` (o provedor, a instância e a chave), que não é versionado. O `local.php.dist` traz o bloco vazio e o passo; o `scripts/verificar-local-php.php` o lista como GRAVE. - **`ClienteAutenticacaoService::pedirCodigo`** cria a sessão e enfileira o código quando o telefone é de um cliente ativo (não o "SEM CADASTRO") e o central está pronto (`ISBase\Util\WhatsAppCentral::daConfiguracao`: a instância e a chave preenchidas, só de espaços contando como vazia, e o provedor `evolution` ou `waha`). A unidade do cliente não decide mais: **o cliente de unidade sem WhatsApp passa a receber o código.** Sem o central, nenhum código sai e nenhuma sessão nasce -- a mesma regra de antes para "sem canal". A resposta continua 202 nos dois casos (o D59 não conta se o número existe). - **A chave não vai para a fila:** a linha leva o provedor `central` e a chave e a instância vazias, e `CronJobService::marketingPush` lê a credencial do `local.php` na hora do envio. Sem ela, a linha falha e fica na fila marcada (o D302). **Provado** no `AutenticacaoDoClienteTest` (13 casos, nos dois bancos; o serviço montado com um central inventado) e no `WhatsAppQueFalhaTest`: a linha do código com o provedor `central` e sem chave nem instância; o central vazio, só de espaços ou de provedor desconhecido, sem sessão e sem linha; o cliente de unidade sem WhatsApp com sessão; a rotina da fila mandando a linha do central com a credencial da configuração, e a da unidade com a dela; e, sem o central, a linha dele marcada como falha, sem envio. No `SegredosForaDoCodigoTest`, o verificador do `local.php` com as duas chaves do central como GRAVE, e sem imprimir o valor. Seis mutantes, um de cada vez, vermelhos (a tabela no roadmap de 12/10/2026). **O que é do dono, e não foi decidido aqui:** qual número e qual credencial. Para ligar: criar (ou escolher) a instância da franqueadora no provedor -- o Evolution ou o WAHA, os das unidades --, conectar nela o telefone da franqueadora, e preencher os três valores no `local.php` da produção (o passo está no `local.php.dist`). Até lá, o login V4 não manda código a ninguém -- o aplicativo instalado não usa o login V4, e as rotas congeladas seguem abertas até o aplicativo novo, como antes. No servidor de teste, o passo 9.1 de `docs/ambiente-teste.md` (a resposta 149) passou a pôr um central de mentira no `local.php` do teste, no lugar de ligar o WhatsApp de uma unidade. **A verificação do item (12/10/2026)** achou e consertou duas coisas. **O provedor em maiúsculas:** o formulário de Unidades rotula a opção como "WAHA", e `'provedor' => 'WAHA'` no `local.php` dava o central como não configurado -- o login V4 parava de mandar código em silêncio, com o `verificar-local-php.php` dizendo `ok` nas duas chaves. Agora `WhatsAppCentral::daConfiguracao` tira a caixa e os espaços do provedor, e o verificador ganhou a linha `whatsapp.central.provedor`: com a instância e a chave preenchidas, o provedor que nenhum cliente conhece sai GRAVE (pela mesma classe, e não por uma cópia da conta; o recusado não é impresso). **Cada metade sozinha:** os casos tinham as duas vazias juntas, e cada checagem saía sem vermelho; o `testSemOWhatsAppCentralNaoHaSessaoNemMensagem` mede agora só a instância vazia e só a chave vazia. Casos novos: `AutenticacaoDoClienteTest::testOProvedorDoCentralEmMaiusculasValeComoOMinusculo` (o " WAHA " cria a sessão), `WhatsAppQueFalhaTest::testOCentralComOProvedorEmMaiusculasSaiPeloWaha` (a linha sai pelo cliente do WAHA) e `SegredosForaDoCodigoTest::testOVerificadorRecusaOProvedorDoCentralQueNinguemConhece`; quatro mutantes, um de cada vez, vermelhos (a tabela no roadmap). **Qual número e qual credencial** foi ao lote como pergunta (WHATSAPP-F0-E-CENTRAL, a verificação): até a resposta, a configuração fica vazia, e o login V4 não manda código a ninguém -- nem aos clientes das 26 unidades que recebiam pelo WhatsApp da própria unidade. #### PARCIAL em 14/10/2026 -- o número central (a resposta 169; o item WHATSAPP-E-APLICATIVO) **Decidido pelo dono em 14/10/2026** (a pergunta 169 da página do lote, a opção (a), a recomendada): *"Um número novo da franqueadora, só para os códigos -- numa instância nova no provedor, conectada a um aparelho da franqueadora; o passo de preencher está escrito no modelo da configuração."* Registrado, sem código. **Conferido o passo, e faltava uma metade.** O `local.php.dist` traz o bloco `whatsapp.central` vazio e o passo desde 12/10/2026, e o `scripts/verificar-local-php.php` lista a instância e a chave como GRAVE. **O corte não o levava:** o passo 7 de `docs/procedimento-de-corte.md` troca o `local.php` pelo `local.postgres.php.dist`, que não tinha o bloco, e a lista do que levar do `local.mysql.php.guardado` tinha só a chave do Asaas e o token das rotinas. Quem preenchesse o central antes do corte o perderia no passo 7, e o login V4 voltaria a não mandar código a ninguém, com o verificador dizendo GRAVE numa lista que "não reprova". Agora: - o `config/autoload/local.postgres.php.dist` traz o bloco vazio, com o passo (o número novo da 169, a instância nova, de onde vêm os valores no corte); o `rodar-caracterizacao-postgres.sh`, que monta o `local.php` dos testes dele, passou verde com o bloco; - o passo 7 do procedimento ganhou a terceira entrada, `whatsapp.central` -- do guardado, se a instância já estiver conectada e preenchida; senão, da instância nova, depois --, e a conferência do `verificar-local-php.php` fala das três. Nenhum valor real em lugar nenhum: os três campos estão vazios nos dois modelos, e o procedimento não traz número nem chave. **O que resta (por isso PARCIAL), do dono:** mandar criar a instância nova no provedor (o Evolution ou o WAHA, os das unidades), conectar nela o aparelho da franqueadora, e os três valores no `local.php` da produção. Até lá, o login V4 não manda código a ninguém -- e o aplicativo instalado não sente: ele não usa o login V4. #### ANOTADO em 14/10/2026 — as seis leituras reabertas ao aplicativo instalado, pela resposta 189 (b) do dono > *"A etapa 1 sobe com as dez rotas abertas ao aplicativo de hoje: como estão hoje na produção, e elas fecham quando o > aplicativo novo estiver em campo. A exposição fica a de hoje, nem maior nem menor."* **A exposição deste débito volta, por decisão do dono, até o aplicativo novo estar em campo.** As seis leituras — `/api/agendas/getCliente` (o telefone que devolve o CPF e o RG de até 354 pessoas), `/api/cliente/indicacoes/:id` (o telefone de terceiros), `/api/cliente/agenda/:id` (onde a pessoa vai estar), `/api/cupons/selecionar/:id`, `/api/sorteios/selecionarCupons/:id` e `/api/agendas/getConsumoCliente` (o histórico de compras) — respondem de novo sem sessão, com o `Access-Control-Allow-Origin: *` de julho, como a produção de hoje. A contenção 1 (o teto de taxa do `getCliente` no nginx) não muda. O interruptor, o que fecha de novo e o provado estão no **D91** ("ANOTADO em 14/10/2026"): é a mesma constante para as dez, `AplicativoController::ROTAS_DO_APLICATIVO_INSTALADO`. **Fecha quando o aplicativo novo, que fala o `/api/v4`, estiver em campo** — o passo 2 deste débito —, trocando a constante para `fechadas`: o 401 volta, o cabeçalho sai, e a suíte de contrato passa a conferir os `-sem-autenticacao`, guardados. Quantos pedidos por dia as dez recebem (o número que diz quantos clientes o fechar atinge) é a leitura 19 do procedimento da etapa 1, na produção. O que fica diferente de julho nas dez, e o que fica igual e pode surpreender (o colaborador da unidade inativa no marcar, a data que não existe, o corpo do V3 em disco), está no D91. --- ### D60 — A integração fiscal por unidade manda o segredo na query string Registrado em 29/08/2026, ao fechar a última lacuna da suíte de contrato. `/api/unidade/vendas`, `vendasV2` e `vendasV3` são a **única parte da API que autentica**: exigem um `hash` que bata com o da unidade. É uma boa notícia no meio do D59 — mas o segredo viaja onde não devia. ``` GET /api/unidade/vendas?id=7&hash=&inicio=...&fim=... ``` **O hash é a credencial, e a credencial vai na URL.** Isso significa que ela é gravada em texto claro no log de acesso do nginx, de toda requisição, para sempre — e o log é rotacionado, copiado, e às vezes enviado para fora. Também entra em `Referer`, em histórico de proxy e em qualquer captura de tráfego que registre a linha de requisição. É o mesmo defeito de forma do D59, que expõe telefone na query, com uma diferença: **aqui o que vaza não é dado de uma pessoa, é a chave que abre o faturamento de uma unidade inteira**. **O que essa chave abre**, medido pela resposta dos três endpoints: número da nota, data e hora, valor bruto e líquido, forma de pagamento, itens vendidos, colaborador, e — no `vendasV3` — nome, telefone, CEP, endereço e data de nascimento dos clientes. **O que já melhorou:** os três ganharam teste de contrato em 29/08 e a checagem do hash ganhou uma asserção própria (`testUnidadeVendasRecusaHashErrado`). Antes, afrouxar a verificação não faria teste nenhum acusar. **A correção, quando houver janela:** o segredo passa a viajar em cabeçalho (`Authorization`), não em query. É mudança de contrato e portanto precisa ser combinada com quem consome — o que exige, primeiro, **descobrir quem consome**. As três versões coexistindo sugerem mais de um consumidor, e `scripts/inventariar-versoes-app.php` responde isso a partir do log: mostra quais das três estão vivas e com que frequência. Enquanto isso não vem, vale saber que **rotacionar o hash de uma unidade é barato** — é uma coluna — e que qualquer suspeita de vazamento de log se resolve com uma rotação. --- ### D61 — Seis endpoints que mudam estado só têm contrato do caso vazio — OS SEIS COBERTOS em 11/09/2026, com resíduo medido ZERO — PARCIAL em 06/10/2026 — PARCIAL em 08/11/2026: os 22 roteiros que entram no ERP devolvem o login; ficam o fechamento da agenda e a variante do DDI Registrado em 29/08/2026, ao varrer os snapshots atrás do defeito que o D55 tinha ensinado a procurar. **A varredura foi feita e a maior parte já está fechada.** Dez snapshots terminavam em `-sem-dados` sem par: o formato que o aplicativo realmente interpreta não estava congelado em lugar nenhum. Três eram de leitura e ganharam o caso com dados no mesmo dia — `cliente-selecionar`, `cliente-consumo` e `agenda-selecionar-v2`. Este débito é o que sobrou, e sobrou por um motivo que vale escrever. | Endpoint | O que faz | |---|---| | `/api/agendas/cancelar` | desmarca um agendamento | | `/api/v2/agendas/agendar` | cria agendamento | | `/api/v3/agendas/agendar` | cria agendamento | | `/api/clientes/novo` | cadastra cliente | | `/api/cliente/indicacao` | registra indicação | | `/api/clientes/sac` | abre chamado de SAC | > **QUATRO DOS SEIS MUDARAM DE PORTA em 03 e 04/09/2026.** `cancelar`, as duas > versões de `agendar` e `indicacao` passaram a exigir sessão (**D91**), e seus > snapshots foram renomeados de `-sem-dados` para `-sem-autenticacao` — porque o > corpo vazio passou a ser recusa, e não falta de dado. > > *Isso não resolve este débito, e vale dizer por quê.* A suíte ganhou login > (`getAutenticado()`), então a barreira deixou de ser "não sabe autenticar" e > passou a ser só a outra — cobrir o caso com dados continua significando > **escrever no banco**. A decisão abaixo continua inteira. > > Os outros dois — `clientes/novo` e `clientes/sac` — continuam abertos por > desenho: quem se cadastra ainda não é cliente. Eles ganharam teto de taxa no > nginx (**D59**), que não é cobertura de contrato. **Os seis mudam estado, e é isso que os torna diferentes.** Cobrir o caso com dados significa a suíte de contrato passar a **escrever no banco** — e aí ela deixa de ser repetível: rodar duas vezes seguidas sem recriar o banco daria resultados diferentes na segunda. Não é impeditivo, e há caminho: o CI monta o banco do zero a cada execução, e localmente `scripts/montar-banco-contrato.sh` faz o mesmo em um comando. Mas **muda o que a suíte é** — de "leitura que confere formato" para "roteiro que exige banco limpo" — e isso merece decisão, não uma escolha minha no meio de outra tarefa. **O que está em jogo, dos dois lados:** *A favor de cobrir:* é exatamente onde a quebra dói mais. Um cliente que não consegue agendar pelo aplicativo é pior que uma tela de consumo com formato estranho, e a Fase 2 vai mexer nesses endpoints. *Contra:* uma suíte que exige preparação é uma suíte que alguém vai rodar sem a preparação, ver falhar, e aprender a ignorar. Suíte que se ignora não protege nada — é a mesma lição do D55 por outro caminho. **~~Uma terceira via, se a decisão for difícil:~~ cobrir só `cancelar`, que muda estado de forma reversível.** — **ESTA FRASE ESTAVA ERRADA, e o erro era meu.** #### A correção, medida em 31/08/2026 `cancelar` **não** muda estado de forma reversível. `AgendaService::desmarcar` arquiva a linha e depois a **apaga**: ```php $horariosFilhos = $repo->selecionarHorariosFilhos($idPai); // casa `age.id = :idPai` foreach ($horariosFilhos as $horarioFilho) { $this->arquivarAgendaExclusao($horarioFilho, ...); $this->em->remove($horarioFilho); $this->em->flush(); } return true; ``` Escrevi "reversível" sem ter lido o serviço. O efeito prático desmonta a terceira via inteira: numa segunda execução sem recriar o banco, a agenda não existe mais, `AplicativoController::agendaDesmarcarAction` cai em `empty($agenda)` e devolve `{sucesso: false, mensagem: "ID inválido."}` — e o teste falha. **Ou seja: cobrir o `cancelar` também transforma a suíte em "roteiro que exige banco limpo".** Era exatamente o custo que a terceira via prometia evitar. #### DECIDIDO em 11/09/2026 — e a premissa que eu ofereci estava errada > *"Cobrir com restauração"* Eu levei a decisão ao dono com um argumento novo: os ensaios provaram o padrão de **restaurar-o-que-escreveu**, então a suíte de contrato poderia cobrir os seis e continuar repetível. **A premissa era minha e estava errada**, e o código a desmentiu em uma linha: ```php abstract class ContratoTestCase extends TestCase ``` PHPUnit puro. A suíte **não tem conexão com o banco**, por desenho — até a conferência de *"o banco de fixtures está no lugar"* é feita por HTTP, chamando `/api/agendas/getUnidades` e olhando o JSON. Restaurar exige ler e escrever no banco. Dar conexão àquela suíte muda o que ela **é** — que é precisamente a decisão que este débito queria evitar tomar de passagem. #### A via que existe, e que é melhor que as duas originais A cobertura foi para um **ensaio**: `scripts/ensaiar-escritas-do-aplicativo.php`. Lá o padrão já mora, e há uma razão que não era visível quando o débito foi escrito: **No PostgreSQL, a declaração de inquilino vem de graça num ensaio.** `agendas` e `agendas_exclusoes` têm `FORCE ROW LEVEL SECURITY` com política que compara `inquilino_id` com `current_setting('app.inquilino_id')` (`postgres/schema.sql:1766-1778`), e a aplicação conecta como `bvip_app` — papel comum, RLS em vigor. Numa conexão que não declara inquilino, **toda consulta volta vazia: sem erro, sem aviso, sem exceção** — o próprio `ISBase\Doctrine\DeclararInquilino:14-20` diz isso em voz alta. Um teste que abrisse conexão crua para ler *"o que havia antes"* leria **zero linhas** e restauraria **nada**, em silêncio. E seria **invisível no CI**: o job de PostgreSQL conecta como o dono do banco, que ignora RLS, e o job diz que isso é deliberado. Verde no CI e inútil na máquina de quem desenvolve é pior que vermelho nos dois. No ensaio a conexão vem de `Application::init()`, e `DeclararInquilino` é ouvinte de `postConnect`: a GUC é ajustada sem ninguém pedir. #### O primeiro dos seis, e o que ele afirma `POST /api/agendas/cancelar`. Três afirmações, como as recusas do D170 — o código HTTP, **as chaves exatas** do corpo, e o **efeito no banco**: | afirmação | por que ela e não outra | |---|---| | HTTP 200 | — | | corpo é exatamente `{sucesso}` | o erro devolve `{sucesso, mensagem}`; *"contém sucesso"* não distinguiria os dois, e é o primeiro que o aplicativo recebe | | nenhuma linha de agenda em pé | `desmarcar()` devolve `true` **mesmo quando o laço não roda** — agenda com `status = 0` não casa `selecionarHorariosFilhos` | | arquivou tantas quantas apagou | uma implementação que apagasse sem arquivar perderia o rastro e responderia o mesmo `{sucesso:true}` | Escreve em **três** tabelas, e devolve as três pelo valor lido antes: `agendas` (re-`INSERT` das linhas lidas), `agendas_exclusoes` (ancorado no `MAX(id)` lido antes — as fixtures **nunca** limpam essa tabela) e `clientes.ultimo_acesso_app`. **Medido:** resíduo **ZERO**, e **três execuções seguidas sem remontar o banco** passam igual — que era a objeção original deste débito, respondida com número. **Falsificado nas duas pontas:** desligada a restauração, a primeira execução acusa *"agendas: voltaram 0 de 1 linhas"*, e a segunda é **barrada antes de medir** — *"a agenda não está no cenário"*. A segunda rede recusa medir o vazio em vez de dar falso verde. #### O segundo: `POST /api/cliente/indicacao` Este cria **duas** linhas — um cliente (o convidado) e a indicação que liga indicador e convidado —, e as duas se referenciam **cruzado**: `clientes.indicacao` aponta para a indicação, `indicacoes.convidado` aponta para o cliente. A ordem da remoção não é preferência. O sucesso devolve `{sucesso, indicacao_id, url}`; a recusa devolve `{sucesso, mensagem}`. Muda o status **e** todos os campos menos `sucesso` — e o snapshot que existia congelava só a segunda forma. Quatro afirmações, e as duas últimas são as que distinguem *"respondeu"* de *"fez"*: | afirmação | por que ela | |---|---| | HTTP 200, corpo exatamente `{indicacao_id, sucesso, url}` | — | | o cliente convidado existe | — | | a `url` do convite aponta para **esse** convidado | uma url montada com o id errado manda o convite para outra pessoa | | `clientes.indicacao` aponta de volta para a indicação | sem a ligação de volta, a indicação existe e não rende nada ao indicador — e o endpoint responde o mesmo `{sucesso:true}` | **O mesmo método de serviço atende a rota nova** `POST /api/v4/clientes/:id/indicacoes`: dois controladores, um escritor. O que se congela aqui vale para os dois. #### Duas coisas que o vermelho da primeira execução ensinou **1. A coluna não guarda o que o serviço monta.** O serviço compõe `'+' . $ddi . ' ' . $telefoneLimpo` — com espaço — e passa ao setter. Mas `Cliente::setTelefoneSemMascara()` aplica `removerMascaraTelefone()` **de novo**, e o espaço cai: a coluna guarda `+5547988880001`. Minha busca procurava a grafia com espaço e não achava o cliente que o endpoint acabara de criar — o ensaio ficou vermelho dizendo *"respondeu sucesso e não criou o cliente"*, que era falso. A asserção estava certa em existir; quem estava errado era eu. **2. E isso tem consequência fora do ensaio.** A checagem de duplicata do próprio serviço prova **duas** grafias (`AplicativoService:262-265`), e a coluna só tem uma — a variante com espaço **nunca** casa, porque nunca esteve lá. Não é defeito de resultado: a segunda variante pega a forma real. É um pedido por chamada que não pode achar nada, e uma linha que faz quem lê concluir que as duas grafias são conferidas. **A cascata também apareceu:** `FFK_INDICACOES_convidado` é `ON DELETE CASCADE` (`mysql.sql:854`), então apagar o convidado leva a indicação junto. O `DELETE` explícito da indicação ficou assim mesmo — depender da cascata seria depender de o passo seguinte dar certo, e se o cliente não for encontrado a indicação ficaria órfã apontando para uma linha que existe. **Medido:** resíduo **ZERO** nas cinco tabelas, e três execuções seguidas sem remontar o banco. #### O terceiro: `POST /api/clientes/novo` **Este não exige sessão, e é por desenho:** quem se cadastra ainda não é cliente. O que o protege é teto de taxa no nginx — e é o **mesmo balde** do `/api/clientes/sac`. O ensaio gasta um crédito por execução. A forma do sucesso é a mais traiçoeira dos três: **`mensagem` vem no sucesso**, vazia. A ação a atribui sempre, e o validador devolve string vazia quando tudo passa. Então: | | corpo | |---|---| | sucesso | `{id, mensagem, sucesso}` | | recusa | `{mensagem, sucesso}` | A diferença é **uma chave**. Afirmar *"tem `sucesso`"* não distinguiria os dois — e o snapshot que existe congela só a recusa. Além das chaves, o caso afirma que o `id` é **inteiro de verdade** e não texto — o snapshot de estrutura não distingue inteiro de decimal, mas distingue de `string` —, que a linha existe, que o e-mail foi para minúsculo e que a unidade gravada é a do corpo. **O e-mail em minúsculo não é detalhe.** A consulta de duplicidade compara o valor **cru** do pedido, e a entidade grava `strtolower()`: com maiúscula a guarda nunca casaria, e um resíduo deixado para trás não bloquearia a execução seguinte — ela criaria a **segunda** linha em silêncio. **O contador de `AUTO_INCREMENT` não volta**, e é deliberado: rebobiná-lo faria o próximo `INSERT` pedir um id que pode já ter sido entregue, trocando um resíduo inofensivo por colisão de chave primária — o defeito que `postgres/repontar-sequencias.sql` existe para impedir. **Falsificado nas duas pontas**, com os códigos de saída: desligada a remoção, a primeira execução sai com **1** e acusa *"sobrou 1 cadastro"*; a segunda sai com **2**, barrada antes de medir — *"o e-mail ou o telefone já existem neste banco"*. #### O quarto e o quinto: marcar, v2 e v3 — e elas não são a mesma rota A v3 **não é um salto de versão**: é outro contrato dos dois lados. | | entra | sai | |---|---|---| | v2 | form-urlencoded | `{id, mensagem, sucesso}` | | v3 | **JSON cru**, tudo dentro de um nó `query` | `{id, sucesso}` — **sem `mensagem`** | As duas chamam o **mesmo** `agendaSalvarV2` por dentro. Um aplicativo que lesse `mensagem` da resposta da v3 leria nulo sempre — e é o tipo de diferença que só aparece quando alguém congela a forma do **sucesso**, que é o que o D61 pedia. São **três** leituras de corpo entre as rotas cobertas: a v2 lê `getPost()`, a v3 lê o conteúdo cru, e a indicação aceita as duas. Não dá para ter um `pedir()` só, e mandar o formato errado faz o ensaio medir *"JSON inválido"* achando que mediu o agendamento. **A data é lida por posição de caractere**, não por separador: `dataHoraBr_to_dateTime()` toma 0-1 como dia, 3-4 como mês e 6-9 como ano. ISO (`2030-06-15`) vira dia 20, mês 30 — data inválida, e sem dizer por quê. **E a v3 escreve fora do banco:** `logarJsonRecebido` grava `data/logs/agenda_json/json_.log` com o corpo recebido, **antes** de validar qualquer coisa. Nenhum `finally` de SQL o alcança, e a suíte de contrato não teria como limpá-lo — ela fala só HTTP. O ensaio roda dentro do contêiner e limpa por **diferença** da listagem tirada antes; apagar o diretório seria trocar o resíduo por perda de rastro alheio. #### E o resíduo que eu não estava contando `autenticar()` grava `usuarios.token_web` e insere uma linha em `usuarios_acessos`, e o `fixtures.sql` não limpa nenhuma das duas. Até aqui este ensaio dizia *"resíduo ZERO"* contando só as tabelas dos casos: o número estava certo para o que media, e a frase dava a entender mais do que media. Agora conta as duas, e o rótulo diz o que abrange — **sete tabelas e o diretório de log**. Os ensaios irmãos continuam deixando o deles: `ensaiar-recusas-adm-api` e `ensaiar-fluxo-adm-api` também entram no ERP, e consertar aqui não conserta lá. **Falsificado:** desligadas a remoção por faixa e a limpeza do log, a execução acusa *"agendas: sobraram 2 linha(s)"* e *"agenda_json: sobraram 1 arquivo(s)"*, e sai com 1. #### Faltava um, e ele estava quebrado — consertado em 11/09/2026 O **SAC** não tinha como ser coberto: ele respondia **500** por um template trocado, e nunca funcionou. Ver o **D172** — foi esta cobertura que o encontrou. Em 11/09/2026 ele foi consertado, por decisão sua sobre o destinatário, e passou a responder `HTTP 200` com `{"sucesso":true}` entregando o e-mail à franqueadora — provado por execução, com a caixa do Mailpit medida antes e depois. O sexto caso deste ensaio ficou possível, e o que falta para ele existir está escrito no D172. #### Os seis, fechados em 11/09/2026 O sexto caso entrou, e com ele o ensaio passou a ter **seis de seis**. Resíduo **ZERO** nas seis tabelas, no diretório de log e na caixa de e-mail. **Ele não grava linha nenhuma, e isso mudou o que "resíduo" significa aqui.** Os cinco primeiros escrevem em tabela; o SAC entrega uma **mensagem**. O banco dele é a caixa de captura, lida por HTTP, e quatro funções novas — `caixaDeEmail`, `idsNaCaixa`, `mensagemDaCaixa`, `apagarDaCaixa` — são o equivalente do `$conexao` para ela. A restauração é por **id**, nunca apagando a caixa: `DELETE /api/v1/messages` sem corpo apaga tudo, e tudo inclui o que outra pessoa deixou ali para olhar. **O caso afirma três coisas que `{sucesso:true}` não diz.** O endpoint devolve `true` literal — a flag só significa "nenhuma exceção subiu". Então o caso abre a caixa e exige: que exista **exatamente uma** mensagem nova; que ela tenha ido para a franqueadora; e que o texto do cliente esteja dentro dela. O `Reply-To` e o assunto também são conferidos. **E ele manda `unidade_id` de propósito** — a unidade `90001200` do cenário, que **tem** e-mail (`decima@teste.invalid`). Exigir que a mensagem chegue na franqueadora *mesmo assim* é o que distingue "o caminho padrão funciona" de "a sobrescrita morreu". **Falsificado:** com a sobrescrita plantada de volta, o caso acusa *"6. sac: entregou para [decima@teste.invalid] — tinha de ser só a franqueadora"* e sai com 1. Sem o `unidade_id`, ele passaria com o defeito de volta. #### A guarda nova é a primeira deste projeto que protege um TERCEIRO Todas as outras guardas destes ensaios protegem o **cenário**. Esta protege quem ia receber. O caso 6 manda um chamado de SAC de verdade, e o SAC manda e-mail. Se a seção `mail` apontar para um servidor real em vez de um capturador, o ensaio entrega uma mensagem de teste na caixa da franqueadora — e **e-mail entregue nenhum `finally` desfaz**. Então, sem caixa de captura que responda, ele **recusa rodar**, com saída 2, antes de qualquer caso. Ela também impede o avesso: caixa que não responde significa caso que não pode conferir a entrega, e que passaria afirmando o que não mediu. **Falsificado:** apontando o e-mail para um host inexistente, ele para com saída 2 e nenhuma mensagem sai. #### E AÍ VEIO O ACHADO QUE VALE MAIS QUE O SEXTO CASO: nada disso rodava no CI Ao conferir se o sexto caso ia executar, descobri que **nenhum dos dois ensaios que escrevem jamais rodou no CI** — e que o CI estava **vermelho** por isso. Medido, não suposto: as cinco execuções mais recentes do workflow, todas `failure`, e o log do run `34651184927` nomeando o passo. O job `caracterizacao-postgres` roda contra **PostgreSQL**, e os dois ensaios foram escritos em SQL do **MySQL**. Eram **quatro** construtos: | construto | onde | o que o PostgreSQL diz | |---|---|---| | `GET_LOCK` / `RELEASE_LOCK` | os **dois** ensaios | `function get_lock(unknown, integer) does not exist` | | `DATABASE()` e `REFERENCED_TABLE_NAME` | `limpar()` do ensaio de recusas | `function database() does not exist` | | crase como citação de nome | o `DELETE` da mesma função | erro de sintaxe | | `ON DUPLICATE KEY UPDATE` (×2) | os casos 14 e 21 das recusas | não existe; lá é `ON CONFLICT` | E havia um quinto, este no ensaio do D61 e **mais caro que os outros**: a restauração das agendas re-inseria a linha lida com `$conexao->insert()`, e no PostgreSQL `SELECT *` devolve coluna booleana como `bool` do PHP. Sem dizer o tipo, o DBAL liga `false` como **texto**: ``` ERROR: invalid input syntax for type boolean: "" unnamed portal parameter $12 = '' ``` O `$12` era `agendas.checkin`. E o erro acontecia **dentro do `finally`**, depois de o `DELETE` de faixa já ter corrido: a agenda do cenário ia embora e **não voltava**. Eu vi isso acontecer — a primeira execução no PostgreSQL destruiu a agenda de fixture do `franquiabv_pgcontrato`, e a execução seguinte recusou rodar por resíduo. É a família do **D81/D82** no lugar mais caro possível: o código que existe para não deixar resíduo era o que deixava. **O que isso significa sobre os débitos:** o D61 dizia que a cobertura estava no CI, e estava escrita no CI, e não executava. O D170 dizia o mesmo dos seus 23 casos. *Portão que não roda é pior que portão que não existe* — e **verde por ausência de execução também não é verde**. **Consertado, e medido nos dois bancos:** | | MySQL | PostgreSQL | |---|---|---| | recusas da comanda (D170), 23 casos | 23 de 23 | **23 de 23** | | escritas do aplicativo (D61), 6 casos | 6 de 6 | **6 de 6** | | resíduo | ZERO | ZERO | A trava saiu para `scripts/trava-de-banco.php`, que emite `GET_LOCK` no MySQL e `pg_try_advisory_lock(CAST(? AS bigint))` no PostgreSQL — o `CAST` não é enfeite: o PDO manda parâmetro como texto e o PostgreSQL não infere tipo de função sobrecarregada. As duas execuções seguidas saem 0, que é o que prova que a restauração restaurou. **E um segundo vermelho, independente, no outro job.** `conferir-rotas-sem-login.php` é o único portão do job `verificacao` que precisa de `vendor/autoload.php` — ele mescla a configuração do Laminas para saber quais rotas existem. Aquele job nunca instalou dependência nenhuma, porque é o dos portões textuais. Resultado medido: `Failed opening required 'vendor/autoload.php'`, saída 255, **em toda execução desde que o passo entrou** (D146). O portão passa localmente, onde o `vendor/` existe. Entrou um `composer install` naquele job, antes do passo. #### O CI ganhou um capturador de e-mail, e a alternativa era pior O job `caracterizacao-postgres` — onde este ensaio roda — tinha **só** o serviço `postgres`, e o `local.php` que ele gera mantém `'host' => 'mailpit'`, porque o `sed` é deliberadamente endereçado ao bloco do Doctrine para **não** tocar na seção de e-mail. No runner esse host não existe: o sexto caso ficaria vermelho sem haver defeito nenhum. Entrou o serviço `axllent/mailpit` no job, com as portas 1025 (SMTP) e 8025 (a API que o ensaio lê), e um **segundo `sed`**, com endereço próprio no bloco `'mail'`, trocando o host por `127.0.0.1` — serviço do Actions responde em `localhost`, e não pelo nome, porque o job roda direto no runner e não em contêiner. Os dois `sed` ficam separados de propósito: juntá-los desfaria a proteção que o comentário do primeiro explica. Conferido por simulação local — as duas substituições pegam exatamente duas linhas, e o resto do bloco fica intacto. **A alternativa era pior:** deixar a seção de e-mail cair no `global.php`, que diz `mail.barbearia.vip`, entregaria uma mensagem de teste na caixa da franqueadora a cada execução do CI. **Não entrou teste de contrato para o caminho de sucesso**, e é por desenho: o sucesso e a recusa deste endpoint têm a **mesma forma** (`{sucesso}`), só o valor muda, então um instantâneo de estrutura não distingue os dois — é exatamente por isso que `sac-sem-dados.json` passava enquanto o endpoint estava inteiramente quebrado. A afirmação que vale é o efeito, e o efeito só se vê na caixa. O ensaio é o lugar dele. #### Um fato que sobrou da conferência, e vale por si O snapshot de hoje congela `{mensagem, sucesso}` — a forma do **erro**. O sucesso real devolve **só `{sucesso}`**, sem `mensagem`. As duas formas são diferentes, e o que está congelado é a que não interessa ao aplicativo. É o defeito do **D55** vivo, num endpoint que a Fase 2 vai mexer. #### A DECISÃO, tomada em 31/08/2026: adiar até o D66 fechar **Por decisão sua, nada muda agora — e o motivo não é custo, é diagnóstico.** A suíte de contrato já falha sozinha, sem causa conhecida (**D66**). Somar dependência de estado do banco criaria um segundo modo de falha, e na próxima falha haveria duas explicações possíveis e nenhuma forma barata de separá-las. **A dependência fica escrita:** quando o D66 fechar, este débito volta à mesa com as opções reais, que são duas e não três — cobrir os seis com o roteiro recriando o banco, ou não cobrir nenhum. A terceira via não existe. `/api/visagismo/dados-processar` também está sem o par, e fica fora desta conta por decisão sua: visagismo é dívida futura declarada. #### PARCIAL em 06/10/2026 -- os ensaios irmãos devolvem o que o login grava O parágrafo "E o resíduo que eu não estava contando" deixou escrito que `ensaiar-recusas-adm-api.php` e `ensaiar-fluxo-adm-api.php` também entram no ERP e não devolvem o deles. Os dois passaram a devolver, no molde do ensaio das escritas: leem, **antes do primeiro login**, o `token_web` de cada usuário da fixture (`id >= 90001000`) e o maior id de `usuarios_acessos`, e no `finally` regravam cada token pelo valor lido e apagam os acessos acima daquele id. Depois do `finally`, e antes da saída, conferem: token diferente ou acesso a mais sai com 1, nomeando o usuário. - **O de recusas** já lançava em vez de `exit` (o D171) e já tinha o `finally`; a devolução entrou como o primeiro passo dele -- uma falha num dos passos de baixo não a deixa para trás. - **O de fluxo** não abria o banco: era só HTTP, e cada passo que falhava saía por `exit(1)`, que em PHP não roda `finally`. Passou a abrir a conexão pelo `Application::init` (e a recusar rodar com mais de 10 unidades, como os irmãos: a devolução apaga acessos), e a parada virou a exceção `FluxoParou`, com o código de saída -- o passo que falha, o login recusado, o dia com um horário só. O corpo do fluxo foi para dentro do `try` sem reindentar. **Medido, com o banco de contrato montado do zero:** | banco | ensaio | saída | resíduo dos logins | |---|---|---:|---| | PostgreSQL, na ordem do CI | recusas, 201 de 201 | 0 | ZERO | | PostgreSQL, na ordem do CI | fluxo | 0 | ZERO | | MySQL | recusas, 201 de 201 | 0 | ZERO | | MySQL | fluxo, duas vezes seguidas | 0 e 0 | ZERO | | MySQL | fluxo com a senha errada | 2 | ZERO | | MySQL | fluxo contra um servidor que não responde | 2 | ZERO | | MySQL | fluxo parado no passo 5, depois do login (o serviço desativado no banco) | 1 | ZERO | | MySQL | recusas com a senha errada | 2 | ZERO | | MySQL | recusas contra um servidor que não responde | 2 | ZERO | | MySQL | recusas, rodada parcial (`ENSAIO_SO=1`) | 3 | ZERO | E por fora dos dois ensaios, lido no banco: depois das oito primeiras execuções no MySQL, `usuarios_acessos` tinha as mesmas zero linhas e os tokens da fixture o mesmo resumo (o sha1 da lista de sha1 por usuário -- nenhum token impresso) que antes da primeira. **Os mutantes, um de cada vez, no arquivo, restaurados pelo sha1:** | mutante | saída | o que acusou | |---|---:|---| | recusas sem a devolução no `finally` | 1 | o token do 90001000 e do 90001001 trocados, 2 acessos sobrando | | fluxo sem a devolução no `finally` | 1 | o token do 90001001 trocado, 1 acesso sobrando | | fluxo com o `exit(1)` de volta no passo, parado no passo 5 | 1 | nada: o `finally` e a conferência não rodam -- e o banco, lido por fora, ficou com 1 acesso a mais e o token trocado | O terceiro é o que o aviso do lote pedia para provar: com `exit`, o ensaio interrompido deixa o resíduo calado. #### A revisão de 06/10/2026: a rodada depois de uma morta, a interrupção depois dos logins, e os irmãos que faltam A revisão da seção de cima achou três coisas, e mediu as duas primeiras contra o banco de contrato do MySQL: **1. A rodada que limpa a sobra de uma rodada morta saía com 1.** A foto dos tokens (`id >= 90001000`) incluía o administrador do ensaio (90007501) quando uma rodada morta o deixava no banco; o bloco "A SOBRA DE UMA RODADA MORTA" o apagava, e a conferência lia `false` na linha que não existe mais e dizia "o login trocou o token e ele não voltou", sobre o banco limpo. **Conserto:** o administrador do ensaio fica fora da foto -- ele não é da fixture, o ensaio o cria e o apaga, e os acessos dele saem pelo `DELETE ... WHERE usuario` e pelo id --; e a conferência, quando a linha da foto some, diz que ela sumiu, em vez de culpar o token. **2. A devolução depois de um login nunca tinha sido exercida por uma interrupção.** As linhas "senha errada" e "servidor que não responde" da tabela de cima param antes do primeiro login -- o login que falha não grava nada, e o ZERO delas é de quem não tinha o que devolver --, e a rodada parcial (`ENSAIO_SO=1`) termina pelo caminho normal, sem passar pelo `catch`. **Medido agora**, cada linha sozinha, com cópias do ensaio em `/tmp/ens` no contêiner (o arquivo do repositório não foi tocado) e o retrato agregado do banco lido por fora entre uma e outra (o sha1 da lista de tokens dos cinco usuários da fixture, nunca um token): | rodada | saída | o que disse | o banco depois | |---|---:|---|---| | exceção lançada logo depois dos três logins | **2** | "resíduo dos logins: ZERO" | tokens e acessos iguais aos de antes | | morta por SIGKILL logo depois dos três logins | 137 | -- | o administrador ficou, 3 acessos, os tokens trocados | | a 1ª versão do D61, parcial, sem remontar | **1** | "token do usuário 90007501 ... não voltou" | limpo: o vermelho é falso | | outra morta, e a revisão SEM tirar o administrador da foto | **1** | "usuarios 90007501: a linha estava na foto e sumiu" | limpo | | outra morta, e a revisão, parcial | **3** | "resíduo dos logins: ZERO" | os tokens que encontrou, o administrador e o acesso dele apagados | E a revisão inteira, com o banco montado do zero: **MySQL 201 de 201, saída 0**, resíduo ZERO e o retrato do banco igual antes e depois; **PostgreSQL (o `franquiabv_pgcontrato` montado do zero) 201 de 201, saída 0**, resíduo ZERO. A linha da morta mostra o limite que fica: a rodada morta por SIGKILL não roda `finally` nenhum, e o que ela gravou -- os tokens trocados e os acessos dos logins dela -- fica no banco; a rodada seguinte devolve só o dela, porque não sabe o "antes" da outra. Remontar o banco continua sendo o que zera. **3. Os irmãos que também entram no ERP**, levantados pelo `grep` de `autenticacao/entrar` em `scripts/`, e não de memória. Entram com usuário da fixture e não mencionam `token_web` nem `usuarios_acessos`: `ensaiar-busca-de-cliente-da-agenda`, `ensaiar-fidelidade-adm-api`, `ensaiar-usuarios-adm-api`, `ensaiar-permissao-adm-api`, `ensaiar-sessao-do-erp` (o cabeçalho dele diz que "os logins escrevem o que o login sempre escreve"), `ensaiar-links-consertados-do-erp` (fora do CI), `ensaiar-fechamento-da-agenda` (que não se roda aqui), `medir-adm-api-no-postgres`, `medir-relatorios-no-postgres` e `medir-telas-no-postgres`; e o `ensaiar-cupons-adm-api` apaga só os acessos do próprio administrador. Na ordem do CI vários deles rodam antes e depois das recusas e do fluxo, e o banco de contrato continua juntando acessos e trocando o token do gerente e do colaborador. Eles ficaram fora do item, que pedia os dois. **O que fica deste débito:** - os dez roteiros acima, mais a sobra do de cupons, que entram no ERP e não devolvem o que o login grava -- o molde é o do ensaio das escritas e o destes dois (a foto antes do primeiro login, a devolução no `finally`, a conferência depois, e a parada por exceção, nunca por `exit`); - a variante `'+' . $ddi . ' ' . $telefone` da checagem de duplicata do `AplicativoService` (o "Duas coisas que o vermelho da primeira execução ensinou", item 2) -- um pedido por chamada que não pode achar nada. Fora deste item por decisão do levantamento. #### PARCIAL em 08/11/2026 -- os 22 roteiros que entram no ERP devolvem o que o login grava (a fatia 127) A fatia 127 da fila dos débitos de pé (ARNES-DOS-TESTES-E-ENSAIOS) levou o molde a todos os roteiros que entram no ERP, derivados pelo `grep` de `autenticacao/entrar` em `scripts/` (30 arquivos; quatro só citam a rota num comentário -- o `conferir-mensagem-sem-redirecionar`, o `conferir-registro-de-acesso`, o `conferir-rotas-sem-login` e o `ensaiar-rotas-publicas-do-erp` --, três já devolviam -- o das escritas, o das recusas e o do fluxo -- e o `ensaiar-fechamento-da-agenda` não foi tocado: é proibido rodá-lo aqui, e o conserto sem prova não entra). **O ajudante comum: `scripts/residuo-do-login.php`**, no molde do `trava-de-banco.php` (o `require` devolve as funções). A foto é o `token_web` de cada usuário com `id >= 90001000`, pelo valor, menos os que o próprio ensaio cria e apaga (o administrador, o leitor), e o maior id de `usuarios_acessos`; a devolução regrava cada token e apaga os acessos acima do maior; a conferência diz, nomeando o usuário, o token trocado, a linha que sumiu e os acessos que sobraram, e o ensaio sai com 1. Sem foto (a recusa antes da guarda), nada: a devolução apaga acessos, e a foto vem sempre depois da guarda das 10 unidades. **Dois jeitos, conforme o roteiro:** - **no `finally`, com a parada por exceção** -- os 17 que já tinham o `try`/`finally` em volta dos logins e paravam por exceção: arquivos, banners, cupons, cursos, etiquetas, fidelidade, mensagens, pesquisas, saídas, sorteios, usuários, VIP Class, WhatsApp, o provedor de mentira do WhatsApp, notificações, a busca de cliente da agenda e os links consertados. A devolução é o primeiro passo do `finally` (nos dois que desfazem passo a passo -- notificações e o provedor de mentira --, o primeiro que precisa do banco, no `$desfazer`); nos links consertados é o ÚLTIMO, porque o "Sair" do `finally` apaga o `token_web` de quem sai. A conferência vem logo depois do `finally`, antes das outras saídas. - **no fim do encerramento do PHP** -- os cinco cujo corpo não cabe num `try`: o `ensaiar-permissao-adm-api` (a primeira parte sai por `exit` e a terceira declara `const`, que o PHP não aceita dentro de bloco), o `ensaiar-sessao-do-erp` (os ajudantes saem por `exit`, e as devoluções dos casos 19 e 22 a 24 já moravam no encerramento) e os três medidores do PostgreSQL (`medir-adm-api`, `medir-relatorios`, `medir-telas`). A função registrada registra, quando o encerramento começa, a que devolve e confere -- vai para o fim da fila, depois das devoluções do roteiro, e roda também depois de `exit`, de exceção não apanhada e de erro fatal; com resíduo, a saída vira 1. **O que mudou junto:** o `ensaiar-permissao-adm-api` e o `ensaiar-sessao-do-erp` abriam o banco só na parte que escreve, depois dos primeiros logins; a conexão e a guarda das 10 unidades subiram para antes do primeiro login, e os dois recusam rodar inteiros fora do banco de fixtures (antes, as primeiras partes entravam em qualquer banco). O `medir-relatorios-no-postgres` e o `medir-telas-no-postgres` não abriam o banco: passam a abrir pela raiz do repositório, com a mesma guarda. Nenhum caso de nenhum ensaio mudou. **Medido, com o banco de contrato montado do zero, e com um retrato de fora** (o sha1, no PostgreSQL o md5, da lista `id:token` dos usuários da fixture -- nenhum token impresso -- e a contagem de `usuarios_acessos`): | banco | rodada | saídas | retrato antes | retrato depois | |---|---|---|---|---| | MySQL | 24 ensaios, na ordem do CI: os 23 do CI (os 18 tocados, as recusas, as escritas, o fluxo, as rotas públicas, o erro JSON) e o dos links consertados, que é tocado e fica fora do CI | 24 de 24 com 0 | tokens b91f4477…, 0 acessos | tokens b91f4477…, 0 acessos | | PostgreSQL | os mesmos 24 e o `medir-adm-api` | 25 de 25 com 0 | tokens cb06fbdf…, 0 acessos | tokens cb06fbdf…, 0 acessos | | PostgreSQL | o `medir-telas` (187 telas) e o `medir-relatorios` (17 relatórios), com a concessão do CI e o cache | 2 de 2 com 0 | tokens cb06fbdf…, 0 acessos | tokens cb06fbdf…, 0 acessos | Os 22 roteiros tocados disseram "resíduo do login: ZERO" (os 19 do MySQL e do PostgreSQL, o `medir-adm-api` e os dois medidores). A saída do `medir-relatorios` é a mesma linha a linha da rodada do `p48-medir-relatorios-pg.sh` de 08/11/2026, mais a linha do resíduo. **Os mutantes, um por roteiro**, cada um uma cópia do roteiro em `scripts/` (o arquivo do repositório não foi tocado), sem a devolução e com a conferência, apagadas no fim: | roteiro sem a devolução | banco | saída | o que a conferência acusou | |---|---|---:|---| | arquivos | MySQL | 1 | token do 90001001, 3 acessos dele | | banners, cupons, cursos, etiquetas, fidelidade, mensagens, pesquisas, saídas, sorteios, VIP Class (dez) | MySQL | 1 cada | tokens do 90001000 e do 90001001, 1 acesso de cada | | busca de cliente da agenda | MySQL | 1 | token do 90001000, 4 acessos | | links consertados | MySQL | 1 | token do 90001001, 2 acessos | | notificações | MySQL | 1 | token do 90001001, 5 acessos | | permissão (no encerramento) | MySQL | 1 | token do 90001000, 5 acessos | | sessão do ERP (no encerramento) | MySQL | 1 | token do 90001001, 30 acessos | | usuários | MySQL | 1 | tokens do 90001000 (a desativação, não o login) e do 90001001, 1 acesso | | WhatsApp | MySQL | 1 | tokens do 90001000 e do 90001001, 1 e 3 acessos | | provedor de mentira do WhatsApp | MySQL | 1 | token do 90001001, 1 acesso | | `medir-adm-api` (no encerramento) | PostgreSQL | 1 | token do 90001001, 2 acessos | | `medir-telas` (no encerramento) | PostgreSQL | 1 | token do 90001001, 1 acesso | | `medir-relatorios` (no encerramento) | PostgreSQL | 1 | token do 90001001, 1 acesso | | o ajudante sem o `DELETE` dos acessos (H1, pelo de cupons) | PostgreSQL | 1 | 1 acesso do 90001000 e 1 do 90001001 | | o ajudante sem a volta dos tokens (H2, pelo de cupons) | PostgreSQL | 1 | tokens do 90001000 e do 90001001 | Nenhum mutante errou caso do próprio ensaio: a saída 1 é só a do resíduo. Depois dos 19 mutantes do MySQL o retrato de fora mostrava 75 acessos e os tokens trocados -- o que a rodada inteira deixava no banco de contrato até aqui. **O que fica deste débito:** - o `ensaiar-fechamento-da-agenda`, que entra no ERP e não devolve o login -- não foi tocado: rodá-lo aqui é proibido, e o conserto sem prova não entra; quem puder rodá-lo leva o molde (`residuo-do-login.php`, no `finally` dele); - a variante `'+' . $ddi . ' ' . $telefone` do `AplicativoService`, fora por decisão do levantamento, como antes; - a rodada morta por SIGKILL, que não roda `finally` nem encerramento: o limite de 06/10/2026 continua, e remontar o banco continua sendo o que zera. **A verificação de 08/11/2026 (três lentes)** confirmou cinco achados baixos e um sexto foi refutado: - **A `ParadaDoEnsaio` era peça morta** (dois achados iguais): o ajudante declarava a classe e o cabeçalho mandava lançá-la, e nenhum roteiro a usava -- os 17 do `finally` param pelas exceções que já tinham. A classe saiu, e o cabeçalho diz que a parada é a exceção do próprio roteiro, nunca `exit`. - **As guardas das 10 unidades não tinham mutante nem portão**, e nem a exclusão dos usuários do ensaio. Agora: (1) a própria foto confere de novo e LANÇA `DomainException` com mais de 10 unidades, antes de ler qualquer outra coisa -- o roteiro que perder a guarda, ou tirar a foto antes dela, morre antes do primeiro login; (2) o `D61ResiduoDoLoginTest` (6 casos, nos dois bancos) prova o ajudante contra o banco da suíte (o token trocado e o acesso a mais acusados nomeando o usuário, a devolução que zera, o usuário do ensaio fora da foto, a linha que some acusada, a devolução sem foto que não toca o banco) e, com uma conexão dublê, a recusa da foto com 11 unidades e a foto com 10; (3) o mesmo teste lê do disco, sem comentários, todo roteiro que cita `autenticacao/entrar` no código (27; cinco fora, nomeados com o motivo: o fechamento da agenda, os três do molde de 06/10 e o portão das mensagens) e exige, nos 22, a guarda que sai por `exit(2)` ou lança ANTES da foto, e a devolução no `finally` com a conferência depois e nenhum `exit` entre a foto e a devolução -- ou a devolução no encerramento com a foto como argumento. E a recusa rodou de verdade: os cinco roteiros com guarda nova ou subida (a permissão, a sessão do ERP e os três medidores) contra o `franquiabv_dev` (64 unidades; só a contagem), saída 2 em todos, e a contagem e o maior id de `usuarios_acessos` e o sha1 dos tokens da faixa iguais antes e depois. - **Os cinco roteiros sem `try` param por `exit`**, contra a letra "nunca por `exit`": é o desvio já declarado acima (o encerramento roda depois de `exit`, e os mutantes deles saíram 1). Não mudou; o coordenador decide se aceita. - **Refutado: "o `medir-telas` apaga um `$cookies` que nunca existiu".** Existe: `$cookies = tempnam(...)` na linha 61, antes da guarda, e o `@unlink` dela é a mesma limpeza das outras saídas. Medido: com o `@unlink` arrancado (U1), a recusa deixou um `/tmp/telas-*` no contêiner; com ele, nenhum. **Os mutantes da verificação**, um por vez, devolvidos pelo sha1: N1 (a foto sem a exclusão do ensaio), N2 (sem a recusa da foto), N3 (`>=` no lugar de `>`) e N4 (a devolução sem a guarda do nulo -- ela apagou todos os acessos) vermelhos nos dois bancos; R1 (a permissão sem a guarda), R2 (a foto do `medir-telas` antes da guarda), R3 (um `exit` no `try` dos banners) e R4 (os cupons sem a devolução) vermelhos no portão do teste, nomeando o roteiro. Depois, os 19 ensaios do ajudante no MySQL (o banco de contrato montado do zero; o retrato de fora igual antes e depois, zero acessos) e os 19 mais o `medir-adm-api` no PostgreSQL (zero acessos no fim), saída 0 e "resíduo do login: ZERO" em todos. O `medir-telas` e o `medir-relatorios` não rodaram de novo: o caminho deles (o quarto elemento) é o da permissão, da sessão do ERP e do `medir-adm-api`, que rodaram. **Nota sobre os quatro `null` que restam nos snapshots**, para quem varrer de novo e estranhar: são legítimos. `mensagem` só é preenchida em erro, e o caminho de sucesso a devolve nula; `programa_fidelidade_url` é literalmente `null` no código; e `convenio` é campo genuinamente anulável, que ficaria arbitrário em qualquer um dos dois estados. **O snapshot registra tipo, e tipo não sabe dizer "texto ou nulo"** — é um limite da ferramenta, não um defeito do cenário. --- ### D62 — `TIMESTAMPDIFF` estava quebrado, e com ele o filtro de idade — CORRIGIDO Encontrado em 30/08/2026 pelo teste escrito para o **D25**, não por leitura. `ISBase\Doctrine\TimestampDiff::parse()` lia o token do lexer como array: ```php $this->unit = $lexer->token['value']; ``` Em `doctrine/lexer` 2.x o token é um **objeto** `Doctrine\Common\Lexer\Token`, com a propriedade `value`. O acesso por índice dá erro fatal — *"Cannot use object of type Doctrine\Common\Lexer\Token as array"* — **ao parsear a consulta**, antes de chegar ao banco. **A consequência é uma tela que quebra hoje:** o único uso de `TIMESTAMPDIFF` no sistema é o filtro de faixa de idade do relatório de clientes (`ClienteRepository`, por volta da linha 658). Preencher os dois campos de idade e filtrar produz erro fatal. **Por que ninguém tropeçou nisso antes**, e é o mais interessante deste débito: a função só é registrada **dentro do `if` que monta esse filtro**. Quem não preenchesse os dois campos nunca chegava ao parse, e nunca via o erro. O defeito estava protegido pela própria raridade do caminho. E foi assim que ele apareceu: ao centralizar as funções na configuração (D25), escrevi um teste que exercita **todas** elas em DQL real. Sete funções passaram; `TIMESTAMPDIFF` estourou. Nenhum teste anterior a tocava, porque nenhum teste cobre aquele filtro. **A correção é uma linha** — `$lexer->token->value`. Fica a observação que ela sugere: o mesmo idioma antigo pode existir em outras classes de função. As demais sete foram exercitadas e passam, então o problema estava só aqui. --- ### D45 — O inquilino é fixo na configuração, não vem de quem está autenticado Descoberto em 27/08/2026, ao apontar a aplicação para o PostgreSQL (F1.8). O schema PostgreSQL tem Row-Level Security com `FORCE` em 75 tabelas, e a política compara `inquilino_id` com `current_setting('app.inquilino_id')`. `ISBase\Doctrine\DeclararInquilino` declara esse valor depois de cada conexão, lendo-o de `module/ISBase/config/module.config.php` — onde ele está **fixo em `1`**, a Barbearia VIP. **Isso está certo hoje.** A instalação tem um inquilino só, e um valor de implantação numa configuração de implantação é o lugar dele. **Deixa de estar certo no dia em que houver o segundo.** Aí o inquilino passa a ser propriedade de *quem está autenticado*, e a troca passa a ser **por requisição**, não por conexão — o que colide com o reaproveitamento de conexões do pool. Não é uma linha de configuração: é decidir onde a identidade do inquilino vive e como ela sobrevive ao pool. **O risco de esquecer é assimétrico.** Um inquilino declarado a menos devolve **zero linhas, sem erro** — uma tela em branco que parece falta de dado. Um inquilino declarado a mais vaza dado de um cliente para outro. O primeiro sintoma se investiga; o segundo não se percebe. **Ao resolver:** ler o inquilino da identidade autenticada e emiti-lo por requisição, com um teste que prove que duas sessões simultâneas de inquilinos diferentes não se enxergam. --- ### D46 — Ordenações por coluna anulável: o defeito saiu, e o vigia passava no caso exato que ele existia para pegar — CORRIGIDO em 14/09/2026 Descoberto em 27/08/2026, medindo a F1.8. MySQL e PostgreSQL discordam sobre onde o nulo entra numa ordenação — o MySQL o trata como o **menor** valor, o PostgreSQL como o **maior**. Não há erro: a consulta roda nos dois e devolve as mesmas linhas **em ordem diferente**. A varredura encontrou **28 ordenações por coluna anulável, em 17 colunas**, de 157 métodos com `ORDER BY`. **Sete foram corrigidas** com `ISBase\Doctrine\Ordenacao::comoMysql()` — as que têm nulos em quantidade (`clientes.nps` com 228.924 de 242.587) ou que um teste expôs. **As 21 restantes ordenam por coluna que hoje não tem nulo nenhum.** Por isso não foram tocadas: a correção acrescenta trabalho ao banco sem mudar resultado. **O que faz disto um débito e não um não-problema:** a coluna *aceita* nulo. No dia em que a primeira linha nula aparecer — um cadastro incompleto, uma importação, um campo que virou opcional — a listagem muda de ordem sozinha, e nada avisa. O sintoma chega como "o relatório está errado". **A varredura virou roteiro, em 29/08/2026:** `scripts/conferir-ordenacao-nulos.php`. Lê as ordenações em DQL, cruza com as colunas anuláveis do banco, conta os nulos de cada uma, e **sai com 1 se alguma coluna sem correção tiver nulo** — pode virar portão. Enquanto a contagem dependia de alguém lembrar, dependia de alguém lembrar. **Rodá-lo pela primeira vez achou cinco colunas expostas**, e a premissa deste débito não se sustentou: nem todas as restantes tinham zero nulo. | Coluna | Nulos | Usos | |---|---:|---:| | `usuarios.data_contratacao` | **959** de 2.430 | 1 | | `unidades.data_inauguracao` | 14 de 62 | 1 | | `arquivos.subcategoria` | 7 de 109 | 2 | | `dashboard_colaboradores.total_vendas` | 7 de 18.257 | 2 | | `usuarios.data_nascimento` | 3 de 2.430 | 1 | As sete foram corrigidas, e a varredura passou a sair limpa. **Duas coisas que a primeira versão do roteiro errou**, e valem mais que o conserto: **Falso positivo.** Ele procurava só a palavra `comoMysql` para saber se uma ordenação estava corrigida, e acusou seis ordenações por `unidades.estado` que **já estavam certas** — escritas com o `CASE WHEN ... IS NULL` inline, à mão, antes de o auxiliar existir. Eu quase "consertei" código correto, e só não o fiz porque abri os arquivos antes de aplicar o script. Agora ele reconhece as duas formas. **Correção errada.** Três das cinco ordenam por `DAY(coluna)`, não pela coluna: o auxiliar precisa envolver a expressão inteira, e aplicá-lo ao campo teria produzido DQL que não corresponde à ordenação real. O relatório passou a mostrar o termo cru justamente para que quem o lê veja o `DAY(...)`. Nos três casos o filtro por mês é **condicional** — sem mês, as linhas nulas entram, e é aí que a divergência aparece. --- #### O vigia ficava VERDE sobre o defeito dele — fechado em 14/09/2026 O defeito original está pago: as cinco ordenações expostas carregam `Ordenacao::comoMysql()` hoje, e o portão confirma por execução. O que sobrava era ele, e ele não aguentou a primeira falsificação séria. **A dispensa era por CLÁUSULA, e o motivo escrito é por COLUNA.** Bastava a marca `@ordenacao-nulos-conferida` aparecer na janela de 900 caracteres e **todos** os termos daquele `ORDER BY` viravam "corrigida". A única dispensa da casa fala de `uni.estado` — *"1 nulo em 63"* — e calava as vizinhas `uni.pais`, `uni.cidade`, `uni.bairro` e qualquer coluna acrescentada depois. Medido: acrescentar `uni.dataInauguracao DESC` — **15 nulos de 64**, sem correção — àquela cláusula deixava o portão **verde**, imprimindo *"0 sem correção"* três linhas abaixo da própria medida. A mesma mudança **sem** a linha da dispensa dava vermelho. A dispensa era a causa única. Hoje a marca exige alvo: `@ordenacao-nulos-conferida(uni.estado) motivo…`. Dispensa sem alvo não dispensa nada **e é acusada** — calar sobre ela transformaria a sintaxe antiga em "nenhuma dispensa", e o portão ficaria vermelho sem dizer por quê. E dispensa cujo alvo não está na cláusula também é acusada: marca que descola do que ela dispensa é lista que não encolhe. #### O alias de JOIN não resolvia, e o descarte era mudo Havia um comentário dizendo que *"a resolução real vem do Doctrine mais abaixo"*. Abaixo havia um `continue;`. **A resolução prometida nunca foi escrita** — comentário que promete o que o código não faz custa o mesmo que nome que mente. Eram **44 ocorrências descartadas em silêncio**: `uni.cidade`, `cli.nome`, `pro.tipo`, `pag.nome` e outras, num portão que se anunciava varrendo o sistema. Duas das 44 nem eram consulta — eram `ORDER BY` recortado de comentário, e saem pelo conserto descrito abaixo; as outras **42 eram DQL de verdade** que ninguém estava olhando. Resolvi as 44 à mão antes de consertar: **nenhuma esconde defeito vivo hoje** — mas a cegueira era permanente. O conserto tem três partes: o **dono do JOIN** entra na captura (`JOIN uni.cidade c` só diz que `c` é a propriedade `cidade` de alguém — sem o dono não há entidade), as **associações** das entidades passam a ser lidas das anotações `targetEntity`, e a corrente é seguida até um `FROM`, com limite de profundidade. Depois disso: **0 não resolvidas**, e o censo subiu de 9 colunas em 17 usos para **10 em 20** — `unidades.nome` estava invisível desde sempre. #### E ele lia `ORDER BY` dentro de comentário Duas "ocorrências" tinham como termo `dito com numero: …` e `ate cinco`, recortados da documentação dos consertos anteriores — a prosa desta casa cita cláusulas de `ORDER BY` para contar história. As faixas de comentário agora são calculadas por token e puladas. #### A falsificação, com o controle que quase me enganou | O que foi quebrado | Saída | |---|---| | `uni.dataInauguracao DESC` na cláusula dispensada | 1 — `>>> unidades.data_inauguracao 15 nulos de 64` | | a marca volta a não ter alvo | 1 — DISPENSA SEM ALVO | | o alvo aponta para coluna fora da cláusula | 1 — DISPENSA QUE NÃO DISPENSA NADA | | `uni.pais` vira `zzz.pais` | 1 — NÃO CONSEGUI RESOLVER O ALIAS | | **controle:** `cli.nps` volta a ser cru | 1 — `>>> clientes.nps 228.934 nulos de 242.597` | | `ORDER BY` anulável escrito como **comentário** | **0** — prosa não é consulta | **O controle quase virou um achado falso.** A primeira tentativa trocou só o nome da função PHP e deu **verde** — eu escrevi que a culpa era da janela de ±120 caracteres alcançar um `comoMysql` vizinho. Estava errado: com `" ORDER BY " . comoMysql(…)` o trecho capturado termina na aspa e **não sobra termo nenhum** para examinar, então não havia ocorrência. Reconstruído o defeito dentro da string, o portão acusou. A receita das seis está escrita no cabeçalho do roteiro, para a próxima pessoa não repetir o engano. #### O que continua valendo, e precisa estar escrito **Ele não roda no CI, e isso não se resolve escrevendo que roda.** Contar nulos exige a cópia de produção, e o CI só tem o schema — é o mesmo motivo dos irmãos `conferir-relacoes-doctrine` e `conferir-booleano-em-coluna-inteira`. O único chamador é o `conferir-tudo.sh`. Dizer "agora há vigia" sem essa linha seria repetir a frase que o próprio D46 usou contra si. **E a dispensa continua sendo uma dispensa.** `unidades.estado` tem 1 nulo em 64 e segue ordenando sem correção, porque a listagem é paginada e o paginador sem output walkers exige que toda expressão do `ORDER BY` esteja no `SELECT` — um `CASE` nunca está (D97). Onde há nulo, a ordem **difere** entre os bancos, e isso já foi medido na comparação de telas (D109). ### D47 — 36 listagens paginadas sem desempate (FECHADO em 30/08/2026) — CORRIGIDO em 06/10/2026 Descoberto em 27/08/2026, ao provar a correção do D46. Corrigida a colocação dos nulos, os dois bancos passam a devolver o **mesmo conjunto** de linhas no topo — mas não necessariamente na mesma ordem entre si: ``` ORDER BY nps DESC (com a correção) MySQL: 36, 58, 59 PostgreSQL: 58, 36, 59 ``` Os três têm NPS 10. Nenhum `ORDER BY` do sistema tem critério de desempate, e sem ele **nenhum dos dois bancos promete ordem estável** — nem entre bancos, nem entre duas execuções da mesma consulta no mesmo banco. **Isso é anterior à migração e vale igual no MySQL de hoje.** O que o PostgreSQL faz é tornar visível o que já era verdade. **Onde machuca é na paginação.** Com `LIMIT/OFFSET` sobre uma ordem instável, uma linha pode aparecer em duas páginas ou em nenhuma. Numa listagem de 242.587 clientes ordenada por NPS — onde 228.924 empatam em nulo e o resto se concentra em poucos valores inteiros — o empate é a regra, não a exceção. **Medido em 29/08/2026, e o número é 36.** A varredura virou `scripts/conferir-ordenacao-empates.php`, que sai com 1 enquanto houver alguma. **A correção parece uniforme e não é** — é o principal achado da medição, e o motivo de o roteiro classificar caso a caso em vez de mandar corrigir tudo: | | | |---|---:| | Listagens paginadas sem desempate | **36** | | Seguras de corrigir mecanicamente | **33** | | A conferir uma a uma | **3** | **Por que 12 exigem conferência:** `ISBase\Paginator\AdapterQuery` chama `setUseOutputWalkers($selectFields)`, e `$selectFields` é `false` por padrão. Nesse modo o Doctrine pagina por subconsulta e **exige que o campo ordenado esteja no SELECT** — acrescentar `raiz.id` a uma consulta que não o seleciona pode devolver resultado errado, sem erro. E onde há `GROUP BY`, a coluna do desempate precisa estar no agrupamento. **As 33 foram aplicadas em 29/08/2026**, por decisão sua, e o roteiro ganhou `--aplicar` — a ferramenta que identifica passou a ser a que corrige, e pode ser reexecutada. Restam as 3 a conferir, e elas são legítimas: uma monta a DQL num método auxiliar (o `FROM` não está no texto), e as outras duas têm raiz cuja chave não está no `SELECT`. **Duas foram recusadas pela própria ferramenta**, e a recusa vale registrar: *"a ordenação aparece 2 vezes no método; não sei qual"*. Eram listagens com **um ramo de ordenação por coluna clicável da tela** — `ClienteRepository::listagemIndexRelatorio` tem nove, `ConvenioRepository::listagemIndex` tem seis. Corrigir só o último ramo deixaria a listagem determinística ao ordenar por nome e indeterminística ao ordenar por e-mail. Os quinze ramos foram corrigidos à mão. **E isso expôs que ramos escritos com `comoMysql()` são invisíveis ao roteiro** — o `ORDER BY` deixa de ser seguido do nome da coluna. Medido: hoje são zero, porque os únicos estavam nesses dois métodos. Mas o ponto cego existe, e um ramo novo escrito assim não seria acusado. **Três medições erradas antes da certa**, e cada uma errou de um jeito diferente: 1. A primeira contou **comentários** como `ORDER BY` — inclusive comentários meus explicando por que um `ORDER BY` tinha sido removido. 2. A segunda procurou `setFirstResult` e achou **zero**, o que parecia dizer "não há paginação". `setFirstResult` **não existe no projeto**: quem aplica o offset é o paginador do Doctrine, por dentro. Zero não era ausência de problema, era sinal errado. 3. A terceira, pelo `getPaginator()`, achou os 36. O passo 2 é o mais instrutivo: **uma medição que devolve zero parece uma boa notícia**, e é quando ela merece mais desconfiança, não menos. #### As 3 que restavam, fechadas em 30/08/2026 E a lição está em **como** elas restavam. O classificador marcou as três com o mesmo `CONFERIR`, e pelo mesmo motivo trivial: não conseguia enxergar o `FROM` — numa ele estava num método auxiliar, noutra havia cinco `SELECT` alternativos no mesmo método. **`CONFERIR` era um estado do classificador, não uma medida de gravidade** — e o pior defeito dos 36 estava exatamente nessa pilha de três. **A pior era a de cupons gerados, e não era falta de desempate: era `ORDER BY` por constante.** ``` FROM CupomCliente cupcli JOIN cupcli.cupom cup WHERE cup.id = :cupom ORDER BY cup.validade, cup.dataCriacao <-- cup é UM só ``` O `WHERE` fixa `cup` numa única linha, então **todas as linhas da consulta compartilhavam os mesmos dois valores de ordenação**. A cláusula existia, era lida por qualquer revisor como ordem definida, e não ordenava nada. Nem era o mesmo dado: `Cupom::$validade` é um **inteiro** de dias de duração, enquanto `CupomCliente::$validade` é a **data** de vencimento daquele cupom entregue — que é o que a projeção seleciona e o que a tela formata com `dateToString()`. Um `cup` onde cabia `cupcli`. **O tamanho, medido:** 100.374 linhas em 32 cupons, o maior com **18.658** — 933 páginas de 20 em ordem arbitrária. **A dos descontos trazia uma armadilha de colisão.** A listagem é enraizada no item e ordenava pela data da **venda**: uma venda com três itens descontados gera três linhas com a mesma data, empatadas entre si (18.047 vendas assim só em 2025). O desempate é `pro.id` — mas `pro.id` sem apelido vira a chave `id`, que a projeção **já usa** para `ven.id`, e a view monta o link de detalhes com `$venda['id']`. Sem o `AS itemId`, o conserto do desempate trocaria o link da venda pelo id do item, calado. **A de indicações era o caso simples** que as outras duas não eram: raiz visível, `ind.id` já na projeção, uma linha de mudança. São 7 indicações na base, então o desempate não muda nada hoje — entrou porque é grátis. **As três precisaram de `useOutputWalkers`.** `AdapterQuery` nasce com `setUseOutputWalkers(false)`, que exige na projeção todo campo citado no `ORDER BY`. Foi por isso que duas delas exigiram mexer no `SELECT`, e é onde a colisão de chave apareceu. **36 de 36.** O classificador não acusa mais nenhuma. #### O ponto cego dos auxiliares, CORRIGIDO em 06/10/2026 O parágrafo de cima registrou que "ramos escritos com `comoMysql()` são invisíveis ao roteiro", e o portão continuou assim por mais de um mês. Lido no código, o ponto cego era maior do que o escrito: `conferir-ordenacao-empates.php` lia **só o último** `ORDER BY` do método, e só até a primeira aspa. Dois buracos, nenhum acusado: - o ramo `" ORDER BY " . Ordenacao::comoMysql('cli.email', $dir)` deixa o `ORDER BY` seguido de aspa -- a expressão regular não via termo nenhum, e um método que só ordenasse pelo auxiliar saía como "sem ordenação: o D47 não se aplica"; - os ramos de coluna clicável que não eram o último -- oito dos nove de `ClienteRepository::listagemIndexRelatorio`, cinco dos seis de `ConvenioRepository::listagemIndex` -- não eram lidos, com auxiliar ou sem. **O conserto:** cada `ORDER BY` do método é lido pelo tokenizador do PHP, seguindo a concatenação até o fim da expressão: o texto das strings, `ASC` no lugar de `Ordenacao::direcao()`, e o **primeiro argumento** de `comoMysql()` e de `nulosPorUltimo()` como o termo ordenado. Toda cláusula tem de terminar no `.id`; a que termina numa variável ou numa chamada qualquer sai CONFERIR ("não sei ler"), e não como desempate. O `--aplicar` recusa o ramo montado por concatenação -- ele edita texto, e a cláusula não existe inteira no texto. **Medido:** 41 listagens paginadas, **54 ramos de `ORDER BY` lidos** (eram 41, um por método), e a árvore limpa verde, saída 0. O `--aplicar` continua corrigindo o ramo simples (conferido numa cópia: o `cup.id` tirado de `CupomRepository::listagemIndex` voltou, e o arquivo ficou idêntico ao do repositório). **Falsificado numa cópia fora do repositório** (`/tmp/fals-d47`, o `module/` copiado), cada mutante sozinho, e a cópia conferida idêntica ao repositório no fim: | mutante na árvore | portão novo | portão de antes | |---|---|---| | ramo `comoMysql` do convênio sem `, con.id` | **1**, CONFERIR | 0 | | ramo `comoMysql` do e-mail do cliente sem `, cli.id` | **1** | 0 | | a única ordenação pelo auxiliar, sem desempate (cupons gerados) | **1** | 0 | | a mesma, com `. ", cupcli.id"` | 0 (sem falso vermelho) | 0 | | ramo do meio com `direcao()`, sem desempate | **1** | 0 | | ramo terminando em `$desempate` | **1**, "não sei ler" | 0 | E o código novo arrancado, no portão, um pedaço de cada vez: lendo só o último ramo, os ramos do meio voltam a passar (0 nos dois `comoMysql` e no `direcao()`); sem seguir a concatenação, a **árvore limpa** fica vermelha (o `listagemIndexRelatorio` sai "acrescentar `, cli.id`", que já está lá); e sem ler o termo do auxiliar a cor não muda -- o ramo sai CONFERIR por "não sei ler" em vez de por falta de desempate. Ler o termo muda o diagnóstico, e aceita o auxiliar que envolva o próprio `.id`; quem acusa é ler cada ramo pela concatenação. **O que ele ainda não lê:** a cláusula partida em duas instruções (`$dql .= " ORDER BY a.x";` e depois `$dql .= ", a.id";`). Ela sairia acusada sem defeito -- o erro é para o lado do vermelho. Zero assim nas 41. #### A revisão de 06/10/2026: o `.id` tem de ser o da raiz, e havia uma listagem viva sem ele A revisão da versão acima achou que o portão novo herdou o critério de antes -- "termina em **qualquer** `.id`" -- e, com ele, um defeito vivo: `ClienteDebitoRepository::listagemIndex` (a lista de devedores, do ERP antigo e da API nova) termina em `ORDER BY ven.id DESC` sobre a raiz `deb`, e uma venda tem vários débitos. Medido no `franquiabv_dev`, só SELECT: 15 vendas com 2 ou 3 débitos ativos, 32 débitos empatados, em unidades com 296, 114 e 59 débitos ativos -- mais de uma página de 20. Na virada da página, um débito empatado sai em duas ou em nenhuma. É a classe do `cup` em vez de `cupcli` que este débito já registrava. **Os consertos:** - **a listagem:** `ORDER BY ven.id DESC, deb.id DESC` (`deb.id` já estava no SELECT, sem GROUP BY). Caso novo `DevedorTest::testNaMesmaVendaODebitoMaisNovoVemPrimeiro`: dois débitos a mais na venda 90001010, e a ordem cobrada é o de id maior primeiro. **Vermelho sem o conserto nos dois bancos** (os dois devolveram `90001000, 90001001, 90001002`), verde com ele; - **o portão:** a cláusula principal tem de terminar no `.id` **da raiz** -- a do `FROM` do método, ou, quando o `FROM` mora num auxiliar do mesmo arquivo (`IndicacaoRepository::listagemRelatorioIndex` chama `$this->buildRelatorioDqlSelect()`), a do auxiliar. O `.id` de outro alias sai acusado com o motivo ("termina em `ven.id`, que não é a raiz `deb` e pode se repetir nela"); - **o pedaço da concatenação** passou a ser montado só com os tokens significativos: o `//` do fim da linha ficava no pedaço, e `" ORDER BY " . $ordem // antes: Ordenacao::comoMysql('cli.id', $d)` passava, lendo o termo no comentário; - **todo `ORDER BY` de cada literal**, e não só o primeiro: a subconsulta ordenada antes do `ORDER BY` principal, no mesmo literal, escondia o principal. A cláusula de subconsulta (a cortada no parêntese que a fecha) fica com a regra de antes -- termina em algum `.id` --, porque a raiz dela é outra e a ordem dela não pagina nada (DQL não tem `LIMIT` em subconsulta). Medido de novo na árvore limpa: as mesmas 41 listagens e 54 ramos, saída 0; com a listagem dos devedores de antes, saída 1, só ela. **Falsificado numa cópia fora do repositório** (`/tmp/fals-d47b`), cada mutante sozinho, a cópia conferida idêntica ao repositório no fim. "Antes de 06/10" é o portão do HEAD; "1ª versão" é a da seção de cima: | mutante na árvore | revisão | 1ª versão | antes de 06/10 | |---|---:|---:|---:| | devedores com `ORDER BY ven.id DESC` só | **1** | 0 | 0 | | subconsulta `ORDER BY x.id` antes do `ORDER BY cupcli.validade`, no mesmo literal | **1** | 0 | 1 | | a mesma, com `, cupcli.id` no principal | 0 | 0 | 0 | | ramo por variável com `comoMysql('con.id', ...)` num `//` do fim da linha | **1**, "não sei ler" | 0 | 0 | E o código novo arrancado do portão, um pedaço de cada vez: aceitando qualquer alias, os devedores voltam a passar (0); com o comentário no pedaço, o ramo por variável volta a passar (0); lendo só o primeiro `ORDER BY` do literal, a subconsulta volta a esconder o principal (0); sem seguir o auxiliar, a **árvore limpa** fica vermelha -- "não achei o alias da entidade raiz" nas indicações, o falso vermelho que ele evita; e cobrando a subconsulta pela raiz do método, a subconsulta com desempate próprio sai vermelha sem defeito. --- ### D44 — A trava contra execução simultânea é usada em 6 rotinas, não 4 — e o teste do dashboard ficava verde com a trava arrancada — PARCIAL, lido em 05/10/2026 — PARCIAL em 13/10/2026 — PREPARADO em 07/11/2026 > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito sem marca de estado, e o corpo diz que ele está parcial: uma parte está consertada, e a outra não. Falta: a trava em `relatoriosRoyaltiesFaturasGerar`, à espera de decisão sua; trocar `flock` por `pg_advisory_lock` depois do corte; a unicidade de royalties, DDL em produção. `CronJobService::acquireLock()` implementa exclusão mútua com `flock`, e está aplicada apenas em `marketingEnvios` e `marketingPush`. **O D40 é o preço disso**: 107 linhas duplicadas no dashboard, 84 com valores divergentes, porque a rotina que as grava não usa a trava que o próprio arquivo oferece vinte linhas acima. A de **royalties** grava com o mesmo padrão de ler-e-criar-se-não-existe, também sem trava — e é a única do conjunto que mexe em dinheiro. **Duas limitações que precisam ser ditas antes de espalhar a trava por aí:** 1. **É trava de arquivo**, em `sys_get_temp_dir()`. Protege contra dois processos na mesma máquina e **não** contra duas máquinas. Com a F1.7 e mais de um nó, deixa de proteger — e o sintoma volta a ser duplicata silenciosa. 2. **Trava não substitui restrição de unicidade.** A do dashboard entrou no schema PostgreSQL; a de royalties ainda não tem. **Duas rotinas a mais ganharam a trava em 30/08/2026**, e agora são 4 de 29: - **dashboard de colaboradores**, que era a causa do D40. A trava mora no serviço, junto do trabalho, e tem teste. - **royalties**, a única do conjunto que mexe em dinheiro. A trava ficou no *controller* do cron, porque `FranquiaService` recebe só o EntityManager e não alcança `acquireLock()`. Funciona, e é meio-caminho: a cobertura é por leitura, não por execução. #### A extração foi feita em 30/08/2026 A exclusão mútua virou `ISBase\Util\TravaDeExecucao`, com `obter()` e `liberar()`. `CronJobService::acquireLock()` e `releaseLock()` continuam existindo como delegação, para não quebrar quem já chamava. **A trava de royalties voltou do controller para dentro do serviço**, que é onde devia estar desde o começo — estava fora por alcance, não por desenho. E trava longe do trabalho que protege é trava que a próxima pessoa esquece de levar junto. **A extração trouxe a cobertura junto, e essa é a razão prática de fazê-la.** Enquanto a trava morava no controller, testá-la exigiria subir HTTP com o token do cron; com ela no serviço, o teste é uma chamada. `CronTravaSimultaneaTest` passou a ter o caso de royalties — a rotina onde a trava mais importa, porque a tabela não tem restrição de unicidade em banco nenhum e a trava é a única proteção que existe. Extrair não foi arrumação: foi o que tornou a proteção verificável. #### Espalhar não era espalhar por todas — eram duas Classifiquei as 27 rotinas públicas do `CronJobService` pelo padrão que a corrida estraga, em vez de aplicar a trava a todas: | | | |---|---:| | Já com trava | 3 | | **Lê-e-cria-se-não-existe, sem trava** | **2** | | Escrevem sem esse padrão | 11 | | Não escrevem | 11 | As duas do meio ganharam trava em 30/08/2026, e **são 5 de 27**. As outras 22 não precisam: rotina que só lê não corre risco, e rotina que só insere não duplica *por corrida* — pode duplicar de outro jeito, o que é outro assunto. **`relatoriosDashboardFaturamentoAtualizar`** tinha o padrão e nenhuma duplicata na base. Isso não é proteção: é sorte de agendamento, com a mesma corrida na mesma janela noturna e sem restrição de unicidade para barrar a segunda gravação. **`npsContabilizar` é o caso mais exposto de todos, e não por ser cron.** `VendasController` a chama **toda vez que alguém abre o relatório de vendas realizadas** — dois usuários abrindo junto disputam, e um usuário abrindo durante a execução noturna também. E a base confirma: `nps_resultados_colaboradores` tem **5 combinações (colaborador, mês, ano) repetidas**, todas com `data_criacao` idêntica ao segundo — a assinatura de duas execuções gravando juntas. A mais recente é de **12/2025**. **Um preço visível ao usuário, que vale dizer:** com a trava detida, o relatório abre sem consolidar os NPS pendentes daquele instante, e a próxima abertura os atualiza. É menos ruim que a alternativa atual, em que a tela lê uma de duas linhas duplicadas sem que ninguém saiba qual — mas é mudança de comportamento numa tela, e não só numa rotina noturna. **O que continua pendente:** trocar `flock` por `pg_advisory_lock` na migração. O `flock` protege contra dois processos na mesma máquina e não contra duas máquinas, e a F1.7 torna isso necessário. **Decidido em 31/08/2026: adiado, e agora com um número ao lado.** Ao decidir este débito perguntei se a corrida da tabela de royalties já tinha acontecido. Tinha: **87 pares duplicados, 29 unidades, entre 25/11 e 14/12/2025** — virou o **D71**. O dinheiro está correto hoje por acidente, e o D71 explica qual acidente e o que o desfaz. A troca da trava e a unicidade que falta voltam à mesa juntas, no desenho do corte. **Ao resolver:** extrair a trava para um utilitário compartilhado, trocar `flock` por `pg_advisory_lock` na migração — que vale entre nós, e a F1.7 torna isso necessário — e acrescentar a unicidade que falta. A trava evita o trabalho repetido; a restrição garante que, se ele acontecer, o banco recusa. **A de `royalties` não existe em banco nenhum**, nem MySQL nem PostgreSQL. Ali a trava é a única proteção, e é por isso que ela entrou mesmo pelo caminho imperfeito. --- #### O vigia ficava verde com a trava arrancada — e é a segunda vez — 14/09/2026 **Este débito não fecha**, e o motivo é o que o próprio registro já dizia: o que sobra dele é trocar `flock` por `pg_advisory_lock` — que só faz sentido com a aplicação em PostgreSQL, depois do corte — e a unicidade que falta no MySQL, que é DDL em produção congelada. Há decisão sua de 31/08/2026 sobre isso. O que muda hoje é o vigia, que não vigiava. **`testODashboardDesisteQuandoJaHaExecucaoEmCurso` passava com a guarda da trava arrancada.** Medido em 14/09/2026: removida a guarda de `relatoriosDashboardColaboradoresAtualizar`, a rotina roda apesar da trava detida — e o teste continuava **verde**. A causa é onde ele olhava. A rotina percorre `selecionarUsuariosRelatorio`, que filtra `status = 1 AND grupo = 1 AND DATE(relatorio_dashboard_colaboradores) < hoje` — **180 colaboradores** hoje. A linha vigiada era a `90001516`, da fixture, cujo colaborador é o `90001000`, de `grupo = 90001000`. Perguntado com o filtro da própria rotina, o número é **zero**: aquele colaborador não está no conjunto que ela percorre. `data_alteracao` não mudava nem quando a rotina rodava, e a asserção era verdadeira nos dois mundos. **Foram dois caminhos para o mesmo buraco.** O remendo de 01/09/2026 — que consertou uma dependência de calendário real — passou a inserir a linha sintética `90001500` com `colaborador 90001000`, igualmente inalcançável. E hoje nem chega lá, porque a fixture já traz a `90001516`, do mesmo colaborador, que o `SELECT` encontra primeiro. Trocou-se um vermelho falso por um verde falso, e ele durou treze dias. **E é a segunda cegueira do mesmo teste.** O comentário vizinho, escrito quando a primeira foi consertada, diz com todas as letras: *"contar linhas não serve, e a primeira versão deste teste fazia isso — e passava mesmo com a trava desligada"*. Duas vezes o conserto pareceu certo e o vigia continuou olhando para o lugar errado. O conserto: o colaborador passa a sair da **consulta da própria rotina**, com o mesmo filtro escrito igual, e a linha vigiada é a daquele colaborador — a de menor `id`, que é a que `selecionarPorMesAnoColaborador` devolve. Não há como o vigia olhar onde o vigiado não passa. **E o conserto nasceu com um defeito meu, achado horas depois.** O caso passou a escolher o colaborador pela consulta da própria rotina — e **no banco do CI não existe nenhum**: ele nasce de `mysql.sql` mais as fixtures, e a fixture tem `grupo = 90001000`. Com o `assertNotFalse` duro, o caso **reprovava** no banco limpo: eu teria deixado o CI vermelho para sempre no dia em que ele voltasse. Apareceu rodando `scripts/rodar-caracterizacao-como-ci.sh`, que monta o banco do jeito que o CI monta — 641 testes, **1 falha**, e a falha era minha. O conserto é o que a base já oferece: `exigeHistoricoDaProducao()`, que **pula dizendo o motivo** quando a cópia da produção foi declarada ausente, e continua falhando quando ela deveria estar lá. Falhar diria que há regressão onde há ausência de dado; passar calado seria verde sobre nada. | | | |---|---| | teste antigo, guarda arrancada | **verde** — por treze dias | | teste novo, guarda arrancada | **vermelho**: `2000-01-01 00:00:00` virou `2026-09-14 04:58:31` | | teste novo, guarda no lugar | verde, e em 3 segundos | #### O número do título estava velho, e a contagem é 6 `grep` por `acquireLock` e `TravaDeExecucao::obter` em `module/` devolve **seis** pontos de aquisição, em dois arquivos: `npsContabilizar`, `relatoriosDashboardFaturamento`, `relatoriosDashboardColaboradores`, `marketingEnvios` e `marketingPush` (nome montado, serve mais de uma ação) no `CronJobService`, e `relatoriosRoyaltiesAtualizar` no `FranquiaService`. O título dizia **4**. #### Uma rotina de cron com o padrão do D44, sem trava, que emite boleto — PARA DECISÃO SUA Este é o achado que **não** foi consertado esta noite, e a razão está escrita abaixo. `module/ISRelatorio/src/Service/FranquiaService.php`, método `relatoriosRoyaltiesFaturasGerar()`. Ele tem o ler-e-criar-se-não-existe exato que o D44 descreve — `selecionarPorUnidadeVencimento()`, `if (empty($fatura))`, `persist`/`flush` — e **não tem trava**. `royalties_faturas` não tem restrição de unicidade em banco nenhum, nem no MySQL nem em `postgres/schema.sql`. Ela escapou da classificação porque o D44 diz *"classifiquei as 27 rotinas públicas do `CronJobService`"* — e as rotinas de cron que moram no `FranquiaService` ficaram de fora da varredura. **Por que não foi consertada:** o corpo do método termina chamando `gerarFatura()`, que fala com a API **de produção** do Asaas, com a chave escrita no construtor de `module/ISBase/src/Util/Asaas.php` — que o **D3** já registra como sendo a de produção. E essa chamada está **fora** do `if (date('d') == 16)` que envolve o resto do método: ela roda em **toda** invocação, qualquer dia. *Dito com a precisão que eu tenho, e não mais que ela:* a busca que alimenta o laço é `DATE(vencimento) = :vencimento AND asaasStatus = 'WAITING'`, com o vencimento montado como `"29/" . date('m/Y')` — hoje, `2026-09-29`. Na cópia há **5** faturas em `WAITING`, e nenhuma vence nessa data (a mais recente é 2026-01-29). Então **hoje**, nesta cópia, a rotina não acharia nada para cobrar. Isso é acidente do dado, não garantia: no dia 16 ela mesma cria as faturas com vencimento `29/mm/aaaa` e **no mesmo fôlego** entra no laço que as cobra. Eu não executei a rotina, e não vou executá-la para descobrir a diferença. **E ela era chamada por nós, todo dia, sem ninguém saber.** Medido em 14/09/2026: `scripts/medir-cron-no-postgres.php` pedia as 22 rotinas de cron uma a uma — e `relatoriosRoyaltiesFaturasGerar` estava entre elas, assim como `relatoriosRoyaltiesFaturasAtualizar`. O CI também as pediu, na última corrida verde. As duas saíram da medição no mesmo dia, com o motivo escrito; o registro disso está no **D98**. Isso não conserta o D44 — a rotina continua sem trava —, mas tira do caminho a única coisa que, aqui, poderia transformar uma medição em cobrança. A guarda em si é PHP puro e cabe em cinco linhas, no molde da irmã vinte linhas acima. Mas pôr guarda em código que mexe em cobrança **sem poder falsificá-la** contraria a regra desta casa — e a alternativa custa apenas esperar você acordar. O trecho, pronto para entrar: $trava = Util\TravaDeExecucao::obter('relatoriosRoyaltiesFaturasGerar'); if ($trava === false) { return false; } try { ... } finally { Util\TravaDeExecucao::liberar($trava); } #### A trava das faturas do dia 16 — 13/10/2026 (a resposta 98 do dono) O dono respondeu a pergunta 98 do lote, em 11/10/2026, com a opção (a): **"A trava, e a emissão continua em qualquer chamada"** -- repetir a chamada no dia 17 emite só as que falharam no dia 16. **O conserto** (o item UNIDADES-GRUPOS-ROYALTIES). `FranquiaService::relatoriosRoyaltiesFaturasGerar` pega a trava `relatoriosRoyaltiesFaturasGerar` (a `TravaDeExecucao` da rotina irmã das 05:25, com o nome desta) antes de tudo, e ela cobre a criação e a emissão; com a trava detida, a rotina devolve `false` sem tocar em nada, e o `CronJobController` responde `{"sucesso": false, "mensagem": "Processo já em execução."}`, como o da apuração. A emissão continua onde estava, fora do `if` do dia 16: qualquer chamada emite as faturas do mês ainda `WAITING`, e a emitida sai do `WAITING` com o status do Asaas. Duas mudanças pequenas para o teste: o dia da conta virou argumento (`$hoje`; a rotina usa o de agora, e as contas são as de antes, com o mês anterior pelo primeiro dia dele), e o cliente do Asaas (`asaas()`) ficou protegido, e não privado, para o teste trocá-lo por um dublê numa subclasse. **Provado sem falar com o Asaas** (`tests/Caracterizacao/FaturasDeRoyaltiesTravaTest.php`, 3 casos, nos dois bancos, em série): com a trava detida, a rotina devolve `false`, o dublê não é chamado e a fatura do caso continua `WAITING`; com a trava livre, a emissão chega na fatura do caso num dia que não é 16, e a segunda chamada roda (a trava foi liberada) e não a reemite; com o dublê recusando uma das duas, a recusada fica `WAITING` com o erro, e a segunda chamada tenta só ela. A rotina nunca rodou fora da suíte, e a configuração passada ao serviço do teste é vazia: o Asaas de verdade lançaria no construtor, antes de qualquer `curl`. **Mutante:** o `if ($trava === false)` arrancado deixa o primeiro caso vermelho. **O que continua pendente** é o de antes, e por isso o débito segue PARCIAL: trocar `flock` por `pg_advisory_lock` depois do corte (a trava de arquivo não protege entre duas máquinas), e a unicidade de `royalties` e de `royalties_faturas`, que é DDL em produção. Até lá a trava é a única proteção das duas tabelas. #### A revisão da trava das faturas — 13/10/2026 A verificação do item achou quatro lacunas na prova acima e uma no que ela afirmava; as cinco foram fechadas ou registradas: - **A trava cobria a criação só na leitura.** Os três casos passavam com ela movida para depois do `if` do dia 16: a contenção só era medida na emissão, e o ler-e-criar das faturas -- o defeito que o D44 descreve -- não estava preso por teste. O caso novo `testComATravaDetidaNoDia16NenhumaFaturaNasce` põe um dia de retrato no ciclo da unidade do caso e passa o dia 16 deste mês: com a trava detida, nenhuma fatura nasce e o dublê não é chamado; solta, nasce uma só e é emitida. - **Os casos rodavam no dia de hoje.** Sem `$hoje`, a força do "em qualquer dia" dependia do calendário: num dia 16, a emissão movida para dentro do `if` ficava verde. Agora os casos passam o dia (o 17 deste mês para "um dia que não é 16", o 16 deste mês para a criação); o mês continua o corrente, porque as fixtures gravam nele. - **A resposta do controller não era medida.** `testOControllerDoCronDizQueARotinaJaEstaEmExecucao` despacha `relatoriosRoyaltiesFaturasGerarAction` com um contêiner que só entrega o serviço com o Asaas dublado: com a trava detida, `{"sucesso": false, "mensagem": "Processo já em execução."}`; livre, `{"sucesso": true}`. - **"Emite só as que falharam" vale quando a resposta chega.** Se o `curl` passa dos 30 s (ou o corpo não é JSON) depois de o Asaas criar a cobrança, `gerarFatura` não via nem id nem erro, e a fatura ficava `WAITING`, sem nada, igual à que nunca foi tentada: a chamada repetida do dia 17 manda outro `POST /payments`, e são dois boletos para a mesma unidade. O defeito é anterior ao item (a emissão em qualquer chamada já existia). **Consertado o que não pede decisão:** a resposta perdida fica anotada em `asaas_erro` ("sem resposta do Asaas ao gerar boleto (a cobranca pode ter saido: confira no Asaas antes de emitir de novo)"). **O resto -- como conferir antes de reemitir -- é o D484**, que foi ao lote; o caso `testARespostaPerdidaFicaAnotadaEAChamadaRepetidaReemite` mede o aviso e caracteriza a reemissão, sem decidir. **Mutantes**, um por vez, no MySQL, todos vermelhos: a trava só depois da criação, a emissão só no dia 16, o controller sempre com sucesso e a resposta perdida sem o aviso. A rotina continua sem falar com o Asaas em caso nenhum. #### A trava no banco e a fatura única por vencimento — 07/11/2026 (a fatia 105, ROYALTIES-E-TRAVAS-DO-CRON) **O que faltava, nas palavras de 13/10/2026:** trocar `flock` por `pg_advisory_lock` (a trava de arquivo não protege entre duas máquinas) e a unicidade de `royalties_faturas` (a de `royalties` já estava no `postgres/schema.sql`). As duas entraram, no PostgreSQL, e por isso o débito fica **PREPARADO**: no MySQL de produção nada muda até o corte, e o que entrou só vale com a aplicação no PostgreSQL. - **A trava no banco.** `TravaDeExecucao::obter($nome, $conexao)` ganhou a conexão, opcional. Com ela, e no PostgreSQL, depois do `flock` a trava pede `pg_try_advisory_lock` pela conexão do EntityManager (a chave: os 8 primeiros bytes do sha256 do nome, `chaveNoBanco`), sem esperar, como o `LOCK_NB`; detida por outra sessão, o arquivo é solto e a resposta é `false`, a mesma da execução em curso. O `liberar` solta a do banco antes do arquivo e não reclama se o banco recusar (a transação abortada): a trava de sessão morre com a conexão, no fim do pedido. **O arquivo continua na frente**: é ele quem recusa a segunda execução neste processo (a trava do banco é reentrante na mesma sessão, e o EntityManager é um só). No MySQL fica o `flock`: uma máquina só até o corte, e o `GET_LOCK` valeria para o servidor inteiro, entre bancos. - **As seis rotinas passam a conexão:** `relatoriosRoyaltiesAtualizar` e `relatoriosRoyaltiesFaturasGerar` (no `FranquiaService`), `relatoriosDashboardFaturamento` e `npsContabilizar` (no `CronJobService`), e `marketingEnvios` e `marketingPush` (pelo `CronJobService::acquireLock`, que agora passa a do serviço). As telas e os relatórios que usam a `TravaDeExecucao` sem conexão (as travas por pessoa) seguem só com o arquivo. - **Uma fatura por unidade e vencimento.** Medido antes, só com `SELECT` de contagem: na `franquiabv_dev` do MySQL, 890 faturas, nenhuma sem vencimento e **zero** pares (unidade, vencimento) repetidos; na cópia local do PostgreSQL, também 890 e zero. Sem duplicata, nada a apagar: `royalties_faturas` entrou na lista `$unicidades` de `scripts/gerar-ddl-postgres.php` (com a evidência escrita), o `postgres/schema.sql` foi regerado (uma linha: a restrição `royalties_faturas_inquilino_id_unidade_vencimento_unico`) e o portão `scripts/conferir-unicidade-do-schema.php` a declara (onze unicidades). O `conferir-limpeza-da-unicidade.php` a lê "limpa, e não precisa de bloco". No MySQL ela não entra, como a de `royalties`. **Se até o corte a produção ganhar um par repetido**, a carga da tabela recusa e o `conferir()` do `migrar-dados.sh` aponta; o `scripts/conferir-unicidade.php` já pergunta por ela (esperado 0) — e limpar seria apagar linha, do dono. - **Dois testes mudaram por causa da restrição:** o `FaturasDeRoyaltiesTravaTest` punha duas faturas na mesma unidade e no mesmo vencimento (a segunda foi para a 90001000, que o dublê cadastra no Asaas antes do boleto), e o `RelatorioDeRoyaltiesTest` semeava a repetida da desativada (a 90006905) — agora só no MySQL, onde ela ainda entra e o relatório a conta; no PostgreSQL a conta é zero. **Provado** (os casos novos `D44TravaNoBancoTest`, 16, e três em `FaturasDeRoyaltiesTravaTest`, nos dois bancos, em série): para cada uma das seis rotinas, com a trava detida por outra conexão nesta máquina (nos dois bancos) e só no banco, como a rotina de outra máquina (no PostgreSQL; no MySQL o caso pula dizendo que lá a trava é de arquivo), a rotina desiste; o par das campanhas e da fila do push roda com a trava livre. A própria trava: no PostgreSQL o handle traz a do banco e outra sessão a vê, liberada ela volta, a de outra sessão recusa e solta o arquivo, um nome só trava o nome dele, e com a transação abortada o `liberar` não lança. No PostgreSQL a segunda fatura do mesmo vencimento é recusada pelo banco; no MySQL ainda entra. **Nada saiu da máquina**: o marketing roda com o push e o WhatsApp dublados e as campanhas num instante de 2000; as faturas, com o Asaas dublado. **Mutantes**, um por vez, devolvidos pelo sha1, no PostgreSQL: a trava do banco arrancada da `TravaDeExecucao` (9 casos vermelhos), o `pg_advisory_unlock` arrancado, e a conexão tirada de cada uma das seis rotinas (um vermelho cada, o da outra máquina); a restrição tirada do `schema.sql` (o caso da fatura repetida vermelho, e o portão da unicidade sai 1). O de soltar o arquivo ao desistir ficou verde, e é equivalente: o PHP fecha o arquivo, e solta o `flock`, ao sair do escopo. **Não provado:** duas máquinas de verdade (a outra sessão do banco faz o papel dela); o PgBouncer em modo transação, que quebraria a trava de sessão (hoje não há pooler no desenho da F1.7, e o `DeclararInquilino` já depende da sessão). **A cópia local do PostgreSQL** (a correção da fatia 105, o achado da verificação): a chave entrou só no `schema.sql`, e os bancos que nascem dele (o da suíte, o do contrato e, na janela do corte, o de produção) a tinham; a `franquiabv_dev` do contêiner `franquiabv-postgres-1`, nascida antes, não. Ela a recebeu por `postgres/migracao-royalties-faturas-unica.sql` (só acrescenta: sem par repetido o `ALTER` cria a chave, com par repetido falha e a transação volta; idempotente), rodado duas vezes em 07/11/2026: 890 faturas, zero pares, e a chave `UNIQUE (inquilino_id, unidade, vencimento)`. O caso `FaturasDeRoyaltiesTravaTest::testORoteiroDaCopiaDoPostgresCriaAChave` roda o roteiro duas vezes sobre uma tabela sem a chave (uma temporária com o mesmo nome, como a das conclusões da VIP Class) e confere o nome e as colunas contra o `schema.sql` e a recusa da fatura repetida; com o `ALTER` arrancado do roteiro, vermelho. Não é passo do corte: o MySQL de produção não recebe a chave, e o PostgreSQL de produção nasce do `schema.sql`. **A de `royalties` continua fora da cópia local do PostgreSQL** (o mesmo vão, de 13/09/2026): ali estão os 87 pares do D110 (contados em 07/11/2026), e acrescentá-la pede apagar linha. ### D42 — PHP e MySQL discordam sobre que dia é, três horas por dia — CORRIGIDO E COM PORTÃO em 13/09/2026 — PREPARADO, lido em 05/10/2026 > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito como fechado, e o corpo diz que ele está pronto no código, à espera só do passo em produção na janela da migração final. Falta: ler o relógio do servidor de produção, que nunca foi medido, na janela do corte. Descoberto em 27/08/2026, investigando quatro testes de caracterização que passaram às 19h34 e falharam às 21h. | | | |---|---| | MySQL | `2026-08-27 03:05` — **UTC** | | PHP | `2026-08-27 00:05` — America/Sao_Paulo | São três horas de diferença. Entre **21h e meia-noite** no horário de Brasília, o `CURDATE()` do banco já é o dia seguinte enquanto o `date()` do PHP ainda é hoje. **Qualquer código que misture as duas fontes tem três horas por dia em que elas discordam** — e o sintoma é um resultado vazio, não um erro. Foi assim que apareceu: `royaltiesAtualizar` grava a linha com a data do PHP, e o teste a procurava com `CURDATE()`. #### Onde isso pode doer de verdade **Os cronjobs rodam às 23h**, medido pelos horários das duplicatas do D40 — ou seja, **02h UTC do dia seguinte** para o banco. Todo cron que use `NOW()`, `CURDATE()` ou `CURRENT_DATE` em SQL está calculando para o dia errado, todas as noites. Isso liga a três débitos já registrados. O **D28** — a venda não pode ser registrada na data em que aconteceu — fica pior se o próprio "hoje" for ambíguo. O **D40**, das duplicatas de dashboard, nasce num lote que roda exatamente nessa janela. E a **F1.3** escolheu `timestamptz` justamente para o instante nunca ser ambíguo; esta é a mesma questão, do lado da aplicação. #### MEDIDO em 27/08/2026: produção está alinhada A réplica respondeu `-03:00`, com `NOW()` batendo com o relógio de Brasília: | | | |---|---| | `@@global.time_zone` | **-03:00** | | `NOW()` | 06:15 — horário de Brasília | | `UTC_TIMESTAMP()` | 09:15 | **Não é problema vivo.** Os cronjobs das 23h calculam para o dia certo, e a suspeita de que estivessem uma noite adiantados cai por terra. O descompasso era do **contêiner**: a imagem oficial do MySQL roda em UTC, e o ambiente estava mentindo sobre produção. Corrigido com `--default-time-zone=-03:00` no `docker-compose.yml`, e conferido. #### O que continua aberto, e por que ainda é débito Alinhar o fuso conserta o sintoma e **deixa a armadilha armada**. O problema de fundo é a aplicação misturar duas fontes de relógio: data que ela decide vem do PHP, e `CURDATE()`/`NOW()` em SQL vêm do banco. Enquanto as duas convivem, basta um servidor novo com fuso diferente para tudo voltar — sem erro, com resultado vazio. **Ao resolver:** varrer o código atrás de `NOW()`, `CURDATE()` e `CURRENT_DATE` em SQL e trocá-los por parâmetro vindo do PHP. É pequeno e some com a classe inteira. **Severidade revista:** de "pode estar errado todas as noites" para "está certo hoje, e depende de um detalhe de infraestrutura que ninguém documentou". O `docker-compose.yml` agora documenta. **Ao resolver:** a saída não é só alinhar o fuso do banco — é parar de misturar as duas fontes. Data que a aplicação decide vem do PHP e vai como parâmetro; `CURDATE()` em SQL some. Alinhar o fuso conserta o sintoma e deixa a armadilha armada para o próximo servidor. #### A VARREDURA FOI FEITA em 03/09/2026 — e o débito dizia a verdade: era pequeno O registro previa *"varrer o código atrás de `NOW()`, `CURDATE()` e `CURRENT_DATE` em SQL"* e dizia que era pequeno. Medido: no `module/` inteiro há **três** ocorrências de relógio do banco, e **uma delas é comentário**. Sobram duas: | Onde | O que fazia | |---|---| | `ClienteRepository:712` | a idade, no filtro por faixa etária do relatório de clientes | | `PesquisaRepository:57` | carimbava `dataAlteracao` ao desligar pesquisas do plano de fidelidade | As duas passaram a receber o instante como parâmetro, vindo do PHP. A segunda era a **última escrita do sistema que datava pelo relógio do banco** — todo o resto usa `setDataAlteracao()`, que faz `new \DateTime('now')`. **Não sobrou nenhum `NOW()`, `CURDATE()`, `CURRENT_DATE` ou `CURRENT_TIMESTAMP` em SQL no `module/`.** #### E A TROCA REVELOU UM DEFEITO QUE SÓ APARECIA COM PARÂMETRO Ao pôr o parâmetro no filtro de idade, o PostgreSQL recusou: > `bind message supplies 4 parameters, but prepared statement "" requires 5` A tradução de `TIMESTAMPDIFF` para PostgreSQL escrevia `age(b, a)` **duas vezes** para montar `anos * 12 + meses`. Com os dois lados resolvidos pelo próprio SQL — que era o único uso que existia — nada quebrava. Basta um deles ser parâmetro para o marcador sair duplicado no SQL enquanto o Doctrine liga o valor uma vez só. O defeito estava lá desde que a função foi escrita, e **nenhum teste o alcançava** porque nenhum passava parâmetro. Foi o conserto do D42 que o trouxe à tona. **A correção faz cada argumento aparecer uma vez.** Para `YEAR` a conta some: `age()` já devolve os anos inteiros, respeitando dia e mês — que é exatamente o que `trunc((anos*12 + meses)/12)` calculava. Para `MONTH`, uma subconsulta escalar nomeia o intervalo uma vez e extrai as duas partes dali. **A equivalência foi medida, não deduzida.** Sobre as 242.586 linhas de `clientes` com data de nascimento, as duas fórmulas de `YEAR` divergem em **zero** casos. E as três unidades, com parâmetro, dão o mesmo número nos dois bancos: `YEAR` 60, `MONTH` 722, `DAY` 21.988. **Coberto por `FuncoesDqlDeclaradasTest`**, que ganhou três casos passando parâmetro — um por caminho da tradução (`YEAR` e `MONTH` usam `age()`, `DAY` usa EPOCH). O caso antigo passava `ven.dataCriacao` dos dois lados, e é por isso que nunca acusou. #### FECHADO EM 13/09/2026 — e o que faltava não era o conserto, era o vigia **O defeito não existe mais, e isso foi medido, não suposto.** Varredura por token — não por texto — sobre o código que roda: | alvo | arquivos | ocorrências | |---|---:|---:| | `module/` | 658 | **0** | | `public/` | 4 | 0 | | `config/` | 7 | 0 | | `scripts/` | 70 | 5, e nenhuma é SQL executado | **O que faltava era um portão, e o vão era específico.** `conferir-relogio-nos-testes.php` varre **só `tests/Caracterizacao`** — ele cuida do *momento* (a mesma fonte lida duas vezes, com a virada no meio: o D87). Nada olhava para o código de produção, então um `CURDATE()` novo numa entidade entraria sem ninguém ver. Agora há `scripts/conferir-relogio-do-banco.php`, o **36º do conjunto**, que cuida da *fonte*. **E havia uma ocorrência viva, fora de produção.** `ensaiar-rotas-publicas-do-erp` inseria três vendas com `NOW()` no SQL. Virou parâmetro, e o motivo é duplo: a fonte passa a ser a mesma do resto da casa, **e as três vendas passam a nascer no mesmo instante** — `NOW()` reavalia a cada `INSERT`, e uma virada de meia-noite no meio do laço dataria irmãos em dias diferentes. É o D42 e o D87 na mesma linha. #### ELE LÊ POR TOKEN, e sem isso seria inútil Os comentários desta casa **citam** `NOW()` e `CURRENT_TIMESTAMP()` para explicar o próprio conserto — são **seis linhas em quatro arquivos** (`TimestampDiff.php`, `ClienteRepository.php`, `PesquisaRepository.php`, `Unidade.php`). Um portão escrito por `grep` nasceria **vermelho sobre a documentação do conserto**, e o único jeito de deixá-lo verde seria apagar a explicação. Este olha só literais de texto, que é onde o SQL mora. Conferido: com as seis lá, ele sai 0. **E ele não se acusa.** Este arquivo carrega a lista dos símbolos que procura; entrar na própria lista de exceções — como o irmão faz — obrigaria a recontar a cada palavra mexida no cabeçalho, e portão que quebra quando se edita seu próprio comentário ensina a ignorar o vermelho. #### FALSIFICADO EM TRÊS SENTIDOS | o que se estraga | o que ele faz | |---|---| | `CURRENT_TIMESTAMP()` volta em `ClienteRepository` | sai **1**, nomeando arquivo e linha | | acrescenta-se uma exceção que ninguém usa | sai **1**: *"exceção que não descreve mais o código"* | | o alvo encolhe para um diretório só | sai **2**: *"verde sobre nada não é verde"* | #### O QUE CONTINUA ABERTO, e é o mesmo de antes **O relógio de produção nunca foi medido.** Aqui os dois batem no segundo — `@@global.time_zone` é `-03:00` e o PHP é `America/Sao_Paulo`, conferido hoje. O servidor de produção não foi lido, e por decisão de 11/09/2026 não será até a janela do corte. O número que dimensiona o risco: **48.015 linhas** do banco de desenvolvimento nasceram na faixa das 21h às 24h — 38.050 vendas (1,68%) e 9.965 clientes (4,11%) —, que é a faixa em que duas fontes desalinhadas em três horas datariam o dia errado. O estrago **hoje é zero**, porque não há duas fontes. O número diz o que voltaria a ficar exposto se um servidor novo subisse com outro fuso **e** o código voltasse a misturá-las — e é a segunda metade dessa frase que o portão agora impede. Desconfie de quem esperar 12,5% (3 de 24 horas): 1,68% em vendas é coerente com barbearia que fecha cedo, e 4,11% em clientes também — cadastro pelo aplicativo à noite. --- ### D41 — As campanhas por WhatsApp deixam 3.473 pessoas sem parabéns por ano — PARCIAL, lido em 05/10/2026 — PARCIAL em 12/10/2026: o parabéns não sai no dia de preenchimento (a resposta 114); falta a identidade por telefone (a F1.2) — PARCIAL em 13/10/2026 (a resposta 166) > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito sem marca de estado, e o corpo diz que ele está parcial: uma parte está consertada, e a outra não. Falta: decidir a campanha de parabéns diante das datas inventadas (4.880 mensagens todo 12/12); a identidade por telefone espera a tabela `pessoas` da F1.2. Medido na réplica de produção em 26/08/2026, ao analisar as consultas da F1.4. Três campanhas de cron — parabéns, pesquisa de cliente novo e "sentimos sua falta" — agrupam por telefone para não mandar duas mensagens à mesma pessoa. A consequência é que, quando dois clientes dividem o número, **um deles não recebe**. | | | |---|---| | Telefones com mais de um cliente ativo | **5.670** | | Clientes envolvidos | 13.379 | | Telefones em mais de uma unidade | 1.642 | | Pior caso, num único número | **354 clientes** | | Aniversariantes num dia típico | 557, com 549 mensagens — **8 não recebem** | | **No ano** | **3.473 pessoas** | #### A hipótese do número-lixo foi testada e CAIU Os números mais repetidos não são famílias: | Telefone | Clientes | Unidades | |---|---:|---:| | `+554733692043` | 354 | 2 | | `+55` | 320 | 3 | | `+554799999999` | 193 | 5 | | `+5500000000000` | 61 | **20** | | `+5548999999999` | 31 | 7 | Código de país solto, dígito repetido, tudo zero. É o **D32** — telefone de balcão e preenchimento de campo obrigatório — aparecendo por outro caminho. O raciocínio era: duas pessoas só se anulam se fizerem aniversário no **mesmo dia**; num telefone com dois clientes isso é cerca de 1 em 366, o que daria umas quinze perdas no ano para os 5.670 telefones compartilhados, enquanto um telefone com 354 clientes colidiria consigo mesmo o ano todo. **Medido em 26/08/2026, está errado por duas ordens de grandeza:** | | | |---|---| | Perda em telefones com 10+ clientes | **617** (18%) | | Perda em telefones com menos de 10 | **2.817** (82%) | | Telefones "grandes" | apenas 24 | E os telefones inválidos pela forma são menos do que pareciam: 1.054 curtos demais e 138 com assinante repetido, somando 1.192 números e 1.969 clientes. Ou seja, **a maior parte da perda vem de telefones normais, com dois ou três clientes**. O raciocínio do aniversário coincidente estava certo na aritmética e errado na premissa: ele supõe que os dois cadastros são de **pessoas diferentes**. #### A causa real: `data_nascimento` está tomada de preenchimento automático Medido em 26/08/2026, e não é nenhuma das duas hipóteses anteriores: | | | |---|---| | Colisões que são a mesma pessoa (mesmo nome e data) | 148 | | Mesma data, nomes diferentes | 49 | | **Dia e mês iguais, ANO diferente** | **3.237 (94%)** | Os exemplos dizem o resto: ``` Ulisses Galasse 1980-01-01 15:39:00 01/01 com HORA embutida Wesley Moicano 0001-01-01 00:00:00 ano 1 Dimas Arnold 0000-11-30 10:03:19 data zero do MySQL ``` E a distribuição confirma: **12/12 tem 4.880 clientes** e 01/01 tem 2.012, contra cerca de 660 por dia se fossem aniversários de verdade. **As 3.434 "perdas" são ruído.** Não são pessoas sem parabéns — são cadastros com data inventada colidindo entre si. #### O problema que apareceu no lugar, e é maior **Todo 12 de dezembro o sistema dispara 4.880 mensagens de parabéns**, quase todas para quem não faz aniversário naquele dia. O mesmo em 01/01 e nas outras datas concentradas. Isso não é defeito de consulta: é dado ruim alimentando uma campanha. Cabe ao D32/D41 e não à F1.4, mas a decisão é de negócio — mandar parabéns para quem tem data plausível, ou parar de mandar até a base ser limpa. #### O que isso desenterrou, e é urgente `0000-11-30` em `clientes.data_nascimento` **quebra a carga no PostgreSQL**, que não tem ano zero. Quando isto foi escrito, `scripts/pre-migracao-limpeza.sql` **não cobria essa coluna** — cobria `agendas`, `agendas_fechamentos` e `usuarios.data_contratacao`. > **Fechado desde então**, e conferido em 30/08/2026: o commit `40eabe1` > estendeu a limpeza para `clientes.data_nascimento` e `usuarios.data_nascimento`, > anulando o que estiver abaixo de `1000-01-01`. São 2.395 clientes e 2 > colaboradores. O script anula em vez de inventar um ano, e a razão está escrita > nele: *"não sei quando nasceu" é verdade; "nasceu em 2000" seria invenção — e > invenção aqui manda parabéns no dia errado, que é pior que não mandar*. Passou despercebido por um motivo que vale guardar: **a anonimização reescreve `data_nascimento`**, então na base de desenvolvimento o defeito não existe. A limpeza foi montada procurando coluna por coluna, e encontrou só o que já se sabia. `scripts/medir-datas-invalidas.sql` varre **todas** as colunas de data do catálogo, em vez de procurar as conhecidas. Rodar antes do corte é barato; descobrir no corte custa a janela de migração. #### O que a escolha da linha decide, independentemente disso Vão junto na projeção as credenciais de WhatsApp da unidade. Ou seja, ao escolher a linha o banco decide **qual unidade manda a mensagem**, hoje por sorteio. Para os 1.642 telefones que atravessam unidades, isso é real: quem dá os parabéns ao cliente de Curitiba e Itajaí é aleatório. **Ao resolver:** ver o **D24**/F1.4 para o conserto da consulta, e a tabela `pessoas` da F1.2 para a resposta definitiva — telefone é chave de identidade provisória, e a F1.2 já registrou por quê. --- **Decidido pelo dono em 12/10/2026 (a resposta 114, opção a, a recomendada):** não mandar o parabéns nos dias de preenchimento -- no dia em que os aniversariantes passam do dobro de um dia comum (na réplica, 12/12 e 01/01), a rotina não manda. Quem faz anos de verdade nesse dia fica sem a mensagem. #### O conserto (12/10/2026, o item PDV-E-CADASTRO) `CronJobService::notificarAniversario` conta, antes de ler os aniversariantes do dia, os de cada dia do ano (`ClienteRepository::contarAniversariantesPorDia`, a população da rotina: do Brasil, ativos, com a data, numa unidade com as mensagens) e, no dia de preenchimento (`RegraDoParabens::eDiaDePreenchimento`), não enfileira nada. **O dia comum é a mediana dos 366 dias** (o dia sem ninguém conta zero): o do meio, que os próprios dias de preenchimento não puxam -- a média subiria com eles. Na réplica, perto de 660, e o corte, 1.320: só 12/12 (4.880) e 01/01 (2.012) passam. **Com a mediana em zero** (menos aniversariantes que a metade dos dias do ano), não há dia comum, e a rotina manda sempre: sem isso, qualquer dia com um aniversariante passaria do dobro de zero. A rotina devolve quantos aniversariantes leu (zero no dia de preenchimento), e recebe o dia da conta (a rotina chama sem ele: o de agora). **Na cópia** (`franquiabv_dev`, MySQL, só contagens, 12/10/2026): a anonimização reescreve a data de nascimento, e nenhum dia passa do dobro (o maior tem 794, a média é de uns 707): a rotina mandaria todo dia, como antes. Só a réplica tem o 12/12. **Provado em processo, sem a rotina de envio** (`D41ParabensNoDiaDePreenchimentoTest`, novo, 6 casos), verdes no MySQL e no PostgreSQL, em série: a regra com os números da réplica (só os dois dias passam; o dobro exato não "passa do dobro"; 1.321 passa), o dia sem ninguém contando zero, e a mediana em zero sem dia de preenchimento; a contagem na população da rotina (o de Portugal, o inativo e o sem data não contam, e a hora não importa), igual à que a rotina lê; e a rotina que enfileira, chamada com o dia da conta num ano de um aniversariante por dia e mais cinco num dia: nesse dia ela não lê ninguém, e num dia comum lê o do dia. A unidade do cenário tem as mensagens sem o texto do parabéns: nada vai à fila nos dois casos, e a fila é conferida igual. Quem manda (`marketingPushOutros`) nunca é chamado. **Falsificado** (`medir-mutantes-pdv-cadastro.py`, no rascunho do item: um mutante por vez, o arquivo devolvido e conferido pelo sha256 depois de cada um, contra os 181 casos do filtro do item; o mesmo vermelho no MySQL e no PostgreSQL): | mudança | vermelho | |---|---| | a rotina sem a conta do dia | 1: o dia de preenchimento | | a média no lugar da mediana | 3: os números da réplica (1.321 deixa de passar), o dia sem ninguém e a mediana em zero | | sem a guarda da mediana em zero | 1: a base pequena | | o dia sem ninguém sem contar zero | 1: o dia sem ninguém | | a contagem sem o país da rotina | 1: a população da rotina | **O que fica -- o PARCIAL do título:** a identidade por telefone, que espera a tabela `pessoas` da F1.2 (o resto do corpo, acima). E a base pequena (uma barbearia sozinha, com a conta só nos clientes dela, quando houver mais de um dono): o acaso também passa do dobro, e a pergunta do corte foi ao lote (PDV-E-CADASTRO, o D41). Hoje a conta é a da rede inteira. #### 13/10/2026 — NA BASE PEQUENA A ROTINA MANDA SEMPRE — pela resposta 166 do dono: *"aguarde terminar e continue de forma autonoma a resolver todos os debitos que tiver resposta"* **A resposta 166** (a opção "b", a recomendada): *"A regra do dia de preenchimento do parabéns (a 114) só vale quando o dia comum (a mediana) tem pelo menos 30 aniversariantes; abaixo disso, a rotina manda sempre."* ##### O conserto `RegraDoParabens::eDiaDePreenchimento` só diz "dia de preenchimento" com o dia comum de 30 aniversariantes ou mais (a constante `MINIMO_DE_UM_DIA_COMUM`, o número do dono); abaixo disso, nunca, e a rotina (`CronJobService::notificarAniversario`) manda como mandava antes da 114. A guarda da mediana em zero ficou dentro da nova. O dobro e a mediana não mudaram. **Na rede inteira nada muda:** na réplica o dia comum é perto de 660; na cópia (`franquiabv_dev`, só contagens, 13/10/2026), 708,5 (o maior dia, 794; o menor, 218). ##### Provado `D41ParabensNoDiaDePreenchimentoTest` (de 6 a 9 casos), verdes no MySQL e no PostgreSQL, em série, em processo e **sem a rotina de envio**: a regra com o dia comum de 29, 29,5, 5 e 1 (nenhum dia é de preenchimento, nem o de 1.000) e com o de 30 (61 passa, 60 é o dobro exato e não passa); e a rotina que enfileira, chamada com o dia da conta, numa unidade com as mensagens sem o texto do parabéns (nada vai à fila, conferida igual): num ano de 30 aniversariantes por dia (10.980 clientes, num `INSERT` de várias linhas) e mais 40 num dia, nesse dia ela não lê ninguém e num dia comum lê os 30; num ano de um por dia e mais cinco num dia -- a base pequena --, ela lê os seis desse dia (até esta data, nenhum). Quem manda (`marketingPushOutros`) nunca é chamado. | mutante (sozinho, restaurado e conferido pelo sha256; `medir-mutantes-r30.py`, no rascunho do item) | vermelho, no MySQL e no PostgreSQL | |---|---| | a regra de antes (só a mediana em zero desliga) | 2: o dia comum abaixo de 30; a base pequena na rotina | | "mais de 30" no lugar de "pelo menos 30" | 2: o dia comum de 30; o dia de preenchimento na rotina (a base grande tem 30 por dia) | **O que fica -- o PARCIAL do título:** a identidade por telefone, que espera a tabela `pessoas` da F1.2 (o resto do corpo, acima). A base pequena está respondida. ### D39 — A view `v46` existe em produção e ninguém sabe para quê — PREPARADO, lido em 05/10/2026 > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito sem marca de estado, e o corpo diz que ele está pronto no código, à espera só do passo em produção na janela da migração final. Falta: executar em produção, na janela, o `DROP VIEW IF EXISTS v46`, que já está em `scripts/pre-migracao-limpeza.sql`. Descoberta em 25/08/2026, comparando a homologação recém-carregada com o `mysql.sql` do repositório: produção tem um objeto a mais, chamado **`v46`**. Não é tabela — é uma **view**, e isso apareceu do jeito mais indireto possível. Qualquer consulta a ela falha aqui com: ``` ERROR 1449: The user specified as a definer ('andre'@'%') does not exist ``` Ou seja, ela foi criada por um usuário que não existe na homologação, e o MySQL recusa executá-la antes mesmo de olhar a definição. Em produção o `andre` existe, então lá ela responde normalmente e nunca deu sinal de vida. **Nenhum arquivo do repositório menciona `v46`** — nem código, nem script, nem SQL. Pelo nome, cheira a sobra de versão: alguém congelou uma consulta antes de um deploy e não voltou para apagar. **O que impede de simplesmente apagar:** o código não é a única coisa que fala com esse banco. Ferramenta de BI, planilha conectada, relatório externo — nada disso apareceria numa busca no repositório. Antes de remover, é preciso confirmar com quem opera. **Por que importa na migração:** views não vêm no DDL gerado pela F1.3, que foi construído a partir do `mysql.sql`. Se `v46` estiver em uso por algo fora do código, ela some no corte da F1.8 e o sintoma aparece longe da causa — um relatório que para de abrir, dias depois, sem ninguém ligar as duas coisas. **RESPONDIDO em 25/08/2026:** o responsável confirmou — sobra de deploy antigo, sem consumidor. O `DROP VIEW IF EXISTS v46` entrou em `scripts/pre-migracao-limpeza.sql`, depois do `COMMIT`, porque DDL no MySQL provoca commit implícito e estragaria a atomicidade dos UPDATEs acima. Fica aberto só enquanto produção estiver congelada; é uma linha para executar, não um problema para resolver. **O que este débito ensina, e vale além dele:** o `mysql.sql` do repositório não descreve produção inteira. Views, rotinas e eventos não estão lá, e a comparação que expôs isso só existiu porque a homologação foi carregada a partir da réplica, não do arquivo versionado. Antes do corte da F1.8, a mesma comparação precisa ser feita para rotinas e gatilhos — ver **D37**. **Ver a definição sem esbarrar no `DEFINER`:** ```sql SELECT view_definition FROM information_schema.views WHERE table_schema = DATABASE() AND table_name = 'v46'\G ``` --- ### D37 — Produção não está sob controle de versão — PARCIAL em 08/11/2026: o roteiro de publicar está escrito e ensaiado num contêiner; nunca rodou em servidor, e a produção segue sem git Informado pelo responsável em 19/08/2026: o servidor de produção não tem git — o que existe é cópia do código, com backup em drive. Isso explica algo que vinha incomodando na redação de vários débitos. D1, D2 e D3 estão marcados como "corrigido no código, pendente em produção" desde o começo, e o que faltava não era decisão: **é que não há caminho de entrega.** Deploy, aqui, é cópia manual de arquivo. #### O risco imediato, e é sério O repositório nasceu de uma cópia de **julho de 2026**. Se alguém alterou qualquer coisa direto no servidor desde então, essa alteração **não está no repositório** — e um deploy por cima a apagaria, em silêncio, num sistema onde defeito significa dinheiro errado. **Nenhum deploy pode acontecer antes de saber se produção divergiu.** `scripts/comparar-com-producao.sh` gera a impressão digital do código do servidor para essa comparação. É somente leitura. #### O que isso não bloqueia Vale separar, porque a maior parte da remediação do Dia 0 **não depende de deploy**: | Passo | Precisa de deploy? | |---|---| | 1 — tirar os arquivos do webroot | **Não.** É `mv`, feito pelo script | | 2 — apurar acesso nos logs | **Não** | | 3 — criar o `local.php` | Não, é arquivo novo | | 4 — código corrigido | **Sim** — e só depois da comparação | | 5 — rotação de credenciais | Não, é painel de provedor | | 6 — bloquear a rota no nginx | Não, é configuração de servidor | Ou seja: **o que está exposto agora pode ser fechado hoje**, sem esperar deploy nenhum. O passo 4 é o único que espera. #### Ao resolver Colocar produção sob git é o certo, e não é trabalho grande — mas exige decidir o fluxo (quem faz merge, como se faz rollback, o que acontece com o `local.php`) e comparar antes, para o primeiro commit registrar o que **está rodando**, não o que se supõe que rode. Enquanto não houver, todo deploy passa pela comparação de impressão digital, e essa é a regra que evita perda silenciosa. #### PARCIAL em 08/11/2026 -- o roteiro de publicar na produção (a fatia 129 da fila dos débitos, DEPLOY-TESTE-E-PUBLICAR) Pelas respostas 200 (c), 201 (a) e 206 (a), a entrega na produção é por um roteiro de publicar, que não existia (o item 9 de "O que falta" da `docs/procedimento-de-corte-etapa-1.md`). **Escrito, e nunca rodado em servidor nenhum:** `scripts/publicar-producao.sh`, no molde do `deploy-teste.sh`. - `montar `, na sua máquina: o `git archive` do commit; o `composer install` numa imagem do `docker/php/Dockerfile`, com o freio do teste (nada fora do `vendor/` muda); a build com `--base=/novo/` num contêiner `node:22-bookworm-slim`; a impressão digital do `` (o que a produção roda: na janela da etapa 1, o `eaf1fca5`, a importação) pelo `comparar-com-producao.sh`; e recusa levar `local.php`, `.env`, `ensaios/` ou cópia anonimizada. Sai o pacote e o `.sha256`, e os comandos de copiá-lo. - No servidor, como root: `levar` (o sha256, o disco, a release em `public_html.novo` com o dono root e o `local.php` `root:` 640); `trocar` (o da janela: o `data/` por `cp -aT`, os proxies do Doctrine apagados, as pastas de upload e o avatar por `mv -T`, as três imagens padrão comparadas, o `app.json` de lá, as graváveis do pool, a troca de nome com a árvore de antes inteira ao lado -- `public_html.antigo-` na primeira vez, `public_html.anterior-` depois -- e a tela nova com a troca atômica do `trocar_front`; para antes do PHP-FPM, porque a janela tem os `.sql` do passo 7 e o vhost do 8 no meio); `entregar` (o das entregas: o `trocar`, o recarregar do PHP-FPM e a conferência sem escrever do passo 10 -- o `verificar-local-php.php`, o 401 do `npsContabilizar` sem token e o `/novo/` com a build); e `voltar` (a liberação anterior, as pastas e a tela nova de volta; entre duas releases, com o PHP-FPM recarregado e a que sai em `public_html.devolvida-`; **na volta ao código antigo, na ordem de "A volta" do procedimento**: a que sai em `public_html.novo-`, o nome de lá, e **sem** recarregar, que vem depois do `devolver-nomes` do item 4, cujo caminho ele imprime; e, se a troca parou nas pastas, só as pastas de volta, sem tocar o `app.json` de lá). - **Antes de mexer, quem recusa o quê** (a primeira versão dizia "cada um recusa" tudo, e não era assim): | | hora | manutenção | cron | rotinas | impressão | |---|---|---|---|---|---| | `levar` | sim | -- | -- | -- | -- | | `trocar`, `entregar` | sim | sim | sim | sim | sim | | `conferir` | sim | sim | sim | com a release ao lado | com a release ao lado | | `voltar` | -- | sim | sim | sim | -- | O `levar` é o passo 1, que vem antes da manutenção do 2; o `voltar` é o caminho de sair, a qualquer hora. **A hora:** depois das 00:05 e até a `HORA_LIMITE` da 206 (a), e a entrega que, pelo ensaio, não cabe (agora + `ENTREGA_MIN` > `HORA_LIMITE` − `VOLTA_MIN`). **A manutenção, carregada no `nginx -T`** -- e ela não existe (o item 10): **sem ela, nada troca**. **O cron:** o crontab do root sem linha ativa, o `/etc/cron.d` sem chamar o site (a linha que a recusa mostra sai sem o token, nas duas formas: `token=` e o `Authorization: Bearer` da forma nova), e o `CRONTAB_GUARDADO` **sem padrão**, desta noite (menos de 12 horas), e numa entrega depois da etapa 1 **nunca** o `/root/crontab-antes-do-corte.txt` da janela, que a volta ao código antigo religa; na volta ao código antigo, só ele. **As rotinas:** conexão no `SHOW PROCESSLIST` do usuário do `local.php` da release ao lado, do da árvore no ar e, com o código antigo no ar, do `USUARIO_DB_NO_AR` (obrigatório: a leitura 10 diz que o `local.php` da release pode trazer outro usuário), ou do dump, ou um dump rodando, depois da espera (o sinal do passo 2). **A impressão:** a produção divergente da do ``, listando cada arquivo (diferente, só no servidor, só no repositório) -- o que este débito pede ("nenhum deploy antes de saber se produção divergiu"); só passa o caminho que o dono aceitar num arquivo (`DIFERENCAS_ACEITAS`). E a volta ao código antigo só com o bloqueio do `migrar-senhas` no `nginx -T` (o item 2 de "A volta"). **O ensaio** (`scripts/ensaiar-publicar-producao.sh`, no `conferir-tudo.sh`; fora do CI, que não tem a imagem do app nem o histórico): o `montar` de verdade com um `docker` de mentira (o `vendor/` daqui, sem rede), e o resto num contêiner descartável, sem rede, com uma produção de mentira (a árvore do `eaf1fca5`, pastas de upload e `data/` inventados, fotos no avatar, um `app.json` mudado) e dublês do nginx, do cron, do MySQL, do PHP-FPM e do relógio: 41 casos (eram 18; a verificação da fatia acrescentou 23) -- as recusas do `levar` (às 23:50 e às 00:02, as duas metades da guarda de hora), do `entregar`, **do `trocar`** (o subcomando da janela, que não tinha nenhuma) e **do `voltar`** (nas duas metades: sem a manutenção, com o cron, com conexão, sem o bloqueio, com o crontab de uma entrega, com uma volta parada no meio); o guardado sem padrão, velho e o da janela numa entrega; o `USUARIO_DB_NO_AR` e as conexões dele e do `local.php` no ar; a linha da forma nova sem o token; a troca que para nas pastas e a volta dela, a entrega e a volta cronometradas (a volta ao código antigo sem recarregar, com o `devolver-nomes` pela `public_html.novo-`), e a segunda entrega sobre a primeira pelo `trocar`, com a volta entre as duas recarregando. **Os tempos daqui** (um pacote de cerca de 28 MB): desempacotar ao lado em cerca de 0,6 s, a entrega em cerca de 0,7 s e a volta em cerca de 15 ms -- com 120 MB de upload e 40 MB de `data/`, e de novo com 340 MB e 300 MB (0,8 s e 19 ms): trocas de nome e uma cópia do `data/`. **Não são os da produção:** o ensaio da sua 199 (a), no BVIP, dá os números que entram em `ENTREGA_MIN` e `VOLTA_MIN`. Mutantes, um por vez, cada um vermelho: sem a manutenção, sem a hora no `levar`, sem a impressão, `cp -a` no lugar do `mv -T`, o dono do pacote mantido, a volta sem as pastas, o `app.json` do repositório na volta do meio, sem o cron, sem a conta da hora-limite, o `local.php` contado na impressão, e a espera sem as conexões. Os 19 da verificação, cada um vermelho: o padrão do guardado de volta, sem a idade, sem a recusa do da janela numa entrega, sem a do da entrega na volta ao antigo; sem exigir o `USUARIO_DB_NO_AR`, sem contá-lo, sem o `local.php` no ar; sem o bloqueio; a volta ao antigo recarregando; o `devolver-nomes` pela árvore no lugar; o nome `devolvida-` na volta ao antigo; o `trocar` sem as conferências; o `voltar` sem a manutenção, sem o cron, sem as rotinas (em cada metade), sem a recusa da volta parada; a hora sem o "depois das 00:05"; e o `sed` de antes, que deixava o `Bearer` inteiro. **O que falta, e por isso PARCIAL:** a produção segue sem git (o "Ao resolver" de cima); o roteiro nunca rodou num servidor; **a página de manutenção** (o item 10), sem a qual ele recusa; o ensaio no BVIP (a 199 (a)), que dá os tempos de verdade; os nomes a medir da leitura 7 (o serviço do PHP-FPM, o usuário e o grupo do pool), o usuário do banco do código antigo (a leitura 10, o `USUARIO_DB_NO_AR`) e a raiz da tela nova do vhost novo (o item 5), que ele pede como variáveis e não adivinha; e o "com ou sem as dependências de desenvolvimento" do composer, que segue a medir (ele instala como o teste, com elas). O dono revisa o roteiro antes da janela. ### D36 — `app.json` é configuração morando em arquivo — PARCIAL em 20/10/2026: um gravador só, e a tela nova recria o arquivo Levantado em 19/08/2026, ao terminar a F1.5. `public/app.json` tem **77 bytes** e guarda quatro campos: versão do aplicativo (major, minor, patch) e o liga-desliga do push. ```json [{"push":"inativo","versao_major":"2","versao_minor":"0","versao_patch":"8"}] ``` É lido por `/api/versao/app` a cada abertura do aplicativo, e escrito por duas telas de administração. **Não é upload de usuário — é configuração.** **Por isso não deve ir para armazenamento de objetos.** Seria uma ida à rede, a cada abertura de app, para buscar 77 bytes. O lugar certo de configuração é o banco, que já é replicado e transacional. #### Destravado: ninguém busca o arquivo pela URL A dúvida era se o aplicativo buscava `/app.json` direto — o arquivo é servido, já que a regra de bloqueio do nginx cobre `.txt`, `.log` e `.sql` mas não `.json`. Medido em 14 dias de log de produção: | | | |---|---:| | Requisições diretas a `/app.json` | **0** | | Requisições a `/api/versao/app` | 11.032 | | Requisições a qualquer `/api/` | 236.785 | As duas últimas linhas são o que dá valor à primeira: sem elas, o zero poderia significar log errado em vez de ausência de uso — e foi exatamente isso que aconteceu na primeira tentativa de medir, quando o glob cobria só `access.log*` e o site tem log próprio por vhost. **Conclusão:** o arquivo pode sair do disco e virar configuração no banco, sem período de transição e sem risco para as versões antigas do aplicativo. **Prioridade baixa mesmo assim, pelo modo de falha.** Sumindo numa promoção, `selecionarVersaoAction` devolve `sucesso: false` e o aplicativo fica sem informação de atualização — degradado, não quebrado, e um administrador refaz em trinta segundos pela tela. Comparar com o **D33**, onde o que some é contrato e certificado, que ninguém refaz. **Correção de registro (03/10/2026):** o "refaz em trinta segundos pela tela" está errado. As duas telas que escrevem o arquivo só abrem se ele existir: o `file_exists` cerca a ação inteira (`module/ISConfiguracao/src/Controller/AppConfiguracoesController.php:37` e `:85`), e sem o arquivo as duas respondem 404 (`:78` e `:122`). Sumindo o arquivo, ninguém o refaz pela tela -- só no disco. Achado pelo desenho da Versão do aplicativo (`docs/f3-telas-restantes/tela-versao-app.md`, Dnovo-4), cuja fatia 1 faz a tela nova recriar o arquivo; e o **D354** registra as outras duas formas de o arquivo ficar errado com a tela dizendo sucesso (o campo vazio publica 0.0.0, e um byte inválido o esvazia). **Ao resolver:** tabela de configuração no banco e trocar os três pontos de código. Como a medição mostrou uso zero da URL, não é preciso continuar servindo o arquivo. #### PARCIAL em 20/10/2026 -- a fatia 23 da fila das telas que faltam, VERSAO-DO-APLICATIVO **O que mudou:** o arquivo passou a ter um gravador só, `ISConfiguracao\Service\RegistroDoAplicativo` -- a versão e o Push gravam por ele, sob a trava e por `rename` (o D354) --, e a tela nova (Configurações › Aplicativo › Versão, sobre a `/adm/api/aplicativo/versao`) o recria quando ele falta: diz "Hoje o aplicativo recebe “sem informação de versão”", e publicar refaz o registro com o `push` "inativo". O Dnovo-4 do desenho fica aqui: o "refaz pela tela" passou a ser verdade pela tela nova; as duas antigas continuam 404 sem o arquivo, de propósito. Quem mudou e quando fica num histórico só de acréscimo, `data/aplicativo/historico.jsonl`, fora de `public/` e ignorado pelo git (o D548). **O que falta (o corte, como estava decidido):** a tabela de configuração no banco. Os pontos de código passaram de três para dois -- o gravador e o leitor congelado do `/api/versao/app` (`AplicativoController::selecionarVersaoAction`) --, e o histórico vai junto na importação. Nenhum esquema mudou nesta fatia, e nada entrou no passo 0. ### D35 — Adiada a migração do visagismo para a abstração Decisão do responsável em 19/08/2026: não migrar o `visagismo` agora. São **7 pontos de escrita** em 4 arquivos (`ISApi` e `ISCadastro`, serviço e controller), num fluxo que fala com API externa de geração de imagem — mais superfície e mais risco que os outros, e nenhum teste automatizado cobrindo. **O que já foi feito e não espera:** o furo de segurança do D34 está corrigido — `public/visagismo` entrou na regra de nginx que impede execução de PHP em diretório de upload. Isso era o urgente; a migração para a abstração é arrumação. **Consequência de adiar:** aquele diretório continua gravando no disco local mesmo depois de os outros passarem para armazenamento de objetos. Numa promoção, as imagens de visagismo somem junto — soma-se ao D33, não é um problema novo. **Ao resolver:** mesmo padrão dos demais — `Armazenamento::padrao()->guardar()` com caminho lógico `visagismo/...`. O cuidado extra é que o caminho aparece **na resposta da API** (`VisagismoController`, `VisagismoService`), então o aplicativo recebe a URL montada — trocar o destino sem trocar a URL devolvida quebra a exibição no app. ### D33 — Arquivos ficam fora do failover — PARCIAL, lido em 05/10/2026 — PARCIAL em 08/11/2026: a foto do colaborador sai pelo `Armazenamento` nas telas e na API; seguem à mão os banners da API e as capas dos assistentes; a agenda da V4 manda só o nome; a virada pede a `url_publica` > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito sem marca de estado, e o corpo diz que ele está parcial: uma parte está consertada, e a outra não. Falta: contratar o destino, migrar o `app.json`, trocar as URLs de leitura (9 `.phtml` e a API), subir os 346 MB e virar o driver. Decisão do responsável em 19/08/2026: o armazenamento de objetos fica no servidor local por ora, com a distribuição em nuvem adiada. **Consequência:** a camada de arquivos não é coberta pelo failover automático da F1.7. Numa promoção, o nó novo sobe funcionando e **sem** contrato, certificado, banner, material do VIP Class e foto de colaborador — 346 MB em 1.146 arquivos, com o caminho gravado no banco apontando para o vazio. É lacuna conhecida e aceita, não descoberta. A diferença entre as duas é justamente este registro. **O custo de resolver já está pago.** A abstração `Armazenamento` está pronta e testada contra MinIO, e o driver fala o protocolo S3 — que MinIO, Cloudflare R2, Backblaze B2 e o Google Cloud Storage em interoperabilidade entendem. Virar a chave é editar `config/autoload/local.php`, sem tocar em código. #### O que será necessário implementar, em ordem Registrado a pedido, para o trabalho futuro não depender de memória. **1. Contratar e configurar** — escolher o destino (`f1-5-armazenamento.md` compara custo e durabilidade; para 346 MB são centavos por mês), criar o balde e as credenciais, e preencher a seção `armazenamento` em `config/autoload/local.php`. Nenhuma linha de código. **2. Terminar de migrar os pontos de escrita.** Feito: `arquivos`, `banners`, `assistentes`, `vip-class/capas`, `vip-class/certificados`. Falta: | Onde | Pontos | |---|---:| | ~~`vip-class/materiais`~~ | feito | | ~~`layout/img/avatar`~~ | feito | | `app.json` | 3 | | `visagismo` | 7 — adiado, ver **D35** | Sobre o avatar: só o **final** passa pela abstração. O `cache/`, onde mora o arquivo entre o envio e o recorte, fica local de propósito — é rascunho que morre em segundos, e mandá-lo para a rede seria pagar latência à toa. **3. Resolver as URLs de leitura — é o item que costuma ser esquecido.** Gravar no lugar novo não adianta se a tela continua pedindo o antigo. Hoje o caminho é montado à mão em pelo menos **9 arquivos `.phtml`** e no retorno da API. Todos precisam passar a usar `Armazenamento::padrao()->url()`, que já existe e já devolve o endereço certo em cada driver. *Nota de 05/11/2026 (a fatia 79; o D712):* a VIP Class do aluno passou: a capa do cartão pelo `url()`, e o fundo do certificado e o material lidos pelo `Armazenamento` (o material vai ao endereço direto do bucket quando há a `url_publica`). Seguem escritos à mão a capa e o certificado da administração e a capa do relatório da VIP Class (o D712). *Nota de 08/11/2026 (a fatia 130, PREPARO-DO-PHP-E-DO-ARMAZENAMENTO):* a nota de 05/11 ficou velha -- o D712 fechou a VIP Class inteira. **A foto do colaborador passou**, nos sete pontos que a montavam à mão (o `grep` por `img/avatar`; a triagem listava seis, e o sétimo é o endereço que a tela recebe depois do recorte): o topo do ERP (`layout.phtml`), a lista e a foto do usuário (`usuarios/index.phtml` e `usuarios/editar-foto.phtml`) e o `UsuarioService::definirImagem` pelo `url()`; e as três respostas da API do aplicativo -- a agenda do cliente e o consumo dele (`AplicativoController`) e a lista de colaboradores da unidade (`UnidadeRepository::getUnidadeColaboradoresServicos`) -- pelo `urlCompleta($caminho, $prefixoLocal)`, novo no `Armazenamento`: **no disco, a URL sai byte a byte a de sempre** (o prefixo que cada resposta colava, inclusive as duas barras de `https://franquiabv.com.br//layout/img/avatar/...` da lista de colaboradores), e no bucket é o `url()` dele. Os snapshots do contrato só conferem o tipo (`"string"`): quem prende os bytes é o `D33EnderecoDaFotoPeloArmazenamentoTest` (9 casos, nos dois bancos: no disco, a API igual à fórmula antiga e as telas pedindo ao site; no bucket com a `url_publica`, as três telas, as três respostas e a foto recortada apontando para ele). Nas telas, o `src` passou a sair pelo `escapeHtmlAttr`: o mesmo endereço para o navegador, e a coluna `imagem` deixou de ir crua ao HTML. **Seguem escritos à mão:** a URL dos banners na API do aplicativo (`AplicativoController::bannersSelecionarAction`, `$url . "banners/"`), que o `BannersPelaApiTest` prende ao `sistema.url` de propósito desde a fatia 22 -- passá-la ao `urlCompleta` é a mesma troca, e pede reescrever aquele caso; as capas dos assistentes (`assistentes-usuarios/index.phtml:29` e `assistentes-admin/capa.phtml:38`), que esperam o dono com as fatias 87 a 89; e o `app.json` (o D36). Os passos 1, 4 e 5 (contratar, subir os arquivos e virar o driver) são do dono e do corte. *Na correção da fatia 130 (08/11/2026), duas coisas que a nota de cima não dizia:* **(1) a virada passa a pedir a `url_publica`** (ou um bucket de leitura pública). Antes, a foto era sempre pedida ao site; agora as telas e a API pedem o endereço ao `Armazenamento`, e sem a `url_publica` o `ArmazenamentoS3::url()` devolve o endereço cru do bucket, que o navegador e o aplicativo pedem sem assinatura -- com o bucket privado, o normal no R2 e na AWS, as fotos (no `franquiabv_dev`, 1.498 usuários com `padrao*` e 934 com `avatar_*`) somem nas três telas e no aplicativo. Está no passo 0 de "Migrar os 346 MB" em `docs/f1-5-armazenamento.md`, com os três `padrao*` versionados em `public/layout/img/avatar/`, que também precisam subir, e no comentário da classe; que o endereço cru dê 403 depende da política do bucket, e não foi medido. **(2) A agenda da API nova fica de fora:** `GET /api/v4/clientes/:id/agenda` (`V4\ClientesController::agendaAction`) devolve só o nome do arquivo (`colaboradorImagem`, `avatar_12.jpg?abcd`), e quem a consome monta o endereço a partir do site -- o `grep` por `img/avatar` não a acha, porque ela não tem o caminho. Trocar pede mudar o contrato (o snapshot `v4-clientes-agenda-autenticado.json`), e nenhum aplicativo fala o `/api/v4` ainda (o D59): o caminho, quando o aplicativo novo for escrito, é um campo com o endereço pronto pelo `urlCompleta`, como a convenção da API manda. Os dois ficam neste débito até lá. O caminho que aparece **na resposta da API** é o mais sensível: o aplicativo móvel recebe a URL pronta, e há versões antigas em campo (**D5**) que não podem ser atualizadas junto. A URL antiga precisa continuar funcionando durante a transição — na prática, o nginx segue servindo `public/` como está, e só depois de o parque renovar é que aquele caminho sai. **4. Subir os 346 MB existentes**, preservando o caminho lógico, e conferir contagem e resumo de cada arquivo antes de virar a chave. **5. Virar o `driver` no `local.php`.** **6. Manter o disco local intacto por algumas semanas.** É o que torna a virada reversível: se algo escapou, o arquivo ainda está lá. **7. Backup do novo destino.** Armazenamento de objetos não se faz sozinho — ativar versionamento ou replicação no provedor, e incluir no plano de contingência. Hoje os arquivos dependem do `sistemacompletofbv.sh`, diário. #### O que NÃO será necessário Vale registrar para dimensionar: **nenhuma mudança nos serviços já migrados.** A abstração existe justamente para isso, e o driver S3 já está escrito e testado contra MinIO. Os itens acima são configuração, URLs de leitura e cópia de arquivo — não reescrita. **Enquanto não resolver:** o backup dos diretórios de `public/` passa a ser parte do plano de contingência, não conveniência. Hoje o `dumpv3.sh` cobre o banco de hora em hora; os arquivos dependem do `sistemacompletofbv.sh`, diário. ### D31 — Logins e CPFs duplicados em produção — PARCIAL em 08/10/2026: os logins e e-mails repetidos vão ao passo 3 do corte; os dois ativos e os CPFs são do dono Levantado em 19/08/2026, na coleta de produção. É a resposta que faltava para o D29, e ela é pior que o esperado. | Coluna | Valores repetidos | Linhas envolvidas | |---|---:|---:| | `usuarios.login` | 159 | **389** | | `usuarios.email` | 144 | 316 | | `clientes.cpf` | 348 | **1.483** | | `unidades.hash` | 0 | 0 | O `hash` estar limpo é a boa notícia: era o mais perigoso, porque autentica as rotas `/api/unidade/vendas*`. > **ESTES NÚMEROS NÃO PODEM SER REMEDIDOS NA CÓPIA LOCAL, e quem tentar vai > achar zero.** Medido em 31/08/2026: a anonimização reescreveu **todas** as três > colunas para valores únicos. > > | Coluna | Linhas | Distintas | > |---|---:|---:| > | `usuarios.login` | 2.427 | **2.427** | > | `usuarios.email` | 2.427 | **2.427** | > | `clientes.cpf` | 242.586 | **242.586** | > > Zero duplicatas locais **não é evidência de conserto** — é evidência de que a > anonimização funcionou. Os 159, 144 e 348 acima são números de produção, de > 19/08/2026, e só a produção pode confirmá-los ou desmenti-los. > > Isto está escrito aqui porque eu mesmo caí nele em 31/08: fui remedir os > logins duplicados para avaliar o **D72**, achei zero, e por um instante li > aquilo como "o problema não existe". #### Apurado em 19/08: o login NÃO é falha de autenticação Eu havia levantado a hipótese de que os logins duplicados quebrassem a autenticação, já que o Laminas usa `login` como propriedade de identidade. A segunda coleta desmente: | | | |---|---:| | Logins com **mais de um usuário ativo** | **0** | | Linhas ativas entre as 389 | 1 | | Linhas inativas | 388 | Ou seja: toda duplicata de login envolve colaborador **desligado**. A autenticação hoje é determinística, e o problema é de higiene de cadastro, não de segurança. **Retiro a gravidade que atribuí.** Fica um risco condicional: reativar um colaborador antigo cujo login coincida com o de alguém ativo cria a duplicata entre ativos, e aí vira falha de verdade. A restrição de unicidade é o que impede isso. #### O CPF é o oposto: quase todos ativos | | | |---|---:| | Clientes em CPF duplicado | 1.483 | | **Ativos** | **1.451** | Aqui não é higiene: são 1.451 clientes ativos que quase certamente são **cadastro duplicado da mesma pessoa**, cada um com sua pontuação e seu histórico. Fundir exige somar saldo e preservar as duas trilhas. **Consequência imediata para o D29:** as restrições de unicidade **não podem ser criadas** na F1.3 como estava planejado. O `CREATE UNIQUE INDEX` falharia. A ordem passa a ser: apurar, limpar, e só então restringir. **Ao resolver:** decidir caso a caso o que fazer com cada duplicata — e isso é decisão de negócio, não de banco. Dois colaboradores com o mesmo login podem ser a mesma pessoa cadastrada duas vezes, ou dois cadastros que precisam de logins distintos. O mesmo vale para os 1.483 clientes com CPF repetido, que provavelmente são cadastro duplicado da mesma pessoa — e aí a fusão precisa somar pontuação e preservar histórico dos dois lados. **Decidido pelo dono em 06/10/2026** (lote de perguntas, pergunta 8): a opção (b), "Renomear o login do inativo de cada par, e baixar a caixa de todos" -- ninguém ativo muda de login, e o par com dois ativos fica com o dono, um a um. Entrou no roteiro do corte: no passo 3, os quatro `UPDATE` do fim de `scripts/medir-logins-com-maiuscula.sql` (o inativo de cada par ganha `.inativo` no login, e no e-mail no par de e-mails; depois a caixa de quem ficou sem par baixa), e a listagem 4c, no 5 de "O que hoje bloqueia", dá antes da janela os ids de quem tem mais de um ativo no mesmo login ou e-mail. Ensaiado em `scripts/ensaiar-sql-do-passo-3.php`, no 8.4.11 e no 8.0.46, com usuários inventados; o par é só a caixa -- o par que só difere pelo acento não é tocado (a revisão de 06/10/2026, ver o D349). **O que a decisão não alcança:** o repetido EXATO de login -- uma grafia só, que a conta de 19/08 não separou dos pares -- não é par de caixa, e fica como está: não piora com a caixa baixa, mas impede o índice único do D295; a pergunta de estender o renomear a ele está no lote. E os 1.483 clientes com CPF repetido continuam do dono, caso a caso. **Decidido pelo dono em 07/10/2026** (pergunta 32 da página do lote): a opção (a), "A mesma regra para eles" -- "Sobra só o caso de dois ativos, que já é seu, e o índice fica possível depois da janela." Entrou no roteiro do corte em 08/10/2026: os dois `UPDATE` do renomear de `scripts/medir-logins-com-maiuscula.sql` agrupam pelo minúsculo byte a byte com "mais de uma linha" (`COUNT(*) > 1`), e não mais "mais de uma grafia" -- o inativo do repetido exato, de login e de e-mail, ganha `.inativo` como o do par de caixa --, e o e-mail vazio fica fora do grupo (não é e-mail repetido; sem o filtro, o inativo de e-mail vazio virava `.inativo` sozinho). A listagem nova 3b conta os repetidos exatos por estado, a 4 dá também os ids deles (com a coluna `grafias`), e a 4b conta o renomear dos dois tipos. O passo 3 e o 5 de "O que hoje bloqueia" do procedimento dizem isso. **Provado** em `scripts/ensaiar-sql-do-passo-3.php`, no 8.4.11 e no 8.0.46 (um contêiner descartável, sem porta publicada, apagado no fim): dez usuários inventados a mais -- o repetido exato com um ativo e um inativo, o de dois ativos com um inativo, o de dois inativos, o e-mail exato com um inativo, o de dois ativos e um inativo de e-mail vazio --; os quatro `UPDATE` mudam 8, 2, 5 e 2 linhas (eram 4, 1, 5 e 2) e nada na segunda vez, e cada usuário fica como o ensaio escreve; depois deles, o que ainda se repete pelo minúsculo byte a byte são só os ativos da 4c (106/107 e 125/126 no login, 116/117 e 130/131 no e-mail); e o índice único do login, na chave da entrada do PostgreSQL (`CAST(LOWER(login) AS BINARY)`, a do D349), é recusado com eles e nasce sem eles. **Falsificado**, um mutante por vez em cópias dos roteiros (o `--scripts` do ensaio; os arquivos de verdade não mudaram), com o mesmo vermelho nos dois MySQL: o roteiro de 06/10/2026 inteiro (6 vermelhos), o renomear do login de volta a "mais de uma grafia" (4), o do e-mail (3), o do e-mail sem tirar o vazio (2 -- 8, 3, 5 e 2, e o e-mail vazio virando `.inativo132`) e a 4b do login (1). **A revisão de 08/10/2026: a 3b e a 4 passaram a ser conferidas.** O ensaio lia a 4b, a 4c e o efeito dos `UPDATE`, e não a 3b, que é a única medida dos repetidos exatos que vale (a cópia os apaga) e dá o número que vai a você antes da janela -- apagá-la, agrupá-la pelo minúsculo em vez da grafia exata ou deixar o e-mail vazio entrar nela não deixava nada vermelho. Agora ele exige a 3b (login: 5 grupos, 12 linhas, 8 inativas, 1 grupo com dois ativos; e-mail: 3, 6, 3 e 1) e a 4 inteira (os ids, o estado de cada um e a coluna `grafias` de cada grupo). E ganhou oito usuários inventados, os grupos que a 3b e o renomear contam de jeitos diferentes: o de caixa e exato juntos ("Nina" ativo, "nina" e "nina" inativos -- três linhas no renomear, duas na 3b), o exato de um ativo com dois inativos, e o e-mail exato só de inativos. Os quatro `UPDATE` passam a mudar 12, 4, 6 e 2 linhas, e o resto do ensaio dá o mesmo. **Falsificado**, um mutante por vez em cópias, com o mesmo vermelho no 8.4.11 e no 8.0.46 (o contêiner descartável, apagado no fim): a 3b com o e-mail vazio, a 3b pelo minúsculo, sem a 3b e a 4 sem a coluna `grafias` (1 cada); e os de antes, com os dados novos: o roteiro de 06/10/2026 inteiro (8), o renomear do login por "mais de uma grafia" (4 -- ele ainda pega o grupo da Nina, que tem duas grafias, e deixa o edu, o joel, o zeca e o otto), o do e-mail (3) e o do e-mail com o vazio (2). **Uma sobra de texto no código, que este item não muda:** o docblock de `UsuarioRepository::selecionarPorLogin` (`module/ISConfiguracao/src/Entity/UsuarioRepository.php`) diz que o par de caixa "e o repetido exato, de antes do D294" existem, "e o que fazer com ele e pergunta do dono". Desde a resposta 8 e a 32, o inativo dos dois é renomeado no passo 3, e só os dois ativos (a 4c) continuam seus; o comportamento que o comentário descreve (devolver até dois, e a recusa com a frase do par) segue certo e necessário até a janela, e depois dela para os ativos da 4c. Fica para quem mexer no arquivo: "o que fazer com ele foi decidido (respostas 8 e 32): o inativo e renomeado no passo 3 do corte, e o de dois ativos e do dono". **Feito em 11/10/2026** (o item RESPOSTAS-SEM-RODADA), com esse texto e "até a janela, e depois dela para os dois ativos" na frase seguinte; só o comentário, e o título continua PARCIAL pelos dois ativos e pelos CPFs, que são do dono. **A verificação do mesmo dia achou três irmãs** com a mesma sobra ("o que fazer com cada par e pergunta do dono"), pelo `grep` de `D31` e `D295` em `module/` e `tests/`: o docblock da frase do par (`RegraDoUsuario`), o de `UsuariosController::validarCampoUnico` e o da classe `LoginSemCaixaTest`. As três dizem agora que os pares foram decididos pelas respostas 8 e 32 -- o inativo renomeado no passo 3, e o de dois ativos com o dono, um a um. Só comentário. **Medido na cópia** (só `SELECT` de contagem, sem login nem e-mail, em 08/10/2026): 0 logins e 0 e-mails repetidos exatos, nos 2.432 usuários (371 ativos), e 0 e-mails vazios. **Não vale como medida**, pelo que está acima: a anonimização reescreveu as duas colunas para valores únicos. Na produção, a 3b dá o número antes da janela (o 5 de "O que hoje bloqueia"). Continuam do dono: o login ou o e-mail com dois ativos (a 4c, um a um) e os 1.483 clientes com CPF repetido. ### D32 — Números de telefone de balcão contaminam a base — PARCIAL, lido em 05/10/2026 — PARCIAL em 12/10/2026: o cadastro recusa o número em 10 cadastros (a resposta 113); falta a lista dos números de balcão, na produção — PARCIAL em 13/10/2026 (a resposta 167) > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito sem marca de estado, e o corpo diz que ele está parcial: uma parte está consertada, e a outra não. Falta: classificar manualmente os números de balcão como não identificáveis antes de o telefone virar chave; no cadastro, recusar número reusado acima de um limite. Levantado em 19/08/2026, na coleta de produção. Um único número de telefone aparece em **355 cadastros de cliente**. Outro em 320, outro em 193, outro em 176. A distribuição continua com 70, 61, 47, 46, 32, 31. Isso não é telefone de família. É o número da própria loja, ou um preenchimento padrão que a recepção usa quando o cliente não informa o dele. #### Dimensão real, medida em 19/08 | | | |---|---:| | Clientes em número repetido | 13.977 | | Números distintos repetidos | 5.944 | | Clientes nos números com **10 ou mais** cadastros | **~1.590** | A distinção importa: 5.944 números repetidos para 13.977 clientes significa que a **maioria é repetição de dois ou três**, que é telefone de família legítimo. O problema real são os ~1.590 clientes presos nos números de balcão — 0,65% da base, não 5,8%. #### Metade se resolve por regra; a outra metade, não A função `normalizar_telefone` passou a descartar número cujo assinante é um **dígito repetido**, porque isso é preenchimento e não telefone. Testado contra os oito piores casos reais: | Número | Cadastros | Resultado | |---|---:|---| | `+554733692043` | 355 | descartado (fixo, não é identidade) | | `+55` | 320 | descartado | | `+554799999999` | 193 | descartado (dígito repetido) | | **`+5547991744313`** | **176** | **ACEITO** | | `+554730194612` | 70 | descartado (fixo) | | `+5500000000000` | 61 | descartado | | `+5548999999999` | 31 | descartado | | `+5548012345678` | 10 | descartado | Sete dos oito saem sozinhos. **O oitavo é o que prova que a lista manual é obrigatória:** `+5547991744313` é um celular perfeitamente válido — provavelmente de um gerente ou da própria unidade — digitado em 176 cadastros. Nenhuma regra de formato o distingue de um cliente real. **Impacto direto sobre a identidade do cliente** (`f1-2-identidade-do-cliente.md`): o telefone é a chave escolhida, e sem uma lista de exclusão desses números, **355 pessoas viram uma só** no momento em que a identidade de plataforma for criada. Elas passariam a compartilhar histórico, pontuação e consentimento. **Ao resolver:** antes de o telefone virar chave, levantar todo número com mais de N cadastros (`coletar-producao-2.sql`, seção 2), classificar manualmente quais são de balcão, e marcá-los como **não identificáveis** — o cadastro existe, o telefone serve para contato da unidade, mas não gera vínculo com uma pessoa da plataforma. Vale também impedir a entrada de novos: validação no cadastro que recuse número já usado acima de um limite. **Decidido pelo dono em 12/10/2026 (a resposta 113, opção a, a recomendada):** recusar o número que já tem 10 cadastros -- "Este telefone já está em 10 cadastros. Informe o telefone do próprio cliente." --, no ERP e na tela nova; a família de até 10 continua entrando como dependente. O aplicativo já recusa qualquer repetido, e não muda. #### O conserto (12/10/2026, o item PDV-E-CADASTRO): o cadastro novo, nas três portas - **A regra:** `RegraDoCadastroDeCliente::telefoneEmMuitosCadastros` (o teto, `CADASTROS_POR_TELEFONE`, 10, e a frase do dono, `FRASE_DO_TELEFONE_EM_MUITOS_CADASTROS`) e `ClienteRepository::contarClientesPorTelefone` -- os ativos com o número, pelo `telefone_sem_mascara`, fora os cadastros do sistema: a mesma pergunta do repetido, que é quem faz um cadastro novo virar dependente. - **O modal do ERP** (`ClientesController::validarFormulario`, o da agenda e o do PDV): com 10, recusa com a frase, com ou sem o `responsavel_id`, e sem o `telefone_existente` -- o modal só oferece "cadastrar como dependente" com ele. - **A página "Novo cliente"** (`validarTelefone`): ela já recusava todo repetido ("Telefone já cadastrado"); com 10, diz a frase do teto. - **A API da tela nova** (`Adm\ClientesController::conferirRepetidos`): 409 com a frase e `detalhes.motivo = 'telefone_em_muitos_cadastros'`, sem o dono, ANTES do `responsavelId` (que pulava a conferência do telefone). A tela (`formularioDoCliente.ts`, `errosDaRecusa`) põe a frase no campo do telefone, e não oferece o dependente (`donoDoTelefone` só lê o `telefone_repetido`). - **A alteração não passa pelo teto:** quem já divide o número salva sem trocá-lo. A troca para o número de outro é recusada a quem não é dependente (o D417) -- e só a ele: o dependente gravado troca o telefone sem conferência (a resposta 27), e pode passar para o número em 10 (a verificação, abaixo). **Provado** em `D32TelefoneEmMuitosCadastrosTest` (novo, 12 casos), verdes no MySQL e no PostgreSQL, em série: a regra e a frase; a contagem (o inativo não conta, e o cadastro do sistema só conta sem o filtro); pelo modal, com 10, a recusa sem a oferta e sem nada gravado, e o reenvio como dependente também recusado; com 9, a oferta e o décimo entrando como dependente; 9 ativos com 3 inativos e o "SEM CADASTRO" ainda oferecem o dependente; um dos 10 edita sem trocar o número; pela página, a frase do teto com 10 e a de sempre com 9; pela API, o 409 com o motivo e sem o dono, com e sem o `responsavelId`, e com 9 o 409 de sempre e o décimo cadastrado com o dono. No front, `formularioDoCliente.teste.ts` (o 409 do motivo novo é do campo do telefone; o dono não vem dele) e `ClientesLigada.teste.tsx` (um caso novo: a frase no telefone, com o foco, e sem o botão do dependente). **Falsificado** (`medir-mutantes-pdv-cadastro.py`, no rascunho do item: um mutante por vez, o arquivo devolvido e conferido pelo sha256 depois de cada um, contra os 181 casos do filtro do item; o mesmo vermelho no MySQL e no PostgreSQL): | mudança | vermelho | |---|---| | a API sem o teto | 2: a API com 10, sem e com o `responsavelId` | | a API com o `responsavelId` pulando o teto (a ordem de antes) | 1: a API com 10 e o `responsavelId` | | o modal do ERP sem o teto | 2: o modal com 10, sem e com o `responsavel_id` | | a página "Novo cliente" sem a frase do teto | 1: a página com 10 | | o teto em "mais de 10" | 6: a regra e as cinco recusas com 10 | | a contagem com os inativos | 2: a contagem e o de 9 ativos com 3 inativos | | a contagem com os cadastros do sistema | 2: a contagem e o de 9 ativos com o "SEM CADASTRO" | | a tela nova sem o motivo novo (`errosDaRecusa` só com o `telefone_repetido`; no `vitest`, os dois arquivos) | 2: o 409 do motivo novo no `formularioDoCliente.teste.ts` e a frase no telefone no `ClientesLigada.teste.tsx` | #### A verificação (12/10/2026): duas portas da API sem caso, e a do dependente A verificação do item achou o que os casos não prendiam, e o que o comentário do teto afirmava errado: - **A API na alteração.** O `conferirRepetidos` da API também roda no `PUT`, e o teto só não vale ali pelo `$atual === null`; o "um dos 10 edita sem trocar o número" ia só pelo modal. Sem o `$atual === null`, o `PUT` de qualquer um dos 10 daria 409 do teto, e a tela nova deixaria de editar quem já está num número de balcão. Caso novo: `testAApiAlteraUmDosDezSemTrocarONumero`. - **O cadastro do sistema fora da conta, na API.** A API passa a lista dela (`AVULSO`, `SEM_CADASTRO`) na própria chamada, e o ERP usa outra (`ClientesController::SENTINELAS`); só o modal provava que o "SEM CADASTRO" não conta. Caso novo: `testAApiNaoContaOCadastroDoSistema` (9 ativos e o "SEM CADASTRO": o 409 de sempre, com o dono). - **O dependente troca o telefone para o número em 10** (no modal e na API), e a reativação do inativo que tem o número também o leva a 11: a alteração não confere o telefone do dependente (a resposta 27), e a reativação não confere nada. A 113 fala do cadastro novo, e fechar essas portas é escolha do dono: foi ao lote (PDV-E-CADASTRO, a verificação, o D32), com a recomendação de o teto valer quando o telefone muda na alteração, para o dependente também. Caracterizado, sem decidir: `testODependenteTrocaParaONumeroEmDezCadastros` (com o controle de quem não é dependente, recusado com a frase do repetido). O comentário de `RegraDoCadastroDeCliente::CADASTROS_POR_TELEFONE` dizia "a alteração não muda: o telefone de outro já é recusado nela" -- falso para o dependente --, e atribuía à cópia os números da coleta da produção (355, 320, 176, ~1.590): corrigido. Na cópia, contado só em agregados, o maior número tem 26 clientes ativos, e os 10.000 números da anonimização têm 10 ou mais cada um (sem o "+": nenhum cadastro novo os alcança). **Falsificado** (`medir-mutantes-pdv-cadastro-verif.py`, no rascunho do item, com o mesmo método; o mesmo vermelho no MySQL e no PostgreSQL): | mudança | vermelho | |---|---| | o teto da API também na alteração (sem o `$atual === null`) | 2: a API altera um dos 10 sem trocar o número; e a caracterização do dependente (o `PUT` dele cai no teto) | | a API contando os cadastros do sistema (sem a lista) | 1: a API não conta o cadastro do sistema | **O que fica -- o PARCIAL do título:** a lista dos números de balcão, que só a produção dá, classificada à mão como não identificável antes de o telefone virar a chave do cliente (a regra da migração já descarta o fixo e o de dígito repetido, 7 dos 8 piores); "a lista dos números de balcão sai da produção, pela sua mão". Os números que já passam de 10 cadastros continuam como estão: o teto vale para o cadastro novo. A troca do telefone do dependente e a reativação, no lote (acima). Na cópia não dá para medir quantos números passam de 10 hoje: a anonimização deriva o telefone do id (`medir-telefones-compartilhados.sql`). E nada foi aberto num navegador. #### 13/10/2026 — O TETO TAMBÉM NA TROCA DO TELEFONE — pela resposta 167 do dono: *"aguarde terminar e continue de forma autonoma a resolver todos os debitos que tiver resposta"* **A resposta 167** (a opção "b", a recomendada): *"O teto de 10 cadastros por telefone vale também quando o telefone MUDA na alteração, para o dependente também, com a frase 'Este telefone já está em 10 cadastros. Informe o telefone do próprio cliente.'; quem não muda o telefone continua salvando; a reativação fica como está. No ERP e na tela nova."* ##### O conserto - **A regra:** `RegraDoCadastroDeCliente::mudaOTelefone` -- o `telefone_sem_mascara` gravado contra o pedido, a mesma comparação que o `confereOTelefoneNaAlteracao` do D417 já fazia (e que agora a chama). - **A API da tela nova** (`Adm\ClientesController::conferirRepetidos`, o `PUT`): o teto vale no cadastro novo e na alteração que troca o telefone, antes da regra do D417 (que deixaria o dependente passar): 409 com a frase e o motivo `telefone_em_muitos_cadastros`, sem o dono. - **O ERP** (`ClientesController::recusaDoTelefoneNaAlteracao`, as duas portas da alteração: o modal `salvar` e a página `editar`): a frase do teto, antes da regra do D417. - **Quem não é dependente** e troca para o número em 10 recebe a frase do teto, e não mais a do repetido ("Este telefone já é do cliente X."): a mesma recusa, com a frase que diz a saída. Abaixo do teto, nada muda: o dependente troca (a resposta 27) e quem não é recebe a frase do repetido. - **A tela nova não mudou:** o `salvar` da edição é o mesmo do cadastro, e o 409 do motivo novo já ia para o campo do telefone, com o foco e sem o dependente; agora um caso o prende na edição. A reativação ficou como está. **Provado** nos dois bancos, em série: `D32TelefoneEmMuitosCadastrosTest` (de 15 a 19 casos, um deles a caracterização do D481, abaixo) -- o dependente não troca para o número em 10 pelo modal, pela página `editar` nem pelo `PUT`, com a frase (e o 409 com o motivo), e os três ficam no número de antes; quem não é dependente recebe a frase do teto nas três; abaixo do teto, com 8 no número, quem não é dependente recebe a do repetido e os dependentes trocam -- o nono pelo modal, o décimo pela API --, e o seguinte, já com 10, é recusado pela página; quem já está no número em 10, o dependente inclusive, salva sem trocar nas três portas. O caso que caracterizava a porta aberta (`testODependenteTrocaParaONumeroEmDezCadastros`) virou o que a fecha. No front, `ClientesLigada.teste.tsx` (um caso novo: a edição que troca para o número em 10 põe a frase no telefone, com o foco, e o formulário fica). | mutante (sozinho, restaurado e conferido pelo sha256; `medir-mutantes-r30.py`, no rascunho do item) | vermelho, no MySQL e no PostgreSQL | |---|---| | a API com o teto só no cadastro novo (a regra de antes) | 2: o dependente não troca; quem não é dependente recebe a frase do teto | | a API com o teto em toda alteração, troque ou não | 2: a API altera um dos 10 sem trocar; o dependente que já está no número salva | | o ERP sem o teto na alteração | 3: o dependente não troca; quem não é dependente; o seguinte, já com 10, pela página | | o ERP com o teto em toda alteração | 2: um dos 10 edita sem trocar; o dependente que já está no número salva | | a tela nova sem o motivo do teto (`errosDaRecusa` só com o `telefone_repetido`; no `vitest`) | 2, em `ClientesLigada.teste.tsx`: a frase no telefone no cadastro novo e na edição | **Não provado:** o teto compara o `telefone_sem_mascara` gravado com o pedido. Um cadastro antigo com a coluna fora da forma de hoje (nula, ou gravada antes da regra) contaria como troca e, num número em 10, seria recusado mesmo sem mexer no telefone -- o risco que o D417 já corre com quem não é dependente. Na cópia não se mede: a anonimização reescreve as duas colunas. E nada foi aberto num navegador. **Achado no caminho, ao derivar as portas pelo `grep` (`setTelefoneSemMascara`), e não pela memória:** a etapa 1 da adesão troca o telefone do cliente gravado sem conferência nenhuma -- é o **D481**, no lote. **O que fica -- o PARCIAL do título:** a lista dos números de balcão, que só a produção dá, classificada à mão como não identificável antes de o telefone virar a chave do cliente; e a etapa 1 da adesão (o D481, no lote). ### D29 — Nenhuma restrição de unicidade em todo o banco — PARCIAL, lido em 05/10/2026 > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito sem marca de estado, e o corpo diz que ele está parcial: uma parte está consertada, e a outra não. Falta: conferir na réplica de produção as seis chaves que a cópia anonimizada não mede (logins, e-mails, CPFs, hashes) e declará-las com a limpeza correspondente. Levantado em 17/08/2026, no inventário da F1.3. As 83 tabelas somam 137 índices e **nenhum deles é único**. Não há `UNIQUE KEY` em lugar nenhum do schema. Ou seja: o banco aceita dois colaboradores com o mesmo login, duas unidades com o mesmo `hash` de API, dois clientes com o mesmo CPF. O que impede isso hoje é exclusivamente o código da aplicação — quando impede. Uma condição de corrida entre duas requisições simultâneas passa por qualquer verificação feita em PHP. O `hash` de unidade é o caso mais sensível: ele autentica as três rotas `/api/unidade/vendas*` (ver D4). Duas unidades com o mesmo `hash` significa uma enxergando os dados da outra. **Ao resolver:** na F1.3, junto com a criação do schema — é quando sai de graça. Duas exigências: 1. **Conferir duplicatas na réplica de produção primeiro.** Se existirem, o `CREATE UNIQUE INDEX` falha. A base anonimizada **não serve** para essa conferência: ela deriva login, e-mail, CPF e hash do `id`, então são únicos por construção. Ver `f1-3-conversao-schema.md`. 2. **Toda restrição é composta com `inquilino_id`**, senão dois inquilinos não podem ter um colaborador com o mesmo login — o que quebraria o SaaS logo no segundo cliente. #### Em 05/09/2026 a pergunta virou roteiro `scripts/conferir-unicidade.php` guarda as nove chaves conferíveis e as seis que **não são conferíveis na cópia anonimizada**, com o motivo de cada uma escrito ao lado. Ele é leitura pura — só `GROUP BY ... HAVING COUNT(*) > 1` — e a mesma invocação serve para a réplica: ```bash BANCO_HOST= php scripts/conferir-unicidade.php ``` O que ele respondeu na cópia local, que é onde o dado de negócio está intacto: | chave | repetidos | |---|---:| | `royalties` (unidade, dia) | **87** | | `nps_resultados_colaboradores` (colaborador, mês, ano) | 5 | | `clientes_creditos` (cliente, unidade) | 3 | | `nps_resultados_unidades` (unidade, mês, ano) | 3 | | `push_app` (cronjob) | 2 — esperado, é lista | | os outros quatro | 0 | E o que ele **se recusa** a responder, porque a anonimização deriva do `id`: `usuarios.login`, `usuarios.email`, `usuarios.cpf`, `clientes.cpf`, `clientes.hash` e `unidades.hash` — este último é o que autentica as rotas `/api/unidade/vendas*`, e portanto o mais sensível dos seis. Duas guardas o impedem de mentir: - **sem a cópia de produção ele para e diz isso**, em vez de reportar zero duplicatas num banco só de fixtures — zero ali não é "não há duplicata", é "não há dado"; - **as contagens conhecidas são declaradas**, e ele falha nas duas direções: duplicata nova reprova, e uma conhecida que suma também, para que a lista não envelheça em silêncio. Conferido: com a conta de `royalties` zerada à força, ele acusa e sai com 1. #### Em 15/09/2026 apareceu o vão do OUTRO lado: quem limpa antes da carga O gerador de DDL escreve, dentro do schema que ele mesmo emite, uma frase que é uma **promessa sobre outro arquivo**: > A carga FALHA se os dados ainda tiverem duplicatas. É de propósito: > `scripts/pre-migracao-limpeza.sql` roda antes, e falhar aqui é melhor que > migrar o problema. **Nada conferia essa promessa.** Enquanto as duas pontas coincidirem por hábito, funciona; no dia em que alguém declarar uma chave sem o bloco de limpeza correspondente, quem descobre é a carga — no meio do corte, com o banco pela metade. O preço está medido. `scripts/migrar-dados.sh` copia **83 tabelas**, e sua função `conferir()` só aceita a resposta `COPY ` do PostgreSQL: ```sh if echo "$2" | grep -qE '^COPY [0-9]+$'; then ... fi echo "FALHOU"; exit 1 ``` Não há `|| continue`. Uma violação de unicidade na 29ª tabela deixa as **54 seguintes nunca carregadas**. E a sequência documentada do corte roda a limpeza **antes** e o `conferir-migracao.php` **depois** — o único portão que enxergaria o estranho só fala quando o estrago já aconteceu. #### A regra certa não é "toda entrada precisa de bloco" Essa regra mais simples seria **mentira**, e vermelha sobre um estado correto: `clientes_sessoes.token_hash` é única, tem zero duplicatas e não tem bloco nenhum — corretamente, porque não há o que limpar. Portão vermelho sobre estado certo ensina a ignorar portão. A regra que vale é o **par**: chave declarada + dado sujo na origem ⇒ tem de haver quem limpe. Medido na cópia local: | chave declarada | duplicatas | quem limpa | |---|---:|---| | `clientes_sessoes` (token_hash) | 0 | ninguém, e está certo | | `privilegios` (grupo, funcionalidade) | 0 | `DELETE p FROM`, linha 125 | | `dashboard_colaboradores` (4 colunas) | 0 | `UPDATE` 198, `DELETE d FROM` 203 | | `royalties` (unidade, data) | **87** | `DELETE r FROM`, linha 273 | O `royalties` é a prova de que o par não é enfeite: a cópia local **ainda tem** as 87 duplicatas, e a única coisa entre a chave declarada e uma carga abortada é aquele bloco. `scripts/conferir-limpeza-da-unicidade.php` passou a conferir isso, e entrou no `conferir-tudo.sh`. **Ele imprime o comando que casou, com o número da linha** — e isso não é enfeite de saída. *Escrever na tabela* não é *deduplicar a tabela*: o bloco 4 faz `UPDATE usuarios` para consertar ano de nascimento inválido, e no dia em que `usuarios.login` entrar na lista — é um dos seis que este débito espera — o portão acharia aquele UPDATE e diria "tem quem limpe". Não dá para distinguir os dois por regra sem mentir (os três blocos de hoje nem se parecem entre si; o do `dashboard_colaboradores` monta tabela temporária antes, e o `HAVING` nem está no mesmo comando). Então em vez de adivinhar, ele mostra, e quem lê decide. **Falsificação**, nas três direções: | o que arranquei | o que ele fez | |---|---| | acrescentei `'funcionalidades' => ['nome']` ao gerador | **EXIT 1**, nomeando a tabela, as 63 e o bloco ausente | | comentei o `DELETE` de `royalties` na limpeza | **EXIT 1**, nomeando `royalties` e as 87 | | rodei sem `BANCO_HOST`, com o banco inalcançável | **EXIT 2** — "não consegui medir", e não 0 | Os dois arquivos voltaram byte a byte (`sha1` e contagem conferidos, `git status --porcelain` vazio), e o portão voltou ao verde. #### O que fez este portão nascer: a entrada que eu ia acrescentar Eu ia declarar `funcionalidades.nome` única. A evidência de que a duplicata é **erro** é das mais duras que há neste repositório — e continua valendo: `ISConfiguracao\Permissions\Acl::carregarFuncionalidades()` registra cada linha como recurso da ACL **pelo nome**: ```php $this->addResource(new GenericResource($funcionalidade->getNome())); ``` e o Laminas lança na segunda (`vendor/laminas/laminas-permissions-acl/src/Acl.php:254`): > `Resource id '' already exists in the ACL` Não há `try`/`catch` em nenhum ponto do login. Alimentei a biblioteca com os **126 nomes reais** da tabela: estourou no **64º** recurso, em `Agendas visualizar`. Com os **63 da faixa de produção**, montou inteira. O mesmo vale para `grupos.nome`, por `addRole` — `Role id "%s" already exists in the registry`. **E mesmo assim a entrada estava errada de ser acrescentada sozinha.** A origem padrão da carga é `franquiabv_dev`, que hoje tem 63 duplicatas de nome, e a limpeza não tem uma linha sequer sobre `funcionalidades`. Ela seria a primeira unicidade declarada sem par — e o preço seria a carga parando na 29ª de 83. **A duplicata não é da produção: é do instrumento de medida.** São 126 linhas para 63 nomes, e os 63 grupos são todos mistos, uma linha de produção e uma de fixture. Dentro da faixa de produção: 63 linhas, 63 nomes distintos, zero duplicatas — conferido por colação `ci`, por `BINARY` e por `LOWER(TRIM(nome))`. **A causa tem endereço**, e o próprio `tests/Caracterizacao/fixtures.sql` enuncia a regra antes de quebrá-la. Na linha 295, sobre `grupos`: > Condicional, como o cliente 1 e a área 3: quando as fixtures entram num banco > que já tem produção, a linha real fica. São **nove** `WHERE NOT EXISTS` no arquivo. Mas o bloco de `funcionalidades` (linha 208) insere os 63 nomes **incondicionalmente**, precedido de um `DELETE FROM funcionalidades WHERE id >= 90001000` que jamais alcança as linhas de produção (ids 1..68). É essa a razão de o ERP não conseguir montar a ACL no banco de desenvolvimento — ver D167. #### A premissa que fechou este parágrafo era FALSA, e caiu no mesmo dia O parágrafo original dizia, sobre consertar a fixture: > Torná-la condicional significa reusar os ids de produção, e aí esses cinco > deixam de achar o que procuram. **A segunda metade não decorre da primeira.** Dá para condicionar pela coluna `nome` e **manter os ids `90002xxx`** — eles continuam existindo exatamente onde não há produção. O erro foi ler a convenção do próprio `fixtures.sql`, cujos nove `WHERE NOT EXISTS` condicionam todos pelo **id**, como se fosse a única forma possível. `funcionalidades` é a única tabela daquele arquivo cuja colisão é numa coluna de negócio, com o id livre. E os cinco acoplamentos, conferidos um a um: **quatro nunca veem produção.** `ensaiar-recusas-adm-api.php` **se recusa a rodar** onde há — `if ($unidades > 10) … exit(2)`, linha 267 —, e `medir-telas-no-postgres.sh` e o `ci.yml` fazem `DROP`/`CREATE` do banco antes de carregar. Sobrou **um**: `PrivilegioPropagacaoTest.php`, que também roda contra a cópia. #### O conserto, feito em 15/09/2026 O bloco de `funcionalidades` do `fixtures.sql` passou a ceder pelo nome: ```sql INSERT INTO funcionalidades (id, nome) SELECT v.id, v.nome FROM ( SELECT 90002000 AS id, 'Agendas visualizar' AS nome UNION ALL SELECT 90002001, 'Agendas gerenciar' ... ) v WHERE NOT EXISTS (SELECT 1 FROM funcionalidades f WHERE f.nome = v.nome); ``` A forma foi **escolhida por medição**, e não por gosto: a compacta (tabela derivada) podia esbarrar no erro 1093 do MySQL, então foi ensaiada em banco descartável nos **dois** bancos, nos dois cenários. Tabela vazia → as 63 entram na faixa de fixture; tabela com os nomes de produção → nenhuma linha nova. Idêntico no MySQL e no PostgreSQL. O bloco das oito concessões do gerente de fixture passou a casar por nome pelo mesmo motivo — com id fixo ele violaria a chave estrangeira na cópia e abortaria a carga inteira. E `PrivilegioPropagacaoTest` passou a achar a funcionalidade pelo nome, com uma asserção que **diz o que houve** em vez de morrer quatro camadas adiante num `Column funcionalidade cannot be null`. **Os 63 pares `(id → nome)` foram conferidos idênticos antes e depois**, acentos inclusive — e a primeira conferência que escrevi era um falso verde: `grep -P` falhou por locale, os dois lados saíram vazios, e o `diff` disse "idênticos" comparando nada com nada. Refeita em PHP. #### O que isso fez com a cópia, medido | | antes | depois | |---|---:|---:| | `funcionalidades` (MySQL) | 126 linhas / 63 nomes | **63 / 63** | | `funcionalidades` (PostgreSQL) | 126 / 63 | **63 / 63** | | concessões do gerente de fixture | 8 no MySQL, **7** no PostgreSQL | 8 nos dois | | privilégios de produção | 15.495 | 15.495 | E a prova que importa, com a classe do próprio projeto, dentro do container, contra o banco vivo, pelo caminho que o login usa: > **A ACL DO PROJETO MONTOU.** > `isAllowed('Gerente unidade', 'Agendas visualizar', 'ler') = true` Antes: `Resource id 'Agendas visualizar' already exists in the ACL`, no 64º recurso. **O ERP voltou a ter ACL.** A recarga completa do `fixtures.sql` na cópia também passou, e é o que atualiza `_fixtures_versao` — a marca do banco e a do arquivo voltaram a bater. #### E a chave única, que era o objetivo desde o começo Com a cópia limpa, `conferir-limpeza-da-unicidade.php` — que na véspera recusava esta entrada com `63 SUJA E SEM NINGUÉM QUE LIMPE` — passou a dizer `funcionalidades (nome) 0 limpa, e não precisa de bloco`. **O mesmo portão, a mesma entrada, veredito oposto, porque o dado mudou.** `'funcionalidades' => ['nome']` entrou no gerador, o `postgres/schema.sql` ganhou `ALTER TABLE funcionalidades ADD CONSTRAINT funcionalidades_nome_unico UNIQUE (nome);`, e a entrada entrou na declaração de `conferir-unicidade-do-schema.php`. Falsificada: arrancada do gerador, o portão sai com **1** nomeando a tabela e o custo. São **cinco** unicidades declaradas. ### D30 — Dinheiro em ponto flutuante — MESMO DEFEITO DO D49 **Este débito e o D49 são o mesmo**, registrados com dez dias de diferença: as mesmas 85 colunas `double`, a mesma consequência, a mesma resolução adiada para depois do corte. Descoberto em 30/08/2026, ao varrer o registro atrás de assuntos repetidos. **E os dois já tinham divergido.** O D30 mandava converter para `numeric(12,2)`; o D49, para `numeric(14,2)`. Uma escala errada para valores acumulados é exatamente o tipo de detalhe que se perde quando duas páginas descrevem a mesma migração — e a de 14 dígitos é a certa, porque `royalties_faturas.valor` e as somas de relatório passam de 10 dígitos antes da vírgula com folga. **O conteúdo vivo está no D49**, que é mais rico: ele traz a divergência medida na 16ª casa entre os dois bancos, e o episódio em que a própria prova de migração passou por sorte — comparava somas de ponto flutuante com tolerância de meio centavo, valor **abaixo do que o tipo distingue** numa soma de 155 milhões. Este registro fica como remissão, e não é apagado: quem chegar aqui por um link antigo precisa ser mandado ao lugar certo, não encontrar um vão. ### D28 — A venda passou a poder ser registrada na data em que aconteceu; falta o caixa — FECHADO, lido em 05/10/2026 > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito sem marca de estado, e o corpo diz que ele está fechado, sem nada a fazer. O corpo: "A guarda nova não é redundante — ela fecha exatamente essas 44". Levantado em 17/08/2026, ao detalhar as metas de RTO. `Venda::setDataCriacao()` **não aceita parâmetro**: o corpo é `new \DateTime('now')`, fixo. E `VendaPagamentoService::finalizar()` atribui o caixa com `selecionarPorUsuario($usuario, true)` — o caixa aberto **naquele instante**. Consequência: uma venda lançada depois do fato fica com a data do lançamento e no caixa que estiver aberto na hora, e não na data e no caixa em que realmente ocorreu. Isso importa porque descreve o que a operação faz numa parada. O sistema fora do ar não impede a venda: o cliente é atendido presencialmente e o lançamento é feito quando o sistema volta. Se a volta acontece dentro do mesmo caixa, o desvio é de minutos e não tem efeito. Se atravessa o fechamento do caixa, a venda cai no caixa seguinte — o dia que teve o movimento mostra menos, e o dia seguinte mostra mais. Se atravessa a virada do mês, **o cálculo de royalties do mês fica errado**, porque ele soma por período a partir de `vendas`. Na parada de 36 h de 2025, portanto, todo o movimento do período foi registrado com data e caixa errados. Vale considerar isso ao comparar aqueles meses com outros. #### O erro de data não se corrige sozinho, e chega na fatura *Apurado em 17/08/2026, depois de o responsável definir que atravessar a virada do dia é inaceitável.* Royalties **não são somados de `vendas` ao vivo**. `FranquiaService::royaltiesAtualizar()` grava um retrato diário por unidade na tabela `royalties`, e os relatórios leem de lá (`RoyaltiesRepository`, filtrando por `roy.data`). Duas propriedades desse retrato agravam o problema: 1. **A janela de recálculo é de dois dias.** O método começa em `-2 days` e avança duas vezes, ou seja, recalcula **ontem e hoje**. Um lançamento que entre com data errada e só seja notado no terceiro dia **nunca é recalculado**: o número fica congelado errado. 2. **A fatura fecha no dia 16, cobrindo do dia 16 ao 15.** Uma venda que escorregue de um dia para o outro atravessando essa fronteira **muda de fatura de royalties** — deixa de ser cobrada num período e passa a ser cobrada no seguinte. Isso não é relatório: é cobrança ao franqueado. #### A metade da data foi feita em 30/08/2026 `Venda::setDataCriacao()` passou a aceitar um `?\DateTime` opcional, com o mesmo padrão de antes: ```php public function setDataCriacao(?\DateTime $quando = null) { $this->dataCriacao = $quando ?? new \DateTime('now'); return $this; } ``` **Toda chamada existente se comporta de forma idêntica** — e há uma só, `VendaPagamentoService::finalizar()`. Não é mudança de comportamento: é permissão para informar o que era impossível informar. Cobertura em `tests/Caracterizacao/VendaDataDoFatoTest.php`, com quatro asserções, e conferi que acusam: removendo o parâmetro, três das quatro falham. > **Este arquivo não existe mais.** Ele foi removido em 31/08/2026 junto com o > parâmetro que cobria, quando a regra de negócio enunciada naquele dia proibiu > retroagir venda. O parágrafo fica porque descreve o que foi feito em 30/08, e > a seção seguinte descreve por que foi desfeito. Uma delas verifica por **reflexão** que o parâmetro continua opcional. Parece excessivo, e não é: é exatamente a opcionalidade que torna a mudança segura, e alguém que a torne obrigatória quebra a única chamada existente sem que nenhum outro teste perceba. **O QUE ISTO NÃO ENTREGA, e é importante ser exato:** não há como informar a data pela tela. Nenhum campo existe, e criá-lo é decisão de produto — inclui decidir quem pode retroagir um lançamento e até quando. O que a mudança faz é remover o impedimento técnico; a operação continua registrando tudo como "agora". #### A REGRA FOI ENUNCIADA em 31/08/2026, e ela substitui a resposta de 30/08 **A regra, dita por quem decide:** > Não permitir venda retroagida, apenas na data atual ao lançamento. Se o caixa > passar de 23:59:59, pedir para fechar o caixa e abrir um na data vigente. **Isso inverte a resposta que este débito tinha recebido no dia anterior.** Em 30/08 a saída escolhida foi permitir informar a data do fato; em 31/08 a regra de negócio diz que não se retroage. As duas não valem juntas. **O que foi desfeito:** `Venda::setDataCriacao()` voltou a ser `new \DateTime('now')` fixo, e `VendaDataDoFatoTest` saiu com ele. Manter o parâmetro seria pior que nunca o ter criado — uma capacidade que a regra proíbe usar é armadilha, porque quem a encontrar depois vai supor que é permitida. **O que foi feito:** `VendaPagamentoService::caixaDeDataAnterior()` devolve o caixa aberto quando ele é de data anterior a hoje, e `finalizar()` recusa a venda **antes de qualquer escrita** — as primeiras linhas do método debitam crédito do cliente e do programa de fidelidade, e sair no meio deixaria o cliente sem o crédito e sem a venda. `VendasPagamentosController` usa a mesma função para dizer ao operador o que fazer, em vez de a venda falhar em silêncio. Cinco testes em `tests/Caracterizacao/CaixaNaoAtravessaODiaTest.php`, verificados **desligando a guarda de propósito**: com ela desligada, três dos cinco caem. **Um deles passava sem provar nada, e isso vale registrar.** O teste que verifica que a recusa não deixa a venda pela metade buscava a venda *antes* de `recuarCaixa()`, que faz `em->clear()` — a entidade chegava desanexada a `finalizar()`, nada era gravado, e a asserção passava por acidente. Só apareceu porque, com a guarda desligada, ele continuou verde enquanto os outros dois caíam. **A prova de que um teste acusa é a única forma de saber que ele mede.** #### E o tamanho disto é muito menor do que eu apresentei Eu levei a você o número de **19,18%** — 4.156 dos 21.666 caixas fechados desde 2025 fecharam em data diferente da abertura — dizendo que a guarda encostaria na operação todo dia. **Esse número mede outra coisa:** caixa deixado aberto de um dia para o outro e fechado depois, sem venda no meio. O número que mede o risco é este: | | | |---|---:| | Vendas desde 2025 | 407.544 | | **Em caixa de outra data** | **44 — 0,011%** | | Valor | R$ 7.787 | **É pouco porque a tela já barrava.** `VendasController::validarCaixaAberto()` recusa a entrada em `novoAction()` quando o caixa é de outro dia, e mostra a mensagem certa, desde antes de tudo isto. As 44 são o que escapa: abrir comanda, finalizar venda já aberta, ou estar com a tela aberta quando o dia virou. **A guarda nova não é redundante — ela fecha exatamente essas 44**, e é a lição do D20 pela terceira vez: trava na tela protege a tela; trava no serviço protege qualquer chamador, inclusive um endpoint REST da Fase 2. #### As duas asserções que pareciam ter sumido Ao trocar `VendaDataDoFatoTest` por `CaixaNaoAtravessaODiaTest`, o total da suíte caiu de **203 para 201** asserções — e os dois arquivos declaram 7 cada. Duas tinham deixado de rodar, que é a forma exata de um teste que silenciosamente para de verificar. **Não era isso, e a diferença foi medida e não deduzida.** Rodei a suíte antiga com `--log-junit`, guardando as mudanças no stash e recarregando as fixtures antigas, e comparei classe a classe: | | Antes | Agora | |---|---|---| | `VendaDataDoFatoTest` | 4 testes, **9 asserções** | removido | | `CaixaNaoAtravessaODiaTest` | — | 5 testes, **7 asserções** | | **as outras 19 classes** | — | **idênticas, uma a uma** | 203 − 9 + 7 = 201. **O arquivo removido executava 9 declarando 7**, e a causa foi provada com um teste descartável: | Asserção | O PHPUnit conta | |---|---| | `assertSame` | **1** | | `assertGreaterThanOrEqual` | **2** | | `assertLessThanOrEqual` | **2** | As duas últimas são constraints compostas — `LogicalOr` de "maior que" **ou** "igual a" —, e cada lado incrementa o contador. `testSemArgumentoContinuaSendoAgora` usava as duas: duas instruções, quatro asserções contadas. **A lição é a mesma do D67, no mesmo dia:** contei com `grep` e tratei instrução como asserção. `grep` conta linhas, não o que o código faz. E "o total bateria se eu contasse do meu jeito" não é conferência — a conferência foi rodar as duas versões e comparar. #### O "avisar antes" pedido na decisão já existia A decisão de 31/08 pedia duas coisas: recusar a venda **e** avisar antes, no primeiro acesso do dia, para o operador não descobrir o problema com cliente na frente. **A segunda metade já estava implementada**, e ninguém tinha notado ao redigir este débito. `VendasController::novoAction()` chama `validarCaixaAberto()` e, se o caixa é de outro dia, mostra: > *"O caixa foi aberto no dia X, para realizar uma nova venda você precisa fechar > o caixa e abrir novamente."* ...e redireciona para a tela de gerenciar caixas. É mais forte que um aviso: o operador não entra na tela de venda sem resolver. **Nada foi construído para isso, então.** O que faltava era só a metade do serviço — e é ela que fecha as 44. #### Os caixas que já estavam abertos `scripts/medir-caixas-abertos.sql` mede e lista, e **não fecha nada** — o `UPDATE` fica comentado no fim, para ser conferido antes. | | | |---|---:| | Caixas abertos | 137 | | **De usuário ativo** | **36** — são os únicos que travariam alguém | | De usuário inativo | 101 | | O mais antigo de usuário ativo | id 245, aberto em 20/10/2015 — **3.968 dias** | Fechar é mais simples do que parece: `CaixaService::fechar()` faz `setStatus(false)` e nada mais, porque o `valor_final` já é mantido durante a operação por `atualizar()`. Fechar **não recalcula dinheiro** — encerra o caixa com o saldo que ele já tem. #### A metade do caixa continua aberta, e é de propósito Apontar um lançamento para um caixa já fechado mexe na reconciliação de saldo (`CaixaService::atualizar()`) e exigiria decidir o que fazer com um caixa fechado que muda de valor. A distinção importa porque **a data é o que afeta dinheiro** — royalties, fatura, fechamento diário. O caixa é reconciliação operacional, resolvida por quem opera. Enquanto a segunda metade não vem, uma venda retroagida ficaria com a data certa e o caixa de hoje. Para royalties isso basta, porque a apuração soma por data. Para o fechamento do caixa, não. ### D27 — A réplica em MySQL 8.4 não serve para retorno Levantado em 17/08/2026, ao inventariar a infraestrutura. A produção e duas das três réplicas rodam MySQL 8.0.4x. O servidor 1 (Hostinger `linkwise`) roda **8.4.10**. A replicação do MySQL é suportada de uma versão menor para uma maior, **não no sentido inverso**. A consequência aparece justamente no cenário que motiva a redundância: 1. Se o servidor 1 for promovido a primário numa falha, **as outras duas réplicas (8.0) não conseguem replicar a partir dele**. A cadeia de redundância desaba para um nó só no momento em que ela mais importa. 2. Voltar para a produção 8.0 depois de ter operado em 8.4 não é suportado. 3. O MySQL 8.4 **desabilita `mysql_native_password` por padrão**. Se algum usuário de aplicação ou de replicação ainda usa esse plugin, a conexão falha — e falha na hora do desastre, não antes. 4. Dumps tirados dele carregam sintaxe 8.4. Já causou confusão em 16/08/2026: um dump da réplica foi tomado por dump de produção, e a divergência de versão ficou dois dias sem explicação. Enquanto as versões divergirem, o servidor 1 é **réplica de leitura, não nó de contingência** — e o plano de contingência precisa dizer isso com todas as letras, senão alguém vai contar com ele numa madrugada. **Ao resolver:** alinhar o servidor 1 em 8.0.4x (o caminho simples), ou subir todos para 8.4 de uma vez. Não deixar o parque misto. --- ### D63 — 78 entidades declaravam `@ORM\Entity` duas vezes — CORRIGIDO em 30/08/2026 Encontrado em 30/08/2026 de raspão, ao ler `CupomCliente` por outro motivo. ```php /** * @ORM\Entity * @ORM\HasLifecycleCallbacks * @ORM\Table(name="cupons_clientes") * @ORM\Entity(repositoryClass="ISConfiguracao\Entity\CupomClienteRepository") */ ``` **Não era um deslize num arquivo: eram 78 das 82 entidades do projeto.** Era a convenção, escrita do mesmo jeito em todo lugar, com a linha nua sempre antes da que carrega o `repositoryClass`. **Não quebrava nada, e a ordem era a única razão.** O `AnnotationDriver` reindexa as anotações pelo nome da classe, então a segunda sobrescreve a primeira — e a segunda é justamente a que traz o repositório. Invertida a ordem em qualquer um dos 78 arquivos, aquela entidade perderia o repositório customizado sem nenhum aviso. **O problema era a Fase 1.** Anotação em docblock aceita repetição; **atributo de PHP 8 não**. Verificado por execução em 30/08/2026, e não de memória: ``` Attribute "Marca" must not be repeated ``` `ORM\Entity` não é `IS_REPEATABLE`. Uma conversão mecânica de anotações para atributos — que é o caminho normal ao subir de Doctrine, e o projeto vai subir — produziria **78 erros fatais de uma vez**, todos no carregamento da classe, e todos com a mesma mensagem opaca. #### Como foi resolvido `scripts/conferir-entidade-duplicada.php` relata por padrão e corrige com `--aplicar`. Remove a linha nua apenas, preservando integralmente a que traz `repositoryClass`: **78 remoções idênticas, nenhuma inserção**. **O roteiro passou por uma prova de que consegue acusar.** Uma entidade forjada, com a duplicata e **sem** `repositoryClass`, apareceu na lista dos casos que ele se recusa a corrigir sozinho — ali, remover a linha nua apagaria a única declaração de entidade existente. O contador de corrigíveis seguiu em 77 e não 78, mostrando que a exclusão é real e não apenas relatada. **E o roteiro errou uma vez, do jeito que roteiro erra: por não ler.** Na primeira passada ele disse "0 restantes" com uma duplicata ainda de pé. `ClienteCredito` traz um `use` **entre o docblock e a palavra `class`** — legal em PHP, e o docblock continua valendo para a classe —, e o padrão simplesmente não casava esse arquivo. O único sinal foi as contagens não baterem: **82 entidades mapeadas contra 81 lidas**. Sem essa diferença de um, o 78º caso teria ficado para trás com o roteiro declarando sucesso. **Verificação:** `orm:validate-schema` reprova 19 entidades antes e 19 depois — idêntico, e por motivo alheio (**D64**). Os 80 repositórios customizados continuam existindo e resolvendo, com 0 quebrados. E 109 de 109 na caracterização no MySQL e no PostgreSQL, 35 de 35 no contrato. **Nota de leitura:** quatro entidades escrevem o `repositoryClass` sem namespace (`UnidadeRepository`, `UnidadeMensageriaRepository`, `SaidaParcelaRepository`, `SaidaParcelaPagamentoRepository`). Funciona porque o `ClassMetadata` resolve nome curto contra o namespace da própria entidade — mas convém não mexer nesses quatro sem olhar. --- ### D64 — O `orm:validate-schema` voltou a valer como portão — FECHADO em 31/08/2026 Medido em 30/08/2026, ao conferir se a limpeza do **D63** tinha estragado algo. Não tinha — **19 reprovações antes, 19 depois** —, e foi essa conferência que mostrou o tamanho de um problema que já estava registrado pela metade. **31 queixas em 19 entidades**, de dois tipos bem diferentes. #### 29 são `inversedBy` faltando — barulho, mas barulho que esconde O lado inverso declara `mappedBy`, o lado proprietário não declara o `inversedBy` correspondente. O Doctrine funciona assim mesmo: carrega, grava, consulta. As mais concentradas são `Usuario` com 5, e `Unidade` e `VipClass` com 3 cada. O custo não é de execução, é de leitura. **`orm:validate-schema` é um portão que hoje reprova sempre**, então ninguém consegue usá-lo para descobrir se uma mudança estragou o mapeamento. Foi preciso rodar a validação duas vezes — com e sem a mudança guardada — e comparar contagens, porque o "reprovado" sozinho não diz nada. #### 2 são de outra natureza: apontam para campos inexistentes ``` Convenio#clientes OneToMany(Cliente, mappedBy="cliente") Cliente não tem $cliente. Tem $convenio. ProdutoEstoque#produto ManyToOne(Produto, inversedBy="entradas") Produto não tem $entradas. Não tem nada parecido. ``` A primeira é um erro de uma palavra: `mappedBy="cliente"` onde cabia `mappedBy="convenio"`. A segunda aponta para um lado inverso **que nunca foi escrito** — `entradas` não existe em `Produto`, e a única ocorrência da palavra no projeto inteiro é a própria anotação. **Nenhuma das duas é percorrida hoje**, e isso foi conferido: `Convenio::getClientes()` existe e não é chamado de lugar nenhum fora da própria entidade. Enquanto ninguém tocar nessas associações, elas não falham — e foi por isso que duraram. É o padrão que você já descreveu: **placeholder de função que nunca foi usada**. #### As duas quebradas foram corrigidas em 30/08/2026 Por decisão sua, e só elas — os 29 `inversedBy` ficaram de fora de propósito. **`Convenio#clientes`** passou a apontar para `convenio`, que é o campo que existe, e `Cliente#convenio` ganhou o `inversedBy="clientes"` que fechava o par. Duas linhas, uma de cada lado. **`ProdutoEstoque#produto`** perdeu o `inversedBy="entradas"`. Inventar a coleção `$entradas` em `Produto` seria escrever código novo para satisfazer uma anotação; remover descreve o que a relação sempre foi na prática — unidirecional. **Medido depois:** `orm:validate-schema` caiu de **19 para 18** entidades reprovadas e de **31 para 29** queixas, e as queixas do tipo *"refers to a field which does not exist"* passaram a ser **zero**. `Convenio` continua na lista, mas agora só pelo `#unidades`, que é do grupo dos 29. **Por que só estas duas.** Acrescentar `inversedBy` a uma relação muda como a UnitOfWork trata a coleção do lado inverso; fazer isso em 29 relações de uma vez é mudança de comportamento disfarçada de arrumação. Estas duas são diferentes porque **ninguém as percorre** — o único efeito possível era o validador parar de reclamar, e foi o que aconteceu. #### Os 29 `inversedBy` foram aplicados em 31/08/2026, por decisão sua ``` [OK] The mapping files are correct. ``` De **18 entidades reprovadas e 29 queixas** para **zero**. O `[ERROR]` que continua aparecendo logo abaixo é de banco fora de sincronia — outro assunto (**D29**), que some quando o PostgreSQL recebe as restrições que o MySQL nunca teve. **A lista não foi minha, e isso foi deliberado.** Cada edição saiu de uma queixa do próprio `orm:validate-schema`, que já diz a entidade alvo, o campo alvo e o valor exato do atributo. Varrer o código por conta própria abriria espaço para eu decidir errado; aqui o validador ditou e o roteiro executou. **E as duas listas foram comparadas antes de aplicar.** Derivei uma segunda lista do código — todo lado inverso com `mappedBy`, conferindo se o proprietário tem `inversedBy` — e ela deu **30**. A diferença era falso positivo meu: `SaidaParcelaPagamento#parcela` declara `targetEntity="SaidaParcela"` **sem namespace**, o meu roteiro não achou o arquivo e reportou como faltante. Já tinha o atributo. Fora essa, **as 29 são idênticas nas duas listas**. | | | |---|---:| | Arquivos tocados | 27 | | Anotações alteradas | 29, todas `ManyToOne` | | Linhas do diff | 58 — 29 fora, 29 dentro | | Linhas acrescentadas sem `inversedBy` | **0** | Nenhuma é `OneToOne`, o que mantém o caso simples: o lado proprietário continua carregando por referência tardia, e o que muda é o Doctrine passar a saber que a coleção do outro lado existe. **O ganho é o portão.** Antes, para saber se uma mudança estragou o mapeamento, era preciso rodar a validação duas vezes — com e sem a mudança guardada — e comparar contagens, porque "reprovado" sozinho não dizia nada. Agora `[OK]` significa `[OK]`. **Não confundir com o `[ERROR]` de banco fora de sincronia** que aparece no fim da mesma saída: aquele é outro assunto (**D29**), e some sozinho quando o PostgreSQL recebe as restrições que o MySQL nunca teve. --- ### D65 — 98 colunas onde a anotação e o banco discordam sobre aceitar nulo — e um SEGUNDO eixo, o tipo, MEDIDO em 12/09/2026 Medido em 30/08/2026, ao investigar a observação de passagem do **D51** de que `vendas.comanda_temp` é declarada `nullable=true` e o MySQL diz `NOT NULL`. Não era uma coluna: são **98 de 732** — 13% do mapeamento. E elas discordam nos **dois sentidos**, que quebram de jeitos opostos: | | | O que isso faz | |---|---:|---| | Anotação diz NOT NULL, banco aceita nulo | **52** | o Doctrine hidrata nulo num campo que o código trata como sempre preenchido | | Anotação diz NULO, banco diz NOT NULL | **46** | o código pode gravar nulo, e o `flush()` falha com erro de SQL opaco | #### Das 52, quantas têm nulo de verdade **33.** Descontando 8 que são artefato da anonimização — ela zera `salt`, `whatsapp_api_key`, `asaas_id` e afins —, **restam 25 reais**. (Uma das oito era `iframe_bi`, que saiu do sistema em 09/09/2026 com o Power BI. A medida acima é de 08/09 e fica como foi feita.) | Coluna | Nulos | de | |---|---:|---:| | `agendas.add_comanda` | **708.877** | 4.000.081 | | `clientes_creditos.pontuacao_validade` | 153.135 | 256.985 | | `produtos.pacote_validade_dias` | 9.268 | 9.506 | | `produtos.categoria` | 8.040 | 9.506 | | `visagismo.feedback_nota` | 2.557 | 2.740 | | `push_app.link` | 701 | 701 | | `produtos.quantidade` | 280 | 9.506 | | `convenios.data_ultima_venda` | 188 | 638 | | `notificacoes.primeiro_envio` / `ultimo_envio` | 149 | 2.787 | | `unidades.faturamento_*` (9 colunas) | 2 a 19 | 60 | | `unidades.potencial_franquia` | 5 | 60 | | `grupos.administrador` | 2 | 13 | | `arquivos.subcategoria` | 7 | 109 | #### As fixtures contaminam a contagem, e quase me fizeram registrar defeito nosso A primeira medição acusou **`unidades.nome` com 1 nulo em 62**, e eu escrevi que uma unidade sem nome merecia olhada. Merecia — e a olhada mostrou que era a unidade **90001000**, criada pelas nossas próprias fixtures de teste. O mesmo para `unidades.estado`. Excluindo os ids da faixa `9000xxxx`, **`unidades.nome` tem zero nulos reais**. **A regra que fica:** a base de desenvolvimento tem, além da cópia anonimizada da produção, as linhas que os testes criam. Em tabela grande isso é irrelevante — `agendas.add_comanda` cai de 708.879 para 708.877. Em tabela pequena é decisivo: `unidades` tem **60 linhas reais e 2 nossas**, e uma contagem de "1 em 62" pode ser inteiramente artefato. Toda medição em tabela pequena precisa de `WHERE id < 90000000`. #### O código já sabe o que a anotação nega `AgendaService:212`, ao arquivar uma exclusão: ```php 'add_comanda' => $addComanda === null ? null : ($addComanda ? 1 : 0), ``` **O código trata o nulo explicitamente**, e a anotação três arquivos adiante diz `nullable=false`. Quem escreveu o serviço sabia; quem lê a entidade, não. A propriedade é `private $addComanda`, sem tipo — então a hidratação de nulo é silenciosa. O construtor grava `false`, então linha nova nasce preenchida: os 708.879 nulos são históricos. #### NÃO é risco de corte, e vale dizer por quê `scripts/gerar-ddl-postgres.php` lê o **`mysql.sql`**, que é o dump de estrutura do banco — nunca a anotação. Conferido: `postgres/schema.sql` traz `add_comanda boolean DEFAULT false`, **sem `NOT NULL`**, exatamente como o MySQL. **E isso deixou de ser argumento de mecanismo para virar medição.** Na madrugada de 31/08/2026 comparei a nulabilidade **coluna a coluna nos dois bancos vivos**: | | | |---|---:| | Colunas no MySQL | 891 | | Colunas no PostgreSQL | 970 | | Presentes nos dois | 890 | | **Divergentes** | **0** | As 80 a mais no PostgreSQL se explicam inteiras: **75 são `inquilino_id`**, e as outras **5 são a tabela `inquilinos`**, que só existe lá. Nenhuma sobra. Os dois bancos concordam perfeitamente. **Quem discorda dos dois é o mapeamento** — e só ele. **Onde isso morde, então:** 1. **`orm:schema-tool` propõe `NOT NULL` em coluna cheia de nulo.** É parte dos 71 comandos `CHANGE` que ele lista, e é mais uma razão para o `--force` nunca ser executado (**D17**). 2. **Quem regenerar o schema a partir do MAPEAMENTO** — e não do dump — produz um banco que a carga recusa. Não é o caminho de hoje, mas é o caminho natural de quem chega e usa `schema-tool:create`. 3. **A anotação é o que o leitor humano acredita.** 98 divergências são 98 oportunidades de alguém raciocinar sobre o campo errado. **Ao resolver:** alinhar a anotação ao banco, coluna por coluna, **depois do corte**. É mudança de mapeamento, e mapeamento é o que a suíte de caracterização exercita — então o portão "o comportamento não mudou" precisa estar livre para falar só de uma coisa por vez. **Nota sobre o D51:** a coluna que ele cita, `vendas.comanda_temp`, é do segundo grupo — anotação `nullable=true`, banco `NOT NULL`. A observação dele estava certa; o que faltava era saber que não estava sozinha. #### HÁ UM SEGUNDO EIXO, achado em 11/09/2026: o TIPO, e não só o nulo Este débito conta desacordos de **nulabilidade**. Procurando onde caracterizar o valor de um relatório, tropecei num desacordo de **tipo**, que é outro eixo e não está contado em nenhuma das 98: | | anotação | MySQL | PostgreSQL | |---|---|---|---| | `dashboard_movimentos.data_inicio` | `type="datetime"` | `date` | `date` | | `dashboard_movimentos.data_fim` | `type="datetime"` | `date` | `date` | Os dois bancos concordam entre si — **de novo** — e quem discorda dos dois é a anotação, exatamente o padrão que este débito descreve. O efeito hoje é benigno por sorte: o Doctrine manda `Y-m-d H:i:s` para uma coluna `date`, e os dois motores truncam em silêncio. Onde ele morde é no mesmo lugar das 98 — quem regenerar o esquema a partir do **mapeamento** produz `datetime` onde o dado é `date`, e o `orm:schema-tool` propõe a mudança. **O CENSO FOI FEITO em 12/09/2026**, e não pelo `orm:schema-tool:update --dump-sql`: aquele dump mistura eixos — 274 linhas, com 130 `RENAME` de índice, 39 `DROP`, 32 `ADD` e 72 `CHANGE`, várias por linha, a maioria sendo nulabilidade de chave estrangeira, que já é a contagem de cima. Um número tirado dali seria chute com cara de medida, e este registro já pagou por isso (o **D82** nasceu com "~65 linhas" e precisou de medidor próprio). O censo veio do cruzamento do metadata com o `information_schema` dos **dois** bancos, coluna a coluna. São **746 campos mapeados, nenhum sem coluna**, e sete tipos distintos de anotação. O que NÃO casa: | anotação → coluna | quantos | o que é | |---|---:|---| | `datetime` → `time` | **34** | hora do dia anotada como instante | | `datetime` → `date` | **16** | dia anotado como instante (os dois do `dashboard_movimentos` são daqui) | | `string` → `text` | 15 | anotação mais estreita que a coluna | | `integer` → `tinyint(1)`/`smallint` | 9 | inteiro pequeno | | `text` → `varchar` | 1 | o inverso do de cima | | `string` → `double` | 1 | `convenios.porcentagem` | | `integer` → `varchar` | 1 | `dashboard_colaboradores.total_produtos_vip_vendidos` | | `float` → `varchar` | 1 | `dashboard_colaboradores.total_produtos_vip_vendidos_reais` | | `float` → `int` | 1 | `dashboard_faturamento.total_clientes_antigos` | Os dois bancos dão **os mesmos números** em todas as linhas acima — mais uma vez, quem discorda dos dois é a anotação. #### E uma correção no parágrafo de cima: a anotação NÃO é ignorada pelo gerador Este débito afirma que `scripts/gerar-ddl-postgres.php` *"lê o `mysql.sql` […] **nunca** a anotação"*. Isso está **errado como absoluto**, e o próprio gerador diz por quê (`gerar-ddl-postgres.php:229-231`): > *"Só o par inteiro/booleano é resolvido pela anotação. É onde MySQL e PostgreSQL > discordam de fato, e onde converter pelo tipo da coluna produziria erro de > execução — nos dois sentidos."* E a razão é medida, não estética: *"Convertendo pelo tipo do MySQL, **70 colunas** ficariam com o tipo errado — nos dois sentidos. Quem decide, portanto, é a anotação da entidade."* O MySQL não sabe dizer a diferença entre `int`, `tinyint` e `tinyint(1)`; o PostgreSQL não perdoa. O argumento de "não é risco de corte" continua valendo para a **nulabilidade**, que é o assunto deste débito — mas a frase absoluta não. #### As 29 colunas em que os dois bancos DISCORDAM de tipo — e as 29 são deliberadas Na nulabilidade, este débito mediu **zero** divergências entre os dois bancos. No tipo, são **29 de 906 colunas comuns** — e eu cheguei a achar que tinha encontrado um defeito, porque a forma assusta: `tinyint(1)`, que é o booleano canônico do MySQL, virou `smallint` no PostgreSQL, enquanto `int` virou `boolean`. Parece invertido. Não é: | família | quantas | por que | |---|---:|---| | `int` → `bigint` | **12** | `agendas`, `vendas` e `vendas_produtos` são as `GRANDES` do gerador: chave primária e toda estrangeira que aponta para elas viram `bigint`, por projeção de centenas de milhões de linhas em 4.000 inquilinos | | `int`/`tinyint` → `boolean` | **7** | a anotação diz `boolean`, então o gerador escreve `boolean` — é a regra de cima | | `tinyint(1)` → `smallint` | **8** | a anotação diz `integer`, então o gerador escreve `smallint`. A coluna *parece* booleana no MySQL e não é, segundo quem mapeou | | `char` → `varchar` | 1 | `string` nos dois; diferença de dialeto | | `tinyint` → `boolean` (restante) | 1 | idem à segunda família | **Nenhuma das 29 é defeito**, e registrar isso tem valor próprio: a próxima pessoa que cruzar os dois `information_schema` vai ver a mesma forma estranha e precisar de duas horas para chegar onde este parágrafo chega. `vendas.comanda_temp` — a coluna do **D51** — é uma das sete da segunda família. #### Os três casos singulares que merecem olhada, e o que a olhada achou `convenios.porcentagem` é `double` anotado como `string` — porcentagem de desconto lida como texto. E dois estão em `dashboard_colaboradores`, que é a tabela do **D40** (linhas duplicadas e divergentes, causa declarada como não confirmada): uma **contagem** e um **total em dinheiro** guardados em `varchar(255)`. Fui atrás, e o resultado é **latente, não vivo** — medido em 12/09/2026: | | | |---|---| | linhas em `dashboard_colaboradores` | 18.257 | | nulas nas duas colunas | 15.283 (84%) | | valores com **vírgula** decimal | **0** | | valores com ponto decimal | 297 | | consultas que ORDENAM ou comparam essas colunas | **nenhuma** | `DashboardColaboradorRepository::colaboradorDestaque()` monta `ORDER BY das.$item DESC` com o nome da coluna interpolado — o que acende dois alarmes e apaga os dois: os **13** chamadores passam **literal** (`DashboardColaboradoresController:43-55`), então não há injeção alcançável pela URL — é por isso que a varredura do **D73** não a listou —, e **nenhum dos 13 é uma das duas colunas `varchar`**, então ninguém ordena texto como se fosse número. Ordenar por elas ordenaria `"9"` acima de `"85"`. Ninguém ordena hoje. Fica escrito aqui para que o décimo quarto chamador não seja o primeiro a descobrir. #### E agora há portão, porque número que não se repete apodrece `scripts/conferir-tipos-do-mapeamento.php`, nos **32** portões e **no CI**. Ele cruza o tipo da anotação com o `information_schema` do banco apontado e compara com uma linha de base **por banco**: | | desacordos | |---|---:| | MySQL | **70** | | PostgreSQL | **54** | Ele reprova quando a contagem **muda** — para cima ou para baixo. Para cima porque desacordo novo é trabalho novo; para baixo porque o alinhamento do D65 andou e a linha de base precisa descer, ou o próximo desacordo entra de graça. E imprime a lista inteira quando muda, pela lição do `conferir-guarda-do-erp.php`: trocar um desacordo por outro mantém o total, e mesmo assim é trabalho. **Falsificado:** anotando `dashboard_movimentos.data_criacao` como `string`, ele acusa *"a contagem mudou: eram 70 e agora são 71"*, nomeia a coluna e sai com 1. **E a diferença de 16 entre os dois bancos é a notícia boa deste débito.** São exatamente os 7 `boolean` sobre coluna inteira mais os 9 `integer` sobre `tinyint(1)`: nesses 16, o esquema do **PostgreSQL concorda com a anotação e o do MySQL não**, porque `gerar-ddl-postgres.php:229` resolve o par inteiro/booleano pela anotação. Ou seja — o banco para o qual estamos migrando é **mais fiel ao mapeamento** do que o de onde saímos. **Ele roda no CI**, e isso foi conferido antes de ligar: contra `franquiabv_pgcontrato`, montado do mesmo `postgres/schema.sql` que o job usa, dá os mesmos 54. Ao contrário dos irmãos que dependem de banco (`conferir-booleano-em-coluna-inteira.php`, `conferir-relacoes-doctrine.php`), este **não precisa da cópia de produção** — basta o esquema. *Portão que não roda é pior que portão que não existe*, e isso foi aprendido caro em 11/09. **O conserto é o mesmo e a hora é a mesma:** alinhar a anotação ao banco, depois do corte. --- ### D66 — A suíte de contrato falha sozinha, e todo "35 de 35" desta semana vale menos do que parecia Descoberto em 31/08/2026, ao aplicar os 29 `inversedBy` do **D64**. **O susto primeiro.** A execução seguinte à mudança deu **6 falhas**, e a atribuição óbvia era a mudança de mapeamento. Não era. **A prova, e é o que torna este débito um débito:** com a mudança guardada no stash — **o mesmo código, byte a byte** — duas execuções seguidas deram | Execução | Resultado | |---|---| | 1ª | **OK (35 tests, 36 assertions)** | | 2ª | **Failures: 3** | A suíte falha sozinha. #### O que as falhas são, e o que não são Todas trazem `"status": 0`. Isso não é payload diferente: é **o `curl` desistindo antes de qualquer resposta**, com `CURLOPT_TIMEOUT => 30` em `ContratoTestCase:157`. Elevando o limite para 120 segundos, passa **35 de 35 com e sem a mudança de mapeamento**. É tempo, e só tempo. #### E o número não fecha Medido direto, com a aplicação apontada para `franquiabv_contrato`, o endpoint mais lento dos que falham responde em **1 a 1,6 segundo**, estável em quatro medições seguidas: ``` cupons/selecionar/1 http=200 tempo=1,37s cupons/selecionar/1 http=200 tempo=0,98s cupons/selecionar/1 http=200 tempo=1,62s cupons/selecionar/1 http=200 tempo=1,23s ``` **Por que dentro da suíte ele às vezes passa de 30 segundos, eu não sei.** O que já foi descartado: | Hipótese | Como caiu | |---|---| | Carga da máquina | `docker stats` com tudo entre 0% e 8% de CPU | | Cache de configuração do Laminas | `config_cache_enabled => false`, e `data/cache/` vazio | | A aplicação no banco errado | a guarda de ambiente teria abortado a suíte inteira | | Payload divergente | com 120 s passa tudo, sem tocar em snapshot nenhum | As duas que restavam foram medidas em 31/08/2026, e **as duas caíram.** #### A medição que derrubou as duas hipóteses Um só conjunto de dados as separa. Com a aplicação apontada para `franquiabv_contrato`, proxies e cache apagados e o `local.php` recém-reescrito, 25 requisições seguidas ao endpoint mais pesado, de dentro do container, anotando a cada uma o tempo e a contagem de arquivos de proxy: | # | s desde o início | tempo | arquivos de proxy | |---|---|---|---| | 1 | 7,31 | **7,29 s** | 2 | | 2 | 9,93 | 2,58 s | 2 | | 3 | 11,33 | 1,36 s | 2 | | … | … | 1,1 a 2,5 s | 2 | | 25 | 51,31 | 2,13 s | 2 | **Hipótese 1, proxy do Doctrine — caiu.** A contagem é **2 já na primeira requisição e nunca muda**. Os proxies são gerados uma vez e reusados; não há custo por requisição. Junto com ela cai uma afirmação errada deste próprio registro: eu havia escrito que "não há `generate_proxies` em configuração nenhuma". Há — `vendor/doctrine/doctrine-orm-module/config/module.config.php:64` traz `generate_proxies => true`, e a configuração efetiva resolve para isso. O diretório estava vazio porque `scripts/rodar-contrato.sh` o apaga no início *e* no `trap` de saída. **Diretório vazio depois de uma execução não é prova de que nada foi gerado durante ela** — foi só isso que eu havia lido. **Hipótese 2, janela do opcache — caiu.** A lentidão não decai em dois segundos: ela **persiste por 51 segundos**, do começo ao fim da série. Se fosse a janela de revalidação, as requisições após o segundo 2 teriam voltado ao normal. As requisições 3 a 25 estão todas entre 1,1 e 2,5 segundos. O que a série mostra de verdade é um custo frio **real mas único** — 7,29 s na primeira contra ~1,8 s de regime — e um endpoint que custa 1,1 a 2,5 s sempre. Um endpoint leve na mesma série responde em 0,20 s, então o arranque do framework não é o custo: a consulta é. #### E aí o problema muda de forma Cinco execuções completas da suíte, seguidas, deram **35 de 35 as cinco vezes** (30 a 38 segundos cada). O flake não reproduziu. Mas o `--log-junit` dessas cinco execuções dá o número que reformula tudo: | | | |---|---| | teste mais lento das 175 medições | `testAgendaSelecionar`, **4,11 s** | | limite do `curl` | 30 s | | folga | **25,89 s** | **Uma falha por tempo limite aqui não é "ficou lento": é 7 vezes o pior tempo já medido.** A suíte não se arrasta até os 30 segundos — alguma coisa *trava*. Isso muda o que procurar. Não é afinar desempenho, é achar o que bloqueia: uma espera por trava no banco, uma conexão que não volta, um worker preso. É por aí que a próxima investigação deve começar, e não pela lentidão. #### UM MECANISMO MEDIDO em 22/09/2026 — o pool do PHP-FPM tem CINCO filhos, e já bateu no teto nove vezes A ficha acima terminava com um pedido: *"não é afinar desempenho, é achar o que bloqueia: uma espera por trava no banco, uma conexão que não volta, **um worker preso**"*. Esta é a medição do terceiro. ##### O que foi medido ``` pm.max_children = 5 pm.start_servers = 2 pm.min_spare_servers = 1 pm.max_spare_servers = 3 ``` E o próprio FPM reclama, no registro do contêiner: ``` WARNING: [pool www] server reached pm.max_children setting (5), consider raising it ``` **Nove vezes**, em 09/09, 10/09 (×3), 11/09 (×2), 16/09 (×2) e **21/09 às 23:57** — esta última durante a minha própria rodada de portões, o que é a demonstração mais direta possível: basta outra coisa estar usando a aplicação. ##### Por que isto casa com a forma do defeito, e não com a lentidão A reformulação desta ficha era que **uma falha por tempo limite aqui é 7 vezes o pior tempo já medido** — a suíte não se arrasta até os 30 segundos, alguma coisa trava. Teto de pool produz exatamente isso: enquanto os cinco filhos estiverem ocupados, o nginx **enfileira**, e a requisição não anda. Não é lentidão proporcional; é espera até alguém liberar. E casa com a intermitência: o mesmo código falha ou passa conforme **o que mais estiver batendo na aplicação naquele minuto** — outro portão, o navegador aberto, uma rotina de cron. *"A suíte falha sozinha"* sempre quis dizer "sem mudança de código", e não "com mais nada rodando". ##### Duas ressalvas, e elas importam **1. Isto NÃO explica o incidente original.** O registro do contêiner começa em **07/09**, e o D66 nasceu em **31/08**. Não há linha para olhar. Afirmar que o teto causou aquelas seis falhas seria inventar. **2. NÃO é configuração deste projeto.** `pm.max_children = 5` vem da imagem base do PHP; não há `max_children` em `Dockerfile`, `docker-compose` ou `.conf` do repositório. **E o CI também não a sobrescreve** — o mesmo teto vale lá. ##### O ensaio que decide, e por que não o fiz agora Rodar a suíte de contrato **enquanto se observa o registro do FPM**: se uma falha por tempo limite coincidir com a linha de `max_children`, o mecanismo está confirmado; se falhar sem ela, é outro. Não rodei porque `rodar-contrato.sh` **reponta o `local.php`** para o banco de contrato, e deixar isso a meio caminho numa madrugada sem ninguém olhando é o risco que o registro do D190 e o do `definir-senha-contrato.php` já descrevem. Com alguém acordado, é um comando. ##### Se confirmar, o conserto não é subir o teto Subir `max_children` esconde o sintoma e **destrói a reprodução**. O conserto é decidir o que a suíte deve fazer quando o pool está cheio — e o `CURLOPT_TIMEOUT => 30` passa a ser a pergunta certa: hoje ele não distingue *"o endpoint quebrou"* de *"não havia worker livre"*, que são defeitos diferentes com o mesmo rosto. #### O ENSAIO FOI FEITO em 22/09/2026 — o flake reproduziu, as DUAS hipóteses caíram, e o instrumento não conseguia diagnosticar trava Quatro execuções seguidas, com o registro do FPM observado em cada uma: | # | condição | duração | resultado | |---:|---|---:|---| | 1 | logo após recriar o banco | **237 s** | **3 falhas** | | 2 | quente | 106 s | OK | | 3 | logo após recriar de novo | 108 s | OK | | 4 | com o limite novo, 60 s | 94 s | OK | ##### O flake reproduziu, e a testemunha ficou As três falhas da execução 1 são `testPedirCodigoRecusaGet`, `testPedirCodigoSemTelefone` e `testPedirCodigoComTelefoneDesconhecido` — os **três primeiros casos do arquivo, em sequência**, cada um exatamente 30 s: ``` resolucao de nome 0,002115 s conexao 0,002480 s pronto para enviar 0,002534 s primeiro byte 0,000000 s total 30,002228 s ``` **Conectou e a aplicação não respondeu byte nenhum.** Depois delas, os outros 64 casos passaram. É janela de tempo, e não endereço — os três nem sequer mandam SMS: são todos casos de **recusa**. ##### Hipótese 1, o pool do PHP-FPM — CAIU Era a minha, escrita ontem. **`max_children` não foi atingido em nenhuma das quatro execuções** — zero linhas no registro do FPM nos quatro intervalos. O teto de 5 filhos é real e já foi atingido nove vezes, mas **não é o que derruba esta suíte**. ##### Hipótese 2, custo frio depois de recriar o banco — CAIU A execução 1 veio logo depois de um `--montar`, e pareceu explicação. A execução **3 teve a condição idêntica** — banco recriado imediatamente antes — e passou em 108 s. Recriar não reproduz. ##### O que APARECEU, e é mais afiado que as duas ``` innodb_lock_wait_timeout 50 s (medido) CURLOPT_TIMEOUT 30 s (era) ``` **O instrumento desistia antes do banco.** Numa espera por trava, o MySQL aguarda até 50 s antes de devolver erro; o curl largava aos 30. O resultado é que uma trava **nunca podia se apresentar como trava** — ela chegava sempre como *"conectou e não respondeu byte nenhum"*, indistinguível de worker preso, de chamada de rede sem tempo limite (**D67**) ou de laço infinito. Isto reinterpreta uma frase desta própria ficha. Ela dizia, de 31/08: *"Elevando o limite para 120 segundos, passa 35 de 35 (…) É tempo, e só tempo."* Não era só tempo: **era o limite passando por baixo do limite do banco**, e apagando a única pista que teria nome. ##### O que entrou `CURLOPT_TIMEOUT` de **30 para 60 segundos**, acima dos 50 do InnoDB. Isto **não conserta o D66** — conserta o instrumento: da próxima vez, uma trava chega com o erro do MySQL, e não como silêncio. E não esconde travamento de verdade: 60 s continua sendo **15 vezes** o pior tempo já medido nesta suíte (4,11 s). Execução 4, com o limite novo: **OK, 67 testes, 94 s**. ##### O candidato que sobra, com a história causal Antes da execução 1 eu havia **interrompido** uma rodada de portões no meio do `medir-cron-no-postgres` — e rotinas de cron gravam. É exatamente o padrão que a memória desta casa registra: *matar a suíte deixa trava*. Não há como provar em retrospecto (as transações já haviam saído quando fui olhar), mas é a única explicação que sobrevive às duas refutações acima, e agora **a próxima vez vai deixar rastro**. **Antes de rodar a suíte, olhe `information_schema.INNODB_TRX`.** Se houver transação `RUNNING` antiga, o vermelho que vier não é do código. #### A TRAVA SEGURADA DE PROPÓSITO, em 22/09/2026 — o ensaio que fecha a cadeia Decisão do dono: *"segure a trava de propósito e rode"*. Feito, em dois braços, com uma transação que **não grava nada** (`SELECT … FOR UPDATE` + `SLEEP` + `ROLLBACK`) e se solta sozinha, sobre o banco **descartável** de contrato. ##### Braço 1 — a trava durante o PREPARO O `definir-senha-contrato.php` faz `DELETE FROM clientes_sessoes WHERE telefone = ?`. Com a trava de pé ele esperou os 50 s e apanhou: ``` Doctrine\DBAL\Exception\LockWaitTimeoutException: 'DELETE FROM clientes_sessoes WHERE telefone = ?' com ["+5547320000000"] SQLSTATE[HY000]: General error: 1205 Lock wait timeout exceeded ``` A suíte abortou com **255**, antes de rodar um caso. Isso é comportamento **bom**: uma trava perdida não produz vermelho esquisito no meio dos testes — ela estoura no preparo, com nome. ##### Braço 2 — a trava durante os TESTES, e é a que responde a pergunta Com a trava tomada **depois** do preparo, a falha chegou assim: ``` Failed asserting that 500 is identical to 202 ``` **A aplicação RESPONDEU.** Com os 30 s de antes, o curl teria desistido aos 30 — **antes** dos 50 do InnoDB — e isso teria aparecido como *"conectou e não respondeu byte nenhum"*, que é a assinatura exata do flake. O conserto do instrumento está **provado por experimento**, e não por aritmética. ##### E o relatório ainda jogava fora a testemunha O 500 chegava como número: *"500 is identical to 202"*, sem uma palavra sobre o porquê. Conferido que **nenhum dos 67 casos espera 5xx**, o auxiliar de requisição passou a falhar com o corpo e com o caminho: ``` POST /api/v4/sessoes respondeu 500 -- a aplicacao quebrou. corpo: {"sucesso":false,"mensagem":"Não foi possível atender a este pedido."} O CORPO E GENERICO DE PROPOSITO: a API nao vaza interno, e esta certa. O MOTIVO fica no log do conteiner, com a excecao e o SQL por extenso: docker logs franquiabv-app-1 --since 5m | grep -i 'PHP message' Se disser `1205 Lock wait timeout`, o vermelho e de TRAVA e nao de codigo. ``` E o log tinha mesmo o nome: ``` LockWaitTimeoutException ... 'UPDATE clientes_sessoes SET tentativas = ? WHERE id = ?' SQLSTATE[HY000]: General error: 1205 Lock wait timeout exceeded ``` ##### O mecanismo do órfão foi reproduzido ao vivo, sem querer Ao encerrar o primeiro braço com `TaskStop`, **a transação continuou de pé**: o cliente morreu e a sessão do MySQL dentro do contêiner sobreviveu segurando as cinco linhas. Foi preciso `KILL 21111`. É exatamente o mecanismo que esta ficha suspeitava da execução 1 — demonstrado, ainda que em outro papel. ##### O que este ensaio NÃO prova **Não prova que a execução 1 foi trava.** Prova que, se for, da próxima vez a trava chega com nome em vez de silêncio. O flake original continua sem causa atribuída — o que mudou é que ele perdeu o esconderijo. Suíte limpa depois de tudo: **67 testes, 107 s, verde**, e o `local.php` restaurado byte a byte nas sete execuções desta sessão. #### A PONTE DE ARQUIVOS, medida em 05/09/2026 — e ela já estava escrita aqui Encontrei o D66 duas vezes num dia: duas execuções seguidas da suíte falharam em testes **diferentes**, por tempo esgotado, com o mesmo código. Fui medir. **Onde o custo está, e onde não está:** | alvo | mediana | máximo | |---|---:|---:| | arquivo estático (só nginx) | **5 ms** | 525 ms | | endpoint PHP leve | **320 ms** | 2,4 s | A rede e o nginx não são o custo. O PHP é — e um pedido trivial varia oito vezes. **Por quê, com número:** `/var/www/html` é um bind mount **v9fs**, a ponte que o Docker Desktop usa para expor o `D:\` do Windows. Medido de dentro do contêiner, percorrendo arquivos de verdade: | origem | por arquivo | |---|---:| | `module/` (bind mount v9fs) | **3,63 ms** | | `vendor/` (volume nomeado) | **0,03 ms** | **A ponte custa 121 vezes mais.** Com os caches de configuração desligados, um pedido do Laminas toca centenas de arquivos da aplicação — e 100 arquivos a 3,63 ms dão 0,36 s, que é a mediana observada. O número fecha. *Isto não é descoberta minha, e vale dizer.* `docker/php/php.ini` já registra, com medida: *"com 0 o PHP faz stat() em cada um dos ~4.900 arquivos do projeto a cada requisição, e sobre um bind mount do Docker no Windows isso custava cerca de 9 segundos por página"*. O que faltava era **este débito ligar-se àquele comentário** — a tabela de hipóteses descartadas acima não menciona o sistema de arquivos uma vez sequer. #### Uma hipótese testada que NÃO se sustentou Se a revalidação do opcache (`revalidate_freq = 2`) fosse a causa da cauda, uma janela longa a derrubaria. Medido, três execuções completas de cada lado: | `revalidate_freq` | execuções | |---|---| | 2 (como está) | 105 s, 94 s, **79 s** | | 300 | 87 s, 82 s, 88 s | **As faixas se sobrepõem** — a execução mais rápida de todas foi com a janela curta. A primeira leitura sugeria 17% de ganho; com três de cada lado, ela era ruído. **A hipótese cai.** #### E uma correção de raciocínio na tabela acima A linha *"Cache de configuração do Laminas — `config_cache_enabled => false`"* está listada como hipótese **descartada**, e o argumento estava invertido: o cache estar desligado é o **mecanismo**, não a refutação. Com ele ligado, num endpoint trivial: | | sem cache | com cache | |---|---:|---:| | mediana | 320 ms | **244 ms** | | máximo | 2,43 s | **1,15 s** | Num endpoint que toca o Doctrine, porém, a diferença some no ruído (444 ms contra 414 ms). Ele é **um** contribuinte, e não a causa. #### O que continua sem resposta Nada disto explica os **30 segundos**. O pior tempo que consegui provocar num endpoint foi 12,9 s, uma vez, e em série controlada o máximo foi 2,4 s. A observação anterior continua valendo e agora com mais razão: **alguma coisa trava**, e travar não é o mesmo que estar lento. O que este registro acrescenta é onde *não* procurar — não é a rede, não é o nginx, não é a revalidação do opcache — e um custo de base que explica a lentidão comum sem explicar o travamento. #### Por que isto importa mais que a falha em si **"35 de 35" foi reportado como evidência dezenas de vezes nesta semana**, aqui e no roadmap. Parte desses verdes pode ter sido sorte. E o lado pior é o simétrico: **a partir de agora existe a tentação de descartar uma falha real como "flakeou de novo"**. Suíte que falha sozinha não protege — e ainda dá cobertura para ignorar quando ela acerta. #### Ao resolver — e o que NÃO fazer **Não é elevar o limite para 120 e seguir.** Isso esconde o sintoma sem explicar a causa, e o número certo depende de decidir quanto tempo um endpoint do aplicativo pode legitimamente levar — que é pergunta de negócio, não de teste. #### A DECISÃO, tomada em 31/08/2026 **Por decisão sua, este débito passa a esperar evidência, não trabalho.** Nada de laço de reprodução, nada de mexer no limite de 30 s. A instrumentação está posta, e a próxima falha — quando vier — vai carregar o diagnóstico consigo. **O que isso aceita conscientemente:** pode demorar. Até lá, todo "35 de 35" deste documento carrega um asterisco, e toda falha futura terá a desculpa pronta de "flakeou de novo". A defesa contra a segunda parte é esta seção: quando a suíte falhar, **leia o diagnóstico antes de rerodar**. Ele diz de que lado travou, e ele desaparece na execução seguinte. **O que NÃO fazer, e continua valendo:** elevar o limite. Com 120 s passa tudo, e o sintoma some sem que ninguém saiba por quê — foi medido. **Uma opção que foi considerada e recusada:** baixar o limite de 30 s para 10 s. Ela transformaria um travamento raro num sinal mais frequente, já que o pior tempo medido é 4,11 s. Foi recusada pelo risco simétrico: numa máquina carregada a suíte passaria a falhar por lentidão legítima, e o remédio viraria a doença. #### O caminho, quando a evidência chegar Procurar o que **bloqueia** por mais de 30 segundos, com 25 s de folga sobre o pior tempo já medido. **A instrumentação para pegá-lo já está posta** (31/08/2026). Até aqui toda falha chegava como `"status": 0` — um número que diz só "o curl desistiu", sem dizer de quê, e que fazia as três falhas serem indistinguíveis entre si e de qualquer outra causa. Agora `ContratoTestCase` guarda o erro do `curl` e a repartição de tempos, e **calcula o veredito**: | `connect_time` | `starttransfer_time` | Veredito | |---|---|---| | exatamente 0 | — | a conexão nunca se completou; procure fora do PHP | | > 0 | exatamente 0 | conectou e a aplicação não respondeu byte nenhum — **este é o caso que este débito persegue** | | > 0 | > 0 | a resposta começou e foi cortada no meio | Os dois primeiros ramos foram postos à prova, cada um contra a sua causa fabricada — um ouvinte que aceita e nunca responde, e um endereço que engole o pacote — e cada um acusou o seu. **E a primeira versão dessa mensagem estava errada**, o que vale registrar porque é o mesmo erro de sempre nesta semana. Ela imprimia os tempos com três casas decimais e pedia ao leitor que reparasse num zero. Contra o ouvinte que aceita e não responde, ela imprimiu `conexao 0,000 s` — porque conectar em localhost leva menos de um milissegundo — e teria mandado a próxima investigação procurar rede, o único lugar onde o problema não está. Seis casas decimais, e o veredito calculado em código em vez de deixado para o olho. **Da próxima vez que a suíte flakear, a falha dirá de que lado ela travou.** É a única testemunha que existe, e ela desaparece na execução seguinte: anote os números aqui antes de rodar de novo. **Correção de registro:** a mensagem do commit `30d4696` diz que esta suspeita ficou "registrada no D61". Não ficou — o D61 é sobre snapshots que só têm o caso vazio, e este débito não existia quando aquela mensagem foi escrita. Fica dito aqui porque mensagem de commit não se corrige, e uma remissão para o lugar errado custa a próxima pessoa procurar onde não está. #### Mais uma ocorrência, 23/09/2026 às 08:1x — anotada antes de rodar de novo A suíte de contrato rodou logo depois do corredor e de `montar-banco-contrato.sh`, com o banco recém-montado, e **quatro** casos bateram nos 60 s, todos com o mesmo veredito: **conectou e a aplicação não respondeu byte nenhum**. | caso | rota | conexão | primeiro byte | total | |---|---|---:|---:|---:| | `ApiV4Test::testCredencialQueNaoAutentica` | `GET /api/v4/clientes` | 0,001592 s | 0 | 60,000993 s | | `AplicativoApiTest::testVersaoDoAplicativo` | `GET /api/versao/app` | 0,001738 s | 0 | 59,999968 s | | `AplicativoApiTest::testUnidadesSelecionar` | `GET /api/agendas/getUnidades` | 0,001832 s | 0 | 60,000817 s | | `AplicativoApiTest::testUnidadeSelecionar` | `GET /api/agendas/getUnidade/90001000` | 0,001547 s | 0 | 60,001149 s | O que se olhou em seguida, sem rodar nada: - **O registro do FPM não tem linha de `max_children` nesta rodada** — a última é de 22/09 às 20:47. O teto do pool não explica esta ocorrência. - **`INNODB_TRX` vazio** logo depois — nenhuma transação aberta. Se houve trava, ela já tinha soltado quando se olhou. - As quatro rotas são da API do aplicativo, e **nenhuma foi tocada** pela mudança que se estava verificando (o formatador da sessão de `/adm/api`). A execução seguinte, com o banco montado de novo e nada mais mudado: **67 de 67**, e também sem linha de `max_children` no registro. Mesmo código, outro resultado — é o retrato que este débito tem desde 31/08. #### E no ensaio de recusas, 23/09/2026, antes das 10:27 A primeira rodada de `ensaiar-recusas-adm-api.php` do B10, contra o banco de contrato, passou pelos casos 1 a 44 e **parou no 45** até o `timeout 300` a matar. O caso 45 é um `POST /adm/api/agendas/fechamentos` que o servidor recusa com 422 antes de tocar no banco. Não houve linha de saída do caso, nem erro. - A rodada seguinte, com o mesmo código, passou os 46 casos em **198 s**, e o 45 levou **3 s**. - Depois da morte, nenhum processo do ensaio ficou vivo no contêiner, o banco de contrato não tinha resíduo do ensaio, e o banco dev não recebeu nada (os pedidos HTTP do ensaio usam o `local.php`, que já tinha voltado para o dev). É a mesma cara das ocorrências acima: o pedido entra e a aplicação não responde. #### No PostgreSQL, 27/09/2026 — anotada antes de rodar de novo A suíte de contrato no PostgreSQL, na verificação da fatia 3 de clientes, levou **1.046 s** (o normal é ~250) e três casos bateram nos 60 s, os três com o veredito de sempre: | caso | rota | conexão | primeiro byte | total | |---|---|---:|---:|---:| | `ApiV4Test::testUmIdDeOutroTelefoneERecusadoComToken` | `GET /api/v4/clientes/90001152/consumo` | 0,002881 s | 0 | 60,082047 s | | `AplicativoApiTest::testIndicacoesListarAutenticado` | `GET /api/cliente/indicacoes/90001000` | 0,002457 s | 0 | 59,999804 s | | `AplicativoApiTest::testClienteSelecionarAutenticado` | `GET /api/agendas/getCliente?telefone=…` | 0,003137 s | 0 | 60,001673 s | - **A máquina estava carregada, e isto é o que a distingue das anteriores**: 31 agentes de uma auditoria de código lendo o repositório e consultando o banco dev, e a suíte do front rodada cinco vezes na mesma janela. - **Sem linha de `max_children`** no registro do FPM nos 90 minutos anteriores, e **nenhuma transação aberta** no PostgreSQL logo depois (`pg_stat_activity`: duas conexões ociosas no banco de contrato). - As três rotas são da API do aplicativo, e nenhuma foi tocada pela mudança que se verificava; a mesma suíte, no MySQL, na mesma rodada, deu 67 de 67. - Na mesma janela, o ensaio de permissão no PostgreSQL saiu 2 com "SEM RESPOSTA" num `GET /adm/api/clientes` que só devia devolver 403, e os outros ensaios levaram de duas a três vezes o normal (o de recusas, 739 s). **De novo, com a máquina parada** e nada mais mudado: a suíte de contrato no PostgreSQL, **67 de 67 em 139 s**, e o ensaio de permissão, **42 de 42**. **Esta ocorrência não explica as de antes.** A tabela de hipóteses lá em cima descartou a carga da máquina (`docker stats` entre 0% e 8% de CPU) para as ocorrências de agosto e setembro. Esta é de outra espécie: a carga estava lá, medida do lado de fora, e sem ela o erro sumiu. Fica anotada para que ninguém a conte como mais um caso do flake sem causa -- nem como a causa dele. ### D67 — Nove chamadas de rede sem tempo limite — 7 CORRIGIDAS em 31/08/2026, 2 congeladas — PARCIAL em 10/10/2026: as duas do OneSignal têm tempo limite e SSL; resta o teto do php-fpm, para o corte — PARCIAL em 11/10/2026: o teto escrito no corte Descoberto em 31/08/2026, procurando o que poderia travar por 30 segundos no **D66**. **Não é a causa do D66** — a ligação foi conferida e não existe, e isso está dito no fim deste registro. É achado independente, e mais grave. #### O que foi medido Nove chamadas `curl` no código de produção **sem `CURLOPT_TIMEOUT`**: | Arquivo | `curl_init` | com tempo limite | |---|---|---| | `module/ISBase/src/Util/OneSignal.php` | 2 | **0** | | `module/ISBase/src/Util/Asaas.php` | 5 | **0** | | `module/ISApi/src/Service/CronJobService.php` (Yungas) | 2 | **0** | **Este registro nasceu dizendo dez, e eram nove.** O `grep -c curl_init` que eu usei primeiro contou uma linha comentada no `CronJobService` — a chamada do `yungasNpsAtualizar` (**D43**), que está desligada atrás de `//`. Quem corrigiu foi `scripts/conferir-tempo-limite-rede.php`, que lê o PHP pelo `token_get_all` em vez de por texto, e por isso não vê comentário. É a terceira vez nesta semana que a ferramenta acha o erro da contagem feita à mão, e a lição continua a mesma: **`grep` conta linhas, não código.** O padrão do `curl` sem `CURLOPT_TIMEOUT` é **não desistir nunca**. As outras integrações do sistema — `EvolutionApi`, `WahaApi`, `VisagismoService`, `ArmazenamentoS3` — todas definem o seu. Estas três não. #### E não há teto em lugar nenhum acima delas Medido no container local (a produção está congelada e não foi medida): | | | |---|---| | `max_execution_time` | **0** — o PHP nunca mata o script | | `request_terminate_timeout` | **não definido** — o php-fpm nunca mata o worker | | `pm.max_children` | **5** | | `fastcgi_read_timeout` do nginx | 300 s | O `fastcgi_read_timeout` limita **quanto o chamador espera**, não quanto o worker vive. Aos 300 s o nginx devolve 504 e desliga; o processo PHP continua rodando, e como um laço de cron não emite saída, ele nunca percebe que o cliente sumiu. **As rotinas de cron são chamadas por URL** — o próprio `docker/nginx/default.conf:76` diz isso ao justificar o timeout de 300 s. Ou seja: elas passam pelo mesmo pool de 5 workers que atende o aplicativo dos clientes. #### O tamanho da exposição O envio é **serial, uma chamada HTTP por destinatário**, dentro de um laço aninhado (`CronJobService:1402`). Na cópia da produção: | | | |---|---| | maior lista de destinatários | **6.573** | | média por notificação | 940 | | notificações do tipo push já enviadas | 2.186 | Uma única campanha grande são 6.573 POSTs em sequência, num worker de cinco, sem nada que possa interrompê-los. #### O que NÃO está quebrado — e vale dizer, porque parece Duas coisas neste código levantam suspeita e foram conferidas: **A remoção do destinatário da lista está correta.** `setClientesIds` usa `str_replace`, o que normalmente estraga listas assim (remover o id `12` mordendo o `123`). Mas a chamada envolve o id nos delimitadores, e todas as **1.398** listas não vazias começam e terminam com `;`. As concluídas ficaram reduzidas a `;;`, isto é, todos os ids saíram. **Um travamento não reenvia a campanha inteira.** O `flush` é por destinatário, com o id já removido, então a execução seguinte retoma de onde parou em vez de notificar de novo quem já recebeu. A trava (`TravaDeExecucao`, **D44**) também não vaza: o `flock` é liberado pelo sistema quando o processo morre. O problema é que o processo **não morre** — e enquanto ele estiver pendurado, toda execução seguinte da rotina responde `Processo já em execução`, que é uma mensagem tranquila para uma rotina que parou de acontecer. #### Três achados menores, no mesmo caminho 1. **`OneSignal::ativo()` nunca é chamado.** O método lê `public/app.json` para decidir se o push está ligado, e nenhum ponto do sistema o consulta. O desligamento de emergência não existe na prática. Liga-se ao **D36**. 2. **Código morto engolindo o log da rotina.** Em `CronJobService:1437` há um `return`, e o `logScripts` de `marketingNotificacoes` está na linha 1439 — depois dele. A rotina nunca registra que rodou. São 17 `logScripts` para 30 ações de cron. (Um detector ingênuo apontou 4 trechos; três eram `return` de várias linhas e foram descartados na leitura.) 3. **`CURLOPT_SSL_VERIFYPEER => false`** nas duas chamadas do OneSignal — o certificado não é conferido, e o cabeçalho leva a chave da API. #### O que foi corrigido, por decisão sua (31/08/2026) **Sete das nove receberam tempo limite:** as cinco do Asaas e as duas do Yungas. `CURLOPT_CONNECTTIMEOUT` de 5 s e `CURLOPT_TIMEOUT` de 30 s. Os dois números foram provados mordendo, contra causas fabricadas, sem tocar em nenhuma das APIs reais — chamar o Asaas de verdade é mexer num meio de pagamento, e não se faz para testar: | Cenário | Sem os dois | Com os dois | |---|---|---| | endereço que engole o pacote | desistiu em **21,04 s** (era o sistema operacional, não o código) | **5,01 s** | | servidor que aceita e cala | **nunca** desistiria | **30,00 s** | A segunda linha é a que importa: sem `CURLOPT_TIMEOUT`, um servidor que aceita a conexão e não responde segura o worker para sempre. É o cenário do fornecedor com problema, e é o mais provável dos dois. **Quem confirmou que as sete pegaram não fui eu:** foi o próprio portão, que passou a acusar exatamente aquelas sete como "estão na lista e não existem mais". Ler o diff teria sido a mesma pessoa conferindo o próprio trabalho. Uma dívida pequena nasceu aqui, e fica dita: os números vivem em constantes na classe `Asaas` e **escritos à mão** no `CronJobService`. Mudar lá não muda aqui. Dar casa comum a duas constantes exigiria uma classe nova só para elas, e não pareceu troca boa — mas a divergência é possível. #### O que continua em aberto **As duas do OneSignal**, congeladas por instrução sua, e é o par que mais assusta: são as que rodam em laço, uma chamada por destinatário, com a maior lista em 6.573. **E o teto do php-fpm, que não foi posto.** Ele é o que protege contra a próxima integração escrita sem tempo limite — os sete `curl_setopt` de hoje protegem só os sete lugares de hoje. `request_terminate_timeout` continua indefinido, `max_execution_time` continua 0, e o pool continua com 5 workers. #### Por que o resto não foi corrigido Instrução em vigor: *"por hora, ignorar tudo do onesignal, visagismo e sms. Anote como débito tecnico e será resolvido no futuro."* O OneSignal fica registrado, e só. O Asaas e o Yungas **não** estão nessa lista — mas a correção é a mesma linha nos três, e o número certo do tempo limite é uma decisão só. Separá-los faria três decisões onde há uma. #### O que impede a décima `scripts/conferir-tempo-limite-rede.php` guarda as nove numa lista com o motivo de cada uma, e falha nos dois sentidos: quando aparece uma décima, e quando uma das nove some sem que a lista seja atualizada — porque lista desatualizada esconde a próxima. Ele entrou no `scripts/conferir-tudo.sh`, que passou a ser onze portões. Foi posto à prova nos dois sentidos, com um arquivo temporário que trazia duas chamadas irmãs: acusou a que não tinha tempo limite e ignorou a que tinha. **A granularidade é a função**, e isso é um limite real: uma função que abra duas conexões e defina o tempo limite só numa delas passa. Nenhuma das nove tem essa forma hoje. #### Ao resolver #### O teto do php-fpm — DECIDIDO em 31/08/2026: fica para o desenho do corte **Por decisão sua, nada muda no container agora.** A justificativa é boa: a produção está congelada e a configuração de php-fpm dela é desconhecida, então qualquer número escolhido aqui seria palpite sobre outro ambiente. E as 7 chamadas já corrigidas reduziram a exposição de nove buracos para dois. **O requisito fica escrito aqui para não ser redecidido lá.** Quem desenhar o corte precisa de três coisas, nesta ordem de importância: | | | |---|---| | 1 | `request_terminate_timeout` **acima de 21 minutos** — 1800 s serve | | 2 | pool separado para as rotinas de cron, com o do aplicativo em teto curto | | 3 | `pm.max_children` acima de 5 — mas **nunca sozinho**, ver abaixo | **E um fato que elimina o caminho fácil, para ninguém o tentar de novo:** `max_execution_time` **não serve**. Ele é a opção óbvia porque o `php.ini` é o único arquivo versionado dos três — mas ele **não conta tempo gasto fora do script**: consultas ao banco, operações de socket e chamadas de rede ficam de fora do relógio. Ou seja, ele não mata um `curl` pendurado, que é exatamente o caso deste débito. Quem mata é o `request_terminate_timeout`, porque quem o aplica é o processo mestre do php-fpm e não o script. **Subir `pm.max_children` sozinho não é teto.** Uma chamada infinita continua infinita; o esgotamento só demora mais. Vale como acompanhamento de um teto de verdade, nunca no lugar dele. **Por que o pool separado é o desenho certo, e não só o teto:** com um teto único de 30 minutos, cinco rotinas penduradas ainda ocupam os 5 workers por meia hora — e o aplicativo dos clientes divide esse mesmo pool. `marketingPush` roda **a cada minuto das 8h às 22h**, em pleno horário de uso. Com pools separados, uma rotina pendurada nunca tira worker do aplicativo. #### O número que decide o teto **O teto do php-fpm tem um número que ninguém tinha medido, e ele decide a escolha.** `request_terminate_timeout` é global do pool: ele mata *qualquer* requisição que passe do limite, e as rotinas de cron passam pelo mesmo pool. A mais demorada é `relatoriosDashboardColaboradoresAtualizar`, medida em **21 minutos na base local** — qualquer teto abaixo disso a mataria toda noite. E aqui aparece outra coisa: **o crontab dá 600 s a essa rotina.** O `curl` do agendador desiste aos 10 minutos de um trabalho que leva 21 — todas as noites, desde sempre. Ele desiste e o worker continua, então o trabalho *termina*; o que não existe é quem saiba disso. É o mesmo desenho do nginx: o limite de cima protege o chamador, nunca o processo. Portanto o teto útil está **acima de 21 minutos**, não abaixo. Algo como 1800 s não protegeria contra uma chamada lenta — protegeria contra a chamada *infinita*, que é o caso do D67. Infinito e 30 minutos são coisas muito diferentes num pool de 5. Definir um `CURLOPT_TIMEOUT` e um `CURLOPT_CONNECTTIMEOUT` nas nove chamadas, e um `request_terminate_timeout` no php-fpm como rede de segurança para o que escapar. O teto do php-fpm é o que protege contra a próxima integração escrita sem timeout, e é ele que impede que cinco chamadas penduradas derrubem o aplicativo inteiro. #### Isto não explica o D66 Conferido: o OneSignal só é alcançado a partir do `CronJobService`, e o Asaas a partir do `FranquiaService` (relatórios). **Nenhum dos dois está no caminho de nenhum endpoint exercitado pela suíte de contrato.** A tentação de fechar o D66 com este achado é grande e seria errada. #### As duas do OneSignal, em 10/10/2026 (PUSH-FCM-ENVIO) O dono decidiu a troca do OneSignal pelo Firebase, e a ordem de ignorar o OneSignal cedeu para esta migração. A classe `module/ISBase/src/Util/OneSignal.php` saiu; o envio mora em `module/ISBase/src/Push/`, e o único `curl_init` dele (`ClienteHttpCurl::postar`) tem os números do Asaas -- 5 s para conectar e 30 s ao todo -- com a conferência do certificado ligada (`CURLOPT_SSL_VERIFYPEER`, e `CURLOPT_SSL_VERIFYHOST` em 2). O pedido ao OneSignal é o mesmo byte a byte; o do FCM passa pelo mesmo cliente. A lista do `scripts/conferir-tempo-limite-rede.php` ficou vazia: as nove têm tempo limite, e qualquer chamada nova sem ele reprova. **Provado** no `EnvioDePushTest`, contra servidores de mentira no 127.0.0.1: o que aceita e cala por 6 s é largado em 1 s (o caso usa o limite de 1 s), e o TLS de certificado próprio é recusado. Os dois mutantes -- sem o `CURLOPT_TIMEOUT`, e com o SSL desligado -- deixam os casos vermelhos, e o primeiro também o portão. **Na verificação do mesmo dia**, os números da produção ganharam guarda, porque o caso de 1 s só provava o mecanismo: o `testOsTemposDaProducao` prende os 30 s e os 5 s do cURL que a fábrica monta (`FabricaDoPush::clienteHttp`), e o construtor recusa o zero -- que no cURL é "sem limite", este débito de volta, calado. E o `testOCertificadoEConferido` passou a provar o nome além da cadeia: um certificado dado como confiável e com outro nome (`outro.exemplo`) é recusado, e o mesmo confiável com o nome certo passa. Os mutantes novos -- `TEMPO_LIMITE` em 0, a fábrica com uma hora de limite, o construtor aceitando o zero, `CURLOPT_SSL_VERIFYHOST` em 0 -- deixam os casos vermelhos. **O que fica:** o teto do php-fpm (`request_terminate_timeout`), decidido em 31/08/2026 para o desenho do corte, continua sem existir. E um provedor que aceita e cala ainda segura o worker 30 s por destinatário -- numa campanha de 6.573, horas: o disjuntor para isso (parar a rodada depois de algumas falhas de transporte seguidas) não foi feito, e está no D461. (O FCM ganhou, na verificação, um disjuntor para o 429 e o 5xx, que são resposta; o tempo limite, que é silêncio, segue sem ele nos dois provedores.) O liga-desliga do push (o achado 1, `OneSignal::ativo()`) saiu com a classe sem ser ligado a nada: foi ao lote de perguntas (ligar ao despachante, retirar a tela, ou esperar o aplicativo novo). #### Em 11/10/2026 (PUSH-TERCEIRA-RODADA): o teto escrito no corte, e o liga-desliga decidido **Os três requisitos do php-fpm** decididos em 31/08/2026 (o `request_terminate_timeout` acima de 21 minutos, o pool separado para o cron e o `pm.max_children` nunca sozinho) estão agora em `docs/procedimento-de-corte.md`, "Antes da janela" > "Preparação, sem tocar em produção", item 4, com o porquê de cada um e o `max_execution_time` que não serve -- para o corte não os esquecer. **Aplicar é do dono**, no servidor da produção: a configuração do php-fpm de lá não está no repositório. Nada mudou no contêiner. Este débito segue parcial pelo que o título diz: o teto não existe em servidor nenhum. **O liga-desliga, decidido pelo dono** (a resposta 76, a opção (c)): **como está até o aplicativo novo**, e decidido lá, junto com o que o aplicativo novo lê do `public/app.json`. Nada mudou no código: a tela segue gravando o campo `push`, e nenhum envio o lê. O guia do aplicativo pede a quem o mantém que diga se o aplicativo lê o arquivo, e para quê. #### Em 15/10/2026 (RESPOSTAS-DE-15-10): os três na janela, e o teto curto do site no lote **A resposta 205 (a) do dono** põe os três requisitos **na janela** da etapa 1 (`docs/procedimento-de-corte-etapa-1.md`, os passos 8 e 9), e não "antes da janela", e diz que a volta não os desfaz. A verificação da fatia achou que o teto curto do requisito 2, no pool do site, mataria as rotinas que a volta devolve a ele: foi ao lote como o **D497**, e até a resposta o pool do site fica com o teto das rotinas. O teto segue sem existir em servidor nenhum. ### D68 — Onze rotinas de cron não deixam rastro, e são as que mais podem travar — DECIDIDO em 31/08/2026, e o portão consertado em 14/09/2026 — DECIDIDO, e a falha do push vai ao registro desde 10/10/2026 Descoberto em 31/08/2026, ao conferir se o registro do `marketingEnvios` — que estava depois de um `return` (**D67**) — chegava mesmo a acontecer. #### A prova de que não acontecia O log das rotinas, `data/logs/log_scripts.txt`, tem 5.451 linhas e vai de 25/04/2024 a 28/07/2026, que é a data da cópia da produção. Nele: | | | |---|---| | última linha de `marketingNotificacoes` | **05/12/2025** | | campanhas que a produção enviou entre 05/12/2025 e 28/07/2026 | **217**, das quais 59 push | **A rotina rodou, trabalhou e não escreveu uma linha em oito meses.** Não é o caso de "não havia campanha": a tabela `notificacoes` conta 217. O `return` de sucesso estava três linhas acima do registro. Corrigido em 31/08/2026: o registro passou para antes do laço, que é onde a própria mensagem dele diz que ele pertence — ela começa com "iniciou". Assim ele também sobrevive a uma execução que morra no meio, que é justamente quando saber que ela começou importa. O nome na mensagem também estava velho: `marketingNotificacoes` virou `marketingEnvios` em algum rename, e as 58 linhas antigas do log usam o nome anterior. **Não executei a rotina para provar que agora ela registra.** Executá-la manda mensagens de verdade para pessoas de verdade. A prova é estrutural: o registro está antes do `return`, e o detector de código inalcançável, que apontava este trecho, deixou de apontá-lo. #### E aí a pergunta maior Das 30 ações do `CronJobController`, três são endpoints de consulta e não rotinas. Das 27 que sobram: | | | |---|---| | registram alguma coisa | 15 | | **não registram nada** | **11** | **Eram 12 até 31/08**, quando o `yungasNpsAtualizar` foi removido pela decisão do **D43**. Das 30 ações do controlador restam 29, das quais 26 são rotinas. As onze mudas: | Rotina | Observação | |---|---| | `notificarAniversario` | **manda push** | | `clientesNotificarPrimeiraVisita` | **manda push** | | `clientesNotificarSentimosSuaFalta` | **manda push** | | `marketingPush` | **manda push** | | `marketingPushOutros` | **manda push** — delega para `marketingPush` | | `vencimentoPontuacaoProgramaFidelidade` | | | `relatoriosDashboardFaturamentoAtualizar` | | | `npsNotificacoes` | | | `relatoriosRoyaltiesAtualizar` | delega para `FranquiaService` | | `relatoriosRoyaltiesFaturasGerar` | delega para `FranquiaService` | | `relatoriosRoyaltiesFaturasAtualizar` | delega para `FranquiaService` | **As cinco rotinas que enviam push estão entre as onze mudas.** São exatamente as que chamam o OneSignal sem tempo limite (**D67**): as que mais podem ficar penduradas são as que não deixariam rastro de terem ficado. **Este registro nasceu dizendo oito, e são onze.** A primeira contagem foi minha, à mão, e ela parou nas ações cujo método de serviço tem o mesmo nome. As quatro que faltavam delegam para um método de **outro** nome — três para `FranquiaService`, uma para `marketingPush` — e eu as deixei de fora sem olhar dentro. É a terceira contagem à mão que erra nesta semana, e as três foram corrigidas por um roteiro. Este é o roteiro. #### Por que isto é da mesma família do D43 e do D50 Uma rotina que para não dá erro — ela simplesmente deixa de acontecer, e o sintoma aparece longe. O D43 é uma rotina que ninguém dispara; o D50 é uma que dispara e cujo efeito ninguém vê. Este é o terceiro modo: **a que roda e não conta.** `scripts/conferir-agendamento.php` pega o primeiro caso; nenhum roteiro pega este. #### Ao resolver #### A DECISÃO, tomada em 31/08/2026 **Por decisão sua, nenhuma das onze é instrumentada no legado.** O requisito passa para o sistema novo, e o portão fica. O raciocínio que sustenta a escolha: **uma linha de log só vale quando o código roda**, e este código não vai rodar num lugar onde alguém leria o log. A produção está congelada, então nada disto a alcança; o legado será substituído. Instrumentar onze rotinas que estão de saída é trabalho cujo retorno morre com elas. #### O PORTÃO PASSAVA NO DEFEITO QUE DEU ORIGEM A ESTE DÉBITO — 14/09/2026 Com a instrumentação decidida como "não se faz", **todo o valor restante deste débito é o portão**. Ele foi falsificado, e passou no teste que não devia passar. `conferir-rastro-das-rotinas.php` decidia *"tem rastro"* assim que via o token `logScripts` em qualquer lugar do corpo do método — **sem conferir se ele é alcançável**. **Reproduzi o caso histórico**: movi o registro de `CronJobService:: marketingEnvios()` para depois do `return $this->jsonResponse(true, ...)`, que é exatamente a forma que passou **oito meses mandando campanha em silêncio**. O portão saiu **verde, código 0**: *"Nenhuma rotina muda nova."* O portão que existe para impedir este defeito passava nele. **Como ficou:** o laço mantém uma pilha, um lugar por bloco aberto, marcando se aquele bloco já terminou em `return`, `throw` ou `exit`. Um `logScripts` só conta quando **nenhum** bloco aberto — o dele ou qualquer um que o contenha — já terminou. **O `nenhum` é carregante, e olhar só o bloco corrente não basta:** | forma | conta? | por quê | |---|---|---| | `if (a) { return X; }` e depois `logScripts()` | **sim** | o bloco que retornou fechou; o de fora segue vivo | | `return X;` e depois `logScripts()` | não | mesmo bloco, já terminado | | `return X;` e depois `if (a) { logScripts(); }` | **não** | bloco novo, mas o de fora já terminou | | `return` dentro de uma *closure*, e depois `logScripts()` | **sim** | a closure abre o próprio bloco, e o `return` morre com ele | As quatro foram medidas, uma a uma, e não deduzidas. **Falsificado:** com o caso histórico de volta, o portão agora sai **1** e nomeia `marketingEnviosAction`. Na árvore limpa continua verde, com os mesmos **15 com rastro e 11 mudas** — a regra nova não inventou falso positivo nenhum. #### E O NÚMERO ESTAVA ERRADO EM TRÊS LUGARES O título dizia **oito**, o corpo dizia **doze** em três parágrafos, o comentário do portão dizia **12** — e o portão **mede onze**, que é o que `$conhecidas` lista. Corrigidos os quatro. É a quarta contagem à mão deste registro a ser desfeita por um roteiro, e a lição já estava escrita aqui: *quem conta à mão erra, e o roteiro é o que não erra.* **O que fica valendo, e é o que importa:** 1. **Requisito do sistema novo:** toda rotina agendada deixa rastro do que fez — não só que rodou, mas o quê e quantos. Está escrito na seção da Fase 2 do roadmap. 2. **O portão continua de pé.** `conferir-rastro-das-rotinas.php` recusa a décima terceira rotina muda no legado. A decisão foi não instrumentar as doze, não deixar nascer a próxima. **O que isso aceita conscientemente:** o legado segue cego pelo tempo que ainda rodar, e o episódio dos oito meses do `marketingEnvios` pode se repetir sem que ninguém saiba. O `marketingEnvios` em si já está corrigido — a decisão vale para as doze restantes. #### Ao resolver, no sistema novo Um registro em cada rotina, com o que ela fez e quantos — não só que rodou. **O portão foi construído**, e eu havia escrito aqui que não valia a pena. Mudei de ideia por evidência, não por gosto: a conta à mão errou, e errou justamente neste débito. `scripts/conferir-rastro-das-rotinas.php` lê pelo `token_get_all`, segue um nível de delegação e recusa a décima terceira rotina muda. Ele entrou no `conferir-tudo.sh`, que passou a ser doze portões. Posto à prova nos dois sentidos: com uma ação muda temporária no controller ele sai com 1 e a nomeia; sem ela, sai com 0. O controller voltou byte a byte, e o `git diff` confirma. **A lista conhecida tem doze itens, e isso é o débito, não o portão.** Ele não cobra as doze — cobra a próxima. #### A falha do push, em 10/10/2026 (PUSH-FCM-ENVIO) Com a troca do push (o D461), o envio passou a ler a resposta do provedor, e a falha vai ao `data/logs/log_scripts.txt` pelo despachante (`ISBase\Push\DespachanteDePush`): o tempo limite, a chave recusada, o 5xx que não passou, a troca do token do Google que falhou, e o FCM pedido e desligado por falta da conta de serviço. Cada motivo sai uma vez por rodada, com o primeiro cliente que o teve, até 50 linhas e um aviso: uma chave errada numa campanha de 6 mil destinatários não escreve 6 mil linhas. A recusa normal ("nenhum aparelho inscrito") não vai. **As onze continuam mudas, e a decisão de 31/08 vale:** a linha de falha não diz que a rotina rodou, e o `conferir-rastro-das-rotinas.php` continua contando as cinco do push entre as mudas -- o registro mora no despachante, fora do nível de delegação que ele segue, e é o certo, porque não é o rastro de que a rotina rodou. É o envio novo (o que sobrevive à migração) que ganhou o registro, e não o legado. Provado no `EnvioDePushTest` (`testAFalhaVaiAoRegistroUmaVezPorMotivo`; os mutantes sem a deduplicação e sem o teto o deixam vermelho). #### O aviso do retrato zerado não é rastro — 07/11/2026 (a fatia 105, o D364) `relatoriosRoyaltiesAtualizar` passou a escrever no log das rotinas, mas **só** quando o retrato zera (o aviso do **D364**). Não é a linha de "rodou" — a decisão de 31/08 continua valendo, e a rotina segue entre as onze mudas. O aviso sai por `FranquiaService::escreverNoLogDasRotinas`, dois níveis abaixo da ação, e o `conferir-rastro-das-rotinas.php` segue um: a rotina continua muda **sem lista de exceção**. A primeira versão da fatia pôs no portão uma lista `$soAvisam` que pulava a ação antes de olhar o rastro — e o cegava para ela: uma linha de "rodou" posta depois em `royaltiesAtualizar` não a tiraria das mudas, e o portão nunca a mostraria em "ganharam registro, tire-as da lista". A verificação a apontou, e a correção a tirou. **Falsificado**: com a linha `logScripts('relatoriosRoyaltiesAtualizar - rodou')` posta direto na rotina, o portão sai 1 e manda tirá-la da lista; devolvida pelo sha1. ### D69 — A caracterização passa 108 de 109 contra um banco de 36 linhas — CORRIGIDO em 31/08/2026 Descoberto em 31/08/2026, por um erro meu: rodei a caracterização em segundo plano e `scripts/rodar-contrato.sh` por cima dela. #### O que aconteceu `rodar-contrato.sh` reescreve o `config/autoload/local.php` — que é compartilhado por tudo — para apontar ao `franquiabv_contrato`, e restaura no fim. A suíte de caracterização, iniciada dentro dessa janela, leu o banco de contrato do começo ao fim. **E quase não deu para perceber.** A suíte devolveu: ``` Tests: 109, Assertions: 201, Failures: 1. ``` Uma falha só, e a mensagem dela não diz nada sobre banco: *"o cenário precisa de uma linha do mês corrente para observar"*. #### O número, medido de propósito Apontei a suíte ao `franquiabv_contrato` deliberadamente e rodei inteira. O resultado reproduziu byte a byte — mesma falha única, mesmas 201 asserções: | Banco | Tabelas | Linhas | Resultado | Tempo | |---|---|---|---|---| | `franquiabv_dev` | 84 | ~15,2 milhões | 109 de 109, 203 asserções | ~14 min | | `franquiabv_contrato` | 83 | **36** | **108 de 109**, 201 asserções | **1min25** | As contagens de linha são a estimativa do `information_schema`, não um `COUNT(*)` tabela a tabela — a ordem de grandeza é o que importa aqui, e ela é de seis casas de diferença. **108 de 109 testes passam contra um banco com 36 linhas.** Não é sorte, e nem é defeito dos testes: **14 dos 19 arquivos citam a faixa 90001000+**, que as fixtures criam nos dois bancos, e cada teste roda dentro de uma transação revertida no fim. **Não depender do que já estava lá é boa qualidade de teste, e aqui ela cobra o preço** — a suíte quase não consegue perceber que está lendo o banco errado. O único teste que percebe é `CronTravaSimultaneaTest::testODashboardDesiste...`, porque ele precisa de uma linha de `dashboard_colaboradores` do mês corrente, e só a cópia da produção tem. **Um teste e duas asserções separavam "109 de 109" de "108 de 109 sobre 36 linhas."** #### O que já existia, e do lado errado `ContratoTestCase::exigirBancoDeFixtures` recusa rodar contra um banco com dado real desde o **D55**. A metade de cá nunca foi escrita. A assimetria fazia sentido quando nasceu — o estrago do D55 foi caro e visível —, mas o buraco oposto é pior: o D55 falhava em cascata e gritava; este passa. #### A correção `CaracterizacaoTestCase::exigirCopiaDaProducao`, espelho do de lá: exige uma unidade com id **abaixo** de 90000000, que só a cópia anonimizada tem. Uma consulta, uma vez por processo, ao lado da guarda de fixtures que já existia. Posta à prova: contra o `franquiabv_contrato` os 7 testes do arquivo passaram de 1 falha confusa para **7 erros com a explicação inteira** — o que é o banco, por que ele quase não é notado, os dois outros sinais que denunciam (o tempo e a contagem de asserções), e como voltar. `scripts/rodar-contrato.sh` também ganhou o aviso de que nada deve rodar junto com ele. Mas o aviso é lembrete; **quem protege é a guarda**, porque ela pega a causa independente de quem a criou — inclusive uma execução do roteiro interrompida antes do `trap`. #### O que isto não invalida A linha do roadmap que diz **109 de 109 contra PostgreSQL, com as mesmas 203 asserções do MySQL**. São 203, e o banco errado dá 201: aquela execução leu a cópia certa. **A contagem de asserções foi o que permitiu afirmar isso** — sem ela, a dúvida ficaria de pé. ### D70 — Metade do "contrato do aplicativo" não era — CORRIGIDO em 31/08/2026 > **A MESMA RAIZ VOLTOU DUAS VEZES EM 03/09/2026**, e as duas ficam registradas > no fim deste débito: o gerador do inventário lê **texto**, e comentário é > texto. Quem for mexer nele leia aquela seção antes. Descoberto em 31/08/2026, ao conferir se dava para remover a rota do **D43**. O inventário a classificava como **CONTRATO-APP**, com a nota *"versões antigas em campo; os 28 testes seguram"* — que é exatamente o motivo pelo qual alguém **não** mexeria nela. Não era evidência. `scripts/inventariar-acoes.php` atribui esse veredito em bloco a **toda** ação do módulo `ISApi`: ```php if ($a['modulo'] === 'ISApi') { return ['CONTRATO-APP', 'versões antigas em campo; os 28 testes seguram']; } ``` #### A composição das 60 | Controlador | Ações | O que é | |---|---:|---| | `CronJobController` | **29** | rotinas de cron — **o aplicativo nunca as chama** | | `AplicativoController` | 20 | a API do aplicativo de verdade | | `ApiDocsController` | 8 | documentação da API | | `VisagismoController` | 3 | visagismo (congelado por instrução) | E a suíte de contrato, medida: **27 caminhos distintos, e zero rotas de cron.** **Ou seja: 29 ações estão rotuladas como "seguradas pelos 28 testes" e não têm teste nenhum.** O rótulo não protege — ele só desencoraja mexer. #### Por que isso importa, e em duas direções **Para a Fase 2, o número está inflado.** O roadmap dimensiona a fase com "contrato do aplicativo: 60 — não se mexe". A superfície que realmente não pode mudar é a do aplicativo instalado: cerca de 20 ações, mais as 3 do visagismo. As 29 de cron precisam de tratamento *diferente*, não de tratamento *nenhum* — e 11 delas são as rotinas mudas do **D68**. **E na direção oposta, é um convite a errar.** Um rótulo que diz "protegido por testes" sobre algo que não tem teste é pior que nenhum rótulo: ele desliga a desconfiança na hora errada. Se eu tivesse acreditado nele, o D43 não teria sido resolvido — e se alguém acreditar no sentido contrário, vai mexer numa dessas 29 achando que a suíte avisaria. **Detalhe menor, mesmo defeito:** a nota diz "28 testes". São **35** desde 28/08/2026 (**D55**), quando cinco ações versionadas que o gerador não enxergava entraram na conta. #### Um segundo achado, do mesmo momento Ao regerar o inventário para tirar a linha do D43, ele mudou em coisa que **não era minha**: `Convenios::atualizarVencimento` saiu do módulo `ISConfiguracao` e `conveniosAtualizarVencimento` apareceu no `CronJobController`. A rotina mudou de lugar durante o trabalho do **D50**, e o inventário nunca foi regerado. **Ninguém teria notado.** `docs/inventario-acoes.md` e o `.csv` são gerados, mas nada confere se o gerado bate com a fonte — diferente do que já existe para schema, rotas órfãs e relações do Doctrine. #### Ao resolver Duas coisas, e a primeira é mais barata que parece: 1. ~~**Separar o veredito das ações de cron**~~ — **FEITO em 31/08/2026, por decisão sua.** 2. ~~**Um portão que regere o inventário e recuse a diferença**~~ — **FEITO em 31/08/2026**, ver abaixo. #### A separação, aplicada em 31/08/2026 `veredito()` ganhou um teste antes do bloco do `ISApi`: se o controller for o `CronJobController`, o veredito é `ROTINA` com o motivo *"rotina de cron disparada por URL; o aplicativo não a chama"*. O resto do `ISApi` continua `CONTRATO-APP`, e com razão — `AplicativoController` e `VisagismoController` são exercitados pela suíte, este último por `VisagismoApiTest`. **O que o número virou:** | Veredito | Antes | Agora | |---|---:|---:| | CONTRATO-APP | 60 | **31** | | ROTINA | 0 | **29** | | MORTA | 3 | 3 | | NORMALIZAR | 124 | **123** | | CRIAR | 158 | 158 | | ARQUIVO | 16 | 16 | As seis somavam 361 nos dois lados no momento da separação: nada apareceu nem sumiu, só mudou de coluna. **O 123 do NORMALIZAR veio de outra correção, no mesmo dia** — a ação fantasma que a seção seguinte descreve. O total passou de 361 para **360**. **Antes de mexer, reconferi a premissa** — a suíte de contrato exercita **25** caminhos distintos, e **nenhum** é rota de cron. *Correção de registro:* a mensagem do commit `8d6c214` diz "27 caminhos distintos"; são 25. A conclusão não muda, o número estava errado. #### E o portão pegou uma ação que nunca existiu O portão do inventário ganhou, em 31/08/2026, um **segundo contador**: comparar gerado-contra-commitado tem um ponto cego, porque os dois vêm do mesmo gerador — se ele parar de enxergar uma ação, os dois concordam e o portão fica verde. Esse segundo contador usa `token_get_all`, enquanto o gerador usa expressão regular sobre o texto. **Na primeira vez que rodou, ele discordou: 360 contra 361.** A diferença era `ISCadastro\VisagismoController::processarImagem`, e ela **não existe**: ```php // public function processarImagemAction() { // $request = $this->getRequest(); ``` **O método inteiro está comentado.** A regex procura `function ...Action(` no texto, e comentário é texto — então a ação entrou no inventário como se existisse, e foi até classificada: *NORMALIZAR, "já devolve JSON"*. Um veredito completo sobre código que ninguém executa. É a mesma família do **D43**, onde uma rotina de 27 linhas comentadas tinha rota e respondia sucesso. E é a razão de o segundo contador existir: **um número sozinho não se contradiz.** **E a correção enfraqueceu o próprio contador, o que precisa ser dito.** Quando ele nasceu, o gerador usava só a expressão regular e a independência era total. Agora o gerador cruza a regex **com** o tokenizador — o mesmo mecanismo do contador. Ele continua pegando uma regex que quebre ou passe a ver de menos, e continua pegando `Action` dentro de comentário; **não pega** um erro de lógica que os dois compartilhem. O que sobra de independente é pouco: o contador exige visibilidade pública e o gerador não. Está escrito no cabeçalho do próprio roteiro, com a alternativa honesta para o dia em que a completude do inventário voltar a importar de verdade: contar as rotas declaradas no `module.config.php` e cruzar com as ações — evidência de outra fonte, não do mesmo leitor. **A correção no gerador é de risco mínimo.** O tokenizador diz quais nomes são reais; a regex continua fatiando os corpos, porque é ela que tem os deslocamentos. Como `$fim` vem do array bruto de deslocamentos, pular a fantasma **não altera o corpo de nenhuma outra ação** — só some a linha dela. O inventário passou de 361 para **360**, e `NORMALIZAR` de 124 para **123**. **Duas coisas que pareciam defeito e não eram**, conferidas no caminho: - O CSV commitado tinha **0** ações `ROTINA`, não 1 — então o "Rotina ou morta: 4" que o roadmap trazia já estava velho antes desta mudança. - `conveniosAtualizarVencimento` parecia ter sumido do inventário. Não sumiu: eu havia grepado `atualizarVencimento` em minúscula, e ela mudou de nome ao mudar de módulo no **D50**. Está lá, agora como `ROTINA`. #### O portão existe desde 31/08/2026 `scripts/conferir-inventario-atual.sh` guarda os dois arquivos, roda o gerador, compara e **devolve os originais** — aconteça o que acontecer, inclusive se o gerador morrer no meio. Ele nunca altera o repositório; quando acha diferença, imprime o `diff` e o comando para você regerar. Entrou no `conferir-tudo.sh`, que passou a ser **treze portões**. **Posto à prova nos dois sentidos:** com uma linha inventada acrescentada ao CSV commitado, ele sai com 1 e nomeia a linha; sem ela, sai com 0. E o `git status docs/` ficou vazio depois das duas execuções, que é a prova de que ele não altera nada. **Duas guardas contra o verde falso**, das que esta semana ensinou a colocar: | | | |---|---| | Gerador que falha | a saída dele é impressa e o roteiro sai com **2**, não com 0 | | Arquivo curto demais | menos de 300 linhas no `.md` ou 200 no `.csv` sai com **2** | A segunda existe porque comparar dois arquivos igualmente vazios passa — e passaria em silêncio, que é o modo de falha que mais custou nesta semana. #### A MESMA RAIZ, DUAS VEZES EM 03/09/2026 — e uma delas era antiga O D70 nasceu porque o gerador contava um **método inteiramente comentado** como ação: ele procurava `function ...Action(` com expressão regular sobre o texto, e comentário é texto. Aquilo foi corrigido cruzando a regex com o tokenizador. **A mesma raiz sobrevivia noutra coluna.** As colunas `servicos` e `repositorios` — que dizem "de onde vem o dado", e por onde se estima o trabalho da Fase 2 — eram extraídas por regex sobre a fatia de texto entre uma ação e a seguinte. Duas consequências, medidas ao mexer no `AplicativoController`: 1. **Comentário virava dado.** Um docblock que cita `FranquiaService` fez o inventário atribuir aquele serviço a uma ação que nunca o usou. 2. **E era atribuído à ação ERRADA.** A fatia vai de uma ação até a próxima por deslocamento, então ela engole o docblock da ação *seguinte* — o serviço citado ia para a ação *anterior*. Corrigido lendo o corpo **sem comentários**, pelo tokenizador. Três linhas mudaram, e **duas eram anteriores a esta sessão**: | Ação | Atribuição falsa | De onde vinha | |---|---|---| | `CronJobController::relatoriosDashboardFaturamentoAtualizar` | `FranquiaService` | docblock da ação seguinte | | `AgendasController::checkin` | `VendaPagamentoService` | uma chamada **comentada**, na linha 491 | | `AplicativoController::paisesSelecionar` | `FidelidadeService` | docblock que eu mesmo escrevi hoje | A segunda é a mais parecida com o D70 original: `// $this->serviceVendaPagamento->gerarCupons(...)` está comentada, e o inventário dizia que aquela ação dependia do serviço. **Não é a única vez que o inventário mentiu nesta sessão.** As outras duas — a chave de "rota declarada" sem o controller, e a colisão de namespace ao achatar para o basename — estão em `docs/f2-fatia-pdv.md`. Somando: **45 atribuições falsas** corrigidas em um dia, num arquivo que dimensiona uma fase inteira. --- ### D71 — 87 linhas de royalties duplicadas, e o `SUM` só acerta por acidente — PREPARADO em 13/09/2026 Descoberto em 31/08/2026, ao decidir o **D44**. O débito dizia que a unicidade de `royalties` "não existe em banco nenhum" e que ali a trava é a única proteção. Faltava perguntar se a corrida já tinha acontecido. Tinha. #### Medido na cópia da produção | | | |---|---:| | Pares `(unidade, data)` repetidos | **87** | | Linhas envolvidas | 174 | | Unidades afetadas | **29** de 62 | | Janela | **25/11/2025 a 14/12/2025** | | Fora dessa janela | **nenhum** | **É um episódio, não um regime** — vinte dias, como os 41 caixas negativos de 2018 no **D20**. Mas metade das unidades passou por ele. **O mesmo defeito de origem está no D40**, em `dashboard_colaboradores`, e ali a consequência é oposta: aquela consulta agrupa e o banco devolve uma linha arbitrária, então **o número exibido pode estar errado hoje**. Aqui a consulta soma, e o número está certo. Mesma corrida, resultados opostos — e por isso os dois débitos ficam separados. **Em cada par, uma das linhas está zerada e a outra tem o valor.** A soma de `MIN(ret_total)` sobre os 87 pares dá exatamente **0**, o que só acontece se toda duplicata tiver um lado vazio. É a assinatura do ler-e-criar-se-não-existe: um processo criou a linha, o outro criou de novo, e só um preencheu. | | | |---|---:| | Pares com royalty divergente | 44 | | Maior divergência de royalty | R$ 360,10 | | Royalty total em jogo | **R$ 5.030,67** | | Maior divergência de faturamento | R$ 11.226,20 | #### Ninguém foi cobrado errado — e é aí que mora o problema `RoyaltiesRepository::relatorioFranquias` agrega com **`SUM`**. Como um lado de cada par é zero, a soma devolve o valor certo. **O dinheiro está correto hoje.** Mas isso é acidente de dois fatos que se cancelam, e ambos podem mudar: ```php // RoyaltiesRepository::selecionarPorDataUindade ->setMaxResults(1)->getOneOrNullResult(); // sem ORDER BY ``` A rotina lê **uma** das duas linhas, e qual delas não é determinado — não há `ORDER BY`. Hoje ela vem escrevendo na que já tem valor. **Se um recálculo dessas datas pegar a linha zerada, as duas ficam preenchidas e o `SUM` passa a dobrar o faturamento daquele dia.** O erro seria silencioso e para mais, num número que a franquia cobra. O `LIMIT 1` sem `ORDER BY` é a mesma família do **D46** e do **D47**, e os portões daqueles não pegaram este: eles varrem listagens paginadas e ordenação por coluna anulável, não `setMaxResults(1)` em consulta de leitura pontual. #### O que existe de proteção, e o que não existe | | | |---|---| | Restrição de unicidade no MySQL | **não existe** (**D29**) | | Restrição de unicidade no PostgreSQL | **não existe** — a do dashboard entrou, esta não | | Trava de execução | existe desde 30/08 (**D44**), e é de arquivo | A trava chegou **depois** do episódio, o que explica por que ele não se repetiu desde então. Mas ela é `flock`: protege contra dois processos na mesma máquina e não entre nós, e a F1.7 tem mais de um. #### DECIDIDO em 31/08/2026: registrar e decidir depois **Por decisão sua, nada é corrigido agora.** O raciocínio: ninguém está sendo cobrado errado, a janela foi de vinte dias há nove meses, e a decisão volta junto com o desenho do corte. **O que fica escrito para essa hora**, e é barato quando chegar: 1. `UNIQUE (unidade, data)` no `postgres/schema.sql`. 2. A limpeza dos 87 pares em `scripts/pre-migracao-limpeza.sql`, que já existe e já roda antes do dump. **Apagar a linha zerada preserva a soma exatamente** — é a limpeza mais segura que se pode fazer, porque o valor não muda. 3. Um `ORDER BY` em `selecionarPorDataUindade`, para que "qual das duas" deixe de ser sorteio enquanto as duas existirem. **O item 2 tem prazo:** se a unicidade entrar sem a limpeza, a carga falha nos 87 pares. Os dois andam juntos ou nenhum anda. #### OS TRÊS ITENS ESTÃO FEITOS — 13/09/2026 E o terceiro já estava, sem que este registro soubesse. | item | onde | quando | |---|---|---| | **1.** a unicidade | `scripts/gerar-ddl-postgres.php`, em `$unicidades`, e o `postgres/schema.sql` regerado | hoje | | **2.** a limpeza | `scripts/pre-migracao-limpeza.sql`, bloco 8 | hoje | | **3.** o `ORDER BY` | `RoyaltiesRepository::selecionarPorDataUindade` — `ORDER BY roy.id ASC` | **já estava**, no commit `6ba8609` | **Nada disto toca produção nem o schema do servidor.** Os dois artefatos são da **migração**: a limpeza roda antes do corte, e a restrição nasce com o schema PostgreSQL. O `ensaiar-corte.sh` já exercita os dois localmente, na ordem limpeza → schema → carga. #### A REGRA SE ESCOLHE SOZINHA, e é isso que tira a decisão da frente O registro dizia que fica a linha de menor id *"porque é a limpeza mais segura que se pode fazer, porque o valor não muda"*. Remedido hoje, com a pergunta feita de outro jeito — não *quanto some*, mas *onde está o valor*: | | | |---|---:| | pares com as **duas** linhas zeradas | **41** | | pares com exatamente **uma** com valor | **46** | | destes, quantos têm o valor no **menor id** | **46 de 46** | | pares com as **duas** tendo valor | **0** | Não é que apagar o maior id seja *seguro*: é que **as 87 linhas que saem são todas as 87 todo-zero**. A soma se preserva por construção, e a conferência fecha ao centavo: ``` fat_total 57.632.640,83 -> 57.632.640,83 ret_total 2.422.062,28 -> 2.422.062,28 ``` Ao contrário do bloco 6 da mesma limpeza — o do **D40** —, aqui **nenhum número de relatório se mexe**. Lá é preciso avisar quem lê que o valor exibido muda; aqui não há o que avisar. #### A CÓPIA RESPONDE POR PRODUÇÃO, e isso foi conferido `royalties` **não** está entre as nove tabelas que o anonimizador toca, e a tabela está **completa**: `MAX(id)` 32.580 contra `AUTO_INCREMENT=32.581` no `mysql.sql` — o portão de completude do D181 a dá por inteira. O número de 87 é o de produção, não um recorte. #### O QUE CONTINUA ABERTO **A limpeza e a restrição ainda não rodaram contra dado de verdade.** Elas são passos do corte, e por decisão de 11/09/2026 o corte é a única janela. Até lá o `SUM` do relatório continua acertando **por acidente** — porque a duplicata é zerada —, e é por isso que o título diz *preparado*, e não *corrigido*. --- ### D72 — 37 buscas escolhem uma linha sem dizer qual — 6 restam, sem consequência medida, e o número publicado estava velho em três lugares — PARCIAL, lido em 05/10/2026 — CORRIGIDO em 08/11/2026: as três que restavam têm escritor único e travado, e o portão está em zero > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito sem marca de estado, e o corpo diz que ele está parcial: uma parte está consertada, e a outra não. Falta: restam 3 buscas sem ordem (o D349 baixou de 6 para 3 em 04/10); o conserto é a unicidade do D29, schema em produção. Descoberto em 31/08/2026, ao registrar o **D71**. Aquele débito acusou uma consulta com `setMaxResults(1)` e sem `ORDER BY`, e a pergunta seguinte era óbvia: quantas mais existem? #### Onde está, em 05/09/2026 Este registro é longo porque a triagem é o trabalho. O estado atual, para quem chega agora: | | | |---:|---| | **10 famílias, 12 consultas** | consertadas, cada uma com a regra escrita no método e presa por teste | | **13** | dispensadas, com o motivo escrito dentro do método | | **6** | restam — e **nenhuma tem consequência medida** | | — | um contador no CI impede que virem 15 | As dez, na ordem em que caíram: o **pacote** debitado na venda, a validação de **telefone**, o **certificado** da VipClass, a validação de **e-mail**, o **saldo** do cliente, o **débito** da venda, os **textos** que a unidade envia, o **cupom** aplicado e queimado, as três consultas do **NPS** (uma família) e o **bilhete** do sorteio. **A regra não é a mesma nas dez, e essa é a parte que não dá para automatizar:** no saldo e no débito vale a linha *original*, porque é onde o dinheiro está; nos textos da unidade vale a *editada por último*, porque é o que alguém revisou; no pacote e no cupom vale *o que vence antes*, porque é o que evita perda. Trocar `setMaxResults(1)` por `setMaxResults(1) ORDER BY id` em massa teria produzido código estável e errado em quatro delas. As 6 que restam esperam decisões que não são de código: unicidade em produção (**D29**), a limpeza pré-migração (**D40**), o desenho do corte (**D71**) e uma decisão sua sobre o OneSignal. **Dois defeitos novos apareceram durante a triagem**, e não são de ordem: o **D93** (duas consultas do mesmo par perguntam o mês de jeitos diferentes) e o **D94** (a busca do bilhete não filtra pelo sorteio). #### Medido | | | |---|---:| | Métodos examinados | 3.908 | | Com `setMaxResults` e **sem** ordem | 74 | | Destes, **agregação** (`SELECT SUM/COUNT/...`) — ordem não muda nada | 37 | | Destes, **selecionam linhas** — a ordem decide qual vem | **37** | **Só a segunda metade é assunto.** Numa agregação, `setMaxResults(1)` devolve a única linha que existe; em `SELECT c FROM Cliente c WHERE ...`, ele devolve *uma* das que casarem, e **qual não está definido** — nem entre bancos, nem entre duas execuções no mesmo banco. **Cheguei a três números errados antes deste.** O primeiro foi 72, sem separar agregação. O segundo classificou por `getSingleScalarResult`, e deu "0 agregações" — implausível, porque este código usa `getOneOrNullResult` para os dois casos. O terceiro olha a cláusula `SELECT` da própria DQL, que é onde a resposta estava desde o começo. #### Por que isso é débito e não estilo Cada uma dessas 37 está correta **se e somente se** no máximo uma linha casar. E **nada no banco garante isso**: o **D29** mediu zero restrições de unicidade em todas as tabelas, MySQL e PostgreSQL. Ou seja, 37 consultas cuja correção depende de uma promessa que ninguém faz. **Uma já foi cobrada:** `RoyaltiesRepository::selecionarPorDataUindade`, com 87 pares duplicados na base (**D71**). Ali o estrago está contido por acidente — uma das linhas de cada par está zerada e o relatório soma. #### O que NÃO é o caso, e vale dizer `UsuarioRepository::autenticacao` está na lista, e a leitura assustadora seria "a autenticação escolhe um usuário arbitrário entre logins duplicados". **Não é.** O **D31** já apurou isso em 19/08/2026: das 389 linhas em login duplicado, **uma** está ativa e 388 são de colaboradores desligados, e a consulta filtra `status = 1`. A autenticação é determinística hoje. Fica o risco condicional que o próprio D31 nomeia: reativar um colaborador antigo cujo login coincida com o de alguém ativo cria a duplicata entre ativos — e aí a falta de `ORDER BY` deixa de ser teórica. #### A triagem, medida em 31/08/2026 Das 37, **29 puderam ser medidas automaticamente** contra a cópia da produção: para cada uma, quantas combinações dos valores que ela filtra têm mais de uma linha hoje. As outras 8 usam função de data no filtro ou dependem de `JOIN`, e foram medidas à mão logo abaixo — **as 37 estão todas classificadas.** **Onde a busca PODE devolver mais de uma linha hoje:** | Combinações repetidas | Busca | Exato? | |---:|---|---| | **10.000** (até **26** clientes no mesmo telefone) | `clientes` por telefone | exato | | 167 | `vipclass_checkpoints_usuarios` por vipclass+usuário | exato | | 15 | `clientes_debitos` por venda | exato | | 7 | `cupons_clientes` por cliente | teto | | 4 | `sorteios_vendas` por venda | exato | | 3 | `clientes_creditos` por cliente+unidade | exato | | 3 | `nps_resultados_unidades` por unidade+mês+ano | exato | | 3 | `sorteios_vendas` por sorteio+ganhador | teto | | 2 | `push_app` por cronjob | exato | | 1 | `unidades_mensagerias` por unidade | exato | **"Teto"** quer dizer que a consulta tem filtros que o medidor não soube aplicar — um `JOIN`, uma comparação de data —, então o número real é menor ou igual. #### As 8 que faltavam, medidas à mão em 31/08/2026 As 29 acima saíram do medidor automático. As outras 8 usam função de data no filtro ou dependem de `JOIN`, e foram traduzidas para SQL uma a uma: | Combinações repetidas | Busca | O que significa | |---:|---|---| | **2.083** (até 37) | `logradouros` por CEP | um CEP geral cobre muitas ruas; o preenchimento de endereço sugere uma delas | | **99** (até 7) | `clientes_pacotes` por cliente+unidade+produto | **ver abaixo — a segunda com consequência real** | | 87 | `royalties` por unidade+data | é o **D71** | | 5 | `nps_resultados_colaboradores` por colaborador+mês+ano | a corrida que o **D44** já descreve | | 3 | `nps_resultados_unidades` por unidade+mês+ano | idem | | 0 | `royalties_faturas` por unidade+vencimento | | | 289.042 | `vendas_produtos` por cliente+produto | **irrelevante**: os dois chamadores são `if (empty(...))`, regras de cupom "consumiu"/"não consumiu" | | — | `pesquisaNpsLocalizarClientePorId` | **segura por construção**: agrupa por `cli.id` e filtra `cli.id = :id`, então no máximo uma linha | Com isso, **as 37 estão todas classificadas.** #### A segunda com consequência real: qual pacote é debitado `ClientePacoteRepository::selecionarPacote` escolhe **um** pacote ativo do cliente para aquele produto, e o chamador **usa o objeto**, não só a existência: ```php $vendaProduto->setValorUnitario($pacote->getValorSessao()); $vendaProduto->setDescontoMotivo($pacote->getItem()->getPacote()->getNome()); $vendaProduto->setPacote($pacote); ``` Medido: **99 clientes** têm mais de um pacote ativo do mesmo produto. E eles não são intercambiáveis: | | | |---|---:| | Com `valor_sessao` **diferente** entre os pacotes | **36** | | Maior diferença por sessão | **R$ 45,00** | | Com **validade** diferente | **84** | Duas consequências, e nenhuma é teórica: 1. **O valor gravado na venda depende de qual linha o banco devolveu** — em 36 casos há mais de um valor possível, com até R$ 45 de diferença por sessão. 2. **Em 84 casos o pacote consumido pode não ser o que vence antes**, e aí o cliente perde sessões de um pacote que expira enquanto o outro é gasto primeiro. Aqui o `ORDER BY` não é detalhe de estilo: **é a regra de negócio que ninguém escreveu** — consumir primeiro o que vence antes, ou o mais barato, ou o mais antigo. Como não está escrita, o banco decide. #### A primeira com consequência visível: o telefone `ClienteRepository::selecionarClientesPorTelefone` tem quatro chamadores. Dois apenas perguntam se existe, e para isso tanto faz qual linha volta. **Os outros dois usam o id da linha sorteada:** ```php // ClientesController:759 if (!empty($clienteTelefone) && $clienteTelefone['id'] != $request['id']) { $validacao['mensagem'] .= "- Telefone já cadastrado
"; $validacao['responsavel_id'] = $clienteTelefone['id']; } ``` Com 26 clientes ativos no mesmo telefone, **se a linha sorteada for o próprio cliente que está sendo editado, a validação passa; se for outro dos 26, ela bloqueia** — e oferece um "responsável" arbitrário entre os homônimos de telefone. `ClientesController::validarTelefone` tem a mesma forma. Não é hipótese: é o comportamento de hoje, e ele muda entre duas execuções da mesma tela. A causa de fundo dos 10.000 é o **D32** — telefones de balcão compartilhados por muitos clientes. #### Quatro falsos alarmes, derrubados por medição Números que pareciam graves e não eram. Ficam registrados porque a próxima pessoa vai reencontrá-los: | Parecia | É | Por quê | |---:|---:|---| | `caixas` 504 | **0** | as duplicatas são de caixas **fechados**; a consulta busca `status = true` | | `vendas` 532 | **0** | o filtro `status IS NULL` (venda temporária) elimina todas | | `cupons_clientes` 8.712 | **7** | eu agrupava por `status+cliente` sem aplicar `status = 1` | | `pontuacoes_historicos` 149.109 | **irrelevante** | é verificação de existência: `if (empty($historico))`. E na família que a guarda protege — "Completou a etapa N" — são **2** pares repetidos, valendo **20 pontos**. | #### Seis medições erradas antes da certa Vale registrar o caminho, porque cada erro tinha uma forma diferente: 1. **72**, sem separar agregação de seleção de linhas. 2. Classificação por `getSingleScalarResult` → "0 agregações", implausível: este código usa `getOneOrNullResult` para os dois casos. 3. **37/37** pela cláusula `SELECT`, que é onde a resposta estava. 4. Agrupamento sem excluir nulos — os "2 tokens repetidos" eram 2.426 linhas com token **nulo** agrupadas entre si. 5. Excluir vazio com `<> ''` em coluna **numérica**: no MySQL isso vira `<> 0` e apagou silenciosamente todos os caixas fechados. 6. Agrupar por colunas que a consulta fixa num literal, em vez de filtrar por ele — foi o que inflou `caixas` e `cupons_clientes`. #### Seis dos dezesseis zeros não são confiáveis Das 29 medidas, 16 não têm duplicata na cópia local. **Seis desses zeros são artefato da cópia, não do sistema:** | Busca | Por que o zero é falso | |---|---| | `dashboard_colaboradores` (3 métodos) | `pre-migracao-limpeza.sql` **remove** essas duplicatas (linha 137, citando o **D40**, que mediu 107 em produção) | | `usuarios` por login, e-mail (3 métodos) | a anonimização reescreveu as colunas para valores únicos (**D31**) | É a segunda armadilha do mesmo tipo neste débito, e a terceira no dia. **Zero na cópia local não é evidência de conserto.** #### Ao resolver Não é acrescentar `ORDER BY` nas 37. Em boa parte delas a ordem certa é "nenhuma, porque não deveria haver duas" — e nesses casos o conserto é a **restrição de unicidade** (D29), que transforma um empate silencioso em erro do banco. O `ORDER BY` serve onde o empate é legítimo e alguém precisa da mais recente ou da mais antiga; ali a ausência dele é bug de verdade, e a triagem das 37 nessas duas famílias é o primeiro passo. ~~**Não construí portão para isto.** Os portões que existem cobrem listagens paginadas (**D47**) e ordenação por coluna anulável (**D46**); este caso escapa dos dois. Um portão aqui nasceria com 37 itens na lista conhecida, e uma lista desse tamanho documenta o débito em vez de proteger contra ele — a decisão de triar vem antes.~~ **Riscado em 05/09/2026, e o raciocínio errado vale mais que a conclusão.** Eu comparei com portão-em-zero, que de fato não cabe aqui, e concluí "nenhum portão". A terceira forma já existia neste projeto e eu não a considerei: **contador com linha de base**, como o `conferir-injecao-dql.php` faz com as 31 concatenações que ninguém vai remover. Ele não pede lista vazia — pede que o número não cresça. Está descrito logo abaixo. #### As duas com consequência real estão consertadas — 05/09/2026 Não as 37. **As duas que o próprio débito nomeou** como tendo efeito visível: o pacote debitado na venda e a validação de telefone. As outras 35 continuam abertas, e a triagem delas continua sendo o primeiro passo. **Os consertos são de formas diferentes, e a diferença é a lição:** | | O pacote | O telefone | |---|---|---| | o que faltava | a **regra** de qual escolher | a **pergunta** certa | | o conserto | `ORDER BY` que escreve a regra | mover a exclusão para dentro da consulta | ##### O pacote: "vence antes, sai antes" `ClientePacoteRepository::selecionarPacote` passou a ordenar por validade crescente, com desempate por `id`. Das ordens possíveis — mais barato, mais antigo, o que vence antes — **as três dão resposta estável, e só uma evita perda**: gastar primeiro o perecível é a única em que o cliente não vê um pacote expirar com saldo enquanto o outro era consumido no lugar dele. A regra não existia em lugar nenhum do sistema. Agora está escrita no método que a executa, e presa por seis testes. **Validade nula quer dizer "não vence", e por isso vai por ÚLTIMO** — foi preciso um auxiliar novo, `Ordenacao::nulosPorUltimo()`. Ele não é o `comoMysql()` do **D46** com outro nome: aquele *preserva* onde o MySQL punha o nulo, porque a tela já era assim; este **decide**, porque aqui a regra do MySQL é que está errada. `ORDER BY validade ASC` cru poria o pacote eterno na frente do que vence amanhã. ##### O telefone: o conserto não foi ordenar `ClienteRepository::selecionarClientesPorTelefone` ganhou um parâmetro `$exceto`, e os dois chamadores que comparavam o id **depois** passaram a excluí-lo **dentro** da consulta. A validação sempre quis saber *"alguém ALÉM deste cliente usa o número?"*, e perguntava *"me dê um cliente deste número"* para conferir o id em seguida. Com 26 clientes na mesma linha, a resposta dependia de qual linha o banco sorteasse — e a pergunta reescrita **não depende de ordem nenhuma**. A ordem entrou mesmo assim, por causa do segundo uso: a tela oferece o id devolvido como *responsável* pelo cadastro, e uma sugestão que muda a cada F5 é pior que nenhuma. `cl.id ASC` é o cadastro mais antigo da linha. ##### Uma correção ao que este débito mediu O número **99** — clientes com mais de um pacote ativo do mesmo produto — e os que dependem dele (**36** com valor diferente, até **R$ 45,00**; **84** com validade diferente) foram medidos **sem o filtro de validade**. Os dois chamadores de produção passam `date('Y-m-d')`, e o filtro elimina a maior parte: | | | |---|---:| | pacotes ativos com saldo | 533 | | **destes, já vencidos** | **452** | | combinações ambíguas para o chamador real | **1** | | e nela, valores diferentes | 0 | **A ambiguidade viva hoje é uma, e inofensiva** — dois pacotes de mesma validade e mesmo valor. O débito continuava real (nada no banco promete unicidade, e a cópia é uma foto de um dia), mas a frase "até R$ 45,00 de diferença" descrevia pacotes que a consulta nunca chegava a ver. Fica corrigida aqui em vez de apagada acima: o erro foi *medir a tabela em vez de medir a chamada*, e ele é fácil de repetir. ##### Um defeito de brinde, no mesmo método `selecionarPacote($cliente, $unidade, $produto, $validade)` **descartava o argumento**: usava-o só como "filtrar ou não" e comparava com `date('Y-m-d')`. Quem passasse outra data receberia hoje, sem aviso. Os dois chamadores passam hoje, então nada mudou de comportamento — mas a armadilha estava armada, e o mesmo valia para `selecionarPacotes()`. ##### O que ficou provado, e onde `tests/Caracterizacao/PacoteDebitadoTest.php` (6) e `TelefoneCompartilhadoTest.php` (4). **Nos dois arquivos o resultado certo é o de id MAIOR ou exige a exclusão** — sem isso passariam por acaso, já que a resposta sem ordem tende a vir na ordem física. Postos à prova: comentando o `ORDER BY`, **4 dos 6** ficam vermelhos; anulando o `$exceto`, **2 dos 4**. E rodam nos dois bancos — 202 testes verdes contra o PostgreSQL. #### O contador, e por que não é portão em zero — 05/09/2026 `scripts/conferir-linha-sorteada.php`, no `conferir-tudo.sh` e no CI. | | | |---:|---| | **6** | selecionam linha, sem ordem — a linha de base | | 42 | com `ORDER BY` | | 37 | agregações, onde a ordem não muda nada | | 13 | dispensadas com motivo escrito | | **98** | o total, e ele fecha: é o número de chamadas de `setMaxResults` em `module/` | *Remedido em 14/09/2026, e os quatro números acima saem do portão, não desta prosa.* A linha do total está aqui de propósito: ela é a única que permite ver, sem rodar nada, se alguém mexeu numa das quatro sem mexer nas outras. **Ele falha nas duas direções.** Subir é o caso óbvio. Cair sem baixar a linha de base deixaria folga para uma busca nova entrar escondida atrás de uma corrigida — e a mensagem diz isso ao autor do conserto, em vez de só o parabenizar. **A distinção que faz o número valer** é a mesma que custou três medições erradas ao D72: agregação não conta. Quem responde é a cláusula `SELECT`, e não o método de leitura — este código usa `getOneOrNullResult()` para os dois casos. **A dispensa exige motivo com 40 caracteres**, como no auditor de `GROUP BY` (**D24**), e serve para "a segunda linha não pode existir" — não para "hoje não tem duplicata na cópia". O próprio D72 mediu **seis zeros que eram artefato da cópia anonimizada**, e essa armadilha não pode voltar pela porta da dispensa. A única dispensada até agora é `ClienteSessaoRepository::porTokenHash`, e ela é minha, do **D59**: o filtro é o `sha256` inteiro de um token de 256 bits: duas linhas iguais significariam o gerador quebrado, e não empate de dados. **Ali um `ORDER BY` seria pior que a falta dele** — daria regra de desempate a um impossível, e esconderia o impossível no dia em que ele acontecesse. ##### O erro que ele quase cometeu, e como apareceu O roteiro casa a fatia limpa (onde procura a consulta) com a bruta (onde mora a justificativa, num comentário). Casava **por índice** — e tirar comentários deixa linhas em branco que o corte também aceita: o mesmo arquivo saiu com **4 fatias no bruto e 9 no limpo**. O marcador do método certo era procurado no pedaço errado. Só apareceu porque a primeira dispensa que escrevi **não surtiu efeito**, e fui atrás do motivo em vez de mexer no texto do comentário. Casar por nome resolveu. É a terceira vez neste projeto que uma leitura por posição mente calada. #### A primeira triagem: 34 viraram 27 sem mudar uma linha de comportamento Sete das buscas **não podiam mesmo** devolver duas linhas. Elas não estavam corretas por sorte: estavam corretas por construção, e faltava dizer isso onde alguém fosse ler. | Busca | Por que não há segunda linha | |---|---| | `ClienteRepository::selecionarPorIdHash` | o filtro fixa a **chave primária**; o hash só decide entre uma linha e nenhuma | | `PesquisaRepository::selecionarPorIdHash` | idem | | `VipClassMaterialRepository::selecionarMaterialPorIdHash` | idem | | `ProdutoRepository::pesquisarQuantidade` | idem — o `status` pode zerar o resultado, nunca multiplicá-lo | | `VendaProdutoRepository::pesquisaNpsLocalizarClientePorId` | agrupa por `cli.id, uni.id` e o `WHERE` já fixa `cli.id` | | `PontuacaoHistoricoRepository::selecionarPorDescricao` | o único chamador faz `if (empty(...))` — **só existência** | | `VendaProdutoRepository::selecionarProdutoVenda` | os dois chamadores idem, e a linha nunca é lida | As duas últimas são de outra natureza: ali **pode** haver duas linhas — 149.109 combinações repetidas na primeira —, e mesmo assim a ordem não muda decisão nenhuma, porque ninguém olha o conteúdo. A dispensa registra o motivo certo, e não o conveniente. **A linha de base desceu junto.** Guardar a folga seria pior que não ter contador: uma busca nova entraria escondida atrás de uma explicada. **As 27 que sobram não são resto uniforme.** Há pelo menos quatro famílias com duplicata medida hoje na cópia — crédito do cliente por unidade (3), débito por venda (15), NPS por unidade e por colaborador (3 e 5), credencial de WhatsApp da unidade (1) —, e nelas o chamador **usa** o objeto. Essas precisam de regra escrita, não de dispensa. O login e o e-mail duplicados (**D31**) continuam sendo caso de restrição de unicidade (**D29**), e não de ordenação: ordenar escolheria um vencedor de empate que não deveria existir. #### O certificado da VipClass saía com a data de uma tentativa sorteada A terceira com consequência real, e ela imprime papel. `VipClassCheckpointUsuarioRepository::selecionarUsuario` escolhia **uma** das tentativas do aluno naquele curso. A linha não é só consultada: vira a **nota** na listagem de alunos e vira o **certificado em PDF**, com a data impressa nele. *Correção de registro (04/10/2026, o D343):* o certificado imprime só o nome, o curso e a carga horária, e não a data (`docs/f3-telas-restantes/tela-vipclass.md`). A tentativa sorteada pesa na nota e na data da listagem de alunos. *(Revisão, 04/10/2026:)* o comentário de `VipClassCheckpointUsuarioRepository::selecionarUsuario` repetia a frase errada ("com a data impressa nele"), e foi corrigido junto. | | | |---|---:| | pares (curso, aluno) repetidos | **167** | | maior número de tentativas da mesma pessoa | 6 | | destes, com **data** diferente | **167** | | destes, com **nota** diferente | 3 | **A regra escrita: vale a tentativa mais recente** — `ORDER BY vip.data DESC, vip.id DESC`. A coluna `data` é `NOT NULL` no banco e na anotação, então não há nulo para posicionar (**D46**); o `id` desempata duas tentativas gravadas no mesmo segundo, que é o caso do **D42/D87** aplicado a uma coluna sem fração de segundo. Se o negócio decidir que vale a **maior nota**, muda uma linha — e a decisão passa a estar num lugar onde se pode mudá-la. ##### Dois testes verdes que não provavam nada Escrevi os dois primeiros com a tentativa recente no id **menor**, anotando no cabeçalho que assim fugia da ordem física. **Era o contrário:** sem `ORDER BY` o banco devolve justamente a primeira linha gravada, então eles passavam **com a consulta quebrada de propósito**. Só o teste de desempate acusava. Refeitos, e agora cada um guarda uma coisa: | Teste | Fica vermelho quando | |---|---| | `testValeATentativaMaisRecente` | não há `ORDER BY` nenhum | | `testAOrdemEPelaDataENaoPeloId` | a ordem é `vip.id DESC` sozinho — a simplificação tentadora | Provado nas três configurações: sem ordem, **3 de 5** vermelhos; só por `id`, **1 de 5**; com a ordem certa, verde. **A lição é sobre como se escolhe o cenário de um teste de ordenação.** "Inverti os ids" não basta — é preciso saber o que a consulta devolve quando não ordena, e montar o cenário contra isso. #### O e-mail tinha o mesmo defeito do telefone, em três chamadores `ClienteRepository::selecionarClientesPorEmail` recebeu a mesma exclusão (`$exceto`), e os três chamadores que comparavam o id **depois** passaram a excluí-lo **dentro** da consulta: | Onde | O que fazia | |---|---| | `ClientesController::validarCliente` | comparava `$clienteEmail['id'] != $request['id']` | | `ClientesController` (validação de e-mail) | idem, com `$id` | | `FidelidadeController` (adesão) | idem, com `$request['id']` | O quarto, no cadastro pelo aplicativo, só pergunta se existe alguém — para ele a ordem é indiferente, e nada mudou. ##### O sétimo zero que não é evidência A cópia local tem **zero** e-mails repetidos, e esse zero não vale nada: a anonimização reescreve `clientes.email` como `cliente@exemplo.invalid`, **único por construção**. Medir duplicata de e-mail ali responde sobre o roteiro de anonimização, não sobre a produção. Este débito já catalogava seis zeros desse tipo — `dashboard_colaboradores` e `usuarios` —, e este é o sétimo. **A conta de zeros falsos é maior que a de zeros verdadeiros neste débito**, e é a melhor razão para o conserto não depender de medição na cópia: `EmailCompartilhadoTest` monta os dois cadastros que a produção tem e a cópia não pode mostrar. #### O saldo do cliente: R$ 408,00 numa linha, R$ 0,00 na outra `clientes_creditos` guarda o saldo do cliente numa unidade — `pontuacao` é a fidelidade, **`valor` é crédito em dinheiro que ele gasta**. Deveria haver uma linha por (cliente, unidade), e não há nada no banco que o exija (**D29**). São **três pares repetidos**, e num deles as duas linhas discordam: | id | cliente | unidade | valor | pontuação | |---:|---:|---:|---:|---:| | 158334 | 169360 | 1 | **408,00** | 1944 | | 251303 | 169360 | 1 | **0,00** | 1944 | Sem `ORDER BY`, o saldo que a tela mostra era o de uma das duas. ##### Por que só o `valor` diverge, e a pontuação não A explicação estava nos dois escritores, e ela é exata: | Rotina | O que faz | |---|---| | `ClienteService::atualizarPontuacao` | percorre **todas** as linhas do cliente e grava a pontuação em cada uma — **espelha** | | `sincronizarValorCreditoClienteComExtrato` | lê **uma** linha, a sorteada, e só nela grava o valor do extrato | Por isso os três pares têm pontuação igual dos dois lados, e só o `valor` diverge. **A ordem que faltava é a mesma que decide onde se grava** — com ela, ler e gravar passam a ser sempre a mesma linha. **A regra escrita: vale a mais antiga do par**, que é a que o "lê-e-cria-se-não-existe" teria achado antes de a segunda aparecer, e onde o dinheiro está hoje. **Isto não conserta o dado** — juntar os três pares é decisão de quem manda, e mexe em produção congelada. ##### O teste que fica verde no MySQL e vermelho no PostgreSQL Com o `ORDER BY` comentado de propósito: | | | |---|---| | MySQL | **3 de 3 verdes** — o InnoDB guarda a tabela na ordem da chave primária, e a varredura devolve o menor id de qualquer jeito | | PostgreSQL | **1 vermelho** — a tabela é um monte, a varredura devolve a ordem de gravação, e o teste recebe a linha de R$ 0,00 | As duas linhas entram com a **mais nova primeiro**, para que a ordem física discorde da ordem de id. No MySQL isso não muda nada; no PostgreSQL muda tudo. **É a tese deste débito acontecendo diante do teste** — e a melhor defesa do job `caracterizacao-postgres` (**D92**): sem ele, três jobs verdes esconderiam exatamente este defeito. #### O débito da venda: duplo clique, não duas dívidas `ClienteDebitoRepository::selecionarDebitoPorVenda` alimenta `VendaService::cancelar()`, que **estorna o débito** — o objeto é usado, não é teste de existência. **15 vendas têm mais de um débito ativo**, até três, e a assinatura é sempre a mesma: | id | venda | cliente | valor | criado em | |---:|---:|---:|---:|---| | 7669 | 1038323 | 148079 | 5,00 | 30/12/2021 08:50:48 | | 7670 | 1038323 | 148079 | 5,00 | 30/12/2021 08:50:**56** | | 7671 | 1038323 | 148079 | 5,00 | 30/12/2021 08:51:**09** | Mesmo cliente, mesmo valor, segundos de diferença: **é duplo clique no botão, não três dívidas**. Como as linhas são idênticas no valor, a escolha não muda *quanto* se estorna — muda **qual** linha fica marcada, e sem ordem isso variava entre duas execuções. A regra: a mais antiga, que é a original. **As gêmeas continuam ativas depois do cancelamento**, e isso é defeito de dado, não de ordem — limpá-las é decisão de quem manda, em produção congelada. É a mesma corrida que o **D44** descreve, sem trava e sem unicidade. Provado do mesmo jeito que o saldo: com o `ORDER BY` comentado, verde no MySQL e **vermelho no PostgreSQL**. #### Os textos que a unidade manda: o PostgreSQL escolheria o que ninguém revisou `unidades_mensagerias` guarda as **mensagens enviadas ao cliente** — aniversário, pesquisa de satisfação, "sentimos sua falta", o aviso de que o cliente chegou. **Sete** lugares do sistema leem daqui, e o objeto devolvido vira mensagem enviada. A unidade 1 tem **duas linhas ativas**, criadas no mesmo segundo — outro duplo clique — e elas **não são iguais**: `pesquisa_satisfacao_app`, `sentimos_sua_falta_app` e `cliente_chegou_whatsapp` diferem entre as duas. **A regra aqui é outra: vale a linha editada por último.** No saldo e no débito a regra é a linha *original*, porque o dinheiro está nela; aqui o conteúdo é mantido à mão, e a linha que alguém cuidou por último é a que representa a intenção de quem escreve as mensagens. **Regra por família, e não uma regra para todas** — é o que torna a triagem trabalho de leitura, não de substituição. ##### O caso que prova o D46, com o texto na mão `dataAlteracao` aceita nulo, e nulo significa "nunca editada" — tem de **perder** de uma linha editada. Medido com as três formas: | Ordenação | MySQL | PostgreSQL | |---|---|---| | nenhuma | 2 vermelhos | — | | `dataAlteracao DESC` cru | **verde** | **vermelho** | | `Ordenacao::nulosPorUltimo()` | verde | verde | Na linha do meio o teste mostra o que a unidade mandaria ao cliente: **"texto que ninguem revisou"** em vez de "texto revisado". O `DESC` cru põe o nulo no topo no PostgreSQL, e a unidade passa a enviar o rascunho que ninguém aprovou. **É o D46 acontecendo diante de um teste**, e não em uma tabela de contagens. #### O cupom aplicado e o cupom queimado podiam ser dois `selecionarCupomProdutoCliente` é chamada **duas vezes, por códigos diferentes**: | Quando | Quem | O que faz com a linha | |---|---|---| | ao lançar o produto | `CuponsController` | lê o desconto e o grava no motivo | | no fechamento | `VendaPagamentoService` | marca **usado** e desativa | Sem ordem, nada garantia que as duas achassem o mesmo cupom: **aplica-se o desconto de um e queima-se o outro**. O cliente fica sem um cupom que não foi usado e com um que já foi. **Esta é diferente das anteriores.** Nas outras o dano era ler o valor errado; aqui são duas leituras que precisam **concordar entre si**, e é por isso que o teste mais importante do arquivo compara duas chamadas em vez de olhar uma. **Zero casos vivos na cópia** — e um cliente pode legitimamente ter dois cupons do mesmo produto, de campanhas diferentes. O cenário é montado, como no e-mail. A regra é a do pacote: **vence antes, sai antes**, com o nulo por último. Sem o `ORDER BY`, 2 dos 3 testes ficam vermelhos já no MySQL. #### O NPS somava de uma linha e gravava em outra A consolidação do NPS lê **três vezes** o mesmo conjunto, com três consultas diferentes — os totalizadores da unidade, o resultado da unidade e o do colaborador —, calcula a média com os totalizadores que leu e grava no resultado que leu. **Linhas diferentes nas duas leituras somam de uma e gravam na outra.** | Repetidas | | |---:|---| | 3 | combinações (unidade, mês, ano) | | 5 | combinações (colaborador, mês, ano) | Todas com `data_criacao` igual ao segundo: é a corrida do **D44**, sem trava. O que este débito trata é a consequência dela na leitura — as três consultas ganharam a mesma ordem, e a mais antiga é a canônica, como no saldo. **Três de uma vez** — foi a maior queda do contador num só conserto. ##### O que o teste realmente guarda, e o que não guarda O teste que compara as duas leituras **passa mesmo sem o `ORDER BY`**, nos dois bancos: as duas consultas varrem a tabela do mesmo jeito e sorteiam a mesma linha. Quem fica vermelho sem a correção é o outro teste, no PostgreSQL. Registro isso em vez de deixar parecer que ele prova mais do que prova. Ele guarda o dia em que os dois planos deixarem de coincidir — **um índice novo em uma delas basta** —, e esse dia é mais próximo do que parece, porque as duas já não fazem a mesma pergunta. Ver o **D93**. #### O bilhete que vira ganhador, e mais duas dispensas `SorteioService` sorteia uma venda e chama `selecionarVenda()` para pegar o bilhete dela — **e usa o objeto**: marca aquele bilhete como ganhador e o grava no sorteio. **Quatro vendas têm dois bilhetes.** Nas quatro os dois são do mesmo sorteio, então o vencedor está certo; o que variava era a linha marcada. Regra: o primeiro bilhete da venda. **Duas dispensas honestas no mesmo passo:** | Busca | Por que | |---|---| | `UsuarioRepository::selecionarPorTokenWeb` e `::selecionarPorTokenTocarSenha` | o filtro é um token de **100 caracteres** sorteados por `random_int` (`RandomString`); duas linhas iguais não acontecem | | `SorteioVendaRepository::validarGanhador` | a única coluna projetada é `sorven.ganhador`, e o `WHERE` fixa `ganhador = true` — **qualquer** linha devolve o mesmo valor | A dos tokens é sobre **colisão**, não sobre força do segredo: os valores gravados antes de 01/09/2026 saíram do `mt_rand`, e essa parte é do **D77**. ##### O que fica, e por quê | Restante | Situação | |---:|---| | 5 | `usuarios` por login/e-mail/autenticação — é o **D31**, e a correção é a unicidade, não a ordem | | 4 | dashboards — é o **D40**, e as duplicatas saem no `pre-migracao-limpeza.sql` | | 2 | royalties — é o **D71**, e volta com o desenho do corte | | 1 | `push_app` — **parado por decisão sua**: "por hora, ignorar tudo do onesignal" | | 2 | `pesquisas` por fidelidade, `usuarios_comissoes_extras`, `caixas` por usuário — zero duplicatas hoje, e o conserto é a restrição do **D29** | **Nenhuma das 6 restantes tem consequência medida.** As oito que tinham foram consertadas, cada uma com a regra escrita no método que a executa e presa por teste. O que sobra depende de decisões que não são minhas: unicidade em produção, a limpeza pré-migração, e o corte. ##### `autenticacao` não recebeu ordem, e é decisão, não esquecimento Seria uma linha. **Mas qual ordem?** O **D31** descreve o risco: reativar um colaborador antigo cujo login coincida com o de alguém ativo. Com `id ASC` ganha o colaborador **antigo** — o pior resultado possível. Com `id DESC` ganha o mais recente, o que parece certo e é um palpite meu sobre autenticação. Escolher errado aqui é pior que não escolher: a ordem daria aparência de decisão a um caso que precisa de **restrição de unicidade**, e esconderia o dia em que dois logins ativos coexistirem. Fica na lista, de propósito. #### Três números para a mesma grandeza, e o portão lia por método — 14/09/2026 **Este débito não fecha hoje**, e o motivo continua o mesmo: nas 6 que restam o conserto certo é a restrição de unicidade do **D29**, que é schema em produção congelada. Pôr `ORDER BY` ali seria o conserto **errado** — faria o código tolerar em silêncio um estado que não deveria existir, e em `usuarios.login` isso significa duas contas com a mesma credencial e o sistema escolhendo em qual delas se entra. O que mudou é que o número publicado e o vigia ficaram honestos. **Três lugares publicavam três números.** O título desta seção dizia **14**, o comentário do passo de CI dizia **27**, e o código media **6**. É a doença do **D186** outra vez, agora numa grandeza que tem portão: prosa e comentário não são medidores, e envelhecem sem avisar. Pior: a queda está registrada **pela metade**. O único degrau escrito é o do **D110** — *"a linha de base do D72 caiu de 13 para 9"*. Os saltos 14 → 13 e 9 → 6 não estão em lugar nenhum; só o portão sabe. Por isso a tabela do contador ganhou a **linha do total**: 6 + 42 + 37 + 13 = **98**, que é exatamente o número de chamadas de `setMaxResults` em `module/` fora de comentário — medido em 14/09/2026, 107 no texto bruto e 98 fora dos comentários. Com o total à vista, mexer numa das quatro sem mexer nas outras deixa de passar despercebido. #### E o portão creditava como ordenada uma busca que não é Ele lia **por método**: pegava o primeiro `SELECT ... FROM` da fatia e procurava `ORDER BY` na fatia **inteira**. Método que monta três consultas e limita só a primeira ficava creditado como ordenado por causa da ordem **das outras duas**. Instância viva: `module/ISConfiguracao/src/Entity/UnidadeRepository.php`, método `getUnidadeColaboradoresServicos`. O `setMaxResults(1)` pertence a uma DQL `WHERE uni.id = :unidadeId` **sem ordem nenhuma**; o mesmo método traz `ORDER BY usu.ordernacaoApp` e `ORDER BY p.nome`, de outras duas consultas. Ela ia para o balde dos 43 "com `ORDER BY`". Ela **não é defeito vivo** — `uni.id` é `@ORM\Id`, então é uma linha ou nenhuma — e é justamente essa a pior forma de descobrir um buraco: **sem sintoma**, e dentro do balde dos consertados. O portão passou a ler **por chamada**: para cada `setMaxResults`, o dono é o **último** `SELECT ... FROM` antes dele, e o `ORDER BY` só conta se estiver **entre os dois**. Medido, e o delta é de exatamente um: | | antes (por método) | depois (por chamada) | |---|---:|---:| | sem ordem | 6 | **7** | | com `ORDER BY` | 43 | **42** | | agregações | 37 | 37 | | dispensadas | 12 | 12 | | total | 98 | 98 | Nenhum falso positivo novo. A que apareceu recebeu a **mesma dispensa** que a família `selecionarPorIdHash` já tinha — filtro na chave primária —, e a linha de base continua **6**. **Falsificado com o portão antigo contra a árvore de hoje:** ele devolve 6 / 43 e sai **verde**, cego para a busca; o portão novo, sem a dispensa, devolve 7 / 42 e sai **vermelho**. Com a dispensa escrita, 6 / 42 e verde. #### CORRIGIDO em 08/11/2026 -- as três que restavam têm escritor único e travado, e o portão está em zero **A fatia 125 da fila** (CONSULTAS-MORTAS-E-PORTOES-DE-DQL). O `conferir-linha-sorteada.php` contava 3 (desde o D349, 04/10/2026): `PesquisaRepository::selecionarPorFidelidade`, `UsuarioComissaoExtraRepository::selecionarPorUsuarioProduto` e `CaixaRepository::selecionarPorUsuario`. O conserto que este registro esperava era a unicidade do D29, esquema em produção. **Não foi preciso:** fatias posteriores deram a cada uma um escritor único, que trava antes de ler e grava na mesma transação, e "a segunda linha não pode existir" passou a ser verdade pelo código, e não pela cópia: | Busca | O escritor | O que fica vermelho sem a trava (nos dois bancos) | |---|---|---| | o caixa aberto do operador | `CaixaService::abrirSemDuplicar`, a única porta que abre caixa (a tela antiga e a `/adm/api/caixas`), trava a linha do usuário e só então pergunta se já há um aberto | `CaixaSobTravaTest::testAAberturaTravaOOperadorAntesDeConferir` e `::testAAberturaEsperaATravaDoOperador` (o mutante T1, sem o `FOR UPDATE`) | | a pesquisa da adesão | `PesquisaService::marcarParaAdesao`, o único que põe a marca: trava todas em ordem de id, lê as marcadas com trava e desmarca as outras; a pesquisa nova nasce desmarcada | `PesquisasPelosControllersTest::testATrocaTravaAPesquisaEAsMarcadasAntesDeLer` (T2, sem o `travarTodas`; no PostgreSQL, também `testDuasTrocasAoMesmoTempoDeixamUmaSoNaAdesao`); `testATrocaPoeAOutraETiraSoAMarcada` e mais três (T3, sem o desmarcar) | | a extra do par (pessoa, produto) | a janela antiga (`UsuarioService::comissaoExtraSalvar`) e o `PUT` da tela nova (`gravarCotaParte`) travam a pessoa e conferem o par de novo com ela travada (`outraExtraNoPar`; `RegraDaCotaParte::conferirExtras`) | `UsuarioCotaPartePelaApiTest::testATravaDaPessoaEDeVerdadeNasPortas` (T4, sem o `FOR UPDATE` da pessoa), `::testOParDaJanelaEConferidoDeNovoComAPessoaTravada` e `::testOParCriadoNoMeioVoltaAJanelaComAFraseESemAGemea` (T5, sem o par da janela), `::testARecusaDaRegraNaoGravaNada` (T6, sem o par do `PUT`) | Cada busca ganhou o `@linha-sorteada-conferida` com esse motivo e com os casos que ficam vermelhos -- a regra "motivo na dispensa não é guarda": cada trava citada foi arrancada, uma por vez, e o caso ficou vermelho. O "gravar" do `PUT` (`gravarAsExtras`) foi conferido antes: ele só recebe as mudanças que a `conferirExtras` aprovou contra as linhas lidas com a pessoa travada. O comentário de `outraExtraNoPar`, que ainda dizia "dois cadastros simultâneos do mesmo par passam os dois", foi corrigido. **O que a dispensa não cobre, e fica dito nela:** um par herdado de antes das travas. Na pesquisa, a próxima troca o desfaz (ela desmarca todas as outras). Contado de novo na cópia em 08/11/2026, só `SELECT`, nos dois bancos: 1 pesquisa marcada, 0 operadores com dois caixas abertos (entre 139 abertos) e 0 pares repetidos de extra. A restrição do D29 continua sendo a garantia mais forte, e é do corte. **O portão:** `LINHA_DE_BASE` de 3 para **0** -- daqui em diante é portão em zero (0 sem ordem, 46 com `ORDER BY`, 27 agregações -- eram 31; quatro saíram com as consultas mortas do D485 --, 20 dispensadas). Falsificado: arrancada a dispensa do caixa, o portão sai com 1 ("SUBIU de 0 para 1"); devolvida, 0, com o arquivo igual pelo sha1. ### D73 — Injeção de DQL no relatório de clientes, alcançável pela barra de endereços — FEITO em 01/09/2026 — PARCIAL em 07/10/2026: saíram 4 dos 12 sítios sem chamador; ficam os outros 8, os de valor interno e a prova por HTTP — PARCIAL em 04/11/2026: os 8 sítios dos quatro selecionarAniversariantes* sem chamador saíram (a DE2); ficam os de valor interno e a prova por HTTP — CORRIGIDO em 08/11/2026: os valores internos viraram parâmetro, e a prova por HTTP perdeu o objeto com o relatório Descoberto em 31/08/2026, ao medir as 8 buscas que o **D72** não alcançou automaticamente. A primeira delas trouxe outra coisa: ```php // LogradouroRepository:15 . " WHERE l.cep = '" . $cep . "'"; ``` O valor entra na consulta por **concatenação de texto**, não como parâmetro. #### A extensão **59 linhas** do `module/` concatenam variável dentro de uma consulta. A família confirmada como alcançável por dado de usuário é `ClienteRepository::filtrosListagemIndexRelatorio`, com **14 interpolações de `$request[...]` direto na DQL**: ```php $dql .= " AND uni.id = " . $request['unidade']; $dql .= " AND cli.origem = '" . $request['origem'] . "'"; ``` E o `$request` vem cru da barra de endereços, sem validação nenhuma: ```php $request['unidade'] = $this->params()->fromQuery('unidade', null); ``` O caminho é `ISRelatorio\Controller\ClientesController`, protegido por `getAcesso('ler')` — ou seja, **qualquer usuário autenticado com permissão de ler o relatório de clientes**. #### A prova, feita localmente e sem tocar em HTTP DQL não é SQL, e a defesa natural seria supor que o Doctrine reanalisa a string e neutraliza o que vier. **Ele não neutraliza.** Montei as duas formas com um valor hostil e pedi o SQL gerado: | Forma no código | Valor injetado | SQL gerado | |---|---|---| | `= " . $valor` | `1 OR 1=1` | `... AND u1_.id = 1 OR 1 = 1` | | `= '" . $valor . "'` | `x' OR '1'='1` | `... AND c0_.origem = 'x' OR '1' = '1'` | **As aspas não protegem.** Nos dois casos o `OR` sobrevive à análise do Doctrine e chega ao SQL, e um `OR 1 = 1` torna o `WHERE` inteiro verdadeiro. No caso do `uni.id`, o `WHERE` que sobra devolve **os clientes de todas as unidades**, não só a do usuário. São 242.586 clientes com nome, CPF, telefone e e-mail. #### O que eu NÃO fiz, e por quê - **Não executei isto por HTTP contra a aplicação.** A prova no nível da DQL é suficiente e não deixa rastro em log de acesso nem dado alterado. - **Não testei contra a produção**, que segue congelada. - **Não executei isto por HTTP contra a aplicação** (repetido aqui porque continua valendo depois da conferência abaixo). **Uma tentativa que falhou, e não vira conclusão:** injetar no *nome da coluna* (`GROUP BY uni." . $coluna`, `UnidadeRepository:293`) foi recusado pelo analisador com erro de sintaxe. Foi **uma** tentativa com **um** payload; isso não prova que a forma seja segura. #### As 54 conferidas, uma a uma — 31/08/2026 **O total não era 59 nem 52.** O primeiro número veio de `grep` e contava linhas, não sítios. O segundo veio de um varredor meu que exigia `" AND "` **com espaço à frente** — e perdeu `"AND u.unidade = " . $unidade`, que começa com `AND`. Corrigido, são **54**, em 10 arquivos de repositório e 20 métodos. | Categoria | Sítios | |---|---:| | **Alcançáveis por dado de usuário** | eram **18**, hoje **17** | | Defendidas — duas delas por acaso | 6 | | Valor interno: cron, sessão, entidade, literal | 26 | | **Código morto — nenhum chamador** | 4 | Somam 54. **As 18 alcançáveis:** | Onde | Sítios | Origem | |---|---:|---| | `ClienteRepository::filtrosListagemIndexRelatorio` | 14 | `fromQuery`, sem validação | | `ClienteRepository::listagemIndexRelatorio` | 1 | o mesmo `$request` | | `DashboardFaturamentoRepository::relatorio` e `relatorioUnidades` | 2 | `implode(', ', $request['ano'])` dentro de um `IN (...)` | | ~~`LogradouroRepository::buscarEndereco`~~ | ~~1~~ | **CORRIGIDA em 31/08** — virou `setParameter` junto com a troca pelo ViaCEP (**D74**) | O relatório de faturamento é achado novo desta conferência, e a busca de CEP também — e **essa saiu em 31/08**, corrigida de passagem quando a consulta de CEP foi trocada pelo ViaCEP (**D74**): virou `setParameter`. **Restam 17.** As 14 já estavam descritas acima; eu havia contado 13 porque olhei linhas, e a linha do `BETWEEN` traz **duas** interpolações. **As 6 defendidas, e vale saber por quê:** | Onde | O que a defende | |---|---| | `filtrosListagemIndexRelatorio`, o `$tag` | `str_replace("'", "", ...)` tira as aspas antes; sem aspa não há como sair do literal. **É defesa por acaso** — a remoção existe para outra coisa. | | `listagemIndexClientesNovos` (5) | a unidade vem da sessão, e a data passa por `DataHora::stringDate`, que **normaliza**: testei `01/01/2026' OR '1'='1` e ela devolve `2026-01-01`. A faixa de 7 dias recusa depois. | **As 4 mortas são justamente a forma mais perigosa.** `UnidadeRepository::popularComboboxPorColuna` interpola o **nome da coluna** em `GROUP BY` e `ORDER BY` — que é o caso que `setParameter` não resolve. Ela não tem chamador nenhum, em `module/` ou em `public/`. Idem `UsuarioRepository::selecionarTempoAtendimento`. Sorte, não desenho. **Uma que parecia grave e não é:** `selecionarUsuariosRelatorio` interpola o próprio parâmetro `$unidade`. Os três chamadores passam `null`, `$unidade['id']` de um laço e `$sessao->getUnidade('id')` — nenhum vem de fora. #### Por que isto é diferente dos outros itens de segurança Sua instrução em vigor é *"não se preocupe com a exposição agora, os dados estão seguros no servidor... vamos ver essa questão quando for fazer a migração"*. Ela foi dada sobre **arquivos expostos e credenciais no repositório** — coisas que dependem de alguém achar um arquivo. Este é de outra natureza: é uma falha alcançável **de dentro da aplicação, por um usuário legítimo**, e o que ela expõe é a separação entre as 32 unidades. Registro aqui e levo a decisão a você em vez de arquivar junto com os demais. #### Situação: DECISÃO EM ABERTO, por escolha sua em 31/08/2026 Você optou por deixar a decisão em aberto e voltar a ela depois. **Não é falta de informação**: os 54 sítios estão conferidos um a um, e o que falta é escolha de momento. Está listada como a única pendência ativa da seção "um segundo grupo, que não depende de produção", no roadmap — a lista chegou a esvaziar em 31/08 e voltou a ter esta. **Enquanto estiver em aberto, o que vale saber:** nada foi corrigido, nada foi testado por HTTP, e a produção não foi tocada. #### Ao resolver `setParameter` no lugar da concatenação. **Feito em 01/09/2026** — ver a seção abaixo. O que eu escrevi aqui antes — "é mudança mecânica" — estava certo sobre cada linha e errado sobre o conjunto: o auxiliar devolvia só a string da DQL, então não havia onde ligar valor nenhum. A mudança mecânica precisou de uma mudança de assinatura antes. #### RESOLVIDO em 01/09/2026 -- as 17 alcancaveis viraram parametro A conta fecha exatamente nas 17 que faltavam: | Onde | Sitios | O que virou | |---|---:|---| | `ClienteRepository::filtrosListagemIndexRelatorio` | 14 | `:unidade`, `:origem`, `:tipo`, `:area`, ... | | `ClienteRepository::listagemIndexRelatorio` | 1 | a subconsulta da pontuacao, `:unidadePontuacao` | | `DashboardFaturamentoRepository` (2 metodos) | 2 | `IN (:anos)`, com o array ligado direto | **O obstaculo era estrutural, e nao de digitacao.** O auxiliar devolvia SO a string da DQL; quem criava a consulta eram os chamadores, que nao tinham como saber que valores ligar. Passou a receber `array &$params` por referencia, e os dois chamadores -- `listagemIndexRelatorio` e `marketingPesquisarClientes` -- fazem o `setParameters`. **Parametrizei tambem 8 sitios que ja estavam seguros** (as datas por `DataHora::stringDate`, os valores em dinheiro por `Monetario::removeMask`) e os 5 de `listagemIndexClientesNovos`. Nenhum deles era alcancavel; a razao e que depender da normalizacao e depender de efeito colateral -- basta mover a funcao para o buraco voltar sem aviso. #### Uma mudanca de comportamento, pequena e deliberada A busca por tags se defendia com `str_replace("'", "", ...)` no termo pesquisado. Isso mudava **o que o usuario procura** para proteger a consulta: quem digitasse um nome com apostrofo procurava outra coisa, sem ser avisado. O `str_replace` saiu junto com a concatenacao, e a busca voltou a ser pelo que foi digitado. #### A prova, e ela e comportamental `tests/Caracterizacao/RelatorioClientesInjecaoTest.php` -- 4 testes que rodam a consulta com o filtro honesto e depois com a carga, e comparam contagens. Guardei a correcao num `git stash` e rodei os testes contra o codigo antigo: | Carga | Codigo antigo | Hoje | |---|---:|---:| | `?origem=x' OR '1'='1` | **242.592** | 0 | | `?unidade=90001000 OR 1=1` | **242.592** | 2 | 242.592 e a tabela inteira de clientes. **O teste sabe ficar vermelho** -- e por isso o verde dele significa alguma coisa. Tudo passa pelo PAGINADOR, que e o caminho da tela: o `Paginator` do Doctrine CLONA a consulta para contar antes de buscar a pagina, e um parametro que nao sobrevivesse ao clone estouraria em `Invalid parameter number` so em producao. #### Dois erros meus nesta correcao, os dois pegos por medicao **Contei um sitio alcancavel que nao era.** Anotei o `uni.id` de `listagemIndexClientesNovos` como achado novo, fora das 18. Fui conferir o chamador: `$request["unidade"] = $this->unidadeId` -- vem da SESSAO, nao da query. O documento ja o classificava como defendido, e estava certo. As 18 continuam 18. **A primeira versao dos testes era verde e nao valia nada.** Usei `count()` no que volta do `AdapterQuery`, que e um `Laminas\Paginator\Paginator` -- e ali `count()` devolve o numero de PAGINAS, nao de itens. As duas assercoes de injecao passavam por sorte: o caso defendido tem zero linhas, e zero linhas dao zero paginas. Trocado por `getTotalItemCount()`. **E a mesma licao de sempre: o veredito nunca acusa, a contagem sempre acusa** -- e desta vez a contagem que eu tinha escolhido contava a coisa errada. **E a primeira versao levava minutos.** Ela chamava a consulta sem filtro e sem paginar, o que hidratava os 242.587 clientes com joins e `GROUP BY` para dentro do PHP. Com o paginador, 22 segundos. #### O que continua em aberto - **Nunca testei isto por HTTP** contra a aplicacao, nem antes nem depois. A prova e no nivel da DQL e da consulta, e nao cobre o caminho do controlador. - **Os 4 sitios mortos seguem la**, e sao a forma que `setParameter` NAO resolve: interpolam o NOME DA COLUNA em `GROUP BY` e `ORDER BY` (`UnidadeRepository::popularComboboxPorColuna`, `UsuarioRepository::selecionarTempoAtendimento`). Nao tem chamador nenhum hoje; se ganharem um, precisam de lista branca, nao de parametro. - **Os 26 de valor interno** ficaram como estavam. `fidelizacao` e `selecionarAniversariantes` foram reconferidos hoje: so o cron os chama, com `$colaborador->getId()`, `date("d")` e `date("m")`. #### 4 dos 12 sítios mortos saíram em 07/10/2026 (o item CODIGO-MORTO-E-DOCS) **Apagados** `UnidadeRepository::popularComboboxPorColuna` e `UsuarioRepository::selecionarTempoAtendimento`. Conferido antes de apagar, de novo: nenhum chamador em `module/`, `public/`, `scripts/`, `tests/` nem `frontend/`, nem nas views e no JS, nem pelo nome montado em texto (o único despacho dinâmico de repositório, `UsuariosController::validarCampoUnico`, monta `selecionarPor`). O `conferir-injecao-dql.php` desceu a linha de base de **32 para 28** -- 3 sítios do primeiro (o nome da coluna no `SELECT`, no `GROUP BY` e no `ORDER BY`) e 1 do segundo (`WHERE c.id = " . $id`) -- e o comentário que os citava diz o que houve. **Falsificado:** devolvido o `popularComboboxPorColuna`, o portão sai com 1 ("SUBIU de 28 para 31"); tirado, volta a 0, com o arquivo igual byte a byte. **Um erro deste registro, achado no caminho:** "nome de coluna interpolado" eram só os 3 de `popularComboboxPorColuna`; o `selecionarTempoAtendimento` interpolava valor, e o portão dizia "seis vezes em cada arquivo" para a forma do nome de coluna. O que fica nos dois arquivos (3 e 5 sítios) interpola **valor**: a data de corte que o cron passa com `date('Y-m-d')` e o dia e o mês de três `selecionarAniversariantes*` -- o de `UnidadeRepository` e os dois de `UsuarioRepository` (`selecionarAniversariantes` e `selecionarAniversariantesTempoTrabalho`). **Esses três também não têm chamador** (medido em 07/10/2026: o cron chama só o de `ClienteRepository`), e são 6 dos sítios de valor interno. Não estavam no levantamento do item, e ficaram: apagá-los é o mesmo gesto, com a mesma conferência, e cabe no próximo que passar por aqui. **São quatro, e não três (verificação de 07/10/2026).** O parágrafo acima esqueceu `UnidadeSocioRepository::selecionarAniversariantes`, que interpola o dia e o mês do mesmo jeito (`DAY(soc.dataNascimento) = '" . $dia . "'`) e também não tem chamador: o `git grep` de `selecionarAniversariantes` em `module/`, `public/`, `scripts/`, `tests/` e `frontend/` acha um chamador só, a `CronJobService` (`:398`), e é o de `ClienteRepository` (o `conferir-caminhos-postgres.php` usa o mesmo). O comentário da linha de base o contava em "os demais (11)", como valor de entidade. **Os quatro métodos mortos somam 8 dos 28 sítios** (2 cada), e **os sítios sem chamador eram 12: saíram 4, ficam 8.** Quem for apagá-los, apague os quatro. O comentário do `conferir-injecao-dql.php` foi corrigido junto. **Fica de pé:** a prova por HTTP do relatório de clientes; os 8 sítios dos quatro métodos sem chamador; e os sítios de valor interno com chamador. O portão conta hoje 28 concatenações, pelo critério dele, que não se compara com os 26 deste registro (o próprio portão avisa); 8 das 28 estão nos quatro métodos sem chamador. #### Os quatro métodos sem chamador saíram em 04/11/2026 (a fatia 76h, DATAS-DA-EQUIPE-DE2) **Apagados** `UnidadeRepository::selecionarAniversariantes`, `UnidadeSocioRepository::selecionarAniversariantes` e `UsuarioRepository::selecionarAniversariantes` e `::selecionarAniversariantesTempoTrabalho` -- os quatro do parágrafo de 07/10/2026, o dia e o mês concatenados. Conferido antes de apagar: o `git grep` de `selecionarAniversariantes` em `module/`, `public/`, `scripts/`, `tests/` e `frontend/` só acha o de `ClienteRepository` (o parabéns do cron, que FICA: o `AniversariantesSaiuTest` o cobra junto, para um conserto largo demais ficar vermelho). Saíram no mesmo commit as quatro `relatorioSelecionarAniversariantes*` da tela antiga, que já eram por parâmetro. O `conferir-injecao-dql.php` desceu a linha de base de **22 para 14** -- os 8 sítios, 2 por método morto, medidos arquivo a arquivo (`UsuarioRepository` de 5 para 1, `UnidadeRepository` de 3 para 1, `UnidadeSocioRepository` de 2 para 0); as `relatorioSelecionar*` contavam 0, porque o `" ORDER BY " . \ISBase\...` delas é um nome qualificado, e não variável nem chamada. **Falsificado:** devolvido o de `UnidadeSocioRepository`, o portão sai com 1 ("SUBIU de 14 para 16"); com a linha de base de volta a 22, sai com 1 ("DESCEU de 22 para 14"); devolvido, 0, com o arquivo igual pelo sha1. **Fica de pé:** a prova por HTTP do relatório de clientes e os sítios de valor interno: os 14 que o portão conta hoje, pelo critério dele (entre eles, a data de corte do cron em `UnidadeRepository` e `UsuarioRepository` e o parabéns e o índice no nome do parâmetro em `ClienteRepository`). Não reconferi o chamador de cada um nesta fatia: só os quatro que saíram. #### CORRIGIDO em 08/11/2026 -- os valores internos viraram parâmetro, e a prova por HTTP perdeu o objeto **A fatia 125 da fila** (CONSULTAS-MORTAS-E-PORTOES-DE-DQL). **Reconferido o chamador de cada um dos 13 sítios** que o `conferir-injecao-dql.php` contava (a leitura está no comentário da linha de base dele). Os que levavam **valor** -- todos interno, nenhum alcançado por pedido -- viraram `setParameter`: | Sítio | Quem chama | Sítios | |---|---|---:| | `ClienteRepository::selecionarAniversariantes`, o dia e o mês | a rotina do parabéns, com `$hoje->format('d')` e `('m')` | 2 | | `UnidadeRepository::selecionarUnidadesRelatorioFranquias`, a data de corte | a rotina dos atendimentos, com `date('Y-m-d')` | 1 | | `VendaPagamentoRepository::relatorioYungas`, o período e a unidade | a rotina da Yungas | 3 | | `UsuarioRepository::selecionarUsuariosRelatorio`, a data de corte | ninguém: era o `$dataDashCola`, que saiu (o D485) | 1 | **E um sítio que o portão não via:** `"AND u.unidade = " . $unidade`, no mesmo `selecionarUsuariosRelatorio` (o combo de colaboradores do NPS antigo e do formulário dos atendimentos, com a unidade da sessão). O literal começava pelo `AND` sem o espaço antes, e a lista de palavras do detector pedia ` AND `. **O detector ficou mais largo** (o literal que começa por `AND ` ou `OR ` conta; medido: só esse em `module/`), e o sítio virou parâmetro junto. Falsificado: com ele de volta, o portão novo conta 7 e sai com 1; o antigo, na mesma árvore, contava 6. **E um terceiro, que nenhum dos dois detectores via** (achado pela verificação da fatia 125): `ConvenioRepository::popularCombobox` punha a unidade da **sessão** no texto por **interpolação** -- `"... OR conuni.unidade = $unidadeId)"`, dentro das aspas, sem ponto --, e o próprio registro deste débito já o chamava de "sítio do D73" (o combo de convênios do cadastro de clientes, dos Descontos e do filtro de clientes; ver o parágrafo "E um caso precisou de sessão", acima). O contador lê `T_CONSTANT_ENCAPSED_STRING` seguido de ponto, e o pedaço interpolado é outro token. **Virou `:unidade`** (sem sessão, o `null` ligado não casa com nenhuma unidade e vem só o ramo sem unidade; antes a DQL ficava com `conuni.unidade = )` e o analisador recusava -- nenhuma tela chega ali sem login). **E o portão ganhou um terceiro contador**, em zero: a variável **interpolada logo depois de um operador** (`=`, `<>`, `<`, `>`, `IN (`, `LIKE`, `BETWEEN`), em literal de aspas duplas ou heredoc com palavra de consulta. Medido em `module/`, só leitura: 50 literais interpolados com palavra de consulta, e nenhum outro depois de operador -- os demais são o nome do parâmetro (`LIKE :$param`, `= :produto_$key`), o alias (`{$aliasInd}.dataConvite`) ou a coluna de lista fixa (`uni.{$coluna}`, `SELECT {$colunas}`). Falsificado: com o `= $unidadeId` de volta na linha, o portão sai com 1 ("SUBIU de 0 para 1"); devolvido pelo sha1, 0. O caso `D73ValorPorParametroTest::testAUnidadeDaSessaoNoComboDeConvenios` declara a unidade na sessão e pergunta ao banco; o mutante G6 (a forma de antes, interpolada e sem `setParameter`) fica vermelho nele, nos dois bancos, e o `ComboDeConveniosNoRelatorioTest` (o recorte em si) segue verde, como deve: o resultado é o mesmo. **Ficam 6, e nenhum leva valor:** os dois índices no nome do parâmetro (`:tag" . $i` e `:busca' . $i`, em `ClienteRepository`: o DQL não tem lista de `LIKE`, e uma condição por palavra pede um nome por palavra, com o número de `array_values`) e os quatro `" ORDER BY " . Ordenacao::nulosPorUltimo(...)` do D72 (dois literais escritos no próprio arquivo). A linha de base desceu de **13 para 6** e o `ClienteRepository` de 4 para 2, no mesmo passo; falsificado: devolvido o dia e o mês concatenados do parabéns, o portão sai com 1 ("SUBIU de 6 para 8"). **O caso:** o `D73ValorPorParametroTest` pergunta ao banco, e não ao texto -- o SQL que cada uma das quatro manda não traz o valor, e os parâmetros trazem -- e afirma que a unidade continua recortando o combo (nenhum caso afirmava: arrancado o filtro, o `PesquisasNpsNoRelatorioTest` seguia verde). Os mutantes, nos dois bancos: G1 a G4 (cada valor de volta ao texto) e G5 (o filtro da unidade trocado por `:unidade = :unidade`) vermelhos; devolvidos pelo sha1. O que cada consulta devolve continua afirmado onde estava (`D41ParabensNoDiaDePreenchimentoTest`, `FranquiasNoRelatorioTest`, `ReceitaParaYungasTest`, `PesquisasNpsNoRelatorioTest`). **A prova por HTTP do relatório de clientes perdeu o objeto:** o Clientes antigo saiu do ERP em 04/11/2026 (a fatia 76e, a CA4 de `spec-carteira.md`) -- o alias `rel-clientes` e as quatro ações saíram, e `/mod-relatorios/rel-clientes/index` é 404 (o `ClientesAntigoSaiuTest`); o `listagemIndexRelatorio` saiu junto. **O que fica do caminho de 01/09** é o `filtrosListagemIndexRelatorio`, que as Campanhas usam para contar a audiência (`marketingPesquisarClientes`), todo por parâmetro desde 01/09 e cobrado no nível da DQL pelo `RelatorioClientesInjecaoTest`. **Não provado:** por HTTP, pela porta das Campanhas -- o débito era sobre a barra de endereços do relatório, e essa porta não existe mais. ### D74 — O CEP passou a vir do ViaCEP, e o dicionario virou cache — FEITO em 31/08/2026 — PREPARADO, lido em 05/10/2026 > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito como fechado, e o corpo diz que ele está pronto no código, à espera só do passo em produção na janela da migração final. Falta: decidir se e quando rodar scripts/limpar-dicionario-cep.sql em produção (antes do dump ou depois do corte); lá o dicionário segue com 709.440 logradouros. > > **06/10/2026:** decidido pelo dono (lote de perguntas, pergunta 10): o `limpar-dicionario-cep.sql` roda no passo 3 do corte, antes do dump. A verificação achou que ele apagava também as UFs do campo obrigatório de estado do ERP antigo, e ele passou a repor as 27 (o D430). Falta: o passo na janela, e duas confirmações do dono -- repor as 27 UFs, e como o cache volta a encher -- ver o fim deste registro. > > **08/10/2026:** as duas confirmações vieram em 07/10/2026 (página do lote, perguntas 30 e 34: o cache sob demanda, e as 27 UFs repostas). Falta só o passo na janela -- ver o fim deste registro. Por decisao sua, depois de o **D72** medir que 2.083 CEPs tinham mais de um logradouro no dicionario local — um deles com **37**. #### O que havia O sistema carregava um dicionario proprio: **709.440 logradouros, 38.777 bairros, 10.053 cidades, 27 estados**, de origem e data desconhecidas. Ele alimentava uma unica tela: o preenchimento automatico de endereco a partir do CEP. Dois defeitos, e o segundo so apareceu porque o primeiro foi medido: 1. **Envelhecia sozinho.** Comparado com a fonte no mesmo CEP `01001000`, o dicionario dizia *"Praça da Sé - lado ímpar"* e o ViaCEP diz *"Praça da Sé"*. 2. **A consulta escolhia uma linha sem dizer qual** — `setMaxResults(1)` sem `ORDER BY`, com ate 37 candidatas (**D72**). E um terceiro, achado no caminho: o CEP era **concatenado** na DQL entre aspas, que e a injecao do **D73** — as aspas nao protegem. #### O que passou a existir | | | |---|---| | `ISBase\Util\ViaCep` | cliente HTTP da API, **com tempo limite** (5 s para conectar, 10 s no total) | | `ISBase\Service\EnderecoService` | cache local primeiro, ViaCEP depois, e grava o que trouxe | | `LogradouroRepository::buscarEndereco` | agora com `setParameter` e `ORDER BY` | | `scripts/limpar-dicionario-cep.sql` | esvazia as quatro tabelas, com o porque escrito | **O contrato da tela nao mudou.** O formulario espera `{sucesso, endereco: {cidade, bairro, logradouro, uf}}` e continua recebendo exatamente isso — conferido ponta a ponta por HTTP. **As tabelas continuam existindo, vazias, e enchem sozinhas.** Medido depois de esvaziar: | Chamada | Tempo | Cache depois | |---|---:|---| | 1a, CEP novo | 890 ms | 1 logradouro, 1 bairro, 1 cidade, 1 estado | | 2a, mesmo CEP | **3 ms** | inalterado | | 3a, outro CEP | 446 ms | 2 de cada | | CEP inexistente | 436 ms | inalterado — nao se cacheia ausencia | #### O erro de ordem que eu cometi, e como ele acabou bem **Esvaziei as tabelas antes de entender uma coluna delas.** O primeiro INSERT do cache foi recusado: `logradouros.tipo` e `int NOT NULL` sem valor padrao, e a entidade **nao a mapeava** — entao nao havia como preenche-la. Nesse ponto o dado que explicaria a coluna ja tinha sido apagado do MySQL. Ele sobreviveu por sorte, na copia migrada para PostgreSQL: **709.440 linhas, um unico valor distinto — `1`.** A coluna nunca carregou informacao. A ordem certa era medir a coluna antes de apagar a tabela. Que tenha dado certo nao torna a ordem correta. #### E isso derrubou um dos quatro comandos destrutivos Mapear `tipo` na entidade teve efeito colateral bom: o `orm:schema-tool` parou de propor `ALTER TABLE logradouros DROP tipo` — **um dos quatro comandos que o D17 rastreia, e justamente o que estava nomeado como exemplo no texto dele.** `scripts/conferir-schema-tool.sh` acusou a mudanca sozinho, dizendo *"sao menos que a linha de base"* e mandando ler antes de comemorar. Estava certo em exigir: um numero que cai pode ser conserto ou pode ser alguem mapeando o que era para sumir. **Aqui foi conserto**, e a linha de base baixou de 4 para 3 com o motivo escrito no proprio roteiro. #### O que este desenho aceita de proposito **O cache nunca invalida.** CEP muda com raridade, e o preco de um endereco velho no preenchimento e o usuario corrigir um campo. Se incomodar, o conserto e uma data de coleta em `logradouros` e um prazo. **Nada lanca para cima.** ViaCEP fora do ar devolve `sucesso: false`, que e o mesmo caso de "CEP nao encontrado" que a tela ja tratava desde sempre: digitar a mao. Falha ao gravar o cache tambem nao interrompe — o endereco ja foi achado. **Duas requisicoes simultaneas do mesmo CEP podem gravar duas linhas iguais.** E o ler-e-criar-se-nao-existe do **D40** e do **D71** — mas aqui as duas linhas seriam identicas, entao qual delas volta nao muda a resposta. La mudava; por isso la e defeito e aqui nao e. #### Procurei irmas dessa coluna, e nao ha `logradouros.tipo` barrou o INSERT por ser `NOT NULL`, sem padrao e **nao mapeada**. Qualquer outra coluna assim faria o mesmo, e em silencio ate alguem tentar gravar. Varri as 84 tabelas em 31/08/2026, cruzando o metadado do Doctrine com o `information_schema`: | | | |---|---:| | Tabelas com entidade | 82 | | Colunas **nao mapeadas** | **3** | | Dessas, as que **barram INSERT** | **0** | As tres sao `usuarios.senha_php83`, `usuarios_acessos.local` e `vendas.desconto_motivo` — e nenhuma barra: as duas primeiras aceitam nulo ou tem padrao `''`, e a terceira aceita nulo. **As mesmas tres que o `conferir-schema-tool.sh` quer apagar.** Duas ferramentas independentes chegando na mesma lista e o tipo de confirmacao que vale mais que qualquer uma delas sozinha. Ou seja: o `tipo` era caso unico, e agora esta resolvido. #### Uma sobra que fica anotada, sem mexer `LogradouroRepository::autoCompliteLogradouro` continua no arquivo e **nao tem chamador nenhum** — conferido em `module/` e `public/`. Com o dicionario virando cache, ela passaria a completar sobre um punhado de CEPs ja consultados, o que nao serve para autocompletar nada. Nao removi: e metodo sem rota e sem efeito, e tirar codigo que ninguem chama nao era o que voce pediu. Fica dito para quem for limpar depois. #### O que isto mexe no corte **Nada quebra, e foi conferido.** `scripts/migrar-dados.sh:101` esvazia cada tabela de destino antes de copiar, reiniciando a identidade em cascata. O PostgreSQL sera limpo e preenchido com o que o MySQL tiver -- sem duplicata e sem sobra do dicionario velho, que hoje ainda esta la com 709.440 linhas. **Um numero do roadmap ficou velho, e a ressalva entrou nele.** A carga medida -- "16,2 milhoes de linhas em 511 a 521 s" -- foi medida com o dicionario dentro. Sao **758.297 linhas a menos** na proxima execucao: 709.440 logradouros, 38.777 bairros, 10.053 cidades e 27 estados. O tempo deve cair junto; nao remedi, porque a carga leva mais de oito minutos e o numero so importa de verdade no ensaio do corte. #### Cobertura `tests/Caracterizacao/EnderecoPorCepTest.php`, **5 testes e 20 assercoes**, e **nenhum toca a rede**: o `ViaCep` entra pelo construtor e e trocado por um duble que conta chamadas. A contagem e o que prova o cache — duas consultas ao servico, uma ao ViaCEP. Posto a prova: desliguei o cache de proposito e `testOMesmoCepDeNovoNaoVaiAoViaCep` falhou com *"a segunda consulta tem de sair do cache"*. **Decidido pelo dono em 06/10/2026** (lote de perguntas, pergunta 10): a opção (b), "Sim, no passo 3, antes do dump", com a observação dele: *"Sim, no passo 3, antes do dump. Utilize a api do ViaCEP para popular as informações."* O passo 3 do corte passou a rodar `scripts/limpar-dicionario-cep.sql` depois da limpeza e antes do dump. **A revisão de 06/10/2026 achou que "alimentava uma única tela", acima, não vale para `estados`:** o ERP antigo monta dela a lista do campo obrigatório de estado, e o roteiro, que a apagava, passou a repor as 27 UFs logo depois do `DELETE` -- é o **D430**, que espera a confirmação do dono. `php scripts/ensaiar-sql-do-passo-3.php` roda o roteiro num banco descartável com as tabelas do `mysql.sql` de hoje e linhas inventadas, e exige 0 logradouros, bairros e cidades e as 27 UFs, duas vezes seguidas; com 709.440 + 38.450 + 10.082 + 27 linhas inventadas (`--tamanho-de-producao`), o roteiro inteiro levou 3,7 s no MySQL 8.4.11 sem limite de CPU e 5,2 s num 8.0.46 limitado a 4 CPUs, os dois com 128 MB de buffer pool e o log binário ligado -- não é a produção, cujo disco e buffer pool não se conhecem (o D189). **O modo de repovoar espera a confirmação do dono:** "popular pelo ViaCEP" pode ser o que o código já faz -- o cache se enche sozinho a cada CEP consultado, 890 ms na primeira vez e 3 ms depois (acima) -- ou carregar antes os CEPs dos cadastros, que seria um roteiro novo, e não foi escrito. A pergunta está no lote, no item DECISOES-NO-REGISTRO-E-NO-CORTE. O que resta deste débito: o passo na janela. **Decidido pelo dono em 07/10/2026** (pergunta 30 da página do lote): a opção (a), "Sob demanda, como o código já faz" -- "Nada a construir." O cache de endereços volta a encher a cada CEP consultado na tela, pelo ViaCEP, como medido acima (890 ms na primeira vez, 3 ms depois) e como `EnderecoPorCepTest` prova (5 casos, verdes nos dois bancos em 08/10/2026); a pré-carga dos CEPs dos cadastros não será escrita. E na pergunta 34, a opção (a), "Apagar e repor as 27 UFs no mesmo roteiro" -- "A lista da tela nova; o ensaio do passo 3 confere as 27." --, que é o que o roteiro faz desde 06/10/2026 (o D430). As duas confirmações que este débito esperava estão dadas, e o passo 3 do `docs/procedimento-de-corte.md` diz as duas desde 08/10/2026. Nada mudou no roteiro; o ensaio do passo 3 segue verde no 8.4.11 e no 8.0.46. O que resta deste débito: o passo na janela -- e é por isso que o título fica PREPARADO. ### D75 — O inventario nao via servico guardado em propriedade — CORRIGIDO em 31/08/2026 Descoberto ao trocar a busca de CEP pelo ViaCEP (**D74**): a acao passou a usar um servico, e a coluna `servicos` do inventario ficou **vazia**. #### A causa `scripts/inventariar-acoes.php` achava os servicos de uma acao procurando um nome **comecando com maiuscula**. Isso acha `new ClienteService(...)` e `ClienteService::class`, e **nao acha** `$this->authService->autenticar(...)` -- servico recebido no construtor e guardado em propriedade, que e nome de variavel e comeca minusculo. #### O NUMERO QUE EU DEI PRIMEIRO ESTAVA ERRADO POR UM FATOR DE 25 Registrei **4 acoes**. Sao **100**. O erro foi do meu proprio medidor: eu procurava `$this->([a-z]\w*[Ss]ervice)` -- propriedade cujo nome **termina** em "service". A propriedade mais comum deste codigo se chama exatamente `$this->service`, e ela nao casa com esse padrao: sobra "ervice" para o `[Ss]ervice` casar, e ele nao casa. Alem disso, os 4 so contavam acoes com a celula **inteiramente vazia**. As que ja citavam um servico pelo nome e escondiam outro nem entravam na conta. O quadro real, medido comparando o CSV antes e depois: | | | |---|---:| | Linhas cuja coluna `servicos` mudou | **100** | | Delas, a celula estava vazia antes | **91** | | Delas, ja tinha algo e faltava outro servico | 9 | | Inalteradas | 260 | **Tres das 100 continuam sendo o caso que mais incomoda:** `AutenticacaoController::entrar` agora diz `AutenticacaoService AuthenticationServiceInterface` -- antes dizia nada. #### A correcao O gerador resolve a classe em duas tentativas: o tipo na assinatura do construtor (`EnderecoService $enderecoService`), e, sem tipo, a **fabrica** do controller, que faz `$service = $container->get(AplicativoService::class)`. O casamento e por nome da variavel, que neste codigo e o mesmo dos dois lados. **Sem classe resolvida, a celula fica vazia** -- nao se inventa nome. A primeira versao punha `service (?)` como marcador, e o resultado foram cem linhas com ruido que tinha cara de dado. Foi desfeito antes de commitar. **E o padrao da fabrica falhou na primeira tentativa**, pelo mesmo motivo de sempre: `[\w\\]` dentro de aspas simples do PHP vira `[\w\]`, classe de caracteres nao terminada. O conserto foi tirar a barra do padrao, nao escrever mais barras. #### O espelho nos repositorios esta limpo `getRepository(` e sempre chamado direto no corpo da acao, nunca por propriedade -- **0 ocorrencias**. O buraco era so nos servicos. ### D76 — O login por cookie nao entrava no registro de acessos — CORRIGIDO em 01/09/2026 — PARCIAL, lido em 05/10/2026 — CORRIGIDO em 12/10/2026 — CORRIGIDO em 13/10/2026 (a resposta 162) > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito como fechado, e o corpo diz que ele está parcial: uma parte está consertada, e a outra não. Falta: decidir se usuarios_acessos.local é mapeada, com um valor por caminho (web, cookie), ou removida; e fazer o escolhido. Descoberto em 31/08/2026, ao varrer colunas nao mapeadas depois do **D74**. `usuarios_acessos.local` apareceu na varredura, e puxar o fio levou a outra coisa. #### O que foi medido | | | |---|---:| | Linhas em `usuarios_acessos` | 1.880.078 | | Com `local` preenchido | 1.804.389 | | **Valores distintos em `local`** | **1** — sempre `web` | | Ultima linha com `local` preenchido | **13/11/2025** | | Acesso mais recente na copia | 16/08/2026 | E o volume, por ano: | Ano | Acessos | |---|---:| | 2022 | 232.550 | | 2023 | 253.012 | | 2024 | 324.099 | | 2025 | 317.881 | | **2026** (ate 16/08) | **59.985** | **Nao e sazonalidade:** o primeiro semestre de 2026 tem 47.797 acessos contra 168.271 no de 2025 — **72% a menos**. E a virada do `local` acontece no mesmo momento: zero linhas vazias ate outubro/2025, parciais em novembro, **100% vazias de dezembro em diante**. #### CORRECAO DE 01/09/2026: eu chamei de explicacao o que era hipotese A secao abaixo dizia "o que explica", e nao explica. **O mecanismo e real e verificado; a causa da queda de 72% nao esta estabelecida.** Fui medir quantos usuarios tem `token_web` ativo, para dimensionar o caminho por cookie. Achei **um**. Se so um usuario pode entrar por cookie, o cookie nao explica queda nenhuma. **So que esse numero tambem nao vale:** `scripts/anonimizar.sql.modelo:82` faz `token_web = NULL`. A copia local nao tem os tokens, entao **o uso do login por cookie nao e mensuravel aqui** -- nem para confirmar, nem para descartar. E a quarta vez neste dia que a copia anonimizada esconde o que se quer medir -- depois do **D31** (login, e-mail, CPF), do **D40** (a limpeza pre-migracao remove as duplicatas do dashboard) e do **D72**. Fica dito aqui tambem. **O que continua de pe, medido:** a queda de 72%, a virada do `local` em novembro de 2025, e o fato de que `entrarCookies` autentica sem registrar. **O que virou hipotese de novo:** a ligacao entre eles. #### O mecanismo, que e fato Ha **dois caminhos de autenticacao**, e so um registra: | Caminho | Registra acesso? | |---|---| | `AutenticacaoController::entrar` → `criarToken()` → `logAcesso()` | **sim** | | `AutenticacaoController::entrarCookies()` — login por cookie `token_web` | **nao** | `entrarCookies` autentica de verdade — monta o adaptador, chama `authenticate()`, cria a sessao e a ACL — e **nao chama `logAcesso`**. Quem entra com o cookie valido nao aparece no registro. E o `local` esvaziou porque quem grava hoje e `logAcesso`, que cria a entidade `UsuarioAcesso` — e essa entidade **nao mapeia a coluna `local`**. O banco aplica o padrao `''`. **O QUE EU NAO SEI, e nao vou afirmar:** por que a virada foi em novembro de 2025, nem se o caminho por cookie tem participacao nisso. O historico do repositorio comeca na importacao inicial, entao nao ha o que comparar. Os dois sinais mudam juntos, o que sugere uma so alteracao no fluxo de login, mas isso e leitura, nao medida. #### Por que importa **Nada de valor foi perdido na coluna** -- `local` sempre disse `web`, para todo mundo, desde 2016. Perder uma constante nao perde informacao. **O que se perde e o registro de quem entrou.** `usuarios_acessos` e a unica trilha de acesso do sistema, e ela hoje ignora o caminho por cookie -- que, pelo tamanho da queda, virou o caminho da maioria. Para auditoria, "este usuario nao acessou" e indistinguivel de "este usuario acessou pelo cookie". #### CORRIGIDO em 01/09/2026 `entrarCookies` passou a chamar `logAcesso`, depois de montar a sessao e a ACL. Uma linha. **Guardado por `scripts/conferir-registro-de-acesso.php`**, que confere pelo tokenizador se a chamada continua dentro daquele metodo -- e sai com 1 quando ela some. A guarda e estrutural, e o roteiro diz isso de si mesmo: alcancar `entrarCookies` num teste exigiria montar cookie, sessao e ACL, e um teste que precisa de tudo isso para provar uma linha nao vale a fragilidade. `logAcesso` em si tem teste de comportamento, em `SenhaEAcessoTest`. #### O que continua aberto **E ai aparece a decisao:** se `local` for para valer alguma coisa, ela precisa ser mapeada na entidade **e** receber valores diferentes por caminho -- `web` para o formulario, algo como `cookie` para o outro. Se nao for, o mais honesto e tira-la, e o `schema-tool` ja quer faze-lo. **Nao mexi em nada.** E codigo de autenticacao, e a decisao entre instrumentar ou remover e sua. #### 12/10/2026 — O REGISTRO DIZ COMO A PESSOA ENTROU — pela resposta 104 do dono: *"aguarde terminar e continue de forma autonoma a resolver todos os debitos que tiver resposta"* **A resposta 104** (a opção "a"): *"O registro de acessos passa a dizer como a pessoa entrou: senha, cookie, ou assumida por um administrador (e qual). Na lista de acessos da pessoa, a troca aparece como 'assumida por Beltrano'."* A coluna `local` já existe nos dois bancos, e usá-la não muda o esquema. ##### O conserto - **A entidade mapeia a coluna** (`UsuarioAcesso::$local`, `varchar(255)`, padrão `''`, como no `mysql.sql` e no `schema.sql`), com três valores, as constantes `PELA_SENHA` (`senha`), `PELO_COOKIE` (`cookie`) e `ASSUMIDA_POR` (`assumida:` -- o id, e não o nome, que muda). `AutenticacaoService::logAcesso` passou a exigir o `local`: o formulário (`criarToken`) grava `senha`; o cookie (`entrarCookies`), `cookie`; e a personificação (`UsuariosController::autenticarComoAction`, na entrada), uma linha **da pessoa assumida** com `assumida:` -- até esta data ela não gravava nada (o D127). A volta não grava: quem volta já estava logado. As linhas de antes (`web` até 13/11/2025, `''` depois) ficam como estão. - **A lista de acessos da pessoa** (`UsuariosController::localizarAcessosAction`, o modal da lista de usuários) diz, ao lado da data, "pela senha", "pelo cookie" ou "assumida por Beltrano" (o nome escapado); as linhas de antes, só a data. **A da unidade** (`UnidadesController::localizarAcessosAction`) põe "(assumida por Beltrano)" ao lado do nome -- sem isso a troca apareceria ali como se a pessoa tivesse entrado. O nome de quem assumiu sai de uma consulta só, pelos ids que aparecem (`UsuarioAcessoRepository::comQuemAssumiu`). - O `schema-tool` deixou de propor apagar a coluna: a linha de base do `conferir-schema-tool.sh` desceu de 7 para 6. ##### Provado - `RegistroDeAcessosTest` (novo, 13 execuções, nos dois bancos), despachado em processo com os controllers de verdade: o formulário grava `senha`; o cookie grava `cookie`; assumir grava a linha da pessoa assumida com `assumida:`, e a volta e o administrador não ganham linha; as duas listas dizem como a pessoa entrou (as cinco formas, da mais nova à mais antiga). E o `testLogAcessoGravaUmaLinha` do `SenhaEAcessoTest` confere o `local` gravado. - Por HTTP, o caso 22 do `ensaiar-sessao-do-erp.php` (abaixo, no D127): a linha `assumida:` no banco de contrato, nos dois bancos. Falsificado por HTTP, no MySQL: sem a gravação da troca, o caso 22 fica vermelho (22 de 23). **A primeira versão do caso lia a última linha da pessoa assumida, e o mutante passou**: a linha de uma rodada anterior, sem o banco remontado, respondia por ele. Agora o caso lê só as linhas de id maior que o de antes do pedido, e o encerramento tira as que a troca gravou. - Mutantes, um de cada vez, no MySQL, restaurados e conferidos pelo sha256, cada um com o seu vermelho: o formulário sem o `local` (o caso do formulário), o cookie gravando `senha` (o do cookie), a personificação sem a linha (o da troca), a lista sem o nome de quem assumiu e a lista da unidade sem o rótulo (o das listas). **O que fica, e foi ao lote:** o "Tot. Acessos" e o "Últ. Acesso" de duas listas contam todas as linhas -- a de usuários (as duas telas, `UsuarioRepository::listagemIndex`), onde a troca soma um acesso da pessoa e vira o último acesso dela, e a de unidades (o ERP e a `/adm/api/unidades`, `UnidadeRepository::listagemIndex`, pelo `UnidadeJson`), onde a mesma troca soma um acesso à unidade da pessoa e vira o último acesso da unidade, sem ninguém dela ter entrado. Contar só as da própria pessoa, nas duas, é a pergunta `SESSAO-E-ROTAS (o D76, depois da resposta 104)`, com a recomendação de contar só as dela. Hoje nenhuma linha assumida existe na cópia: elas começam agora. *(A primeira versão deste parágrafo, e da pergunta, citava só a lista de usuários; a verificação do mesmo dia achou a de unidades.)* ##### A verificação do mesmo dia: os nomes escapados nas duas listas **O escape do nome de quem assumiu não tinha prova:** o caso das listas usava "Gerente Teste", sem marca nenhuma, e arrancar o `htmlspecialchars` de qualquer das duas listas deixava tudo verde. E, ao lado dele, **o nome da pessoa saía cru na lista de acessos da unidade** (`UnidadesController::localizarAcessosAction`), desde sempre: a lista é HTML montado no controller, que o `mod-configuracoes.js` põe na página pelo `.html()` -- a família do D203. Agora os dois nomes são escapados. `RegistroDeAcessosTest::testONomeDoCadastroSaiEscapadoNasDuasListas`, nos dois bancos: o nome de quem assumiu com ``, as duas aspas e `&`, e o da pessoa com `` e o apóstrofo, saem escapados nas duas listas, e nenhuma marca sobra. Vermelho antes do conserto, no MySQL (o nome da pessoa, cru, na lista da unidade). Três mutantes, cada um vermelho nesse caso, nos dois bancos: sem o escape de quem assumiu na lista da pessoa, na da unidade, e sem o do nome da pessoa na da unidade. **Por onde o nome chega com marca** é o D476: o "Meus dados" grava o POST cru, sem o `StripTags` do filtro. #### 13/10/2026 — O TOTAL E O ÚLTIMO ACESSO SÃO DA PRÓPRIA PESSOA — pela resposta 162 do dono: *"aguarde terminar e continue de forma autonoma a resolver todos os debitos que tiver resposta"* **A resposta 162** (a opção "a", a recomendada): *"O 'Tot. Acessos' e o 'Último acesso' contam só as entradas da própria pessoa (senha e cookie, e as linhas de antes), nas duas listas: a de usuários (a mesma consulta no ERP e na tela nova) e a de unidades (`UnidadeRepository::listagemIndex`, a tela antiga e a `/adm/api/unidades`). A troca aparece só nas listas de acessos, com o nome de quem assumiu."* ##### O conserto - **A lista de usuários** (`UsuarioRepository::listagemIndex`, a do ERP e a `GET /adm/api/usuarios`): o `LEFT JOIN` dos acessos só junta as linhas cujo `local` não começa com `assumida:` -- `SUBSTRING(ace.local, 1, 9) <> 'assumida:'`, o prefixo pelo `SUBSTRING` como em `UsuarioAcessoRepository::entrouPeloNavegadorDesde`, e pela mesma razão. Contam a senha, o cookie e as linhas de antes (`web` e `''`). Quem só foi assumido continua na lista, com 0 acessos e sem último. - **A lista de unidades** (`UnidadeRepository::listagemIndex`, a do ERP e a `GET /adm/api/unidades`): as duas subconsultas, a do `MAX` e a do `COUNT`, com a mesma condição. - As listas de acessos (a da pessoa e a da unidade) não mudam: a troca continua nelas, com o nome de quem assumiu. Nenhuma tela mudou -- as quatro mostram o que a consulta devolve. **Na cópia** (`franquiabv_dev`, só contagens, 13/10/2026): nenhuma linha assumida (quem as grava é o código de 12/10/2026, e a cópia é anterior), e os `local` são `web` (1.804.389) e `''` (75.777): as listas dão hoje o mesmo número de antes. ##### Provado `D76AcessosDaPropriaPessoaNasListasTest` (novo, 3 casos), verdes no MySQL e no PostgreSQL, em série, despachados em processo nas quatro portas -- o `index` das duas telas antigas e o das duas rotas da API --, com o registro de acessos vazio e seis linhas de "Colaborador Teste" (`web` e `''` há quatro dias, a senha há três, o cookie há dois, e duas assumidas por "Gerente Teste", há um dia e agora): as quatro dizem **4 acessos e o último há dois dias** (antes, 6 e hoje); e com só as duas assumidas, a pessoa e a unidade dizem 0 e nenhum último, e as duas linhas continuam nas listas. O `RegistroDeAcessosTest` (as listas de acessos com "assumida por Beltrano") segue verde nos dois bancos. | mutante (sozinho, restaurado e conferido pelo sha256; `medir-mutantes-r30.py`, no rascunho do item) | vermelho, no MySQL e no PostgreSQL | |---|---| | a lista de usuários junta todas as linhas (a condição com `OR ace.id IS NOT NULL`) | a lista de usuários; quem só foi assumido | | o último acesso da unidade conta a assumida | a lista de unidades; quem só foi assumido | | o total da unidade conta a assumida | a lista de unidades; quem só foi assumido | *(A primeira forma do mutante da lista de usuários arrancava a condição e deixava os dois parâmetros sobrando: o Doctrine recusa a consulta, e o vermelho era de erro, e não de contagem. Refeito com a condição que junta tudo.)* **Não provado:** as telas não foram abertas num navegador. ### D77 — O gerador trocado; os valores ja emitidos e que esperam decisao — PARCIAL, lido em 05/10/2026 — PARCIAL em 12/10/2026: o prazo do cookie (a resposta 103); o ALTER das três colunas e as rotações são da janela e da produção — PARCIAL em 06/11/2026: a entrada automática na tela nova decidida (317 a); o ALTER e as rotações seguem da janela > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito sem marca de estado, e o corpo diz que ele está parcial: uma parte está consertada, e a outra não. Falta: dar validade ao token_web; em produção, o ALTER TABLE das três colunas do hash anterior e as rotações dos hashes de unidade e de cliente. Descoberto em 01/09/2026, ao investigar o login por cookie do **D76**. #### O que foi lido `ISBase\Util\RandomString::gerar()` monta a cadeia com **`mt_rand()`**: ```php $rand = mt_rand(1, $len); $retorno .= $caracteres[$rand - 1]; ``` `mt_rand` e o Mersenne Twister. A propria documentacao do PHP diz que ele **nao serve para criptografia** e manda usar `random_int()` / `random_bytes()` quando o valor for segredo. Ele e deterministico: conhecido o estado interno, toda a sequencia futura sai. #### O que ele gera, e o que cada coisa abre | Credencial | Tamanho | O que ela permite | |---|---:|---| | `usuarios.token_web` | 100 | **entrar como o usuario**, via cookie, sem senha | | `usuarios.token_trocar_senha` | 100 | **redefinir a senha** de um usuario | | `unidades.hash` | 60 | ler o faturamento em `/api/unidade/vendas`, `V2` e `V3` | | `clientes.hash` | 8 | **abrir o cadastro do cliente**, sem login — ver a correção abaixo | | `pesquisas.hash` | 30 | abrir a pesquisa de um cliente | | `vipclass_materiais.hash` | 10 | abrir material de treinamento | As tres primeiras sao **portadoras**: quem tem o valor entra, sem mais nada. Quantas existem hoje, na copia: | | | |---|---:| | Unidades com hash | **60** | | Clientes com hash | **242.586** | *(Os valores locais foram substituidos por MD5 na anonimizacao -- as contagens valem, os valores nao.)* #### Dois agravantes, medidos **1. O `token_web` nao expira.** Nao ha coluna de validade, e `selecionarPorTokenWeb` so confere `tokenWeb = :token AND status = 1`. Um cookie vazado vale enquanto o usuario nao entrar de novo ou sair. **2. Nenhuma comparacao de segredo e de tempo constante.** Sao **quatro** comparacoes com `==` -- tres em `CronJobController` (o hash da unidade nas rotas de vendas) e uma em `VipClassEduController`. **`hash_equals` nao aparece uma unica vez no `module/`.** #### O que eu NAO provei **Nao demonstrei previsao de token.** Recuperar o estado do Mersenne Twister a partir de saidas reduzidas a uma faixa de 62 valores e mais dificil que a partir das saidas cruas de 32 bits, e eu nao tentei -- fazer isso exigiria muitos tokens do mesmo processo, e nao ha por que produzi-los para provar um ponto que ja esta no manual do PHP. O que esta estabelecido e mais simples e basta: **estas sao credenciais de seguranca geradas por um gerador que a documentacao da linguagem desaconselha para credenciais de seguranca.** Um detalhe do ambiente que amplia a duvida, e que tambem nao foi explorado: o php-fpm reaproveita workers entre requisicoes, entao o estado do `mt_rand` de um worker atravessa varios usuarios. #### CORRIGIDO EM PARTE, em 01/09/2026 **`random_int()` no lugar de `mt_rand()`, dentro do `RandomString`.** Duas linhas num arquivo, e as seis credenciais passaram a sair de gerador criptografico -- sem tocar nos dezesseis arquivos que o consomem. `random_int` lanca se nao houver fonte de aleatoriedade, e isso ficou de proposito: credencial fraca gerada em silencio e pior que requisicao que falha alto. **Guardado por `scripts/conferir-registro-de-acesso.php`**, que le pelo `token_get_all` -- o comentario do proprio arquivo menciona `mt_rand` para contar esta historia, e comentario nao pode acusar. Posto a prova: com o `mt_rand` devolvido, o portao sai com 1. #### O QUE CONTINUA ABERTO **Os valores ja emitidos.** Os 60 hashes de unidade e os 242.586 de cliente continuam sendo os antigos ate serem regerados -- e **regerar o da unidade quebra quem ja usa a URL de vendas**. Isso e decisao sua. *(Em 02/09/2026 a parte do cliente ganhou ferramenta e numeros. Ver as duas secoes abaixo.)* ~~**O `hash_equals` nas quatro comparacoes** foi FEITO em 01/09/2026 -- e a justificativa que eu tinha dado para nao faze-lo estava errada. Eu escrevi que "pedia teste que nao existe". Existe: a suite de contrato exercita as tres rotas de vendas com hash valido, **e tem um teste dedicado a recusa**, o `testUnidadeVendasRecusaHashErrado`, com o comentario *"o hash e a unica credencial da API inteira, e precisa continuar valendo"*. Bastava olhar. As quatro trocas: tres em `CronJobController` (as rotas `vendas`, `V2` e `V3`) e uma em `VipClassEduController`. **Nao sobrou nenhuma comparacao de segredo com `==` no `module/`**, e `hash_equals` passou de zero para quatro usos. Posto a prova: substitui a checagem por `true` e a suite de contrato acusou com **uma falha** -- exatamente o teste da credencial. Restaurada, 35 de 35.~~ **FEITO em 01/09/2026, e a frase riscada estava errada.** O teste existia: a suite de contrato exercita `/api/unidade/vendas`, `V2` e `V3` com hash valido, e tem um caso dedicado -- `testUnidadeVendasRecusaHashErrado` -- cujo proprio comentario diz *"o hash e a unica credencial da API inteira, e precisa continuar valendo"*. Eu afirmei que nao havia cobertura sem procurar. As quatro comparacoes viraram `hash_equals((string) $unidade->getHash(), (string) $hash)` -- tres em `CronJobController`, uma em `VipClassEduController`. > ~~**Nao sobrou nenhuma comparacao de segredo com `==` no `module/`.**~~ > > **ERRADO, e corrigido em 04/09/2026.** Sobravam **27**: as comparacoes do > token dos crons (`$token == $this->tokenPadrao`), 26 em `CronJobController` e > uma em `VisagismoController`. Aquele trabalho trocou quatro comparacoes -- > todas do hash da unidade -- e eu generalizei para "nenhuma" sem procurar as > outras. E a segunda vez que uma frase minha neste mesmo registro afirma mais > do que eu tinha medido. > > As 27 viraram `hash_equals` agora, e a contagem foi feita por busca, nao por > impressao: `git grep -cE '(==|===|!=) *\$this->tokenPadrao' -- module/` > devolve zero. Posto a prova: troquei a checagem por `true` e a suite de contrato acusou com **uma falha**, a do hash errado. Com a checagem no lugar, 35 de 35. **Nada disso foi feito.** Trocar o gerador nao invalida os tokens que ja existem: os 242.586 hashes de cliente e os 60 de unidade continuariam sendo os antigos ate serem regerados -- e regerar o hash da unidade **quebra quem ja usa a URL de vendas**. Essa parte e decisao, nao conserto. #### CORRIGIDO O QUE EU TINHA ESCRITO: o hash de cliente não "identifica" — ele ABRE A tabela acima dizia que `clientes.hash` serve para *"identificar um cliente em `selecionarPorIdHash`"*. **Subdimensionei.** Lido o caminho inteiro em 02/09/2026: `FidelidadeController::cadastroAction` aceita `?id=&hash=<8>` **sem autenticação** e, para quem ainda não está no programa de fidelidade, renderiza o formulário **preenchido** com nome, data de nascimento, telefone, e-mail, CEP, estado, cidade, bairro, logradouro, número e profissão. Não é identificação: é **exposição do cadastro**, e o hash é a única credencial. Três agravantes, todos medidos: 1. **A busca não confere `status`, de propósito.** O comentário no repositório diz por quê: *"nao validar status pois os amigos são setados com status false"*. O convidado precisa abrir o convite antes de existir de verdade — e a consequência é que cliente inativo também fica alcançável. 2. **O alfabeto é menor do que "8 caracteres" sugere.** `setHash()` chama `gerar(8, false, true, false)`: minúsculas e dígitos, **36 símbolos**. São 36^8 ≈ 2,8 × 10¹², e não 62^8. 3. **A superfície é quase toda a base.** Dos 242.589 clientes, **217.133 estão fora do programa de fidelidade** — ou seja, caem no ramo que renderiza o cadastro. *O que isso não é:* não é um furo explorável por força bruta. 36^8 para um `id` escolhido não se percorre por HTTP. O problema é o do D77 desde o começo — **previsibilidade**, não tamanho: os valores saíram de `mt_rand`. **Caracterizado em `tests/Caracterizacao/HashDoClienteTest.php`**, quatro casos, nos dois bancos. Um deles força uma colisão de hash de propósito e mostra que ela é inofensiva: a busca é pelo **par** `id + hash`, então hash repetido não abre o cadastro de outra pessoa. Outro guarda um acoplamento que ninguém vê — o controller exige `strlen($hash) == 8` **antes** de consultar, e quem produz o valor é `Cliente::setHash()`, noutro módulo. Mudar o tamanho ou o alfabeto lá para "reforçar" a credencial faria a tela recusar todo mundo, com um 404 mudo por sintoma. #### FERRAMENTA PRONTA para a metade do cliente, em 02/09/2026 `scripts/rotacionar-hashes-clientes.php`. **Sem `--aplicar` ele só mede**, e não imprime hash nenhum — nem antigo nem novo. **O que a rotação quebraria, e por que quase nada.** O link `fidelidade?id=..&hash=..` é montado **na hora** em quase todos os caminhos: o aplicativo o remonta a cada listagem (`AplicativoController:325`) e a tela o reemite ao renderizar o formulário. Para esses, rotacionar é invisível. O único caminho que **não** remonta é o convite: `FidelidadeService:75` manda o link por WhatsApp ao amigo indicado, e a mensagem fica no telefone da pessoa. E é aí que o número decide: | | | |---|---:| | Indicados pendentes (`origem` "Indica…", `status = 0`) | **910** | | Mais antigo | 04/06/2015 | | Dos últimos 90 dias | **71** | Ou seja: rotacionar tudo mataria 910 convites, dos quais **839 têm mais de três meses** e alguns têm onze anos. Por isso o padrão preserva a janela de 90 dias — **rotaciona 242.515 e poupa 71**. A janela é ajustável, e `--preservar-dias=0` rotaciona todos. **Não foi rodado em produção**, que segue congelada. É ferramenta pronta, como `scripts/medir-senhas-producao.sql` — com a diferença de que aquele só lê, e este escreve; daí o `--aplicar` obrigatório. **Também não foi rodado na cópia local, e por um motivo:** rotacionar 242 mil hashes só no MySQL deixaria o PostgreSQL divergente em 242 mil linhas, e `conferir-migracao.php` compara os dois no ensaio de corte. O caminho de escrita foi provado por teste, não sujando a cópia. #### A METADE DA UNIDADE — FEITA em 03/09/2026 > *"ataque o D77"* O que estava escrito aqui era: rotacionar `unidades.hash` quebra quem já usa `/api/unidade/vendas`, `V2` e `V3`, e **não se sabe quem é** — o inventário das consultas do Power BI é o **D9**, e depende da produção descongelada. Rotacionar sem ele seria apagar a luz para procurar a chave. Também estava escrito o caminho que tira a decisão do impasse, e que eu não fiz sem você pedir: **guardar o hash anterior e aceitá-lo por uma janela, registrando quem ainda o usa.** É o que foi feito. ##### As três colunas, e o que cada uma resolve | coluna | o que resolve | |---|---| | `hash_anterior` | rotacionar deixa de derrubar quem não trocou | | `hash_anterior_expira_em` | sem prazo não há rotação, só acúmulo | | `hash_anterior_usado_em` | **o inventário que faltava se escreve sozinho** | A terceira é a que muda o problema de lugar. Ela não diz *quem* consulta — para isso seria preciso guardar origem, e guardar origem de quem chama uma API é outra decisão —, mas diz **se** alguém ainda consulta. E era só isso que faltava para saber quando derrubar o antigo. **O D9 continua valendo pelo que ele é:** saber quais consultas existem e o que fazem. O que a janela desfez foi o *bloqueio* — não é mais preciso esperar por ele para rotacionar. *(Em 09/09/2026 o Power BI foi removido e o D9 encolheu para revogar a credencial que sobrou em produção. A conclusão sobre a rotação não muda: ela já não dependia do inventário.)* ##### O ciclo inteiro, medido contra a aplicação de pé | | | |---|---| | hash novo | **200** | | hash antigo, janela aberta | **200**, e `hash_anterior_usado_em` gravado | | hash antigo, janela vencida | **Acesso negado.** | | hash inventado | **Acesso negado.** | ##### UM DEFEITO ENCONTRADO NO CAMINHO, e ele era um oráculo As três ações usavam `getReference`, que **nunca devolve nulo**: monta um proxy mesmo para id inexistente, e a exceção só estoura quando alguém toca no objeto. O `!empty($unidade)` ao lado era decorativo. Medido antes de mexer: **id inexistente respondia HTTP 500**, e id existente com hash errado respondia `Acesso negado.` — ou seja, **o código de status contava se a unidade existia**, sobre ids sequenciais, para quem não apresentou credencial nenhuma. Agora as duas respostas são idênticas. ##### A ferramenta `scripts/rotacionar-hashes-unidades.php`. Sem `--aplicar` ela só mede, e **nunca imprime hash na tela**. Três coisas nela são deliberadas: **`--saida=` é obrigatório com `--aplicar`**, e é conferido *antes* de escrever no banco. Credencial impressa no terminal fica no histórico do shell e na rolagem de quem estiver olhando — e estes valores abrem o faturamento. Rotacionar e depois não conseguir gravar o valor novo deixaria a unidade com uma credencial que ninguém conhece, e a janela correndo. **Ela se recusa a sobrescrever um CSV existente.** Ele pode ser a saída de uma rotação anterior ainda não aplicada no Power BI. **`--unidade=` é o modo normal.** Rotacionar as 62 de uma vez obriga a reconfigurar 62 consultas no mesmo minuto; sem o parâmetro ela mexe em todas, e isso é deliberadamente mais difícil de digitar. ##### Onde está a prova **`tests/Caracterizacao/HashDaUnidadeTest.php`** — 12 casos nos dois bancos. Inclui dois que descrevem comportamento que ninguém deveria descobrir por acidente: `hash_equals('', '')` é **verdadeiro**, então vazio e nulo são recusados antes da comparação; e **rotacionar duas vezes não empilha** — a janela é uma, não uma fila, e quem rotaciona de novo antes de ela fechar derruba quem estava no hash de duas rotações atrás. **Uma entrada nova em `conferir-autorizacao-privilegiada.php`**, para a decisão dentro do controller que teste nenhum alcança. Ela exige o registro do uso: sem ele a janela vira só uma segunda credencial permanente. Removi a linha e o portão acusou. ##### DE PASSAGEM: o inventário atribuía o auxiliar à ação anterior A quarta ocorrência da mesma família de rótulo falso — as outras estão no **D70** e em `docs/f2-fatia-pdv.md`. `scripts/inventariar-acoes.php` fatiava o código de uma **ação até a ação seguinte**, por deslocamento. Um método **privado** no meio caía dentro do corpo da ação anterior, e tudo o que ele fizesse era atribuído a ela. Apareceu porque `unidadeAutorizada()` ficou logo depois de `unidadeVendasV3Action` — e o inventário passou a dizer que **só o V3 muta e escreve direto**. As três ações chamam o mesmo auxiliar e nenhuma escreve no próprio corpo. O rótulo era falso de um jeito pior que errado: era **inconsistente entre três ações idênticas**, o que sugere uma diferença que não existe. A fatia agora termina no **próximo método**, e não na próxima ação. O efeito é maior do que o caso que o revelou: **28 das 360 linhas mudaram**, quase todas em controllers com auxiliar privado entre ações — serviços e repositórios que a ação não usa deixaram de ser atribuídos a ela, e o total de `CRIAR` caiu de 158 para 157. Uma ação passou a ter veredito **`CONFERIR`**: `CaixasController::gerenciar` delega para dois métodos privados e não devolve nada por conta própria. O veredito anterior vinha do corpo do `abrir()`. *"Não sei, leia antes de decidir"* é mais útil que um palpite bem formatado. ##### O QUE PRECISA ACONTECER NO DEPLOY O `ALTER TABLE` das três colunas entra na lista que espera o descongelamento — agora são **quatro** mudanças aditivas esperando a mesma janela (D54, D86, D88 e esta). **Sem elas o código não roda**: `hashAnteriorConfere` lê colunas que não existiriam. A rotação em si é operação, não deploy: uma unidade por vez, trocando o hash na consulta do Power BI, e conferindo pelo relatório quem ainda não trocou antes de encerrar o antigo. #### 12/10/2026 — O COOKIE TEM O PRAZO DO NAVEGADOR — pela resposta 103 do dono: *"aguarde terminar e continue de forma autonoma a resolver todos os debitos que tiver resposta"* **A resposta 103** (a opção "a"): *"12 horas depois da última entrada, como o navegador -- o servidor confere a hora da última entrada da pessoa (o registro de acessos já guarda, também a do cookie desde 01/09) e o valor copiado para de entrar 12 horas depois da última entrada. Sem mudar o banco."* ##### O conserto `AutenticacaoController::entrarCookies` só aceita o `token_web` quando `AutenticacaoService::cookieAindaVale` diz que a pessoa entrou **pela senha ou pelo cookie** nas últimas 12 horas (`UsuarioAcessoRepository::entrouPeloNavegadorDesde`, pelo índice `(usuario, data)` dos dois bancos). As 12 horas moram num lugar só, `SessaoAcl::PRAZO_DO_COOKIE` (43.200 s), que o `setCookie` também usa -- é o prazo que o navegador já aplicava. **A entrada assumida por um administrador não conta** (o D76): ela não toca no cookie da pessoa, e contar faria o valor copiado dela valer mais 12 horas a cada vez que alguém a assumisse. As linhas de antes (`web`, `''`) contam: foram todas de senha ou de cookie. Fora do prazo, a resposta é a página do formulário, como a do cookie que não existe, e nada se grava. **Ninguém percebe:** o navegador já apagava o cookie nesse prazo, e cada entrada pelo cookie renova as 12 horas, como antes. ##### Provado - `RegistroDeAcessosTest`, nos dois bancos: oito situações pelo `entrar` de verdade (pela senha há quase 12 horas e pelo cookie há 11, entram; há 12 horas e um minuto, há dois dias e sem entrada nenhuma, não; as linhas de antes, `web` e vazia, de uma hora atrás, entram; a assumida de uma hora atrás com a da pessoa de 13 horas, não) -- e só o cookie que entra grava; e a borda com o relógio na mão (o segundo 43.200 vale, o 43.201 não). Os arneses do D315 e do D347 (`cookieQueEntra`, o `setUp` do `SenhaTrocadaTest`) ganharam a entrada que o login de verdade deixa. - Por HTTP, o caso 23 do `ensaiar-sessao-do-erp.php`, nos dois bancos de contrato: com as entradas do gerente das últimas 12 horas deslocadas 13 horas para trás, o mesmo `token_web` de um login novo responde o formulário (200); de volta às horas, ele entra (302). Falsificado por HTTP, no MySQL: sem o prazo, o caso 23 fica vermelho (22 de 23). - Mutantes, no MySQL, cada um vermelho: o `entrarCookies` sem o prazo (os quatro casos de fora do prazo), a entrada assumida contando (o dela) e a borda estrita (`>` no lugar de `>=`, o da borda). ##### A verificação do mesmo dia **A entrada tem de ser da própria pessoa, e nada o provava.** Sem o `ace.usuario = :usuarioId` na consulta de `entrouPeloNavegadorDesde`, o `token_web` de qualquer pessoa entraria sempre que alguém tivesse entrado nas últimas 12 horas -- em produção, sempre --, e nenhum caso o via (o verificador conferiu os 990): todo conjunto grava entradas só da pessoa, e os bancos de teste não têm linha nenhuma em `usuarios_acessos`. Por HTTP, o caso 23 pegaria só por acaso (a linha `senha` do administrador que o caso 22 cria). Agora o `RegistroDeAcessosTest` tem a nona situação -- outra pessoa entrou pela senha há uma hora, e a pessoa há 13 horas: não entra -- e a borda confere a consulta com o id de outra pessoa. Mutante, nos dois bancos: a consulta sem o usuário (a condição e o parâmetro) fica vermelha nos dois casos. **O resíduo, que é o desenho da 103.** Cada entrada pelo cookie também é "a última entrada": ela grava a linha `cookie`, e o `setCookie` dá mais 12 horas ao navegador -- é o "como o navegador" da resposta. Por isso **o valor copiado que é usado a cada menos de 12 horas não para de entrar**: quem o copiou renova o prazo a cada uso, como o navegador da pessoa renovaria. Ele cai quando a pessoa entra pela senha (o `criarToken` gira o `token_web`), clica em Sair, ou passa 12 horas sem que ninguém use o valor; e cada uso de quem o copiou fica no registro de acessos da pessoa, "pelo cookie". O "Ninguém percebe" acima vale para quem usa o próprio navegador; o "para sempre" de quem para sem sair só acaba se o valor copiado também parar. Fechar esse resíduo é um teto contado da última entrada pela senha -- a opção (b) da pergunta 103 ("as 12 horas, e a senha de novo a cada 30 dias"), que o dono não escolheu. Fica registrado, sem pergunta nova. **O que continua aberto, e não é daqui:** o `ALTER TABLE` das três colunas do hash anterior e as rotações dos hashes de unidade e de cliente -- janela e produção. (A pesquisa do `pesquisas.hash`, a quinta credencial da tabela acima, deixou de abrir qualquer coisa em 12/10/2026: o link público avulso saiu, o D399.) **06/11/2026: a entrada automática na tela nova decidida pela resposta 317 (a) do dono** (gravada na página do lote em 07/11/2026 01:14 UTC, sem observação): "Fica como está: entra sozinho, pela mesma regra do ERP". A fatia 94 já fazia assim (`POST /adm/api/sessao/retomar`, pela `Permissions\EntradaPeloCookie`, a mesma regra do `entrarCookies`), e nada muda. O estado deste débito não muda por isso: o que continua aberto é o de cima -- o `ALTER TABLE` e as rotações, da janela e da produção. ### D78 — A coluna chamada `salt` guarda a senha, e ela e reversivel Descoberto em 01/09/2026, seguindo o gerador de credenciais do **D77**. O **D7** olhou para esta coluna em 17/08 e escreveu: *"Salt nao e segredo por definicao, entao o impacto e menor"*. **A frase esta errada, e errou pelo nome da coluna.** #### O que a coluna guarda ```php public function setSalt($salt) { $this->salt = openssl_encrypt($salt, 'AES-128-CBC', '0', 0, '0123456789101112'); } public function getSalt() { return openssl_decrypt($this->salt, 'AES-128-CBC', '0', 0, '0123456789101112'); } ``` E quem a preenche: ```php public function criptografarSenha($senha) { $this->setSalt($senha); // <- a SENHA entra aqui return password_hash($senha, PASSWORD_BCRYPT); } ``` **A coluna guarda a senha do usuario, cifrada de forma reversivel**, com chave `'0'` e vetor `'0123456789101112'` -- os dois literais no codigo versionado. Provado com valor sintetico, sem tocar em senha real: ``` senha inventada: MinhaSenhaInventada#2026 o que vai na coluna: opsGt+LTk0mzOgAxemAe79abhBag8LFeNOuObZ4TYUI= de volta com a chave do codigo: MinhaSenhaInventada#2026 ``` #### E o bcrypt e decoracao A coluna `senha` guarda `password_hash(..., PASSWORD_BCRYPT)`, que esta certo. Mas **a autenticacao nao usa esse hash**: ```php // UsuarioRepository::autenticacao if (!empty($usuario) && $senha == $usuario->getSalt()) { ``` Compara o que o usuario digitou com o retorno de `getSalt()` -- isto e, com a senha decifrada. O `entrarCookies` faz o mesmo: `setCredential($usuario->getSalt())`. **Quem tem o dump e o repositorio tem as senhas de todos, em texto claro.** E senha se reusa: o estrago nao para neste sistema. #### O que atenua, e o que nao **Atenua:** `scripts/anonimizar.sql.modelo:81` faz `salt = NULL`, entao as copias que circulam para desenvolvimento nao levam as senhas. O **D2** e o **D3** ja tratam de credenciais versionadas. **Nao atenua:** a producao tem a coluna cheia, e o esquema de criptografia esta no repositorio. Um dump de producao vazado -- ou um acesso de leitura ao banco -- entrega as senhas. #### DECISAO DE 01/09/2026: medir a producao antes Apresentei tres caminhos. Voce escolheu **nao escolher ainda**, e medir primeiro -- e o pedido esta certo, porque um dos tres pode trancar usuarios para fora. **A pergunta que decide:** o conserto troca a autenticacao por `password_verify` contra a coluna `senha`. Isso so e seguro se **todo usuario ativo tiver um bcrypt valido ali**. Quem nao tiver perde o acesso no instante da mudanca. **A copia local nao responde.** A anonimizacao faz `salt = NULL` e troca `senha` por um hash de desenvolvimento, entao qualquer medicao aqui devolve verde falso. Rodei para conferir o roteiro, e ele diz "0 ativos sem bcrypt valido" -- numero que **nao vale nada**, porque mede o hash que a propria anonimizacao gravou. `scripts/medir-senhas-producao.sql` esta pronto: **so SELECT**, nenhuma senha impressa, e a unica listagem individual traz `id` e data. Ele espera a leitura da producao ser descongelada. #### O levantamento que encolheu o problema Ao preparar as opcoes, tres fatos mudaram o tamanho do conserto: **1. O login principal ja esta correto.** `config/autoload/doctrine.global.php` configura o adaptador com `credential_callable` fazendo `password_verify($senhaDigitada, $user->getSenha())`. O caminho que todo mundo usa todo dia ja autentica por bcrypt -- e o fato de as pessoas entrarem e prova empirica de que a coluna `senha` tem hashes validos. **2. A senha reversivel serve a tres lugares, e so:** | Onde | Para que | |---|---| | `AutenticacaoController::entrarCookies` | login por cookie | | `UsuarioService::autenticarComo` | entrar como outro usuario -- sem chamador; APAGADO em 03/10/2026 | | `UsuarioRepository::autenticacao` | confirmar a senha atual | Os dois primeiros recuperam a senha apenas para **simular** um login no adaptador. O terceiro compara texto com texto. **3. Trocar o codigo nao remove a exposicao.** As linhas ja gravadas continuam com a senha recuperavel ate serem sobrescritas. Qualquer conserto real precisa de um `UPDATE` -- e ele tem de vir **depois** do codigo: na ordem inversa, o login por cookie e o "entrar como" param de funcionar. #### Ao resolver Autenticar pelo `password_verify` contra a coluna `senha`, que ja existe e ja esta preenchida com bcrypt. Nos dois fluxos de impersonacao, escrever a identidade na sessao direto, sem passar pelo adaptador -- o token ja foi validado antes. Depois o `UPDATE`, e so entao **apagar a coluna `salt`**. **Nao e mudanca de uma linha, e por isso e decisao sua:** `entrarCookies` e `autenticacao()` dependem de recuperar a senha, e trocar isso muda o fluxo de login. E a coluna `salt` e `NOT NULL`. **Nao fiz nada.** E o caminho de autenticacao de um sistema em producao. ### D79 — `setSenha()` estava quebrado desde 17/08/2026 — CORRIGIDO em 01/09/2026 Descoberto em 01/09/2026, ao ler o `criptografarSenha()` do **D78**. ```php public function criptografarSenha($senha) { $this->setSalt($senha); $this->setSenhaPhp83($senha); // <- este metodo NAO EXISTE return password_hash($senha, PASSWORD_BCRYPT); } ``` O commit `8f95f86` -- "Fecha o portao da F1.3" -- removeu o mapeamento, o `getSenhaPhp83()` e o `setSenhaPhp83()` da entidade, e **manteve a chamada**. Conferido executando, com valor sintetico: `setSenha()` lanca `Error: Call to undefined method ...::setSenhaPhp83()`. #### O que isso derruba Tudo que passa por `setSenha()`: criar usuario com senha, trocar a propria senha, e confirmar a redefinicao por token (`AutenticacaoService::senhaConfirmar`). #### Por que ninguem viu O **D7** afirma que *"nada fora da propria entidade os chamava"*. Fora, nao -- **dentro** chamava, na linha seguinte ao `setSalt()`. A verificacao olhou para o lado errado da fronteira. E os *"67 testes de caracterizacao continuam passando"* passavam porque **nenhum deles define uma senha**. Verde que nao cobre o caminho -- o mesmo desenho do **D55**, onde nove contratos congelavam resposta vazia. #### O alcance real, e ele e menor do que parece **A producao nao esta quebrada**: ela roda o codigo de antes da modernizacao e segue congelada desde 23/08. O que esta quebrado e o repositorio -- e o que estiver rodando no BVIP. **Mas o corte leva o defeito junto**, se ninguem o consertar antes. #### CORRIGIDO em 01/09/2026 A linha `$this->setSenhaPhp83($senha);` saiu. `setSenha()` volta a funcionar -- criar usuario com senha, trocar a propria senha e confirmar redefinicao por token. **E agora existe o teste que faltava.** `tests/Caracterizacao/SenhaEAcessoTest.php` define uma senha e confere que o bcrypt gravado bate com ela. Posto a prova: devolvi a linha quebrada de proposito e **tres dos quatro testes deram erro**, com exatamente a mensagem que ficou quinze dias escondida. O `setSalt()` continua ali, e continua errado -- e o **D78**, que espera a medicao da producao. #### O que era, antes de ser corrigido *(A versao anterior deste registro dizia que o conserto esperava o D78, porque `criptografarSenha` faz duas coisas. Por decisao sua de 01/09, as duas foram separadas: a linha quebrada saiu hoje, e o `setSalt` fica ate a producao ser medida. Destravar a troca de senha nao piora o D78 -- so devolve o que ja existia antes de 17/08.)* ### D80 — A fixture do caixa tinha validade de um dia — CORRIGIDO em 01/09/2026 Descoberto em 01/09/2026, na primeira vez que a suite rodou num dia diferente do dia em que as fixtures foram carregadas. **25 dos 119 testes cairam de uma vez.** #### O que aconteceu A guarda do **D28**, escrita em 31/08, recusa venda em caixa de data anterior -- que e a regra que voce enunciou. As fixtures gravam o caixa assim: ```sql INSERT INTO caixas (..., data_criacao, ...) VALUES (..., CONCAT(CURDATE(), ' 08:00:00'), ...) ``` `CURDATE()` e avaliado **no momento da carga**. Carregou dia 31, rodou dia 1: o caixa e de ontem, a guarda recusa toda venda, e a suite desaba. **A guarda estava certa.** A fixture e que tinha prazo de validade de vinte e quatro horas, e ninguem percebeu porque naquele dia ela foi carregada e usada na mesma tarde. #### O sintoma enganava As falhas nao diziam "caixa de outro dia". Diziam: ``` venda paga a menor deveria gerar debito Failed asserting that false is not false produto nao-servico deve dar baixa no estoque Failed asserting that 10.0 is identical to 9.0 -'89,90' +'0,00' ``` Tudo zerado, nada gravado -- o formato de quem **nao chegou a executar**. Sao sete arquivos de teste diferentes acusando sete coisas diferentes, e a causa era uma so, tres camadas abaixo. #### A correcao `CaracterizacaoTestCase::setUp` passou a por os caixas de fixture na data de hoje, **dentro da transacao** que ele ja abre e reverte. O acerto vai ali, e nao na fixture, porque so ali existe a garantia de ser "hoje" no momento do teste. Toca so a faixa 90001000+, e so quando a data difere -- nenhuma linha real e alterada, e nada sobrevive ao `tearDown`. #### A licao, e ela e generalizavel **Fixture que depende do calendario quebra sozinha, e quebra longe.** Nao houve mudanca de codigo entre o verde e o vermelho: mudou o dia. Qualquer dado de teste montado com `CURDATE()`, `NOW()` ou equivalente tem esse prazo embutido, e o custo aparece na forma mais cara -- vinte e cinco falhas que parecem vinte e cinco defeitos. *(As outras fixtures usam datas fixas, como `2026-01-01`. A do caixa precisou ser relativa por causa da propria regra do D28, e foi por isso que so ela teve o problema.)* #### E havia uma segunda, no mesmo dia e por outro caminho Consertados os 25, sobrou **um** teste falhando: `CronTravaSimultaneaTest::testODashboardDesisteQuandoJaHaExecucaoEmCurso`, com *"o cenario precisa de uma linha do mes corrente para observar"*. Mesma familia, origem diferente. Ele exigia que a **copia da producao** ja tivesse uma linha de `dashboard_colaboradores` do mes em curso -- e a copia e um retrato de 28/07, com dados ate agosto. No dia 1o de setembro o mes virou e a linha deixou de existir. **O que aquele teste mede e a trava, nao a existencia do dado.** Entao ele passa a montar o proprio cenario na faixa 90001000+, dentro da transacao, e usa a linha da copia quando ela existe. #### Procurei uma terceira, e nao ha Depois de consertar as duas, varri os testes de caracterizacao atras de tudo que usa `CURDATE()`, `NOW()`, `date(` ou `strtotime`. Sao 27 pontos, e a separacao e limpa: | | | |---|---| | **Montam** a data que usam | 25 -- inserem a linha com `date(...)` e depois a observam | | **Encontram** | 2 -- eram exatamente as duas que quebraram, e ja foram corrigidas | Um caso mereceu leitura por parecer risco e nao ser: `ConvenioDescontoTest` escolhe a coluna do dia da semana com `date('w')` e a **desabilita**, para verificar que o convenio deixa de valer. Adapta-se ao dia em vez de depender dele. E o que o tornaria falso -- desabilitar um dia que ja estivesse desabilitado, e passar sem provar nada -- foi conferido: a fixture da unidade 90001000 traz os **sete dias habilitados**. **Duas quebras por calendario no mesmo dia, em lugares independentes.** Nao e coincidencia: e o que acontece quando dado de teste depende de "hoje" sem que ninguem tenha decidido isso explicitamente. Vale como regra: **teste que precisa de uma data relativa monta essa data, nao a encontra.** #### E o conserto do D80 quebrou o PostgreSQL, por trinta horas Descoberto em 01/09/2026, na primeira rodada completa depois da correcao. O metodo que eu escrevi para por o caixa no dia de hoje usa `CURDATE()`, `TIME()` e `CONCAT()`. **As tres sao do MySQL.** No PostgreSQL a rodada morreu com `syntax error at or near "data_criacao"`, e nao em um teste: **nos 123**, porque o metodo roda no `setUp`. ``` Tests: 123, Assertions: 0, Errors: 123. ``` **O erro nao foi escrever SQL do MySQL. Foi conferir num banco so.** O roteiro `scripts/rodar-caracterizacao.sh` existe justamente para rodar nos dois, e eu tinha rodado o `phpunit` direto, contra o MySQL, porque era mais rapido. O verde que eu vi era metade do verde que eu precisava. Nao ha expressao unica que sirva aos dois bancos aqui: o `+` de data soma INTERVALO no PostgreSQL e NUMERO no MySQL. O metodo passou a ramificar por plataforma, o que e feio e honesto: ```php $postgres = stripos($conexao->getDatabasePlatform()->getName(), 'postgre') !== false; ``` **A regra que fica**, ao lado da do calendario: **verde em um banco nao e verde** — e este projeto tem dois justamente porque um vai substituir o outro. ### D81 — `status = 1` compara inteiro com coluna booleana, e o PostgreSQL recusa — CORRIGIDO em 02/09/2026 > **Ver tambem o D82**, que e o mesmo erro de tipo na direcao contraria: valor > booleano indo para coluna inteira. Ele apareceu justamente ao corrigir este. Descoberto em 01/09/2026, quando o teste novo do **D73** foi o primeiro a exercitar o relatorio de clientes contra o PostgreSQL. #### O que acontece O auxiliar dos filtros abre assim: ```php $dql .= " WHERE cli.status = 1"; ``` No MySQL, `status` e `tinyint` e a comparacao passa. No PostgreSQL a coluna e `boolean`, e o literal `1` nao tem operador: ``` SQLSTATE[42883]: Undefined function: 7 ERROR: operator does not exist: boolean = integer HINT: No operator matches the given name and argument types. ``` **O relatorio de clientes inteiro nao roda no PostgreSQL** — nao devolve resultado errado, nao devolve resultado nenhum. E o mesmo vale para todo caminho que compare uma coluna booleana com `0` ou `1`. #### A escala, agora medida de verdade — 02/09/2026 **O primeiro numero deste registro estava errado, e eu o marquei como "piso" para disfarcar que era chute.** Ele dizia "37 comparacoes em 12 arquivos", e saiu de um `grep` sobre nomes de coluna que eu ADIVINHEI. Adivinhar nome e depois chamar o resultado de piso nao e medir com margem: e nao medir. `scripts/conferir-booleanos-em-consulta.php` mede. A lista de campos booleanos vem do **metadata do Doctrine**, a mesma fonte que o ORM usa para gerar SQL, e o roteiro RESOLVE O APELIDO: junta os pedacos de DQL de cada metodo, le o `FROM`/`UPDATE`/`DELETE ` e cada `JOIN .`, segue as associacoes, e so entao pergunta o tipo do campo NAQUELA entidade. | | | |---|---:| | **Quebram no PostgreSQL** | **26** | | — literal na consulta, resolvidas pelo roteiro | 23 | | — literal na consulta, resolvidas a mao | 3 | | Inofensivas | 10 | **As 10 inofensivas sao o motivo de o numero antigo nao servir.** `status` esta mapeado como **boolean, string E integer**, conforme a entidade; `x.status = 1` so quebra onde o apelido cai numa entidade em que ele e booleano. Contar por nome misturava as duas coisas. **As 3 nao resolvidas pelo roteiro** sao todas de `filtrosListagemIndexRelatorio`, que recebe o inicio da DQL por parametro e por isso nao declara `FROM` no proprio corpo. Os dois chamadores usam `FROM ISCadastro\Entity\Cliente cli`, e `Cliente::status`, `Cliente::programaFidelidade` sao ambos `boolean`: as tres quebram. (O `marketing` daquele metodo NAO quebra -- ele e parametro; ver a correcao abaixo.) #### CORRIGINDO O QUE EU ESCREVI AQUI — medido em 02/09/2026 Eu registrei, e commitei, que `cli.marketing = :marketing` com `$params['marketing'] = (int) $request[...]` **quebraria igual ao literal**, e que a correcao do D73 tinha "mudado o defeito de lugar" — da consulta, onde um grep o acha, para o parametro, onde nao se ve. **Isso esta errado.** Fui medir contra o PostgreSQL, com a coluna `clientes.marketing`, que e `boolean`: | forma | resultado | |---|---| | `:m` = int `1` | OK — 242.412 | | `:m` = string `'1'` | OK — 242.412 | | `:m` = bool `true` | OK — 242.412 | | `:m` = int `0` / string `'0'` | OK — 175 | | **literal `= 1`** | **FALHA**: `operator does not exist: boolean = integer` | | literal `= true` | OK | **Parametro funciona em qualquer forma.** O valor chega tipado pelo driver e o PostgreSQL converte; o literal `1` vira inteiro na SINTAXE, e ai nao ha operador. O defeito e so o literal escrito na consulta. **Consequencias, e elas mudam o conselho:** 1. **A correcao do D73 CONSERTOU aquele sitio**, nao o escondeu. Trocar `" AND cli.marketing = " . (int) $x` por `= :marketing` fez a comparacao passar a funcionar no PostgreSQL. 2. **O total volta a 26**, nao 27. O caso do `marketing` nunca foi defeito. 3. **Para quem for atacar o D81: parametrizar tambem resolve.** Nao e preciso escolher entre `= true` e `= :flag` — as duas formas funcionam nos dois bancos, e a segunda tem o beneficio extra de nao ser injetavel. 4. A guarda perdeu a categoria `porParametro`, que media uma coisa que nao e defeito. Contar nao-defeito e pior que nao contar: infla o trabalho aparente. **Como o erro aconteceu:** eu raciocinei que "inteiro em coluna booleana falha" e apliquei isso ao parametro sem testar, porque o literal falhava. A diferenca entre sintaxe e valor ligado e exatamente o assunto do D73, que eu tinha acabado de tratar — e ainda assim escrevi o contrario. #### Dois erros na propria medicao, e o segundo e o pior tipo **Adivinhei os nomes das colunas** na primeira contagem. Corrigido lendo o metadata. **E a primeira versao do roteiro so procurava `FROM`.** DQL de `UPDATE` declara o apelido em `UPDATE SET ...`, entao `atualizarFidelizacao` e `removerPesquisasPlanoFidelidade` caiam em "nao resolvidas" — e as duas do `Cliente` quebram. O numero saiu de 21 para 23 quando isso foi corrigido. **Errar para menos e o pior sentido**, porque numero baixo e o que faz alguem concluir que da para adiar. #### O que a medicao NAO alcanca **Parametro ligado como inteiro para coluna booleana.** `$params['marketing'] = (int) $x` com `cli.marketing = :marketing` falha igual no PostgreSQL, e nao aparece em varredura nenhuma: o valor so existe em execucao. **A correcao do D73 criou uma dessas**, no filtro de marketing do relatorio de clientes. Consulta montada fora de `module/`, se houver, tambem fica de fora. #### Por que nao consertei junto A mudanca do D73 e sobre injecao. Trocar `= 1` por `= true` em 37 lugares e uma mudanca de outra natureza, sem cobertura, e **consertar so o sitio que o meu teste alcanca seria pior que nao consertar**: daria verde na suite e deixaria os outros 36, com a aparencia de resolvido. #### Como isto aparece hoje `tests/Caracterizacao/RelatorioClientesInjecaoTest.php` **salta no PostgreSQL**, com a mensagem dizendo qual e o defeito. Nao e `@group` silencioso: quem rodar a suite le o motivo. A prova do D73 naquele arquivo vale contra o MySQL; a do dashboard de faturamento roda nos dois. Quando o D81 sair, a condicao do salto sai junto, e o teste passa a cobrar os dois bancos — o que tambem serve de guarda contra o D81 voltar. #### CORRIGIDO em 02/09/2026 Os 26 literais viraram `= true` / `= false`, por SITIO EXATO — arquivo, linha e trecho, nao busca-e-substitui. A distincao importa: `status` e booleano em algumas entidades e `string` ou `integer` noutras, e uma troca cega quebraria as 10 comparacoes que ja estavam certas. 23 linhas em 12 arquivos. No MySQL o Doctrine traduz `true` de volta para `1`, entao a mudanca preserva o comportamento la e corrige aqui. **A prova nao e a minha sondagem, e sim a suite:** | | antes | depois | |---|---|---| | caracterizacao MySQL | OK (126, 240) | OK (126, 240) | | caracterizacao PostgreSQL | 126, **4 saltados** | **OK (126, 239)** | O `RelatorioClientesInjecaoTest` **perdeu o salto do PostgreSQL** — era a condicao escrita quando o salto foi posto ("quando o D81 sair, esta condicao sai junto"). Os 126 testes passaram a rodar nos dois bancos. A diferenca de uma assercao tem explicacao exata: no teste da carga `OR 1=1` o MySQL converte o valor e cai no `assertLessThanOrEqual`, que conta DUAS assercoes por ser restricao composta; o PostgreSQL recusa e cai no `assertNull`, que conta uma. E as sondagens, reexecutadas sem alteracao: dos 15 caminhos que quebravam, **14 passaram a rodar**. O 15o e o assunto do D82. #### O QUE PARA, POR TELA — rastreado em 02/09/2026 "26 comparacoes em 12 repositorios" nao ajuda ninguem a priorizar. Subi de cada sitio ate quem o chama. **Seis dos 26 estao em CODIGO MORTO** — sem chamador em `module/` nem em `public/`: | Metodo | Sitios | |---|---:| | `UnidadeRepository::selecionarAniversariantes` | 1 | | `UnidadeSocioRepository::selecionarAniversariantes` | 2 | | `UsuarioRepository::selecionarAniversariantes` e `...TempoTrabalho` | 2 | | `ClienteRepository::selecionarClientesAtivos` | 1 | **Sobram 20 vivos**, e estes sao os caminhos: | O que para | Onde | Sitios | |---|---|---:| | **O PDV** — `VendaFinalizarModal` e `VendaIndex` montam a lista de formas de pagamento | `FormaPagamentoRepository::popularCombobox` | 1 | | **A API do aplicativo** — `AplicativoController:792` busca cliente por telefone | `ClienteRepository::selecionarClientesPorTelefone` | 1 | | Cadastro de cliente e tela de fidelidade (mesmo metodo) | `ClientesController`, `FidelidadeController` | — | | Tela de vendas — o debito do cliente | `ClienteDebitoRepository::selecionarValorDebitosCliente` | 1 | | Financeiro — formularios de saida | `SaidaTipoRepository::popularCombobox` | 1 | | Servicos, usuarios e o formulario do relatorio de clientes | `AreaAtuacaoRepository::popularCombobox` | 1 | | Assistentes e mensagens | `GrupoRepository::popularCombobox` | 1 | | Lista de convenios | `ConvenioRepository::listagemIndex` | 1 | | Relatorio de caixas | `CaixaRepository::selecionarPorPeriodoUnidade` | 1 | | Agenda — clientes novos | `ClienteRepository::listagemIndexClientesNovos` | 1 | | Marketing — pesquisa de clientes | `ClienteRepository::marketingPesquisarClientes` | 1 | | Relatorio de clientes (as 3 do auxiliar) | `filtrosListagemIndexRelatorio` | 3 | | **Cron** — fidelizacao, aniversariantes, clientes sem retorno | `CronJobService` | 7 | **O que isso reordena.** O relatorio de clientes, que foi por onde tudo isso apareceu, e um item entre treze — e nao o mais grave. **O PDV e a API do aplicativo estao na lista**, e sao respectivamente o que as 32 unidades usam para fechar venda e o que ~800 clientes por dia usam no telefone. #### E entao eu executei, em vez de inferir — 02/09/2026 A tabela acima nasceu de rastro de CHAMADOR, o que e inferencia. Chamei os metodos, um a um, contra o PostgreSQL: | caminho | resultado | |---|---| | **o PDV** (formas de pagamento) | **QUEBRA** | | **API do app** (cliente por telefone) | **QUEBRA** | | tela de vendas (debito do cliente) | **QUEBRA** | | financeiro (tipos de saida) | **QUEBRA** | | servicos/usuarios (areas de atuacao) | **QUEBRA** | | cron: aniversariantes | **QUEBRA** | | cron: clientes sem retorno | **QUEBRA** | | cron: fidelizacao | **QUEBRA** | **Oito de oito**, todas com a mesma mensagem: `operator does not exist: boolean = integer`. Nao e mais suposicao: **essas telas nao executam no PostgreSQL hoje.** **E depois alcancei os seis que faltavam.** Eles pediam objeto de sessao ou o `$request` da tela; montei um substituto minimo de sessao (so `getUsuario('administrador')` e `getUnidade('id')`) e as chaves que cada um le: | caminho | resultado | |---|---| | assistentes/mensagens (grupos, **nao-admin**) | **QUEBRA** | | assistentes/mensagens (grupos, **admin**) | **QUEBRA** | | relatorio de caixas (periodo) | **QUEBRA** | | lista de convenios | **QUEBRA** | | marketing (pesquisa de clientes) | **QUEBRA** | | agenda (clientes novos) | **QUEBRA** | | cron: fidelizacao por colaborador | **QUEBRA** | Onde o codigo ramifica por administrador, rodei os dois ramos — um caminho que so quebrasse para admin passaria despercebido. **Somando as duas rodadas: 15 execucoes, 15 quebram.** #### DUAS VEZES EU LI VERDE ONDE NAO HAVIA CONSULTA A lista de convenios deu "PASSOU" duas vezes antes de quebrar, e as duas foram erro meu: 1. **O metodo devolve um paginador, que e PREGUICOSO.** Chamei e larguei; nao executou consulta nenhuma. "Passou" significava "nao rodou". 2. Forcei com `getTotalItemCount()` — e ainda passou. Porque aquilo executa a consulta de CONTAGEM, e o Paginator **descarta a subconsulta do `SELECT`** ao monta-la. E na subconsulta que mora o `cli.status = 1`. So `getCurrentItems()`, que busca as linhas, alcancou a subconsulta. **E a terceira vez nesta semana que um verde meu era ausencia de execucao** — as outras duas foram o `count()` no paginador (que devolve paginas, nao itens) e o `git stash` de um arquivo ja commitado (que nao guardou nada). **Fica de fora, ainda, `ClienteRepository::atualizarFidelizacao`:** e um `UPDATE` que zera `fidelizadoColaborador` e `fidelizadoUnidade`, e sondagem que escreve deixa de ser sondagem. Pelo texto, ele quebra igual — mas isso e leitura, nao execucao, e esta escrito assim de proposito. **E um ficou de fora de proposito:** `ClienteRepository::atualizarFidelizacao` e um `UPDATE` que zera `fidelizadoColaborador` e `fidelizadoUnidade`. Sondagem que escreve deixa de ser sondagem. #### A pergunta que ficou aberta, e o quanto dela ja da para responder — 02/09 Eu escrevi aqui: "se o relatorio de clientes nao roda, quantas outras telas nao rodam?" A pergunta continua sem resposta completa — isso se responde exercitando as telas, nao varrendo codigo — mas tres das quatro maneiras conhecidas de um sistema MySQL nao rodar no PostgreSQL ja foram olhadas. **1. SQL cru na producao: nao e risco.** `module/` inteiro tem **UMA** execucao de SQL direto, em `ISBase\Doctrine\DeclararInquilino`, e ela e PostgreSQL-only por desenho (guardada por `instanceof PostgreSqlPlatform`) e usa parametro. Tudo o mais passa por DQL. As ~110 execucoes de SQL cru do projeto estao nos TESTES, que rodam contra os dois bancos — e onde havia MySQL puro, ja quebrou e foi corrigido (o `DATE_SUB(..., INTERVAL ? DAY)` de `CaixaNaoAtravessaODiaTest`). **2. Funcoes de DQL: tratadas de proposito.** `DATE`, `DAY`, `MONTH`, `YEAR`, `DAYOFWEEK`, `TIMESTAMPDIFF` e as demais sao classes proprias em `module/ISBase/src/Doctrine/`, e elas RAMIFICAM POR PLATAFORMA — `DateFunction` emite `DATE(x)` no MySQL e `CAST(x AS date)` no PostgreSQL. Nao e sorte: esta escrito no codigo, com o motivo. **3. `GROUP BY` estrito: provavelmente nao e problema, e nao verifiquei.** O PostgreSQL exige que toda coluna selecionada e nao agregada esteja no `GROUP BY` — o MySQL nao, com `ONLY_FULL_GROUP_BY` desligado. O relatorio de clientes seleciona ~25 colunas e agrupa por tres. **Mas as tres sao chaves primarias** (`cli.id`, `con.id`, `colab.id`), e o PostgreSQL aceita dependencia funcional desde a versao 9.1: agrupar pela PK cobre as colunas daquela tabela. Pela leitura, passa. **Nao vi rodar**, porque o erro do booleano acontece antes — e um defeito atras de outro foi exatamente o que aconteceu com o D80 hoje. **4. Booleano comparado com inteiro: e esta, e sao 27.** A unica das quatro que sobra como defeito medido e aberto. **O que isso muda para a decisao:** o D81 nao e a ponta de um iceberg desconhecido. E o item que restou depois de tres classes vizinhas terem sido olhadas — duas resolvidas e uma provavelmente inofensiva. Continua valendo exercitar as telas antes do corte; o que muda e que isso deixa de ser uma expedicao as cegas. ### D82 — O espelho do D81: valor booleano indo para coluna inteira — CORRIGIDO em 02/09/2026 > **Ver tambem o D81**, corrigido em 02/09: literal inteiro contra coluna > booleana. Sao direcoes opostas do mesmo erro de tipo, com correcoes distintas. Descoberto em 02/09/2026, no instante em que o D81 saiu da frente. **Nao e regressao da correcao** — e um defeito que estava atras dela. #### O caso confirmado `CronJobService:587` monta os parametros do relatorio de fidelizacao assim: ```php $parametros = [..., 'colaborador' => $colaborador['id'], 'status' => true]; ``` E `VendaRepository::fidelizacaoPorColaborador` liga esse valor a `ven.status = :status`. Mas **`Venda::status` e `integer`**, nao booleano. No MySQL o `true` vira `1` e passa; no PostgreSQL vira `'t'`, e a coluna recusa: ``` SQLSTATE[22P02]: invalid input syntax for type integer: "t" ``` E o mesmo erro de tipo do D81, **na direcao contraria**: la era literal inteiro numa coluna booleana; aqui e valor booleano numa coluna inteira. #### A escala, medida em 02/09/2026 — sao 8 `scripts/conferir-booleano-em-coluna-inteira.php`, o espelho da guarda do D81: le o tipo do campo no metadata, resolve o apelido pelo `FROM`/`UPDATE`/`JOIN`, e so entao procura o literal `true`/`false`. | | | |---|---:| | No MESMO metodo | 6 | | Montado por QUEM CHAMA | 2 | | **Total** | **8** | | Nao resolvidas (conferidas a mao, nenhuma e caso do D82) | 13 | **As 6 do mesmo metodo:** | onde | campo | |---|---| | `VendaRepository:933` (x2) | `Venda::npsNotificacao` e `npsRespondido`, ambos `integer` | | `VendaProdutoRepository:178` e `:200` | `Venda::npsRespondido`, `integer` | | `VipClassRepository:129` | `VipClass::status`, `integer` | | `TesteEstiloColunaRepository:12` | `TesteEstiloColuna::status`, `integer` | **As 2 do chamador**, as duas em `CronJobService:574`, do mesmo array `$parametros`: `fidelizacaoPorColaborador()` e `evasaoPorColaboradorTotalVendas()`, ambas ligando `status => true` a `Venda::status`, que e `integer`. **A primeira e a que foi confirmada por execucao**; a segunda eu nao conhecia. #### DUAS VEZES O MEDIDOR ERROU, e as duas foram pegas pelo caso conhecido Ter UM caso confirmado por execucao foi o que permitiu conferir o medidor — e ele falhou duas vezes antes de acertar: 1. **A primeira versao devolveu 6 e NAO continha o caso conhecido.** Ela so procurava o literal dentro do mesmo metodo, e o `CronJobService` monta o array num arquivo enquanto a DQL vive noutro. Um medidor que nao ve o caso que eu sei que existe nao mede nada. 2. **A segunda criou uma categoria "A CONFERIR" com 316 linhas.** Ela listava TODO parametro ligado a coluna nao-booleana — inclusive `est.uf = :estado`, que e texto indo para coluna de texto. Isso e o erro oposto ao chute do D81: em vez de subestimar, **superestimava por cinquenta vezes**. So a terceira — seguir o chamador, um salto — produziu um numero que significa alguma coisa. **O que o medidor ainda nao ve**, e esta escrito nele: valor que chega por variavel atribuida a mais de um salto de distancia, e consulta montada com `QueryBuilder` em vez de DQL em texto (o `VisagismoController:278` e uma dessas — conferida a mao, e inofensiva: `Visagismo::status` e `string` e recebe `'finalizado'`). #### CORRIGIDO em 02/09/2026 Os 8 sitios viraram o inteiro que significavam: `true` para `1`, `false` para `0`. Sao 6 ligacoes em 5 arquivos — duas delas servem a dois sitios cada. No MySQL, `true` ja se ligava como `1` para coluna inteira; a mudanca preserva o comportamento la e corrige aqui. medicao quebram 0, pelo chamador 0 caminhos 16 verdes, 0 vermelhos conhecidos, 16 caminhos **E O PORTAO CONTINUOU VERMELHO DEPOIS DA CORRECAO** — o que foi bom. Ele chamava `fidelizacaoPorColaborador` com o proprio `status => true`: eu tinha corrigido a producao e deixado o dado de teste com o valor antigo. O valor do portao passou a espelhar o que `CronJobService:587` passa hoje. **O limite disso esta escrito no portao:** como o valor mora nele, ele nao veria alguem devolver o `true` no chamador. Quem vigia isso e `scripts/conferir-booleano-em-coluna-inteira.php`, que le o codigo. **Um executa, o outro le, e nenhum dos dois sozinho cobre o caso.** A medicao virou guarda, com linha de base 0/0/13 e falhando nos dois sentidos. #### E os caminhos viraram portao — 02/09/2026 As sondagens que acharam o D81 e o D82 viviam no scratchpad, e sumiriam. `scripts/conferir-caminhos-postgres.php` e a versao que fica: executa 15 caminhos reais da aplicacao contra o PostgreSQL, com o D82 listado como **vermelho conhecido, com o motivo escrito**. Ele preenche um buraco de METODO, e nao so de codigo. Antes dele o projeto tinha `verificar-schema-postgres.php` (compara esquema) e `gerar-ddl-postgres.php` (gera DDL) — ambos necessarios, nenhum suficiente. O D81 passou despercebido justamente por ser erro que so aparece ao RODAR a consulta. 14 verdes, 1 vermelho conhecido, 15 caminhos **Falha nos dois sentidos, e foi provado:** tirando o D82 da lista de conhecidos, o portao acusa `REGRESSAO` e sai com codigo 1. Quando o D82 for corrigido, ele avisa que a linha de base precisa descer junto. **E ele diz o que NAO e:** 15 caminhos nao sao o sistema. Responde "estes continuam rodando?", nao "o sistema roda no PostgreSQL". #### Por que nao consertei junto Trocar `true` por `1` naquela linha resolveria o unico caso que me atrapalhava e deixaria os outros, com a aparencia de resolvido. E exatamente o argumento que usei para nao remendar o D81 pela metade, e vale igual aqui. #### O que este achado ensina sobre o metodo Os 15 caminhos do D81 foram medidos por execucao, e 14 passaram a funcionar. O 15o revelou ESTE defeito — que so era visivel depois do outro sair. E a terceira vez que isso acontece no projeto: antes foram o D80 (tres quebras do caixa atras de uma) e o `DATE_SUB` escondido atras da falha total do PostgreSQL. **Corrigir um defeito e um ato de medicao:** ele revela o proximo. ### D83 — A F1.1 vai para a homologação — DECIDIDO em 02/09/2026 — REMISSÃO ao D1, D2, D3 e D7, lido em 05/10/2026 > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito como fechado, e o corpo diz que ele está reduzido a remissão: o defeito mora em outro débito. Remete ao D1, D2, D3 e D7, onde moram as pendências da F1.1 (rota migrar-senhas, credenciais, arquivos do webroot, senha_php83). Por decisão sua: *"anotar f1.1, f1.7 e f1.9 como débito tecnico, isso será resolvido na homologação. Preciso avançar na fase 2 e 3"*. A F1.1 é a remediação que se aplica **no servidor**, não no código. Ela vinha da Fase 0, foi congelada em 23/08 e agora sai do caminho crítico da Fase 1. #### O que fica pendente, e continua valendo em produção | | | |---|---| | `/autenticacao/migrar-senhas` | rota pública que, **num GET**, sobrescreve o hash de senha de TODOS os usuários ativos (**D2**) | | Seis credenciais em texto claro | versionadas, aguardando rotação (**D3**) | | Arquivos com dados pessoais no webroot | acessíveis por URL (**D1**) | | `usuarios.senha_php83` | 2.430 senhas com criptografia reversível e chave fixa no código (**D7**) | #### O que já está pronto e parado `scripts/remediacao-dia0.sh` (audita por padrão; `--aplicar` move para quarentena datada e grava a apuração LGPD) e `scripts/bloquear-migrar-senhas.sh`, este **provado contra um nginx real**. Nenhum dos dois precisa de trabalho novo: o que falta é a janela e a autorização. #### O que esta decisão significa, dito uma vez **A rota `migrar-senhas` continua ativa até a homologação.** Um GET nela sobrescreve o hash de todos os usuários ativos, e ela não pede autenticação. O risco não mudou de tamanho por ter mudado de lugar no plano — mudou de prazo. Isso não é objeção à decisão, que é sua e está tomada: é o registro do que se aceita ao adiar, para que a escolha continue visível quando a homologação chegar. ### D84 — A F1.7 vai para a homologação — DECIDIDO em 02/09/2026 — PARCIAL, lido em 05/10/2026 > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito como fechado, e o corpo diz que ele está parcial: uma parte está consertada, e a outra não. Falta: na homologação: VPN em malha, três nós de etcd, arquivos fora do disco local (D33), troca de tráfego por DNS e o ensaio no parque. Alta disponibilidade com failover automático, ensaiada em laboratório e não no parque. Sai do caminho crítico pela mesma decisão de 02/09. #### O que está provado, e continua valendo | | | |---|---| | Promoção automática, sem intervenção | provada **três vezes** | | Tempo | **30 a 36 s** contra meta de 300 | | Reintegração do nó caído | automática | | RPO 0 | provado, com `sync_standby` designado | O laboratório fica versionado e repetível (`f1-7-ensaio-failover.md`). Quando os cinco itens abaixo estiverem prontos, o mesmo roteiro roda no parque, e a comparação entre os dois números dirá quanto a rede real custa. #### Os cinco itens, em ordem de dependência | | O que falta | Por quê | |---|---|---| | 1 | VPN em malha | o Orange Pi está atrás de CGNAT: não recebe conexão, logo não vota nem assume | | 2 | Três nós de etcd | um só não tem quórum; sem maioria, um nó isolado pode promover indevidamente | | 3 | Arquivos fora do disco local | **D33** — a abstração está pronta desde a F1.5; falta ligar o driver S3 | | 4 | Troca de tráfego | DNS com verificação de saúde, contando o TTL no tempo total | | 5 | Ensaio no parque | primário real derrubado sem aviso, cronometrado | #### A consequência para o corte **O corte vai de nó único.** Isso era uma decisão em aberto e passou a ser consequência desta: sem os cinco itens, não há failover automático no dia. Se o primário cair durante a janela, a volta atrás é manual, pelo `procedimento-de-corte.md`. ### D85 — A F1.9 vai para a homologação — ENCERRADO em 09/09/2026 Repontar o BI. Sai do caminho crítico pela mesma decisão de 02/09. #### O lado do banco está pronto e provado O papel `bvip_bi` é **somente leitura** (cinco tentativas de escrita recusadas), com escopo por inquilino e contraprova, lendo de **réplica** — onde nem o superusuário escreve. #### O lado da ferramenta não foi tocado Trocar o conector, instalar o provedor Npgsql no gateway e republicar. Nada disso é trabalho de banco, e é o que depende da Microsoft (**D9**). #### O RISCO QUE ESTA DECISÃO CARREGA, e é o maior dos três **Hoje o Power BI lê o MySQL de produção direto.** Se o banco migrar sem repontar, o BI **quebra no corte** — não degrada, para. Adiar a F1.9 para a homologação só é seguro se o repontamento acontecer **antes** do corte, e não depois. O portão de saída da F1.9 continua sendo "BI lendo do PostgreSQL, com credencial própria e sem permissão de escrita", e ele precisa fechar antes do passo 1 do `procedimento-de-corte.md`. #### ENCERRADO EM 09/09/2026 — o risco saiu junto com o BI O maior risco registrado acima era: *"Se o banco migrar sem repontar, o BI quebra no corte — não degrada, para."* **Não há mais o que quebrar.** O Power BI saiu do sistema por decisão do dono (**D9**), e o portão de saída desta frente deixou de ter sujeito. O repontamento sai do pré-requisito do passo 1 do `procedimento-de-corte.md`. **O ganho no corte é medível, e é por subtração:** um papel a menos para criar, dez provas a menos para conferir — `scripts/conferir-papeis.sh` foi de dezesseis para seis —, um roteiro a menos (`conferir-bi-replica.sh`, 159 linhas), uma variável de ambiente a menos em quatro roteiros, e a Microsoft fora do caminho crítico. **O que este encerramento NÃO resolve** está no D9: a credencial que o Power BI usava continua existindo no MySQL de produção. Tirar o consumidor não revoga o usuário. #### E o achado que esta frente revelou continua aberto Ao começar a F1.9 apareceu o **D48**: as 75 políticas de isolamento por inquilino da F1.3 **não estavam em vigor**, porque a aplicação conectava como superusuário — que está acima de qualquer política. Medido, sem declarar inquilino, o superusuário via **61 unidades**. Corrigido no ambiente com `bvip_app`; **em produção, ainda não.** --- ### D86 — A autorização da venda em fiado não autoriza: é um aviso no navegador — PARCIAL em 02/09/2026 > **Ver também o D165** — a outra metade, achada em 09/09/2026. Aqui a > autorização **não existia** de verdade; lá ela **existe demais**: uma vez > gravada, nada a limpa, e ela sobrevive ao fiado que a motivou. Requisito do responsável pelo projeto, 02/09/2026, em três partes: > 1. A autorização deve ser verificável e rastreável. Caso uma venda seja > lançada como fiado, junto com o operador de caixa deve aparecer o gerente > que autorizou a venda (hoje não existe isso — expandir visualização e > registro). > 2. Somente o gerente daquela unidade ou gerente geral podem autorizar > (verificar antes de autorizar). > 3. Conferir as credenciais de fato e validar da forma correta no banco de > dados. **O que é a venda em fiado.** O cliente não paga na hora, mas o lançamento precisa acontecer porque o serviço foi de fato prestado — é ele que produz a conta-parte do barbeiro. O pagamento entra depois, pela quitação de débitos, com a forma correta, e só então cai no caixa da unidade. A autorização do gerente é o que separa "crédito concedido" de "venda que ninguém pagou". O mecanismo **já existe**: `pdvAutorizarVendaFiado` (`public/layout/scripts/mod-vendas.js:856`) abre o modal, e `VendasPagamentosController::autorizarVendaFiadoAction` (linha 106) responde. Ele tem quatro buracos, medidos hoje no código. #### Buraco 1 — a autorização não é aplicada, é apenas consultada `autorizarVendaFiadoAction` devolve `{sucesso: true}` e **não grava nada**. Quem aplica o resultado é o navegador: `mod-vendas.js:875` faz `if (response.sucesso === true) pdvFinalizarVenda();`. `finalizarAction` (linha 72) não menciona fiado, nem autorização, nem gerente — verificado. **Chamar `finalizar` direto pula o modal inteiro.** Não é uma suposição sobre o que dá para fazer: é a ausência da verificação no único lugar que decide. Enquanto a decisão morar no navegador, o requisito 1 não tem o que registrar, porque não há momento no servidor em que "esta venda foi autorizada por fulano" seja um fato. #### Buraco 2 — não é o gerente **daquela** unidade O teste é `$usuario->getGrupo()->getGerente()` (linha 126): um sinalizador do **grupo**, não da unidade. Gerente de qualquer uma das 32 unidades autoriza fiado em qualquer outra. Os campos do `Grupo` são `administrador`, `gerente`, `caixa`, `colaborador` e `status` — **não existe "gerente geral"** como sinalizador próprio. O que existe é `administrador`, e o próprio sistema já o usa com esse sentido em `VendasController.php:177`: ```php $venda->getUnidade()->getId() == $usuario->getUnidade()->getId() || $usuario->getGrupo()->getAdministrador() ``` Esse é o precedente a seguir: **mesma unidade, ou administrador**. `Usuario` tem `unidade` como `ManyToOne` — uma só —, então "gerente daquela unidade" é verificável. Uma ressalva medida: `Venda::getUnidade()` (linha 188) **é derivada**, não guardada — devolve `getUsuario()->getUnidade()`. A unidade da venda é a unidade *atual* do operador. Se o operador for transferido, a unidade das vendas passadas dele muda junto. Para a verificação no ato isso não atrapalha; para a auditoria depois, atrapalha, e é mais um motivo para o requisito 1 gravar. #### Buraco 3 — a senha é comparada em texto claro `UsuarioRepository::autenticacao` (linha 111): ```php if (!empty($usuario) && $senha == $usuario->getSalt()) { ``` `Usuario::getSalt()` (linha 815) faz `openssl_decrypt($this->salt, 'AES-128-CBC', '0', 0, '0123456789101112')` — chave e IV fixos, no código-fonte. A coluna `salt` **não guarda um salt**: guarda a senha em texto claro, cifrada de forma reversível (`criptografarSenha`, linha 1485, grava o bcrypt em `senha` e chama `setSalt($senha)` com o texto claro). Então a comparação é texto claro contra texto claro, com `==` e não `hash_equals`. **A forma correta já está no projeto**, e é a que o requisito 3 pede: `config/autoload/doctrine.global.php:100` autentica o login principal com `password_verify($passwordSent, $user->getSenha())`, contra a coluna `senha`, que é bcrypt. O conserto aqui é usar o mesmo mecanismo, não inventar um. **Consequência que liga este débito ao D78:** enquanto a autorização do fiado depender de `getSalt()`, remover a coluna reversível **quebra a autorização**. Consertar o buraco 3 tira um usuário da coluna e diminui o D78. **O que ainda não dá para medir aqui.** Trocar para `password_verify` só é seguro se todo usuário ativo tiver bcrypt válido em `senha`. A cópia local não responde: a anonimização faz `salt = NULL` e troca `senha` por um hash fixo de desenvolvimento. `scripts/medir-senhas-producao.sql` (seção 4) é o número que decide, e ele continua esperando a leitura de produção — a mesma que o D78 e o D79 esperam. #### Buraco 4 — o modal pede e-mail, a consulta procura login O modal manda o campo `email` (`mod-vendas.js:868`) e `autorizarVendaFiadoAction:120` o repassa para `autenticacao($dados['email'], ...)`, cuja DQL filtra `usu.login = :login`. São colunas diferentes — `Usuario` tem `login` e `email` separados, e existe um `selecionarPorEmail` à parte. Isso funciona hoje só na medida em que login e e-mail coincidam. É pequeno, mas entra no requisito 2: "verificar antes de autorizar" exige saber com certeza **quem** está sendo verificado. #### O que o requisito 1 custa: mudança aditiva de esquema `Venda` tem `usuario` (o operador), `cliente`, `caixa`, `convenio`, `debito`, valores, `nps`, `status` e as datas — verificado campo a campo. **Não há coluna para o autorizador.** Gravar quem autorizou é coluna nova em `vendas` (`ManyToOne` para `Usuario`, mais o instante da autorização). Isso põe o D86 na mesma categoria do **D54**: mudança aditiva que precisa estar **em produção antes do corte**, senão a tela nova encontra coluna que não existe. A dependência é para verificar no `procedimento-de-corte.md`, não para assumir. #### O que foi corrigido em 02/09/2026 **Buraco 3 — fechado, e o alcance era maior do que este endereço.** `autenticacao` não é do fiado: **quatro** telas dependem dela — cancelar venda (`VendasController:171`), autorizar fiado (`VendasPagamentosController:120`), uma ação de clientes (`ClientesController:654`) e a troca da própria senha (`UsuariosController:658`). As quatro comparavam texto claro. Agora usam `password_verify` contra a coluna `senha`. *A espera pela produção não se aplicava aqui, e isso foi verificado.* A dúvida legítima — "e quem tiver `senha` sem bcrypt válido?" — se responde no código: o login por formulário (`entrarAction:31`) manda a senha digitada direto ao adapter, e o login por cookie (`entrarCookies:181`) manda o texto claro ao **mesmo** adapter. Nenhum caminho de entrada evita o `password_verify`. Quem não passa por ele não está logado, e portanto não está diante do PDV. `medir-senhas-producao.sql` continua sendo o portão do **D78**, que é outra pergunta: quem perde o **login** quando a coluna sair. **Buraco 2 — fechado, igualando à tela que já estava certa.** O teste passou a ser gerente **e** (unidade da sessão **ou** administrador) — a mesma regra de `VendasController:177`. Nada foi inventado; as duas telas passaram a concordar. **Provas.** `tests/Caracterizacao/AutorizacaoFiadoTest.php`, cinco casos. O terceiro é o que separa o antes do depois: planta na coluna reversível um valor diferente da senha e exige que ele **não** autentique. Com o código antigo reposto, a suíte dá **duas falhas**; com o novo, nenhuma — medido, não suposto. A regra de unidade mora no controller, e alcançá-la em teste exigiria montar sessão e ACL. Segue a decisão já registrada no **D76**: `scripts/conferir-autorizacao-privilegiada.php` a vigia estruturalmente, junto com o cancelamento, para que as duas telas não voltem a divergir. A guarda falha nos dois sentidos — conferido removendo os termos. #### O buraco 1: o registro existe, a aplicação ainda não **A coluna nasceu, e o número que ela revelou é o tamanho do problema.** A migração `scripts/migracao-venda-autorizacao-fiado.sql` acrescenta `vendas.autorizado_por` (FK para `usuarios`) e `vendas.autorizado_em`. Ao ser aplicada à base local: **2.269.212 vendas, 36.978 em fiado, e nenhuma com autorizador registrado.** Não era uma lacuna ocasional — era a totalidade. O endpoint passou a gravar as duas colunas, e a tela de detalhes da venda mostra "Fiado autorizado por: *nome*, em *data*" logo abaixo do operador de caixa — onde quem decide pediu. Quando o registro falta numa venda que é fiado, a tela diz **"Sem registro de autorização"** em vermelho, em vez de omitir a linha: venda antiga e venda burlada precisam ser visíveis, não silenciosas. *Por que a linha não aparece em venda à vista:* não há o que autorizar, e um "—" em toda venda treinaria o olho a ignorar o campo. *Por que só nessa tela:* "junto com o operador de caixa" tem um lugar só. A expressão "Operador de Caixa" aparece em **um** ponto do sistema inteiro, `detalhes.phtml:92` — a listagem de vendas não mostra o operador em nenhuma coluna, só o oferece como filtro. Foi conferido antes de escolher onde pôr, e não por suposição. **A aplicação no servidor ficou de fora, e a razão é de implantação, não de código.** `finalizarAction` ainda não recusa fiado sem autorização, e o motivo está em `module/ISBase/view/layout/layout.phtml`: o JavaScript é servido com `?cache=`, e o navegador do operador guarda a versão antiga. Se o servidor passasse a exigir o registro **no mesmo instante** em que o navegador começa a enviá-lo, toda estação ainda com o script em cache pararia de finalizar venda em fiado — **PDV parado nas 32 unidades** até o cache virar. Por isso a ordem é de dois tempos, e o segundo depende de o primeiro estar no ar: 1. *(feito)* servidor **grava** quando recebe `venda_id`, e **concede** quando não recebe; navegador passa a enviar; `?cache=161` subiu para `162`. 2. *(pendente)* servidor **recusa** fiado sem autorização registrada — só depois de confirmado que nenhuma estação usa o script antigo. O lugar do passo 2 já está localizado: `validarFinalizarVenda` (`VendasPagamentosController:214`), que junta mensagens de recusa e é a mesma função onde o D28 pôs a recusa do caixa de dia anterior. A condição é `getValorRecebido() < getValorTotal() && getAutorizadoPor() === null`. #### O PASSO 2 EXISTE desde 03/09/2026 — mas só na API nova A primeira fatia da Fase 2 (`docs/f2-fatia-pdv.md`) trouxe `POST /adm/api/comandas/:id/finalizacao`, e **ele recusa** fiado sem autorização registrada — HTTP 409, medido contra a aplicação de pé: > `Venda em fiado exige autorização de um gerente antes de ser finalizada.` **Por que lá pode e aqui não.** A trava nunca foi de rigor: era o cache. O navegador do operador pode estar com o script anterior, e exigir de repente pararia o PDV das 32 unidades. **A API nova não tem consumidor nenhum** — pode exigir desde o primeiro dia. E `POST /adm/api/comandas/:id/autorizacao-fiado` **grava** o autorizador, em vez de responder um sim que o navegador aplica. Ela nasce com a regra das outras telas — gerente **e** (unidade da sessão **ou** administrador) — e é a **quinta** entrada de `conferir-autorizacao-privilegiada.php`. Três respostas distinguidas, medidas: credencial que não confere dá **422** (dado errado, e não se diz qual dos dois falhou); credencial boa de quem não pode autorizar dá **403**; comanda que não é fiado dá **409**, porque não há o que autorizar. **A tela velha continua como estava**, e o passo 2 dela continua esperando o cache virar. O que mudou é que o caminho novo não herda a dívida. *E a regra ganhou nome:* `Venda::ehFiado()` e `Venda::fiadoSemAutorizacao()`. A comparação `valorRecebido < valorTotal` estava escrita em **quatro** lugares — o serviço, o controller antigo, o novo e o apresentador da API. Regra repetida diverge, e a primeira cópia a mudar cria o defeito. Enquanto o passo 2 não acontece, chamar `finalizar` direto continua pulando o modal. **O registro é confiável para o que ele afirma** — quem está gravado autorizou de fato, com credencial conferida — mas a ausência dele ainda não impede a venda. **Esta migração precisa estar em produção ANTES do corte**, pela mesma armadilha do **D54**: o passo 1 do `procedimento-de-corte.md` refaz o `mysql.sql` a partir da estrutura de produção, e é dele que `gerar-ddl-postgres.php` parte. Sem o `ALTER` aplicado antes, o schema PostgreSQL nasce sem as colunas e a tela de vendas morre na primeira consulta. Aplicada aos quatro lugares no ambiente: banco MySQL local, `mysql.sql` versionado, `postgres/schema.sql` regerado e o PostgreSQL de pé — conferido por `verificar-schema-postgres.php` (0 colunas ausentes) e por dois testes que escrevem nas colunas novas **nos dois bancos**, que é a falha de sequência que o D54 ensinou a temer. **ERAM CINCO LUGARES, e o quinto só apareceu no dia seguinte.** Existe um `franquiabv_contrato`, montado uma vez a partir do `mysql.sql`, contra o qual roda a suíte de contrato. Ele ficou para trás. O sintoma **mentia**: três testes de contrato falharam com HTTP 500 e a mensagem dizia *"o contrato do endpoint 'cliente-consumo' mudou"*. Não mudou. As entidades passaram a mapear duas colunas que aquele banco não tinha, e qualquer consulta que tocasse `vendas` morria. *E eu diagnostiquei errado na primeira tentativa.* Fiz `git stash` para saber se as falhas eram minhas, vi que persistiam e as chamei de pré-existentes — mas o `stash` só desfaz o que não está commitado, e a causa estava no commit `173b1bd`, desta mesma sessão. O teste que resolveu foi comparar o catálogo dos dois bancos: `franquiabv_dev` tinha as duas colunas, `franquiabv_contrato` tinha zero. **`scripts/rodar-contrato.sh` passou a conferir antes de rodar.** Ele compara os pares tabela/coluna do `mysql.sql` com os do banco e, se faltar algum, nomeia a coluna e manda remontar — em vez de deixar a suíte acusar a coisa errada. *A primeira versão dessa conferência contava colunas dos dois lados.* Os números não batiam por um (887 contra 888), e com isso **uma** coluna faltando passaria despercebida — 887 não é menor que 887. Contagem aproximada num portão é o mesmo que portão nenhum. A versão que ficou compara os pares, e foi posta à prova derrubando exatamente uma coluna: acusou `vendas.autorizado_em` pelo nome. *E quase reintroduzi o estrago que aquele roteiro existe para evitar:* a conferência criava arquivos temporários e eu instalei um `trap ... EXIT` para limpá-los — o que **substitui** o `trap restaurar`, deixando o `local.php` apontando para o banco de contrato depois da execução. Os temporários passaram a sair à mão, e o teste confirma que a linha `ambiente restaurado` continua saindo. #### O buraco 4, fechado: o rótulo pedia e-mail, a consulta queria login **A dúvida que travava isto era falsa, e quem decide a desfez em 02/09/2026:** > *"o login pode ser apenas um nome de usuário ou um endereço de e-mail (login)"* O identificador **é o `login`**. Ele *pode ter forma de e-mail* — e era justamente isso que fazia o defeito passar despercebido por anos: para o gerente que cadastrou o login como o próprio endereço, o campo rotulado "E-mail (gerente)" funcionava. Para o gerente cujo login é um nome de usuário, digitar o e-mail dava **"Não foi possível localizar o usuário"** — credencial boa, recusada, com uma mensagem que sugeria que a pessoa não existe. `login` e `email` são colunas distintas de `usuarios`, e `autenticacao` sempre filtrou `usu.login`. **O que mudou, e o que deliberadamente não mudou.** A consulta continua em `login`: aceitar também a coluna `email` **alargaria** quem pode autorizar e abriria colisão — o e-mail de um poderia ser o login de outro. O que estava errado era o rótulo, e é ele que foi consertado: - o campo passa a se chamar **"*Login (gerente):"**, com a dica *"nome de usuário ou e-mail"*, nos dois modais de fiado (`novo.phtml`, `comanda.phtml`) e no formulário de cancelamento (`VendaCancelarModal`); - o navegador manda a chave `login`; - a mensagem de recusa deixou de dizer "não foi possível localizar o usuário" quando a senha é que estava errada. Agora diz **"Login ou senha não conferem"** — verdade sem revelar qual dos dois falhou. **A redação não foi inventada.** A terceira tela que reconfirma senha — a devolução de crédito (`ISCadastro\Form\CreditoDevolucao:27`) — **já** rotulava o campo como *"\*Login (gerente)"* e já lia `$request['login']`. Ela estava certa desde sempre; eram as duas telas de venda que destoavam. Conferido antes de escolher o texto, e agora as três dizem a mesma coisa. **O cancelamento levou a mesma correção**, e não por zelo: ele tinha o defeito idêntico (`VendasController:171` lia `$request['email']`), e o portão `conferir-autorizacao-privilegiada.php` existe exatamente para as duas telas não divergirem. Deixar metade consertada era criar a divergência que o portão vigia. **Duas coisas ficaram no lugar antigo, com motivo escrito:** 1. *A chave `email` continua aceita no servidor.* O `layout.phtml` serve o JavaScript com `?cache=`, e o navegador do operador pode estar com o script anterior — que manda `email`. Recusá-la trocaria um defeito de rótulo por um PDV parado. O `?cache=` subiu de `162` para `163`. 2. *O `id` do campo continua `email`.* É por esse `id` que o script seleciona o campo; trocá-lo agora faria o script em cache não achá-lo. Renomear depois que o cache virar — o servidor já aceita as duas chaves. **O que a cópia local não pôde medir, e por isso não foi medido:** quantos usuários reais têm login em forma de e-mail. A anonimização sobrescreve `usuarios.login` para `user` e `email` para `colaborador@exemplo.invalid` (`anonimizar.sql.modelo`, linhas 77 e 78) — qualquer contagem daqui seria artefato, o mesmo motivo pelo qual `medir-senhas-producao.sql` existe. **A correção não depende desse número:** ninguém que autoriza hoje deixa de autorizar, porque a consulta não mudou. #### Um achado de ambiente, encontrado por acidente ao escrever o teste **Os dois bancos de desenvolvimento não partem do mesmo estado**, e nada avisava. O PostgreSQL local é povoado por `scripts/migrar-dados.sh`, que copia do MySQL. As linhas de `tests/Caracterizacao/fixtures.sql` que ele tem são, portanto, tão antigas quanto a última carga — e o `fixtures.sql` cresceu desde então. Medido em 02/09/2026, para os identificadores `90001000+`: | tabela | MySQL | PostgreSQL | |---|---:|---:| | unidades | 2 | 1 | | usuarios | 3 | 2 | | clientes | 3 | 1 | | caixas | 2 | 1 | | **vendas** | **3** | **0** | | vendas_pagamentos | 3 | 0 | **Por que ninguém tinha visto:** todo teste que precisa de venda já insere a sua própria, dentro da transação desfeita — `FechamentoVendaTest`, `ConvenioDescontoTest`, `CupomTest` e os demais. O hábito, que existe por outro motivo, escondia a diferença. Foi este débito que a revelou: a primeira versão de `AutorizacaoFiadoTest` usou a venda de fixture, **passou no MySQL** e morreu no PostgreSQL com `Call to a member function getAutorizadoPor() on null`. Mais uma vez a mesma lição do **D80** — *verde em um banco não é verde* —, agora pelo lado do dado e não do SQL. **Não foi consertado aqui, e o motivo é de custo:** igualar os dois exigiria recarregar o PostgreSQL com `migrar-dados.sh`, que copia 2,27 milhões de vendas e 242 mil clientes; é ferramenta de ensaio de corte, não de rotina de teste. O teste foi feito autossuficiente, como os outros. Fica registrado que a suíte do PostgreSQL **não** exercita as fixtures posteriores à última carga, e que qualquer teste novo que dependa delas vai falhar só lá. #### O que continua aberto **O irmão encontrado no caminho — corrigido em 02/09/2026, por decisão de quem opera.** `ClientesController::creditoDevolucaoAction` exigia gerente e **não** conferia a unidade. É o mesmo defeito do buraco 2, em outra tela e num fluxo em que **sai dinheiro**: devolve crédito ao cliente. Ficara registrado sem conserto porque mudar quem pode autorizar devolução de crédito não é decisão de quem edita o código. A regra é a mesma das outras duas — gerente **e** (unidade da sessão **ou** administrador) — e a unidade certa não foi escolhida por analogia: o crédito é buscado com `$this->unidadeId`, logo o dinheiro é da unidade da sessão, e quem autoriza a saída dele responde por essa unidade. A mensagem de recusa também deixou de mentir aqui, como nas outras duas: dizia "não foi possível localizar o usuário" mesmo quando a senha é que estava errada. **A guarda ganhou a quarta entrada, e um par de termos em vez de um.** O sinal óbvio seria exigir `unidadeId` no método — e ele **não prova nada aqui**, o que foi medido, não suposto: a busca do crédito usa `$this->unidadeId` de qualquer forma, então o termo continua presente mesmo com a comparação apagada. Ao apagar o bloco inteiro num teste de regressão, `unidadeId` de fato **não** acusou; quem acusou foram `getAdministrador` e `getUnidade`, este último porque no método só aparece na comparação. Por isso os dois andam em par. *(É o mesmo erro de raciocínio que este projeto vem corrigindo: o termo estava presente, e presença não é evidência de que ele faz o que se supõe.)* **Uma armadilha para quem for planejar a fatia do PDV — e que esta correção fechou.** O inventário marcava `autorizarVendaFiado` como **Escreve: sim** quando ele não escrevia nada. A coluna vem de uma heurística que o próprio gerador declara — *"uma ação que recebe POST quase sempre muta, ainda que pela mão de outro"* (`scripts/inventariar-acoes.php:303`) — e esta ação era o contraexemplo dela. Ler o inventário sem essa ressalva escondia exatamente o buraco 1: o rótulo prometia uma escrita que não existia. **Deixou de ser contraexemplo em 02/09/2026**, porque a ação passou a gravar de verdade: o `escreve_direto` do inventário virou `sim` pelo sinal forte, e não pela aproximação. A advertência sobre a heurística continua valendo — ela é aproximação por construção —, mas este já não é o caso que a ilustra. *(O buraco 4 foi fechado em 02/09/2026 — ver a seção abaixo.)* *10/10/2026, a verificação do item PDV-TERCEIRA-RODADA (o D380):* mais um caminho em que a tela velha pulava o modal sem ninguém chamar o `finalizar` à mão. O "Quitar" sobe o total, e o `pdvPagarDebitos` não refazia o par "Finalizar"/"Finalizar fiado": com o pagamento já cobrindo o total de antes, ficava o "Finalizar", e os débitos fechavam como fiado sem o gerente -- inclusive na saída da recusa da pergunta 55. A tela foi consertada (a resposta do "Quitar" traz o `fiado` e a tabela, como a do pagamento, `mod-vendas.js?cache=166`); o servidor do ERP continua sem conferir a autorização, que é este buraco 1. --- ### D87 — Um teste que não sobrevivia à meia-noite — CORRIGIDO em 03/09/2026 Descoberto por acidente: a suíte de caracterização rodou atravessando as 00h e o MySQL acusou **uma falha** que o PostgreSQL, rodando minutos depois, não teve. `RoyaltiesTest::testCamposDeLavaVipVaoParaAColunaCerta` falhou. Nenhuma linha de código havia mudado entre uma coisa e outra — o que mudou foi o dia. #### O mecanismo O cenário fazia duas leituras do relógio, em momentos diferentes: 1. `vendaFinalizadaHoje()` grava a venda com `date('Y-m-d H:i:s')`; 2. minutos depois, `royaltiesDeHoje()` procura a linha com outro `date('Y-m-d')`. Entre as duas passa o cálculo dos royalties, que não é rápido — a classe inteira leva cerca de dez minutos. Atravessando a meia-noite, as duas chamadas devolvem **dias diferentes**, e a busca não acha nada. A asserção vê `0,00` onde esperava o faturamento. #### NÃO É O D42, e a diferença é o que importa O **D42** foi a **fonte** do relógio: o MySQL do contêiner em UTC contra o PHP em `America/Sao_Paulo`, três horas de divergência, e os testes passavam às 19h34 e falhavam às 21h. A correção de lá foi comparar com a mesma fonte. Este é o **momento**: mesma fonte, lida duas vezes, com a virada do dia no meio. A correção de lá não alcançava este, e não tinha como alcançar. #### A correção Fixar o dia **uma vez**, no instante em que a venda é criada, e usar o mesmo valor nos dois lados — inclusive no período pedido ao serviço, no teste que compara os dois caminhos do relatório. Ela funciona porque `royaltiesAtualizar()` recalcula **ontem e hoje** (`FranquiaService:45-48`). A linha do dia da venda existe mesmo que o serviço rode já no dia seguinte — então não há janela em que o cenário fique sem resposta. #### A prova, nos dois sentidos A meia-noite não se agenda, então o cenário foi **simulado**: a venda passou a ser datada de ontem, que é exatamente o estado em que o teste se encontra depois da virada. | | | |---|---| | Com a correção, venda de ontem | **passou** | | Sem a correção, venda de ontem | **falhou** — `'89,90'` esperado, `'0,00'` obtido | O segundo é o mesmo sintoma visto às 00h. Restaurado o arquivo, 5 de 5. #### O que isto custava, e por isso não ficou como está Uma falha por relógio é pior que uma falha comum: ela aparece sozinha, some sozinha, e ensina quem vê a desconfiar do vermelho. Este projeto passou semanas construindo portões para que vermelho signifique alguma coisa — um teste que falha uma vez por dia, sempre à mesma hora, desfaz isso em silêncio. #### A busca pelos outros — feita em seguida, e o conserto virou sistêmico A primeira versão deste registro dizia *"não foi procurado se há outros"*. Foi, logo depois. Das 26 classes de caracterização, **11 liam o relógio**, num total de 23 leituras. Três tinham o mesmo defeito, com frequências diferentes: | Onde | Quando quebraria | |---|---| | `ConvenioDescontoTest` | escolhe a coluna do **dia da semana** por `date('w')` depois de inserir a venda — risco **diário** | | `CronTravaSimultaneaTest` | lê `date('m')` e `date('Y')` duas vezes, e ainda misturava `NOW()` do banco — risco **mensal** | | `DashboardFaturamentoAnosTest` | monta o intervalo esperado com `date('Y')` — risco **anual** | Consertar um a um deixaria o próximo para o próximo. O conserto foi outro: **`CaracterizacaoTestCase::agora()`**, que lê o relógio **uma vez por teste** e devolve sempre o mesmo instante, com deslocamento relativo opcional aplicado sobre ele. As 23 leituras viraram chamadas a ele, menos as que **não são** leitura de relógio — e essas estão nomeadas. **Um caso pedia asserção diferente, não troca mecânica.** `PagamentoTrocoDebitoTest` afirmava `assertStringStartsWith(date('Y-m-d'), $data)` sobre uma data carimbada pela *produção* ao finalizar. Aí não há instante único possível: quem grava é o código, quem confere é o teste, e a meia-noite pode cair entre os dois. Passou a comparar a **distância** até agora (600 s), que diz a mesma coisa — *"o campo vale o momento do fechamento"* — sem depender do dia. **Guardado por `scripts/conferir-relogio-nos-testes.php`**, o vigésimo portão. Ele lê pelo `token_get_all` — os comentários deste projeto citam `date()` e `CURDATE()` para contar a história, e comentário não pode acusar. Falha nos dois sentidos: leitura nova acusa, e exceção que ninguém usa mais também, porque lista de exceção que não encolhe deixa de descrever o código. Conferido dos dois lados. **Ele já pagou na primeira execução**, achando o que eu não tinha visto: `CronTravaSimultaneaTest` inseria `data_criacao` com `NOW()` **do banco** na mesma instrução em que o ano e o mês vinham do PHP. Hoje as duas fontes coincidem, mas coincidir por configuração não é ser uma fonte só. **E corrigiu um comentário que envelheceu.** `RoyaltiesTest` afirmava que *"o MySQL do contêiner roda em UTC"*. Não roda: o `docker-compose.yml` passou a subi-lo com `--default-time-zone=-03:00` em 27/08/2026, para espelhar a réplica de produção. Medido em 03/09 — `@@global.time_zone` e `@@session.time_zone` são `-03:00`, e o `NOW()` do banco bate com o `date()` do PHP no segundo. **O D42 continuava aberto assim mesmo**, por dois motivos: a aplicação ainda misturava as fontes, e a produção não foi medida. > **Metade disso caiu em 13/09/2026.** A aplicação não mistura mais — zero > ocorrências em 658 arquivos de `module/`, medido por token —, e agora há portão > (`conferir-relogio-do-banco.php`). **A outra metade continua de pé:** o relógio > de produção segue sem medida, e medi-lo é ação de servidor, que espera a janela > do corte. --- ### D88 — Um código mestre resgatava a pontuação de qualquer cliente — CORRIGIDO em 03/09/2026 — PREPARADO, lido em 05/10/2026 > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito como fechado, e o corpo diz que ele está pronto no código, à espera só do passo em produção na janela da migração final. Falta: aplicar em produção, na janela, o ALTER TABLE de pontuacoes_historicos.autorizado_por; sem a coluna, o resgate autorizado falha. Encontrado em 03/09/2026, ao procurar como este sistema já provava a identidade de um cliente — porque a autenticação do **D59** precisava saber se havia precedente. Havia, e ele tem uma chave-mestra. O resgate de pontos do programa de fidelidade manda um código de seis dígitos ao cliente por WhatsApp e pede que ele seja digitado no balcão. A conferência está em `ClientesController::programaFidelidadeResgatarPontuacaoAction`: ```php if ($credito->getCliente()->getCodigoApp() == $request['codigo'] || $request['codigo'] == "000000") { ``` **O segundo termo aceita `000000` para qualquer cliente**, sem consultar código nenhum. O código existe para provar que o cliente está ali e concorda; com essa linha, quem opera a tela resgata a pontuação de quem quiser sem que a pessoa saiba — e o resgate vira crédito, que é dinheiro na conta da unidade. **Não é hipótese de invasor externo:** a tela exige sessão do ERP, então quem alcança isso é funcionário. É exatamente o risco que o código de verificação existia para cobrir. **Um segundo defeito na mesma linha, menor e real.** A comparação é `==`, e o PHP compara duas strings numéricas como NÚMEROS. `'012345' == '12345'` é verdadeiro, e o gerador (`RandomString::gerarSomenteNumeros`) produz códigos com zero à esquerda. Para esses, o espaço de busca encolhe. **Por que não corrigi na descoberta.** `000000` tem cara de saída operacional deliberada — cliente sem sinal, WhatsApp fora do ar, cliente sem o celular na mão. Apagar a linha travaria o balcão numa situação real, e isso era decisão sua. Você mandou atacar no mesmo dia. **Não há como medir o uso histórico**, e isso não mudou: `PontuacaoHistorico` grava quem resgatou e quanto, e nunca gravou qual código foi aceito. Os 373.104 resgates da base não se separam entre "o cliente confirmou" e "alguém digitou seis zeros". Daqui para a frente, separam. #### O QUE FOI FEITO — a saída continua existindo, e agora tem nome A chave-mestra virou uma **autorização registrada**, com o mesmo desenho do fiado (**D86**), porque é a mesma pergunta: um gerente reconfirma a **própria senha**, o sistema confere contra o bcrypt, exige o papel de gerente e a unidade da sessão — ou `administrador`, que é o que faz o gerente geral atravessar unidades — e grava quem autorizou. | | antes | depois | |---|---|---| | Resgatar sem o código | digitar `000000` | login e senha de um gerente | | Quem podia | qualquer operador da tela | gerente da unidade, ou administrador | | O que fica registrado | nada que distinga | `pontuacoes_historicos.autorizado_por` | **A coluna, e não só a descrição.** A descrição também passou a dizer, porque é ela que aparece na tela do histórico — mas quem responde *"quantos resgates saíram sem o cliente confirmar"* é a coluna. Texto livre de 200 caracteres serve para ler, não para perguntar. #### O SEGUNDO DEFEITO DA MESMA LINHA, e ele era real `==` no PHP compara duas strings numéricas como **números**: um código com zero à esquerda conferia com o mesmo número sem o zero, e o gerador produz códigos assim (`RandomString::gerarSomenteNumeros`). Para esses, bastava tentar o número sem o zero. A comparação virou uma regra com nome na entidade — `Cliente::codigoAppConfere()` —, estrita e de texto. Sair do controller não foi arrumação: privada lá dentro, ela não tinha como ser testada, e é a regra que decide se uma credencial vale. #### ONDE ESTÁ A PROVA **`tests/Caracterizacao/ResgateSemCodigoTest.php`** — 8 testes. Restaurei a comparação antiga por um instante e **três deles ficaram vermelhos**: os seis zeros como chave-mestra, o zero à esquerda, e o cliente sem código gerado. Um teste que nunca falhou não prova que pega. Um deles diz o contrário do que se esperaria e está certo: **seis zeros continuam valendo quando são o código do cliente**. É um dos 10⁶ que o gerador pode sortear, e recusá-lo por precaução deixaria alguém sem conseguir resgatar. **Três entradas novas em `scripts/conferir-autorizacao-privilegiada.php`**, para a metade que teste nenhum alcança — a decisão dentro do controller exigiria montar sessão e ACL, a mesma ressalva do fiado. O portão ganhou uma forma que não tinha: **proibir um literal**. A chave-mestra não era função nem variável, era o texto `"000000"`; vigiar só identificadores a deixaria voltar em silêncio. Reintroduzi a linha e o portão acusou. #### O QUE PRECISA ACONTECER NO DEPLOY, e a ordem importa **1. O `ALTER TABLE`.** `pontuacoes_historicos.autorizado_por` entrou em `mysql.sql` e em `postgres/schema.sql`, e está aplicado nos três bancos locais. Em produção ele é mais um da lista que espera o descongelamento. **Sem a coluna, o resgate autorizado falha** — o resgate com código, que é a esmagadora maioria, continua funcionando. **2. O `?cache=` foi de 163 para 164.** A tela ganhou uma etapa nova, e o navegador do operador precisa buscar o script novo. Sem o número novo, quem estiver com o script antigo em cache vê a tela velha — que já não aceita seis zeros, e não oferece a autorização. **Uma página já aberta no navegador precisa ser recarregada.** **O contraste vale ser dito:** a autenticação do cliente construída no mesmo dia (**D59**) usa o mesmo canal e o mesmo tamanho de código, e lá `000000` sempre foi um palpite errado como qualquer outro. --- ### D89 — O portão de segredos do CI não via atribuição a índice — CORRIGIDO em 03/09/2026 Encontrado em 03/09/2026, lendo `CronJobService` para entender a fila do WhatsApp. `CronJobService::yungasAutenticacao()` montava a autenticação de um serviço externo com **apikey, e-mail e senha escritos no arquivo**. > **A CREDENCIAL EM SI JÁ ERA CONHECIDA, e o mérito não é meu.** Ela é a oitava > linha da tabela do **D3**, com o arquivo e a função nomeados desde 31/08/2026. > Eu a encontrei lendo o `CronJobService` por outro motivo e a registrei como > descoberta, sem conferir se já estava registrada — foi o portão de débitos > repetidos que me corrigiu. > > **A rotação continua sendo assunto do D3**, que é dono da lista das oito. O que > é deste débito é outra coisa: *por que o portão do CI não a viu.* **O portão existe e não pegou.** O passo "Nenhum segredo versionado" do CI procura o nome do segredo seguido de `=>`, `=` ou `:` e então o valor entre aspas. Aqui a atribuição é a um ÍNDICE — o colchete e a aspa de fechamento ficam entre o nome e o `=`, e a expressão não casa. Três credenciais passaram por baixo de um portão feito para isso. **O portão foi ampliado**, com a forma exata que escapou, e as credenciais saíram do código para `config/autoload/local.php`. Isso é o que era trabalho de código, e está feito. #### DECIDIDO em 03/09/2026: não é prioritário, e talvez a integração saia > *"colocar yungas como débito técnico, não é prioritário e talvez seja > descontinuado"* A rotação das credenciais **não** entra na fila de coisas a fazer antes do corte. A integração pode ser descontinuada, e trocar credencial de um serviço que vai sair é trabalho jogado fora. **O que isso muda, e o que não muda.** *Muda:* este débito deixa de aparecer como pendência ativa nas listas de "o que espera você". Ele fica aqui, registrado, à espera da decisão sobre a integração em si. *Não muda:* as três credenciais **continuam válidas** no serviço externo, e continuam no histórico do git. Tirá-las do arquivo impede que novas cópias apareçam; não desfaz as antigas. Se a Yungas for descontinuada, o certo é **revogar** a conta no fornecedor — o que resolve melhor que rotacionar, porque uma credencial revogada não vale nem no histórico. **Se a integração for mantida**, a ordem é contraintuitiva e vale relembrar: trocar no fornecedor primeiro, preencher o `local.php` depois. Ao contrário, a rotina fica sem autenticar até alguém chegar no painel. **A rotina não cala quando falta credencial** — `yungasFaturamentoAtualizar` registra no log que não sincronizou nada, em vez de rodar em silêncio sobre nenhuma unidade. --- ### D90 — O par `.js`/`.min.js`, e qual dos dois o navegador recebe — CORRIGIDO em 03/09/2026 — PARCIAL, lido em 05/10/2026 — CORRIGIDO em 15/10/2026: a 121 (a) > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito como fechado, e o corpo diz que ele está parcial: uma parte está consertada, e a outra não. Falta: gerar os .min.js a partir do fonte na implantação, com uma etapa de construção; os oito pares seguem cópia manual. Decisão do dono. Notado ao mexer no `mod-vendas.js` pelo **D88**, e o que eu registrei primeiro descrevia só metade. `public/layout/scripts/` guarda os scripts da casa **em pares**: `geral.js` e `geral.min.js`, `mod-vendas.js` e `mod-vendas.min.js`. A tela escolhe **um** dos dois no `appendFile`, e o outro fica ali, parecido, sem rodar em lugar nenhum. **A medição, feita antes de apagar qualquer coisa:** | | | |---|---:| | Pares na pasta | 11 | | Que servem o **minificado** | **8** | | Que servem o **fonte** | **3** | Os três que servem o fonte — `mod-cadastros`, `mod-vendas`, `theme-switcher` — têm minificados que **nunca foram servidos na história deste repositório**: desde a importação inicial (`eaf1fca`, 15/08/2026) o `layout.phtml` aponta para o `.js`. E um deles tinha acabado de divergir, porque o **D88** acrescentou a etapa de autorização do resgate só no arquivo que roda. *Quase escrevi o oposto por contar em vez de olhar.* Uma primeira contagem disse que os três tinham "1 referência" cada — e a referência era este próprio débito, que os cita pelo nome. Contagem que inclui o documento que fala do problema não mede o problema. #### A ARMADILHA QUE IMPORTA É A OUTRA, e ela vale para 8 arquivos O minificado órfão é cópia velha de um script vivo: quem um dia trocar o servido pelo minificado "para ficar mais leve" leva junto o estado do arquivo no dia em que ele parou de ser atualizado. Chato, e limitado a três. **O caso inverso é pior, e alcança os outros oito.** Onde o servido é o minificado, editar o `.js` — que é o gesto natural, e o único legível — **não muda nada em produção**. O botão continua chamando uma função que existe no fonte e não existe no arquivo entregue, e o erro só aparece no console de quem clicar. **Medido: não tinha disparado.** Os **127 manipuladores** citados nas 15 telas que apendam script existem todos em algum arquivo servido. Nenhum botão morto hoje. #### O QUE FOI FEITO **Os três minificados órfãos foram removidos.** Ninguém os servia, o git guarda o histórico, e o `mod-vendas.min.js` já contradizia o arquivo vivo. **Um portão novo, `scripts/conferir-scripts-servidos.php`**, com as duas verificações: 1. nenhum `.min.js` da casa pode estar sem quem o sirva; 2. todo manipulador citado numa tela precisa existir em algum script **servido**. Provei as duas: recolocando um órfão, e trocando um `onclick` por um nome que só existiria num arquivo não servido. As duas acusaram, e o verde voltou. **O que o portão NÃO faz, de propósito:** comparar o minificado com o fonte. Minificador renomeia função local e reescreve `function x()` como `x=function()`, então diferença de texto entre os dois não prova nada — foi a primeira medição que tentei, e ela acusava `layout` e `mod-autenticacao` sem que houvesse defeito. O que se afirma com honestidade é mais estreito e mais útil: o nome que a tela chama aparece no arquivo que a tela manda servir. #### O QUE CONTINUA ABERTO, e é decisão sua **Os oito pares continuam sendo cópia manual.** Ninguém gera o `.min.js` a partir do `.js`; alguém minificou uma vez e versionou o resultado. O portão impede que a divergência passe despercebida **quando ela chega às telas**, e não impede a divergência em si. A saída definitiva é **gerar o minificado na implantação**, a partir do fonte — aí eles deixam de ser cópia e voltam a ser derivados. Isso exige uma etapa de construção que este sistema não tem hoje, e é trabalho a agendar, não a improvisar. #### FECHADO EM 15/10/2026 — a resposta 121 do dono, opção (a) "Servir o legível e apagar os oito minificados" (a fatia 5b, RESPOSTA-121-SCRIPTS-LEGIVEIS, o pedido "continue"). A opção pedia comparar cada par antes, porque o que rodava era o minificado, e o legível podia ter ficado para trás. **A comparação foi pelo comportamento, e não pelo texto** — a régua de 03/09 tinha razão: diff de texto entre fonte e minificado não prova nada. Os dois lados de cada par passaram pelo **mesmo** minificador (o do `rolldown` do front, com compressão e troca de nomes locais); a comparação de Yoda do minificador antigo foi desfeita (`!0===e.sucesso` → `e.sucesso===!0`, `11`); os nomes locais viraram um só; e o diff foi por token, lido trecho a trecho. Ao lado, a contagem dos literais de texto, números, nomes de propriedade e chaves de objeto dos dois arquivos crus. | Par | Tokens (legível × minificado) | Trechos que diferem | O que muda no comportamento | |---|---:|---:|---| | `fidelidade_cadastro` | 1.277 × 1.279 | 1 | só o `'use strict'` do topo do minificado — trazido ao legível (depois: 0) | | `geral` | 856 × 856 | 0 | nada | | `layout` | 2.991 × 2.968 | 54 | só o `'use strict'` do topo do minificado — trazido; o resto é reescrita: parâmetro reaproveitado como variável, `if` virando `&&`, o `return;` dentro do `.each` (que não para o laço) tirado, a variável `-200` posta no lugar | | `mod-autenticacao` | 809 × 787 | 13 | o legível é estrito dentro da função, e o minificado não; o `formToObject` do legível nunca é chamado, e o minificado não o tem; o resto é reescrita | | `mod-configuracoes` | 11.830 × 11.829 | 4 | nada: o minificado reaproveita o parâmetro `e` como variável, em duas funções | | `mod-financeiro` | 1.055 × 1.055 | 0 | nada | | `mod-marketing` | 2.130 × 2.130 | 0 | nada | | `mod-relatorios` | 2.412 × 2.401 | 12 | nada: o contador do laço do telefone no parâmetro `e`, e o `!a&&!b&&!c&&X` como `a\|\|b\|\|c\|\|X` | **Nenhum minificado tinha código que o legível não tivesse, e o legível não tinha ficado para trás em ponto nenhum.** Pelo git, todo commit que mexeu num lado de um par mexeu no outro — cinco, de 04/10 a 13/10 (Contas a Pagar duas vezes, a sessão e as rotas, o PDV e o cadastro, o Profissional Parceiro) —, e o conserto ficou igual nos dois. **O modo estrito era a única diferença, e foi medido.** O `layout.min.js` e o `fidelidade_cadastro.min.js` começavam por `'use strict'` (o minificador antigo o punha), e os legíveis não. Com a diretiva no topo, os dois legíveis compilam, não escrevem em nome não declarado e não leem o `this` de função chamada pelo nome — o medidor acha, no `mod-configuracoes.js`, as duas escritas que ele tem (`boundx` e `boundy`, em nenhum lado estrito), então ele mede. A diretiva veio para os dois legíveis, com o motivo escrito, para que trocar o arquivo servido não trocasse também o modo. O `mod-autenticacao.js` é o contrário — o legível já era estrito dentro da função, e o minificado não — e ficou como está: a mesma medição não acha nada que o modo mude ali, e no navegador a entrada e a redefinição da senha ligam os seus envios sem erro no console. Desde a revisão do mesmo dia, o `D90PortoesDosScriptsTest` prende a diretiva como a primeira instrução dos dois legíveis (arrancada, ou posta depois da primeira linha de código, o caso fica vermelho); que nada neles muda com ela segue sendo a medição acima, e não um caso. **O que mudou:** - **As sete telas pedem o legível.** O layout do ERP pedia seis (`layout`, `geral`, `mod-configuracoes`, `mod-financeiro`, `mod-marketing`, `mod-relatorios`); a entrada, a redefinição e a confirmação da senha, o `mod-autenticacao`; a adesão à fidelidade, o `fidelidade_cadastro`; as duas páginas da pesquisa NPS do balcão, o `mod-relatorios`. O `?cache=` de cada uma ficou: nenhum commit jamais pediu o endereço do legível, então nenhum navegador o guarda. - **Os oito minificados saíram do repositório.** O git guarda o histórico. - **`scripts/conferir-scripts-servidos.php` vigia o contrário do que vigiava:** nenhum `.min.js` na pasta da casa, nenhuma tela pedindo `.min.js` da casa, todo script da casa pedido existe (um 404 calado deixaria a tela sem os botões), e os 125 manipuladores como antes. Na revisão, mais três: todo arquivo da pasta da casa é pedido por alguma tela (a cópia órfã com outro nome, `mod-financeiro.antigo.js` ou `geral.js.bak`, que o servidor entregaria); o manipulador vale pelo nome inteiro e fora de comentário (os legíveis têm 104 comentários, e os minificados não tinham nenhum: uma função apagada que sobrasse num comentário passaria); e os seis pares do tema são os declarados. - **`scripts/conferir-segredos.sh` deixou de pular `public/layout/scripts/` e todo `*.min.js`.** As duas exclusões vinham da importação, sem motivo escrito; o que sobra na pasta é o legível, editado à mão e entregue a todo navegador. Medido antes de tirar: nenhuma linha casava nelas. Com uma chave inventada plantada no `geral.js`, o portão de antes saía 0, e o de agora sai 1 — e, desde a revisão, o `D90PortoesDosScriptsTest` faz isso num repositório de rascunho, nos dois modos do portão: a volta de qualquer das duas exclusões o deixa vermelho. - **`D90ScriptsLegiveisTest`** desenha as sete telas pelo `ViewRenderer` da aplicação — o layout com a sessão de quem entrou (`SessaoAcl::setAcl`), a adesão pelo despacho da ação — e confere que cada uma pede só legível, pede o que pedia minificado, e que o arquivo existe; no layout, também a ordem dos dez scripts da casa. - **`contasAPagarDaTelaAntiga.teste.ts`** roda só o legível (rodava os dois), e confere que o layout pede o `mod-financeiro.js` com o cache de pelo menos 166, e não o `mod-financeiro.min.js`; os outros cinco minificados do layout ficam com o `D90ScriptsLegiveisTest` e com o portão. - Os comentários que mandavam "mudar também o `.min.js`" (`mod-financeiro.js`, `remover-por-post.js`, `SaidasController.php`, `SaidasDoErpTest.php`) dizem o de hoje. **No navegador**, no ambiente local: a entrada (`/autenticacao/entrar`) e a redefinição da senha recebem o `mod-autenticacao.js` (200, 6.466 bytes) e ligam o envio do formulário; as duas páginas da pesquisa NPS recebem o `mod-relatorios.js` (200), todo `onclick` delas acha a sua função, e o teclado numérico monta `(11) 98765-4321` dígito a dígito — o ramo do décimo primeiro dígito era um dos trechos que o minificador reescrevia. Nenhum erro no console. E, numa página em branco do mesmo ambiente (a do 404), os 41 scripts do layout do ERP, na ordem dele, carregam com o `layout.js` estrito e sem um erro; 123 dos 125 manipuladores das telas são funções ali — os outros dois são o `buscarEndereco` da adesão (do `fidelidade_cadastro.js`) e um `y` que o portão lê num comentário do mural. Os 17 da adesão também carregam sem erro, com o `fidelidade_cadastro.js` estrito, e as máscaras dele formatam o telefone e o CEP. **O que não vi no navegador:** o layout do ERP logado (daqui não há sessão), a confirmação da senha (pede um token válido) e a adesão à fidelidade de verdade (pede um cliente, com dado pessoal). Nessas três, a prova é o teste em processo, a comparação dos pares e os scripts carregados na página em branco — e não o clique de quem usa. **Fica de fora, de propósito:** os seis pares do tema, de terceiros, em `public/global/scripts/` (`app`, `quick-sidebar`) e `public/pages/scripts/` (`components-color-pickers`, `components-select2`, `login-4`, `login-5`). As telas seguem pedindo o `.min.js` deles: o `app.min.js`, o layout e mais doze telas (as três da senha, as da fidelidade, da pesquisa NPS e dos assistentes); o `quick-sidebar`, o `components-color-pickers` e o `components-select2`, o layout; o `login-4.min.js`, as três telas da senha; e o script do `login-5` ninguém pede (as telas públicas usam só o CSS dele). Nenhum dos doze arquivos mudou desde a importação (`eaf1fca`) — mas quem editar o legível de um deles não muda a tela, a mesma armadilha deste débito. O `conferir-scripts-servidos.php` os conta e diz quem pede cada um. E o `conferir-segredos.sh` segue pulando `public/global/plugins/`, que também não casa nada hoje — não é desta resposta. #### A revisão de 15/10/2026 — oito achados, todos tratados | Achado | O que se fez | O que o pega | |---|---|---| | Os pares do tema eram seis, e não quatro: faltavam o `login-4` (pedido pelas três telas da senha, e não só pelo layout) e o `login-5` | a contagem e a lista acima, no cabeçalho do portão e no roadmap | `PARES_DO_TEMA`, no portão: um par a mais ou a menos o reprova; no repositório, seis | | O comentário do `SaidasController` dava ao minificado servido até 15/10 o defeito que só o de antes de 04/10 tinha — o `recarrega` entrou nele em `c18ba81` | diz "o de antes de 04/10", como o `SaidasDoErpTest` | nenhum caso: é texto, e a prova é o `git show c18ba81` | | As notas novas dos desenhos ficaram ao lado de `layout.phtml:761` e `:758`, que são comentários | `:765` (o `mod-configuracoes.js`) e `:747` (o `geral.js`), em `tela-tags.md`, `tela-pesquisas.md` e `tela-versao-app.md` | um medidor de rascunho: as três referências apontavam para comentário, e agora para o `appendFile`. O `conferir-referencias-docs.php` só confere que o arquivo existe | | Nenhum caso prendia o `'use strict'` dos dois legíveis | o caso | `D90PortoesDosScriptsTest` | | Nenhum caso pegava a volta das exclusões do `conferir-segredos.sh` | o caso, num repositório git de rascunho, com a credencial inventada montada por pedaços | `D90PortoesDosScriptsTest`, na árvore e no commit | | O docblock do `D90ScriptsLegiveisTest` dizia que nenhum lado tinha código a mais, e o `mod-autenticacao.js` tem o `formToObject`; e a linha do teste de Contas a Pagar dizia "nenhum minificado" | os dois textos dizem o que se mediu | nenhum caso: é texto | | O portão lia os comentários dos legíveis: um manipulador que só sobrasse num comentário passava | os comentários saem antes da busca (`jsSemComentarios`, que dá o mesmo texto que o `@babel/parser` nos doze scripts da casa, nos seis legíveis do tema e em três plugins), também no `` chegavam crus. *Consertado:* `htmlspecialchars($campo, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8')` **antes** do `mb_convert_encoding` — escapar em UTF-8 e só depois converter, porque as entidades são ASCII e atravessam a conversão intactas. Medido nos bytes entregues: `<script>roubar()</script>`, e nenhum `` passava inteiro e virava o `Reply-To` da mensagem. Quem recebe na franqueadora aperta "responder" e fala com o atacante, achando que fala com o atendimento da própria rede — e o e-mail *veio* de um endereço da rede, o que torna o disfarce melhor. **3. E-mail com erro de digitação derrubava o chamado.** Medido: `email=joaoexemplo.com` — um arroba esquecido, não um ataque — fazia `setReplyTo` lançar *"The input is not a valid email address"*, a resposta saía **500** em HTML, e o chamado **não chegava**. Quem digitou errado perdia o chamado e via erro. *Consertados juntos, porque são a mesma fronteira:* o `Reply-To` passa por `FILTER_VALIDATE_EMAIL`, que recusa os três casos — o vazio, o malformado e o `Nome `. O que não passa cai no destinatário, e **o chamado chega**. É a diferença entre perder o chamado e perder só o caminho de resposta. | o que chega | `Reply-To` | o chamado | |---|---|---| | e-mail válido | o cliente | chega | | e-mail com erro de digitação | a franqueadora | **chega** (antes: 500, perdido) | | nome de exibição disfarçado | a franqueadora | chega, sem o disfarce | | `email[]` como array | a franqueadora | chega, sem o *Warning* | | sem `email` | a franqueadora | chega | Os cinco medidos por execução, com a caixa conferida: as cinco respostas vieram `HTTP 200` `application/json` `{"sucesso":true}`, e as cinco mensagens foram entregues à franqueadora. **E os cinco campos ganharam teto de tamanho** — 200 caracteres para nome, e-mail e assunto, 60 para telefone, 4.000 para a mensagem, cortando com aviso no corpo em vez de recusar. A rota é pública e o corpo que chegasse virava e-mail do tamanho que fosse. Quatro mil caracteres são umas duas páginas de texto: o teto não impede ninguém de reclamar, impede que a reclamação seja um anexo. **A documentação embutida da API também estava errada**, e por minha causa: `ApiDocsController:523` dizia que `unidade_id` *"define e-mail da unidade quando informado"* — a frase descrevia exatamente o bloco que o conserto arrancou. Agora diz *"aceito e ignorado"*, e `email` e `telefone` entraram na tabela como opcionais, que o serviço lê e ela omitia. #### E um defeito vizinho, achado de passagem e NÃO mexido O mesmo levantamento mostrou que o **reset de senha** tem um problema que o SAC não tem. Em `AutenticacaoService:24-27`, o token novo é persistido **e descarregado** antes do envio: ``` 1. grava token novo no banco (flush) 2. tenta enviar o e-mail ``` SMTP indisponível no passo 2 → o token novo está gravado, o e-mail não saiu, o token antigo morreu, e o usuário recebe 500. Ele perde o link que tinha **e** não recebe o novo. É a ordem invertida: gravar depois de enviar, ou não invalidar o antigo até o novo sair. Não mexi. É outro endpoint, outro público, e `/autenticacao/migrar-senhas` já é assunto delicado o suficiente neste projeto (D78) para que uma mudança ali não entre de carona num conserto de SAC. **Também medido, e sem dono:** dois templates de mailer estão órfãos — `cliente-novo.phtml` e `cliente-aniversario.phtml`. Nenhum dos dois `new Mail(` do sistema os referencia. O `sac.phtml` era o terceiro órfão até hoje. **E uma anotação sobre a resposta de erro:** quando a ação estourava, o `500` saía **sem** o cabeçalho `Access-Control-Allow-Origin`, porque a exceção acontecia antes dos dois `header()` do fim da ação. Para o aplicativo, um 500 sem CORS é uma falha de rede, e não uma resposta de erro. Com o conserto o caminho de sucesso não passa mais por ali; o caminho de exceção continua assim. #### Um teto de taxa que a suíte precisa respeitar Medido no caminho: `/api/clientes/sac` e `/api/clientes/novo` dividem a **mesma** zona de limite no nginx — `escrita_publica`, 10r/m com rajada de 5, por IP (`docker/nginx/default.conf:60,139-148`). A suíte fala de um IP só e hoje gasta 2 dos 6 créditos imediatos. Quem acrescentar casos nessas duas rotas soma no mesmo balde, e o 429 do nginx tem a **mesma forma de snapshot** que o 500 — só muda o número. A guarda nova nomeia esse caso na mensagem de falha. #### Os restos: o reset na ordem certa, o CORS antes do corpo e o e-mail em UTF-8 — CORRIGIDO em 03/10/2026 O item SESSAO-SENHA-EMAIL fechou as três anotações acima que ficaram sem dono. - **O reset gera, envia e só então grava** (`AutenticacaoService::senhaRedefinir`). O token novo nasce na entidade, o e-mail o leva, e só o envio que não lançou o grava. Com o SMTP fora do ar, a exceção sobe como antes (o 500), o banco não muda -- o link que a pessoa já tinha segue valendo -- e a entidade volta ao banco (`refresh`), para nada mais naquela requisição gravar o token que não saiu. O risco da ordem inversa fica, e é menor: o e-mail que saiu e a gravação que falhou dão um link que não abre, e pedir de novo resolve. O `Reply-To` do fornecedor antigo não mudou (está nas decisões). - **O CORS do SAC antes do corpo** (`AplicativoController::sacAction`): o `Access-Control-Allow-Origin: *` é posto na resposta do Laminas no começo da ação, e não mais com o `header()` do fim. O envio que lança chegava antes do fim, e o 500 saía sem ele. ~~a página de erro reaproveita a mesma resposta (`ExceptionStrategy`). O `Content-type: application/json` ficou no fim: no 500 o corpo é HTML, e o cabeçalho de JSON mentiria.~~ (revisão, 04/10/2026: o mecanismo escrito estava errado.) Quem responde o 500 de `/api/clientes/sac` é o `ErroJsonListener` do `ISApi` -- preso ao `dispatch.error` com prioridade 1000 para tudo sob `/api/` (`ISApi\Module::onBootstrap`) --, e não a `ExceptionStrategy`: ele pega a resposta do evento, que é a MESMA que o controller recebeu (o `DispatchListener` passa a da aplicação), põe o 500, o `Content-Type: application/json; charset=utf-8` e um corpo JSON, e para a propagação. É por isso que o CORS posto no começo chega ao aplicativo, e o 500 é JSON, e não HTML. O `Content-type` do `header()` do fim ficou onde estava: é o do caminho que dá certo, e o 500 já sai com o do ouvinte. - **Os e-mails em UTF-8.** `Mail::prepare` declara `charset=UTF-8` na parte HTML (antes não declarava nenhum), e os quatro templates de `mailer/` deixaram o `mb_convert_encoding` para Windows-1252 e o `` -- os dois em uso (`redefinir-senha` e `sac`) e os dois órfãos, para o dia em que alguém os ligar. O emoji do cliente chega como foi escrito. De passagem, o nome no "Olá" do reset passou a ser escapado, como os campos do SAC (o corpo é HTML). A transferência continua `8bit`, como era. **Provado:** `EmailsDoSistemaTest`, 6 casos verdes nos dois bancos, com SMTP dublê (nenhum e-mail sai): o dublê que guarda lê o banco NO MOMENTO do envio -- ainda o link antigo -- e depois o banco tem o token que o e-mail levou; o que lança deixa o banco e a entidade com o link antigo, e um `flush` depois não grava nada; os bytes da mensagem como iria pela rede (`toString()`) trazem `c3 a7 c3 a3` em "solicitação" e no nome, nenhum `e7 e3`, e a parte declara `charset="UTF-8"` (o cabeçalho vai dobrado no fio); o nome com `` vai escapado; o SAC leva `f0 9f 98 a1` (o emoji) e o acento em UTF-8; e o SAC despachado com o SMTP que lança sobe a exceção com o CORS já na resposta. **No Mailpit, pelos bytes:** um reset de verdade, por HTTP, ao colaborador de fixture (`colab@teste.invalid`), nos bancos de contrato MySQL e PostgreSQL -- a parte diz `charset=UTF-8` (transferência `8bit`), o `` diz `utf-8`, "solicitação" chega como `73 6f 6c 69 63 69 74 61 c3 a7 c3 a3 6f`, nenhum byte de Windows-1252, o corpo inteiro é UTF-8 válido, e o HTML que o Mailpit decodifica traz o texto certo; a caixa e o token do link voltaram ao que eram. O SAC não foi ao Mailpit: o destino dele é um endereço de verdade. Mutantes, um de cada vez, vermelhos: gravar antes de enviar (os dois do reset); sem o `refresh` (o do SMTP que lança); o CORS de volta ao fim (o do SAC que falha); o `Mail` sem o charset (os dois de UTF-8); o texto do reset, o `` e a mensagem do SAC de volta a Windows-1252 (cada um o seu); o nome sem escape (o dele). **A revisão (04/10/2026):** o caso do SAC que falha despachava só o controller, e não passava por quem responde o 500. Entrou `testOSacQueFalhaChegaAoAplicativoEmJsonComOCors`: a exceção passa pelo `dispatch.error` da aplicação montada, como o `DispatchListener` faz, e o 500 sai do `ErroJsonListener` na mesma resposta que o controller recebeu -- JSON, com o `Content-Type` do ouvinte e o CORS. Verde nos dois bancos; vermelho, nos dois, com o CORS de volta ao fim (junto com o caso antigo) e com o ouvinte montando uma resposta nova (só ele: o caso antigo não via o ouvinte). O 500 do SAC continua sem ter sido visto por HTTP: provocá-lo pede o SMTP fora do ar no servidor local, e o destino do SAC é um endereço de verdade. **O que fica:** o SMTP caído continua virando 500 no reset e no SAC, como a primeira das "três coisas que ficaram de fora" acima; e o envio continua síncrono (a terceira). --- ### D173 — O cenário de fixtures não podia ser recarregado, e dois testes eram verdes por ausência de dado — CORRIGIDOS em 12/09/2026 — PARCIAL, lido em 05/10/2026 — CORRIGIDO em 05/10/2026 > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito como fechado, e o corpo diz que ele está parcial: uma parte está consertada, e a outra não. Falta: `BuscaDeLogradouroTest` depende do dicionário de endereços curto e falha contra o real; o conserto provável é buscar termo que só a rua do cenário case. > **05/10/2026, depois da nota:** consertado e provado contra o dicionário real (a seção "O conserto do achado 3", no fim deste débito). E o sexto vermelho do achado 3, o do `BuscaDeClienteComAcentoTest`, que a primeira versão do conserto deixava de fora, consertado na verificação do mesmo dia (a mesma seção). Os três achados desta entrada saíram do **mesmo ato**: recarregar o cenário no banco local para poder medir o que os testes de relatório precisavam. Nenhum deles aparece no CI, e é isso que os une. #### 1. O `fixtures.sql` carregava UMA vez, e abortava na segunda A guarda do **D122** acusou primeiro: *"O cenario deste banco esta defasado"*. Ao recarregar, a carga parou em ERROR 1062 (23000) at line 1183: Duplicate entry '90001000' for key 'estados.PRIMARY' **Medido:** o arquivo **INSERE em 42 tabelas** e a limpeza do topo conhecia **23**. Das 19 que sobravam, nove morrem por `CASCADE` de um pai que a limpeza já apaga — conferido em `REFERENTIAL_CONSTRAINTS.DELETE_RULE`, e não suposto — e **dez não morrem**: | tabela | como falhava | |---|---| | `estados`, `cidades`, `bairros`, `logradouros` | sem pai apagado: o `INSERT` repetido bate em chave duplicada | | `saidas_tipos`, `vipclass` | idem, por caminhos próprios | | `clientes_debitos` | aponta para `vendas`, `clientes` e `unidades` com `NO ACTION` — não quebra no próprio `INSERT`, **bloqueia** o `DELETE` de `vendas` | | `nps_resultados_unidades`, `unidades_socios` | bloqueiam o `DELETE` de `unidades` | | `pacotes_itens` | bloqueia o `DELETE` de `produtos` | **POR QUE ISSO NUNCA APARECEU NO CI, e é a parte que importa:** lá o banco **nasce vazio** a cada execução, então um arquivo que carrega uma vez é indistinguível de um que carrega sempre. Quem paga é quem tem banco local — e o preço não é um erro na tela: a carga **aborta no meio**, deixando o cenário pela metade, que é a mesma falha que um comentário do próprio arquivo já descrevia vinte linhas acima da limpeza. Corrigido com as dez exclusões faltantes, em ordem de filho antes de pai. **Provado por execução: duas cargas seguidas, sem erro.** #### 2. `PrivilegioApiTest` afirmava a tabela INTEIRA vazia Com o cenário recarregado, foi a única das 439 a cair. A linha era self::assertSame([], $this->em->getRepository(Privilegio::class)->findAll()); **Medido:** `privilegios` tem **139 linhas**, ids de 2 a 180, **todas da cópia anonimizada** e nenhuma do cenário. A afirmação é verdadeira no CI, onde o banco nasce de `mysql.sql` mais as fixtures e mais nada, e **falsa em qualquer banco com a cópia carregada**. O teste passava **pelo motivo errado** — pela tabela estar vazia, e não por o cenário não criar molde de grupo. *Verde por ausência de dado.* Escopado à faixa 9000xxxx, e falsificado: com o limiar em 0 a conta volta a ver as 139. #### 3. `BuscaDeLogradouroTest` passa no MySQL porque o dicionário local está vazio Este **fica em aberto**, e é o mais interessante dos três. Rodando a caracterização contra o `franquiabv_dev` do PostgreSQL — que tem a cópia —, cinco casos dele e um do `BuscaDeClienteComAcentoTest` ficam vermelhos. **Não é regressão:** os dois bancos locais carregam dicionários de endereço diferentes. | tabela | MySQL | PostgreSQL | |---|---:|---:| | `logradouros` | **5** | **709.442** | | `bairros` | 4 | 38.778 | | `cidades` | 4 | 10.054 | | `estados` | 4 | 28 | | `clientes` | 242.597 | 242.597 | | `vendas` | 2.269.221 | 2.269.221 | Tudo bate **menos** as quatro tabelas de endereço. E o método que o teste exercita termina em `ORDER BY e.nome, c.nome, b.nome, l.nome` com **`setMaxResults(10)`** — então, com o dicionário de verdade, a rua do cenário cai fora dos dez primeiros, porque o estado dela se chama `ESTADO CARACTERIZACAO` e vem depois de Acre e Alagoas. **Onde isso deixa o teste:** ele passa no CI (dicionário com 2 ruas), passa no MySQL local (dicionário com 5) e falha contra o dicionário real — que é a condição de produção, com 16.203 ruas segundo o docblock do próprio arquivo. Ele guarda o `LOWER()` do **D120**, que é uma guarda que vale; o que não vale é depender de a lista ser curta. **A correção não foi feita aqui de propósito:** mexer nos cinco casos de um teste que guarda o D120 merece mudança própria, e nenhum caminho que o projeto de fato executa está vermelho hoje. O conserto provável é buscar por um termo que só a rua do cenário case, em vez de um que a cópia case milhares de vezes. #### O conserto do achado 3 — CORRIGIDO em 05/10/2026 **Medido antes, no `franquiabv_dev` do PostgreSQL, só leitura e só contagem:** 709.440 ruas; "presidente" casa 2.520; o nome inteiro, "presidente vargas", **237** — e **37** delas em estados que vêm antes do "ESTADO CARACTERIZACAO" (são oito). Então o termo "que só a rua do cenário case" não existia: "AVENIDA PRESIDENTE VARGAS" é nome de rua de verdade, e nenhum pedaço dele é só do cenário. "caracteriza" casa **zero**. **O conserto, nos dois lados:** | | | |---|---| | `tests/Caracterizacao/fixtures.sql` | as duas ruas passam a terminar em "DA CARACTERIZACAO" — "AVENIDA PRESIDENTE VARGAS DA CARACTERIZACAO" e "RUA SÃO JOÃO DA CARACTERIZACAO", em maiúsculas como os Correios escrevem; o bloco diz por quê | | `BuscaDeLogradouroTest` | cada termo carrega esse final ("presidente vargas da caracteriza", "são joão da caracteriza", "sao joao da caracteriza"); a caixa e o acento continuam medidos como antes — é a guarda do `LOWER()` do D120, que segue sendo o que o arquivo guarda | | `testODicionarioLongoNaoTiraARuaDoCenarioDaResposta` | caso novo: dentro da transação, um estado "ACRE ..." com onze ruas de cada nome de antes; o controle exige que, com os termos de antes, a rua do cenário SAIA das dez, e com os de agora a resposta seja ela e só ela | **Provado contra o dicionário real**, que era a condição que faltava: num banco PostgreSQL descartável (schema, fixtures de hoje e as quatro tabelas de endereço do `franquiabv_dev` — só as linhas reais, lidas por `COPY (SELECT ...)` —, apagado no fim), os oito casos verdes; e com "presidente" de volta no lugar do termo novo, cinco ficam vermelhos — os três de caixa, o do endereço inteiro e o do dicionário longo —, o sintoma que este registro media. **Falsificado no banco de teste**, um mutante por vez e restaurado byte a byte: sem o `LOWER()` da consulta, seis casos vermelhos no PostgreSQL (os quatro de caixa e de acento, o do endereço inteiro e o do dicionário longo) e nenhum no MySQL, cuja collation ignora caixa — o mesmo de antes, e o arquivo o diz; com o termo de antes, o caso do dicionário longo vermelho nos dois bancos. **O sexto vermelho, consertado na verificação do mesmo dia.** A primeira versão desta seção o deixava de fora ("não foi remedido aqui") e o atribuía ao `ClienteRepository::autoComplite`. Errado nas duas coisas: o achado 3 conta "cinco casos dele e um do `BuscaDeClienteComAcentoTest`", e o caso é `testSemOAcentoSoOMysqlAcha`, que no PostgreSQL afirmava **zero** num `SELECT COUNT(*) FROM clientes WHERE tags LIKE '%jose%'` — a tabela inteira, e não o `autoComplite`. Medido no `franquiabv_dev` do PostgreSQL, só a contagem: **3.576**. É o "verde por ausência de dado" do título, e com o avesso junto: o caso da coluna normalizada passaria contra a cópia sem normalizar nada, achado pelos 3.576. | | | |---|---| | `BuscaDeClienteComAcentoTest::quantos()` | conta só o cliente acentuado do cenário (`id = 90001030`); os quatro casos que a usam afirmam 1 ou 0, e não "pelo menos 1" | | `testUmJoseSemAcentoDeOutroClienteNaoMudaOQueSeAfirmaDoCenario` | caso novo: dentro da transação, um cliente de outra unidade com "jose" sem acento, como a cópia tem aos milhares; o controle exige que a tabela inteira o veja, e o caso continua dizendo do cenário o mesmo de antes | **Falsificado** nos dois bancos, um mutante por vez e restaurado byte a byte: com a conta de volta na tabela inteira, o caso novo fica vermelho no MySQL (2 onde afirma 1) e no PostgreSQL (1 onde afirma 0). Os dois casos do arquivo que passam pelo `autoComplite` não dependem disso: ele parte o termo em palavras, e no `franquiabv_dev` do PostgreSQL nenhum cliente fora da faixa do cenário tem "jose" (com ou sem acento) e "acentuado" juntos — contado em 05/10/2026, só a contagem: zero. --- ### D174 — O contrato congelado descreve `data_venda` como texto, e a produção sempre manda nulo — ANOTADO em 12/09/2026 Achado ao acrescentar duas indicações ao cenário para poder testar os contadores do relatório de indicações. A suíte de contrato ficou vermelha: O contrato do endpoint 'indicacoes-listar-autenticado' mudou. - "data_venda": "string", + "data_venda": "null", **A guarda funcionou, e o que ela revelou foi o contrário do esperado: quem estava errado era o instantâneo.** #### A medição | | | |---|---:| | indicações na cópia de produção (fora do cenário) | 6 | | … com `data_venda` **nula** | **6** | | … com `data_adesao` nula | 4 | **Todas.** Em produção, `data_venda` é nula em 100% das indicações desta base — a coluna só é preenchida quando a indicação vira venda, e nenhuma virou. O contrato diz `"string"` porque o cenário de fixtures tinha **uma** indicação, completa e artificial, com as três datas preenchidas. O aplicativo instalado, portanto, **sempre recebeu `null` ali** — e o contrato, que existe para congelar o que ele recebe, descrevia outra coisa. É o mesmo *verde por ausência de dado* que apareceu três vezes em 12/09/2026, agora na camada que protege o parque instalado. #### E há uma limitação de mecanismo por baixo `ContratoTestCase::estrutura()` reduz uma lista à estrutura do **primeiro item** — *"já que todos os itens de uma lista devem ter o mesmo formato"*. Para campo anulável isso não vale: o tipo gravado depende de qual linha vier primeiro, e o mesmo endpoint congela `"string"` ou `"null"` conforme a ordenação e o cenário. O formato não sabe dizer `string|null`. Então **qualquer** valor congelado para `data_venda` estará errado em alguma linha. Não é o instantâneo que está mal preenchido: é o vocabulário que não tem a palavra. #### O que foi feito, e o que NÃO foi As duas indicações novas foram penduradas noutro cliente (90001020), fora do endpoint congelado — o contrato voltou ao verde **sem ser alterado**. Virar um contrato congelado é decisão de quem opera, e a própria mensagem da guarda diz por quê: *"confirme antes que TODAS as versões do aplicativo em uso continuam funcionando — inclusive as antigas"*. **Três saídas, e a escolha é sua:** 1. **Atualizar o instantâneo** para `"null"`. É o que a produção manda hoje em 100% dos casos, e portanto o mais fiel. Risco: se uma indicação virar venda, o campo volta a ser texto e a guarda acusa de novo — pelo motivo certo, mas acusa. 2. **Ensinar o contrato a dizer `string|null`**, varrendo a lista inteira em vez de olhar o primeiro item. É a correção de raiz, e alcança **todo** campo anulável de **todos** os 67 instantâneos — provavelmente mais de um mudaria. 3. **Deixar como está**, sabendo que este campo do contrato descreve um caso que a produção não produz. A segunda é a que resolve a classe inteira, e é também a que mexe em mais coisa de uma vez. ### D175 — A ordem alfabética de uma lista muda entre os dois bancos, e não é por acento — ANOTADO em 12/09/2026 Encontrado por acidente, escrevendo um teste: `ComboDeConveniosNoRelatorioTest` afirmava que a ordem devolvida pelo `ORDER BY con.nome` era igual à de `sort()` do PHP. Ficou vermelho, e o vermelho não era do método — era da colação. Seguir o fio levou a comparar os **mesmos dados nos dois bancos locais**, ordenados pela mesma consulta: ```sql SELECT nome FROM convenios WHERE status = true ORDER BY nome; -- 616 linhas ``` | | | |---|---:| | linhas ordenadas | **616** nos dois | | posições que trazem nome **diferente** | **376** | | nomes fora de lugar | **32** | **E a causa não é acento — é espaço e pontuação.** O D119 já descreve a colação de *busca*: `utf8mb4_general_ci` ignora caixa e acento, e o PostgreSQL compara byte a byte no `LIKE`. Este débito é sobre *ordenação*, que é outro eixo, e ali o PostgreSQL **não** compara byte a byte: ele usa a colação do locale, que ignora espaço e hífen no primeiro nível de comparação. Medido nas duas primeiras linhas da lista: | | MySQL | PostgreSQL | |---|---|---| | 1ª | `" ATIVA PLAY FITNESS"` (começa com espaço) | `"360 crédito"` | | 2ª | `" Itapiruba Esporte Clube"` (idem) | `"AAAD-UFPR"` | Dois convênios têm nome **começando com espaço**. O MySQL trata o espaço como caractere e os põe à frente de tudo; o PostgreSQL o descarta e os arquiva sob A e sob I. O mesmo acontece com o hífen em `"ADEPOL - Delegados da Policia Civil"` e `"ARC TOUCH"`. **O tamanho disto não é o combo de convênios.** Toda lista ordenada por nome muda de ordem: combos de unidade, de grupo, de produto, de colaborador, listagens de relatório, e o que o aplicativo recebe em ordem. Nenhum número muda — a mesma linha está lá —, mas a **posição** muda, e há telas paginadas: quem procura na página 1 pode passar a achar na 2, que é a forma do defeito já visto no VipClass. **Por que fica anotado e não corrigido agora:** são três caminhos, e a escolha é de quem opera. 1. **Criar as colunas com uma colação que imite o MySQL** (`ICU`, com o nível de pontuação configurado para não ser ignorado). Resolve na raiz e muda o esquema. 2. **Normalizar os dados** — tirar espaço das pontas de `convenios.nome` e dos outros nomes. Conserta estes 32 casos e não a regra; e é alteração de dado de produção, que por decisão do dono só acontece na migração final. 3. **Deixar como está**, sabendo que as listas saem em ordem um pouco diferente no dia do corte. **O que já está garantido:** nenhum teste desta suíte afirma a ordem inteira de uma lista; os que medem `ORDER BY` afirmam a **posição relativa de dois nomes conhecidos**, que é igual nos dois motores. Sem isso, a migração teria ganhado uma fileira de vermelhos que não eram defeito. ### D176 — A consolidação de NPS divide por zero se a primeira pesquisa do mês não tiver item — CORRIGIDO em 01/10/2026 `CronJobService::npsContabilizar()` calcula a nota de colaboradores da unidade assim: ```php $totalizadoresColaboradores = $repoNpsColaborador->selecionarTotalizadoresNotasPorUnidadeMesAno(...); $resultadoUnidade->setNotaColaboradores($totalizadoresColaboradores['nota'] / $totalizadoresColaboradores['numeroAvaliacoes']); ``` O divisor vem de um método que devolve **`0` quando não há linha** — é o `!empty($totalizadores['numeroAvaliacoes']) ? ... : 0` que todos os repositórios de NPS usam. No PHP 8, `0 / 0` lança `DivisionByZeroError`. **Quando é alcançável.** O laço de itens, logo acima, persiste uma linha de colaborador para o mês corrente — então depois dele o divisor é ≥ 1. A divisão só encontra zero se **o laço não rodou**, isto é, se a pesquisa não tem nenhum item, e se nenhuma outra linha de colaborador existir para aquela unidade naquele mês. Medido na cópia local em 12/09/2026: **1 pesquisa sem item nenhum** em 37.957. O par (pesquisa sem item) × (primeira do mês para a unidade) não ocorreu ainda. **O que acontece se ocorrer.** O `npsContabilizar` tem `try { } finally { }` e **nenhum `catch`**: a trava de execução é liberada corretamente — isso está certo —, mas o erro sobe e a rotina aborta no meio. As pesquisas já processadas ficam consolidadas, as seguintes não, e a próxima passada tenta de novo a mesma pesquisa sem item e aborta no mesmo lugar. **Fica em laço de falha até alguém olhar.** E a rotina é disparada por URL a cada 10 minutos (ver `f1-6-agendamento.md`), então o sintoma seria "o NPS parou de fechar" sem nada na tela. **Ao resolver:** guardar o divisor, não a divisão — `numeroAvaliacoes` zero significa "não há nota de colaborador neste mês", e o valor correto a gravar é zero, não um erro. Uma linha: ```php $media = empty($tot['numeroAvaliacoes']) ? 0 : $tot['nota'] / $tot['numeroAvaliacoes']; ``` Não foi feito agora porque a migração é de caracterização: a correção muda comportamento num caminho que hoje não é percorrido, e o lugar dela é junto com a revisão das rotinas de cron, não no meio da cobertura de relatórios. O que existe hoje é este registro e a medição que o sustenta. #### CORRIGIDO em 01/10/2026 Guardado o divisor, como esta entrada pedia: `numeroAvaliacoes` zero grava `nota_colaboradores` zero -- o mesmo valor com que `NpsResultadoUnidade` nasce -- e a rotina segue para a pesquisa seguinte; a primeira pesquisa com item do mês recalcula a média. A guarda cobre um caso a mais do que esta entrada descrevia: a consulta filtra pela unidade do COLABORADOR, então uma pesquisa com item cujo colaborador é de outra unidade também chegaria a zero (0 na cópia hoje). **Provado:** `D176NpsSemItemTest` (2 casos, nos dois bancos), chamando `npsContabilizar` pelo serviço, como `CronTravaSimultaneaTest`: a pesquisa sem item, primeira do mês, grava zero, conta 1 pesquisa e sai da fila; com uma nota de colaborador de 8 no mês, a média continua 8. A divisão de antes deixa o primeiro em `DivisionByZeroError`; gravar zero sempre deixa o segundo vermelho (0 contra 8). **Medido de novo na cópia:** a mesma 1 pesquisa sem item em 37.957, já contabilizada -- nenhuma na fila. A rotina rodou só pelo teste, no banco de teste. **O que ficou:** enquanto o mês da unidade só tiver pesquisa sem item, a nota geral é a média das três parcelas com esse zero dentro (`setNotaGeral`). A frequência medida é zero, e mudar a média é regra de negócio, e não este débito. ### D177 — A cobertura era medida por NOME de método, e nome não é método: 179 pares atrás de 140 nomes — MEDIDO E COM PORTÃO em 12/09/2026, e o PORTÃO APERTADO em 15/09/2026, que estava verde casando por substring — PARCIAL, lido em 05/10/2026 — PARCIAL em 08/11/2026: dinheiro e vazamento entre unidades com teste; ficam os outros pares > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito como medido, e o corpo diz que ele está parcial: uma parte está consertada, e a outra não. Falta: cobrir os pares sem menção em teste (64 em 15/09) e os 25 falsos positivos, dinheiro primeiro; `UnidadeRepository::listagemIndex` segue na fila de vazamento. > > **06/10/2026:** a medida passou a ler os testes sem comentários; com isso, 148 pares sem menção e 26 falsos positivos (ver "06/10/2026: os quatro métodos por cliente da agenda cobertos", no fim deste registro). Este débito nasce de um erro de **medição**, não de código. Ele foi aberto no dia em que a lista dos relatórios fechou, porque foi fechando-a que o erro apareceu: o inventário contava **nomes** de método, e um teste que citasse `listagemIndex` fazia `listagemIndex` contar como coberto. `listagemIndex` é **declarado em 19 repositórios**, com 19 corpos diferentes — de 18 a 37 linhas cada, nenhum herdado, todos estendendo direto o `EntityRepository` do Doctrine. `popularCombobox` está em 13. São consultas distintas, com filtros distintos, contadas como uma. #### A medição, e ela foi refeita do zero **Os números desta seção são da PRIMEIRA medição, e ela estava incompleta.** Ficam como estavam porque a contraprova mais adiante os corrige com motivo, e apagá-los esconderia o erro que vale mais que o acerto: o glob pegava 63 controllers e havia **84**. O número final é **178 pares atrás de 139 nomes**. Varrendo os **63 controllers** então visíveis e resolvendo cada chamada de repositório à classe concreta: | | | |---|---:| | nomes de método de repositório chamados por controller | **135** | | **pares (classe, método)** por trás desses nomes | **173** | | nomes que existem em mais de uma classe | 15 | | pares alcançados **só** pela forma de variável (`$r = getRepository(...)`) | 27 | | chamadas que o resolvedor não atribui a uma classe | 6 | E a cobertura, pela unidade certa: | | | |---|---:| | pares cujo método não aparece em **nenhum** teste | **70** | | pares cujo nome aparece em teste e **nunca junto da própria classe** | **20** | | pares com nome e classe no mesmo teste (candidatos a coberto) | 83 | Pela medida antiga o sistema parecia ~83 de 135 coberto. Por par, **90 de 173 (52%) estavam descobertos ou contados errado**. #### Os 20 falsos positivos, nomeados São estes, e a lista está no portão para não crescer em silêncio: `AgendaFechamentoRepository::listagemIndex`, `AppBannerRepository::listagemIndex`, `AreaAtuacaoRepository::popularCombobox`, `ArquivoCategoriaRepository::popularCombobox`, `ArquivoRepository::listagemIndex`, `ConvenioRepository::listagemIndex`, `ConvenioUnidadeRepository::convenioAtivo`, `CupomRepository::listagemIndex`, `EstadoRepository::popularCombobox`, `NotificacaoRepository::listagemIndex`, `PesquisaRepository::selecionarPorIdHash`, `PrivilegioRepository::listagemIndex`, `ProdutoEstoqueRepository::listagemIndex`, `ProdutoRepository::popularCombobox`, `ProdutoTagRepository::listagemIndex`, `ProdutoTagRepository::popularCombobox`, `RoyaltiesFaturaRepository::listagemIndex`, `SorteioRepository::listagemIndex`, `UsuarioComissaoExtraRepository::selecionarPorUsuario`, `VisagismoRepository::listagemIndexRelatorio`. #### O MEDIDOR MENTIU PRIMEIRO, e isso vale mais que o resultado A primeira rodada do resolvedor devolveu **9 pares e 468 chamadas ilegíveis**. 408 delas com o motivo "argumento do getRepository não é reconhecível" — número que, num sistema que roda em produção, acusa o instrumento e não o medido. A causa: **o PHP 8 junta o nome qualificado num único token.** `\ISCadastro\Entity\Cliente` era `T_NS_SEPARATOR` + `T_STRING` no PHP 7 e é `T_NAME_FULLY_QUALIFIED` no 8; o laço procurava um `T_STRING` antes do `::` e não achava nenhum. Corrigido para tratar os quatro tokens de nome, o resultado foi 173 pares e 6 ilegíveis. Por isso o resolvedor **conta o não resolvido à parte e nunca soma como resolvido**. As 6 de hoje foram lidas à mão, e as quatro classes que elas revelaram **já estavam no conjunto** por outro sítio de chamada: o ponto cego é real e está vazio. #### O PORTÃO, e o que ele deliberadamente não afirma `scripts/conferir-cobertura-por-par.php`, ligado ao `conferir-tudo.sh` como o 34º portão. Ele afirma só o que é mecânico: 1. o **conjunto** de pares é o declarado — por contagem **e por sha1**, porque contagem sozinha não pega troca de um par por outro; 2. a contagem de chamadas por módulo é a declarada — para um módulo não perder chamada enquanto outro ganha; 3. o número de pares sem teste nenhum é **exatamente** o declarado; 4. a lista dos 20 falsos positivos não cresce. Ele **não** afirma que os 83 restantes estão cobertos: "nome e classe no mesmo arquivo" é positivo fraco, e dizer o contrário repetiria o erro que o portão existe para impedir. **E o item 3 foi corrigido no próprio dia.** A primeira versão comparava com `>`, para não ficar vermelha quando alguém melhorasse a cobertura. Parecia gentil e era erro: ao fechar o primeiro vão, o número caiu de 70 para 69 e **o portão continuou verde**. Com igualdade exata, fechar um vão obriga a descer a base no mesmo commit — e foi o que aconteceu, medido: o portão ficou vermelho pedindo isso. #### QUATRO VÃOS FECHADOS, e os quatro movem dinheiro O critério da casa: dinheiro primeiro. | par | arquivo | o que ele decide | |---|---|---| | `VendaPagamentoRepository::totalPagamento` | `TotalDoPagamentoDaVendaTest` | quanto de crédito do cliente o sistema **debita** — `setValor(getValor() - $creditoUsado)` | | `ClienteDebitoRepository::selecionarValorDebitoCliente` | `ValorDoDebitoDoClienteTest` | quanto o cliente deve | | `ClienteDebitoRepository::selecionarValorDebitosCliente` | o mesmo arquivo | idem — são **gêmeos** | | `CaixaRetiradaRepository::selecionarRetiradasPorCaixa` | `RetiradasDoCaixaTest` | a sangria que entra no fechamento do caixa | De 70 para **66**. Cada caso foi falsificado: neutralizar o filtro medido deixa vermelhos exatamente os casos que dependem dele. ##### Os gêmeos são duplicata, e a diferença entre eles é o eixo da migração `selecionarValorDebitoCliente` e `selecionarValorDebitosCliente` estão lado a lado no mesmo arquivo, com nomes a **uma letra** de distância, e fazem a mesma coisa. A única diferença: ``` singular " WHERE deb.status = :status AND ..." parâmetro, com true plural " WHERE deb.status = true AND ..." literal dentro da DQL ``` É a família do D81/D97 — e a forma literal é justamente a que escapa do portão do D81, que confere valor ligado a parâmetro. Eles são chamados de telas diferentes, e quem consertar um não saberia que o outro existe. O primeiro caso do teste chama os dois e exige o **mesmo número**, em três combinações de argumento; falsificado trocando o literal do plural para `false`, ele fica vermelho. ##### E um caso meu prometia mais do que provava O teste de `totalPagamento` foi escrito afirmando que uma segunda linha da mesma forma de pagamento exercitava o `GROUP BY vp.formaPagamento`. **Não exercitava.** Apagando o `GROUP BY` do repositório, os cinco casos continuam verdes — com ele a consulta devolve uma linha por forma e o PHP as soma, sem ele devolve uma linha já somada, e o resultado é o mesmo sempre. O docblock foi corrigido para dizer o que o caso prova — que as duas linhas contam, e contam uma vez só — e para registrar que o `GROUP BY` é **redundante**, medido. Teste que parece provar mais do que prova é pior que teste ausente: ele convence. #### O ESCOPO, e a consequência dele "Chamado por controller" é o critério herdado do D10: a superfície que o usuário alcança. Método chamado só por serviço, cron, view `.phtml` ou outro repositório **não** entra na conta. Isso não é descuido, e a consequência é real — foi assim que `NpsItemRepository::selecionarTotalizadoresPorColaboradorMesAno` entrou na lista dos relatórios sendo chamado apenas pelo `CronJobService`. #### A CONTRAPROVA: a mesma coisa medida de outro jeito, e as duas estavam erradas Enquanto o portão era escrito, 13 agentes resolveram os mesmos pares **lendo o código** e julgaram cada um **lendo os testes**. Duas medições independentes da mesma coisa, para que a divergência aponte o erro. Apontou três, e dois eram meus. ##### Sobre o CONJUNTO de pares: meu resolvedor era subconjunto estrito do deles | | | |---|---:| | meu, mecânico | 173 | | deles | 228 | | dos quais método do **Doctrine** (`find`, `findBy`, `findOneBy`…) | 48 | | código do projeto | 180 | | pares só no meu | **0** | | pares só no deles | **7** | **Zero pares só no meu lado**: o resolvedor mecânico não inventou nenhum. E dos 7 só deles, cinco eram meus erros e dois eram deles: | par | veredito | |---|---| | `AgendaRepository::selecionarHorariosFilhos` | **meu erro** | | `AgendaRepository::selecionarPorColaboradorDataHora` | **meu erro** | | `AgendaRepository::selecionarPorUnidadeData` | **meu erro** | | `FormaPagamentoRepository::popularCombobox` | **meu erro** | | `VendaRepository::selecionarComandasAbertas` | **meu erro** | | `LogradouroRepository::buscarEndereco` | erro deles — chamador é um **Service**, fora do escopo declarado | | `VendaProdutoRepository::pesquisaNpsLocalizarCliente` | erro deles — e **virou o D178**: o método não existe | **MEU ERRO ERA UM GLOB.** `Controller/*Controller.php` pega 63 arquivos e deixa **21** de fora: 18 em `Controller/Adm/` e 3 em `Controller/V4/`. Um quarto da superfície de controllers, perdido por um asterisco. Corrigido, o portão foi de 173 para **178 pares** — exatamente os cinco, e nenhum saiu. 180 deles menos os 2 indevidos dá 178: **a aritmética fecha nos dois lados.** ##### Sobre a COBERTURA: eles estavam certos, e o limite é estrutural do meu método Cruzando meu balde mecânico com o veredito deles, par a par: | meu balde | veredito deles | pares | |---|---|---:| | candidato (nome **e** classe no teste) | coberto | 74 | | candidato | **descoberto** | 19 | | sem menção do nome | coberto | **16** | | sem menção | descoberto | 47 | | só o nome, sem a classe | coberto | 1 | | só o nome | descoberto | 19 | Os **16 "sem menção mas coberto"** pareciam erro deles, e não eram. A evidência que devolveram é específica e foi conferida: - `UnidadeRepository::paisesSelecionar` — `tests/Contrato/AplicativoApiTest.php::testPaisesSelecionar` faz `GET /api/paises/selecionar`, e `AplicativoController::paisesSelecionarAction:467` chama o método. **Conferido linha por linha.** - `PontuacaoHistoricoRepository::selecionarPontuacaoValidadePorClienteUnidade` — o nome não aparece em teste nenhum, e `FidelidadePontuacaoTest` chama `ClienteService::atualizarPontuacao()`, que o chama em `ClienteService.php:318`. **Conferido.** Ou seja: **a cobertura pode ser INDIRETA** — por rota HTTP no contrato, ou por um serviço no meio —, e casamento de substring é estruturalmente cego a isso. Não é um parâmetro a ajustar; é o que o método não alcança. **Por isso o `SEM_MENCAO_ESPERADA` do portão não significa "descoberto".** Ele significa o que a constante diz: o nome do método não aparece em nenhum `.php` de teste. É sinal mecânico, serve para pegar regressão, e **16 dos 64 de hoje estão exercitados por caminho indireto**. Dizer 64 descobertos seria exatamente o tipo de número que não vale. ##### E duas armadilhas da própria contraprova, ditas porque custaram tempo **A primeira foi minha.** O script do fan-out pedia o nome da classe aos resolvedores como *nome do arquivo* e aos juízes de outro jeito; na junção, **zero** dos 225 vereditos casou, e o resultado voltou com "0 cobertos, 0 descobertos". Recuperei tudo do diário do run e refiz a junção normalizando a chave — nome base, sem `.php` —, e **225 de 228 casaram**. O dado estava lá; a junção era o defeito. A crítica final do fan-out, que foi alimentada com a lista vazia, concluiu que o risco de falso negativo era "zero por construção": essa conclusão é artefato do meu erro e foi descartada. As **medições** dela, não — foram conferidas uma a uma. **A segunda é de tempo.** O fan-out leu `tests/` como estava **uma hora antes**, e por isso julgou descobertos quatro pares que eu cobri nesse intervalo (`selecionarRetiradasPorCaixa`, os dois gêmeos do débito e `apagarVendaTemporaria`). São 4 dos 19 "candidato mas descoberto" — sobram 15 discordâncias reais. Medição assíncrona tem data, e a data entra no resultado. ##### O que a crítica do fan-out acrescentou, conferido Cinco afirmações, todas medidas antes de entrar aqui: | afirmação | medido | |---|---| | as views `.phtml` seriam um vão | **0 de 171** usam `getRepository` — vão **vazio** | | "coberto por teste de rota" dentro da caracterização | **0 de 93** arquivos chamam `dispatch(` — os testes de rota estão no **contrato** | | o cron é invisível a este escopo | `CronJobController` tem **0** `getRepository`; as 24 rotinas moram no Service | | `relatorioFranquias` é homônimo **e** dinheiro | **confirmado**: `RoyaltiesRepository:45` e `VendaPagamentoRepository:97`, mesma assinatura `($request, $unidadeId)` | | `popularComboboxAgenda` decide quais unidades a agenda oferece | chamado **só** de `Form/AgendaIndex.php:18` — fora do escopo, e é a própria superfície do recorte | As duas primeiras **poupam trabalho**: são vãos que o escopo nomeia e que estão vazios. As três últimas são fila, e a terceira explica por que `NpsItemRepository::selecionarTotalizadoresPorColaboradorMesAno` enganou o inventário dos relatórios. #### Ao resolver Os **64** restantes são trabalho sem decisão pendente, e a ordem é a do critério: dinheiro, depois vazamento entre unidades, depois o resto. Entre os que sobram com cara de dinheiro: `VendaRepository::extratoCreditoCliente`, `SaidaParcelaPagamentoRepository::selecionarPagamentosPorSaida`, `VendaRepository::selecionarVendasPorConvenio` e `PontuacaoHistoricoRepository::selecionarPontuacaoValidadePorClienteUnidade`. E os **20 falsos positivos** são mais baratos do que parecem: metade é `listagemIndex` de tela de administração, e nove das 19 `listagemIndex` não filtram unidade — **conferido, e nenhuma das nove tem coluna de unidade na tabela**, então são globais por esquema e não por omissão. A décima, `ProdutoEstoqueRepository`, recorta pelo produto, e o chamador valida a unidade do produto antes de chamar. #### O portão estava VERDE e mentindo — apertado em 15/09/2026 Ele casava por `strpos` em três lugares, e substring credita cobertura que não existe. A tese deste débito é *"nome não é método"*; faltava dizer **"prefixo não é nome"** e **"o nome de uma classe não atesta outra"**. **Primeira forma — o prefixo credita o nome.** Dois pares eram dados por mencionados sem que o método aparecesse em teste nenhum: | par | quem o creditava | é | |---|---|---| | `UnidadeRepository::selecionarUnidades` | `selecionarUnidadesRelatorioNps` (4×), `selecionarUnidadesRelatorioFranquias` (4×), `selecionarUnidadesAtivas` | outros **três métodos** da mesma classe | | `ProdutoRepository::pesquisar` | `pesquisarcep` (7×), `pesquisarQuantidade`, `pesquisarCreditoDebitoConvenioAction` | idem | Conferido à mão: nenhum dos dois aparece como identificador inteiro em `tests/`. **Segunda forma — uma classe atesta outra.** `listagemIndex` aparece inteiro em exatamente três arquivos (`ClienteApiTest`, `DevedorTest`, `SaidaFinanceiroTest`), e em **nenhum** deles `Usuario`, `Unidade`, `Grupo` ou `Pesquisa` aparece como identificador — o que os creditava eram tokens como `testAListagemNaoAtravessaAUnidade` e `getUsuario`. Cinco pares saíam por essa porta, e **é o erro deste próprio débito um nível acima**: a evidência de uma classe atestando outra. **E as duas folgas se compõem.** Medido pelas mutações: revertendo só a classe, ou só o método, saem os mesmos **três** (`UnidadeRepository::listagemIndex`, `UsuarioRepository::listagemIndex`, `UsuarioRepository::popularCombobox`). Os outros dois — `GrupoRepository::listagemIndex` e `PesquisaRepository::listagemIndex` — só são creditados quando **as duas** afrouxam juntas: o método frouxo traz arquivos a mais para a lista, e a classe frouxa acha o nome dentro deles. | | antes | depois | |---|---:|---:| | pares chamados por controller | 179 | 179 | | sem menção em teste nenhum | 62 | **64** | | nome sem a própria classe | 21 | **26** | **A subida de 62 para 64 não é regressão.** Nenhum teste foi apagado: o instrumento parou de mentir. Está escrito assim no docblock da constante, para que a próxima pessoa não leia o número como perda de cobertura. #### A catraca que faltava, e o argumento já estava escrito ao lado `FALSOS_POSITIVOS` era comparada só numa direção — `array_diff($soNome, FALSOS_POSITIVOS)` —, então detectava crescer e nunca encolher. Cobrir um dos 26 deixava o portão **verde com a lista desatualizada**, e a regressão futura de volta para 26 ficava invisível. É palavra por palavra o defeito que este mesmo débito conta ter corrigido na constante irmã (`SEM_MENCAO_ESPERADA`, que ganhou as duas direções): *"uma linha de base que só olha para cima protege menos do que diz"*. O argumento estava escrito a trinta linhas de distância e não tinha sido aplicado aqui. Entrou também `'ISBase' => 0` em `CHAMADAS_POR_MODULO`: o módulo tem três controllers e zero `getRepository` hoje, e sem o zero declarado ele não aparece no `foreach` — uma chamada nova ali cairia no total sem dono, e a conta por módulo continuaria fechando. #### O "16 de cobertura indireta" é de 12/09, e não é contagem de hoje A leitura par a par daquele dia achou **16 dos 64 de então** exercitados por caminho indireto. Aquela lista desceu para 62 com os testes do D178/D179/D184 e voltou a 64 agora **por outro motivo**. São 64 pares diferentes. O portão passou a imprimir a data e a ressalva em vez do número seco: vale como argumento — a cobertura indireta existe e este método é cego a ela —, não como contagem corrente. Refazer a leitura é trabalho deste registro, não do portão. #### A falsificação: seis mutações, seis vermelhos Cada arquivo restaurado byte a byte, com sha1 e `git status --porcelain` vazio conferidos depois de cada uma. | | o que afrouxou | esperado | obtido | |---|---|---|---| | F1 | só a classe volta a `strpos` | vermelho | 1 — 26 → **23** | | F2 | só o método volta a `strpos` | vermelho | 1 — 64 → **62** e 26 → 23 | | F2b | as duas juntas (o código de ontem) | os números de ontem | 1 — **62 e 21**, exatos | | F3 | um teste "cobre" `UnidadeRepository::listagemIndex` sem cobrir nada | vermelho pela catraca nova | 1 — *"a lista desceu de 26 para 25"*; **e com a catraca removida, VERDE** | | F4 | `RetiradasDoCaixaTest.php` renomeado | vermelho pela asserção antiga | 1 — 64 → **65** | | F5 | uma chamada trocada num controller | vermelho pelo sha1 | 1 — sha1 e contagem, as duas | **O F3 é o que prova a catraca**, e prova nos dois sentidos: mesma entrada, vermelho com ela e **verde sem ela** — o verde imprimindo *"25 (base 26)"* e saindo com 0. O defeito em uma linha. O F4 existe para provar que o aperto **não quebrou o que já protegia**: a asserção de 12/09 continua pegando teste que some. #### O que continua aberto Os **64 pares sem menção** e os **26 falsos positivos**. A ordem é a da casa — dinheiro, depois vazamento entre unidades, depois o resto. Os candidatos de dinheiro que sobram já estão nomeados acima nesta entrada: `SaidaParcelaPagamentoRepository::selecionarPagamentosPorSaida`, `VendaRepository::selecionarVendasPorConvenio`, `PontuacaoHistoricoRepository::selecionarPontuacaoValidadePorClienteUnidade` e `CupomRepository::selecionarCuponsGerados`. E o aperto **acrescentou dois à fila de vazamento entre unidades**: `UnidadeRepository::listagemIndex` e `UsuarioRepository::listagemIndex` — que até ontem pareciam cobertos e não estavam. #### 28/09/2026: o F3 aconteceu de verdade, por um teste legítimo A fatia dos convênios trouxe `ConvenioUnidadesTest`, que chama `getRepository(Convenio::class)->listagemIndex` — e isso tirou `ConvenioRepository::listagemIndex` dos falsos positivos com razão (28 → 27) — e também `getRepository(Unidade::class)->popularCombobox`. Medido por arquivo, `Unidade` e `listagemIndex` apareciam juntos, e `UnidadeRepository::listagemIndex` saía da lista **sem cobertura nenhuma**: é o F3 desta entrada, desta vez sem ninguém fabricar. A catraca ficou vermelha, como devia — e a mensagem dela ("isso é BOM, o par ganhou teste") estava certa para um dos dois e errada para o outro. O portão ganhou `COINCIDENCIAS` (par ⇒ arquivo ⇒ motivo): o arquivo listado não conta para aquele par, só para ele, e a lista tem catraca própria — se a coincidência sumir do arquivo, vermelho pedindo para tirá-la. Falsificado em cópia: sem a entrada, 27 → 26 e vermelho; com uma entrada inventada, "a coincidência sumiu" e vermelho; sem o `continue` que a pula, 26 e vermelho. Os pares foram de 288 para 293, os cinco dos convênios, todos com teste. `UnidadeRepository::listagemIndex` continua na fila de vazamento entre unidades. #### 04/10/2026: `UsuarioRepository::popularCombobox` coberto (a revisão do USUARIOS-F0) O `UsuarioApiTest` passou a perguntar a lista de colaboradores da agenda (`getRepository(Usuario::class)->popularCombobox(null, $unidade, 'todos', true)`) para os quatro valores de `visivel_agenda`, o fora da lista e os dois estados, contra a API e a grade (a revisão do D345). O par saiu dos falsos positivos (26 → 25) **coberto de verdade**, e as duas coincidências dele (`UsuarioAtivacaoTest` e `ProfissionalParceiroTest`) saíram de `COINCIDENCIAS`: a medida para no primeiro arquivo que cobre o par, e a catraca pediu para tirá-las. Os pares foram de 314 para 317 -- os três novos de `UsuarioRepository` da revisão do D349, todos com teste que chama a própria classe. #### 05/10/2026: as duas listas da tela de serviços cobertas (o D202) `D202EdicaoPelaRotaNoErpTest` monta o formulário de editar serviço como o controller, com `getRepository(AreaAtuacao::class)->popularCombobox()` e `getRepository(ProdutoTag::class)->popularCombobox()`, e a catraca desceu de 25 para 23. **A chamada sozinha não era cobertura**: os dois `select` têm `disable_inarray_validator`, e o caso da edição passaria com a lista vazia. Antes de tirar os pares, o arquivo ganhou `testAsListasDaTelaDeServicoSaoAsAtivas`, que afirma o que as duas trazem — a área e as etiquetas ativas, pelo nome, e não a desativada que o caso cria —; com o filtro de `status` trocado em cada repositório, um mutante por vez, o caso fica vermelho. Os dois saíram de `FALSOS_POSITIVOS` **cobertos de verdade**; os pares continuam 320, e os sem menção, 146. **A metade das áreas não estava presa (revisão de 05/10/2026).** "Não a desativada" só valia para as etiquetas: o caso criava uma etiqueta desativada e nenhuma área, e as duas áreas do cenário (90001000 e 3) são ativas. O mutante "trocado" (`status = false`) esvazia a lista e fica vermelho; o filtro **arrancado** (`WHERE 1 = 1`) deixava a área ativa lá, e a suíte ficava verde — medido, 12 de 12. O caso ganhou a área desativada 90202006 e afirma que ela não entra. Com o filtro arrancado, um mutante por vez e restaurados pelo sha1, o caso fica vermelho nos dois repositórios (no das etiquetas, `pro.status = :status OR 1 = 1`, porque o parâmetro tem de continuar ligado), no MySQL e no PostgreSQL. A descida de 25 para 23 fica, e agora com as duas metades. #### 06/10/2026: os quatro métodos por cliente da agenda cobertos (o fim do D189) `DiaDoClienteNaAgendaTest` chama `AgendaRepository::horariosMarcadosPorClienteData`, `::selecionarProximoAgendamentosCliente`, `::servicosMarcadosPorClienteData` e `::agendaPorClienteUnidadeData` sobre um cenário que ele mesmo planta — o último dia de um mês, com horários às 00:00:00 e às 23:59:59, a véspera, a virada, a outra unidade e um inativo —, e **afirma os ids**: na ordem, nos três que têm `ORDER BY age.data`; na comanda (`servicosMarcadosPorClienteData`), ordenados antes de comparar, porque ali a ordem não está definida (o D426) — uma regressão de ordem na comanda **não** fica vermelha neste arquivo (desde 07/10/2026 a ordem está escrita, e quem a prende é o `D426OrdemDosServicosDaComandaTest`). Os sem menção desceram de 146 para 142. Conferido tirando o arquivo do lugar: a contagem volta a 146, e a diferença são só estes quatro. E a chamada não está sozinha: um mutante de fronteira em cada um dos quatro (o fim fechado com `<=`, o início aberto com `>`, o fim esquecido) fica vermelho no caso dele, no MySQL e no PostgreSQL. **É a chamada, e não o docblock, que sustenta a descida — medido na revisão de 06/10/2026.** Tirar o arquivo do lugar não separava uma coisa da outra: o docblock do `DiaDoClienteNaAgendaTest` cita os quatro métodos pelo nome, e o `use` traz `Agenda` e `AgendaRepository`. A medida lia o arquivo inteiro, comentário incluído — e foi assim que a primeira versão da descida do D190 se apoiou num docblock. **A medida passou a ler os testes sem comentários** (`semComentarios()`, pelo `token_get_all`). Com ela, os quatro da agenda continuam mencionados; e o cenário da revisão — as quatro chamadas a `servicosMarcadosPorClienteData` trocadas por outro nome, o docblock intacto — fica **vermelho** (149 contra a base de 148), enquanto o portão de antes ficava **verde** em 142. **E a leitura sem comentários mexeu nas linhas de base, sem que teste nenhum mudasse:** | | antes | depois | |---|---:|---:| | pares sem menção em teste | 142 | **148** | | nome sem a própria classe (`FALSOS_POSITIVOS`) | 23 | **26** | | `COINCIDENCIAS` | 4 | 3 | Seis pares só eram "mencionados" em comentário e foram para "sem menção": `CaixaRepository::selecionarPorUsuario`, `PrivilegioUsuarioRepository::selecionarPorUsuario`, `ProdutoRepository::pesquisarQuantidade`, `VendaRepository::listagemIndexComandas` e os dois que saíram de `FALSOS_POSITIVOS` (`UnidadeRepository::selecionarUnidadesAtivas` e `UsuarioComissaoExtraRepository::selecionarPorUsuario`) — conferido par a par: o nome só aparece dentro de `/** ... */` ou `//`. Cinco entraram em `FALSOS_POSITIVOS` porque a própria classe, ou o nome no arquivo que a cita, só estava em comentário: `GrupoRepository::popularCombobox`, `AssistenteRepository::listagemIndexAdmin`, `MensagemRepository::listagemIndexAdmin`, `FuncionalidadeRepository::popularCombobox` e `DashboardFaturamentoRepository::relatorio`. E a coincidência do `CupomTest` (a `Unidade` num comentário antigo) deixou de existir, e saiu. > **13/10/2026 (o item UNIDADES-GRUPOS-ROYALTIES):** `GrupoRepository::popularCombobox` saiu de `FALSOS_POSITIVOS` -- o > `GruposQueONaoAdministradorPoeTest` o chama com a própria classe, nos dois bancos (o **D124**) --, e > `UnidadeRepository::getUnidadeColaboradoresServicos` saiu de "sem menção", chamado pelo `D351UnidadeDesativadaTest` (de > 146 para 145). A chamada não resolvida nova (de 2 para 3) é a `$vigencia->registrar()` de `UnidadeService`, um > `VigenciaDaAliquota` feito com `new`, lida antes de a base subir. **Na revisão do mesmo item**, > `EstadoRepository::popularCombobox` também saiu de `FALSOS_POSITIVOS` (de 25 para 24): o `D368VigenciaDaTaxaDeRoyaltyTest` > o chama pelo repositório da própria classe, para montar o POST inteiro do formulário antigo da unidade -- conferido no > teste, é a chamada, e não só o nome. > **17/10/2026 (a fatia ACL-API):** `FuncionalidadeRepository::popularCombobox` saiu de `FALSOS_POSITIVOS` (de 23 para 22): > o `MoldePelosControllersTest` o chama pelo repositório da própria classe e afirma que a grade do grupo aberto é o > catálogo dele, sem "Vendas caixa", na mesma ordem. E entrou o par `GrupoRepository::atribuiveisPorQuemNaoEAdministrador` > (de 334 para 335), chamado pelo `PrivilegioService` e citado, com a classe, no mesmo arquivo; o "sem menção" ficou em 130. > **20/10/2026 (a fatia 21, BANNERS-SERVIDOR):** `AppBannerRepository::listagemIndex` saiu de `FALSOS_POSITIVOS` (de 22 para > 21): o `TelasDosBannersDoErpTest` o chama pelo repositório da própria classe e afirma a ordem com o desempate pelo id. E > entraram dois pares (de 338 para 340), `AppBannerRepository::listagemDaApi` e `::unidadesAtivas`, chamados pela > `/adm/api/banners` e pelo nome, com a classe, no `BannersPelaApiTest`; o "sem menção" desceu de 130 para 129, porque > `::selecionarBannersAtivos` -- a ordem do aplicativo -- passou a ser chamado por nome nos dois arquivos. > **07/11/2026 (a fatia 109, SESSAO-LE-O-BANCO):** `ConvenioUnidadeRepository::convenioAtivo` saiu de `FALSOS_POSITIVOS` (de 22 > para 21): o `SessaoLeOBancoTest::testOConvenioDoDiaLeOsDiasDaUnidadeNoBanco` o chama pelo repositório da própria classe e > afirma que os dias do convênio são os da unidade no banco, e não os do arranjo que chega (o D350). > **07/11/2026 (a fatia 112, MARKETING-CAMPANHAS-E-SORTEIOS):** `NotificacaoRepository::listagemIndex` saiu de > `FALSOS_POSITIVOS` (de 21 para 20): o `D618BuscaDasCampanhasSemAcentoTest` o chama pelo repositório da própria classe e > afirma a busca por título e por texto da lista antiga das campanhas, com e sem a chave do acento (o D618). E saiu um par > (de 456 para 455), `SorteioRepository::validarVencimento`, com a escrita no GET da lista antiga dos sorteios (o D334). #### 08/11/2026: os três pares de dinheiro, o dos cupons e os dois `listagemIndex` (a fatia 126, PORTOES-E-COBERTURA) **Os três de dinheiro** que este registro nomeava estão no `D177ParesDeDinheiroTest`, chamados pelo repositório da própria classe sobre um cenário plantado (ids 90012600 a 90012699, dentro da transação), com os ids, a ordem e a soma afirmados: `SaidaParcelaPagamentoRepository::selecionarPagamentosPorSaida` (o extrato da despesa: só o pagamento ativo, da parcela ativa, da despesa pedida, do mais novo para o mais velho pela data, e não pelo id), `VendaRepository::selecionarVendasPorConvenio` (só as situações 1 e 2, só o convênio pedido, da mais nova para a mais velha, e o teto recortando pela mesma ordem) e `PontuacaoHistoricoRepository::selecionarPontuacaoValidadePorClienteUnidade` (só a linha `ativa`, do cliente e da unidade; sem linha, zero inteiro -- as somas são potências de dez distintas, para que cada filtro arrancado dê um número que só ele dá). `CupomRepository::selecionarCuponsGerados` **já estava coberto** pelo `CupomEmitidosTest` (os ids por filtro, desde o D266): conferido com dois mutantes, o filtro do `utilizado` arrancado (C1) e o `validade >= :hoje` trocado por `>` (C2), vermelhos nos dois bancos. **Os dois `listagemIndex` da fila de vazamento** estão no `D177ListagensDeUnidadeEUsuarioTest`: na de usuários, o recorte de quem não é administrador (a própria unidade, e ninguém do grupo de administradores; sem unidade, nada) e o administrador vendo a rede ou a unidade que escolhe, mais a situação, o grupo e a ordem pelo nome com o desempate pelo id; na de unidades, a situação, o país, o estado, a cidade e o bairro, e a ordem pelo lugar com o desempate pelo id, com e sem as colunas dos acessos. Os acessos já tinham caso pelas telas (o `D76AcessosDaPropriaPessoaNasListasTest`). **Os mutantes**, um por vez, cada um vermelho nos dois bancos pela asserção do caso e devolvido pelo sha1: E1 a E4 (o extrato: a parcela, o pagamento, a despesa, a ordem), V1 a V4 (o convênio: a situação, o convênio, a ordem, o teto), P1 a P4 (a pontuação: a situação, a unidade, o cliente, o nulo no lugar do zero), N1 a N5 (as unidades: a cidade, a situação, o bairro na ordem, o estado, o bairro no filtro) e U1 a U4 (os usuários: o grupo de administradores, o ramo de quem não é administrador, a unidade escolhida, a situação). O U3 da primeira rodada deu erro, e não falha (o parâmetro ficou sem uso e o Doctrine recusou); refeito tirando o bloco inteiro, ficou vermelho pela asserção. **As linhas de base do `conferir-cobertura-por-par.php` desceram:** "sem menção" de 103 para 100, `FALSOS_POSITIVOS` de 20 para 18, e a coincidência do `ConvenioUnidadesTest` (a única de `COINCIDENCIAS`) saiu, porque a catraca pediu. **Resta:** os outros 100 pares sem menção e os 18 falsos positivos; a ordem continua a da casa (dinheiro, vazamento, o resto). ### D178 — O botão da pesquisa de satisfação chama um método que não existe: 500 na cara do cliente — CORRIGIDO em 13/09/2026 `/pesquisanps/localizarcliente` é rota **declarada**, **pública** e **quebrada**. ```php // ISCadastro\Controller\PesquisaNpsController::localizarClienteAction(), linha 56 $repository = $this->em->getRepository(\ISVenda\Entity\VendaProduto::class); $dados['cliente'] = $repository->pesquisaNpsLocalizarCliente($request['telefone'], $dataLimite); ``` **O método `pesquisaNpsLocalizarCliente` não existe.** `VendaProdutoRepository` declara `pesquisaNpsLocalizarClientePorId` e `pesquisaNpsLocalizarColaboradores`, e mais nenhum parecido — conferido por busca exaustiva em `module/`. #### A cadeia, medida em três pontos independentes 1. **O método não está declarado em lugar nenhum** do projeto. 2. **O `__call` do Doctrine lança.** `vendor/doctrine/orm/src/EntityRepository.php:268` trata `findBy`, `findOneBy` e `countBy`, e para qualquer outro nome faz `throw new BadMethodCallException('Undefined method ...')`. Não há `__call` no repositório do projeto que intercepte antes. 3. **A rota responde 500.** Medido contra o ambiente local: ``` GET /pesquisanps -> 200 POST /pesquisanps/localizarcliente -> 500 ``` O POST levava só `telefone=(47) 99999-9999` — o `if` da ação exige 14 ou 15 caracteres. A página irmã, que é a mesma tela, responde 200: não é ambiente. #### O que isso significa — CORRIGIDO em 13/09/2026, e a correção é grave **A primeira versão deste registro dizia que nenhuma tela chamava a rota. Estava errado, e o erro era meu.** A rota é **pública**: `/pesquisanps` é a pesquisa de satisfação que o cliente abre por link, sem autenticação, e a guarda de rotas não a bloqueia — o 200 do `GET` prova. E ela **é chamada pelo botão CONTINUAR dessa mesma tela**: ```js // public/layout/scripts/mod-relatorios.js:258-267 function pesquisaNpsLocalizarCliente(campo) { $.ajax({ url: "/pesquisanps/localizarcliente", type: "post", data: { telefone: $(campo).val() }, ``` A pesquisa tem **dois caminhos de entrada**, e só um funciona: | caminho | como se chega | estado | |---|---|---| | por link com `?cli=` e `?uni=` | o cliente recebe o link pronto | **funciona** — usa `pesquisaNpsLocalizarClientePorId`, que existe | | digitando o telefone no teclado | o cliente abre `/pesquisanps` e digita | **500** — chama o método que não existe | **Provado na tela, e não por leitura.** Abrindo `/pesquisanps` no navegador, digitando um telefone no teclado numérico e clicando CONTINUAR: o `POST` sai, o servidor responde **500**, e o cliente vê *"Erro ao localizar cliente."* — a mensagem do `error:` do próprio AJAX. Reproduzido também por linha de comando, com o mesmo telefone de 15 caracteres que o teclado monta. #### POR QUE EU NÃO TINHA VISTO, e a lição é sobre a busca Procurei por `localizar-cliente` e `localizarCliente`. A URL no JavaScript é **tudo minúsculo** — `localizarcliente` — e a função se chama `pesquisaNpsLocalizarCliente`, com prefixo. **Nenhum dos dois padrões casava com a string que importava.** O `grep` devolveu zero e eu li o zero como ausência. E o que achou foi **abrir a página**. É a máxima da casa — *curl verde não prova a tela* — cobrando o preço de novo, agora sobre um registro que eu mesmo tinha escrito com confiança. Então o estado real é: **a funcionalidade está quebrada na cara do cliente**, não morta num canto. Quantas pessoas tentam por ali em vez do link é coisa que o banco não registra — a ação estoura antes de gravar qualquer coisa. #### Como apareceu, e por que vale contar Não foi revisão de código. Apareceu numa **divergência entre duas medições** da mesma coisa: um fan-out de agentes listou `VendaProdutoRepository::pesquisaNpsLocalizarCliente` como par chamado por controller, e o resolvedor mecânico do D177 **não** — porque ele só registra o par quando o método existe como `public function` na classe resolvida. Os dois estavam certos: existe a chamada, e não existe o método. **O desencontro era o defeito.** #### COMO FICOU, e a escolha foi a primeira das quatro **Implementado.** O que decidiu foi abrir a tela: `/pesquisanps` sem parâmetros é **inteiramente** o teclado — logo, título, "Informe seu telefone", teclado numérico e CONTINUAR, e mais nada. É o modo totem, de tablet de balcão: a tela se rearma sozinha em 4 segundos e o logo entra em tela cheia. Então as outras três opções caem por terra sozinhas. Tirar o teclado deixaria uma página de marca **vazia**; trocar o 500 por "use o link que você recebeu" falaria com quem não tem link nenhum; e deixar como está é o erro visível. **E a objeção de privacidade que este registro levantou não se sustenta.** O caminho que *funciona* — `?cli=N&uni=M` — é **enumerável**: basta incrementar o id. O caminho quebrado exige **saber o telefone** e só responde sobre quem tem pesquisa **pendente**. A superfície maior é a que já estava de pé. #### O MÉTODO RECUSA AMBIGUIDADE EM VEZ DE SORTEAR `ClienteRepository::selecionarClientesPorTelefone` já tinha medido e escrito que **telefone não identifica cliente**: 10.000 combinações têm mais de um cadastro, uma delas com 26 — os telefones de balcão do D32. Lá a regra é `cl.id ASC`, "o titular provável", porque aquela tela precisa de alguém. Aqui não. Sortear entre homônimos mostraria a um cliente os barbeiros que atenderam **outro**, e gravaria a nota na pessoa errada — numa rota sem sessão. O método usa `setMaxResults(2)` e devolve **só quando o casamento é único**; com dois ou mais, devolve `null`, e o controller já tinha a frase certa. Efeito colateral bom: sem `setMaxResults(1)`, não há linha sorteada, e o portão `conferir-linha-sorteada.php` — que roda no CI — passa com *"Nenhuma busca nova sem ordem"*, sem precisar de dispensa. A saída barata seria copiar o marcador `@linha-sorteada-conferida` do irmão, e ela instalaria uma justificativa **falsa**: o texto do irmão diz "o WHERE já fixa `cli.id`", e aqui o WHERE fixa telefone. #### A JANELA DE DATA ERA UM SEGUNDO DEFEITO, e bloqueava o conserto ingênuo `localizarClienteAction` passava `date('Y-m-d')` — **só hoje** —, enquanto os outros três pontos do NPS usam **-30 dias**. Não era escolha de privacidade; era defeito que só apareceria depois de o método existir. Medido em 13/09/2026 na cópia: **zero** vendas pendentes na data de hoje contra **1.674** clientes na janela de 30 dias. Com o limite antigo, a rota consertada responderia *"Não localizamos nenhuma pesquisa"* para **todo** telefone. E pior que devolver vazio: o formulário era montado com os colaboradores de HOJE e validado no salvar contra os de 30 DIAS — **13.901 de 13.930 clientes divergem**. A tela abriria e recusaria salvar, pedindo resposta a pergunta que nunca mostrou. A linha 68 do controller passou a -30 dias, e as três janelas do NPS concordam. #### MEDIDO NA TELA, antes e depois antes POST /pesquisanps/localizarcliente -> 500, em 8,9 segundos depois POST /pesquisanps/localizarcliente -> 200, com o formulário montado O 200 traz a saudação, as duas perguntas e os colaboradores que atenderam. #### A REDE QUE FICOU `tests/Caracterizacao/LocalizarClienteDaPesquisaNpsTest.php`, seis casos, montando o próprio cenário na transação revertida — porque os telefones das fixtures têm 18 caracteres e o controller só aceita 14 ou 15, e porque na cópia o anonimizador colapsa 242 mil clientes em 10 mil números, o que faria *toda* busca cair no caso ambíguo. Os quatro filtros foram falsificados um a um, mutando o método e conferindo que o caso certo fica vermelho: | mutação | caso que caiu | |---|---| | recusa de ambiguidade vira "devolve o primeiro" | `testTelefoneCompartilhadoNaoDevolveNinguem` | | tira `cli.status = true` | `testClienteInativoNaoAparece` | | tira a janela de data | `testVendaForaDaJanelaNaoAparece` | | tira `ven.npsRespondido` | `testPesquisaJaRespondidaNaoAparece` | O portão `conferir-cobertura-por-par.php` subiu quatro linhas de base no mesmo commit: `PARES_ESPERADOS` 178→179, o sha1, `SEM_MENCAO_ESPERADA` 63→62 e `CHAMADAS_POR_MODULO['ISCadastro']` 86→87. #### O QUE NÃO FOI CONSERTADO DE CARONA Três coisas apareceram no caminho e ficaram anotadas em vez de resolvidas junto: o irmão `...PorId` não filtra `cli.status` (**D182**), e `/pesquisanps/salvar` aceita id de cliente cru e vaza o caminho do servidor (**D180**). ### D179 — O PDV recalculava o crédito do cliente e gravava por cima — GRAVAÇÃO REMOVIDA em 13/09/2026; o passado continua decisão — PARCIAL, lido em 05/10/2026 — CORRIGIDO em 15/10/2026 > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito como fechado, e o corpo diz que ele está parcial: uma parte está consertada, e a outra não. Falta: reconciliar as linhas que já divergem, dinheiro de cliente em produção congelada, e fazer a devolução de crédito virar registro; as duas são decisão sua. Este é o maior achado de dinheiro da frente de cobertura, e ele saiu de escrever teste para um método que não tinha nenhum. #### A cadeia, e o último elo é o que assusta ``` extratoCreditoCliente($cliente, $unidade) VendaRepository:1220 -> calcularSaldoCreditoClientePorUnidade(...) VendaRepository:1311 (última linha, com max(0, ...)) -> sincronizarValorCreditoClienteComExtrato() ClienteService:330 (GRAVA em clientes_creditos.valor) <- pesquisarCreditoDebitoConvenioAction() ClientesController:554 <- public/layout/scripts/mod-vendas.js:215 ``` **O PDV chama isso ao selecionar o cliente.** Abrir uma venda e escolher alguém dispara o recálculo; se o número novo diferir do guardado por mais de R$ 0,009, o guardado é **sobrescrito**. Sem aviso, sem registro, e o operador não vê nada. Os dois métodos vêm da **importação inicial** — é código de produção, rodando hoje, não algo que esta frente introduziu. O que a frente de 04/09 fez (`d9db320`) foi acrescentar o `ORDER BY` que faz ler e gravar caírem sempre na mesma linha do par duplicado; o recálculo em si é antigo. #### O que o extrato enxerga é MENOS do que o sistema usa para conceder crédito O extrato é a união de duas consultas: | | critério | valor | |---|---|---| | crédito | `v.vendaCredito = 1 AND v.status = 1` | `v.valorTotal` | | débito | pagamento com `fp.id = 5`, venda `status = 1` | `vp.valor` | E os gravadores de `clientes_creditos.valor`, lidos um a um, são **cinco**: | onde | o que faz | o extrato vê? | |---|---|---| | `ClienteService:136/141` | soma `getValorRecebido()` na compra de crédito | **não** — o extrato lê `getValorTotal()` | | `VendaPagamentoService:178/183` | soma o **TROCO**, em venda que não é `vendaCredito = 1` | **não** | | `VendaPagamentoService:118` | subtrai o crédito usado | sim, pelo pagamento forma 5 | | `ClienteService:152` | devolução de crédito | **não** | | `FidelidadeService:131` | zera | **não** | Ou seja: **o extrato não é o sistema de registro do crédito, e o sincronizador o trata como se fosse.** Três dos cinco caminhos que criam ou alteram crédito são invisíveis para ele. #### O tamanho, medido na cópia de produção Comparando, para cada par (cliente, unidade) com crédito positivo, o valor guardado com o que o extrato calcula: | | | |---|---:| | linhas com crédito > 0 | **3.998** | | que **divergem** do extrato | **3.573 (89%)** | | guardado em `clientes_creditos` | R$ **93.458,33** | | calculado pelo extrato | R$ **316.069,26** | E por direção do efeito: | efeito do recálculo | linhas | reais | maior caso | |---|---:|---:|---:| | **SOBE** — cliente ganha crédito | 538 | **R$ 266.488,21** | R$ 14.536,00 | | **DESCE** — cliente perde crédito | 3.035 | **R$ 43.877,28** | R$ 9.392,40 | | igual | 425 | zero | — | **Exemplo conferido linha por linha:** o cliente 41640 tem R$ 9.392,40 guardados na unidade 5 e o extrato dele é **inteiramente vazio** — zero compras de crédito, zero usos. Selecioná-lo no PDV daquela unidade zera o saldo. #### Por que isso não aconteceu com todos ainda Porque o recálculo só roda **para o cliente que alguém selecionar**. As 3.573 linhas divergentes são as que ainda não passaram por lá desde a última divergência. É dreno silencioso, um cliente por vez, nos dois sentidos. #### E o `max(0.0, ...)` esconde o negativo `calcularSaldoCreditoClientePorUnidade` devolve `round(max(0.0, $saldo), 2)`. Quando os usos passam as compras, o **extrato mostra saldo negativo** e a função que grava **devolve zero**. As duas funções do mesmo arquivo respondem coisas diferentes sobre o mesmo cliente, e a que grava é a que zera. Está gravado em `ExtratoDeCreditoDoClienteTest::testUsoMaiorQueAsComprasFicaNegativoNoExtratoEZeroNoSaldo`, falsificado removendo o limitador. #### COMO FICOU: a opção 2, e o método mudou de nome junto **O sincronizador parou de gravar em linha que já existe.** Ele virou `ClienteService::garantirLinhaDeCreditoDoCliente()` — o nome antigo prometia sincronização, e quem lesse o chamador continuaria acreditando que o saldo fica alinhado. Nome que mente custa mais que nome feio. O que ficou: **criar a linha quando ela não existe**. Ali não há valor anterior para destruir, e o contrato antigo — *"chamar antes de `atualizarPontuacao` quando se incluir linha nova"* — depende da linha existir. Medido, esse ramo dispara para **zero** pares na cópia: quem compra crédito já ganha a linha na compra. E o extrato passou a ser consultado **só** quando não há linha. No caminho comum do PDV — cliente que já tem linha — a consulta cara, que hidrata entidades `Venda`, deixou de acontecer. #### NÃO CASE ESTE MÉTODO COM `atualizarPontuacao` O docblock antigo mandava chamá-lo junto. Fazer isso põe a cadeia no **cron das 23:00** (`CronJobService:392`), que varre **3.060 clientes por noite** — o defeito de um cliente por vez viraria varredura. Está escrito dentro do método. #### TRÊS CORREÇÕES AO PRÓPRIO REGISTRO, e as três apareceram medindo de novo **1. Não eram cinco caminhos: são quinze sítios, em cinco arquivos.** A tabela acima lista cinco. Faltavam, no mínimo, a **comissão de indicação** (`VendaPagamentoService:320/327`) — que CRIA dinheiro e não tem venda nenhuma por trás, então não dá para deduzi-la de `vendas` — e o **cancelamento/estorno** (`VendaService:195/202`). Um conserto construído sobre a lista de cinco continuaria apagando crédito de indicador, só que com menos linhas. **2. Os números incluíam 3 linhas de fixture, R$ 165,00.** O D167 existe para lembrar disso e mordeu o próprio registro. Remedido em 13/09/2026 com a faixa `>= 90000000` fora: | | registro de 12/09 | remedido | |---|---:|---:| | linhas com crédito > 0 | 3.998 | **3.995** | | divergem | 3.573 | **3.570** | | guardado | R$ 93.458,33 | **R$ 93.293,33** | | calculado pelo extrato | R$ 316.069,26 | R$ 316.069,26 | | sobem | 538 / R$ 266.488,21 | 538 / R$ 266.488,21 | | descem | 3.035 / R$ 43.877,28 | **3.032 / R$ 43.712,28** | **3. O denominador escondia metade do alcance.** A medição usou `valor > 0`, que são 3.995 de 256.987 linhas. Contando a tabela inteira, o sincronizador também gravava onde o guardado era **zero** e o extrato calculava positivo — mais 1.385 linhas. O alcance real era **4.959**, e a diferença toda na direção que DÁ dinheiro. #### O MEDIDOR ESTÁ CEGO, e isso muda o que os números provam `vendas_pagamentos` tem **1.002 linhas para 2,27 milhões de vendas** nesta cópia, e **zero** nas formas 5 e 6. O lado do DÉBITO do extrato — a consulta `fp.id = 5` — é **vazio para todo mundo** aqui. Logo, nesta cópia, o saldo calculado é a soma das compras sem nunca subtrair uso. Consequência, e ela precisa ficar dita: **o "3.570 de 3.995" não distingue "o sincronizador enxerga pouco" de "esta cópia não tem linha de pagamento"**. A divergência real em produção é **NÃO MEDIDA daqui**. O que **sobrevive** à cegueira é a direção destrutiva: **2.984 pares** têm valor gravado e extrato zero, somando **R$ 43.337,93** que o sincronizador zerava. Esse número é **piso**: com as linhas de pagamento presentes o extrato só pode ficar menor, então mais pares cairiam em zero, nunca menos. Pelo mesmo raciocínio, a direção que DÁ dinheiro (R$ 266.488,21) está **inflada** e não transfere. Isso virou o **D181**, porque vale para qualquer medição de pagamento nesta cópia. #### E O NÚMERO NÃO É DECORATIVO `Adm/ComandasController:563` e `VendasPagamentosController:335` leem essa coluna como **TETO do pagamento em crédito** — e por nome de método montado (`$credito->{$saldos[$formaId]}()`), que nenhum `grep` por `getValor` acha. Valor errado ali não é número torto na tela: é **recusa de pagamento no balcão**. #### A REDE QUE NÃO EXISTIA Com um contador injetado nos dois métodos de `ClienteService`, a suíte inteira — 626 testes — chamou o sincronizador **zero** vezes, enquanto o controle positivo `atualizarPontuacao`, no mesmo arquivo e pelo mesmo mecanismo, recebeu **5**. Não havia rede; havia a ilusão de rede, porque os arquivos de nome parecido (`ExtratoDeCreditoDoClienteTest`, `SaldoDuplicadoTest`) cercam a **entrada** e param antes da escrita. `tests/Caracterizacao/SincronizacaoDoCreditoDoClienteTest.php` fecha o vão, com cinco casos. Ele foi escrito **antes** do conserto e rodado contra o código velho: três vermelhos, mostrando o defeito com número — R$ 100,00 zerados e R$ 40,00 virando R$ 500,00. #### O QUE CONTINUA SENDO DECISÃO SUA A gravação parou; **o passado não foi tocado**. As linhas que já divergem seguem como estão, e reconciliá-las é operação sobre dinheiro de cliente em produção congelada — mesma natureza da decisão do D135. E há uma pergunta anterior a ela, que a medição levantou: a **devolução de crédito** não deixa rastro em lugar nenhum (nem venda, nem pagamento, nem saída de caixa, nem histórico), então nenhum extrato conseguirá explicar o saldo enquanto ela não virar registro. --- #### A resposta 89 (b) — 15/10/2026, a fatia 5c (RESPOSTAS-DO-FINALIZAR-E-DA-DEVOLUCAO) As duas decisões que este débito deixava ao dono foram tomadas pela página do lote (a 89, `registro-da-devolucao-de-credito`), com a opção (b): *"A (a), e a devolução sai do caixa aberto como uma retirada. Serve se o dinheiro devolvido sai da gaveta: o caixa fecha certo. Sem caixa aberto, a devolução é recusada."* -- e a (a): *"Cada devolução grava quem autorizou, quem operou, quanto e quando, numa tabela nova (nas cópias locais, pela pergunta do esquema; na produção, no corte), e o histórico do crédito a mostra. Nenhum saldo do passado muda."* **O passado não muda:** as linhas que já divergem ficam, e o saldo de hoje é o ponto de partida. **A devolução, daqui em diante** (`ClienteService::creditoDevolucao`, a única porta do ERP e da API), numa transação só: o cliente, o crédito e o caixa aberto de quem opera, travados nessa ordem; sem caixa aberto, a recusa (`DEVOLUCAO_SEM_CAIXA`); a retirada pela regra da retirada da API (`CaixaService::retiradaDaDevolucaoDeCredito`: o saldo do caixa recalculado sob a trava, e nada além dele -- `DEVOLUCAO_ALEM_DO_CAIXA`; **essa recusa não é da resposta 89**, que só nomeia a falta de caixa: veio junto com a regra da retirada, e o saldo que ela confere não é o dinheiro da gaveta -- fica como está até a resposta da pergunta nova, o D501), com o motivo *"Devolução de crédito a (cliente )"* e sem conta a pagar; o saldo do cliente baixado; e a linha nova em `clientes_creditos_devolucoes` (`ISCadastro\Service\RegistroDaDevolucao`): o cliente, a unidade, o valor, quem autorizou (o gerente da senha), quem operou (`CrudController::autorDaEscrita`) e a retirada. O extrato do crédito (a aba do histórico do cliente no ERP, `VendaRepository::extratoCreditoCliente`) mostra a devolução como débito, com quem autorizou. A tabela entrou no `mysql.sql`, no `schema.sql` do gerador, na carga (`migrar-dados.sh`), nas duas cópias locais (a 83 a) e no laço do passo 0 (`scripts/migracao-clientes-creditos-devolucoes.sql`); sem ela no banco (a base do teste do BVIP até a próxima cópia), a devolução segue, com a retirada e sem a linha (a `ColunaNoBanco`, o D473). **As telas.** O ERP vai ao caixa, com a frase, quando não há caixa aberto (como a compra de crédito), e diz cada recusa; o aviso vermelho da página deixou de dizer *"não será debitado do caixa"*. A API responde 409 com `motivo: sem_caixa` antes de conferir a senha do gerente, e 409 com `motivo: alem_do_caixa`; a tela nova diz que o valor sai do caixa aberto e oferece "ir ao caixa" na recusa, como na compra. **Provado** em `D179DevolucaoRegistradaTest` (15 casos) e no `DevolucaoDeCreditoSobTravaTest` refeito, verdes nos dois bancos, e no front (`FidelidadeLigada.teste.tsx`). **Sem decisão nova, ficou de fora** o que cancelar a retirada da devolução faz com o crédito: a pergunta foi ao lote (o D500). **E a recusa do que passa do saldo do caixa** é escolha que a 89 não fez: a pergunta foi ao lote (o D501), e até a resposta ela fica, por ser o padrão que não perde dado (o cliente continua com o crédito). > **Lido em 16/10/2026 (a fatia 5e, RESPOSTAS-231-E-232):** as duas perguntas voltaram. Pela 231 (a), cancelar a retirada da > devolução a desfaz -- o crédito volta ao cliente, e o registro ganhou quem desfez e quando (o D500, com as duas colunas > novas); pela 232 (c), a devolução sai mesmo maior que o saldo do caixa, que pode ficar negativo, e a recusa > `DEVOLUCAO_ALEM_DO_CAIXA` saiu das duas portas (o D501). O registro e o extrato continuam os daqui; este débito segue > corrigido. ### D180 — `/pesquisanps/salvar` gravava a pesquisa para qualquer id de cliente — CORRIGIDO em 13/09/2026 Apareceu fechando o D178, mapeando a mesma tela. `PesquisaNpsController::salvarAction` lê `$request['cliente']` — **um id cru do POST** — e grava a pesquisa para aquele cliente. A rota é pública, não há sessão, e não há nada que prove que quem envia é aquela pessoa. Quem souber o formato do corpo pode gravar avaliação em nome de qualquer cliente que tenha venda pendente. Não é escalada de privilégio: a pesquisa não dá acesso a nada. É **integridade do NPS** — o número que a rede usa para medir atendimento aceita entrada não atribuída. E a resposta da mesma ação sai com **dois `Warning` do PHP na frente do JSON**, com o caminho absoluto do arquivo e o número da linha: `salvarAction` compara `$request['nota_recepcao_valor']` e `$request['nota_experiencia_valor']` sem conferir se as chaves existem. O JSON só continua válido porque o formulário normal sempre as manda. #### A METADE DO VAZAMENTO SAIU no mesmo dia `validarFormularioSalvar` passou a ler os campos com `?? ''`. Antes, um POST sem eles devolvia isto na frente do JSON, numa rota **pública**: ``` Warning: Undefined array key "nota_recepcao_valor" in /var/www/html/module/ISCadastro/src/Controller/PesquisaNpsController.php on line 138 ``` Depois do conserto, o mesmo POST devolve JSON limpo. A mudança veio junto com a do **D183**, porque são as mesmas duas linhas. #### A ATRIBUIÇÃO FECHOU PELO DESENHO DA TELA IRMÃ, e não pelo hash O registro dizia que o conserto natural era exigir o `hash` do cliente no corpo. Ele funcionaria — e **mudaria o link que o cron já mandou**: quem tivesse o link antigo no WhatsApp deixaria de conseguir responder. Por isso era decisão. O conserto que entrou não toca no link. `PesquisasController::responderAction`, a **outra** pesquisa pública deste mesmo sistema, já resolvia isso há anos: ela guarda a pesquisa na sessão ao abri-la e a lê de volta depois. Era desenho pronto, na casa, e ninguém precisou inventá-lo. A amarra fica em `criarPesquisaHtml`, que é o **único** lugar por onde os dois caminhos passam — o link com `?cli=` e o teclado do totem. Quem não abriu o formulário não tem o que enviar. **E o campo do POST continua sendo lido, de propósito.** Ele tem de *concordar* com a sessão. Num tablet de balcão compartilhado, o formulário de uma pessoa pode estar na tela enquanto a sessão já é de outra, se a segunda digitou o telefone antes de a primeira enviar. Ler só a sessão gravaria a nota da primeira na segunda — trocaria um defeito de atribuição por outro, mais silencioso. `$this->sessao` **não servia**: o controller chama `parent::__construct(true)`, o modo API, então o `SessaoAcl` nunca é montado — e não deveria ser, porque quem abre a pesquisa não tem usuário. O `Container` do Laminas é o mesmo mecanismo que o `SessaoAcl` usa por baixo; muda só o nome do quarto. #### MEDIDO PELA ROTA, antes e depois | o que se manda | antes | depois | |---|---|---| | corpo completo, sem ter aberto o formulário | **gravava** | recusa | | sessão do cliente A, corpo dizendo o cliente B | **gravava para B** | recusa | | sessão de A, corpo de A, faltando um campo | cobra o campo | cobra o campo | #### A FALSIFICAÇÃO ACHOU DOIS DEFEITOS NO MEU PRÓPRIO ENSAIO O `ensaiar-rotas-publicas-do-erp.php` ganhou cinco casos e passou de 18 para **23**. Devolvendo o defeito para conferir que ele fica vermelho, **ele morreu com 255** — e os dois motivos valem mais que o conserto: 1. **A limpeza só desfazia o caminho certo.** Com o D180 de volta, o caso do POST cru passa a *gravar* — o corpo dele é completo de propósito, para que a única recusa possível seja a da sessão — e a limpeza bateu na chave estrangeira de `nps_itens`. O ensaio não reportou vermelho: estourou, e deixou cenário para trás. *Limpeza que só desfaz o caminho certo falha exatamente quando faz falta.* 2. **Um caso era vago, e passou sob a regressão.** O caso da sessão trocada afirmava só `sucesso=false` — verdade por **dois** motivos, porque o corpo dele não mandava a nota do colaborador e a validação de campo o recusava sozinha. É exatamente o erro contra o qual o cabeçalho do próprio ensaio adverte: *o código HTTP não basta*. Corrigidos os dois, a falsificação passou a derrubar **quatro** asserções nos casos 8 e 9, com resíduo zero no banco depois. E os casos destrutivos-sob-regressão foram movidos para o **fim** do bloco: com o defeito de volta, a escrita de um deles envenenava os anteriores, e o diagnóstico virava ruído. 23 de 23 no MySQL e 23 de 23 no PostgreSQL. --- ### D181 — As fixtures apagaram 2,3 milhões de linhas de `vendas_pagamentos` da cópia, e ninguém viu por 28 dias — MEDIDO E COM PORTÃO em 13/09/2026 — PREPARADO, lido em 05/10/2026 > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito como medido, e o corpo diz que ele está pronto no código, à espera só do passo em produção na janela da migração final. Falta: recarregar a cópia exige ler produção de novo, na janela do corte; até lá, toda medição por forma de pagamento nesta cópia é piso. Apareceu fechando o D179, e vale para qualquer medição futura. `vendas_pagamentos` tem **1.002 linhas para 2.269.221 vendas** na cópia, e **zero** nas formas 5 (Crédito Cliente) e 6 (Crédito Prog. Fidelidade). Nenhuma venda com `venda_credito = 1` tem linha de pagamento. O efeito é sistemático: toda consulta que soma, subtrai ou filtra por forma de pagamento devolve, nesta cópia, **um lado só da conta**. No D179 isso inflou a direção "cliente ganha crédito" e transformou "cliente perde crédito" num piso — o número continua servindo para decidir, mas **não** para dizer o tamanho. #### A CAUSA, e ela não é a que este registro dizia A primeira versão daqui afirmava: *“não é defeito do anonimizador: é recorte da cópia”*. **Não é nem uma coisa nem outra.** O anonimizador de fato não toca na tabela (conferido), mas o dump também não veio cortado: as linhas **entraram nesta cópia e foram apagadas aqui**. Quem apagou está versionado. O `tests/Caracterizacao/fixtures.sql` de 15/08/2026 (commit `7e98fa7`) começava assim: DELETE FROM vendas_pagamentos WHERE venda >= 1000; DELETE FROM vendas_produtos WHERE venda >= 1000; DELETE FROM vendas WHERE id >= 1000; A faixa de fixture era `>= 1000`, e a cópia de produção tem ids muito acima disso. Carregar as fixtures levou **2,3 milhões de linhas** — 99,96% da tabela. **`vendas` sobreviveu porque tem DEZ chaves estrangeiras apontando para ela. `vendas_pagamentos` não tem NENHUMA**, e nada a protegeu. #### A PROVA ESTÁ NO DISCO O InnoDB não encolhe o arquivo num apagamento. Medido: | tabela | dados | livre | % livre | |---|---:|---:|---:| | **`vendas_pagamentos`** | **0 MB** | **194 MB** | **100%** | | `vendas` | 211 MB | 7 MB | 3% | | `vendas_produtos` | 263 MB | 7 MB | 3% | Duzentos megabytes de espaço livre para 1.002 linhas. E como o anonimizador não toca nessa tabela, esse espaço **só pode vir de `DELETE`**. #### E O EPISÓDIO FOI REGISTRADO COMO QUASE-ACIDENTE Em 16/08 a faixa foi movida para 90.001.000, fechando o mecanismo. O commit `37b7b71` registrou o episódio com esta frase: > Só não apagou porque as chaves estrangeiras bloquearam. **Para esta tabela, apagou.** A frase está certa sobre `vendas` e errada sobre `vendas_pagamentos`, e foi por acreditar nela que ninguém procurou o estrago. O mecanismo está fechado há 28 dias — os `DELETE` de hoje ficam todos na faixa de fixture, conferido — e o dano nunca foi notado nem desfeito. #### POR QUE NINGUÉM VIU **A tabela não ficou vazia.** Sobraram 993 linhas — as de id 1 a 999, com dado real de 5 a 23 de junho de 2015 — mais 9 de fixture. Consulta que acha linha não parece vazia: parece medição. Foi assim que o D179 mediu crédito de cliente sobre um extrato cujo lado de **débito** estava zerado, e ninguém estranhou. Em números: `vendas` vai até 16/08/2026 e `vendas_pagamentos` morre em 23/06/2015 — **onze anos e dois meses** de ausência —, e **2.268.216 das 2.269.209 vendas** (99,96%) não têm nenhuma linha de pagamento. #### COMO FICOU: um portão, e o instrumento já estava no repositório `scripts/conferir-completude-da-copia.php`, o **35º** do conjunto. `mysql.sql` é um dump **só-de-esquema** de `franquia_producao`, e cada `CREATE TABLE` dele carrega o `AUTO_INCREMENT=` que a tabela tinha **em produção** — o número de ids já consumidos lá. São 82 tabelas que o declaram, e isso é uma marca d'água melhor que qualquer heurística local: - **imune a exclusão** — apagar linha não baixa o contador, então uma tabela que perdeu metade das linhas em onze anos continua alcançando o topo; - **imune às fixtures** — o filtro do que é cenário é **lido dos próprios `DELETE` do `fixtures.sql`**, então os dois ficam em sincronia sozinhos; - **direta** — não infere: lê o que produção declarou. Resultado: **81 tabelas conferidas, 1 sem o topo** — `vendas_pagamentos`, maior id local **999** contra **2.309.941** em produção. #### DUAS ARMADILHAS QUE A PRÓPRIA CONSTRUÇÃO ACHOU **1. A heurística ingênua acusaria dez inocentes.** Comparar `COUNT(*)` com `MAX(id)` põe o dicionário de CEP no topo da lista — e ele foi esvaziado **de propósito** em 31/08/2026, quando o ViaCEP virou a fonte (`scripts/limpar-dicionario-cep.sql`). A marca d'água o absolve sem precisar conhecer a história de cada tabela. **2. A primeira versão do portão disse que estava tudo bem.** Ela filtrava `id < 90000000`, e as fixtures de `vendas_pagamentos` inserem **sem dizer o `id`**: o auto_increment as põe logo acima do último id de produção — 2.311.026 a 2.311.034. **Nove linhas nossas escondiam a falta de 2,3 milhões.** O conserto foi parar de adivinhar e ler o filtro de onde ele já estava escrito. #### ELE FALHA NOS DOIS SENTIDOS, e o segundo é o que importa Falsificado: tirar a declaração de `vendas_pagamentos` dá vermelho com *“perdeu o topo, e ninguém declarou isso”*; declarar uma tabela que está inteira dá vermelho com *“voltou a alcançar o topo”*. Esse segundo caso é deliberado. No dia em que alguém recarregar a cópia, vários números deste projeto — o D179 inteiro — estão publicados com a ressalva *“isto é piso, e não medida”*, e essas ressalvas passam a mentir na direção oposta. O portão obriga a revisitá-las antes de tirar a entrada. #### O QUE CONTINUA EM ABERTO **Os dados não voltam daqui.** Não há dump de dados no repositório — o `mysql.sql` é só esquema, 90 KB — e recarregar a cópia exige ler produção de novo, que por decisão de 11/09/2026 acontece **dentro da janela do corte**. Até lá, toda medição por forma de pagamento nesta cópia é **piso**, e o portão existe para que isso continue dito em vez de lembrado. --- ### D182 — `pesquisaNpsLocalizarClientePorId` não filtrava `cli.status`, e o salvar exige — CORRIGIDO em 13/09/2026 O irmão do método escrito no D178 tem o mesmo vão que o novo já fecha. `PesquisaNpsController::salvarAction` exige `$cliente->getStatus()` e responde *"Cliente inválido"*. Mas `cadastroAction` chama `pesquisaNpsLocalizarClientePorId`, que **não filtra status**. O cliente inativo que abre o link do WhatsApp vê a pesquisa, responde tudo, e leva a recusa no fim. O método novo (`pesquisaNpsLocalizarCliente`) filtra `cli.status = true`, e o teste `testClienteInativoNaoAparece` prende isso. O irmão ficou como estava **de propósito**: mexer nele muda o que o link já enviado faz, e isso é mudança de comportamento numa tela que o cliente vê — não cabe de carona no conserto de outro débito. Medido em 13/09/2026 na cópia: **1** cliente da janela de 30 dias está nessa situação. #### COMO FICOU `AND cli.status = true` entrou no irmão, e os dois caminhos agora concordam sobre quem pode abrir a pesquisa. O caso `testClienteInativoNaoApareceNemPeloLink` prende isso, e foi falsificado tirando a cláusula de volta. Fechou de imediato, e não “de carona”: virou mudança própria, e o efeito para quem recebe o link é estritamente melhor — em vez de responder a pesquisa inteira e levar *“Cliente inválido”* no fim, a pessoa vê de cara a tela de cliente não localizado. --- ### D183 — A nota ZERO a um barbeiro não podia ser enviada, e a nota zero à loja podia — CORRIGIDO em 13/09/2026 Apareceu lendo `validarFormularioSalvar` para fechar o vazamento do D180, e vale mais que ele. As duas perguntas de loja eram validadas com `== ''` e as dos colaboradores com `empty()`. Em PHP: | valor | `== ''` | `empty()` | |---|---|---| | `'0'` | **falso** | **verdadeiro** | | `'10'` | falso | falso | | `''` | verdadeiro | verdadeiro | Ou seja: **a nota 0 passava nas de loja e era recusada nas de colaborador.** #### Provado pela própria rota, antes do conserto POST /pesquisanps/salvar nota_colaborador_1243_valor=0, resto preenchido -> {"sucesso":false,"mensagem":"Responda as seguintes perguntas: - Atendimento do(a) Colaborador 1243"} POST /pesquisanps/salvar nota_recepcao_valor=0, nota_experiencia_valor=0 -> {"sucesso":true} O cliente que quisesse dar **zero** a um barbeiro — a pior nota, e a mais informativa — via "Responda as seguintes perguntas" apontando para a pergunta que ele **tinha** respondido. Não havia como enviar. #### O QUE ISSO FAZ COM O NÚMERO O NPS é o que a rede usa para comparar unidades e colaboradores. Com a recusa, a nota de colaborador nascia com **piso 1**: quem quisesse dar zero, ou desistia, ou trocava por um número que passasse. O indicador era **enviesado para cima**, e o viés era invisível porque a recusa acontecia antes de qualquer gravação. **E isso cria uma descontinuidade na série.** A partir de 13/09/2026 podem aparecer zeros de colaborador que antes não existiam. Quem comparar médias de antes e depois tem de saber disto. #### Ao resolver — já resolvido `validarFormularioSalvar` passou a usar `($request[...] ?? '') === ''` nos três lugares, o que trata os três de forma idêntica e de quebra fecha o vazamento do D180. `PesquisaNpsService::salvar` grava com `setNota($request[...])`, sem `empty()`, então o zero chega ao banco inteiro — conferido antes de liberar. #### A SUSPEITA MAIOR, CONFERIDA E DESCARTADA `empty()` sobre valor numérico é defeito sistêmico? **Não.** Varridas as 15 ocorrências de `empty($request['...valor/nota/quantidade/desconto...'])` em `module/`: `desconto` zero significa "sem desconto"; `quantidade` zero não faz sentido; `VendasProdutosController:114` já trata o zero explicitamente (`empty(...) || ... == 0`); e a cota-parte de comissão extra igual a zero seria registro inócuo. O caso do NPS era o afiado, porque ali o zero é **resposta**, não ausência. --- ### D184 — Nenhuma suíte exercitava a validação de controller das rotas públicas do ERP — CORRIGIDO em 13/09/2026 — CORRIGIDO em 05/10/2026 Os três defeitos da pesquisa de satisfação — D178, D180 e D183 — moram no mesmo lugar: um controller de rota **pública** do ERP. E os três foram achados à mão, dois deles abrindo a página no navegador. O que existe hoje não alcança esse lugar: | instrumento | o que cobre | |---|---| | `tests/Caracterizacao` | repositórios e serviços, por chamada direta | | `tests/Contrato` | as rotas de `/api`, do aplicativo instalado | | `ensaiar-fluxo-adm-api`, `...-permissao-...`, `...-recusas-...` | `/adm/api` | | `ensaiar-escritas-do-aplicativo` | `/api` | | `conferir-rotas-sem-login`, `conferir-guarda-do-erp` | **quem** pode entrar, não **o que** a ação responde | Os portões de rota dizem que `/pesquisanps` é pública e legítima. Nenhum deles pergunta o que ela devolve — e foi por isso que um 500 na cara do cliente sobreviveu sem ninguém notar. #### UMA CORREÇÃO À TABELA ACIMA, achada escrevendo o conserto Falta um instrumento nela, e ele parecia cobrir isto: `medir-telas-no-postgres.php` pede **todas** as telas do ERP e exige que nenhuma responda 500. Mas ele **entra com sessão antes de medir** — *"sem sessão, toda tela responde 401 e a medição não diz nada"*, escrito no próprio roteiro. Ele mede a superfície **autenticada**. A pública continuava sem ninguém. #### COMO FICOU `scripts/ensaiar-rotas-publicas-do-erp.php` — **18 casos** quando este débito fechou, e **23 hoje**: o D180 acrescentou cinco no mesmo dia, ao fazer a gravação depender da sessão do formulário (os casos 8 e 9). Ele é o único ensaio da casa que **não faz login**. Os outros quatro entram por `/autenticacao/entrar` antes de medir; este não, e isso é a propriedade que ele mede: se alguma destas rotas passar a exigir sessão, os casos ficam vermelhos. | casos | o que afirmam | |---|---| | 1 | `GET /pesquisanps` responde 200 **e traz o teclado** — a página sem parâmetros *é* o teclado | | 2 | telefone vazio → 200 com a recusa de comprimento | | 3 | telefone de 15 caracteres que não casa ninguém → 200 — **o canário do D178** | | 4 | o telefone do cenário monta a pesquisa, com as duas perguntas e a do colaborador | | 5 | telefone de dois clientes **recusa** em vez de sortear | | 6 | `POST /salvar` sem campos não traz `Warning` nem `/var/www` — **D180** | | 7 | nota **zero** num colaborador é aceita — **D183**, provado sem gravar | | 8–10 | as URL-capacidade dão **404** sem a capacidade — 200 ali seria o defeito | | 11–12 | as duas páginas de agradecimento respondem 200 | **O caso 3 é o que pega o D178**, e vale explicar por quê: o caso 2 para no `strlen` e nunca chega ao repositório. Um telefone de 15 caracteres que não casa ninguém **alcança** a consulta — e era ali que o método inexistente estourava. **E o caso 7 prova o D183 sem gravar nada:** manda zero no colaborador e **omite** a recepção. A validação falha pela recepção, então nada é salvo, e a mensagem não pode citar o colaborador. Se citar, o zero voltou a ser tratado como ausência. #### ELE ESCREVE, E DEVOLVE TUDO O cenário das fixtures **não servia**: as vendas recentes dele têm `status = 3`, então nenhum cliente de fixture tem pesquisa pendente na janela. Sem isso os casos 4, 5 e 7 passariam por vacuidade — a mensagem não citaria colaborador porque não **há** colaborador, e não porque o zero foi aceito. Então ele troca o telefone de três clientes de fixture e cria três vendas com item na faixa **90008xxx**. A data é `NOW()`, e não um literal: a janela do NPS é relativa a hoje, e uma data cravada sairia dela sozinha no mês seguinte — o ensaio começaria a falhar sem que nada tivesse mudado. Tudo volta num `finally`, cada valor ao que foi **lido** antes, e ele confere resíduo zero antes de sair. #### FALSIFICADO, e essa é a parte que dá valor ao resto Portão que não fica vermelho é pior que portão nenhum. Reintroduzindo cada defeito, um a um, e conferindo que o caso certo cai: | defeito devolvido | saída | caso que caiu | |---|---|---| | o método do D178 volta a não existir | 1 | 3 | | a ambiguidade volta a sortear | 1 | 5 | | o campo volta a ser lido sem `??` | 1 | 6 | | o colaborador volta ao `empty()` | 1 | 7 | Os quatro arquivos foram restaurados byte a byte depois. #### ONDE ELE RODA No job `caracterizacao-postgres`, **primeiro entre os ensaios** — ele lê o telefone e o status dos três clientes **antes** de trocá-los, e rodando depois de quem mexe no cenário devolveria o valor do vizinho. Executado nos **dois bancos** antes de entrar: 18 de 18 no MySQL e 18 de 18 no PostgreSQL. Isso não é zelo: o job é o do PostgreSQL, e hoje mesmo cravar `1`/`0` num INSERT passou no MySQL e quebrou lá — `vendas.status` é `integer`, `nps_respondido` é `smallint` e `comanda_temp` é `boolean`, três tipos na mesma tabela (D128). #### O QUE ELE NÃO COBRE, dito para ninguém supor que cobre O **salvamento bem-sucedido** da pesquisa, que gravaria uma resposta de NPS — a caracterização cobre essa metade, no repositório, nos dois bancos. O `POST` de `/fidelidade/salvarDados`, pelo mesmo motivo. E a família `/autenticacao`, de propósito: ela redefine senha, e um ensaio não é lugar de exercitar isso. #### O `POST /fidelidade/salvarDados`, no banco de teste — CORRIGIDO em 05/10/2026 O que ficou de fora por escrito tinha um motivo — a rota GRAVA, e o ensaio público corre por HTTP no banco de desenvolvimento — e o motivo caiu com o `ControllerEmProcesso`: o `FidelidadeController` de verdade despachado no banco de teste, dentro da transação que o `tearDown` desfaz. A etapa 5 já tinha caso desde 04/10/2026 (`AdesaoComPesquisaTest`); a PORTA da rota não. `tests/Caracterizacao/D184SalvarDadosDaAdesaoTest.php`, doze casos (vinte e três com os do D423), com dois clientes criados no caso com hash de 8 caracteres (a cópia os reescreveu para 32): | pedido | resposta | e no banco | |---|---|---| | o par mal formado — sem id, sem hash, hash de 7 ou de 9, id que não é número | "Dados de segurança inválidos." | nada | | o par bem formado e errado — hash trocado, **o hash do outro cliente**, id que não existe | "Não foi possível localizar o cliente." | nada, nem no cliente do id nem no dono do hash | | o par certo e o campo da etapa vazio; o nome de uma palavra só na etapa 1 | a recusa da validação, com o campo | nada, e o nome fica o que era | | o par certo e a etapa 4 preenchida | `sucesso`, `pontuacao` e `proxima_etapa: 5` | a profissão, um histórico de 10 pontos e o crédito de 10; o reenvio grava o campo de novo e **não** pontua de novo (o D406) | | `GET` | 404 | nada | **Falsificado**, um mutante por vez e restaurado byte a byte: com o cliente achado só pelo id (`find` no lugar de `selecionarPorIdHash`), os casos do hash trocado e do hash do outro cliente ficam vermelhos — gravavam; sem a guarda do par bem formado, os cinco do par mal formado; sem a validação da etapa, os dois da validação. **O que ele não prova:** que a rota responde sem sessão por HTTP. Quem diz que `/fidelidade/salvarDados` é pública é o `conferir-rotas-sem-login.php` (`iscadastro-fidelidade-salvardados`) e o `conferir-guarda-do-erp.php`; o ensaio público continua sem o caso de escrita desta rota, de propósito. **A verificação do mesmo dia achou o que a tabela acima prometia sem ter:** "não pontua de novo" valia só para a grafia exata da etapa. A etapa é campo oculto, como o par, e ninguém a conferia — `-1` rendia 10 pontos, `-2` mais 10, e `04` pontuava a etapa 4 outra vez. Registrado e consertado como **D423**; os casos estão no mesmo arquivo de teste. --- ### D185 — O ramo do operador na pesquisa de satisfação era inalcançável — RETIRADO em 13/09/2026 Apareceu fechando o D180, lendo o construtor para descobrir por que `$this->sessao` era nulo. `PesquisaNpsController` chama `parent::__construct(true)` — o **modo API** do `CrudController`. Nesse modo o construtor pula o bloco inteiro que monta a sessão, e com ele `$this->usuarioId`, que **nunca recebe valor**. `criarPesquisaHtml` passa esse nulo adiante: ```php $dados['usuarioId'] = $this->usuarioId; // sempre null ``` E o template decide por ele: ```php // perguntas.phtml:4

Olá,

Cliente: ...

Telefone: ...
Última visita: ...
``` `empty(null)` é sempre verdadeiro, então **o segundo ramo nunca roda**. Ele mostra o nome completo, o telefone e a última visita — a identificação que um operador precisaria para conferir que abriu a pesquisa da pessoa certa. **E não é código órfão: há um botão que leva exatamente a ele.** A lista de vendas do ERP (`index-vendas.phtml:195`) tem um "Abrir pesquisa NPS" por venda, que abre `/pesquisanps?cli=&uni=` numa aba nova. Quem clica é o operador, autenticado — e vê *"Olá, Fulano"*, a saudação escrita para o cliente, em vez da ficha. #### A MINHA PRÓPRIA ANÁLISE ESTAVA ERRADA, e convém dizer primeiro Este registro dizia, ao ser aberto: *“a tela precisaria saber que quem a abriu tem sessão de ERP, e hoje ela não pode saber … exigiria um parâmetro próprio, e aí é decisão”*. **Ela pode saber, e sem parâmetro nenhum.** `SessaoAcl` é um invólucro de `Laminas\Session\Container`. Instanciá-lo sem argumentos não toca no banco, e `getUsuario('id')` lê o ACL da sessão devolvendo **nulo quando não há sessão** — o `?? null` que o D-de-05/09 pôs ali justamente para não imprimir aviso em requisição anônima. Uma linha resolveria. Escrevi aquela frase sem conferir. O conserto mudou por causa disso: a pergunta deixou de ser *“dá para fazer?”* e passou a ser *“vale fazer?”*. #### E NÃO VALIA. O ramo saiu. Três razões, em ordem de peso: 1. **A ficha exibe telefone numa rota PÚBLICA.** Código que mostra dado pessoal atrás de uma guarda é mais arriscado que código que não existe — a guarda pode falhar, o código ausente não. E hoje aquele ramo é o **único** lugar onde `telefone` e `última visita` do cliente apareceriam nessa tela. 2. **O operador já sabe de quem é.** Ele clica em “Abrir pesquisa NPS” numa LINHA da lista de vendas; a conferência que a ficha daria, ele acabou de fazer com o dedo. 3. **Ninguém sentiu falta, porque nunca houve o que sentir.** O ramo nunca rodou: `parent::__construct(true)` e o `$dados['usuarioId']` sempre nulo vieram na **importação inicial do ERP**, em 15/08/2026 — ou seja, o código já chegou morto a este repositório, e presumivelmente estava morto em produção antes disso. Saíram o `if/else` do `perguntas.phtml` e a linha `$dados['usuarioId'] = $this->usuarioId;` do controller, que não tinha mais leitor. O porquê ficou escrito no topo do template, onde quem for reescrever a tela topa com ele. #### O QUE **NÃO** MUDOU, e vale dizer O botão da lista de vendas continua lá, e continua funcionando: ele abre a pesquisa do cliente daquela venda. O que mudou é só o cabeçalho da tela — o operador vê *“Olá, Fulano”*, a saudação do cliente, como todo mundo sempre viu. Conferido na tela e no ensaio: `ensaiar-rotas-publicas-do-erp.php` **23 de 23** no MySQL e 23 de 23 no PostgreSQL, com os casos 4 e 7 exigindo que o formulário montado traga as duas perguntas de loja e a do colaborador. ### D186 — O roadmap publicava "112 débitos com marca (dá 118 radical)", e o número nunca existiu — CORRIGIDO em 13/09/2026, com régua escrita Descoberto em 13/09/2026, ao republicar o Artifact depois de fechar o D181. Contei os débitos resolvidos com uma régua improvisada: **deu 121**. Refiz com outra régua improvisada, **no mesmo arquivo, no mesmo minuto: deu 118**. As duas eram minhas, escritas com dez minutos de diferença. E o roadmap já estava publicado com a frase **"112 com marca (dá 118 radical)"** — uma frase que admite não saber o número e publica assim mesmo, como se o intervalo fosse uma propriedade do assunto e não do medidor. #### O defeito não estava no arquivo. Estava na pergunta "Quantos estão fechados" pressupõe **dois** estados. Este registro usa **seis**, e a diferença entre eles é exatamente a informação pela qual ele existe: | Estado | O que quer dizer | Hoje | |---|---|---:| | `fechado` | o defeito não existe mais | **119** | | `medido` | o número existe e está escrito; **o defeito continua de pé** | 7 | | `preparado` | o conserto está pronto e **desligado**, esperando a janela do corte | 1 | | `parcial` | parte fechada, parte não — e o título diz qual | 4 | | `adiado` | deixado para depois **por decisão de quem manda** | 4 | | `aberto` | sem marca nenhuma no título | 50 | Espremer seis em dois erra nas **duas** direções ao mesmo tempo: conta como resolvido o que não foi — os 7 medidos e os 4 parciais —, e some com o trabalho de quem mediu, que é o que separa um número escrito de um palpite. #### O caso que prova: o D30 O título dele termina em **"MESMO DEFEITO DO D49"**, e *toda* régua que procura verbo de fechamento no fim do título o conta como resolvido. Ele não é. Ele é uma **remissão** — foi reduzido a ponteiro em 30/08/2026 —, e o defeito que ele aponta, os 85 campos de dinheiro em ponto flutuante, continua **aberto** no D49, com a resolução adiada para depois do corte. Contar o ponteiro como conserto inventa um conserto que ninguém fez. E ele não entra na conta nem como aberto: **remissão não é débito**, e contá-la infla os dois lados da divisão ao mesmo tempo. #### Como ficou: `scripts/contar-debitos.php` A marca é escrita em **maiúsculas**, e é só isso que a torna legível: `str_contains` sem ignorar caixa separa `RETIRADO em 12/09` de uma frase que por acaso diz "retirado". Ela mora depois do último travessão do título; quando não há travessão, vale o título inteiro — foi assim que o D15, o D21 e o D47 ficaram escritos, antes da convenção existir. Esses três são os **únicos** que o atalho pega, conferido varrendo os 186. Quatro títulos cuja marca não descreve o estado ficam numa tabela de exceções, cada um com o motivo, e cada um conferido **lendo o corpo do registro** — não o título: o D30 (remissão), o D7 (marca em minúsculas, de antes da convenção), o D67 (7 de 9 corrigidas, 2 congeladas) e o D65 (o que foi medido é o segundo eixo). **Ele não é portão, e isso é escolha.** Ele conta e imprime; sai com 0 tendo débito aberto ou não — débito aberto é o estado normal de um registro de débito. Só sai diferente de zero quando **não consegue ler**, que é quando o número não vale. Pendurá-lo no `conferir-tudo.sh` acrescentaria um portão que só pode ficar vermelho numa catástrofe de formatação, e inflaria o número de portões que este projeto publica. O conjunto continua com **35**. #### Uma armadilha que a própria construção achou Escrevi no código que a ordem dos estados **importava**, "porque `7 CORRIGIDAS em 31/08/2026, 2 congeladas` tem que cair em PARCIAL". Ao falsificar, varri os 186 títulos atrás dos que disparam ressalva e conserto ao mesmo tempo: **nenhum**. A ordem é guarda para o título que ainda vão escrever, e não o conserto de um caso existente — e o D67, o caso que parecia pedi-la, ela não resolve: a ressalva dele está na palavra *"congeladas"*, que não está em lista nenhuma. Quem o segura é a tabela de exceções. O comentário foi corrigido antes de commitar: comentário que mente custa o mesmo que nome que mente. #### Falsificado em três sentidos | O que se estraga | O que ele faz | |---|---| | a expressão que acha os títulos | sai com **2** e diz `NAO LI: achei apenas 0 titulos` — recusa dar número | | tira-se a exceção do D30 | `fechado` 119 → **120**: o ponteiro vira conserto | | tira-se a exceção do D67 | `parcial` 4 → 3 e `fechado` 119 → **120**: o parcial vira completo | #### O número, agora com a régua escrita **Em 13/09/2026: 185 débitos e 1 remissão.** Não estavam mais de pé **124 de 185 (67,0%)** — fechado, preparado ou adiado por decisão; **continuavam de pé 61**: 50 abertos, 7 medidos sem conserto, 4 parciais. Esses números têm **data**, e é de propósito que estejam escritos com uma. Todo débito novo os move, e número no presente dentro de um arquivo que cresce é o defeito que este mesmo registro acabou de consertar no D184. **A fonte viva é o roteiro**, não esta linha: `php scripts/contar-debitos.php` responde a qualquer hora. O que ele **não** faz: não lê o corpo do débito. Um título que diz CORRIGIDO sobre um débito que voltou passa limpo. É o limite do método, e é o mesmo do `conferir-debitos-repetidos.php` ao lado. ### D187 — O CI parou de rodar por cobrança da conta — MEDIDO DE NOVO em 21/09/2026: oito dias, 18 commits nunca empurrados, e a lista dos "seis portões" estava errada — PARCIAL em 07/11/2026: a cobrança voltou e os jobs rodam inteiros desde 10/10/2026; os 5 casos que só caíam no runner (o fuso do job do MySQL, o superusuário do job do PostgreSQL) e o passo das telas do job do PostgreSQL (a concessão que batia na chave, o piso da cobertura, os 15 ensaios que caíam com ela) foram consertados; falta ver a primeira execução verde — CORRIGIDO em 07/11/2026: a execução 42360871047 (a8324f15) saiu verde inteira **07/11/2026, a primeira execução verde desde 13/09/2026.** A execução 42360871047, no commit a8324f15, saiu `success` nos seis jobs: os dois do MySQL (20 de 20 passos cada), o do PostgreSQL (45 de 46; o pulado é "O que o servidor registrou", que só roda quando um passo falha), o `verificacao` (65 de 65), o do front (8 de 8) e o do isolamento entre inquilinos (14 de 14). Até ela, dois vermelhos que só o runner via, consertados depois da fatia 102: o ensaio do D111 abria sempre `mysql:` e caía na porta do PostgreSQL (fdd1ee6e: o driver vem do `local.php`), e o ensaio da administração da VIP Class exigia o `padrao.jpg`, que fica fora do git (a8324f15: ele guarda o seu onde falta e o tira no fim). Daqui em diante, vermelho no `gh run list` é regressão. Descoberto em 13/09/2026, às 21:01, lendo o CI do commit anterior — o do D186. **As cinco tarefas falharam em seis segundos, com zero passos executados.** Não é portão vermelho: é tarefa que **nunca começou**. A anotação diz, com todas as letras: > The job was not started because recent account payments have failed or your > spending limit needs to be increased. Please check the 'Billing & plans' > section in your settings. **E não é soluço.** Mandei a execução de novo às 21:05 e ela falhou igual, com a mesma anotação nas cinco tarefas. As **sete execuções anteriores do mesmo dia** foram reais — 14 a 25 passos cada, cerca de dois minutos — e todas verdes. O bloqueio começou entre 20:33 e 21:01. #### Por que isto é grave, e não um aborrecimento Este projeto tem instrumentos que **só existem no CI**, porque dependem de serviços que a máquina local não levanta de uma vez — e são seis: | portão | o que ele defende | |---|---| | `conferir-guarda-do-erp` | a lista das 34 ações do ERP sem conferência de privilégio não cresce | | `conferir-rotas-sem-login` | as 184 rotas anônimas continuam as mesmas, cada uma numa das 95 famílias liberadas | | `conferir-linha-sorteada` | nenhuma busca nova devolve linha sorteada por falta de ordenação | | `auditar-group-by` | nenhuma consulta agregada quebra no PostgreSQL | | `conferir-referencias-docs` | nenhum caminho citado na documentação deixou de existir | | `conferir-debitos-repetidos` | nenhum par de débitos novo descreve o mesmo assunto duas vezes | Junto deles param a suíte contra os **três bancos** (MySQL 8.0, MySQL 8.4 e PostgreSQL), o isolamento entre inquilinos e os cinco ensaios da API. **E há um segundo estrago, mais traiçoeiro que o primeiro:** o commit fica com o sinal **vermelho** no histórico. Quem olhar a lista amanhã vai ver um commit falhado e concluir que o código quebrou. **O vermelho é da conta, não do código** — e é por isso que esta página existe, para que ninguém precise adivinhar. É a máxima da casa na forma mais pura: *portão que não roda é pior que portão que não existe*, porque a existência dele dá uma confiança que ele não está ganhando. #### MEDIDO DE NOVO em 21/09/2026 — o bloqueio continua, e a ficha acima envelheceu em três pontos **1. O bloqueio é real e continua.** Pedi **uma** reexecução hoje, sobre o commit que já estava no remoto — sem empurrar nada. Ela rodou às **23:31 de 21/09** e falhou em **10 segundos**, com a mesma anotação, palavra por palavra: > The job was not started because recent account payments have failed or your > spending limit needs to be increased. São **oito dias**. Medido, não suposto. **2. E há um segundo motivo, que é meu.** A última execução do CI é de **16/09**. Não porque o bloqueio tenha começado ali, mas porque **nada foi empurrado desde então**: o remoto está em `d55036d`, e há **18 commits locais** que o GitHub nunca viu. Isso muda o diagnóstico. A ficha acima diz que *"os commits ficam vermelhos no histórico"* — mais traiçoeiro que vermelho é **não estar lá**. Dezoito commits de trabalho, incluindo os consertos do D189, D191, D192, D194, D195, D196 e D197, não existem para quem olha o repositório. **Empurrar é decisão do dono**, e não foi feito: com o bloqueio de pé, cada push vira mais uma fileira de vermelho no histórico, e o vermelho continua sendo da conta. **3. A lista dos "seis portões que só existem no CI" está errada — nos dois sentidos.** Conferido um a um: | portão que a ficha nomeia | corredor local | CI | |---|---|---| | `conferir-guarda-do-erp` | **está** | está | | `conferir-rotas-sem-login` | **está** | está | | `conferir-linha-sorteada` | **está** | está | | `auditar-group-by` | **está** | está | | `conferir-referencias-docs` | **está** | **não está mais** | | `conferir-debitos-repetidos` | **está** | **não está mais** | **Os seis rodam no corredor local.** A frase que justificava o alarme deixou de ser verdade em algum momento que ninguém registrou, e continuou sendo repetida — inclusive por mim, em voz alta, no fim de cada sessão. **4. E os que de fato só existem lá são 14, não 6.** Derivados do `ci.yml` contra o `conferir-tudo.sh`, e não digitados: | estado | quantos | quais | |---|---:|---| | **medidos aqui, verdes** | **3** | `verificar-schema`, `verificar-schema-postgres`, `ensaiar-erro-json-da-api` | | pedem o banco de CONTRATO | 8 | os cinco `ensaiar-*` e os três `medir-*-no-postgres` | | estoura o tempo desta máquina | 1 | `medir-cron-no-postgres` | | não rodado de propósito | 1 | `ensaiar-fechamento-da-agenda` — ESCREVE | | roda, mas sozinho | 1 | `rodar-contrato.sh` | | preparo, não é portão | 2 | `definir-senha-contrato`, `gerar-ddl-postgres` | **E o motivo de serem "só do CI" é mais bobo do que parecia.** Os dois do PostgreSQL resolvem o host `postgres`, que é o nome do serviço no compose: do shell do Windows esse nome não existe. De dentro do contêiner, com `docker exec`, rodam e passam. **Ninguém tinha tentado** — e por isso ficaram meses classificados como inalcançáveis. Os outros oito têm razão de verdade: pedem o **banco de contrato** e a senha que o `definir-senha-contrato.php` grava nele. Chegar lá exige repontar o `local.php`, que é a disputa que já deu falso vermelho duas vezes esta semana — então o roteiro novo **não reponta nada sozinho**, e diz o que fazer. #### O que entrou **`scripts/conferir-lacuna-do-ci.sh`** — deriva a lista a cada execução, **exige que cada passo exclusivo seja declarado** com o que ele defende, e roda o que dá. Na primeira execução ele me pegou: eu tinha deixado o `rodar-contrato.sh` de fora da tabela. O que não roda sai como **NÃO MEDIDO**, nunca como verde. **Gatilho manual no CI** (`workflow_dispatch`). Até hoje o CI só disparava por `push`, então testar se a cobrança voltou exigia **empurrar commit** — e com o bloqueio de pé, cada push vira mais uma fileira de vermelho. Agora é uma pergunta, sem publicar nada: ``` gh workflow run CI && gh run list --limit 1 ``` Tarefa que falha em segundos é cobrança; tarefa que roda minutos é o CI de volta. #### Dois falsos vermelhos meus, no caminho **O primeiro custou uma rodada inteira.** Onze portões saíram vermelhos, e eu sabia que ao menos um deles estava verde — era o Git Bash convertendo `/var/www/html/...` num caminho do Windows antes de o `docker` ver. O medidor mentindo antes do código, de novo. **O segundo era de classificação.** Oito portões saíram como VERMELHO com saída **2** — e 2, nesta casa, é *"não consegui medir"*, não *"achei defeito"*. Os próprios roteiros dizem isso no cabeçalho. Contar "não medi" como vermelho é o mesmo erro do D50 ao contrário: enche o relatório de alarme falso até ninguém mais olhar. **Um terceiro quase aconteceu, e a guarda de outra pessoa impediu:** o `medir-cron-no-postgres.php` pede rotinas de cron, e **duas delas cobram de verdade pelo Asaas**. A `const FORA` do próprio roteiro, escrita em 14/09/2026, as exclui. Conferido antes de deixar rodar. #### Continua de pé, e é seu **Só você destrava a cobrança**, em *Billing & plans*. E só você decide empurrar os 18 commits. Enquanto nenhuma das duas acontece, **11 dos 14 continuam não conferidos** — e o roteiro novo diz isso em voz alta, toda vez. #### O que foi feito enquanto isso Os **seis** portões de CI foram rodados **à mão** contra o commit `516982c`, e os seis saíram com 0. Somados aos 35 do `conferir-tudo.sh` e à suíte de 638 testes, este commit específico está verificado. **Isso não se estende ao próximo:** cada commit daqui para a frente precisa da mesma rodada manual enquanto o CI estiver parado, e é exatamente o tipo de disciplina que ninguém sustenta por muito tempo. #### O que ele precisa, e de quem **Da sua conta do GitHub, em *Billing & plans*.** Não é coisa que se conserte no repositório, e não é coisa que eu vá mexer: é pagamento. Assim que voltar, a primeira execução verde fecha este débito — e vale olhar se ela roda os mesmos 14 a 25 passos por tarefa, e não uma versão encolhida. #### Em 15/09/2026 os quatro que ainda eram só-CI vieram para o corredor local **A tabela dos seis, acima, envelheceu — e envelheceu em silêncio, que é exatamente o defeito que ela própria descreve.** Medido hoje, portão a portão: três dos seis já rodavam no `conferir-tudo.sh` (`conferir-linha-sorteada`, `conferir-referencias-docs` e `conferir-debitos-repetidos`), e um quarto que a tabela não lista tinha entrado no CI depois dela. O que estava fora do corredor local, e o que cada um defende: | portão | estava só na CI | agora | |---|---|---| | `conferir-guarda-do-erp` | `ci.yml:125` | `conferir-tudo.sh`, `guarda do erp` | | `conferir-recorte-por-unidade` | `ci.yml:133` | `conferir-tudo.sh`, `recorte por unidade` | | `conferir-rotas-sem-login` | `ci.yml:159` | `conferir-tudo.sh`, `rotas sem login` | | `auditar-group-by` | `ci.yml:346` | `conferir-tudo.sh`, `group by no postgresql` | **O `conferir-recorte-por-unidade` é o mais gritante dos quatro** — e é preciso ser exato sobre o porquê, porque a primeira versão deste parágrafo errava. **O portão não é novo:** nasceu em 07/09/2026 e entrou no `ci.yml` no mesmo commit (`89de19c`), que aliás já se chamava *"o portão do D131 não estava na CI"*. Ele rodou de verdade, no CI, de 07 a 13/09. O que é novo é a **41ª entrada** dele: `autenticarComoAction`, acrescentada hoje (`511f32b`) para vigiar a porta da personificação do D127. Essa entrada **nunca foi executada por corredor nenhum** — nasceu dois dias depois de o CI parar, num portão que só vivia lá. A falsificação daquele débito foi feita à mão, e a partir de hoje ela também é executada a cada `conferir-tudo.sh`. É a máxima da casa se cumprindo sobre o trabalho de hoje: *portão que não roda é pior que portão que não existe*, porque a existência dele dá uma confiança que ele não está ganhando. Medi os quatro do host antes de pendurá-los: **os quatro saem com 0**. `auditar-group-by` nem toca no banco; `conferir-rotas-sem-login` precisa do `vendor/autoload.php`, que localmente existe — foi justamente a falta dele que o fazia falhar no runner com saída 255 antes de 11/09. **Isto não substitui o CI**, e a distinção importa: lá eles rodam em máquina limpa e contra três bancos. Substitui o **nada**. O corredor passou de 40 para **44** portões, e a rodada completa depois da mudança: 43 verdes, 1 vermelho conhecido (o `agendamento das rotinas`, do D50), nenhuma falha inesperada. #### Em 07/10/2026, a outra direção (D441) Tudo acima pergunta o que o CI roda e o corredor não. A pergunta contrária -- o que o corredor roda e o CI não -- ficou sem dono até 07/10/2026, e a resposta era 36 roteiros, mais os testes do front, que a primeira versão da conta nem enxergava. Ela mora no **D441**: os 28 roteiros e os testes do front ganharam passo no `ci.yml`, e 8 ficam fora com o motivo numa segunda tabela do mesmo `conferir-lacuna-do-ci.sh`, que agora para nas duas direções. Ele roda, só a declaração, no `conferir-tudo.sh`; no job `verificacao` ele está ESCRITO, como os outros passos novos. Nenhum deles rodou no runner -- nem o da própria lacuna: o bloqueio desta página continua. #### Em 07/11/2026, a fatia 102 (CI-VERDE-NO-RUNNER): a cobrança voltou, e o vermelho passou a ser do código **A parte do dono está feita.** `gh run list` mostra jobs rodando de novo desde 10/10/2026, com todos os passos, em cerca de 4 a 4,5 min por execução -- e nenhuma verde nas 200 últimas. Os vermelhos não eram mais da conta. Lidos com `gh run view --log-failed` nas execuções **42338443751** (o commit 696791ae) e **42347466612** (o dd0b4ae3, o HEAD de então), os mesmos cinco casos, só no runner: | job | caso | o que era | |---|---|---| | MySQL 8.4 e 8.0 | `NascimentoSemHoraTest::testNoDiaSemMeiaNoiteODiaVemAMeiaNoite` | `'UTC'` no lugar de `'America/Sao_Paulo'`: o PHP do `setup-php` roda em UTC, e o job do MySQL não fixava o fuso (o do PostgreSQL fixa, desde 04/09/2026) | | MySQL 8.4 e 8.0 | `RegrasDoNpsTest::testOMesEODiaDaResposta` | `1785553199` contra `1785542399`: o texto `'2026-07-31 23:59:59'` lido no fuso do processo (UTC) e o mesmo texto em São Paulo, 3 h de diferença | | PostgreSQL | `TemporariaSemAChaveComORecorteTest`, os três conjuntos | "a linha passou para outro inquilino (1 linha)": o job entra como o `POSTGRES_USER` do serviço, que a imagem cria **superusuário** -- e superusuário ignora o RLS mesmo com o `FORCE`. Aqui a suíte entra como `bvip_app`, que não é | **Nenhum era defeito da aplicação, e nenhuma linha de produção mudou.** O conserto é do ambiente ou do caso: - **O fuso do job do MySQL**, em `.github/workflows/ci.yml`: `ini-values: date.timezone=America/Sao_Paulo` no `setup-php` (como o job do PostgreSQL e o `docker/php/php.ini`), e `SET GLOBAL time_zone='-03:00'` no banco, ao lado do `sql_mode` (como o `--default-time-zone` do `docker-compose.yml`, que registra por que só o PHP em São Paulo com o banco em UTC é a combinação que derruba os royalties das 21h à meia-noite -- e o job roda de noite). E a **afirmação** de que os dois pegaram, no "Configurar o ambiente": `test` do `date_default_timezone_get()` e do `@@global.time_zone`, para que um `ini-values` que não pegue fique vermelho ali, e não quinze passos depois. - **O caso do PostgreSQL** mede o comportamento por quem não ignora o recorte: quando a conexão é `rolsuper` ou `rolbypassrls`, ele cria, dentro de um ponto de salvamento, um papel sem nenhum dos dois, passa a ele a posse da temporária (para que o `FORCE` continue sendo o que se mede, como com a `bvip_app`) e faz `SET LOCAL ROLE`; o `ROLLBACK TO SAVEPOINT` desfaz o papel, a posse e o papel da sessão juntos. Quando a conexão não ignora (aqui), mede direto, como antes. O comentário do `ci.yml` que dizia "o dono ignora RLS" ganhou o porquê exato: ignora por ser superusuário. **Provado aqui, e não só escrito:** - com o PHP em UTC (`php -d date.timezone=UTC`, a mesma suíte montada como o CI monta), os dois do MySQL caem com os **mesmos números do runner** (`1785553199` contra `1785542399`); com `-d date.timezone=America/Sao_Paulo` (o que o `ini-values` faz), `NascimentoSemHoraTest|RegrasDoNpsTest|CampanhaAudienciaTest` dão 57 de 57. O `TZ` do sistema não entra: o `date.timezone` do `php.ini` manda no PHP, aqui e no runner; - o PostgreSQL montado como o do CI e lido como **superusuário** (o `franquiabv` daqui, `rolsuper`): o caso de antes cai nos três conjuntos com a mesma frase do runner; o novo passa (3 de 3, 39 asserções -- as 3 a mais por conjunto são as do papel); sem o `SET LOCAL ROLE`, cai nos três com "o papel da medida não ignora o recorte". Nenhum papel sobra no servidor depois (`pg_roles`, 0). **O que resta, e por que é PARCIAL:** ver a primeira execução verde no runner. O commit desta fatia é o que a dispara; o que ela deve mostrar está no D441. A memória "o CI parou por cobrança" está atrasada desde 10/10/2026: os jobs iniciam. #### Em 07/11/2026, a verificação da fatia 102: os cinco não eram tudo -- o passo das telas do PostgreSQL A frase de cima dizia que "o que restava eram estes cinco casos". **Não era verdade**, e a verificação achou lendo execuções mais antigas: as duas lidas pela fatia caíam na caracterização do PostgreSQL e pulavam os 28 passos seguintes, e atrás dela havia outro vermelho, determinístico, que nenhuma das duas mostrava. - **A concessão batia na chave.** O passo "Telas do ERP (nenhuma pode responder 500)" dá ao gerente de fixture (90001001) todas as funcionalidades de fixture antes de medir, com um `INSERT ... SELECT` sem desvio. As fixtures já lhe dão dez delas, e desde 17/10/2026 (788c1e79) o `postgres/schema.sql` tem a unicidade `(inquilino_id, usuario, funcionalidade)`. Nas execuções 39085954433 (18/10), 41372978356 (02/11), 41782686665 (04/11) e 41940012867/41987442908 (05/11) a caracterização do PostgreSQL saiu VERDE e este passo caiu com `duplicate key value violates unique constraint "privilegios_usuarios_inquilino_id_usuario_funcionalidade_unico"`, pulando os 27 seguintes. De 06/11 em diante ficou escondido atrás do `TemporariaSemAChaveComORecorteTest`. O `scripts/medir-telas-no-postgres.sh` tinha o mesmo `INSERT` nos dois ramos: no do PostgreSQL ele abortava o roteiro; no do MySQL (a unicidade `uq_privilegios_usuarios_usuario_funcionalidade` do `mysql.sql`) o `|| true` engolia o erro, e o MySQL era medido só com as dez. - **E antes da chave, o piso.** A última execução com o passo verde foi a 38790993312 (15/10, df9321b7: 117 de 246). A seguinte, 38814125072 (4693b8f2), deu 116 -- vermelho pelo piso da cobertura, dois dias antes da chave. Ninguém viu: o passo cai antes de imprimir a lista, e de 17/10 em diante nem chegava a medir. - **E depois da medição, os ensaios.** O bloco do `ci.yml` dizia que este passo vinha "POR ÚLTIMO", porque concede privilégios; hoje 27 passos vêm DEPOIS dele, e a maioria dos ensaios monta o próprio cenário de privilégio do mesmo gerente. Com todas as telas concedidas, 8 batiam na mesma chave ao gravar o privilégio que testam, 6 recusavam rodar ("o gerente já tem privilégio de ... que não é deste ensaio") e o de recusas via a VIP Class recusar pelo motivo errado (3 recusas). Desde 15/10 nenhum passo depois das telas rodou no runner, e os ensaios que entraram depois disso nunca rodaram lá com a concessão na frente. **Medido aqui, e não só lido.** O job do PostgreSQL repetido na ordem do runner, num banco descartável montado como o do CI e lido como superusuário (`franquiabv_pgci102`, apagado no fim), com a concessão e a retirada LIDAS do `ci.yml`: com o `ci.yml` desta fatia antes da verificação, o passo das telas saiu 1 (98 de 227, piso 117) e 15 ensaios caíram (14 com saída 2 e o de recusas); com a correção, **os 31 passos saíram 0** -- o contrato, a concessão, as telas, a retirada, a rotina do cache, os 23 ensaios, o medidor da `/adm/api`, a concessão de novo e os relatórios. Fora da repetição, pelas regras da casa: a caracterização (desfeita caso a caso; roda inteira no ciclo), as rotinas de cron (no lugar delas, só a do cache que o relatório de atendimentos lê) e o fechamento da agenda. **O conserto**, sem mudar código da aplicação: - a concessão é repetível -- `ON CONFLICT (inquilino_id, usuario, funcionalidade) DO NOTHING` no `ci.yml` e no ramo do PostgreSQL do roteiro, `NOT EXISTS` no do MySQL; - o passo das telas lê o maior id antes de conceder e, depois da medição, **retira o que concedeu** (as linhas do gerente acima daquele id; as das fixtures ficam): os ensaios veem o banco como no corredor local; - o passo dos relatórios, o último, concede de novo (o gerente precisa delas para pedir os relatórios); - o `scripts/medir-telas-no-postgres.sh`, que roda as telas, o cron, 17 ensaios e os relatórios na mesma ordem, ganhou o mesmo: as duas concessões viram variáveis usadas antes das telas e antes dos relatórios, e a retirada vem depois das telas, nos dois ramos. Rodado inteiro uma vez nesta verificação, antes da retirada, nos dois bancos: as telas deram 98 de 227 no PostgreSQL e no MySQL (o MySQL, com a concessão inteira pela primeira vez), nenhuma com erro do servidor, e os ensaios depois delas caíram como no runner (o de cupons na chave). Depois da retirada ele não foi rodado de novo: chama o `medir-cron-no-postgres.php`, que pede pela rota as rotinas de cron -- o `relatoriosRoyaltiesAtualizar` entre elas --, e a casa não as pede fora do CI sem necessidade; o caso abaixo roda os textos dele; - o piso da cobertura desceu de 117 para 98, com o motivo escrito ao lado da constante: a administração antiga da VIP Class saiu inteira (18 ações, 13 alcançadas em 15/10), saíram os relatórios antigos de clientes, de evasão, de aniversariantes e o de franquias potenciais, e telas fechadas ao gerente ou movidas para o /novo deixaram de ser alcançáveis (as Unidades, c02d7cee, de 4 para 7 não alcançadas). A conta não foi feita ação por ação -- a lista de 15/10 não existe mais --; o alcance de hoje é determinístico e é o piso novo. **O caso que pega:** `ConcessaoDoUsuarioDeFixtureTest` lê o TEXTO das concessões no `ci.yml` (as telas e os relatórios) e no roteiro, e o roda duas vezes contra as fixtures, nos dois bancos; e roda o maior id de antes, a concessão e a retirada do passo das telas, conferindo que as linhas do gerente voltam a ser as das fixtures, pelo id -- e o mesmo com o maior id, a concessão e a retirada de cada ramo do roteiro, no banco dele. Mutantes, um por vez, vermelhos: cada concessão sem o desvio (as duas do `ci.yml` e as duas do roteiro, com a mesma frase do runner), o passo sem a retirada, a retirada antes da medição, e a retirada do roteiro que tira todas as linhas do gerente (nos dois ramos). ### D188 — Dois demos do jcrop executavam POST sem login no webroot, e um deles imprimia o caminho do servidor — REMOVIDOS em 14/09/2026 — CORRIGIDO em 07/10/2026: a pasta `demos` saiu inteira Achado em 14/09/2026, e achado **por um parágrafo**. Ao escrever o portão do D34 eu redigi a seção "o que ele não cobre", dizendo que ele olhava só os sete diretórios de upload e não o resto do webroot. Escrever a limitação foi o que me fez medi-la. Três `.php` estavam versionados sob `public/`. Um é o front controller. Os outros dois eram demos da biblioteca de recorte de imagem: | Arquivo | O nginx | O PHP | |---|---|---| | `public/global/plugins/jcrop/crop-demo.php` | serve, 200 | **executa** | | `public/global/plugins/jcrop/demos/crop.php` | serve, 200 | **executa** | A regra de `deny all` do D34 cobre `arquivos`, `contratos`, `banners`, `assistentes`, `vip-class`, `visagismo`, `logs` e `layout/img/avatar`. Não cobre `global` — e não deveria: ali moram o CSS e o JS de todo o ERP. O problema nunca foi a regra; era haver `.php` naquele diretório. #### A medição, e ela não é teórica Um POST sem sessão, sem cookie, sem nada: ``` POST /global/plugins/jcrop/crop-demo.php x=0&y=0&w=10&h=10 -> code=200 tipo=image/jpeg bytes=1485 ``` `Content-Type: image/jpeg` é a prova de que o PHP rodou: quem produziu aquilo foi o `imagejpeg()` do arquivo, não o nginx servindo texto. E os dois não são iguais. O `crop-demo.php` embrulha cada `$_POST` em `intval()`. O `demos/crop.php` **não**, e passa a string crua para uma função que exige `int`: ``` POST /global/plugins/jcrop/demos/crop.php x=abc&y=0&w=10&h=10 -> Uncaught TypeError: imagecopyresampled(): Argument #5 ($src_x) must be of type int, string given in /var/www/html/public/global/plugins/jcrop/demos/crop.php:21 Stack trace: #0 ...(21): imagecopyresampled(Object(GdImage), Object(GdImage), 0, 0, 'abc', '0', 150, 150, '10', '10') ``` O caminho absoluto do servidor, o número da linha e os argumentos, para quem mandar quatro campos de formulário. #### O tamanho real, dito sem inflar Não é execução remota e não é leitura de arquivo arbitrário: a imagem de origem é **fixa** no código (`./demo_files/image5.jpg`), e o destino é 150×150 fixo. O que de fato havia: 1. **Superfície sem dono.** Dois endpoints sem login que ninguém sabia que existiam, em código que nunca foi escrito para este sistema. 2. **Divulgação de caminho e de versão** por mensagem de erro, num arquivo que não passa por tratamento de erro nenhum. 3. **Nada do ERP se aplica ali.** Não é rota do Laminas, então não passa pelo ACL, não passa pelo `ErroJsonListener` do D16 e não aparece em log da aplicação. Todo o trabalho de envelope de erro vale para quem entra pelo front controller; estes dois entravam por fora. O `display_errors` deste contêiner está `On`, e é dele que veio o rastro acima. **Se produção mostra o mesmo, não se confere daqui** — essa pergunta já está registrada no D16 e continua lá, sem mudar de dono. #### O conserto foi apagar, e custou o que tinha de custar O Jcrop **é usado**: `module/ISBase/view/layout/layout.phtml` carrega o `jquery.Jcrop.min.css` (linha 55) e o `jquery.Jcrop.min.js` (linha 731). A biblioteca fica. Os dois demos saíram, e a varredura da árvore inteira antes de apagar não achou uma citação sequer a eles — a única menção a `crop.php` no projeto era o `action` do formulário do próprio demo, apontando para si mesmo. Ficam os demos em HTML e as imagens de exemplo, que são estáticos e inertes. A pergunta "por que há demos de biblioteca vendorizada no webroot" continua de pé como arrumação, não como risco. #### O vigia `scripts/conferir-protecao-do-webroot.php` passou a valer o webroot inteiro contra uma lista de permitidos de dois itens — `public/index.php` e o `.htaccess` do esqueleto do Laminas. Falsificado: um `.php` plantado em `public/global/` derruba o portão nomeando o arquivo, e um permitido que deixa de existir derruba o portão duas vezes, acusando o órfão na lista **e** o arquivo que virou intruso. A lição vale além daqui: **escrever o que o instrumento não cobre é barato, e às vezes é a medição.** O parágrafo custou dois minutos e achou o débito. #### A arrumação que sobrava, feita em 07/10/2026 (o item CODIGO-MORTO-E-DOCS) **"Ficam os demos em HTML" estava errado:** nenhum demo em HTML foi versionado (o `git log` da pasta mostra só o `crop.php` e a `demo_files/`). O que sobrava em `public/global/plugins/jcrop/demos/` eram os **11 arquivos** de `demo_files/` -- dois CSS e nove imagens de exemplo --, servidos pelo nginx e citados por ninguém: `git grep` por `demo_files`, `jcrop/demos` e pelos nomes das imagens achou só este registro. A pasta saiu inteira (contados os alvos antes: 11 arquivos, 13 entradas com as duas pastas). A biblioteca fica: `css/` e `js/` seguem, e o `layout.phtml` os carrega como antes. O `conferir-referencias-docs.php` continua verde. **E a pasta de volta é acusada** (corrigido na verificação do mesmo dia; a primeira versão desta seção dizia que nenhum portão a acusaria). O vigia do webroot olha só `.php`, mas a remoção pôs `public/global/plugins/jcrop/demos/` em `$explicadas` do `conferir-referencias-docs.php`, porque este registro e o roadmap a citam. Se a pasta existir, o laço pula a entrada antes de marcá-la vista, e ela sai como "EXPLICACOES QUE NAO SE APLICAM MAIS" -- saída 1. **Medido:** recriada a pasta, mesmo vazia, o portão sai com 1 nomeando-a; apagada, volta a 0. Pega a pasta, e não um arquivo solto dentro de `jcrop/` com outro caminho. ### D189 — A grade da agenda lê 241.218 linhas para devolver 189, e o conserto tem duas metades que consertam coisas diferentes — PREPARADO em 21/09/2026: o código entrou, o `ALTER` espera a janela — PARCIAL, lido em 05/10/2026 — PARCIAL em 06/10/2026: os seis `DATE()` por cliente viraram faixa — PREPARADO em 07/11/2026: a migração do índice no passo 0 > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito como preparado, e o corpo diz que ele está parcial: uma parte está consertada, e a outra não. Falta: o `ALTER` do índice (colaborador, data) e a leitura do `innodb_buffer_pool_size` em produção; os seis `DATE(age.data)` na Fase 1; o índice de `filtrarClientesPrimeiraVisita`. > > **06/10/2026:** os seis `DATE(age.data)` saíram — ver "Os seis, trocados", no fim deste registro. Falta o que é da janela: o `ALTER` do índice, a leitura do `innodb_buffer_pool_size` de produção e o índice de `filtrarClientesPrimeiraVisita`. Achado em 16/09/2026 ao ligar a tela nova em `/adm/api/agendas/grade`: 200 com a grade certa, em **22 segundos**. Medido de verdade em 21/09/2026, com autorização explícita para criar e remover o índice na cópia local. **A medição derrubou três afirmações desta própria ficha.** Elas estão corrigidas abaixo, e o que as derrubou está dito em cada lugar. #### O trabalho desperdiçado, que é o defeito de verdade Os 14 colaboradores da unidade 1 somam **241.218 linhas** em `agendas`. Para desenhar **um dia**, o plano lê todas elas — e devolve no máximo 189. Razão de quase 1.300 para 1. O dia mais cheio que esses colaboradores já tiveram em toda a história tem 501 linhas. O plano é `ref` em `FK_AGENDAS_colaborador` seguido de uma busca de linha por candidato, porque `data` não está em índice nenhum e precisa ser materializada da tabela para o filtro ser avaliado. Por isso **um dia sem nenhum agendamento custa o mesmo que um dia cheio**: o preço é a varredura, não o resultado. #### Os 22 segundos NÃO transportam para produção — e isto corrige a ficha A ficha dizia "22 segundos" como se fosse uma propriedade do sistema. É uma propriedade **deste laptop**. Medido no mesmo código, mesma consulta, mesmo dia, mudando só `innodb_buffer_pool_size`: | `montar()`, dia cheio, SEM índice | pool de 128 MB | pool de 2 GB | |---|---|---| | tempo | 20,9 a 35,7 s | **0,90 s** | | páginas pedidas ao InnoDB | 1.030.260 | 989.586 | | páginas vindas do disco | 3 a 5% | **0%** | O trabalho lógico é o mesmo — 989.586 contra 1.030.260 páginas. O que muda é caber na memória. `agendas` ocupa 546 MB (281 de dado, 264 de índice) e o buffer pool deste ambiente é **128 MB, o padrão de fábrica**: o `docker-compose.yml` não define `innodb_buffer_pool_size` e não há `.cnf` no projeto. A tabela não cabe, e cada rodada relê do disco. **O que não se sabe, e que governa a leitura deste débito:** o `innodb_buffer_pool_size` de produção. `docs/operacao-atual.md` registra a VPS como 4 vCPU / 16 GB / NVMe, mas o valor do pool nunca foi lido — e o padrão do MySQL é 128 MB **independentemente da RAM da máquina**. Se produção nunca foi ajustada, os números da coluna esquerda valem lá. Se foi, vale a direita. Ler isso é uma linha de comando e está na lista da Fase 1. #### O conserto, medido: duas metades que consertam coisas DIFERENTES A ficha dizia "as duas juntas — uma sem a outra não adianta". Meio certo, e a razão escrita estava errada. Medido, com o índice `(colaborador, data)` criado: | pool 128 MB, consulta da grade (14 chamadas) | sem índice | com índice | |---|---|---| | forma `DATE(age.data) = :data` (hoje) | 17,5 s | **0,080 s** | | forma faixa `>= :inicio AND < :fim` | 15,6 s | **0,014 s** | **A metade que conserta HOJE é o índice.** E o mecanismo não é o que a ficha supunha: é **Index Condition Pushdown**. Com `data` na folha do índice, o MySQL avalia o `DATE()` dentro do próprio índice e não busca as linhas que não casam. Isto não é leitura de rótulo no `EXPLAIN` — foi medido pelo contrafactual, que é uma variável de sessão: | com índice, pool 128 MB | ICP ligado | ICP DESLIGADO | |---|---|---| | forma `DATE()` | 0,080 s | **30,1 s** | | forma faixa | 0,014 s | 0,016 s | Desligar o pushdown devolve o custo inteiro, **375×**. A forma em faixa é indiferente a ele, porque não precisa de filtro: ela busca. **A metade que conserta AMANHÃ é a reescrita.** Na forma `DATE()`, o índice é usado com **uma** coluna de chave: o `EXPLAIN` diz `Index lookup (colaborador=200), with index condition: (cast(data as date) = ...)`. A segunda coluna não é chave de busca, é filtro varrido sobre **todo o histórico do colaborador**. A forma em faixa a promove a chave: `Index range scan over (colaborador=200 AND '2026-08-06' <= data < '2026-08-07')`. A consequência não é de tamanho, é de forma de crescimento. Medido, mesmo dia, mesmo índice, mesma resposta, variando só o histórico: | linhas do colaborador na tabela | forma `DATE()` | forma faixa | |---|---|---| | 88.604 | 24,58 ms | 0,76 ms | | 37.049 | 10,68 ms | 0,78 ms | | 26.837 | 8,24 ms | 0,85 ms | | 16.027 | 6,23 ms | 0,90 ms | | 4.281 | 2,08 ms | 0,81 ms | | 59 | 0,67 ms | 0,64 ms | `DATE()` segue o histórico numa reta (~3.300 entradas por milissegundo). A faixa é **plana**. Com só o índice, a agenda encarece a cada agendamento gravado, para sempre; com a reescrita, para de encarecer. É por isso que "a reescrita é um arredondamento" — que eu cheguei a escrever no meio da medição — está errado. #### No PostgreSQL a reescrita é OBRIGATÓRIA, e isso decide a Fase 1 **Não existe Index Condition Pushdown no PostgreSQL.** Medido no `postgres:16` deste ambiente, com as mesmas 4.000.084 linhas, com o papel de aplicação `bvip_app` (RLS ativo, sem `BYPASSRLS`) e `random_page_cost` ajustado para NVMe: | com o índice `(inquilino_id, colaborador, data)` | plano | tempo | |---|---|---| | forma `DATE(data) = :dia` | cai no índice VELHO de colaborador e descarta 88.575 de 88.604 linhas | **237,5 ms** | | forma faixa | `Index Scan` com a condição inteira, RLS incluída | **0,102 ms** | **2.330×.** Na forma `DATE()` o planejador não alcança a coluna `data` de jeito nenhum — nem com o índice perfeito disponível. Ou seja: **aplicar só o índice no MySQL produz um conserto que evapora na migração.** O ICP é uma muleta do MySQL que o PostgreSQL não oferece. Dois achados laterais do mesmo ensaio, que valem para toda a Fase 1 e não só para a agenda: - `random_page_cost` está em **4** no Postgres deste ambiente — valor de disco giratório. Com ele o planejador prefere varrer 4 milhões de linhas em paralelo a usar índice; baixando para 1,1 (valor de NVMe, que é o disco da VPS) ele passa a usar. Não é específico da agenda: é um parâmetro de custo que enviesa **todo** plano do sistema migrado. - `shared_buffers` está em **128 MB**, o mesmo padrão de fábrica do MySQL. #### A reescrita é equivalente, provado sobre a tabela inteira Trocar `DATE(age.data) = :data` por `age.data >= :inicio AND age.data < :fim` só é legítimo se devolver exatamente as mesmas linhas. `data` é `DATETIME` e **3.999.907 das 4.000.084 linhas têm hora diferente de meia-noite** — então a faixa tem de ser `[dia 00:00:00, dia+1 00:00:00)`, nunca igualdade. Verificado em **todas as 4.000.084 linhas**, não por amostra: zero linhas caem fora da janela do próprio dia, zero datas nulas, inválidas ou de ano zero. (A primeira tentativa foi amostrar 19.811 pares colaborador-dia e comparar os conjuntos de ids. Desenho ruim: mais lento, e mais fraco. A equivalência é uma propriedade de cada linha e se prova na tabela inteira com uma consulta.) #### O que o índice custa | | MySQL 8.4 | PostgreSQL 16 | |---|---|---| | tempo para criar | 11 a 20 s | 6 s | | tamanho | 81,6 MB | 120 MB | No MySQL os índices da tabela vão de 252 para 334 MB (+32%), sobre 281 MB de dado. É menor que o índice de `cliente`, que já existe. O custo recorrente é manter mais um índice por escrita em `agendas` — com 15.041 agendamentos futuros no banco inteiro, desprezível. #### O que sobra depois do conserto Com o índice posto, o próximo da fila é `filtrarClientesPrimeiraVisita`: **23.409 das 25.991 páginas** de um `montar()` em dia cheio, 90% do trabalho lógico restante. É `vendas` (2,27 M linhas) com `WHERE cliente IN (...) AND status = 1`, e `status` não está no índice. Mesma doença, outra tabela. Não foi medido a fundo nem consertado: fica registrado aqui e **não** vira débito novo, porque é a mesma forma do D189 e o conserto é o mesmo tipo de índice. #### Correções que esta medição fez em mim, e como elas apareceram Nenhuma veio de ler o código com mais atenção. Todas vieram de medir. 1. **"22 segundos"** era o laptop. Um pool de 2 GB põe o mesmo código em 0,90 s. Quem levantou: revisão adversarial, ao apontar que 128 MB é padrão esquecido e que produção tem 16 GB. Confirmado medindo. 2. **"a reescrita é um arredondamento"** — eu escrevi isso no meio da noite, depois de ver 0,080 s contra 0,014 s, e estava errado. A reescrita é o que impede o custo de crescer com o histórico. Levantado pela revisão, provado pela tabela de crescimento acima. 3. **"a contagem de páginas transporta para produção"** — retirado. `Innodb_buffer_pool_read_requests` é um contador **global**, sem escopo de sessão; um verificador mediu deriva de fundo de 1,1 milhão numa janela de 20 s, maior que o número que eu atribuía à consulta. O número que transporta é o do `EXPLAIN`: **241.218 linhas examinadas para devolver 189**, que é propriedade do plano. (As contagens de página seguem citadas acima como ordem de grandeza, e não como medida atribuível a uma consulta.) 4. **Medi um dia vazio sem perceber.** 16/09/2026 não tem agendamento nenhum porque a cópia anonimizada termina em meados de agosto de 2026 — e isso inclui o "hoje" que a tela abre por padrão. O dia vazio serve de controle do estado SEM índice, onde o custo independe do resultado; **não** serve de prova do conserto, porque COM índice ele pula duas consultas e o laço de `buscarAgenda`, e diverge do dia cheio por 21× em páginas. Dia cheio usado: 2026-08-06, 189 agendamentos. 5. **Inflei o custo do `primeiraVisita` em 120×** ao reproduzir sua consulta em SQL cru incluindo o cliente 2 — o genérico de balcão, com 63.517 vendas — que o serviço exclui de propósito. 3,18 s viraram 0,026 s ao medir o serviço de verdade em vez da minha transcrição dele. #### O conserto, quando for autorizado 1. Trocar `DATE(age.data) = :data` por faixa em `AgendaRepository::selecionarPorColaboradorData`. **Obrigatório** — sem ele o Postgres não usa índice nenhum. Nove arquivos alcançam o método, e a mudança é de predicado, não de retorno. 2. Criar `(colaborador, data)` em `agendas` — no MySQL de produção e no gerador de DDL do PostgreSQL, que é onde o esquema novo é declarado. Medido: o esquema do Postgres espelha o do MySQL, índices feitos à mão inclusive (`vendas_idx_vendas_data_status` existe lá sem estar no mapeamento Doctrine), desde que seja regerado depois. 3. Ler o `innodb_buffer_pool_size` de produção antes de prometer qualquer número em segundos. #### CORRIGIDO EM CÓDIGO em 21/09/2026 — e a segunda metade mudou de forma quando foi medida O registro acima diz que o conserto tem duas metades. Tem — mas a segunda não é "criar um índice". É **ampliar um que já existe**, e isso não foi deduzido: foi medido, depois de a forma óbvia falhar. #### A primeira metade: a reescrita, que entrou `DATE(age.data) = :data` virou `age.data >= :inicio AND age.data < :fim` em **dois** métodos — e o segundo é o achado desta passagem (abaixo). **Equivalência provada, e não por amostra escolhida:** 521 pares (colaborador, dia), **6.362 linhas comparadas**, incluindo as bordas de meia-noite e as de depois das 23h — **zero divergências**. E 4 de 4 casos no método por unidade. A referência foi a forma antiga, escrita em SQL cru ao lado. #### O GÊMEO, que ninguém tinha ligado ao D189 `selecionarPorUnidadeData` tem a mesma doença e o mesmo tamanho. Ela entra pela unidade, mas o caminho até as linhas é o mesmo: o plano percorre os **127 colaboradores** da unidade e, para cada um, busca o **histórico inteiro** dele — 3.068 linhas em média. São **389.636 buscas de linha para devolver 189**. **E isso explica um número que estava solto no registro desde 16/09:** `/adm/api/agendamentos` devolvia *"48 bytes em 73 segundos"*, reprodutível, e a causa não era conhecida. É esta consulta. #### A segunda metade: AMPLIAR, e não acrescentar O índice `(colaborador, data)` **ao lado** do `FK_AGENDAS_colaborador` conserta a grade e **não conserta a listagem por unidade**: o otimizador do MySQL continua escolhendo o índice de uma coluna. Ele estima o plano bom como **mais caro** (297.713 contra 258.624) e acredita nisso — inclusive depois de `ANALYZE TABLE`. | medido em 21/09/2026, cópia de produção | grade de um dia | listagem por unidade | |---|---:|---:| | como está hoje | 17,5 s | 21,4 s | | só a reescrita, sem índice | 15,6 s | 20,4 s | | reescrita + índice **ao lado** do velho | 0,08 s | **30,5 s** | | reescrita + índice **no lugar** do velho | **0,72 ms** | **95,7 ms** | A última linha é o conserto. E ele é **mais barato** que a forma óbvia: em vez de somar 82 MB, troca um índice de 69,6 MB por um de 81,6 — **+12 MB**. **E é seguro, conferido e não suposto:** `colaborador` é PREFIXO do composto, então ele serve à chave estrangeira. Testado no MySQL, em banco descartável: criado o composto, o `DROP INDEX FK_AGENDAS_colaborador` é **aceito**, e a restrição `FK_AGENDAS_colaborador → usuarios` continua de pé. A ordem segura é criar antes de remover, que foi a testada. #### O que entrou no repositório 1. **PostgreSQL, já:** `gerar-ddl-postgres.php` passou a **ampliar** o índice — `agendas_FK_AGENDAS_colaborador (inquilino_id, colaborador, data)`. A Fase 1 nasce com ele, sem índice redundante. A coluna de inquilino vem na frente pela regra de `fase-1-plano.md`. 2. **A reescrita**, nos dois métodos, com a medição escrita ao lado. 3. **A normalização da entrada**, que fechou o **D194** de lambuja. #### O que FALTA, e é decisão sua **O `ALTER` no MySQL de produção.** São duas linhas, nesta ordem: ```sql CREATE INDEX IX_AGENDAS_COLABORADOR_DATA ON agendas (colaborador, data); DROP INDEX FK_AGENDAS_colaborador ON agendas; ``` Criar leva **11 a 20 segundos** nas 4 milhões de linhas, e é `INPLACE` — não bloqueia leitura. Mas é mudança no servidor, e a regra desta casa desde 11/09/2026 é que nada muda lá antes da janela do corte. **Enquanto o `ALTER` não acontece, a reescrita sozinha não acelera nada** — medido: 15,6 s contra 17,5 s. Ela entrou mesmo assim por dois motivos: sem ela o índice não adianta quando chegar, e no PostgreSQL ela é **obrigatória**, porque lá não há pushdown. E continua valendo a terceira pendência do registro acima: **ler o `innodb_buffer_pool_size` de produção** antes de prometer qualquer número em segundos. #### Os seis predicados que FICARAM, e por quê Restam seis `DATE(age.data)` no mesmo arquivo, todos filtrando por `cliente`. Medido: o índice de cliente entrega **115 linhas**, e a consulta custa **15 ms**. Mesmo padrão, outra ordem de grandeza — e cada reescrita é risco. Ficam registrados aqui para não virarem descoberta futura: quando a Fase 1 chegar, eles merecem a mesma passagem, porque no PostgreSQL o `DATE()` custa mais do que aqui. #### Os seis, trocados — 06/10/2026 Os seis `DATE(age.data)` por cliente viraram a faixa do `diaInteiro()`: `horariosMarcadosPorClienteData` (o dia pedido, e "de hoje em diante" como `>= hoje 00:00:00`), `selecionarAgendaCliente` (o check-in da tela antiga), `selecionarProximoAgendamentosCliente` (o aplicativo, a V4 e a validação do agendamento), `servicosMarcadosPorClienteData` (a comanda aberta pela agenda) e `agendaPorClienteUnidadeData` (o fechamento do pagamento). O dia ausente continua vazio, como o `DATE(age.data) = NULL` dava. Não é Fase 1 por decisão de ninguém: o registro acima dizia "quando a Fase 1 chegar", e era plano. **Não acelera nada hoje, e isso foi conferido.** O índice que serve essas consultas é o de `cliente`, e `data` não está nele: no PostgreSQL da cópia, as duas formas entram em `agendas` pelo mesmo `Index Scan using agendas_fk_agendas_cliente`, com a data no `Filter` — o que pode mudar é a ordem das junções em volta, porque a estimativa de linhas muda (ver o D426, abaixo). A troca é de FORMA: a coluna nua é o que deixa um índice futuro com `data` servir de chave, e no PostgreSQL não há pushdown que disfarce a outra. **A equivalência, medida na cópia, só com `SELECT`, nos dois bancos** (o `franquiabv_dev` do MySQL e o do PostgreSQL, este com o papel `bvip_app`, RLS ativo, fuso da sessão `America/Sao_Paulo` e `data` em `timestamptz`). Nada de dado pessoal impresso: só contagens. | | MySQL | PostgreSQL | |---|---:|---:| | linhas da tabela | 4.000.085 | 4.000.084 | | linhas fora da faixa do PRÓPRIO dia (a tabela inteira) | **0** | **0** | | linhas às 00:00:00 em ponto | 177 | 177 | | linhas depois das 23h (nenhuma depois das 23:59) | 2 | 2 | | `=`: dias / pares (dia, unidade) / linhas, forma antiga contra a nova | 369 / 4.599 / 148.981 | 369 / 4.599 / 148.981 | | `=`: divergências | **0** | **0** | | `>=`: dias / pares / linhas somadas | 32 / 1.653 / 62.309.803 | 32 / 1.653 / 62.309.771 | | `>=`: divergências | **0** | **0** | | os seis métodos de verdade, HEAD contra hoje: triplas (cliente, unidade, dia) / chamadas / linhas | 4.059 / 24.790 / 660.782 | 4.059 / 24.790 / 630.686 | | ids diferentes / só a ORDEM diferente | **0** / **0** | **0** / **36** | A amostra de dias: o último e o primeiro dia de cada mês de 01/2023 a 09/2026 (a virada), os 111 dias com linha às 00:00:00 e os vizinhos deles, os 22 dias de troca do horário de verão brasileiro de 2008 a 2019 e as vésperas (no PostgreSQL a meia-noite de alguns deles não existe no fuso da sessão), os dias com linha depois das 23h, e 40 sorteados com semente fixa. As linhas por dia e unidade passam pelo Doctrine, com a mesma tradução do `DATE` (`CAST(... AS date)` no PostgreSQL) e a mesma ligação de parâmetro do código. Os seis métodos foram chamados pelo arquivo do HEAD, com outro nome de classe, e pelo de hoje, sobre os mesmos pares — os ids e a ordem. **A única diferença, e ela é de entrada, não de dado:** o texto vazio. `DATE(x) = ''` é erro nos dois bancos (`DriverException`, MySQL 1525); a forma nova devolve vazio, que é a regra do irmão `selecionarPorColaboradorData` desde 21/09 (o `DiaDaAgendaTest` a prende). Nenhum chamador manda `''`: `DataHora::stringDate()` devolve `null` para entrada vazia, e os outros mandam `date('Y-m-d')`. Medido nos quatro métodos que recebem o dia de fora, nos dois bancos; registrado aqui em vez de ajustado. **E a ordem, no PostgreSQL — o D426.** Os ids são os mesmos em todas as chamadas, nos dois bancos. A ORDEM é a mesma em todas no MySQL, e em 36 de 24.790 no PostgreSQL ela muda: 8 são empates do `ORDER BY age.data` (dois horários na mesma data e hora), e 28 são de `servicosMarcadosPorClienteData`, que **não tem `ORDER BY` nenhum**. Nele, cada forma é estável consigo mesma (as 28 chamadas que mudaram, repetidas: 28 de 28 iguais a si mesmas, nenhuma igual à outra forma); quem muda a ordem é o PLANO: na forma antiga o PostgreSQL estima 19 linhas no índice de cliente e entra pelos produtos da unidade; na nova, 1, e entra pela agenda. A ordem nunca foi definida — o banco escolhe —, e é justamente a da comanda aberta pela agenda, onde ela decide qual serviço gasta a sessão do pacote. Não foi ajustada aqui: a ordem a escrever é regra de negócio, e foi ao lote -- decidida em 06/10/2026 (pergunta 23: a ordem do id), no **D426** -- a da comanda entrou em 07/10/2026; o desempate dos quatro voltou ao lote. **E um defeito achado no caminho: o D425.** `diaInteiro()` aceitava `'2026-02-31'` e respondia pelo 3 de março, porque `createFromFormat` transborda e só avisa. Agora recusa, como o `DATE()` recusava — e a conferência entrou ANTES de a faixa chegar ao check-in. **Os casos** (`tests/Caracterizacao/DiaDoClienteNaAgendaTest.php`, 10), nos dois bancos: o último dia de um mês com horários às 00:00:00 e às 23:59:59, a véspera às 23:59:59, a virada às 00:00:00 do dia 1, a outra unidade e um inativo; "de hoje em diante" com a 00:00:00 de hoje e as 23:59:59 de ontem; o dia ausente; o dia que não existe (D425); e a FORMA, lida no SQL que chega ao banco — a coluna `data` nua nos seis. Os casos de resultado passam também sobre o `DATE()` (é a equivalência); o da forma é o que fica vermelho se um dos seis voltar. **Falsificado, um mutante por vez, restaurado pelo sha256, nos dois bancos:** | mutante | vermelho | |---|---| | `agendaPorClienteUnidadeData` com o fim fechado (`<=`) | `testOPagamentoVeODiaDaMeiaNoiteAs235959` | | `selecionarProximoAgendamentosCliente` com o início aberto (`>`) | `testOsProximosAgendamentosComecamNaMeiaNoiteDoDia` (e o da forma) | | `horariosMarcadosPorClienteData` "de hoje" com `>` | `testOsHorariosMarcadosDeHojeEmDiante` (e o da forma) | | `horariosMarcadosPorClienteData` no dia, com `<=` | `testOsHorariosMarcadosNoDiaPedido` | | `servicosMarcadosPorClienteData` com o fim esquecido | `testOsServicosDaComandaSaoOsDoDiaNaUnidade` | | `selecionarAgendaCliente` DE VOLTA ao `DATE(age.data) = :data` | só `testAColunaDataChegaNuaAoBancoNosSeis` — os de resultado ficam verdes, como devem | | `diaInteiro()` sem conferir o aviso do calendário (D425) | `testODiaQueNaoExisteNoCalendarioRecusa` | | `diaInteiro()` com o dia seguinte um segundo tarde | quatro casos de fronteira | **Por HTTP, o contrato do aplicativo passa por eles — corrigido na revisão de 06/10/2026.** A primeira versão desta passagem (e a do roadmap) dizia que nenhum ensaio por HTTP alcançava os seis, e o contrato não tinha rodado depois da troca. Errado: `ApiV4Test::testAgendaAutenticada` (`GET /api/v4/clientes/{id}/agenda`) e `AplicativoApiTest::testClienteAgendaAutenticado` passam por `selecionarProximoAgendamentosCliente`, e `testAgendaSelecionar` e `testAgendaSelecionarV2ComDados` passam pelo `diaInteiro()` que o D425 mudou (pelo `selecionarPorColaboradorData`). Rodado depois da troca: **67 de 67 no MySQL e no PostgreSQL**. Com o `diaInteiro()` recusando toda data (um mutante, restaurado pelo sha256), os quatro ficam vermelhos com 500, nos dois bancos — o contrato atravessa mesmo o código trocado. O snapshot confere o tipo, e não o valor: o resultado continua provado pelos casos e pela equivalência. **E um irmão que não era destes seis:** `totalAgendamentoPorMesAnoColaborador` filtra por `MONTH(age.data)` e `YEAR(age.data)` — função sobre a mesma coluna, no par `(colaborador, data)` do índice deste débito. Registrado no D427, com a medida. **O que continua de pé neste débito**, e é da janela: o `ALTER` do índice `(colaborador, data)` no MySQL de produção, a leitura do `innodb_buffer_pool_size` de lá, e o índice de `filtrarClientesPrimeiraVisita`. Nenhum dos três muda aqui. #### A migração do índice, no passo 0 — 07/11/2026 (a fatia 114, ESQUEMA-QUE-SO-ACRESCENTA) **O que estava de pé** era da janela: o `ALTER` do índice no MySQL de produção, a leitura do `innodb_buffer_pool_size` de lá e o índice de `filtrarClientesPrimeiraVisita`. Conferido antes de mexer: nenhuma das 28 `scripts/migracao-*.sql` fazia o índice, e o `mysql.sql` ainda dizia `FK_AGENDAS_colaborador (colaborador)`; as duas cópias locais já o tinham com `(colaborador, data)`, com o mesmo nome, desde 02/10/2026 (a F4.1 do Profissional Parceiro), e o gerador do PostgreSQL já o ampliava. **O terceiro já não estava de pé:** o índice das vendas por cliente e status (`migracao-vendas-indice-cliente-status-data.sql`, o **D308**, a resposta 294 (a)) é o que serve `filtrarClientesPrimeiraVisita`. **O que entrou:** - `scripts/migracao-agendas-indice-colaborador-data.sql`, no molde da das vendas por cliente: troca o `FK_AGENDAS_colaborador` de uma coluna pelo de `(colaborador, data)` **com o mesmo nome**, num `ALTER` só (`DROP INDEX` e `ADD INDEX`, `ALGORITHM=INPLACE, LOCK=NONE`), idempotente (já ampliado: nada; sem o índice: cria) e parando com saída 1, sem mudar nada, com o nome noutras colunas. O nome é o mesmo, e não o `IX_AGENDAS_COLABORADOR_DATA` que o item 2 da etapa 1 e este registro diziam: é o que as cópias têm e o que o gerador amplia, e o ampliar NO LUGAR, e não ao lado, é o que este registro mediu (30,5 s com os dois, 95,7 ms com um só); - a linha `| 0 | **Aplicar**` e o laço do passo 0 de `docs/procedimento-de-corte.md`, o laço do ensaio geral e o `KEY` de duas colunas no `mysql.sql`, juntos (o `scripts/conferir-passo-zero-do-corte.php` saiu 0, e o trecho que compara as colunas do índice com o mesmo nome, da 76b, o cobra); o item 2 de "O que falta" e o passo 4 da `docs/procedimento-de-corte-etapa-1.md` dizem que está feita; - o `postgres/schema.sql` regerado: igual nesse índice (o `$indicesAmpliados` já o dava). **Nas cópias**, às 18:56:47, ela disse "indice ja ampliado, nada a fazer", duas vezes, em 0,09 e 0,07 s. **Os casos:** `PassoZeroDoEsquemaQueSoAcrescentaTest` (o portão sobre uma cópia do `mysql.sql`: o controle sai 0, e com o `KEY` devolvido a uma coluna sai 1, com o motivo) e `EsquemaQueSoAcrescentaTest::testOIndiceDaGradeEDoColaboradorComAData` (o catálogo dos bancos da suíte, nos dois: o de duas colunas, e o de uma coluna fora). **Os mutantes**, um por vez, devolvidos pelo sha1: o `KEY` do `mysql.sql` de volta a uma coluna (vermelhos o controle do portão, o caso do `KEY` e o do catálogo no MySQL) e a migração trocando para `(colaborador)` (vermelho o controle do portão). **O que continua de pé, e é da janela:** rodar a migração na produção, pelo laço (o passo 4 da etapa 1), e ler o `innodb_buffer_pool_size` de lá antes de prometer qualquer número em segundos. **A correção da verificação (07/11/2026): a migração RODADA, e não só lida.** A verificação achou que só o ramo "índice já ampliado" tinha rodado (nas cópias), e que nenhum caso executava o `.sql`: a troca, o único ramo que a produção roda, e a parada nunca tinham rodado. **Ensaiada num banco descartável** (`descartavel_f114_ensaio`, apagado no fim) com a `agendas` da cópia (4.000.085 linhas, sem o cliente e a observação) na forma da produção -- o índice de uma coluna e a chave estrangeira para uma `usuarios` só com os ids -- e o buffer pool de fábrica (128 MB, MySQL 8.4.13): o `DROP INDEX` sozinho recusado (1553); a troca em 3,6 s (a tabela recém-copiada, na memória), a chave estrangeira de pé, as linhas iguais; a segunda vez "índice já ampliado" em 0,05 s; e, com o nome em `(colaborador, status)`, a parada com o `mysql` saindo 1, o `|| break` do laço parando nela e o índice intocado (num segundo descartável, `descartavel_f114_parada`, também apagado). Os 3,6 s não dizem o tempo da produção, fria e maior: lá segue a leitura do `innodb_buffer_pool_size`. **O caso que a roda a cada suíte**, no MySQL: `EsquemaQueSoAcrescentaTest::testAMigracaoDaGradeTrocaOIndiceDeUmaColunaEParaNaFormaQueNaoConhece` (o roteiro inteiro, numa tabela de ensaio com o nome trocado no texto e a chave estrangeira para uma tabela de ensaio, por uma conexão própria: a troca, a segunda vez, a criação sem o índice e a parada). **Os mutantes**, devolvidos pelo sha1: o `WHEN @colunas = 'colaborador'` com outro literal (a produção cairia na parada), a parada trocada por um `SELECT` inofensivo e o `WHEN @colunas IS NULL` trocado -- os três vermelhos nesse caso. ### D190 — Duas ações da agenda leem e ESCREVEM na franquia que o POST mandar, e a guarda do D150 nunca guardou nada — CORRIGIDO em 20/09/2026 — CORRIGIDO em 05/10/2026 Achado em 20/09/2026 por revisão adversarial da fatia da grade, e **confirmado por leitura direta do código**, não só pelo revisor. O comentário de `AgendasController::atualizarAction` (linhas 124-129) diz, com todas as letras, que o buraco foi fechado: > A UNIDADE VINHA DO POST, com a sessao apenas como valor padrao: bastava > trocar o numero para ler a agenda de outra franquia -- quem atende quem, a > que horas, com telefone no balao. E lá a correção existe: `!empty(...) && $this->unidadePermitida(...) ? ... : $this->unidadeId`. **Ela não alcançou outras duas ações do mesmo arquivo.** #### A que lê — `checkinAction:579` ```php $retorno['tabela'] = $this->getAgenda(str_replace("/", "-", $request['data']), $request['unidade_id'], true); ``` `$request['unidade_id']` sai de `getPost()->toArray()` e vai direto. Quem tem `agendas/gerenciar/escrever` numa unidade recebe a grade RENDERIZADA de qualquer outra — e, por ter `gerenciar`, cai no ramo do `tabela.phtml:43`, que põe **nome e telefone do cliente** no `data-original-title` de cada horário. O JS real já manda o campo (`mod-cadastros.js`: `unidade_id: $("#unidade").val()`); basta trocar o valor. #### A que APAGA — `abrirAction:212` e `:222` ```php $fechamento = $this->em->getReference(AgendaFechamento::class, $request['id']); ... $retorno['sucesso'] = $this->service->abrir($fechamento); // remove() + flush() $retorno['tabela'] = $this->getAgenda(..., $request['unidade'], true); ``` Id cru e unidade crua. `AgendaService::abrir()` é `remove()` + `flush()`: o fechamento de agenda de **outra franquia** é apagado, e a grade dela volta na resposta. De quebra, `getReference()` devolve proxy preguiçoso — `!empty($fechamento)` é sempre verdadeiro, e o ramo `'Não foi possível localizar.'` é **código morto**. #### O que ISTO NÃO É Não é regressão de 45f9042. `git blame` da linha 579 aponta o próprio commit do D150 — a correção nasceu incompleta. O que 45f9042 mudou foi o caminho: essa leitura passa hoje pelo `GradeDaAgendaService`, que **por desenho declarado não lê sessão** ("quem decide é o CHAMADOR"). O serviço está certo; os dois chamadores é que não decidem nada. #### O conserto, e por que ele não foi feito junto com o registro As duas irmãs no mesmo arquivo já mostram a forma: `unidadePermitida($id)` para a unidade e `agendaDaMinhaUnidade($agenda)` para o objeto — usadas nas linhas 347, 374, 421, 477 e 520. O que cobra decisão é que **hoje esses pedidos funcionam**. Passar a recusá-los muda comportamento do ERP em produção, e a regra desta casa é que nada muda lá sem validação. Fica aguardando quem manda. #### O portão que faltava `scripts/conferir-recorte-por-unidade.php` vigia 40+ métodos e não vigia estes dois. Um portão que cobre `Controller/` legado — "toda ação que recebe unidade ou id por POST confere antes de usar" — é o que impede a terceira. #### CONSERTADO em 20/09/2026 — e a raiz era pior do que este registro dizia Ao consertar, a primeira medição derrubou a premissa deste débito. Eu havia escrito que as duas ações **ficaram de fora** da correção do D150. Ficaram — mas isso era o menor dos problemas: **a correção do D150 nunca funcionou**. ```php private function unidadePermitida($unidadeId) { return $this->sessao->getAcl('agendas', 'geral') // ← DOIS argumentos || (int) $unidadeId === (int) $this->unidadeId; } ``` Com dois argumentos, `getAcl` devolve a funcionalidade inteira — `['ler' => false, 'escrever' => false]` —, que é arranjo **não vazio** e portanto **verdadeiro**. O primeiro termo do `||` era sempre `true`, o segundo nunca era olhado, e **todo mundo passava**. É o padrão exato do D123, dentro do conserto do D150. **Medido pela tela de sempre**, com `user200` (unidade 1, gerencia agenda, **sem** `Agendas unidades`), em `/mod-cadastros/agendas/atualizar`: | pediu | colunas | células | **telefones** | bytes | |---|---|---|---|---| | unidade 1 (dele) | 15 | 313 | 66 | 311.320 | | **unidade 48** | **12** | **262** | **88** | **269.643** | E a mesma forma inerte estava em `UnidadeRepository::popularComboboxAgenda`, na negação: o `AND u.id = :unidade` nunca entrava, e a lista de unidades saía **inteira** para qualquer sessão. Medido pela falsificação do teste novo: **36 unidades** onde deviam ser 1. **A tela escondia o seletor** (`index.phtml:63` usa a forma de três argumentos, certa), e por isso o buraco não aparecia usando o sistema. Esconder na tela não é guardar no servidor. #### O que entrou 1. **`unidadePermitida()`** passou a usar `getAcl('agendas', 'geral', 'ler')`. Medido depois: `user200` pedindo a unidade 48 recebe **exatamente os mesmos 311.320 bytes** da própria — a unidade pedida é ignorada. E `user1` (administrador) continua alcançando a 48, com os mesmos 269.643 bytes de antes: a guarda mede nas **duas** direções. 2. **`popularComboboxAgenda()`** idem. 3. **`checkinAction`** ganhou a conferência de unidade na grade — e o recorte da **escrita**, que era pior: `selecionarAgendaCliente` filtra por cliente e data e mais nada, então um check-in invertia o estado de todos os agendamentos daquele cliente naquele dia **na rede inteira**. O filtro ficou no controller, e não na consulta, porque ela tem oito outros chamadores. 4. **`abrirAction`** ganhou três consertos: `find()` no lugar de `getReference()` — o proxy preguiçoso fazia `!empty()` ser sempre verdadeiro e o ramo "não foi possível localizar" era **código morto** —, a conferência da unidade do fechamento, e a da unidade da grade. Medido sem apagar nada, com `acao=pesquisar`: fechamento próprio responde, o da unidade 48 e um id inexistente recebem a **mesma** recusa. #### O portão, porque isto é classe de defeito e não caso isolado `scripts/conferir-acl-como-booleano.php` — a terceira vez que esta armadilha morde. Ele varre 836 arquivos, acha as 119 chamadas a `getAcl()` e acusa as que têm **menos de três argumentos em posição booleana**. Hoje: zero. **E a falsificação dele achou um defeito nele mesmo.** A primeira versão testava o caractere imediatamente antes de `getAcl(` — que em `!$sessao->getAcl(...)` é `>`, e não `!`. Ele saiu **verde sobre o defeito que motivou escrevê-lo**. Agora descarta o receptor antes de decidir, e foi refalsificado nas **duas** formas. #### O que NÃO foi falsificado, e por quê O recorte da **escrita** do check-in está consertado e revisado, mas não falsificado: devolver o defeito exigiria um check-in de verdade no banco de desenvolvimento, e escrita ali pede autorização. A leitura das duas ações e a recusa do `abrirAction` foram medidas sem escrever uma linha. #### O recorte da escrita do check-in, falsificado — CORRIGIDO em 05/10/2026 O impedimento era o banco: devolver o defeito pedia um check-in de verdade no de desenvolvimento. Com o `ControllerEmProcesso`, o `AgendasController` de verdade é despachado no banco de teste, dentro da transação que o `tearDown` desfaz. `tests/Caracterizacao/D190CheckinEmDuasFranquiasTest.php`, cinco casos (nove com os da verificação, abaixo; quinze desde o D422 e a verificação dele, em 07/10/2026; dezessete com os dois do conserto do D437 e dezenove com os dois da verificação dele, no mesmo dia -- os cinco que provam a escolha do dia estão no D437). O cenário nasce no caso: o cliente 90001000 com um horário no colaborador 90001000 (unidade 90001000) e outro no 90001150 (unidade 90001150), no mesmo dia -- desde 07/10/2026, o primeiro dia sem horário nenhum do cliente e dos dois colaboradores a partir de daqui a 45 dias; o "daqui a 45 dias" cru caía, em 09/11/2026, no horário fixo da fixture em 24/12/2026 (D437). A sessão é o dublê com a aridade do `SessaoAcl` (arranjo com dois argumentos, booleano com três), o do `D237AgendaRecortePorUnidadeTest`. | caso | afirma | |---|---| | o check-in na minha unidade | o meu horário marca a chegada; o do mesmo cliente, no mesmo dia, na outra franquia, fica como estava | | o segundo check-in | o interruptor desfaz só o meu; o da outra continua como a outra o deixou | | com "Agendas unidades" | só o horário da unidade do horário clicado vira, e a chegada que a outra franquia registrou fica — a regra do D422, decidida pelo dono (pergunta 22) e escrita em 07/10/2026. Até essa data o caso dizia o contrário, como fato e não como desejo: os dois viravam | | a grade, pedindo a `unidade_id` da outra | volta a da minha unidade | | a grade, com "Agendas unidades" | volta a da unidade pedida | A grade é reconhecida pelo id do colaborador no botão "Agendar" de cada horário livre, e não pelo nome: a coluna mostra o primeiro nome, e os dois se chamam "Colaborador". E o colaborador 90001150 da fixture tem `visivel_agenda = 'sim'`, fora da grade (`RetratoDoHorario::NA_AGENDA`): o caso o põe em `ext_int`, com a agenda aberta, dentro da transação — sem isso, a grade da outra sairia vazia e os dois casos da grade seriam verdes pelos dois lados. **Falsificado**, um mutante por vez e restaurado byte a byte: sem o `array_filter` por `agendaDaMinhaUnidade`, os dois casos da escrita ficam vermelhos (o horário da outra franquia vira junto); com a `unidade_id` crua do POST, o caso da grade da minha unidade. #### A verificação do mesmo dia: o `abrirAction`, uma correção e uma pergunta **O `abrirAction` não tinha caso, e é a ação que APAGA.** O título fechou acima com só o check-in provado; o conserto do `abrirAction` (o `find()`, `fechamentoDaMinhaUnidade` e a unidade da grade) tinha sido medido uma vez por HTTP, só com a consulta do período, e quem o vigiava era o portão textual. O mesmo arquivo de teste ganhou dois casos, com um fechamento em cada franquia criado no caso: | caso | afirma | |---|---| | abrir o fechamento da outra franquia | a mesma resposta do id que não existe ("Não foi possível localizar.", sem `tabela`), e os dois fechamentos continuam lá | | abrir o da minha, pedindo a `unidade` da outra | o meu é apagado, o da outra não, e a grade que volta é a minha | **Falsificado**, um mutante por vez e restaurado byte a byte: sem `fechamentoDaMinhaUnidade`, o primeiro caso fica vermelho nos dois bancos — o `remove()` + `flush()` rodou, `sucesso` verdadeiro com a grade da outra; com `getReference()` no lugar do `find()`, o id que não existe estoura (`EntityNotFoundException`) em vez de recusar; com a `unidade` crua do POST, o segundo. **A correção: a consulta não tem "oito outros chamadores".** O item 3 de "O que entrou", acima, e o comentário do `checkinAction` diziam que o recorte ficou no controller porque `selecionarAgendaCliente` "tem oito outros chamadores". Tem um, o próprio `checkinAction` — conferido pelo `git grep` no `d9595c42`, o commit do conserto, e no anterior. O recorte fica no controller porque a regra é dele (`agendaDaMinhaUnidade`, com a exceção de "Agendas unidades", que vem da sessão), e o repositório não lê sessão. O comentário de produção foi corrigido. E o teste ganhou a chamada direta da consulta — os dois horários do cliente, um em cada franquia, o pré-requisito dos casos da escrita —, porque a descida do `conferir-cobertura-por-par` de 147 para 146 se apoiava só no nome dela num comentário. **A pergunta: "Agendas unidades" desfaz a chegada da outra franquia.** O caso "com 'Agendas unidades'" foi escrito como "o comportamento de antes, para quem pode", e trava a regra mais larga sem que ninguém a tenha decidido: o clique no horário da minha unidade vira também o da outra, e se a outra já registrou a chegada, ela é desfeita. Um caso novo o diz como fato. A outra porta da mesma ação (`Adm\AgendamentosController::checkinAction`) mexe só na família do horário clicado, só na unidade da sessão, e nunca desfaz. Registrado como **D422**, com a pergunta no lote -- decidida em 06/10/2026 (pergunta 22: só a unidade do horário clicado), e implementada em 07/10/2026 (no D422). ### D191 — `/adm/api` usa o mesmo código para "não entrou" e "não pode", e a tela manda refazer um login que já existe — CORRIGIDO em 21/09/2026 Achado em 20/09/2026, pela revisão adversarial da fatia da grade. O defeito que ela apontou era meu: eu havia escrito no cabeçalho de `AgendaLigada.tsx` que o componente `Erro` **distingue** "a sessão caiu" de "faltou permissão". Não distingue, e não tem como. #### A medição Toda ação de `/adm/api` abre assim: ```php if ($this->unidadeId === null) { return $this->erroPermissao('É preciso estar autenticado no ERP para usar esta API.'); } ``` `erroPermissao()` é **403 `sem_permissao`** — o mesmo par que a linha seguinte usa para "está identificado e não tem o privilégio". São **22 ocorrências em 19 controllers**, sem exceção. Do lado do navegador, `ErroDaApi.pedeLogin` trata `sem_permissao` como "entre de novo". Logo os dois casos caem no mesmo ramo, e quem está logado e só não tem `agendas/visualizar/ler` é mandado refazer um login que já tem. **O próprio `RespostaApi` avisa disso, por escrito**, no docblock do 401: > DIFERENTE DE 403, e a distincao importa: 401 quer dizer "entre de novo". 403 > quer dizer "voce esta identificado, e isto nao e seu", e a tela nao deve mandar > o cliente refazer o login por causa dele. O método certo já existe e não é chamado por ninguém nesse ramo: `erroAutenticacao()` → 401 `nao_autenticado`. #### Por que não foi consertado junto Trocar os 22 pontos é mecânico, mas o **403 está congelado em cinco roteiros**: | roteiro | o que congela | |---|---| | `ensaiar-permissao-adm-api.php` | `$ok = $status === 403` — em **39 rotas** | | `ensaiar-recusas-adm-api.php` | dois casos com `'http' => 403, 'codigo' => 'sem_permissao'` | | `medir-adm-api-no-postgres.php` | "sem sessao os onze respondem 403" | | `definir-senha-contrato.php` | "a falta de sessao ja da 403 sozinha" | | `conferir-rotas-sem-login.php` | a anotação da rota da grade | E `frontend/src/api/cliente.teste.ts` tem caso congelado afirmando que `403 sem_permissao` ⇒ `pedeLogin`. É uma mudança coordenada de API, portões e front — não cabia dentro de "conserte os seis da fatia". #### O que foi feito enquanto isso A frase falsa saiu do cabeçalho, e `Erro` passou a **dizer a verdade**: a mensagem apresenta as duas possibilidades e oferece as duas saídas, em vez de afirmar com confiança a causa errada. Tela que não tem como saber não deve fingir que sabe. #### CORRIGIDO em 21/09/2026 — e havia um argumento CONTRÁRIO, escrito, que este registro não mencionava Ao consertar, a primeira leitura achou o que o registro tinha deixado de fora: **a escolha do 403 estava defendida por escrito**, dentro do ajudante privado de `Adm\ComandasController`: > *403, e nao 401. A autenticacao do ERP e a sessao atual, e quem chega sem ela > nao esta "nao autenticado" no sentido do protocolo — nao ha desafio a devolver, > nem cabecalho `WWW-Authenticate` que faca sentido enquanto o mecanismo de token > nao existir. Quando ele existir, isto vira 401 com o desafio certo.* Registrar como defeito algo que tem defesa escrita, sem citá-la, é o mesmo erro que o D191 acusa: decidir sem olhar os dois lados. **A defesa está factualmente certa e mesmo assim não vence.** A RFC 7235 exige `WWW-Authenticate` no 401, e não há desafio honesto para sessão de cookie — inventar um esquema não registrado seria pior que omitir. **Mas o 403 também é desvio, e é o desvio que engana:** a RFC 7231 define 403 como "entendi e recuso autorizar", pressupondo credencial apresentada e insuficiente. Usá-lo para "não há sessão nenhuma" diz ao cliente que entrar **não adianta**, quando entrar é exatamente o que resolve. Então a escolha não era entre desvio e conformidade: era entre **omitir um cabeçalho que nenhum cliente desta casa lê** e **mandar a pessoa tentar o que não funciona**. E `docs/convencao-api.md` já tinha escolhido, em dois lugares — *"401 não autenticado, 403 autenticado e sem permissão"*, e *"mandar o cliente refazer o login por causa dele seria mentir sobre a causa"*. O que havia era uma **segunda verdade sobre a convenção**, morando num docblock privado que ninguém lia junto com ela. O destino que aquele texto previa continua valendo: quando o token existir, este 401 ganha `WWW-Authenticate: Bearer` e o desvio acaba. Não se esperou por ele porque o dano é de hoje. #### A superfície era melhor que o registrado, e pior do que parecia O registro dizia "22 ocorrências em 19 controllers", e estava certo na contagem. Medido, a distribuição: | forma | quantos | |---|---| | `private function semSessao()`, método pelado, sem uma linha de motivo | **14** | | idem, com a defesa do 403 por extenso | 1 (`Adm\ComandasController`) | | idem, apontando para a nota acima | 1 (`Adm\VendasController`) | | a recusa escrita à mão dentro da ação | **6** (`AgendasController` ×4, `FormasPagamentoController`, `SessaoController`) | **Vinte e duas cópias de uma regra já tinham divergido em quatro formas antes de alguém olhar** — e 14 delas seguiam um argumento que não sabiam existir. É a prova, no próprio material, do que a duplicação custa. #### O que entrou 1. **`ApiAdmController::semSessao()`**, `protected`, devolvendo `erroAutenticacao()` → **401 `nao_autenticado`**. Uma regra, um lugar. 2. **As 16 cópias privadas saíram**, e as 6 recusas escritas à mão passaram a chamar o herdado. 152 linhas removidas contra 124 acrescentadas. 3. **`RespostaApi` não foi tocado**: `erroPermissao()` continua 403 `sem_permissao`, e as **66 chamadas** que restam nos controllers são todas de falta de privilégio. O mundo do aplicativo (`/api/v4`) não foi alterado — lá o 403 está certo, porque o telefone ESTÁ autenticado e o cliente é que não é dele. 4. **`ErroDaApi.pedeLogin`** deixou de aceitar o código e passou a olhar só o status; ganhou o irmão **`semPermissao`**. Manter a cláusula do código teria desfeito no cliente o conserto feito no servidor. 5. **A tela voltou a afirmar a causa.** `Erro` tem dois ramos: "a sessão do ERP caiu — entre de novo", com o link; e "esta tela não está liberada para o seu acesso — peça a quem administra", **sem** o link. Pôr a saída errada ao lado da certa é o defeito antigo em formato menor. 6. **Um ramo invertido apareceu no caminho.** `Comandas.tsx` usava `pedeLogin` para mostrar *"sem permissão para ver X — fale com o gerente"*: a condição dizia uma coisa e o texto a oposta. Passava porque a API respondia o mesmo código nos dois casos, então acertava metade das vezes por acaso. #### Os cinco roteiros que congelavam o 403 | roteiro | o que mudou | |---|---| | `ensaiar-recusas-adm-api.php` | o **caso 1** passou a cobrar `401 nao_autenticado`; o caso 2 segue em 403 | | `ensaiar-permissao-adm-api.php` | só a mensagem de recusa; as **39 rotas continuam cobrando 403**, que é o caso dele | | `medir-adm-api-no-postgres.php` | dois comentários | | `definir-senha-contrato.php` | um comentário | | `conferir-rotas-sem-login.php` | dois comentários, com o tamanho **remedido**: 401 `application/json`, **106 bytes** — eram 403 e 104 | E um detalhe que o ensaio de recusas afirmava e deixou de valer: *"NENHUMA DAS 22 RECUSAS TEM CÓDIGO PRÓPRIO"*. Agora **uma tem** — a de sessão ausente é a única identificável pelo código sozinho. As outras 21 continuam precisando do fragmento da mensagem. #### Falsificado dos dois lados **No servidor**, por HTTP: devolvendo `erroPermissao` ao ajudante, `/adm/api/sessao` e `/adm/api/comandas` voltam a **403**; restaurado, **401**. O arquivo voltou ao sha1 `17b0c5e1`. **No front**, pela suíte: devolvendo `|| codigo === 'sem_permissao'` ao `pedeLogin`, **dois casos ficam vermelhos** — `cliente.teste.ts > separa "não entrou" de "entrou e não pode"` e `AgendaLigada.teste.tsx > sem privilégio, diz que é permissão e NÃO manda relogar`. O arquivo voltou ao sha1 `f1edb6cd`. Front: **88 casos**, de 87. `tsc --noEmit` limpo. #### A LACUNA FOI FECHADA no mesmo dia — e a escrita autorizada não foi usada Faltava a prova **em tempo de execução** de que "entrou e não pode" continua respondendo 403. Ela foi pedida e autorizada. Ao executá-la, duas coisas: **1. O roteiro da senha tem guarda própria, e ela recusou.** `definir-senha-contrato.php` respondeu: > *este banco tem 64 unidades — não é o de contrato. O roteiro TROCA SENHA, e não > roda fora do cenário de fixtures.* Ele protege exatamente o que a restrição do dono protege. **Nada foi escrito no `franquiabv_dev`**, nem com autorização na mão. **2. O cenário certo já existia, e estava fresco.** O CI roda esse ensaio contra o servidor apontado para o banco de FIXTURES, não para a cópia de produção. E o `franquiabv_cilocal` — que `rodar-caracterizacao-como-ci.sh` monta do zero — tinha a marca `4fa27696…`, **idêntica à do `fixtures.sql` de hoje**. (O `franquiabv_contrato` estava velho: `264ea148…`.) Então o procedimento foi o do `rodar-contrato.sh`, em passos discretos e sem confiar em `trap`: cópia do `local.php`, `dbname` para `franquiabv_cilocal`, proxies do Doctrine limpos, ensaios, restauração. O `local.php` voltou ao sha1 `177f82c6`, e a restauração conferiu a si mesma. **O que foi medido:** | ensaio | resultado | |---|---| | `ensaiar-permissao-adm-api.php` | **39 de 39 rotas recusaram com 403** — entrando como `colab.teste`, cujo grupo não tem privilégio nenhum | | `ensaiar-recusas-adm-api.php`, caso 1 | `sem sessao` → **401 `nao_autenticado`** | | `ensaiar-recusas-adm-api.php`, caso 2 | `sem privilegio de fechar comanda` → **403 `sem_permissao`** | | o ensaio inteiro | **23 de 23**, 22 recusas e 1 controle que tem de passar | Os dois lados da distinção ficam medidos **no mesmo arquivo**, que é o que impede uma correção futura de derrubar metade sem ninguém ver. **E a cópia anonimizada ficou intocada, provado e não alegado:** o estado de `senha`, `salt` e `token_web` dos dois usuários de fixture em `franquiabv_dev` foi capturado antes e comparado depois — **byte a byte idêntico**, sha1 `a911e9ed`. ### D192 — Quem só lê a agenda não alcança o painel de detalhe, e a tela legada mostra o balão aos dois — CORRIGIDO em 21/09/2026 Criado em 21/09/2026, ao ligar o painel de detalhe do horário. **É lacuna declarada, não desenho** — e está escrita aqui porque capacidade a menos que o ERP de hoje tem é dívida, mesmo quando a tela nova está ganhando em tudo o mais. #### O que acontece `HorarioDaAgenda` põe `disabled` no botão de quem não tem `agendas/gerenciar/escrever`. Botão desabilitado não recebe clique, então o painel não abre para essa pessoa. A tela legada **mostra o resumo aos dois ramos**: `tabela.phtml:62` monta um `title` com cliente, serviço, convênio e observação para quem só lê — sem telefone, que é o recorte de privacidade. Ou seja, hoje o colaborador que só consulta vê o balão; na tela nova ele fica com o `title` e sem o painel. #### Por que não foi consertado junto Porque arrancar o `disabled` agora **devolveria `podeEscrever` ao estado decorativo** que a revisão adversarial acusou em 20/09: ele é a única coisa que esse bit guarda hoje, e sem ação de escrita na tela não há o que ele trave. Trocar um defeito medido por outro não é conserto. #### Quando ele fecha Quando o painel ganhar **ação de escrita** — marcar, check-in, remarcar, cujos endpoints existem desde 05/09. Aí: 1. o `disabled` sai do horário e vai para os botões de agir; 2. `podeEscrever` passa a travar a ação, e não a leitura; 3. o painel abre para todo mundo, como o balão de hoje; 4. o caso `'quem só lê não alcança o painel — lacuna conhecida, D192'` muda junto, de propósito, para afirmar o contrário. O caso de teste existe **para que a lacuna não passe despercebida**. Ele é a única coisa que impede isto de virar comportamento aceito por esquecimento. #### CORRIGIDO em 21/09/2026 — e consertar expôs que a guarda estava no bit ERRADO O registro acima prescrevia quatro passos, e os quatro aconteceram. Mas ao abrir a tela para conferir, apareceu um defeito **que eu ia entregar**: a guarda do botão usava um privilégio que **não é o que a ação exige**. #### O que entrou, como a ficha mandava 1. **O painel ganhou AÇÃO DE ESCRITA:** registrar a chegada do cliente, `POST /adm/api/agendamentos/{id}/checkin`. Medido antes de ligar: a rota responde **401** sem sessão e **404** no verbo errado — o verbo declarado guarda, e o 401 é o dividendo do D191. 2. **O `disabled` saiu do horário.** `HorarioDaAgenda` **perdeu a prop `podeEscrever`** inteira, e `ColunaDoBarbeiro` também — ela só repassava, e prop morta é o estado decorativo que a revisão acusou em 20/09. 3. **O painel abre para todo mundo**, como o balão da tela legada. 4. **O caso que afirmava a lacuna virou o contrário**, de propósito, como estava escrito aqui. **Por que o check-in e não marcar/remarcar:** as três existem no servidor desde 05/09, e o check-in é a única de **um clique**. Marcar e remarcar pedem uma fatia própria. #### O DEFEITO QUE A TELA ACHOU, e nenhum teste acharia A primeira versão guardava o botão com `podeGerenciar`, o único bit que a grade publicava. **Está errado.** `podeGerenciar` é `agendas/gerenciar/escrever` e governa o **recorte** — telefone e nome inteiro. As **ações** vivem em `Adm\AgendamentosController`, que declara `funcionalidade = 'visualizar'`: criar, check-in, remover e remarcar exigem `agendas/visualizar/escrever`. Medido sobre `privilegios_usuarios` — a camada operativa, que o `Acl` lê no login, e **não** a tabela `privilegios`, que é só o molde do grupo (D157) — entre os **371 usuários ativos**: | situação | usuários | |---|---:| | **PODEM agir, e `podeGerenciar` diz que não** | **164** | | **`podeGerenciar` diz que sim, e o servidor RECUSA** | **94** | | têm os dois | 87 | | não têm nenhum | 26 | **258 de 371 — 70% — ficariam com o botão errado.** E não é estatística: foi provado **na tela, com dois usuários reais**, sem escrever nada (id inexistente devolve 404 quando o privilégio passa e 403 quando não passa, e a conferência vem antes da busca): | usuário | privilégio de escrita | grade dizia | servidor no check-in | |---|---|---|---| | `user380` | `agendas/visualizar/escrever` | `podeGerenciar: false` | **PERMITE** | | `user5` | `agendas/gerenciar/escrever` | `podeGerenciar: true` | **RECUSA** | Exatamente invertido. #### O conserto do conserto O recurso da grade passou a publicar **os dois bits**, cada um com o seu nome: podeGerenciar agendas/gerenciar/escrever -> o RECORTE podeEscreverAgendamento agendas/visualizar/escrever -> as AÇÕES O parâmetro novo de `GradeDaAgendaJson::montar()` é **obrigatório**, e não com valor padrão: padrão silencioso é como um chamador esquece e ninguém vê. Os cinco pontos do teste que chamam o formatador foram atualizados. E **o aviso da tela nomeava o privilégio errado** — dizia "falta `agendas/gerenciar/escrever`" a quem, na verdade, pode agir. Corrigido junto. #### Falsificado | o que se devolve | o que fica vermelho | |---|---| | a permissão deixa de guardar a ação | 2 casos | | o painel volta a não abrir para quem só lê | 2 casos | | a tela volta a ler o bit do RECORTE | **4 casos** | Os dois casos da distinção existem porque todos os outros movem os dois bits **juntos** — e passariam com a tela lendo qualquer um deles. Front: **94 casos**, de 88. `tsc --noEmit` limpo. #### O que a tela achou e o CSS confirmou `.agenda-detalhe-acoes` **não existia** na folha de estilo: o envoltório da ação herdaria a margem padrão de parágrafo. O jsdom não aplica CSS, então os casos ficam verdes com a classe existindo ou não. Conferido depois na tela viva, com sessão de verdade: painel aberto em "10:00, agendado · marcado pela web · Cliente 15052", com cliente, serviço, telefone, convênio e o botão **Registrar chegada** — margem de 9px, borda, `cursor: pointer`. E `button:disabled` já existia com `cursor: progress`, que serve ao estado "Registrando…". #### O que ficou para depois **Marcar e remarcar**, que pedem formulário. E o **D195**, que é a causa de raiz do defeito acima. ### D193 — O portão da cobertura por par não enxerga chamada que mora num Service, e a extração de 16/09 tirou duas do campo de visão dele — CORRIGIDO em 22/09/2026 Achado em 21/09/2026, rodando o corredor inteiro. O portão do D177 acusou: ``` ISCadastro: esperava 87 chamadas, achei 85. ``` E estava certo — mas o motivo não é "duas chamadas a menos". #### O que aconteceu `ISCadastro\Controller\AgendasController::getAgenda()` montava a grade ali dentro, com `getRepository(Agenda::class)` e `getRepository(Usuario::class)->selecionarUsuariosAgenda(...)`. Em 16/09 a receita foi **extraída** para `GradeDaAgendaService`, para que a tela nova e a antiga lessem a mesma montagem, e o controller passou a chamar o serviço. As chamadas não sumiram: **mudaram de lugar**. O glob do portão entra em `Controller/` e não em `Service/`, então ele deixou de vê-las. #### O que salvou o conjunto, e por acidente O sha1 dos 179 pares **não mudou** — mas só porque `selecionarUsuariosAgenda` e `selecionarPorColaboradorData` continuam sendo chamados dos dois controllers de `Controller/Adm/`. Fosse a extração a única via, o par teria **sumido do conjunto** e o portão teria acusado com muito mais razão. Ou seja: a contagem por módulo pegou o efeito, e o conjunto não pegou — por sorte da topologia, não por desenho. #### Por que não estendi o glob agora Porque estender para `Service/` **rebaseia um portão congelado**: muda o sha1, o total, a conta de todos os módulos e a lista dos "sem menção em teste". Fazer isso às três da manhã, sem ninguém para revisar o novo baseline, é trocar a fechadura e perder a chave — e um baseline errado é pior que nenhum, porque parece guarda. #### O que o conserto precisa carregar 1. o glob passa a incluir `Service/` (e provavelmente `Regra/`, que tem `RegraDeAgendamento` chamando repositório); 2. o sha1 e as cinco contagens são refeitos **e conferidos par a par**, porque "o número subiu" não distingue par novo de par que já existia e não era visto; 3. os pares que aparecerem pela primeira vez entram na leitura do D177 — a de 12/09 foi feita sobre um conjunto que não os tinha. Enquanto isso, a arquitetura deste projeto **empurra regra para Service de propósito** — foi o que a fatia da agenda fez. Cada extração dessas tira chamadas da vista deste portão, e a próxima pode tirar um par inteiro. #### MEDIDO em 21/09/2026 — a cegueira é de 35%, e o rebase continua bloqueado por 16 chamadas A ficha acima dizia que o portão perdeu **duas** chamadas de vista. Medido: perdeu **noventa e sete**. Estendendo o alcance para `Service/` e `Regra/` — **26 serviços e 1 regra** chamam `getRepository`, e o portão via **zero** deles: | | declarado | com `Service/` e `Regra/` | |---|---:|---:| | pares (repositório, método) | 179 | **276** | | pares **sem menção em teste nenhum** | 64 | **153** | | chamadas NÃO resolvidas | 6 | **22** | | falsos positivos da medida por nome | 26 | 27 | | ISApi | 24 | **121** | | ISCadastro | 85 | 108 | | ISConfiguracao | 110 | 129 | | ISMarketing | 16 | 23 | | ISBase | 0 | 1 | **97 pares novos, e nenhum perdido** — o conjunto declarado é subconjunto estrito do real. E a parte cega não é periferia: royalties, NPS, dashboard de colaborador, cupons, sorteio, pontuação, pacotes e vendas. O `ISApi` saltar de 24 para 121 diz o essencial — a superfície do aplicativo mora quase toda em serviço. ##### Por que a base NÃO subiu, e isto é a parte importante As **chamadas não resolvidas vão de 6 para 22**. São dezesseis formas de chamar que este resolvedor não lê, todas em serviço: | onde | quantas | |---|---:| | `ISApi/Service/CronJobService` | 12 | | `ISRelatorio/Service/FranquiaService` | 3 | | `ISCadastro/Service/AgendaService` | 1 | Todas do tipo `$repo->metodo()` onde o `$repo` é atribuído fora do alcance do caminhador de tokens. **Rebasear com elas por resolver congela um número que já se sabe incompleto** — e a própria ficha acima escreveu a razão: base errada é pior que nenhuma, porque parece guarda. ##### O que entrou, e é o que destrava o resto Duas opções de leitura, porque **até hoje era impossível olhar sem quebrar**: ``` MOSTRAR_PARES=1 php scripts/conferir-cobertura-por-par.php MOSTRAR_NAO_RESOLVIDAS=1 php scripts/conferir-cobertura-por-par.php ``` A primeira imprime os 179 pares; a segunda diz **arquivo e método** de cada chamada não resolvida. O requisito 2 da ficha — *"conferidos par a par"* — era irrealizável sem elas: a única forma de ver a lista era fazer o sha1 divergir, isto é, quebrar o portão para poder olhar. **A medição ficou escrita ao lado do glob**, no próprio código, para que quem abrir o arquivo veja o tamanho do que está fora antes de decidir. ##### O que falta, em ordem 1. ensinar o resolvedor a seguir `$repo = $em->getRepository(...)` atribuído em propriedade ou noutro escopo — as 16; 2. só então estender o glob e refazer as cinco linhas de base; 3. ler os 97 pares novos contra a leitura do D177, que foi feita sobre um conjunto que não os tinha — e 89 deles **não têm teste nenhum**. #### CORRIGIDO em 22/09/2026 — o resolvedor escopa por função, e o portão passou a ver os serviços Os três passos que a medição de ontem deixou em ordem, cumpridos em ordem. ##### 1. Por que as 16 chamadas não resolviam — e não era o que eu tinha escrito Ontem registrei que eram atribuições "fora do alcance do caminhador de tokens". Lendo, a causa era outra e mais simples: **o resolvedor rastreava variáveis por ARQUIVO, e PHP as escopa por FUNÇÃO.** | arquivo | variável | o que ela é, método a método | |---|---|---| | `CronJobService` | `$repoVenda` | `Venda` em quatro métodos, `VendaPagamento` num quinto | | `CronJobService` | `$repoNps` | `Nps` num método, `NpsResultadoUnidade` noutro | | `FranquiaService` | `$repository` | `VendaPagamento` num método, `Royalties` noutro | Por arquivo, cada uma virava **ambígua** — e **todas** as chamadas por ela ficavam sem resolver, inclusive as dos métodos onde o tipo era inequívoco. O conserto é `escoposPorToken()`: cada `function` com corpo abre um escopo, e a atribuição só vale dentro dele. Closure abre escopo próprio, e o que ela importa por `use` sai **contado como não resolvido** — o lado seguro; o resolvedor nunca adivinha. E `$this->metodo()` deixou de ser tratado como variável de repositório: `AgendaService` chamando o próprio `desmarcar()` saía como não resolvida só porque um repositório tem método com o mesmo nome. ##### 2. O efeito, medido em cada alcance | | declarado, antes | declarado, com escopo | estendido, com escopo | |---|---:|---:|---:| | pares | 179 | 179 | **285** | | não resolvidas | 6 | 2 | **2** | **No alcance declarado nenhum par entrou ou saiu** — cinco das seis antigas eram ambiguidade de arquivo e passaram a resolver, e nenhuma escondia par novo, como a leitura de 12/09 já tinha afirmado. **Uma NOVA apareceu, e ela é verdade:** `PesquisaNpsController:165` recebe o repositório **por parâmetro**. Por arquivo, o resolvedor a "resolvia" com a atribuição de **outro método** — e acertava por coincidência de nome, porque os dois chamadores passam o mesmo tipo. Por função, ele diz o que de fato sabe: dali não dá para saber. O par continua no conjunto pela linha 143, que chama na forma direta. ##### 3. As duas que ficam foram lidas, uma a uma | onde | por que não resolve | esconde par? | |---|---|---| | `AplicativoController::findEntity` | `getRepository($repository)->find($id)` — entidade por parâmetro | **não**: `find` é do Doctrine, nunca vira par | | `PesquisaNpsController:165` | repositório por parâmetro | **não**: o par é alcançado na linha 143 | Essa era a condição que a ficha pôs para a base subir. Cumprida, a base subiu. ##### As cinco linhas de base, e o que cada uma diz agora | | antes | agora | |---|---:|---:| | pares | 179 | **285** | | sha1 | `c87d0124…` | `530c1686…` | | não resolvidas | 6 | **2** | | sem menção em teste | 64 | **160** | | falsos positivos da medida por nome | 26 | **28** | Por módulo: ISApi **24 → 136**, ISVenda 55 → 92, ISCadastro 85 → 109, ISConfiguracao 110 → 129, ISRelatorio 92 → 103, ISMarketing 16 → 23, ISBase 0 → 1, ISFinanceiro 3 → 3. ##### Falsificado nas duas direções | o que se devolve | pares | não resolvidas | saída | |---|---:|---:|---:| | apago a **única** chamada de um par que só um serviço alcança | 284 | 2 | **1** | | devolvo o escopo por ARQUIVO | 276 | 21 | **1** | Arquivos restaurados byte a byte, conferido por `sha1sum -c`. Corredor inteiro: EXIT=0, nenhuma falha inesperada. ##### O que isto entrega ao D177, e não fecha **106 pares passaram a ser vigiados, e 96 deles não têm teste nenhum.** O `VendaRepository` sozinho tem 25; `ClienteRepository`, 10; `VendaProdutoRepository`, 8; `VendaPagamentoRepository`, 5. É onde o dinheiro está somado. Isso não é defeito do D193 — o D193 era **não ver**, e agora vê. É o número que a leitura do D177 precisa refazer, porque a de 12/09 foi feita sobre um conjunto que não os tinha. A lista inteira sai de: ``` MOSTRAR_PARES=1 php scripts/conferir-cobertura-por-par.php ``` ### D194 — Fechar a agenda perguntava os agendamentos do dia com a hora do RELÓGIO, recebia zero, e bloqueava horário com cliente marcado — CORRIGIDO em 21/09/2026 — PARCIAL, lido em 05/10/2026 > **Lido em 05/10/2026, pelo corpo inteiro:** o título dava este débito como fechado, e o corpo diz que ele está parcial: uma parte está consertada, e a outra não. Falta: medir na réplica e acertar na janela as datas de nascimento já gravadas com hora; decidir no lote se a coluna vira date no PostgreSQL. > > **06/10/2026:** decidido pelo dono (lote de perguntas, perguntas 12 e 13): medir na réplica e, dando mais que zero, acertar no passo 3 do corte; a coluna fica como está no PostgreSQL. Falta: a medida na réplica e o passo na janela. Achado em 21/09/2026 **ao consertar o D189**, e não procurando por ele. Para trocar `DATE(age.data) = :data` por uma faixa eu precisava saber o que os chamadores passam — e foi aí que a divergência apareceu. #### O defeito `AgendaService::fechar()` pergunta quais horários já estão ocupados assim: ```php $agenda = $repoAgenda->selecionarPorColaboradorData( $colaborador->getId(), \DateTime::createFromFormat('d-m-Y', $data) // <- sem parte de hora ); ``` **`createFromFormat` sem parte de hora NÃO zera a hora: ela herda o relógio.** `createFromFormat('d-m-Y', '06-08-2026')` às 08:58 devolve `2026-08-06 08:58:56`. E o MySQL, ao comparar `DATE(coluna)` com um datetime, promove a data para meia-noite. Então `DATE(age.data) = '2026-08-06 08:58:56'` **nunca casa** — exceto se o relógio estiver exatamente em `00:00:00`. Medido, colaborador 200, dia 2026-08-06: | o que o chamador passa | o que volta | |---|---| | `'2026-08-06'` (`stringDate`, o caminho comum) | 29 linhas | | `dateToString3(...)` | 29 linhas | | **`createFromFormat('d-m-Y', ...)`** → `2026-08-06 08:58:56` | **0 linhas** | | o mesmo, com hora zerada | 29 linhas | #### A consequência, e ela é de escrita `fechar()` usa essa lista para montar a grade e decide o que bloquear por `status == 1` — "este horário está livre". `Util\Agenda::getAgenda()` marca `status => 1` quando **não acha** o horário na lista. Lista vazia, tudo livre. Então o fechamento gravava um bloqueio em **todos** os horários da janela, inclusive nos que já tinham cliente. O código checa `status == 1` justamente para não fazer isso; a consulta vazia derrotava a checagem. **Medido sem escrever nada**, reproduzindo só os dois passos de leitura do serviço, no dia 06/08/2026: | colaborador | o serviço julga livres | deveria julgar | bloqueios sobre horário JÁ MARCADO | |---|---:|---:|---:| | 200 | 34 | 5 | **29** | | 380 | 20 | 7 | **13** | | 998 | 30 | 12 | **18** | | 1052 | 20 | 15 | **5** | **65 horários com cliente**, num único dia e quatro colaboradores. A tabela tem 36 unidades. O efeito para quem usa: o cliente marcado some da grade enquanto o fechamento existir — há duas linhas no mesmo horário, e a de bloqueio é a que a tela mostra. Reabrir a agenda (`abrir()` faz `remove()` do fechamento, com `ON DELETE CASCADE`) apaga os bloqueios e o agendamento reaparece. Ou seja: o dado não se perde, mas **o barbeiro não vê que tem cliente naquele horário** — e é justamente nessa hora que ele precisaria ligar para remarcar. #### Por que ninguém tinha visto O `DATE()` engolia. Uma consulta que devolve zero não levanta erro, não escreve aviso, e — neste caminho — produz uma grade que *parece* correta: uma agenda vazia é um estado legítimo. E o defeito é **dependente do relógio**: à meia-noite em ponto o código funciona. #### O conserto A normalização passou a morar **na consulta**, e não em cada chamador: `AgendaRepository::diaInteiro()` aceita `string` e `DateTimeInterface`, descarta a hora, e devolve a faixa `[dia, dia+1)`. Por que ali e não em `fechar()`: é a consulta que define o que "um dia" significa. Espalhar essa definição por oito pontos foi o que deixou um deles divergir sem ninguém ver — e consertar só o `fechar()` deixaria o nono ponto livre para repetir. #### O teste, e por que ele é determinístico `tests/Caracterizacao/DiaDaAgendaTest.php`, sete casos. O central monta a hora **à mão** (`14:32:07`, `23:59:59`, `00:00:00`) em vez de depender do relógio: um caso que usasse só `createFromFormat` seria **verde uma vez por dia sobre o defeito**. E um caso reproduz a expressão inteira que `fechar()` usa, não uma aproximação dela. Falsificado devolvendo `DATE(age.data) = :data` ao repositório. #### A DEDUÇÃO VIROU MEDIÇÃO — o elo da escrita, fechado em 21/09/2026 Este registro dizia, com todas as letras, que o elo final era **dedução**: a consulta devolve zero (medido), `getAgenda` marca tudo livre com lista vazia (medido), o serviço decide por esse `status` (lido) — mas a linha de bloqueio gravada por cima do cliente não tinha sido vista. Agora foi. **E o arquivo que exercita `fechar()` já existia e NÃO pegava o defeito.** O motivo é de cenário, não de código: `FecharAgendaTest` fecha a janela **10:00–11:00**, e o agendamento da fixture é às **09:00**. As duas nunca se cruzavam — então os quatro casos passavam antes e depois do conserto. Um teste que exercita o caminho certo com o recorte errado não é cobertura; é a aparência dela. O caso novo fecha **08:00–12:00**, que é a única forma de a pergunta ser feita: ``` com o conserto: 5 casos, 23 asserções, verde com o defeito: Failed asserting that 2 is identical to 1 ``` **Dois é o defeito inteiro numa linha:** duas linhas no horário das 09:00 onde deveria haver uma. O bloqueio caiu em cima do agendamento do cliente. E só esse caso fica vermelho — os outros quatro seguem verdes, o que mostra que ele mede uma coisa e não o arquivo todo. **O controle está no mesmo caso, e é a metade que falta na maioria dos testes assim:** ele também afirma que a janela **bloqueou alguma coisa**. Sem isso, o caso ficaria verde se `fechar()` simplesmente não fizesse nada — e "não faz nada" passaria por "faz a coisa certa". Rodado no `franquiabv_cilocal`, que a suíte monta do zero; o caso base envolve tudo em transação e desfaz. Conferido depois: o banco ficou com os 2 agendamentos da fixture e **zero** fechamentos. #### A ARMADILHA É DE CLASSE — e medir disse onde ela NÃO chega `createFromFormat` sem parte de hora é trap do PHP, não peculiaridade deste método. Varrido o projeto: as chamadas com formato só-de-data moram em `DataHora`, e a principal é **`stringToDate()`, com 28 chamadores** — quase todos setters de entidade. **Mas o susto não sobrevive à medição**, e a razão é o tipo da COLUNA: | coluna | tipo | valores com hora ≠ meia-noite | |---|---|---:| | `usuarios.ferias_inicio` | `date` | **0** de 253 | | `usuarios.data_nascimento` | `date` | **0** de 2.428 | | `clientes_pacotes.validade` | `date` | **0** de 3.475 | | `saidas_parcelas.data_vencimento` | `date` | **0** de 15.076 | Sete das oito colunas conferidas são `date`: o banco trunca na escrita, e a hora do relógio morre ali. **O mapeamento diz `type="datetime"` mesmo assim** — a segurança é acidente do esquema, não escolha. Trocar qualquer uma dessas colunas para `datetime` na Fase 1 acorda a armadilha de uma vez. **A exceção é `clientes.data_nascimento`**, que é `datetime` na coluna E no mapeamento. Ali o Doctrine grava `format('Y-m-d H:i:s')`, então a hora do relógio **chega ao banco** — por mecanismo determinístico, lido no código. **E aqui a cópia anonimizada NÃO serve de prova.** Ela tem 242.592 datas de nascimento e **zero** com hora — mas data de nascimento é dado pessoal, e a cópia quase certamente as regenerou. Medir isso ali seria medir o anonimizador, não o sistema. Fica dito que o mecanismo existe, que o dano é baixo (as consultas de aniversário usam `MONTH()`/`DAY()`, que a hora não afeta), e que **a pergunta só se responde na produção**. Nada foi mudado em `DataHora`: mexer numa função com 28 chamadores por um dano que a medição não achou seria trocar risco conhecido por risco desconhecido. #### O NASCIMENTO SEM HORA — CORRIGIDO em 05/10/2026 O registro deixou o mecanismo dito e o conserto adiado. **O conserto:** `Cliente::setDataNascimento()` passou a `DataHora::stringToDia()` -- `createFromFormat("!d/m/Y")`, em que o `!` zera a hora -- e o irmão também: `UnidadeSocio::setDataNascimento()`, que grava `unidades_socios.data_nascimento`, a outra coluna `datetime` com o mesmo setter. `stringToDate()` ficou como estava. **A lista saiu do código, e não da memória:** os 17 pontos das entidades que chamam `stringToDate()`, contra o tipo da coluna no `mysql.sql` e no `postgres/schema.sql`. 14 são `date` nos dois bancos -- o gerador (`scripts/gerar-ddl-postgres.php`) continua mapeando `date` para `date` e `datetime` para `timestamptz` --; 2 são estas; e 1 é o ramo sem hora de `Notificacao::setData()`, que cairia em `datetime` mas não tem chamador (a campanha é gravada com a hora). **O efeito da hora não era só de enfeite:** as consultas de aniversário usam `MONTH()`/`DAY()` e não a sentiam, mas a idade do filtro por faixa etária (`TIMESTAMPDIFF(YEAR, cli.dataNascimento, :agora)`) sentia -- no dia do aniversário, a pessoa só fazia anos depois da hora em que o cadastro foi salvo. **Provado** (`NascimentoSemHoraTest`, 5 casos, nos dois bancos): o dia volta à meia-noite, com o vazio nulo e o formato que não serve falso, como em `stringToDate()`; o cliente e o sócio guardam o dia sem hora; o cadastro pela regra da API e pelo serviço de verdade grava `1990-03-15 00:00:00` na coluna, lida crua; e no primeiro segundo do aniversário -- `2026-03-15 00:00:01`, escrito, e não o relógio -- o `TIMESTAMPDIFF` dá 36. Três mutantes, vermelhos: o setter do cliente de volta a `stringToDate()` (3 casos, nos dois bancos), o do sócio (1) e o `stringToDia()` sem o `!` (os 5). O relógio não é injetável: o mutante só passaria num cadastro salvo exatamente às 00:00:00. **O que fica:** as linhas que já têm hora continuam com ela -- acertá-las é escrita em dado de produção, e a cópia não serve de medida (o anonimizador regera as datas, acima). Foi ao lote. **A revisão (05/10/2026): o dia sem meia-noite.** O `!` zerava a hora no fuso do processo, America/Sao_Paulo -- e nesse fuso a meia-noite NÃO EXISTE nos dias em que o horário de verão começava: o relógio pulava de 00:00 para 01:00. Contados no contêiner, de 1900 a 2030: 45 dias, de 1914 a 2018, 34 deles de 1985 em diante (21/10/1990, 15/10/1989, 04/11/2018...). Neles, `stringToDia()` dava 01:00 -- e o docblock e este registro diziam "a meia-noite"; o `TIMESTAMPDIFF` virava a idade só à 01:00 do aniversário, e a consulta que o lote propõe (`TIME(...) <> '00:00:00'`) contaria essas linhas como "com hora" depois do acerto. **O conserto:** `stringToDia()` cria o dia em UTC. O Doctrine grava o relógio do objeto sem converter fuso (`DateTimeType::convertToDatabaseValue` é um `format`), e em UTC a meia-noite existe todo dia: o MySQL recebe `00:00:00` sempre. O fuso não aparece a ninguém -- os dois getters devolvem o texto `d/m/Y`, o mesmo dia. **O PostgreSQL não ganha isso, e o caso o escreve.** Lá a coluna é `timestamptz` e o banco está no fuso de São Paulo: o `00:00:00` desses dias é lido como 01:00-02 -- o mesmo instante e o mesmo dia --, e a idade só vira à 01:00. Só uma coluna `date` o tiraria, e é mudança de esquema; foi ao lote, como opção, com a recomendação de não fazer agora. **Provado** (`NascimentoSemHoraTest`, mais 2 casos, nos dois bancos): 21/10/1990, 04/11/2018 e 15/10/1989 à meia-noite no `stringToDia()`, no cliente e no sócio, com o getter devolvendo o mesmo dia; e o cadastro de 21/10/1990 pela regra da API, na coluna lida crua -- `00:00:00` e 36 anos no primeiro segundo do aniversário no MySQL, `01:00:00` e 35 no PostgreSQL (o limite). O mutante -- `stringToDia()` de volta ao fuso do processo -- deixa vermelhos os dois casos no MySQL e o primeiro no PostgreSQL, onde a coluna já era 01:00 de qualquer jeito. **Decidido pelo dono em 06/10/2026** (lote de perguntas, pergunta 12): a opção (a), "Medir na réplica e, dando mais que zero, acertar na janela". Entrou no roteiro do corte: `scripts/medir-nascimento-com-hora.sql` (só contagens) é o 7 de "O que hoje bloqueia", e os dois `UPDATE` do fim dele -- `clientes` e `unidades_socios`, o dia sem a hora -- entram no passo 3, depois da limpeza. Ensaiado em `scripts/ensaiar-sql-do-passo-3.php` (desde a revisão de 06/10/2026, no repositório), no 8.4.11 e no 8.0.46, com datas inventadas: 2 e 1 linhas na primeira vez, nada na segunda, a `data_alteracao` intacta; com uma data zero com hora em `unidades_socios`, que a limpeza não alcança, o modo estrito recusa o UPDATE inteiro, e a coluna `anteriores_a_1000` da medida a acusa antes. No `franquiabv_dev` a medida dá 0 com hora em 242.592 nascimentos -- o anonimizador, como acima. **Decidido pelo dono em 06/10/2026** (lote de perguntas, pergunta 13): a opção (a), "Deixar como está" -- a coluna continua `timestamptz` no PostgreSQL, e nos 45 dias sem meia-noite em São Paulo o dia aparece com 01:00. Nada muda no código; a troca para `date` cabe numa janela em que o esquema já vá mudar. O que resta deste débito: a medida na réplica e o acerto na janela. ### D195 — A agenda era governada por DOIS privilégios diferentes, e a fachada nova escolheu o que nunca governou nada — CORRIGIDO em 21/09/2026 Achado em 21/09/2026, ao fechar o D192: ao ligar a primeira ação de escrita da agenda, a guarda do botão e a guarda do servidor discordavam. #### O que acontece A mesma tela é governada por dois privilégios, e quem os concede não tem como saber disso: | o que se faz | privilégio | onde está declarado | |---|---|---| | ver telefone e nome inteiro | `agendas/gerenciar/escrever` | `Adm\AgendasController::gradeAction` | | criar, check-in, remover, remarcar | `agendas/visualizar/escrever` | `Adm\AgendamentosController`, `funcionalidade = 'visualizar'` | Não é desenho: é consequência de as ações terem ido para **outro controller**, que declara outra funcionalidade. Ninguém decidiu que "ver o telefone" e "marcar um horário" seriam permissões diferentes. #### Quanto isso alcança Medido sobre `privilegios_usuarios` — a camada operativa que o `Acl` lê no login (15.503 linhas), e **não** a tabela `privilegios`, que é só o molde do grupo (139 linhas, D157) — entre os **371 usuários ativos**: | situação | usuários | |---|---:| | têm `visualizar/escrever` e não `gerenciar/escrever` | **164** | | têm `gerenciar/escrever` e não `visualizar/escrever` | **94** | | têm os dois | 87 | | não têm nenhum | 26 | **258 de 371 — 70% — têm um e não o outro.** E a primeira medição que fiz disto estava errada, o que vale registrar: contei sobre a tabela `privilegios` e achei três grupos divergentes. Aquela tabela é o **molde**, e não o que decide. A sessão do `user200` desmentiu na hora — ela trazia privilégios que o molde do grupo dele não concede. #### O que isso significa para quem usa - **164 pessoas** podem marcar, remarcar e registrar chegada, e **não veem o telefone do cliente** que vão atender. - **94 pessoas** veem telefone e nome inteiro e **não conseguem marcar nada** — a API recusa com 403. Nenhuma das duas é obviamente errada; o que é errado é **ninguém ter decidido**. A tela de permissões mostra "Agendas visualizar" e "Agendas gerenciar" como se fossem "ler" e "escrever", e não são: `visualizar/escrever` é o que autoriza escrever. #### O que foi feito, e o que NÃO foi **Feito:** o recurso da grade passou a publicar os **dois** bits, com nomes que dizem o que cada um governa, para que a tela guarde a ação pelo privilégio que a ação exige. Ver D192. **Não feito:** unificar os dois. Isso é decisão de produto, não de código — qualquer escolha TIRA acesso de um dos dois grupos: - exigir os dois para agir tiraria a ação de **164** pessoas; - aceitar qualquer um dos dois daria o recorte de telefone a **164** que hoje não o têm; - mover as ações para `gerenciar` tiraria a ação das mesmas 164; - mover o recorte para `visualizar` daria telefone a 164 e tiraria de 94. E a tabela `privilegios_usuarios` tem **347 linhas que divergem do molde do grupo** (D157): parte dessas 258 pessoas pode ser decisão consciente de alguém, e não acidente. Passar a régua por cima apagaria essas decisões. **Precisa de você:** qual das quatro, ou uma quinta. O sistema funciona hoje; o que não existe é alguém tendo escolhido. #### CORRIGIDO em 21/09/2026 — e a correção foi no lugar que o registro acima não olhou Este débito foi escrito como **decisão de produto**, com quatro opções e a frase *"precisa de você"*. Medir mostrou que a premissa estava errada: **não são duas escolhas legítimas.** Uma das duas é o que o ERP faz há anos; a outra nasceu por acidente de lugar, e o bit que ela pede **nunca governou nada de verdade**. ##### O que a medição achou, e o registro acima não dizia A tabela original dizia que `agendas/gerenciar/escrever` governa "ver telefone e nome inteiro". Governa **três** coisas, e a terceira é a que decide: | o que `gerenciar/escrever` governa | onde | |---|---| | **o escopo** — a grade inteira, ou só a sua coluna | `AgendasController.php:892` e `Adm\AgendasController::gradeAction` | | **a privacidade** — telefone e nome inteiro | `GradeDaAgendaJson::umHorario` | | **o AGIR** — as 13 ações de escrita do ERP | `podeGerenciarAgenda()`, via `getAcesso2('gerenciar')` | E `agendas/visualizar/escrever` governava, no ERP inteiro, **uma única ação**: `bloqueiosRemoverAction` — que estava com a **guarda invertida** desde a importação inicial (D196). Ou seja: o bit que a API nova escolheu para autorizar escrita **nunca autorizou nada corretamente** na agenda. ##### A quinta opção, que não estava na lista — e não tira nada de ninguém A lista de quatro opções acima tinha um erro de análise, e ele é meu: a opção *"mover as ações para `gerenciar`"* estava escrita como *"tiraria a ação de 164 pessoas"*. **Não tira.** Essas 164 pessoas **não conseguem agir na agenda hoje** — o ERP as recusa. O único lugar onde elas podiam agir era a API nova, que **não tem consumidor em produção**. Então a escolha que parecia um impasse — 164 contra 94 — não era impasse: | opção | quem perde algo que USA hoje | |---|---| | exigir os dois para agir | 94 | | aceitar qualquer um dos dois | ninguém perde, mas 164 ganham o telefone | | **alinhar a API ao ERP (`gerenciar`)** | **ninguém** | | mover o recorte para `visualizar` | 94 perdem o telefone | A terceira é a que entrou. Ela não é decisão de produto: é a Fase 2 **cumprindo o que promete ser** — uma fachada. *A regra de negócio não muda de lugar.* ##### Os números do registro acima estavam errados, e o erro é meu A medição original contou sobre `privilegios_usuarios` e **ignorou duas coisas** que a revisão adversarial achou: 1. **Administradores passam por fora da tabela.** `Acl.php:29-30` faz `allow($grupo, [], [])` para todo grupo com `administrador = 1` — são **10 pessoas**, que passam em qualquer conferência sem ter uma linha de privilégio. 2. **Cinco dos "371 ativos" são usuários de fixture meus** (`90001000`, `90001001`, `90001003`, `90001100`, `90001150`). Contar o cenário de teste como gente da barbearia é o medidor sujando a medida. Refeito sobre os **366 usuários ativos reais**: | | antes (errado) | medido | |---|---:|---:| | ativos | 371 | **366** | | administradores | não contados | **10** | | só `visualizar/escrever` | 164 | **164** | | só `gerenciar/escrever` | 94 | **94** | | os dois | 87 | **96** | | nenhum | 26 | **12** | | podem AGIR no ERP hoje | — | **190** | | podiam AGIR na API nova | — | **260** | **O racha em si — 164 e 94 — estava certo.** O que estava errado era o denominador e os outros dois baldes: os 10 administradores estavam no balde "nenhum" e são, na prática, "ambos". E a conta só fechou em 366 depois de achar **onze pessoas sem uma única linha** em `privilegios_usuarios`: dez são "Gerente geral" administradoras, e a décima primeira é o **usuário 1377**, Colaborador, `administrador = 0`, com **6.005 acessos**. `MAX()` sobre zero linhas devolve `NULL`, e ele sumia da conta em silêncio. Ele não pode nada na agenda — **exceto** passar pela guarda invertida do D196. ##### O que entrou As **6 ações de escrita** da agenda sob `/adm/api` — criar, check-in, remover, remarcar, fechar e reabrir — passaram a exigir `agendas/gerenciar/escrever`, pelo helper `podeGerenciarAgenda()`, que é **a mesma expressão** da tela legada. As LEITURAS não mudaram: continuam `agendas/visualizar/ler`. A grade continua publicando **dois nomes** — `podeGerenciar` e `podeEscreverAgendamento` — e hoje eles carregam o mesmo bit. O nome não foi removido de propósito: ele responde outra pergunta, e foi ler o campo errado que custou o D192. **A redundância é dívida e está anotada aqui**: dois campos com o mesmo valor podem divergir por engano. ##### Falsificado — e o instrumento é novo, porque nenhum existia Nenhum instrumento desta casa distinguia os dois bits, e a razão é estrutural: o **único login de ERP da suíte de contrato tem OS DOIS**, então qualquer uma das quatro opções passaria. *Verde por indistinção não é verde.* `scripts/conferir-guarda-da-agenda.php`, no corredor e na CI, confere **19 ações de escrita** nas duas pilhas e sai com 1 quando: | o que se devolve | o portão | |---|---| | uma ação da API volta a `getAcesso('escrever')` | **2 problemas** | | a guarda volta com o sinal trocado | **2 problemas** | | alguém acrescenta uma ação e não a declara | **para**, e diz o total novo | A terceira não é hipótese: ela me pegou chutando 22 ações onde havia 20. ##### A pergunta que sobrava foi respondida em 21/09/2026 — e É REGRA O dono decidiu, com estas palavras: > *"essas 164 pessoas é regra, podem ver mas não escrever na agenda, apenas > consultar. Apenas nome e serviço, sem o telefone do cliente."* **O comportamento de hoje está certo e é para ficar.** Quem tem `agendas/visualizar/ler` e não tem `agendas/gerenciar/escrever` consulta a agenda e não age nela. E a decisão bate, palavra por palavra, com o que a tela legada faz desde sempre — o que confirma que a regra é antiga e foi só nunca escrita: | | `tabela.phtml:43` — quem gerencia | `tabela.phtml:62` — quem só consulta | |---|---|---| | Cliente | nome inteiro | primeiro nome, se a unidade mandar | | **Telefone** | **mostra** | **não mostra** | | Serviço | mostra | mostra | | Convênio | mostra | mostra | | Observação | mostra | mostra | **O D195 está fechado nas duas metades:** a divergência entre as pilhas era acidente e foi consertada; o recorte que sobra é decisão, foi tomada, e é a que já estava no código. **E responder isso abriu o D197:** a regra vale na grade e na tela legada, e `GET /adm/api/agendamentos` escapava dela. Ver ali. > **Correção de registro (07/10/2026, o item CODIGO-MORTO-E-DOCS):** o conserto de 21/09 > trocou o bit no controller (`Adm\AgendasController::gradeAction` passa o de `gerenciar` > nos dois nomes) e deixou o recurso falando do bit de antes: o `@param` de > `GradeDaAgendaJson::montar` dava `podeEscreverAgendamento` como `agendas/visualizar/escrever`, > e o comentário do campo dizia que as ações "exigem OUTRO privilégio". Os dois passaram a > dizer o que vale desde 21/09 -- `agendas/gerenciar/escrever`, o mesmo bit nos dois > nomes, e por que o nome fica --, com os números de 21/09 como história. Só comentário: > o recurso devolve o mesmo, e a redundância anotada acima continua a mesma dívida. > Na verificação do mesmo dia, a referência do comentário novo foi acertada: ele dava "o > que o ERP pede há anos" como `AgendamentosController::podeGerenciarAgenda`, e esse é o > da API nova (`Adm\AgendamentosController`, de 21/09), que copia a regra. A regra antiga > é a de `ISCadastro\Controller\AgendasController::podeGerenciarAgenda()` > (`getAcesso2('gerenciar')`), e o comentário agora nomeia as duas. --- ### D196 — A ação que APAGA bloqueio de agenda recusava quem podia e deixava passar quem não podia — CORRIGIDO em 21/09/2026 Achado em 21/09/2026, atacando o D195. Não estava sendo procurado. #### O defeito `ISCadastro\Controller\AgendasController::bloqueiosRemoverAction`, presente assim **desde a importação inicial do ERP**: ```php public function bloqueiosRemoverAction() { if ($this->getAcesso()) { // <- SEM o "!" return $this->notFoundAction()->setTerminal(true); } ... $this->service->abrir($fechamento); // remove() + flush() ``` O sinal está trocado. Quem **tem** `agendas/visualizar/escrever` leva 404; quem **não tem** segue adiante e apaga. Era a **única** guarda das 22 deste arquivo com essa forma — todas as outras são `if (!...) { recusa }` ou `if (...) { prossegue }`. E `AgendaService::abrir()` é `$em->remove($fechamento); $em->flush();`. #### Medido | | | |---|---:| | fechamentos apagáveis | **134.334** | | unidades que eles cobrem | **48** | | clicavam Remover e levavam 404 | **260** de 366 | | passavam pela guarda e apagavam | **106** | Os 260 recusados **incluem os 10 administradores**. Entre os 106 que passavam está o **usuário 1377**, que não tem uma única linha em `privilegios_usuarios` e tem **6.005 acessos** registrados. E o botão é visível para todos: `bloqueios.phtml:85` desenha **Remover** em cada linha da lista, **sem nenhuma conferência de privilégio** — a tela de listagem pede só `agendas/visualizar/ler`. Quem gerencia a agenda clicava e recebia uma página 404. #### E havia mais dois, que são os mesmos do D190 A ação é a **gêmea** da `abrirAction`: mesma entidade, mesma operação. O D190 consertou três defeitos na gêmea em 20/09 e escreveu o comentário; esta ficou de fora, com dois deles ainda de pé: 1. **`getReference()` devolve proxy preguiçoso**, então `empty($fechamento)` era sempre falso e aquele ramo era **código morto**. 2. **Nenhuma conferência de franquia.** O helper `fechamentoDaMinhaUnidade()` existe — foi escrito no D190 — e **não era chamado aqui**. O id vinha cru da rota: dava para apagar o fechamento de qualquer uma das 48 unidades sabendo só o número. #### Por que nenhum instrumento pegou - **O D150 contou esta ação como JÁ GUARDADA.** O registro dele diz, com todas as letras: *"Só `indexAction` (`ler`) e `bloqueiosRemoverAction` (`escrever`) conferiam privilégio"*. Ele olhou se **havia** guarda, não se ela guardava. *Motivo na dispensa não é guarda* — e "tem uma guarda" também não é. - **O `conferir-recorte-por-unidade.php` não a vigiava.** A lista é escrita à mão, e nem esta ação nem a gêmea `abrirAction` estavam nela — o helper `fechamentoDaMinhaUnidade` era exigido por **zero** das 41 entradas. - **Nenhum portão olha polaridade.** O `conferir-acl-como-booleano.php` pega `getAcl()` com menos de três argumentos; sinal trocado passa por ele. #### O que entrou A guarda passou a ser `podeGerenciarAgenda()` — a **mesma expressão** da gêmea e das outras doze ações que agem. Não é `getAcesso()`: remover bloqueio reabre horário, que é agir sobre a agenda. Mais `find()` no lugar de `getReference()` e a conferência `fechamentoDaMinhaUnidade()`. Varri o código inteiro atrás de outras guardas com o sinal trocado: **não há nenhuma**. #### Falsificado | o que se devolve | portão | saída | |---|---|---:| | tiro a conferência de franquia | `conferir-recorte-por-unidade` | **1** | | tiro a conferência de franquia | idem, consertado | 0 | | devolvo o sinal trocado | `conferir-guarda-da-agenda` | **1** | | troco o privilégio numa ação da API | idem | **1** | Arquivos restaurados byte a byte, conferido por `sha1sum -c`. #### Fica de pé, anotado **A ação continua sendo GET.** Um link que apaga é fraqueza por si só — basta alguém abrir a URL. Trocar para POST pede mexer no `bloqueios.phtml`, que chama por `modal_remover(url)`. Não foi feito hoje para não misturar conserto de guarda com mudança de tela. #### E DEIXOU DE SER GET em 22/09/2026 — a dívida que ficou anotada acima, paga Decisão do dono: *"ataque a remoção de bloqueio por GET"*. **Das treze ações deste controller guardadas por `podeGerenciarAgenda()`, doze já exigiam POST.** A `bloqueiosRemover` era a única que apagava por GET — a mesma posição de exceção que ela ocupava na guarda invertida. ##### O que entrou - **A ação:** `if (!$this->getRequest()->isPost() || !$this->podeGerenciarAgenda())`, o mesmo formato das outras doze, antes de tocar no banco. - **A tela:** o botão da linha chama `bloqueioRemover(url)`, que põe a URL como `action` de um `
`; o "Sim" do modal é o botão de envio dele. - **O script mora NA TELA**, e o comentário diz por quê: o `modal_remover` global remove por GET e é usado por outras 22 telas, cujas ações ainda só aceitam GET; e o layout serve `geral.min.js`, que não tem passo de minificação versionado. ##### Verificado sem apagar nada | o que | resultado | |---|---| | `GET …/bloqueiosRemover/3915` como `user1096`, que **pode** remover, bloqueio **da unidade dele** | **404**, e a linha continua **idêntica ao backup, byte a byte** | | a tela servida | botão chama `bloqueioRemover`, formulário `method="post"` | | clique real no `×` do 3915, no navegador | modal abre; `action` = `/mod-cadastros/agendas/bloqueiosRemover/3915`; o "Sim" é o envio desse formulário | O "Sim" **não foi apertado**: seria uma escrita na cópia de produção. O caminho POST do controller não mudou — a condição nova é falsa para POST e cai na guarda que já estava verificada desde 21/09. ##### Os portões - **`conferir-guarda-da-agenda.php`** ganhou a regra `exige_post` para o ERP: ação de escrita que não confere `isPost()` fica vermelha. Falsificado: com o GET de volta, **exit 1** apontando a ação. - **`conferir-scripts-servidos.php`** acusou `bloqueioRemover` como botão morto — ele só olhava os `.js` servidos. Aprendeu que o `