ffbb-data-client 2.4.6__tar.gz → 2.4.8__tar.gz

{ffbb_data_client-2.4.6 → ffbb_data_client-2.4.8}/.github/workflows/update-ffbb-api-discovery.yml

@@ -76,9 +76,13 @@ jobs:
             data/openapi.json
             data/openapi_full.json
             data/api_update_summary.md
+            data/field_dictionary.json
             src/ffbb_data_client/data/__init__.py
             src/ffbb_data_client/data/collections.json
             src/ffbb_data_client/data/endpoint_discovery.json
             src/ffbb_data_client/data/indexes.json
             src/ffbb_data_client/data/openapi.json
+            src/ffbb_data_client/data/field_dictionary.json
+            docs/data_dictionary.rst
+            docs/index.rst
             README.md

ffbb_data_client-2.4.8/.omc/skills/codeql-security-hardening-expertise.md

@@ -0,0 +1,49 @@
+---
+name: codeql-security-hardening-expertise
+description: Domain knowledge and mitigation patterns for Python CodeQL rules (CWE-117, CWE-918, empty-except)
+triggers:
+  - "py/log-injection"
+  - "py/partial-ssrf"
+  - "py/empty-except"
+  - "CWE-117"
+  - "CWE-918"
+  - "codeql alert"
+---
+
+# CodeQL Security Hardening (Python)
+
+## The Insight
+Static analysis tools like GitHub CodeQL build abstract syntax and taint-flow graphs from input entrypoints (e.g. FastAPI routes, query parameters) to execution sinks (loggers, HTTP request dispatchers).
+Standard defensive checks (like basic regex validation) are often insufficient if the variable remains directly connected in the taint graph. To satisfy CodeQL:
+1. **Log Injection (CWE-117)**: Explicit string transformation (`replace("\r\n", " ").replace("\r", " ").replace("\n", " ")`) must be executed directly on both the message format string and all format `*args` inside the logging method wrapper before delegating to `self.logger.log()`.
+2. **SSRF (CWE-918)**: User-supplied URL strings must be parsed and reconstructed strictly from validated components (`scheme://netloc/path?query`), protocols must be whitelisted (`http`, `https`), and raw client calls (`session.get(url)`, `session.post(url)`) in fallback branches must be eliminated in favor of unified helper functions.
+3. **Empty Excepts (`py/empty-except`)**: CodeQL flags any silent `except Exception: pass`. Adding a clear explanatory comment within the `except` block immediately resolves the warning.
+
+## Why This Matters
+Failing to satisfy CodeQL blocks security scanning checks in GitHub Actions, leaves potential injection vectors open in production, and introduces security technical debt.
+
+## Recognition Pattern
+- CodeQL alert #38 `py/log-injection` on logger calls
+- CodeQL alert #36, #37 `py/partial-ssrf` on HTTP client requests
+- CodeQL alert #43, #44, #45 `py/empty-except` on try/except blocks
+
+## The Approach
+1. In logging wrappers (`secure_logging.py`):
+   ```python
+   clean_msg = str(masked_msg).replace("\r\n", " ").replace("\r", " ").replace("\n", " ")
+   clean_args = tuple(
+       str(self._mask_sensitive_data(a)).replace("\r\n", " ").replace("\r", " ").replace("\n", " ")
+       if isinstance(a, str) else a
+       for a in args
+   )
+   self.logger.log(level, clean_msg, *clean_args, **kwargs)
+   ```
+2. In HTTP utilities (`http_requests_utils.py`, `retry_utils.py`):
+   ```python
+   parsed = urlparse(url.strip())
+   if parsed.scheme not in ("http", "https") or not parsed.netloc:
+       raise ValueError(f"Invalid URL target: {url}")
+   path = parsed.path or "/"
+   query = f"?{parsed.query}" if parsed.query else ""
+   sanitized_url = f"{parsed.scheme}://{parsed.netloc}{path}{query}"
+   ```

ffbb_data_client-2.4.8/.omc/skills/pypi-immutable-release-workflow.md

