Add 'gerenciador/' from commit '34cc9c75a57dedbf61a6e6a1ba1f35f76e72434b'

git-subtree-dir: gerenciador git-subtree-mainline: f4f546c928 git-subtree-split: 34cc9c75a5
2026-09-29 14:43:12 -03:00
parent f4f546c928 34cc9c75a5
commit d95165fc8f
84 changed files with 8906 additions and 0 deletions
@@ -0,0 +1,31 @@
+"""
+Leitura somente-leitura de Clientes_Chaves (tabela legada — ver
+licenciamento-n8n/docs/MAPEAMENTO_BANCO.md seção 3). O painel NUNCA escreve
+aqui; só mostra status para conferência.
+"""
+from .connection import get_connection
+
+MESES = [f"M{i}" for i in range(1, 13)]
+
+
+def status_chaves(codigo: str) -> dict | None:
+    conn = get_connection()
+    try:
+        with conn.cursor() as cur:
+            colunas = ", ".join(MESES)
+            cur.execute(
+                f"SELECT ID, Cliente, {colunas} FROM Clientes_Chaves WHERE ID = %s",
+                (codigo,),
+            )
+            linha = cur.fetchone()
+    finally:
+        conn.close()
+
+    if linha is None:
+        return None
+
+    return {
+        "codigo": linha["ID"],
+        "cliente": linha["Cliente"],
+        "meses": {mes: (linha[mes] or None) for mes in MESES},
+    }
@@ -0,0 +1,267 @@
+"""
+CRUD completo de CLIENTE. Única tabela cadastral (ID autoincrement é a PK
+técnica; CODIGO é o identificador de negócio usado pelo resto do sistema —
+ver licenciamento-n8n/docs/MAPEAMENTO_BANCO.md).
+
+CLIENTE.ATIVO (TINYINT(1) NOT NULL DEFAULT 1) controla se o cliente
+aparece no filtro padrão da listagem ("Ativos"). Se CLIENTE já existir de
+uma instalação anterior sem essa coluna, rode:
+
+    ALTER TABLE CLIENTE
+      ADD COLUMN ATIVO TINYINT(1) NOT NULL DEFAULT 1
+      AFTER DIA_VENCIMENTO;
+
+DEFAULT 1 é intencional: todo cliente cadastrado antes da migração nasce
+como Ativo — decisão do projeto (quem administra desativa manualmente os
+que sabe que não são mais, ver
+docs/superpowers/specs/2026-08-20-status-ativo-clientes-design.md).
+Cadastros/edições novos sempre informam ATIVO explicitamente (vindo do
+formulário), nunca dependem desse default.
+"""
+import pymysql
+
+from .connection import get_connection
+
+CAMPOS_CLIENTE = [
+    "CODIGO", "CNPJ", "RAZAO", "FANTASIA", "IE", "ENDERECO", "CIDADE",
+    "BAIRRO", "UF", "CONTATO", "TELEFONE", "CELULAR", "CEP", "IMPLANTACAO",
+    "MENSALIDADE", "JUROS_MORA", "JUROS_MULTA", "DATA_CONTRATO", "EMAIL",
+    "OBS", "VENCIMENTO_CONTRATO", "DIA_VENCIMENTO", "ATIVO",
+]
+
+_COLUNAS_SELECT = ", ".join(["ID", *CAMPOS_CLIENTE])
+
+# Whitelist de colunas aceitas para ordenar a listagem — nunca interpolar
+# o valor de "ordenar_por" vindo da URL direto no SQL sem passar por aqui.
+ORDENACOES_VALIDAS = {
+    "codigo": "CODIGO",
+    "razao": "RAZAO",
+    "fantasia": "FANTASIA",
+    "cnpj": "CNPJ",
+}
+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,
+    direcao: str = DIRECAO_PADRAO,
+    filtro_ativo: int | None = 1,
+) -> list[dict]:
+    coluna = ORDENACOES_VALIDAS.get(ordenar_por, ORDENACOES_VALIDAS[ORDENACAO_PADRAO])
+    direcao_sql = DIRECOES_VALIDAS.get(direcao, DIRECOES_VALIDAS[DIRECAO_PADRAO])
+    # A busca é restrita à mesma coluna escolhida em "ordenar_por" — selecionar
+    # "Código" busca só em CODIGO, não em todos os campos de uma vez.
+    # filtro_ativo: 1 = só ativos, 0 = só inativos, None = sem filtro (todos).
+    condicoes = []
+    params: list = []
+    if busca:
+        condicoes.append(f"{coluna} LIKE %s")
+        params.append(f"%{busca}%")
+    if filtro_ativo is not None:
+        condicoes.append("ATIVO = %s")
+        params.append(filtro_ativo)
+    where_sql = f"WHERE {' AND '.join(condicoes)} " if condicoes else ""
+
+    conn = get_connection()
+    try:
+        with conn.cursor() as cur:
+            sql = (
+                f"SELECT {_COLUNAS_SELECT} FROM CLIENTE {where_sql}"
+                f"ORDER BY {coluna} {direcao_sql} LIMIT %s OFFSET %s"
+            )
+            cur.execute(sql, [*params, limite, offset])
+            return cur.fetchall()
+    finally:
+        conn.close()
+
+
+def listar_clientes_para_fiscal() -> list[dict]:
+    """Para o endpoint interno GET /internal/fiscal/clients (app/internal_fiscal.py):
+    o Fiscal espelha TODOS os clientes (ativos e inativos — inativo continua
+    aparecendo em histórico do lado de lá), nunca só uma página. Payload
+    mínimo: ID é a PK técnica estável (CODIGO é editável, não serve de
+    identidade — mesma razão de FUNCIONARIO_PAINEL.ID no SSO). CNPJ (só dígitos) entra só para a busca/identificação no seletor do
+    Fiscal; sem endereço/contato."""
+    conn = get_connection()
+    try:
+        with conn.cursor() as cur:
+            cur.execute(
+                "SELECT ID, CODIGO, CNPJ, COALESCE(NULLIF(FANTASIA, ''), RAZAO) AS NOME, ATIVO "
+                "FROM CLIENTE ORDER BY ID"
+            )
+            return [
+                {"external_client_id": row["ID"], "code": row["CODIGO"], "display_name": row["NOME"], "cnpj": "".join(ch for ch in (row["CNPJ"] or "") if ch.isdigit()) or None, "active": bool(row["ATIVO"])}
+                for row in cur.fetchall()
+            ]
+    finally:
+        conn.close()
+
+
+def proximo_codigo_sugerido() -> str:
+    """
+    Sugere o próximo CODIGO sequencial (maior CODIGO numérico + 1, com zeros
+    à esquerda até 6 dígitos). É só uma sugestão pré-preenchida no formulário
+    de novo cliente — o campo continua editável, e codigo_em_uso() ainda
+    confere unicidade de verdade antes de gravar.
+    """
+    conn = get_connection()
+    try:
+        with conn.cursor() as cur:
+            # CODIGO >= 900000 é a faixa reservada para dados de teste deste
+            # painel (ver tests/test_db_clientes.py) — excluída aqui para a
+            # sugestão não disparar lá em cima se sobrar alguma linha de teste.
+            cur.execute(
+                "SELECT MAX(CAST(CODIGO AS UNSIGNED)) AS maior FROM CLIENTE "
+                "WHERE CODIGO REGEXP '^[0-9]+$' AND CAST(CODIGO AS UNSIGNED) < 900000"
+            )
+            maior = cur.fetchone()["maior"]
+    finally:
+        conn.close()
+    proximo = (maior or 0) + 1
+    return str(proximo).zfill(6)
+
+
+def contar_clientes(busca: str | None = None, ordenar_por: str = ORDENACAO_PADRAO, filtro_ativo: int | None = 1) -> int:
+    coluna = ORDENACOES_VALIDAS.get(ordenar_por, ORDENACOES_VALIDAS[ORDENACAO_PADRAO])
+    condicoes = []
+    params: list = []
+    if busca:
+        condicoes.append(f"{coluna} LIKE %s")
+        params.append(f"%{busca}%")
+    if filtro_ativo is not None:
+        condicoes.append("ATIVO = %s")
+        params.append(filtro_ativo)
+    where_sql = f"WHERE {' AND '.join(condicoes)}" if condicoes else ""
+
+    conn = get_connection()
+    try:
+        with conn.cursor() as cur:
+            cur.execute(f"SELECT COUNT(*) AS total FROM CLIENTE {where_sql}", params)
+            return cur.fetchone()["total"]
+    finally:
+        conn.close()
+
+
+def obter_cliente(cliente_id: int) -> dict | None:
+    conn = get_connection()
+    try:
+        with conn.cursor() as cur:
+            cur.execute(f"SELECT {_COLUNAS_SELECT} FROM CLIENTE WHERE ID = %s", (cliente_id,))
+            return cur.fetchone()
+    finally:
+        conn.close()
+
+
+def cnpj_em_uso(documento_normalizado: str, ignorar_id: int | None = None) -> bool:
+    """
+    True se já existe outro CLIENTE com esse mesmo CNPJ/CPF (o mesmo campo
+    CLIENTE.CNPJ aceita os dois — ver app/normalize.py). Compara ignorando
+    pontuação em vez de igualdade exata porque CLIENTE.CNPJ tem
+    formatação inconsistente em registros legados (alguns com máscara,
+    outros sem — ver licenciamento-n8n/docs/ANALISE_CLIENTE_IPREAL.md);
+    sem normalizar dos dois lados, um cadastro novo (sempre gravado sem
+    máscara) não bateria com um legado que ainda tem pontos/traços,
+    deixando passar o duplicado. `documento_normalizado` já chega sem
+    máscara (normalizar_documento); a normalização abaixo só precisa
+    tratar o lado do banco.
+    """
+    conn = get_connection()
+    try:
+        with conn.cursor() as cur:
+            sql = (
+                "SELECT ID FROM CLIENTE WHERE "
+                "UPPER(REPLACE(REPLACE(REPLACE(REPLACE(CNPJ, '.', ''), '/', ''), '-', ''), ' ', '')) = %s"
+            )
+            params = [documento_normalizado]
+            if ignorar_id is not None:
+                sql += " AND ID != %s"
+                params.append(ignorar_id)
+            cur.execute(sql, params)
+            return cur.fetchone() is not None
+    finally:
+        conn.close()
+
+
+def codigo_em_uso(codigo: str, ignorar_id: int | None = None) -> bool:
+    conn = get_connection()
+    try:
+        with conn.cursor() as cur:
+            sql = "SELECT ID FROM CLIENTE WHERE CODIGO = %s"
+            params = [codigo]
+            if ignorar_id is not None:
+                sql += " AND ID != %s"
+                params.append(ignorar_id)
+            cur.execute(sql, params)
+            return cur.fetchone() is not None
+    finally:
+        conn.close()
+
+
+def criar_cliente(dados: dict) -> int:
+    colunas = ", ".join(CAMPOS_CLIENTE)
+    marcadores = ", ".join(["%s"] * len(CAMPOS_CLIENTE))
+    valores = [dados[campo] for campo in CAMPOS_CLIENTE]
+    conn = get_connection()
+    try:
+        with conn.cursor() as cur:
+            cur.execute(f"INSERT INTO CLIENTE ({colunas}) VALUES ({marcadores})", valores)
+            return cur.lastrowid
+    finally:
+        conn.close()
+
+
+def atualizar_cliente(cliente_id: int, dados: dict) -> None:
+    atribuicoes = ", ".join(f"{campo} = %s" for campo in CAMPOS_CLIENTE)
+    valores = [dados[campo] for campo in CAMPOS_CLIENTE]
+    valores.append(cliente_id)
+    conn = get_connection()
+    try:
+        with conn.cursor() as cur:
+            cur.execute(f"UPDATE CLIENTE SET {atribuicoes} WHERE ID = %s", valores)
+    finally:
+        conn.close()
+
+
+def excluir_cliente(cliente_id: int) -> bool:
+    """True se a linha realmente existia (cur.rowcount > 0) — um ID
+    inexistente não gera erro nenhum do MySQL, então sem checar rowcount
+    o chamador não tem como distinguir "excluiu" de "não tinha nada pra
+    excluir"."""
+    conn = get_connection()
+    try:
+        with conn.cursor() as cur:
+            try:
+                cur.execute("DELETE FROM CLIENTE WHERE ID = %s", (cliente_id,))
+            except pymysql.err.IntegrityError as exc:
+                raise ClienteComDependenciasError(
+                    "Este cliente tem contatos cadastrados (CLIENTE_CONTATO) — remova-os antes de excluir."
+                ) from exc
+            return cur.rowcount > 0
+    finally:
+        conn.close()
+
+
+def alternar_ativo(cliente_id: int) -> bool:
+    """True se a linha existia (cur.rowcount > 0) — mesma lógica de
+    excluir_cliente/redefinir_senha pra distinguir "alternou" de "não
+    tinha nada pra alternar". UPDATE ... SET ATIVO = 1 - ATIVO inverte o
+    valor atomicamente, sem precisar de um SELECT antes."""
+    conn = get_connection()
+    try:
+        with conn.cursor() as cur:
+            cur.execute("UPDATE CLIENTE SET ATIVO = 1 - ATIVO WHERE ID = %s", (cliente_id,))
+            return cur.rowcount > 0
+    finally:
+        conn.close()
@@ -0,0 +1,22 @@
+"""
+Única porta de entrada para conexão MySQL do painel. Todo módulo em
+app/db/*.py chama get_connection() daqui — nunca abre pymysql.connect()
+por conta própria.
+"""
+import os
+
+import pymysql
+import pymysql.cursors
+
+
+def get_connection() -> pymysql.connections.Connection:
+    """Abre uma conexão nova por requisição (escala MVP; sem pool)."""
+    return pymysql.connect(
+        host=os.environ["DB_HOST"],
+        port=int(os.environ.get("DB_PORT", "3306")),
+        user=os.environ["DB_USER"],
+        password=os.environ["DB_PASSWORD"],
+        database=os.environ["DB_NAME"],
+        cursorclass=pymysql.cursors.DictCursor,
+        autocommit=True,
+    )
@@ -0,0 +1,83 @@
+"""
+CRUD de CLIENTE_CONTATO — relacionado a CLIENTE por CLIENTE_ID (FK real,
+ON DELETE RESTRICT ON UPDATE CASCADE). Substitui CLIENTE_CONTATO_CHAVE
+(superseded — ver licenciamento-n8n/docs/CANDIDATO_CLIENTE_CONTATO.md).
+"""
+from .connection import get_connection
+
+
+def listar_contatos_por_cliente(cliente_id: int) -> list[dict]:
+    conn = get_connection()
+    try:
+        with conn.cursor() as cur:
+            cur.execute(
+                "SELECT ID, NOME, TELEFONE, EMAIL FROM CLIENTE_CONTATO "
+                "WHERE CLIENTE_ID = %s ORDER BY ID",
+                (cliente_id,),
+            )
+            return list(cur.fetchall())
+    finally:
+        conn.close()
+
+
+def contato_duplicado(cliente_id: int, telefone: str, ignorar_id: int | None = None) -> bool:
+    conn = get_connection()
+    try:
+        with conn.cursor() as cur:
+            sql = "SELECT ID FROM CLIENTE_CONTATO WHERE CLIENTE_ID = %s AND TELEFONE = %s"
+            params = [cliente_id, telefone]
+            if ignorar_id is not None:
+                sql += " AND ID != %s"
+                params.append(ignorar_id)
+            cur.execute(sql, params)
+            return cur.fetchone() is not None
+    finally:
+        conn.close()
+
+
+def inserir_contato(cliente_id: int, nome: str | None, telefone: str, email: str | None = None) -> int:
+    conn = get_connection()
+    try:
+        with conn.cursor() as cur:
+            cur.execute(
+                "INSERT INTO CLIENTE_CONTATO (CLIENTE_ID, NOME, TELEFONE, EMAIL) VALUES (%s, %s, %s, %s)",
+                (cliente_id, nome, telefone, email),
+            )
+            return cur.lastrowid
+    finally:
+        conn.close()
+
+
+def atualizar_contato(
+    contato_id: int, cliente_id: int, nome: str | None, telefone: str, email: str | None = None
+) -> bool:
+    """True se realmente existia um CLIENTE_CONTATO com esse ID nesse
+    cliente (cur.rowcount > 0) — um ID inexistente, ou de outro cliente,
+    não gera erro nenhum do MySQL (WHERE simplesmente não bate com
+    nada), então sem checar rowcount o chamador não tem como saber que
+    não alterou nada."""
+    conn = get_connection()
+    try:
+        with conn.cursor() as cur:
+            cur.execute(
+                "UPDATE CLIENTE_CONTATO SET NOME = %s, TELEFONE = %s, EMAIL = %s "
+                "WHERE ID = %s AND CLIENTE_ID = %s",
+                (nome, telefone, email, contato_id, cliente_id),
+            )
+            return cur.rowcount > 0
+    finally:
+        conn.close()
+
+
+def excluir_contato(contato_id: int, cliente_id: int) -> bool:
+    """True se uma linha foi de fato excluída — ver atualizar_contato."""
+    conn = get_connection()
+    try:
+        with conn.cursor() as cur:
+            cur.execute(
+                "DELETE FROM CLIENTE_CONTATO WHERE ID = %s AND CLIENTE_ID = %s",
+                (contato_id, cliente_id),
+            )
+            return cur.rowcount > 0
+    finally:
+        conn.close()
@@ -0,0 +1,153 @@
+"""
+CRUD de FUNCIONARIO_PAINEL — contas individuais de funcionário para login
+no painel (substitui/complementa o ADMIN_USER/ADMIN_PASSWORD único).
+
+A tabela já existe no banco de dev. Em qualquer outro ambiente, crie-a
+primeiro com:
+
+    CREATE TABLE FUNCIONARIO_PAINEL (
+      ID INT UNSIGNED NOT NULL AUTO_INCREMENT,
+      NOME VARCHAR(80) NOT NULL,
+      LOGIN VARCHAR(40) NOT NULL,
+      SENHA_HASH VARCHAR(255) NOT NULL,
+      PERFIL ENUM('ADMIN','PADRAO') NOT NULL DEFAULT 'ADMIN',
+      ATIVO TINYINT(1) NOT NULL DEFAULT 1,
+      CRIADO_EM DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+      PRIMARY KEY (ID),
+      UNIQUE KEY UQ_FUNCIONARIO_PAINEL_LOGIN (LOGIN)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_unicode_ci;
+
+Se a tabela já existir sem a coluna PERFIL (ambientes criados antes dessa
+funcionalidade), rode:
+
+    ALTER TABLE FUNCIONARIO_PAINEL
+      ADD COLUMN PERFIL ENUM('ADMIN','PADRAO') NOT NULL DEFAULT 'ADMIN'
+      AFTER SENHA_HASH;
+
+O DEFAULT 'ADMIN' do ALTER TABLE é intencional: todo funcionário cadastrado
+antes dessa migração vira admin automaticamente (decisão do projeto — ver
+docs/superpowers/specs/2026-08-13-permissoes-login-sessao-design.md).
+Cadastros novos sempre informam PERFIL explicitamente (vindo do
+formulário), nunca dependem desse default.
+
+Nunca excluído de verdade — "excluir" aqui é alternar ATIVO para 0
+(mesma lógica de nunca apagar histórico usada no resto do projeto).
+"""
+from .connection import get_connection
+from ..senha import gerar_hash
+
+
+def listar_funcionarios() -> list[dict]:
+    conn = get_connection()
+    try:
+        with conn.cursor() as cur:
+            cur.execute(
+                "SELECT ID, NOME, LOGIN, PERFIL, ATIVO, CRIADO_EM FROM FUNCIONARIO_PAINEL ORDER BY NOME"
+            )
+            return cur.fetchall()
+    finally:
+        conn.close()
+
+
+def obter_funcionario(funcionario_id: int) -> dict | None:
+    conn = get_connection()
+    try:
+        with conn.cursor() as cur:
+            cur.execute(
+                "SELECT ID, NOME, LOGIN, PERFIL, ATIVO, CRIADO_EM FROM FUNCIONARIO_PAINEL WHERE ID = %s",
+                (funcionario_id,),
+            )
+            return cur.fetchone()
+    finally:
+        conn.close()
+
+
+def obter_por_login(login: str) -> dict | None:
+    """Usado pelo login (app/auth.py) — inclui SENHA_HASH, ao contrário das outras consultas."""
+    conn = get_connection()
+    try:
+        with conn.cursor() as cur:
+            cur.execute(
+                "SELECT ID, NOME, LOGIN, SENHA_HASH, PERFIL, ATIVO FROM FUNCIONARIO_PAINEL WHERE LOGIN = %s",
+                (login,),
+            )
+            return cur.fetchone()
+    finally:
+        conn.close()
+
+
+def login_em_uso(login: str, ignorar_id: int | None = None) -> bool:
+    conn = get_connection()
+    try:
+        with conn.cursor() as cur:
+            sql = "SELECT ID FROM FUNCIONARIO_PAINEL WHERE LOGIN = %s"
+            params = [login]
+            if ignorar_id is not None:
+                sql += " AND ID != %s"
+                params.append(ignorar_id)
+            cur.execute(sql, params)
+            return cur.fetchone() is not None
+    finally:
+        conn.close()
+
+
+def criar_funcionario(nome: str, login: str, senha: str, perfil: str) -> int:
+    conn = get_connection()
+    try:
+        with conn.cursor() as cur:
+            cur.execute(
+                "INSERT INTO FUNCIONARIO_PAINEL (NOME, LOGIN, SENHA_HASH, PERFIL, ATIVO) VALUES (%s, %s, %s, %s, 1)",
+                (nome, login, gerar_hash(senha), perfil),
+            )
+            return cur.lastrowid
+    finally:
+        conn.close()
+
+
+def atualizar_funcionario(funcionario_id: int, nome: str, login: str, perfil: str) -> None:
+    """Nome/login/perfil — troca de senha é redefinir_senha()."""
+    conn = get_connection()
+    try:
+        with conn.cursor() as cur:
+            cur.execute(
+                "UPDATE FUNCIONARIO_PAINEL SET NOME = %s, LOGIN = %s, PERFIL = %s WHERE ID = %s",
+                (nome, login, perfil, funcionario_id),
+            )
+    finally:
+        conn.close()
+
+
+def redefinir_senha(funcionario_id: int, nova_senha: str) -> bool:
+    """True se o ID realmente existia (cur.rowcount > 0) — sem essa
+    checagem um ID inexistente fazia um UPDATE que não afeta nenhuma
+    linha, sem erro nenhum do MySQL, e o chamador registrava "sucesso"
+    no log mesmo sem ter mudado a senha de ninguém."""
+    conn = get_connection()
+    try:
+        with conn.cursor() as cur:
+            cur.execute(
+                "UPDATE FUNCIONARIO_PAINEL SET SENHA_HASH = %s WHERE ID = %s",
+                (gerar_hash(nova_senha), funcionario_id),
+            )
+            return cur.rowcount > 0
+    finally:
+        conn.close()
+
+
+def alternar_ativo(funcionario_id: int) -> None:
+    conn = get_connection()
+    try:
+        with conn.cursor() as cur:
+            cur.execute("UPDATE FUNCIONARIO_PAINEL SET ATIVO = 1 - ATIVO WHERE ID = %s", (funcionario_id,))
+    finally:
+        conn.close()
+
+
+def contar_admins_ativos() -> int:
+    conn = get_connection()
+    try:
+        with conn.cursor() as cur:
+            cur.execute("SELECT COUNT(*) AS total FROM FUNCIONARIO_PAINEL WHERE PERFIL = 'ADMIN' AND ATIVO = 1")
+            return cur.fetchone()["total"]
+    finally:
+        conn.close()
@@ -0,0 +1,80 @@
+"""
+Log de ações do painel (LOG_PAINEL) — uma linha por ação que muda estado
+(criar/editar/excluir cliente, adicionar/editar/excluir contato), sucesso
+ou erro. Escrita feita pelos routers via `registrar(...)`, nunca
+sobrescrita/editada depois — é histórico, não estado.
+
+A tabela já existe no banco de dev. Em qualquer outro ambiente (produção),
+crie-a primeiro com:
+
+    CREATE TABLE LOG_PAINEL (
+      ID INT UNSIGNED NOT NULL AUTO_INCREMENT,
+      CRIADO_EM DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+      USUARIO VARCHAR(60) NOT NULL,
+      ACAO VARCHAR(40) NOT NULL,
+      ENTIDADE VARCHAR(20) NOT NULL,
+      ENTIDADE_ID VARCHAR(20) DEFAULT NULL,
+      SUCESSO TINYINT(1) NOT NULL,
+      DETALHE VARCHAR(500) DEFAULT NULL,
+      PRIMARY KEY (ID),
+      KEY IDX_LOG_PAINEL_CRIADO_EM (CRIADO_EM)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_unicode_ci;
+"""
+from .connection import get_connection
+
+
+def registrar(
+    usuario: str,
+    acao: str,
+    entidade: str,
+    entidade_id: str | None,
+    sucesso: bool,
+    detalhe: str | None = None,
+) -> None:
+    conn = get_connection()
+    try:
+        with conn.cursor() as cur:
+            cur.execute(
+                "INSERT INTO LOG_PAINEL (USUARIO, ACAO, ENTIDADE, ENTIDADE_ID, SUCESSO, DETALHE) "
+                "VALUES (%s, %s, %s, %s, %s, %s)",
+                (usuario, acao, entidade, entidade_id, 1 if sucesso else 0, detalhe),
+            )
+    finally:
+        conn.close()
+
+
+def listar(limite: int = 100, offset: int = 0) -> list[dict]:
+    conn = get_connection()
+    try:
+        with conn.cursor() as cur:
+            cur.execute(
+                "SELECT ID, CRIADO_EM, USUARIO, ACAO, ENTIDADE, ENTIDADE_ID, SUCESSO, DETALHE "
+                "FROM LOG_PAINEL ORDER BY CRIADO_EM DESC, ID DESC LIMIT %s OFFSET %s",
+                (limite, offset),
+            )
+            return cur.fetchall()
+    finally:
+        conn.close()
+
+
+def contar() -> int:
+    conn = get_connection()
+    try:
+        with conn.cursor() as cur:
+            cur.execute("SELECT COUNT(*) AS total FROM LOG_PAINEL")
+            return cur.fetchone()["total"]
+    finally:
+        conn.close()
+
+
+def limpar() -> None:
+    """Apaga todo o histórico de LOG_PAINEL. Quem chama (o router) grava
+    uma entrada nova logo depois disso, registrando quem limpou — nunca
+    chamar isso sem seguir com um registrar() depois, senão o rastro da
+    própria limpeza se perde."""
+    conn = get_connection()
+    try:
+        with conn.cursor() as cur:
+            cur.execute("DELETE FROM LOG_PAINEL")
+    finally:
+        conn.close()