feat: cabecalhos clicaveis para ordenar (crescente/decrescente) a lista de clientes

Codigo, Razao, Fantasia e CNPJ agora sao links no cabecalho da tabela:
clicar ordena crescente; clicar de novo na mesma coluna alterna pra
decrescente (e vice-versa). Trocar de coluna sempre comeca em
crescente. Seta (▲/▼) indica a coluna/direcao ativa.

db_clientes.listar_clientes() ganha o parametro direcao (whitelist
asc/desc, igual ja acontecia com ordenar_por). Links de
Anterior/Proxima da paginacao preservam a direcao escolhida.

97/97 testes passando.

app/db/clientes.py

@@ -26,15 +26,25 @@ ORDENACOES_VALIDAS = {
 }
 ORDENACAO_PADRAO = "razao"
 
+# Idem para a direção — nunca interpolar "asc"/"desc" vindo da URL sem
+# passar por aqui.
+DIRECOES_VALIDAS = {"asc": "ASC", "desc": "DESC"}
+DIRECAO_PADRAO = "asc"
+
 
 class ClienteComDependenciasError(Exception):
     """Levantada ao tentar excluir um CLIENTE que ainda tem CLIENTE_CONTATO."""
 
 
 def listar_clientes(
-    busca: str | None = None, limite: int = 100, offset: int = 0, ordenar_por: str = ORDENACAO_PADRAO
+    busca: str | None = None,
+    limite: int = 100,
+    offset: int = 0,
+    ordenar_por: str = ORDENACAO_PADRAO,
+    direcao: str = DIRECAO_PADRAO,
 ) -> list[dict]:
     coluna = ORDENACOES_VALIDAS.get(ordenar_por, ORDENACOES_VALIDAS[ORDENACAO_PADRAO])
+    direcao_sql = DIRECOES_VALIDAS.get(direcao, DIRECOES_VALIDAS[DIRECAO_PADRAO])
     conn = get_connection()
     try:
         with conn.cursor() as cur:
