fix: validacao de formulario, auth fail-closed, loop de confirmacao, hardening e docs (achados da revisao final)

- Fix 1 (critico): cliente_form.html agora tem required/type por campo
  (date/number) e o router captura DataError/IntegrityError em
  criar/editar, reexibindo o form com erro_gravacao em vez de 500.
- Fix 2 (importante): auth.py falha fechado quando ADMIN_USER/
  ADMIN_PASSWORD nao estao configurados (nao tenta mais compare_digest
  com string vazia).
- Fix 3 (importante): avisos de codigo duplicado e DV invalido agora
  carregam a flag de confirmacao um do outro adiante, quebrando o loop
  quando ambos disparam no mesmo cliente.
- Fix 4 (menor): corrige precedencia 'or 42' -> 'and 42' no lambda de
  teste de criar_cliente.
- Fix 5 (menor): desabilita /docs, /redoc, /openapi.json no FastAPI().
- Fix 6 (menor): comentario explicando o valor de Prorrogacao no fixture
  de teste de chaves.
- Fix 7 (menor): .env.example usa host.docker.internal por padrao,
  docker-compose.yml ganha extra_hosts para Linux, README.md novo com
  quickstart real.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

tests/test_auth.py

@@ -36,3 +36,12 @@ def test_credenciais_corretas_retorna_200():
     resposta = client.get("/protegido", headers=_basic("admin", "teste123"))
     assert resposta.status_code == 200
     assert resposta.json() == {"usuario": "admin"}
+
+
+def test_admin_user_e_senha_vazios_nao_autentica_com_credenciais_vazias(monkeypatch):
+    # Sem ADMIN_USER/ADMIN_PASSWORD configurados, o painel não pode ficar
+    # aberto para uma requisição com usuário/senha vazios (Basic Og==).
+    monkeypatch.setenv("ADMIN_USER", "")
+    monkeypatch.setenv("ADMIN_PASSWORD", "")
+    resposta = client.get("/protegido", headers=_basic("", ""))
+    assert resposta.status_code == 401

tests/test_db_chaves.py

@@ -14,6 +14,8 @@ def _linha_vazia(codigo: str, cliente: str) -> dict:
     linha = {f"M{i}": "" for i in range(1, 13)}
     linha["ID"] = codigo
     linha["Cliente"] = cliente
+    # "0000-00-00" (o valor real usado no legado) é rejeitado pelo MySQL em modo estrito
+    # (NO_ZERO_DATE) — usamos uma data valida qualquer, só para satisfazer a coluna NOT NULL.
     linha["Prorrogacao"] = "2099-12-31"
     return linha
 

tests/test_main.py

@@ -10,6 +10,12 @@ def test_raiz_sem_login_pede_credenciais():
     assert resposta.status_code == 401
 
 
+def test_docs_desabilitado_retorna_404():
+    assert client.get("/docs").status_code == 404
+    assert client.get("/redoc").status_code == 404
+    assert client.get("/openapi.json").status_code == 404
+
+
 def test_raiz_redireciona_para_clientes_com_login(monkeypatch):
     from app.routers import clientes as router_clientes
 

tests/test_router_clientes.py

@@ -7,6 +7,7 @@ from fastapi import FastAPI
 from fastapi.testclient import TestClient
 
 from app.auth import exigir_login
+from app.db.connection import get_connection
 from app.routers import clientes as router_clientes
 
 app_teste = FastAPI()
@@ -32,7 +33,7 @@ def test_criar_cliente_codigo_duplicado_exige_confirmacao(monkeypatch):
     monkeypatch.setattr(router_clientes.db_clientes, "codigo_em_uso", lambda codigo, ignorar_id=None: True)
     criado = {}
     monkeypatch.setattr(
-        router_clientes.db_clientes, "criar_cliente", lambda dados: criado.setdefault("ok", True) or 42
+        router_clientes.db_clientes, "criar_cliente", lambda dados: criado.setdefault("ok", True) and 42
     )
 
     dados_form = {campo: "000001" if campo == "CODIGO" else "x" for campo in router_clientes.db_clientes.CAMPOS_CLIENTE}
@@ -79,3 +80,93 @@ def test_excluir_cliente_com_dependencia_mostra_erro(monkeypatch):
     resposta = client.post("/clientes/1/excluir", follow_redirects=True)
     assert resposta.status_code == 200
     assert "tem contato" in resposta.text
