feat: várias melhorias e evoluções no projeto

diarios/schemas.py

@@ -0,0 +1,63 @@
+from ninja import Schema
+from typing import List, Optional
+
+
+class PaginaSchema(Schema):
+    """Schema que representa uma página de um Diário Oficial.
+
+    Attributes:
+        numero (int): Número ordinal da página no Diário (começa em 1).
+        conteudo (str): Texto extraído da página.
+    """
+
+    numero: int
+    conteudo: str
+
+
+class ResultadoSchema(Schema):
+    """Schema de resposta para um Diário Oficial em resultados de busca.
+
+    Attributes:
+        id (int): ID único do Diário no banco de dados.
+        numero (str): Número de identificação oficial do Diário (e.g., '123-A').
+        data (str): Data de publicação no formato ISO (YYYY-MM-DD).
+        link (str): URL para acessar o Diário Oficial online.
+        tipo (str): Nome do tipo de Diário (e.g., 'Municipal', 'Federal').
+        paginas (List[PaginaSchema]): Lista de páginas com conteúdo extraído.
+        score (Optional[float]): Relevância do resultado (0 a 1), se aplicável.
+    """
+
+    id: int
+    numero: str
+    data: str
+    link: str
+    tipo: str
+    paginas: List[PaginaSchema]
+    score: Optional[float] = None
+
+
+class BuscaDiariosResponseSchema(Schema):
+    """Schema de resposta para buscas paginadas em Diários Oficiais.
+
+    Attributes:
+        total (int): Total de resultados disponíveis (ignorando paginação).
+        resultados (List[ResultadoSchema]): Lista de Diários encontrados.
+        pagina (int): Número da página atual (começa em 1).
+        por_pagina (int): Quantidade de resultados por página.
+    """
+
+    total: int
+    resultados: List[ResultadoSchema]
+    pagina: int
+    por_pagina: int
+
+
+class SugestaoResponse(Schema):
+    """Schema para sugestões de correção de busca (e.g., 'Voc quis dizer...?').
+
+    Attributes:
+        sugestao (Optional[str]): Termo sugerido para refinar a busca.
+                          None se nenhuma sugestão for relevante.
+    """
+
+    sugestao: Optional[str]