@@ -44,12 +54,12 @@ def listar_clientes(
                 # campos de uma vez.
                 sql = (
                     f"SELECT {_COLUNAS_SELECT} FROM CLIENTE "
-                    f"WHERE {coluna} LIKE %s ORDER BY {coluna} LIMIT %s OFFSET %s"
+                    f"WHERE {coluna} LIKE %s ORDER BY {coluna} {direcao_sql} LIMIT %s OFFSET %s"
                 )
                 cur.execute(sql, (f"%{busca}%", limite, offset))
             else:
                 cur.execute(
-                    f"SELECT {_COLUNAS_SELECT} FROM CLIENTE ORDER BY {coluna} LIMIT %s OFFSET %s",
+                    f"SELECT {_COLUNAS_SELECT} FROM CLIENTE ORDER BY {coluna} {direcao_sql} LIMIT %s OFFSET %s",
                     (limite, offset),
                 )
             return cur.fetchall()

app/routers/clientes.py

@@ -81,6 +81,7 @@ def listar(
     request: Request,
     busca: Optional[str] = None,
     ordenar_por: str = db_clientes.ORDENACAO_PADRAO,
+    direcao: str = db_clientes.DIRECAO_PADRAO,
     pagina: int = 1,
     mensagem: Optional[str] = None,
     mensagem_tipo: Optional[str] = None,
@@ -88,6 +89,8 @@ def listar(
 ):
     if ordenar_por not in db_clientes.ORDENACOES_VALIDAS:
         ordenar_por = db_clientes.ORDENACAO_PADRAO
+    if direcao not in db_clientes.DIRECOES_VALIDAS:
+        direcao = db_clientes.DIRECAO_PADRAO
 
     pagina = max(pagina, 1)
     total = db_clientes.contar_clientes(busca=busca or None, ordenar_por=ordenar_por)
@@ -96,13 +99,13 @@ def listar(
     offset = (pagina - 1) * TAMANHO_PAGINA
 
     clientes = db_clientes.listar_clientes(
-        busca=busca or None, limite=TAMANHO_PAGINA, offset=offset, ordenar_por=ordenar_por
+        busca=busca or None, limite=TAMANHO_PAGINA, offset=offset, ordenar_por=ordenar_por, direcao=direcao
     )
     return templates.TemplateResponse(
         request,
         "clientes_lista.html",
         {
-            "clientes": clientes, "busca": busca, "ordenar_por": ordenar_por,
+            "clientes": clientes, "busca": busca, "ordenar_por": ordenar_por, "direcao": direcao,
             "mensagem": mensagem, "mensagem_tipo": mensagem_tipo,
             "pagina": pagina, "total_paginas": total_paginas, "total": total,
         },

app/templates/base.html

@@ -12,6 +12,8 @@
     main { padding: 20px; max-width: 960px; margin: 0 auto; }
     table { width: 100%; border-collapse: collapse; margin-top: 12px; }
     th, td { text-align: left; padding: 8px; border-bottom: 1px solid #3a3a3e; }
+    th a { color: inherit; text-decoration: none; white-space: nowrap; }
+    th a:hover { color: #F5821F; }
     input, select { padding: 8px; border-radius: 6px; border: 1px solid #3a3a3e; background: #17171a; color: #f4f4f5; width: 100%; box-sizing: border-box; }
     label { display: block; margin-top: 10px; font-size: 0.85rem; color: #a1a1aa; }
     button { margin-top: 14px; padding: 10px 16px; border: none; border-radius: 6px; background: #F5821F; color: #17171a; font-weight: 700; cursor: pointer; }

app/templates/clientes_lista.html

@@ -16,7 +16,18 @@
   </form>
   <p><a class="botao" href="/clientes/novo">+ Novo cliente</a></p>
   <table>
-    <tr><th>Código</th><th>Razão</th><th>Fantasia</th><th>CNPJ</th><th></th></tr>
+    <tr>
+      {% set colunas_tabela = [("codigo", "Código"), ("razao", "Razão"), ("fantasia", "Fantasia"), ("cnpj", "CNPJ")] %}
+      {% for campo, rotulo in colunas_tabela %}
+        {% set nova_direcao = "desc" if (ordenar_por == campo and direcao == "asc") else "asc" %}
+        <th>
+          <a href="/clientes?ordenar_por={{ campo }}&direcao={{ nova_direcao }}&pagina=1{{ '&busca=' + busca if busca else '' }}">
+            {{ rotulo }}{% if ordenar_por == campo %}{{ " ▲" if direcao == "asc" else " ▼" }}{% endif %}
+          </a>
+        </th>
+      {% endfor %}
+      <th></th>
+    </tr>
     {% for c in clientes %}
     <tr>
       <td>{{ c.CODIGO }}</td>
@@ -30,11 +41,11 @@
   {% if total_paginas and total_paginas > 1 %}
     <p>
       {% if pagina > 1 %}
-        <a class="botao" href="/clientes?pagina={{ pagina - 1 }}{{ '&busca=' + busca if busca else '' }}&ordenar_por={{ ordenar_por }}">&larr; Anterior</a>
+        <a class="botao" href="/clientes?pagina={{ pagina - 1 }}{{ '&busca=' + busca if busca else '' }}&ordenar_por={{ ordenar_por }}&direcao={{ direcao }}">&larr; Anterior</a>
       {% endif %}
       Página {{ pagina }} de {{ total_paginas }} ({{ total }} clientes)
       {% if pagina < total_paginas %}
-        <a class="botao" href="/clientes?pagina={{ pagina + 1 }}{{ '&busca=' + busca if busca else '' }}&ordenar_por={{ ordenar_por }}">Próxima &rarr;</a>
+        <a class="botao" href="/clientes?pagina={{ pagina + 1 }}{{ '&busca=' + busca if busca else '' }}&ordenar_por={{ ordenar_por }}&direcao={{ direcao }}">Próxima &rarr;</a>
       {% endif %}
     </p>
   {% endif %}

tests/test_db_clientes.py

@@ -106,6 +106,29 @@ def test_listar_clientes_ordenacao_invalida_usa_padrao(cliente_id):
     assert any(c["CODIGO"] == "999901" for c in resultado)
 
 
+def test_listar_clientes_direcao_asc_e_desc(cliente_id):
+    # Dois clientes de teste com códigos diferentes, mesma busca por RAZAO,
+    # pra comparar a ordem entre asc/desc de forma determinística.
+    outro_id = db_clientes.criar_cliente(dict(CLIENTE_TESTE, CODIGO="999905"))
+    try:
+        asc = db_clientes.listar_clientes(busca="TESTE PAINEL RAZAO", ordenar_por="codigo", direcao="asc")
+        desc = db_clientes.listar_clientes(busca="TESTE PAINEL RAZAO", ordenar_por="codigo", direcao="desc")
+        codigos_asc = [c["CODIGO"] for c in asc]
+        codigos_desc = [c["CODIGO"] for c in desc]
+        assert codigos_asc == sorted(codigos_asc)
+        assert codigos_desc == sorted(codigos_desc, reverse=True)
+    finally:
+        _limpar("999905")
+
+
+def test_listar_clientes_direcao_invalida_usa_padrao_asc(cliente_id):
+    # Não deve quebrar nem virar SQL arbitrário — cai em ASC.
+    resultado = db_clientes.listar_clientes(
+        busca="999901", ordenar_por="codigo", direcao="ASC; DROP TABLE CLIENTE"
+    )
+    assert resultado[0]["CODIGO"] == "999901"
+
+
 def test_proximo_codigo_sugerido_ignora_faixa_de_teste(cliente_id):
     # CLIENTE_TESTE usa CODIGO "999901" (faixa reservada para teste, >= 900000)
     # — a sugestão não pode considerar isso, senão qualquer sobra de dado de

tests/test_main.py

@@ -22,7 +22,7 @@ def test_docs_desabilitado_retorna_404():
 def test_raiz_redireciona_para_clientes_com_login(monkeypatch):
     from app.routers import clientes as router_clientes
 
-    monkeypatch.setattr(router_clientes.db_clientes, "listar_clientes", lambda busca=None, limite=100, offset=0: [])
+    monkeypatch.setattr(router_clientes.db_clientes, "listar_clientes", lambda busca=None, limite=100, offset=0, ordenar_por="razao", direcao="asc": [])
     monkeypatch.setattr(router_clientes.db_clientes, "contar_clientes", lambda busca=None, ordenar_por="razao": 0)
     resposta = client.get("/", headers=_AUTH_HEADERS, follow_redirects=False)
     assert resposta.status_code == 307

tests/test_router_clientes.py

@@ -57,7 +57,7 @@ def test_listar_clientes(monkeypatch):
     monkeypatch.setattr(
         router_clientes.db_clientes,
         "listar_clientes",
-        lambda busca=None, limite=100, offset=0, ordenar_por="razao": [
+        lambda busca=None, limite=100, offset=0, ordenar_por="razao", direcao="asc": [
             {"ID": 1, "CODIGO": "000001", "RAZAO": "Cliente Um", "FANTASIA": "Um", "CNPJ": "11222333000181"}
         ],
     )
@@ -71,7 +71,7 @@ def test_listar_clientes_pagina_com_controles_de_paginacao(monkeypatch):
     monkeypatch.setattr(
         router_clientes.db_clientes,
         "listar_clientes",
-        lambda busca=None, limite=100, offset=0, ordenar_por="razao": [
+        lambda busca=None, limite=100, offset=0, ordenar_por="razao", direcao="asc": [
             {"ID": i, "CODIGO": f"{i:06d}", "RAZAO": f"Cliente {i}", "FANTASIA": f"C{i}", "CNPJ": "11222333000181"}
             for i in range(1, 6)
         ],
@@ -89,7 +89,7 @@ def test_listar_clientes_pagina_com_controles_de_paginacao(monkeypatch):
 def test_listar_clientes_ordenar_por_invalido_cai_no_padrao(monkeypatch):
     capturado = {}
 
-    def _listar_clientes(busca=None, limite=100, offset=0, ordenar_por="razao"):
+    def _listar_clientes(busca=None, limite=100, offset=0, ordenar_por="razao", direcao="asc"):
         capturado["ordenar_por"] = ordenar_por
         return []
 
@@ -103,6 +103,43 @@ def test_listar_clientes_ordenar_por_invalido_cai_no_padrao(monkeypatch):
     assert capturado["ordenar_por"] == "codigo"
 
 
+def test_cabecalhos_da_lista_alternam_direcao(monkeypatch):
+    monkeypatch.setattr(
+        router_clientes.db_clientes, "listar_clientes", lambda **kwargs: []
+    )
+    monkeypatch.setattr(router_clientes.db_clientes, "contar_clientes", lambda busca=None, ordenar_por="razao": 0)
+
+    # Sem ordenar_por/direcao na URL: padrão é razao/asc. Clicar de novo em
+    # "Razão" deve levar pra desc; clicar em "Código" (coluna diferente da
+    # atual) deve levar pra asc (não continua o desc de outra coluna).
+    resposta = client.get("/clientes")
+    assert 'ordenar_por=razao&direcao=desc' in resposta.text
+    assert 'ordenar_por=codigo&direcao=asc' in resposta.text
+
+    # Já ordenado por codigo/desc: clicar em "Código" de novo deve voltar pra asc.
+    resposta = client.get("/clientes?ordenar_por=codigo&direcao=desc")
+    assert 'ordenar_por=codigo&direcao=asc' in resposta.text
+    # E as outras colunas oferecem asc (primeira vez que seriam clicadas).
+    assert 'ordenar_por=razao&direcao=asc' in resposta.text
+
+
+def test_listar_clientes_direcao_invalida_cai_no_padrao(monkeypatch):
+    capturado = {}
+
+    def _listar_clientes(busca=None, limite=100, offset=0, ordenar_por="razao", direcao="asc"):
+        capturado["direcao"] = direcao
+        return []
+
+    monkeypatch.setattr(router_clientes.db_clientes, "listar_clientes", _listar_clientes)
+    monkeypatch.setattr(router_clientes.db_clientes, "contar_clientes", lambda busca=None, ordenar_por="razao": 0)
+
+    client.get("/clientes?direcao=coisa_invalida")
+    assert capturado["direcao"] == "asc"
+
+    client.get("/clientes?direcao=desc")
+    assert capturado["direcao"] == "desc"
+
+
 def test_form_novo_preenche_codigo_sugerido(monkeypatch):
     monkeypatch.setattr(router_clientes.db_clientes, "proximo_codigo_sugerido", lambda: "000243")
     resposta = client.get("/clientes/novo")