+
+
+def _limpar_codigo(codigo: str) -> None:
+    conn = get_connection()
+    try:
+        with conn.cursor() as cur:
+            cur.execute("DELETE FROM CLIENTE WHERE CODIGO = %s", (codigo,))
+    finally:
+        conn.close()
+
+
+def test_criar_cliente_com_data_e_decimais_vazios_nao_gera_500():
+    """
+    Integração com o banco real de dev: DATA_CONTRATO/decimais são NOT NULL
+    e o dev roda em STRICT_TRANS_TABLES — submeter strings vazias deve ser
+    capturado pelo router (pymysql.err.DataError) e reexibir o formulário
+    com erro_gravacao, nunca estourar como 500.
+    """
+    codigo = "999906"
+    dados_form = {campo: "x" for campo in router_clientes.db_clientes.CAMPOS_CLIENTE}
+    dados_form.update(
+        {
+            "CODIGO": codigo,
+            "CNPJ": "11222333000181",
+            "IMPLANTACAO": "",
+            "MENSALIDADE": "",
+            "JUROS_MORA": "",
+            "JUROS_MULTA": "",
+            "DATA_CONTRATO": "",
+            "VENCIMENTO_CONTRATO": "",
+            "DIA_VENCIMENTO": "10",
+        }
+    )
+    try:
+        resposta = client.post("/clientes/novo", data=dados_form)
+        assert resposta.status_code == 200
+        assert "Não foi possível salvar" in resposta.text
+    finally:
+        _limpar_codigo(codigo)
+
+
+def test_criar_cliente_com_ambos_avisos_confirma_ambos_de_uma_vez(monkeypatch):
+    """
+    Reproduz Fix 3: um cliente com CODIGO duplicado E DV de documento
+    inválido não pode ficar preso em loop entre os dois avisos — confirmar
+    os dois de uma vez (hidden fields carregados de um aviso para o outro)
+    deve efetivamente criar o cliente.
+    """
+    monkeypatch.setattr(router_clientes.db_clientes, "codigo_em_uso", lambda codigo, ignorar_id=None: True)
+    criado = {}
+    monkeypatch.setattr(
+        router_clientes.db_clientes, "criar_cliente", lambda dados: criado.setdefault("ok", True) and 42
+    )
+
+    dados_form = {campo: "000002" if campo == "CODIGO" else "x" for campo in router_clientes.db_clientes.CAMPOS_CLIENTE}
+    dados_form.update(
+        {
+            "IMPLANTACAO": "0",
+            "MENSALIDADE": "100",
+            "JUROS_MORA": "0",
+            "JUROS_MULTA": "0",
+            "DATA_CONTRATO": "2026-01-01",
+            "VENCIMENTO_CONTRATO": "2027-01-01",
+            "DIA_VENCIMENTO": "10",
+            "CNPJ": "11144477734",  # CPF com DV inválido (1 dígito diferente do válido "...735")
+        }
+    )
+
+    # Round 1: nem codigo nem dv confirmados -> deve pedir confirmação de código duplicado.
+    resposta = client.post("/clientes/novo", data=dados_form)
+    assert resposta.status_code == 200
+    assert "já está em uso" in resposta.text
+    assert "ok" not in criado
+
+    # Round 2: confirma o código duplicado -> agora deve pedir confirmação do DV inválido.
+    dados_form["confirmar_codigo_duplicado"] = "1"
+    resposta = client.post("/clientes/novo", data=dados_form)
+    assert resposta.status_code == 200
+    assert "não confere" in resposta.text
+    assert "ok" not in criado
+    # A raiz do Fix 3: o form do aviso de DV precisa carregar
+    # confirmar_codigo_duplicado=1 adiante (senão confirmar só o DV a seguir
+    # reabriria o aviso de código duplicado, em loop infinito).
+    assert 'name="confirmar_codigo_duplicado" value="1"' in resposta.text
+
+    # Round 3: confirma ambos de uma vez -> deve criar (303), sem cair em outro loop.
+    dados_form["confirmar_dv_invalido"] = "1"
+    resposta = client.post("/clientes/novo", data=dados_form)
+    assert resposta.status_code == 303
+    assert criado.get("ok") is True