compraspublica-shared 0.9.0__py3-none-any.whl

compraspublica_shared/__init__.py

@@ -0,0 +1,37 @@
+"""compraspublica-shared — forense pública de contratações.
+
+Camada compartilhada entre o projeto de auditoria independente
+[`EnemyDisclosure`](https://github.com/renato0503/EnemyDisclosure) e o painel
+de gestão de contratações
+[`CompraPublica.AI`](https://github.com/renato0503/compraspublica.ai).
+
+Roadmap completo no `README.md` e em
+`https://github.com/renato0503/EnemyDisclosure/blob/main/sprint.md` (PARTE E).
+"""
+
+__version__ = "0.9.0"
+__author__ = "Renato Rosa"
+__email__ = "renato0503@gmail.com"
+__license__ = "MIT"
+
+from . import _config  # noqa: F401  (configures env vars on import)
+from . import brasilapi, erros, _log, sancoes, tse
+
+logger = _log.logger
+
+__all__ = [
+    "__version__",
+    "__author__",
+    "__email__",
+    "__license__",
+    "brasilapi",
+    "erros",
+    "logger",
+    "sancoes",
+    "tse",
+]
+
+
+
+
+

compraspublica_shared/_config.py

@@ -0,0 +1,144 @@
+"""Configuração central do pacote `compraspublica-shared`.
+
+Todas as variáveis são lidas de env vars (ou de defaults seguros). Não
+persistimos configuração fora do ambiente — o diretório de cache é
+determinado uma vez no import.
+
+Variáveis reconhecidas:
+- `COMPPUBL_CACHE_DIR`        — diretório raiz de cache (default `~/.compraspubl/cache`)
+- `COMPPUBL_HTTP_UA`          — User-Agent para chamadas HTTP
+- `COMPPUBL_RATE_LIMIT`       — segundos entre chamadas a APIs externas
+- `COMPPUBL_LOG_LEVEL`        — nível do logger (DEBUG/INFO/WARNING/ERROR)
+- `COMPPUBL_SANCOES_DIR`      — path do cache de CEIS/CNEP/CEPIM/Leniência
+- `COMPPUBL_BRASILAPI_CACHE`  — path do cache de BrasilAPI
+- `COMPPUBL_USE_SCRAPFLY`     — habilita fallback SaaS (precisa `SCRAPFLY_KEY`)
+- `COMPPUBL_USE_ZENROWS`      — habilita fallback SaaS alternativo
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from urllib.parse import urlparse
+
+
+def _env_or(name: str, default: str) -> str:
+    val = os.environ.get(name)
+    if val is None or val == "":
+        return default
+    return val
+
+
+def _env_float(name: str, default: float) -> float:
+    try:
+        return float(_env_or(name, str(default)))
+    except ValueError:
+        return default
+
+
+def _env_bool(name: str, default: bool) -> bool:
+    return _env_or(name, "1" if default else "0").lower() in ("1", "true", "yes", "on")
+
+
+# --- cache dir ---
+CACHE_DIR: Path = Path(
+    _env_or(
+        "COMPPUBL_CACHE_DIR",
+        str(Path.home() / ".compraspubl" / "cache"),
+    )
+).expanduser().resolve()
+CACHE_DIR.mkdir(parents=True, exist_ok=True)
+
+
+# --- HTTP ---
+USER_AGENT: str = _env_or(
+    "COMPPUBL_HTTP_UA",
+    "compraspublica-bot/1.0 (auditoria publica; contato: dev@compraspublica.ai)",
+)
+RATE_LIMIT: float = _env_float("COMPPUBL_RATE_LIMIT", 0.35)
+TIMEOUT: int = int(_env_float("COMPPUBL_TIMEOUT", 30.0))
+RETRIES: int = int(_env_float("COMPPUBL_RETRIES", 3.0))
+
+
+# --- log ---
+LOG_LEVEL: str = _env_or("COMPPUBL_LOG_LEVEL", "INFO").upper()
+
+
+# --- paths específicos ---
+SANCOES_DIR: Path = Path(
+    _env_or("COMPPUBL_SANCOES_DIR", str(CACHE_DIR / "sancoes"))
+).expanduser().resolve()
+BRASILAPI_CACHE: Path = Path(
+    _env_or("COMPPUBL_BRASILAPI_CACHE", str(CACHE_DIR / "brasilapi.json"))
+).expanduser().resolve()
+PNCP_CACHE_DIR: Path = Path(
+    _env_or("COMPPUBL_PNCP_CACHE_DIR", str(CACHE_DIR / "pncp"))
+).expanduser().resolve()
+RADARTCE_CACHE: Path = Path(
+    _env_or("COMPPUBL_RADARTCE_CACHE", str(CACHE_DIR / "radartce.db"))
+).expanduser().resolve()
+TSE_CACHE_DIR: Path = Path(
+    _env_or("COMPPUBL_TSE_CACHE_DIR", str(CACHE_DIR / "tse"))
+).expanduser().resolve()
+CNES_CACHE_DIR: Path = Path(
+    _env_or("COMPPUBL_CNES_CACHE_DIR", str(CACHE_DIR / "cnes"))
+).expanduser().resolve()
+HTTP_CACHE_DIR: Path = Path(
+    _env_or("COMPPUBL_HTTP_CACHE_DIR", str(CACHE_DIR / "http"))
+).expanduser().resolve()
+GEOCODE_CACHE: Path = Path(
+    _env_or("COMPPUBL_GEOCODE_CACHE", str(CACHE_DIR / "geocode.json"))
+).expanduser().resolve()
+AMM_CACHE_DIR: Path = Path(
+    _env_or("COMPPUBL_AMM_DIR", str(CACHE_DIR / "amm_diario"))
+).expanduser().resolve()
+PRECO_CACHE_DIR: Path = Path(
+    _env_or("COMPPUBL_PRECO_CACHE_DIR", str(CACHE_DIR / "precos"))
+).expanduser().resolve()
+
+# --- APIs externas (URLs) ---
+BRASILAPI_BASE: str = "https://brasilapi.com.br/api/cnpj/v1/"
+MINHARECEITA_BASE: str = "https://minhareceita.org/{cnpj}"
+CEIS_BASE: str = "https://portaldatransparencia.gov.br/download-de-dados"
+TSE_BASE: str = "https://dadosabertos.tse.jus.br"
+TSE_BASE_OLD: str = "https://cdn.tse.jus.br/estatistica/sead/odsele"
+PNCP_BASE: str = "https://pncp.gov.br/api"
+RADARTCE_BASE: str = "https://radardeprecos.tce.mt.gov.br"
+PORTAL_TRANSPARENCIA_BASE: str = "https://api.portaldatransparencia.gov.br/api-de-dados"
+CADPREV_BASE: str = "https://apicadprev.trabalho.gov.br"
+DATASUS_FTP: str = "ftp.datasus.gov.br"
+DATASUS_CNES_BASE: str = "/dissemin/publicos/CNES/200508_/Dados"
+
+# cria diretórios lazy na primeira escrita — ver helpers abaixo
+for _p in (SANCOES_DIR, PNCP_CACHE_DIR, CNES_CACHE_DIR, TSE_CACHE_DIR,
+          HTTP_CACHE_DIR, PRECO_CACHE_DIR, AMM_CACHE_DIR):
+    _p.mkdir(parents=True, exist_ok=True)
+
+
+# --- fallbacks SaaS ---
+USE_SCRAPFLY: bool = _env_bool("COMPPUBL_USE_SCRAPFLY", False)
+USE_ZENROWS: bool = _env_bool("COMPPUBL_USE_ZENROWS", False)
+
+
+# --- validação ---
+def _validate_url(url: str, env_name: str) -> None:
+    try:
+        u = urlparse(url)
+        if u.scheme not in ("http", "https"):
+            raise ValueError(f"scheme inválido: {u.scheme!r}")
+    except Exception as e:  # noqa: BLE001
+        from .erros import ConfiguracaoInvalida
+        raise ConfiguracaoInvalida(
+            f"{env_name}={url!r} não é uma URL válida ({e})"
+        ) from e
+
+
+for _name, _val in [
+    ("BRASILAPI_BASE", BRASILAPI_BASE),
+    ("CEIS_BASE", CEIS_BASE),
+    ("PNCP_BASE", PNCP_BASE),
+    ("RADARTCE_BASE", RADARTCE_BASE),
+    ("TSE_BASE_OLD", TSE_BASE_OLD),
+    ("PORTAL_TRANSPARENCIA_BASE", PORTAL_TRANSPARENCIA_BASE),
+    ("CADPREV_BASE", CADPREV_BASE),
+]:
+    _validate_url(_val, _name)

compraspublica_shared/_log.py

@@ -0,0 +1,39 @@
+"""Logger central do pacote `compraspublica-shared`."""
+from __future__ import annotations
+
+import logging
+import sys
+
+from . import _config
+
+_LOGGER_NAME = "compraspublica_shared"
+
+_LEVELS = {
+    "DEBUG": logging.DEBUG,
+    "INFO": logging.INFO,
+    "WARNING": logging.WARNING,
+    "WARN": logging.WARNING,
+    "ERROR": logging.ERROR,
+    "CRITICAL": logging.CRITICAL,
+}
+
+
+def _build_logger() -> logging.Logger:
+    logger = logging.getLogger(_LOGGER_NAME)
+    if logger.handlers:
+        return logger  # já configurado
+
+    logger.setLevel(_LEVELS.get(_config.LOG_LEVEL, logging.INFO))
+
+    # Handler que escreve no stderr (sem dependência de root logger)
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(logging.Formatter(
+        fmt="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    ))
+    logger.addHandler(handler)
+    logger.propagate = False  # não propaga para root
+    return logger
+
+
+logger = _build_logger()

compraspublica_shared/amm_diario/__init__.py

@@ -0,0 +1,42 @@
+"""AMM — Diário Oficial dos Municípios de Mato Grosso (amm.diariomunicipal.org).
+
+Publica um PDF por edição (todos os municípios juntos). Serve para extrair:
+- **portarias de nomeação** de cargos comissionados e contratos temporários
+  (para cruzar com o QSA dos fornecedores — servidor/comissionado que é sócio de
+  contratada = conflito de interesse);
+- aditivos contratuais, atas de registro de preços, avisos de dispensa.
+
+Não há API pública: raspa-se `/edicoes/?p=N` (paginado) e baixa-se o PDF do CDN.
+Texto via `pdfplumber` (cacheado em `.txt` ao lado do PDF — a extração de ~500
+páginas leva minutos, então é um **job em lote**, não interativo).
+Varredura por regex de CPF num raio de ~250 caracteres das palavras-gatilho.
+
+Obs.: o AMM agrega TODOS os municípios de MT numa edição. Várzea Grande também
+mantém diário próprio em `diario.varzeagrande.mt.gov.br` (fora do ar em nuvem no
+teste de 01/09) — se voltar, é a fonte mais direta para as portarias de VG.
+
+    >>> from compraspublica_shared import amm_diario as amm
+    >>> for ed in amm.editions(ate_pagina=3):
+    ...     pdf = amm.baixar(ed["url"])
+    ...     for n in amm.nomeacoes(pdf, municipio="VARZEA GRANDE"):
+    ...         ...   # {cpf, nome, tipo, trecho, edicao}
+"""
+from .amm import (
+    BASE,
+    CACHE,
+    UA,
+    editions,
+    baixar,
+    nomeacoes,
+    cruzar_com_socios,
+)
+
+__all__ = [
+    "BASE",
+    "CACHE",
+    "UA",
+    "editions",
+    "baixar",
+    "nomeacoes",
+    "cruzar_com_socios",
+]

compraspublica_shared/amm_diario/amm.py

@@ -0,0 +1,128 @@
+"""Cliente AMM — Diário Oficial dos Municípios de MT.
+
+Refatorado de `D:\\Dev\\EnemyDisclosure\\core\\fontes\\amm_diario.py`.
+Independente do pacote Enemy. Sem rede nas importações (urllib/request só é
+importado nas funções que precisam).
+
+Dependência opcional: `pdfplumber` (instale com `pip install
+compraspublica-shared[amm]`).
+"""
+from __future__ import annotations
+
+import datetime as dt
+import logging
+import re
+import urllib.request
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+BASE = "https://amm.diariomunicipal.org"
+# path local pode ser sobrescrito via env `COMPPUBL_AMM_DIR` (via _config)
+from .. import _config
+CACHE = _config.AMM_CACHE_DIR
+UA = {"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"}
+
+_GATILHOS = re.compile(
+    r"(nomear|nomea[çc][ãa]o|design(?:ar|a[çc][ãa]o)|contrata[çc][ãa]o tempor[áa]ria|"
+    r"contrato tempor[áa]rio|cargo em comiss[ãa]o|comissionad[oa]|admitir|admiss[ãa]o)",
+    re.I)
+_CPF = re.compile(r"\b(\d{3}\.?\d{3}\.?\d{3}-?\d{2})\b")
+_CNPJ = re.compile(r"\b(\d{2}\.?\d{3}\.?\d{3}/?\d{4}-?\d{2})\b")
+
+
+def _get(url: str, timeout: int = 60) -> str:
+    """GET simples via urllib (sem deps)."""
+    with urllib.request.urlopen(urllib.request.Request(url, headers=UA),
+                                 timeout=timeout) as r:
+        return r.read().decode("utf-8", "replace")
+
+
+def editions(ate_pagina: int = 1, desde: dt.date | None = None) -> list[dict]:
+    """Lista edições recentes: [{numero, data, url}]."""
+    out, vistos = [], set()
+    for p in range(1, ate_pagina + 1):
+        html = _get(f"{BASE}/edicoes/?p={p}")
+        for m in re.finditer(
+                r"(https://cdn-amm\.diariomunicipal\.org/edicoes/(\d{4})/(\d{2})/(\d{2})/"
+                r"edicao-(\d+)-[\w-]+\.pdf)", html):
+            url, y, mo, d, num = m.groups()
+            data = dt.date(int(y), int(mo), int(d))
+            if desde and data < desde:
+                return out
+            key = (num, url)
+            if key in vistos:
+                continue
+            vistos.add(key)
+            out.append({"numero": num, "data": data.isoformat(), "url": url})
+    return out
+
+
+def baixar(url: str) -> Path:
+    """Baixa o PDF (com cache local)."""
+    CACHE.mkdir(parents=True, exist_ok=True)
+    destino = CACHE / url.rsplit("/", 1)[-1]
+    if not destino.exists():
+        logger.info("AMM: baixando %s", destino.name)
+        with urllib.request.urlopen(urllib.request.Request(url, headers=UA),
+                                     timeout=180) as r:
+            destino.write_bytes(r.read())
+    return destino
+
+
+def _texto(pdf: Path) -> str:
+    """Texto do PDF, com cache em .txt ao lado (a extração é lenta)."""
+    cache = pdf.with_suffix(".txt")
+    if cache.exists():
+        return cache.read_text(encoding="utf-8")
+    try:
+        import pdfplumber  # type: ignore
+    except ImportError as e:
+        raise ImportError(
+            "amm_diario precisa de `pdfplumber`. Rode: "
+            "`pip install compraspublica-shared[amm]`"
+        ) from e
+    with pdfplumber.open(str(pdf)) as doc:
+        t = "\n\f\n".join((pg.extract_text() or "") for pg in doc.pages)
+    cache.write_text(t, encoding="utf-8")
+    return t
+
+
+def nomeacoes(pdf: Path, municipio: str | None = None) -> list[dict]:
+    """Trechos com palavra-gatilho de nomeação/contratação + um CPF por perto."""
+    txt = _texto(pdf)
+    if municipio:
+        # restringe às páginas/blocos que citam o município
+        mun = municipio.upper()
+        blocos = [b for b in re.split(r"\f|\n{2,}", txt) if mun in b.upper()]
+        txt = "\n\n".join(blocos)
+    achados = []
+    for g in _GATILHOS.finditer(txt):
+        janela = txt[max(0, g.start() - 250): g.end() + 250]
+        for c in _CPF.finditer(janela):
+            achados.append({
+                "cpf": re.sub(r"\D", "", c.group(1)),
+                "tipo": g.group(1).lower(),
+                "trecho": re.sub(r"\s+", " ", janela).strip()[:300],
+            })
+    # dedup por (cpf, tipo)
+    vistos, uniq = set(), []
+    for a in achados:
+        k = (a["cpf"], a["tipo"])
+        if k not in vistos:
+            vistos.add(k)
+            uniq.append(a)
+    return uniq
+
+
+def cruzar_com_socios(nomeados: list[dict], socios_por_cpf: dict) -> list[dict]:
+    """Cruza nomeados (com CPF) × QSA das contratadas.
+
+    `socios_por_cpf`: dict cpf → [(cnpj, empresa, nome), ...].
+    """
+    hits = []
+    for n in nomeados:
+        for cnpj, empresa, nome in socios_por_cpf.get(n["cpf"], []):
+            hits.append({**n, "cnpj_empresa": cnpj,
+                         "empresa": empresa, "socio": nome})
+    return hits

compraspublica_shared/analise_risco/__init__.py

@@ -0,0 +1,60 @@
+"""Motor de análise de risco de fornecedor — B-suite empacotada.
+
+Empacota os 9 módulos B forenses relevantes para o CompraPublica.AI F61
+(due diligence do vencedor) e para auditoria:
+
+    B2  fracionamento de dispensa
+    B3  direcionamento de edital
+    B5  empresas de fachada (score)
+    B6  nepotismo / servidor-sócio
+    B9  aditivos contratuais >25%
+    B11 restos a pagar como caixa 2
+    B17 Lei de Benford
+    B18 ordem cronológica de pagamento
+    B19 pagamentos duplicados
+
+`run_b_suite(cnpj, valor_adjudicado, objeto, uf, data_disputa)` combina os
+módulos + regras (`regras.py`) + fontes (sancoes, brasilapi, cnes, tse) num
+`score_fornecedor` consolidado (0-100).
+
+Uso:
+    >>> from compraspublica_shared import analise_risco
+    >>> r = analise_risco.run_b_suite(
+    ...     cnpj="27814736000150", valor_adjudicado=5_000_000,
+    ...     objeto="Limpeza urbana", uf="MT")
+    >>> r.score, r.categoria
+    (87, 'alto')
+"""
+from . import _util, _canon, benford, aditivos, ordem_pagamento
+from . import pagamentos_duplicados, restos_a_pagar, direcionamento
+from . import fracionamento, laranjas, nepotismo, regras, grafo, models
+from .score import (
+    FlagRisco as _FlagRiscoDC,
+    RiscoFornecedor as _RiscoFornecedorDC,
+    run_b_suite,
+    score_fornecedor,
+)
+
+# re-exporta dataclasses (compat) + Pydantic models
+from .score import FlagRisco, RiscoFornecedor
+from .models import (
+    RequestAnalise,
+    PrecoReferencia,
+    EnderecoGeocodificado,
+    SnapshotOrgao,
+)
+
+__all__ = [
+    "_util", "_canon",
+    "benford", "aditivos", "ordem_pagamento",
+    "pagamentos_duplicados", "restos_a_pagar", "direcionamento",
+    "fracionamento", "laranjas", "nepotismo", "regras", "grafo", "models",
+    "FlagRisco",
+    "RiscoFornecedor",
+    "RequestAnalise",
+    "PrecoReferencia",
+    "EnderecoGeocodificado",
+    "SnapshotOrgao",
+    "run_b_suite",
+    "score_fornecedor",
+]

compraspublica_shared/analise_risco/_canon.py

@@ -0,0 +1,168 @@
+# core/analises/_canon.py
+"""Camada de normalização: schema bruto de cada portal → modelo canônico.
+
+Cada portal (Fiorilli, Elotech, GeneXus-Cuiabá, PNCP...) nomeia os campos de
+um jeito. Aqui um registro bruto vira um dict com chaves canônicas
+(ver PARTE 0 do sprint.md). Os módulos de análise trabalham só no canônico.
+
+    e = canon("empenho", registro_bruto)
+    e["valor_empenhado"], e["credor_doc"], e["data"]
+"""
+from __future__ import annotations
+
+from datetime import datetime
+from typing import List, Optional
+
+from ._util import data as _data
+from ._util import doc_limpo, norm, num
+
+# canônico → lista de nomes possíveis no bruto (1º que existir vence)
+MAPAS = {
+    "empenho": {
+        "numero": ("CODIGO", "EmpenhoNumero", "Empenho", "numeroEmpenho", "numero", "empenho",
+                   "numeroExercicioEmpenho", "numeroAno", "Empenho Numero", "Número/Ano"),
+        "data": ("DATAE", "EmpenhoData", "dataEmpenho", "data", "Data"),
+        "credor_doc": ("CPFFORMATADO", "EmpenhoCredorDoc", "cnpjCpf", "cpfCnpj",
+                       "niFornecedor", "documentoFornecedor", "CPFCNPJ",
+                       "cpfcnpjFavorecido", "cpfCnpjCredor", "Empenho Credor CPFCNPJ"),
+        "credor_nome": ("NOMEFOR", "EmpenhoCredorNome", "EmpenhoCredorRazao",
+                        "NOMEEMPRESA", "nomeFornecedor", "fornecedor", "credor",
+                        "nomeRazaoSocialFornecedor", "nomeRazaoSocialCredor", "nomeFavorecido",
+                        "razao_social", "Empenho Credor Nome"),
+        "valor_empenhado": ("EMPENHADO", "EmpenhoValor", "valor_empenhado",
+                            "valorEmpenhado", "valor", "valorEmpenho",
+                            "valorTotalEmpenhado", "valorEmpenho", "Valor"),
+        "valor_liquidado": ("LIQUIDADO", "EmpenhoValorLiq", "EmpenhoLiquidacaoValorLiq",
+                            "valor_liquidado", "valorLiquidado", "valorTotalLiquidado",
+                            "Valor Liquidado"),
+        "valor_pago": ("PAGO", "EmpenhoPagamentoValorLiq", "valor_pago", "valorPago",
+                       "valorTotalPago", "valorPagoSemAnulacao", "Valor Pago"),
+        "elemento": ("ELEMENTO", "EmpenhoElementoNome", "elementoDespesa",
+                     "descricaoElemento", "NATUREZA", "dotacao",
+                     "dota_o_fonte_de_recurso"),
+        "funcao": ("FUNCAONOME", "EmpenhoFuncaoNome", "FUNCAO", "funcao",
+                   "Empenho Orgao Nome"),
+        # ATENÇÃO: modalidade de LICITAÇÃO (não a modalidade de aplicação da
+        # despesa — em Cuiabá `EmpenhoModalidadeNome`="APLICACOES DIRETAS" é
+        # categoria contábil, não licitatória).
+        "modalidade": ("MODALIDADE", "EmpenhoLicModalidadeNome", "EmpenhoModLicitacao",
+                       "modalidadeLicitacao", "modalidade", "MODALI", "modalidadeNome"),
+        "processo": ("PROC", "EmpenhoProcesso", "EmpenhoNumeroProcessoCompra",
+                     "processo", "PROCLIC"),
+        "licitacao": ("NUMLICIT", "EmpenhoContratoNumero", "LICIT", "licitacao",
+                      "numeroLicitacao"),
+        "descricao": ("descricao_item", "_item_descricao", "EmpenhoDsc",
+                      "DESCLICIT_DETALHESEMPENHO", "descricao", "objeto", "historico", "motivo",
+                      "Histórico"),
+        "valor_unitario": ("_item_valor_unitario", "valorUnitario", "valorUnitarioEstimado"),
+    },
+    "contrato": {
+        "numero": ("CONTRATONUM", "ContratoNumero", "Contrato", "numeroContrato",
+                   "numero", "contrato", "CODIGO"),
+        "fornecedor_doc": ("CPFCNPJ", "ContratoFornecedorDoc", "cnpjCpf",
+                           "niFornecedor", "documentoFornecedor"),
+        "fornecedor_nome": ("FORNECEDOR", "ContratoFornecedorNome", "nome",
+                            "nomeRazaoSocialFornecedor", "fornecedor_nome", "razaoSocial"),
+        "objeto": ("OBJETO", "OBJETO_COMPLETO", "ContratoDsc", "objeto", "objetoContrato"),
+        "valor_inicial": ("VALCON", "ContratoValor", "valorContratado", "valorInicial", "valor"),
+        "valor_atual": ("ContratoValorAtual", "valorGlobal", "valorAtualizado",
+                        "valor_atual", "valorAcumulado"),
+        "valor_aditivos": ("valorAditivo", "valorAditivos"),
+        "assinatura": ("DTASSI", "ContratoDataIni", "dataAssinatura", "assinatura"),
+        "vigencia_inicio": ("VIGENI", "inicioVigencia", "dataVigenciaInicio", "vigencia_inicio"),
+        "vigencia_fim": ("VIGENF", "terminoVigencia", "dataVigenciaFim", "vigencia_fim"),
+        "modalidade": ("MODALI", "descricaoTipoLicitacao", "modalidade"),
+        "aditado_flag": ("ADITADO", "aditado"),
+    },
+    "servidor": {
+        "nome": ("NOME", "nome", "nomeServidor", "nomeRazaoSocial", "FolhaNome"),
+        "cpf": ("CPF", "cpf", "documento", "cpfFormatado", "FolhaCPF"),
+        "cargo": ("CARGO", "cargo", "descricaoCargo", "DESCCARGO", "FolhaCargoPriNome",
+                  "FolhaCargo"),
+        "lotacao": ("LOTACAO", "descricaoLotacao", "localTrabalho", "lotacao", "SETOR",
+                    "estrutAdministrativa", "secretaria", "departamento",
+                    "FolhaLotacaoNome", "FolhaOrgaoNome"),
+        "vinculo": ("VINCULO", "vinculo", "formaInvestidura", "TIPOVINCULO", "situacao",
+                    "formaIngressoFunc", "tipoSituacaoVincTrab", "FolhaSituacaoFuncDsc",
+                    "FolhaTipoIngressoDsc"),
+        "admissao": ("ADMISSAO", "dataAdmissao", "DATA_ADMISSAO", "dataAdmissaoAtivo"),
+        "demissao": ("DESLIGAMENTO", "dataDemissao", "dataFimContrato", "DATA_DESLIGAMENTO",
+                     "dataExoneracao", "FolhaExoneracaoData"),
+        "remuneracao": ("PROVENTOS", "remuneracao", "salarioBase", "REMUNERACAO",
+                        "salario_base", "salarioBruto", "FolhaVlrBruta"),
+        "descontos": ("DESCONTOS", "descontos", "FolhaVlrDescTotal"),
+        "competencia": ("FolhaCompetencia", "competencia", "COMPETENCIA"),
+        "folha_tipo": ("FolhaTipoDsc",),
+    },
+    "pagamento": {
+        "credor": ("NOMEFOR", "credor", "fornecedor", "nomeCredor", "PagamentoEmpCredorNome"),
+        "credor_doc": ("CPFCNPJ", "cnpjCpf", "documentoCredor", "PagamentoEmpCredorCPFCNPJ"),
+        "data_liquidacao": ("DATA_LIQUIDACAO", "dataLiquidacao", "data", "LiquidacaoData"),
+        "data_pagamento": ("DATA_PAGAMENTO", "dataPagamento", "PagamentoData"),
+        "data_vencimento": ("DATA_VENCIMENTO", "dataVencimento"),
+        "valor": ("VALOR", "valor", "valorPago", "PagamentoValor"),
+        "fonte": ("FONTE", "fonteRecurso", "descFonteRecurso"),
+        "empenho": ("EMPENHO", "empenho", "numeroEmpenho", "EmpenhoNumero"),
+    },
+    "licitacao": {
+        "numero": ("NLICITACAO", "LicitacaoNumero", "Licitacao", "NUMLIC",
+                   "numeroLicitacao", "numero", "LICITACAO", "numeroAnoLicitacao"),
+        "ano": ("ANO", "LicitacaoAno", "exercicio", "anoLicitacao"),
+        "modalidade": ("DISCR", "LicitacaoModalidadeNome", "modalidadeNome",
+                       "descricaoTipoLicitacao", "modalidade", "ESPECIETCE",
+                       "descricaoModalidade"),
+        "objeto": ("DISCR10", "LicitacaoObjeto", "objeto", "objetoLicitacao", "OBJETO",
+                   "descricaoObjeto"),
+        "data_publicacao": ("DTENV", "LicitacaoData", "dataPublicacao", "DATAPUBLICACAO"),
+        "data_abertura": ("DATAE", "LicitacaoDataSessao", "dataAbertura",
+                          "DTPROPOSTAINI", "dataSessao"),
+        "data_encerramento": ("DTENC", "DTPROPOSTAFIM", "dataEncerramento"),
+        "valor_estimado": ("VALOR", "valorEstimado", "valor_estimado"),
+        "valor_homologado": ("VALOR1", "valorHomologado", "valor_homologado"),
+        "situacao": ("SITUACAO", "LicitacaoSituacao", "situacao", "descricaoSituacao"),
+        "n_participantes": ("PARTICIPANTES", "numeroParticipantes", "qtdParticipantes"),
+        "vencedor_doc": ("CPFCNPJ", "cnpjVencedor", "documentoVencedor"),
+        "registro_preco": ("REGISTROPRECO", "REGISTRO_PRECO", "srp", "registroPreco",
+                           "flGeraRegistroPrecosExibicao"),
+    },
+}
+
+_DATAS = {"data", "assinatura", "vigencia_inicio", "vigencia_fim", "admissao",
+          "demissao", "data_liquidacao", "data_pagamento", "data_vencimento",
+          "data_publicacao", "data_abertura", "data_encerramento"}
+_VALORES = {"valor_empenhado", "valor_liquidado", "valor_pago", "valor_unitario",
+            "valor_inicial", "valor_atual", "valor_aditivos", "remuneracao",
+            "descontos", "valor", "valor_estimado", "valor_homologado"}
+_DOCS = {"credor_doc", "fornecedor_doc", "cpf", "vencedor_doc"}
+
+
+def _primeiro(rec: dict, nomes) -> Optional[object]:
+    for n in nomes:
+        if n in rec and rec[n] not in (None, "", "null"):
+            return rec[n]
+        # busca case-insensitive
+        for k in rec:
+            if k.lower() == n.lower() and rec[k] not in (None, "", "null"):
+                return rec[k]
+    return None
+
+
+def canon(tipo: str, rec: dict) -> dict:
+    m = MAPAS[tipo]
+    out = {"_raw": rec}
+    for campo, nomes in m.items():
+        v = _primeiro(rec, nomes)
+        if campo in _DATAS:
+            out[campo] = _data(v)
+        elif campo in _VALORES:
+            out[campo] = num(v)
+        elif campo in _DOCS:
+            out[campo] = doc_limpo(v)
+        else:
+            out[campo] = v
+    return out
+
+
+def canon_lista(tipo: str, regs: List[dict]) -> List[dict]:
+    return [canon(tipo, r) for r in (regs or [])]
+

compraspublica_shared/analise_risco/_util.py

@@ -0,0 +1,52 @@
+"""Helpers comuns às análises B (refatorados de `core/analises/_util.py`)."""
+from __future__ import annotations
+
+import re
+import unicodedata
+from datetime import datetime
+from typing import Optional
+
+
+def num(v) -> float:
+    """'1.234,56' | '1234.56' | 1234 → float."""
+    if v is None or v == "":
+        return 0.0
+    if isinstance(v, (int, float)):
+        return float(v)
+    s = str(v).strip().replace("R$", "").replace(" ", "")
+    if "," in s and "." in s:
+        s = s.replace(".", "").replace(",", ".")
+    elif "," in s:
+        s = s.replace(",", ".")
+    try:
+        return float(re.sub(r"[^\d.\-]", "", s) or 0)
+    except ValueError:
+        return 0.0
+
+
+def data(v) -> Optional[datetime]:
+    if not v:
+        return None
+    s = str(v)[:10]
+    for f in ("%Y-%m-%d", "%d/%m/%Y", "%Y%m%d"):
+        try:
+            return datetime.strptime(s, f)
+        except ValueError:
+            pass
+    return None
+
+
+def norm(s: str) -> str:
+    s = unicodedata.normalize("NFKD", str(s or "")).encode("ascii", "ignore").decode()
+    return re.sub(r"\s+", " ", s).strip().upper()
+
+
+def doc_limpo(v) -> str:
+    return re.sub(r"\D", "", str(v or ""))
+
+
+def sobrenomes(nome: str, min_len: int = 4) -> set:
+    """Sobrenomes 'úteis' (ignora conectivos e nomes curtos)."""
+    stop = {"DE", "DA", "DO", "DActionResult", "DOS", "DAS", "E"}
+    toks = norm(nome).split()
+    return {t for t in toks[1:] if len(t) >= min_len and t not in stop}