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/entities/consultor.py

@@ -1,31 +1,11 @@
 from dataclasses import dataclass, field
-from typing import List, Optional, Dict, Any
+from typing import List, Optional
 from datetime import datetime
 
 from ..value_objects.periodo import Periodo
 from ..value_objects.pontuacao import PontuacaoCompleta
 
 
-@dataclass
-class Atuacao:
-    codigo: str
-    tipo_es: str
-    inicio: Optional[datetime] = None
-    fim: Optional[datetime] = None
-    dados: Dict[str, Any] = field(default_factory=dict)
-
-    @property
-    def ativo(self) -> bool:
-        return self.fim is None
-
-    @property
-    def anos_completos(self) -> int:
-        if not self.inicio:
-            return 0
-        fim = self.fim or datetime.now()
-        return int((fim - self.inicio).days // 365)
-
-
 @dataclass
 class CoordenacaoCapes:
     codigo: str
@@ -119,7 +99,6 @@ class Consultor:
     orientacoes: List[Orientacao] = field(default_factory=list)
     membros_banca: List[MembroBanca] = field(default_factory=list)
     pontuacao: Optional[PontuacaoCompleta] = None
-    atuacoes_raw: List[Atuacao] = field(default_factory=list)
 
     @property
     def anos_atuacao(self) -> float:

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

backend/src/domain/value_objects/periodo.py

@@ -1,6 +1,6 @@
 from dataclasses import dataclass
 from datetime import datetime
-from typing import Optional
+from typing import List, Optional
 
 
 @dataclass(frozen=True)
@@ -29,6 +29,35 @@ class Periodo:
         return int((fim - self.inicio).days // 365)
 
     def __post_init__(self) -> None:
-        # Se houver fim anterior ao início, o período é tratado como aberto.
         if self.fim and self.fim < self.inicio:
             object.__setattr__(self, "fim", None)
+
+
+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
+
+
+def anos_completos_periodos(periodos: List[Periodo], data_ref: Optional[datetime] = None) -> int:
+    ref = data_ref or datetime.now()
+    return sum(p.anos_completos(ref) for p in periodos)