feat: add opportunity collector contracts

app/collectors/base.py

@@ -0,0 +1,19 @@
+from abc import ABC, abstractmethod
+
+from app.collectors.types import CollectedOpportunity
+
+
+class BaseOpportunityCollector(ABC):
+    source_slug: str
+
+    @abstractmethod
+    async def collect(
+        self,
+    ) -> list[CollectedOpportunity]:
+        """
+        Collecte les nouvelles opportunités d'une source.
+
+        Le collecteur ne doit pas écrire dans la base de données.
+        Il retourne uniquement des données normalisées.
+        """
+        raise NotImplementedError

app/collectors/types.py

@@ -0,0 +1,34 @@
+from dataclasses import dataclass, field
+from datetime import date
+from typing import Any
+
+
+@dataclass(slots=True)
+class CollectedOpportunity:
+    source_slug: str
+    title: str
+    official_url: str
+    raw_content: str
+
+    summary: str | None = None
+    organization_name: str | None = None
+    category: str | None = None
+    country_code: str | None = None
+    location: str | None = None
+    language: str | None = None
+
+    publication_date: date | None = None
+    deadline: date | None = None
+
+    application_url: str | None = None
+    image_url: str | None = None
+
+    target_countries: list[str] = field(
+        default_factory=list
+    )
+    study_levels: list[str] = field(
+        default_factory=list
+    )
+    eligibility: dict[str, Any] = field(
+        default_factory=dict
+    )