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/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)