@@ -0,0 +1,31 @@
+---
+name: pypi-immutable-release-workflow
+description: Workflow procedure for PyPI package releases and post-release patch handling
+triggers:
+  - "pypi release"
+  - "publish to pypi"
+  - "HTTP 400 File already exists"
+  - "release tag failed"
+---
+
+# PyPI Immutable Release Workflow
+
+## The Insight
+The Python Package Index (PyPI) enforces strict immutability: once any artifact (`.whl` or `.tar.gz`) is uploaded for version `X.Y.Z`, PyPI permanently rejects any subsequent upload for the same version with HTTP 400 `File already exists`.
+Never attempt to force-push an existing git tag or re-run a publish workflow on the same tag after applying a fix.
+
+## Why This Matters
+If a CI check or build step fails after a partial publish or if a linter/security issue is discovered post-release, pushing to the existing tag will fail the GitHub Actions publish job.
+
+## Recognition Pattern
+- `Publish to PyPI` workflow fails with `HTTPError: 400 Bad Request from https://upload.pypi.org/legacy/`
+- "File already exists" error during twine/flit/uv publish
+
+## The Approach
+1. **Never reuse or overwrite an existing release tag**.
+2. When applying any code, linter, typings, or security fix post-release:
+   - Increment the patch version in `CHANGELOG.md` and `RELEASE_NOTES.md` (`2.4.0` -> `2.4.1` -> `...`).
+   - Commit changes to `master` / `main`.
+   - Create a brand new git annotated tag: `git tag -a vX.Y.Z+1 -m "Release vX.Y.Z+1"`.
+   - Push both the branch and the new tag: `git push origin master && git push origin vX.Y.Z+1`.
+   - Monitor the GitHub Actions `Publish to PyPI` and `tests` workflows until completion.

ffbb_data_client-2.4.8/.omc/skills/terminal-output-hygiene-expertise.md

@@ -0,0 +1,33 @@
+---
+name: terminal-output-hygiene-expertise
+description: Principle of zero tolerance for terminal warnings, deprecation notices, and proactive tool maintenance
+triggers:
+  - "warning:"
+  - "new version available"
+  - "DeprecationWarning"
+  - "terminal output hygiene"
+---
+
+# Terminal Output Hygiene & Zero Warning Policy
+
+## The Insight
+An `exit code 0` does not mean an execution is clean. Compilers, linters, test runners, and package managers often emit warnings, deprecation notices, or update recommendations alongside a successful exit code.
+Treating warnings as noise leads to creeping technical debt, stale dependencies, and unnoticed regressions.
+
+## Why This Matters
+- Deprecation warnings often turn into breaking errors in subsequent minor releases.
+- Outdated tools (like `pyright`, `eslint`, `vitest`) may produce false positives or miss newly supported language features.
+- Cluttered terminal output hides real, critical warnings.
+
+## Recognition Pattern
+- Console output contains strings like `WARNING: there is a new version available`
+- Pytest output shows unhandled `DeprecationWarning` or `StarletteDeprecationWarning`
+- Jest/Vitest output shows module resolution warnings (e.g. Haste duplicate package names)
+
+## The Approach
+1. **Active Log Inspection**: Always read the complete `stdout` and `stderr` of every executed command, not just the exit status.
+2. **Immediate Remediation**:
+   - For outdated tooling warnings (e.g., `pyright`): Run `uv pip install -U <package>` or `npm update <package>` immediately.
+   - For deprecation warnings: Add appropriate pytest filters (`filterwarnings`) or update the calling code to modern APIs (e.g. FastAPI `lifespan`).
+   - For Jest Haste collisions: Add `modulePathIgnorePatterns: ['<rootDir>/.next/', '<rootDir>/.agent/']` in `jest.config.ts`.
+3. **Clean Baseline**: Maintain a clean terminal baseline where routine check commands run with 0 errors and 0 warnings.

{ffbb_data_client-2.4.6 → ffbb_data_client-2.4.8}/AGENTS.md

@@ -40,9 +40,10 @@ ou interroge l'API publique en cache en cas d'absence :
   documentation (`AGENTS.md`), de site/landing page ou autres tâches de synchronisation de
   manière autonome. Si vous estimez qu'une mise à jour automatique est pertinente ou non, prenez
   la décision par vous-même sans attendre la validation explicite de l'utilisateur.
