test: make consolidated workspace self-contained

gerenciador/README.md

@@ -61,7 +61,36 @@ a tabela ficar vazia. Login checa primeiro o admin do `.env`, depois
 pytest -v
 ```
 
-Os testes usam defaults definidos em `tests/conftest.py` (equivalentes ao `.env.example`) e incluem testes de integração que precisam do container MySQL de dev (`licenciamento-mysql-dev`, `127.0.0.1:3307`) rodando.
+Os testes usam defaults definidos em `tests/conftest.py` (equivalentes ao `.env.example`) e incluem testes de integração que precisam de um MySQL em `127.0.0.1:3307`.
+
+### Ambiente de teste local (MySQL descartável)
+
+Fora do repositório original (`BLOQUEIO SGV`), este subtree não tem acesso ao container
+`licenciamento-mysql-dev` nem ao dump real de clientes — nem deveria, dado que este monorepo
+não importa dado real de nenhum cliente. Para rodar a suíte de forma autocontida, este
+diretório traz um MySQL de teste **descartável**, separado do `docker-compose.yml` de
+produção:
+
+```
+docker compose -f docker-compose.test.yml up -d
+```
+
+Isso sobe um `mysql:5.7` só com a estrutura das tabelas (`CLIENTE`, `CLIENTE_CONTATO`,
+`Clientes_Chaves`, `FUNCIONARIO_PAINEL`, `LOG_PAINEL`) a partir de `tests/db/schema.sql` —
+**DDL apenas, nenhum dado de cliente**. Cada tabela do schema.sql tem, em comentário, a fonte
+exata de onde a definição foi extraída (docstring do módulo Python correspondente, ou a
+documentação de schema do sistema legado). O banco roda em `tmpfs` (nunca grava em disco,
+nunca sobrevive a um restart do container) e só escuta em `127.0.0.1:3307` — sem rede externa,
+sem volume nomeado, sem credencial real (senha `devpassword123`, válida só para este banco
+descartável).
+
+Depois de rodar os testes:
+
+```
+docker compose -f docker-compose.test.yml down -v
+```
+
+remove o container e a rede — nada persiste.
 
 ## Rodando via Docker