feat: GET /clientes le por_pagina da query/cookie e expoe contexto de paginacao

app/routers/clientes.py

@@ -165,6 +165,7 @@ def listar(
     ordenar_por: str = db_clientes.ORDENACAO_PADRAO,
     direcao: str = db_clientes.DIRECAO_PADRAO,
     pagina: int = 1,
+    por_pagina: Optional[int] = None,
     mensagem: Optional[str] = None,
     mensagem_tipo: Optional[str] = None,
     usuario: str = Depends(exigir_login),
@@ -174,24 +175,42 @@ def listar(
     if direcao not in db_clientes.DIRECOES_VALIDAS:
         direcao = db_clientes.DIRECAO_PADRAO
 
+    por_pagina_efetivo = _resolver_por_pagina(por_pagina, request.cookies.get(POR_PAGINA_COOKIE))
+
     pagina = max(pagina, 1)
     total = db_clientes.contar_clientes(busca=busca or None, ordenar_por=ordenar_por)
-    total_paginas = max(math.ceil(total / TAMANHO_PAGINA), 1)
+    total_paginas = max(math.ceil(total / por_pagina_efetivo), 1)
     pagina = min(pagina, total_paginas)
-    offset = (pagina - 1) * TAMANHO_PAGINA
+    offset = (pagina - 1) * por_pagina_efetivo
 
     clientes = db_clientes.listar_clientes(
-        busca=busca or None, limite=TAMANHO_PAGINA, offset=offset, ordenar_por=ordenar_por, direcao=direcao
+        busca=busca or None, limite=por_pagina_efetivo, offset=offset, ordenar_por=ordenar_por, direcao=direcao
     )
-    return templates.TemplateResponse(
+
+    primeiro_item = offset + 1 if total > 0 else 0
+    ultimo_item = min(offset + por_pagina_efetivo, total)
+
+    resposta = templates.TemplateResponse(
         request,
         "clientes_lista.html",
         {
             "clientes": clientes, "busca": busca, "ordenar_por": ordenar_por, "direcao": direcao,
             "mensagem": mensagem, "mensagem_tipo": mensagem_tipo,
             "pagina": pagina, "total_paginas": total_paginas, "total": total,
+            "por_pagina": por_pagina_efetivo, "opcoes_por_pagina": OPCOES_POR_PAGINA,
+            "primeiro_item": primeiro_item, "ultimo_item": ultimo_item,
+            "janela_paginas": _janela_paginas(pagina, total_paginas),
         },
     )
+    if por_pagina in OPCOES_POR_PAGINA:
+        # Só regrava o cookie quando a query string trouxer um valor válido
+        # (não um valor herdado do cookie que já estava lá) — evita ficar
+        # reescrevendo o mesmo Set-Cookie em toda requisição à toa.
+        resposta.set_cookie(
+            POR_PAGINA_COOKIE, str(por_pagina), samesite="lax",
+            secure=request.url.scheme == "https",
+        )
+    return resposta
 
 
 @router.get("/novo", response_class=HTMLResponse)

tests/test_router_clientes.py

@@ -33,6 +33,20 @@ def _sem_log_real(monkeypatch):
     monkeypatch.setattr(router_clientes.db_log, "registrar", lambda *args, **kwargs: None)
 
 
+@pytest.fixture(autouse=True)
+def _limpar_cookies():
+    """Limpa cookies entre testes para evitar compartilhamento de estado."""
+    # Salva os cookies iniciais (csrf_token deve persistir)
+    csrf_token = client.cookies.get("csrf_token")
+    client.cookies.clear()
+    client.cookies.set("csrf_token", CSRF_TESTE)
+    yield
+    # Limpa novamente após o teste
+    csrf_token = client.cookies.get("csrf_token")
+    client.cookies.clear()
+    client.cookies.set("csrf_token", CSRF_TESTE)
+
+
 def _form_valido(codigo: str = "000001") -> dict:
     """Monta um dict de formulário válido (todos os campos preenchidos)."""
     dados = {campo: "x" for campo in router_clientes.db_clientes.CAMPOS_CLIENTE}
@@ -87,6 +101,64 @@ def test_janela_paginas_ultima_pagina():
     assert router_clientes._janela_paginas(20, 20) == [1, None, 19, 20]
 
 
+def test_listar_clientes_por_pagina_padrao_e_15(monkeypatch):
+    capturado = {}
+    monkeypatch.setattr(
+        router_clientes.db_clientes,
+        "listar_clientes",
+        lambda busca=None, limite=100, offset=0, ordenar_por="razao", direcao="asc": capturado.setdefault("limite", limite) and [],
+    )
+    monkeypatch.setattr(router_clientes.db_clientes, "contar_clientes", lambda busca=None, ordenar_por="razao": 3)
+
+    resposta = client.get("/clientes")
+    assert resposta.status_code == 200
+    assert capturado["limite"] == 15
+
+
+def test_listar_clientes_por_pagina_da_query_e_usada_e_grava_cookie(monkeypatch):
+    capturado = {}
+    monkeypatch.setattr(
+        router_clientes.db_clientes,
+        "listar_clientes",
+        lambda busca=None, limite=100, offset=0, ordenar_por="razao", direcao="asc": capturado.setdefault("limite", limite) and [],
+    )
+    monkeypatch.setattr(router_clientes.db_clientes, "contar_clientes", lambda busca=None, ordenar_por="razao": 3)
+
+    resposta = client.get("/clientes?por_pagina=50")
+    assert resposta.status_code == 200
+    assert capturado["limite"] == 50
+    assert resposta.cookies.get(router_clientes.POR_PAGINA_COOKIE) == "50"
+
+
+def test_listar_clientes_usa_cookie_quando_sem_por_pagina_na_query(monkeypatch):
+    capturado = {}
+    monkeypatch.setattr(
+        router_clientes.db_clientes,
+        "listar_clientes",
+        lambda busca=None, limite=100, offset=0, ordenar_por="razao", direcao="asc": capturado.setdefault("limite", limite) and [],
+    )
+    monkeypatch.setattr(router_clientes.db_clientes, "contar_clientes", lambda busca=None, ordenar_por="razao": 3)
+
+    resposta = client.get("/clientes", cookies={router_clientes.POR_PAGINA_COOKIE: "30"})
+    assert resposta.status_code == 200
+    assert capturado["limite"] == 30
+
+
+def test_listar_clientes_por_pagina_invalida_na_query_cai_no_padrao_e_nao_grava_cookie(monkeypatch):
+    capturado = {}
+    monkeypatch.setattr(
+        router_clientes.db_clientes,
+        "listar_clientes",
+        lambda busca=None, limite=100, offset=0, ordenar_por="razao", direcao="asc": capturado.setdefault("limite", limite) and [],
+    )
+    monkeypatch.setattr(router_clientes.db_clientes, "contar_clientes", lambda busca=None, ordenar_por="razao": 3)
+
+    resposta = client.get("/clientes?por_pagina=999")
+    assert resposta.status_code == 200
+    assert capturado["limite"] == 15
+    assert router_clientes.POR_PAGINA_COOKIE not in resposta.cookies
+
+
 def test_listar_clientes(monkeypatch):
     monkeypatch.setattr(
         router_clientes.db_clientes,
@@ -112,7 +184,7 @@ def test_listar_clientes_pagina_com_controles_de_paginacao(monkeypatch):
     )
     monkeypatch.setattr(router_clientes.db_clientes, "contar_clientes", lambda busca=None, ordenar_por="razao": 250)
 
-    resposta = client.get("/clientes?pagina=2")
+    resposta = client.get("/clientes?pagina=2&por_pagina=100")
     assert resposta.status_code == 200
     assert "Página 2 de 3" in resposta.text
     assert "250 clientes" in resposta.text