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>

app/routers/clientes.py

@@ -6,6 +6,7 @@ Rotas de gestão de CLIENTE: listar/buscar, criar, editar, ver detalhe
 from typing import Optional
 from urllib.parse import urlencode
 
+import pymysql
 from fastapi import APIRouter, Depends, Form, Request
 from fastapi.responses import HTMLResponse, RedirectResponse
 from fastapi.templating import Jinja2Templates
@@ -59,12 +60,17 @@ async def criar(request: Request, usuario: str = Depends(exigir_login)):
     form = dict((await request.form()))
     dados = _ler_form_cliente(form)
     confirmar_duplicado = form.get("confirmar_codigo_duplicado") == "1"
+    confirmar_dv = form.get("confirmar_dv_invalido") == "1"
 
     if not confirmar_duplicado and db_clientes.codigo_em_uso(dados["CODIGO"]):
         return templates.TemplateResponse(
             request,
             "cliente_form.html",
-            {"cliente": None, "dados": dados, "campos": db_clientes.CAMPOS_CLIENTE, "aviso_codigo_duplicado": True},
+            {
+                "cliente": None, "dados": dados, "campos": db_clientes.CAMPOS_CLIENTE,
+                "aviso_codigo_duplicado": True,
+                "confirmar_codigo_duplicado": confirmar_duplicado, "confirmar_dv_invalido": confirmar_dv,
+            },
         )
 
     documento_normalizado, formato_valido, tipo = normalizar_documento(dados["CNPJ"])
@@ -73,14 +79,25 @@ async def criar(request: Request, usuario: str = Depends(exigir_login)):
         dv_invalido = not (
             validar_dv_cpf(documento_normalizado) if tipo == "CPF" else validar_dv_cnpj(documento_normalizado)
         )
-    if dv_invalido and form.get("confirmar_dv_invalido") != "1":
+    if dv_invalido and not confirmar_dv:
         return templates.TemplateResponse(
             request,
             "cliente_form.html",
-            {"cliente": None, "dados": dados, "campos": db_clientes.CAMPOS_CLIENTE, "aviso_dv_invalido": True},
+            {
+                "cliente": None, "dados": dados, "campos": db_clientes.CAMPOS_CLIENTE,
+                "aviso_dv_invalido": True,
+                "confirmar_codigo_duplicado": confirmar_duplicado, "confirmar_dv_invalido": confirmar_dv,
+            },
         )
 
-    novo_id = db_clientes.criar_cliente(dados)
+    try:
+        novo_id = db_clientes.criar_cliente(dados)
+    except (pymysql.err.DataError, pymysql.err.IntegrityError) as exc:
+        return templates.TemplateResponse(
+            request,
+            "cliente_form.html",
+            {"cliente": None, "dados": dados, "campos": db_clientes.CAMPOS_CLIENTE, "erro_gravacao": str(exc)},
+        )
     return _redirect_com_mensagem(f"/clientes/{novo_id}", "Cliente criado.")
 
 
@@ -133,7 +150,14 @@ async def editar(request: Request, cliente_id: int, usuario: str = Depends(exigi
             {"cliente": {"ID": cliente_id}, "dados": dados, "campos": db_clientes.CAMPOS_CLIENTE, "aviso_codigo_duplicado": True},
         )
 
-    db_clientes.atualizar_cliente(cliente_id, dados)
+    try:
+        db_clientes.atualizar_cliente(cliente_id, dados)
+    except (pymysql.err.DataError, pymysql.err.IntegrityError) as exc:
+        return templates.TemplateResponse(
+            request,
+            "cliente_form.html",
+            {"cliente": {"ID": cliente_id}, "dados": dados, "campos": db_clientes.CAMPOS_CLIENTE, "erro_gravacao": str(exc)},
+        )
     return _redirect_com_mensagem(f"/clientes/{cliente_id}", "Cliente atualizado.")