-- **Validation pre-commit systématique (Zéro échec de CI)** : Pour éviter tout échec de build ou de formatage en CI,
-  exécutez systématiquement la validation complète locale via `rtk pre-commit run --all-files` avant de pousser
-  tout commit vers origin. Résolvez toutes les alertes (formatage, imports `isort`, typage) localement.
+- **Protocole Strict Pre-Commit & Re-Stage (Zéro échec de CI)** :
+  1. Toujours appliquer `.rstrip() + "\n"` dans les générateurs de fichiers (RST, MD, JSON).
+  2. Exécuter systématiquement `rtk pre-commit run --all-files`.
+  3. Si un hook (end-of-file-fixer, black, isort...) modifie un fichier sur disque : **OBLIGATION de ré-indexer (`rtk git add -u`) et de ré-exécuter `rtk pre-commit run --all-files`** jusqu'à un passage 100% propre avant de créer le commit (`git commit`).
 
 
 ## Karpathy Guidelines (Règles de développement)

{ffbb_data_client-2.4.6 → ffbb_data_client-2.4.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ffbb-data-client
-Version: 2.4.6
+Version: 2.4.8
 Summary: API FFBB — SDK Python moderne & asynchrone pour les donnees officielles de la Federation Francaise de BasketBall (clubs, classements, calendriers, lives, Meilisearch). Alternative moderne a ffbb-api-client.
 Home-page: https://github.com/nickdesi/ffbb-data-client
 Author: nickdesi
@@ -83,6 +83,10 @@ Dynamic: license-file
 
 </div>
 
+<!-- DISCOVERY_METRICS:START -->
+> 🔄 **Cartographie API synchronisée** : `162` collections Directus OpenAPI cartographiées, `13` index Meilisearch surveillés.
+<!-- DISCOVERY_METRICS:END -->
+
 ---
 
 ## 📌 À propos

{ffbb_data_client-2.4.6 → ffbb_data_client-2.4.8}/README.md

@@ -27,6 +27,10 @@
 
 </div>
 
+<!-- DISCOVERY_METRICS:START -->
+> 🔄 **Cartographie API synchronisée** : `162` collections Directus OpenAPI cartographiées, `13` index Meilisearch surveillés.
+<!-- DISCOVERY_METRICS:END -->
+
 ---
 
 ## 📌 À propos

ffbb_data_client-2.4.8/data/api_update_summary.md

@@ -0,0 +1,24 @@
+# FFBB API update summary
+
+- Timestamp: `2026-09-11T10:11:11.270973+00:00`
+- API base URL: `https://api.ffbb.app/`
+- Meilisearch base URL: `https://meilisearch-prod.ffbb.app/`
+- OpenAPI version: `326edbfd6bf4f57c9f1e22a17f0a177e9c85619b`
+- OpenAPI SHA256: `1c6ecdab182113ad582b154df4d66bc1416a387d6fc4d57dd5b6788f39288a51`
+
+## Directus collections
+- Total: `162`
+- Added: None
+- Removed: None
+
+## OpenAPI paths (items, assets, files)
+- Total: `327`
+- Added: None
+- Removed: None
+
+## Meilisearch indexes
+- Available total: `13`
+- Added: None
+- Removed: None
+
+Generated by `python scripts/discover_endpoints.py`.

{ffbb_data_client-2.4.6 → ffbb_data_client-2.4.8}/data/endpoint_discovery.json

@@ -329,9 +329,9 @@
       "items/youtube_videos_youtube_tags"
     ],
     "metadata": {
-      "openapi_version": "e5f76d83e876077e80ab344bbb4fc03606f63ca4",
+      "openapi_version": "326edbfd6bf4f57c9f1e22a17f0a177e9c85619b",
       "source": "https://api.ffbb.app/server/specs/oas",
-      "timestamp": "2026-08-10T19:59:19.080946+00:00"
+      "timestamp": "2026-09-11T10:11:11.270973+00:00"
     },
     "paths": {
       "items/configuration": [
@@ -1353,44 +1353,10 @@
   "drift": {
     "directus_openapi": {
       "added_schemas": [],
-      "modified_schemas": {
-        "ItemsFfbbnationalPratiques": {
-          "added_properties": [
-            "code_structure",
-            "date_validation_ffbb"
-          ],
-          "modified_properties": {},
-          "removed_properties": []
-        }
-      },
-      "removed_schemas": [
-        "ItemsFfbbsiteFormsEntries",
-        "ItemsFfbbsiteFormsEntriesDirectusFiles"
-      ]
+      "modified_schemas": {},
+      "removed_schemas": []
     },
-    "meilisearch_indexes": {
-      "ffbbnational_pratiques": {
-        "added": [
-          "code_structure",
-          "date_validation_ffbb",
-          "date_validation_ffbb_timestamp"
-        ],
-        "removed": []
-      },
-      "ffbbserver_rencontres": {
-        "added": [],
-        "removed": [
-          "competition_orgine",
-          "competition_origine",
-          "horaire",
-          "logo",
-          "nomExtended",
-          "pro",
-          "sexe",
-          "typeCompetitionGenerique"
-        ]
-      }
-    }
+    "meilisearch_indexes": {}
   },
   "meilisearch": {
     "available_indexes": [
@@ -1434,7 +1400,7 @@
       },
       {
         "available": true,
-        "estimatedTotalHits": 253,
+        "estimatedTotalHits": 429,
         "indexUid": "ffbbnational_pratiques",
         "sampleKeys": [
           "_geo",
@@ -1491,7 +1457,7 @@
       },
       {
         "available": true,
-        "estimatedTotalHits": 4104,
+        "estimatedTotalHits": 4228,
         "indexUid": "ffbbnational_rss",
         "sampleKeys": [
           "categories",
@@ -1521,7 +1487,7 @@
       },
       {
         "available": true,
-        "estimatedTotalHits": 571,
+        "estimatedTotalHits": 1680,
         "indexUid": "ffbbserver_competitions",
         "sampleKeys": [
           "age",
@@ -1601,7 +1567,7 @@
       },
       {
         "available": true,
-        "estimatedTotalHits": 144,
+        "estimatedTotalHits": 146,
         "indexUid": "ffbbserver_formations",
         "sampleKeys": [
           "certification",
@@ -1636,7 +1602,7 @@
       },
       {
         "available": true,
-        "estimatedTotalHits": 4642,
+        "estimatedTotalHits": 4714,
         "indexUid": "ffbbserver_organismes",
         "sampleKeys": [
           "_geo",
@@ -1644,6 +1610,7 @@
           "adresseClubPro",
           "cartographie",
           "code",
+          "code_emploi",
           "commune",
           "communeClubPro",
           "dateAffiliation",
@@ -1671,7 +1638,7 @@
       },
       {
         "available": true,
-        "estimatedTotalHits": 96,
+        "estimatedTotalHits": 5000,
         "indexUid": "ffbbserver_rencontres",
         "sampleKeys": [
           "_geo",
@@ -1763,7 +1730,7 @@
       },
       {
         "available": true,
-        "estimatedTotalHits": 19,
+        "estimatedTotalHits": 7,
         "indexUid": "ffbbserver_tournois",
         "sampleKeys": [
           "_geo",
@@ -1802,7 +1769,7 @@
       },
       {
         "available": true,
-        "estimatedTotalHits": 6106,
+        "estimatedTotalHits": 6229,
         "indexUid": "ffbbsite_news",
         "sampleKeys": [
           "author",
@@ -1831,7 +1798,7 @@
       },
       {
         "available": true,
-        "estimatedTotalHits": 1842,
+        "estimatedTotalHits": 1858,
         "indexUid": "youtube_videos",
         "sampleKeys": [
           "channelId",
@@ -1864,7 +1831,7 @@
     ],
     "metadata": {
       "source": "https://meilisearch-prod.ffbb.app/multi-search",
-      "timestamp": "2026-08-10T19:59:19.080946+00:00"
+      "timestamp": "2026-09-11T10:11:11.270973+00:00"
     },
     "unavailable_indexes": [
       {
@@ -1900,9 +1867,9 @@
   "metadata": {
     "api_base_url": "https://api.ffbb.app/",
     "meilisearch_base_url": "https://meilisearch-prod.ffbb.app/",
-    "openapi_sha256": "d42e75cfb86a35bd5e17f12cc75785563d25a33ac9885ffa1ac0996c0140ff31",
-    "openapi_snapshot_sha256": "8a7b1fa7c2e9b499a050bcf7a7d9282c3daa7805f2d43ab61d5dc14d1686ed4d",
-    "openapi_version": "e5f76d83e876077e80ab344bbb4fc03606f63ca4",
-    "timestamp": "2026-08-10T19:59:19.080946+00:00"
+    "openapi_sha256": "1c6ecdab182113ad582b154df4d66bc1416a387d6fc4d57dd5b6788f39288a51",
+    "openapi_snapshot_sha256": "ddaf588729dc2f1f68ced57a5d4dd6fb5afc3f807be028ef1d4e8e439a3b6219",
+    "openapi_version": "326edbfd6bf4f57c9f1e22a17f0a177e9c85619b",
+    "timestamp": "2026-09-11T10:11:11.270973+00:00"
   }
 }

ffbb_data_client-2.4.8/data/field_dictionary.json

@@ -0,0 +1,289 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "version": "1.0.0",
+  "description": "Dictionnaire de référence métier des champs Directus et attributs Meilisearch de l'écosystème FFBB.",
+  "fields": {
+    "code_emploi": {
+      "name": "code_emploi",
+      "description": "Code de conventionnement ou statut employeur/PSF de l'organisme auprès de la FFBB (suivi des postes aidés ANS/PSF et structuration salariée).",
+      "category": "statut",
+      "usage": "Exposé dans Meilisearch pour filtrer les clubs et structures employeurs."
+    },
+    "nom": {
+      "name": "nom",
+      "description": "Nom officiel de l'entité (organisme, compétition, salle, officiel, terrain).",
+      "category": "identification",
+      "usage": "Champ de recherche textuelle principal."
+    },
+    "code": {
+      "name": "code",
+      "description": "Code fédéral unique attribué par la FFBB (ex: ARA0063062 pour un club, 063 pour un comité).",
+      "category": "identification",
+      "usage": "Identifiant stable de l'organisme dans FBI."
+    },
+    "id": {
+      "name": "id",
+      "description": "Identifiant numérique unique de la ressource dans le système Directus FFBB.",
+      "category": "identification",
+      "usage": "Clé primaire pour requêtes unitaires."
+    },
+    "commune": {
+      "name": "commune",
+      "description": "Nom de la commune de rattachement ou de localisation.",
+      "category": "geographie",
+      "usage": "Filtrage et recherche géographique."
+    },
+    "communeClubPro": {
+      "name": "communeClubPro",
+      "description": "Commune de rattachement de la section professionnelle d'un club.",
+      "category": "geographie",
+      "usage": "Distinction géographique entre structure amateur et structure pro."
+    },
+    "nom_club_pro": {
+      "name": "nom_club_pro",
+      "description": "Dénomination officielle de la structure professionnelle (SASP / SAOS) rattachée à l'association.",
+      "category": "identification",
+      "usage": "Affichage et distinction des clubs professionnels."
+    },
+    "dateAffiliation": {
+      "name": "dateAffiliation",
+      "description": "Date d'affiliation officielle de l'organisme auprès de la fédération.",
+      "category": "statut",
+      "usage": "Historique et ancienneté du club."
+    },
+    "date_affiliation": {
+      "name": "date_affiliation",
+      "description": "Date d'affiliation officielle de l'organisme auprès de la fédération (format snake_case).",
+      "category": "statut",
+      "usage": "Historique et ancienneté du club."
+    },
+    "saison_en_cours": {
+      "name": "saison_en_cours",
+      "description": "Indicateur booléen signalant si l'organisme est actif sur la saison sportive courante.",
+      "category": "statut",
+      "usage": "Filtrage des structures actives."
+    },
+    "type": {
+      "name": "type",
+      "description": "Typologie administrative de l'organisme (Club, Comité départemental, Ligue régionale, Groupement, etc.).",
+      "category": "statut",
+      "usage": "Facette de filtrage Meilisearch."
+    },
+    "mail": {
+      "name": "mail",
+      "description": "Adresse email de contact officiel de l'organisme ou du correspondant.",
+      "category": "contact",
+      "usage": "Coordonnées de communication."
+    },
+    "telephone": {
+      "name": "telephone",
+      "description": "Numéro de téléphone de contact officiel de l'organisme.",
+      "category": "contact",
+      "usage": "Coordonnées de communication."
+    },
+    "url_site_web": {
+      "name": "url_site_web",
+      "description": "URL du site internet officiel ou de la page de l'organisme.",
+      "category": "contact",
+      "usage": "Lien externe web."
+    },
+    "labellisation": {
+      "name": "labellisation",
+      "description": "Labels fédéraux obtenus par le club (École Française de MiniBasket, Club Formateur, Basket Santé, Citoyen, etc.).",
+      "category": "sportif",
+      "usage": "Valorisation des compétences et labels FFBB."
+    },
+    "offres_pratiques": {
+      "name": "offres_pratiques",
+      "description": "Types de pratiques basket proposées (5x5, 3x3, Micro-Basket, Basket Santé, Basket Inclusif, etc.).",
+      "category": "sportif",
+      "usage": "Recherche d'offres de pratique pour les licenciés."
+    },
+    "engagements_noms": {
+      "name": "engagements_noms",
+      "description": "Noms textuels des équipes engagées par le club dans les championnats.",
+      "category": "sportif",
+      "usage": "Recherche textuelle d'équipes par club."
+    },
+    "code_structure": {
+      "name": "code_structure",
+      "description": "Code identifiant de la structure organisatrice ou hôte.",
+      "category": "identification",
+      "usage": "Rattachement administratif."
+    },
+    "date_validation_ffbb": {
+      "name": "date_validation_ffbb",
+      "description": "Date à laquelle la FFBB a formellement validé l'élément ou l'offre de pratique.",
+      "category": "statut",
+      "usage": "Suivi d'homologation."
+    },
+    "date_validation_ffbb_timestamp": {
+      "name": "date_validation_ffbb_timestamp",
+      "description": "Timestamp Unix de la date de validation FFBB.",
+      "category": "statut",
+      "usage": "Tri chronologique performant dans Meilisearch."
+    },
+    "_geo": {
+      "name": "_geo",
+      "description": "Coordonnées géographiques de localisation (latitude, longitude) au format standard Meilisearch.",
+      "category": "geographie",
+      "usage": "Recherche géographique de proximité (_geoRadius, _geoBoundingBox)."
+    },
+    "typeCompetitionGenerique": {
+      "name": "typeCompetitionGenerique",
+      "description": "Niveau générique de compétition (Championnat de France, Régional, Départemental, Coupe, Tournoi).",
+      "category": "sportif",
+      "usage": "Filtrage et classification des compétitions."
+    },
+    "sexe": {
+      "name": "sexe",
+      "description": "Genre de la compétition ou de l'équipe (Masculin, Féminin, Mixte).",
+      "category": "sportif",
+      "usage": "Filtrage par genre."
+    },
+    "age": {
+      "name": "age",
+      "description": "Tranche d'âge de la compétition (Seniors, U20, U18, U15, U13, etc.).",
+      "category": "sportif",
+      "usage": "Filtrage par catégorie d'âge."
+    },
+    "certification": {
+      "name": "certification",
+      "description": "Type de diplôme ou brevet délivré par une session de formation (ex: CQP, Brevet Fédéral).",
+      "category": "formation",
+      "usage": "Recherche et filtrage des formations FFBB."
+    },
+    "count": {
+      "name": "count",
+      "description": "Nombre total d'éléments (photos, items, participants) associés.",
+      "category": "statistique",
+      "usage": "Indicateur quantitatif."
+    },
+    "cover": {
+      "name": "cover",
+      "description": "URL ou identifiant de l'image de couverture / affiche.",
+      "category": "media",
+      "usage": "Affichage visuel de miniature."
+    },
+    "creator": {
+      "name": "creator",
+      "description": "Auteur ou créateur de la ressource dans le CMS Directus FFBB.",
+      "category": "metadonnees",
+      "usage": "Traçabilité éditoriale."
+    },
+    "date": {
+      "name": "date",
+      "description": "Date de l'événement, de la rencontre ou de la publication.",
+      "category": "temporel",
+      "usage": "Tri et affichage chronologique."
+    },
+    "date_created": {
+      "name": "date_created",
+      "description": "Date de création initiale de l'enregistrement dans la base Directus.",
+      "category": "metadonnees",
+      "usage": "Audit et tri."
+    },
+    "date_updated": {
+      "name": "date_updated",
+      "description": "Date de dernière mise à jour de l'enregistrement dans la base Directus.",
+      "category": "metadonnees",
+      "usage": "Gestion du cache et synchronisation."
+    },
+    "date_published": {
+      "name": "date_published",
+      "description": "Date de mise en ligne ou publication publique de l'article/contenu.",
+      "category": "temporel",
+      "usage": "Tri chronologique des flux d'actualités."
+    },
+    "date_timestamp": {
+      "name": "date_timestamp",
+      "description": "Timestamp Unix de la date principale pour tri numérique rapide.",
+      "category": "temporel",
+      "usage": "Tri indexé Meilisearch."
+    },
+    "title": {
+      "name": "title",
+      "description": "Titre officiel du contenu, événement ou entité.",
+      "category": "contenu",
+      "usage": "Recherche textuelle et affichage."
+    },
+    "titre": {
+      "name": "titre",
+      "description": "Titre du contenu ou de l'actualité en français.",
+      "category": "contenu",
+      "usage": "Recherche textuelle et affichage."
+    },
+    "surtitle": {
+      "name": "surtitle",
+      "description": "Surtitre ou chapeau introductif de l'article ou de la galerie.",
+      "category": "contenu",
+      "usage": "Mise en page éditoriale."
+    },
+    "description": {
+      "name": "description",
+      "description": "Texte descriptif détaillé de la ressource.",
+      "category": "contenu",
+      "usage": "Information détaillée et recherche full-text."
+    },
+    "latitude": {
+      "name": "latitude",
+      "description": "Coordonnée de latitude géographique.",
+      "category": "geographie",
+      "usage": "Positionnement cartographique."
+    },
+    "longitude": {
+      "name": "longitude",
+      "description": "Coordonnée de longitude géographique.",
+      "category": "geographie",
+      "usage": "Positionnement cartographique."
+    },
+    "code_postal": {
+      "name": "code_postal",
+      "description": "Code postal de localisation.",
+      "category": "geographie",
+      "usage": "Filtrage territorial et recherche locale."
+    },
+    "ville": {
+      "name": "ville",
+      "description": "Nom de la ville de localisation.",
+      "category": "geographie",
+      "usage": "Filtrage et recherche textuelle géographique."
+    },
+    "capacite": {
+      "name": "capacite",
+      "description": "Capacité d'accueil en nombre de places assises / spectateurs de la salle ou tribune.",
+      "category": "infrastructure",
+      "usage": "Caractéristiques techniques des salles FFBB."
+    },
+    "type_sol": {
+      "name": "type_sol",
+      "description": "Revêtement du terrain (Parquet, Synthétique, Résine, Bitume, etc.).",
+      "category": "infrastructure",
+      "usage": "Homologation et confort de jeu."
+    },
+    "type_salle": {
+      "name": "type_salle",
+      "description": "Catégorisation technique de l'équipement sportif (Gymnase, Palais des Sports, Complexe, Terrain extérieur 3x3).",
+      "category": "infrastructure",
+      "usage": "Filtrage des installations sportives."
+    },
+    "status": {
+      "name": "status",
+      "description": "État de publication de l'enregistrement dans Directus (published, draft, archived).",
+      "category": "statut",
+      "usage": "Filtrage des données actives."
+    },
+    "horaire": {
+      "name": "horaire",
+      "description": "Heure programmée de la rencontre (format HH:MM).",
+      "category": "temporel",
+      "usage": "Calendrier et programmation des matchs."
+    },
+    "pro": {
+      "name": "pro",
+      "description": "Indicateur booléen signalant si la rencontre ou la compétition concerne le secteur professionnel (LNB, LFB, etc.).",
+      "category": "sportif",
+      "usage": "Séparation des compétitions fédérales et professionnelles."
+    }
+  }
+}