Refatoracao de qualidade de codigo

- Mover logica de routes.py para RankingMapper na camada de aplicacao
- Consolidar funcoes mesclar_periodos e anos_completos_periodos em periodo.py
- Extrair RankingCache para modulo separado em infrastructure/cache
- Substituir todos os print() por logging adequado
- Corrigir exception handlers genericos para tipos especificos
- Remover classe Atuacao e atributo atuacoes_raw nao utilizados
- Documentar status dos scripts utilitarios

backend/src/domain/services/calculador_pontuacao.py

@@ -16,36 +16,11 @@ from ..entities.consultor import (
 )
 from ..value_objects.pontuacao import PontuacaoAtuacao, PontuacaoBloco, PontuacaoCompleta
 from ..value_objects.criterios_pontuacao import CRITERIOS, get_criterio, Bloco
-from ..value_objects.periodo import Periodo
+from ..value_objects.periodo import Periodo, mesclar_periodos, anos_completos_periodos
 
 
 class CalculadorPontuacao:
 
-    @staticmethod
-    def _mesclar_periodos(periodos: List[Periodo]) -> List[Periodo]:
-        if not periodos:
-            return []
-        periodos_ordenados = sorted(periodos, key=lambda p: p.inicio if p.inicio else datetime.min)
-        mesclados: List[Periodo] = []
-        for p in periodos_ordenados:
-            if not mesclados:
-                mesclados.append(p)
-                continue
-            ultimo = mesclados[-1]
-            ultimo_fim = ultimo.fim or datetime.now()
-            atual_fim = p.fim or datetime.now()
-            if p.inicio and p.inicio <= ultimo_fim:
-                novo_fim = max(ultimo_fim, atual_fim)
-                mesclados[-1] = Periodo(inicio=ultimo.inicio, fim=novo_fim if not ultimo.ativo else None)
-            else:
-                mesclados.append(p)
-        return mesclados
-
-    @staticmethod
-    def _anos_completos_periodos(periodos: List[Periodo]) -> int:
-        ref = datetime.now()
-        return sum(p.anos_completos(ref) for p in periodos)
-
     @staticmethod
     def calcular_bloco_a(coordenacoes: List[CoordenacaoCapes]) -> PontuacaoBloco:
         if not coordenacoes:
@@ -68,9 +43,9 @@ class CalculadorPontuacao:
 
             coords = coord_por_tipo[tipo]
             periodos = [c.periodo for c in coords]
-            mesclados = CalculadorPontuacao._mesclar_periodos(periodos)
+            mesclados = mesclar_periodos(periodos)
 
-            anos_total = CalculadorPontuacao._anos_completos_periodos(mesclados)
+            anos_total = anos_completos_periodos(mesclados)
             ativo = any(c.periodo.ativo for c in coords)
             tem_retorno = len(mesclados) > 1
 
@@ -109,8 +84,8 @@ class CalculadorPontuacao:
         tempo = 0
         if criterio.pontua_tempo:
             periodos = consultoria.periodos if consultoria.periodos else [consultoria.periodo]
-            mesclados = CalculadorPontuacao._mesclar_periodos(periodos)
-            anos_total = CalculadorPontuacao._anos_completos_periodos(mesclados)
+            mesclados = mesclar_periodos(periodos)
+            anos_total = anos_completos_periodos(mesclados)
             tempo = min(anos_total * criterio.multiplicador_tempo, criterio.teto_tempo)
 
         bonus = 0