docs: mention annexes pour documents, capabilities etc #565

IGNF · Dec 20, 2024 · bbfe5f1 · bbfe5f1
1 parent cc5b0e6
commit bbfe5f1
Show file tree

Hide file tree

Showing 6 changed files with 130 additions and 27 deletions.
diff --git a/docs/developer/entrepot/README.md b/docs/developer/entrepot/README.md
@@ -1,8 +1,12 @@
 # Utilisation de l'API Entrepôt
 
--   [Description des entités de l'API](./entities.md)
--   Utilisation des :
-    -   [tags](./tags.md)
-    -   [labels](./labels.md)
-    -   [annexes](./annexes.md)
-    -   [fichiers statiques](./statics.md)
+Le site cartes.gouv.fr repose principalement sur l'API Entrepôt.
+
+Voici les liens de sa documentation en [production](https://geoplateforme.github.io/entrepot/production) et [qualification](https://geoplateforme.github.io/entrepot/qualification)
+
+- [Description des entités de l'API](https://geoplateforme.github.io/entrepot/production/concepts)
+- Utilisation des :
+    - [tags](./tags.md)
+    - [labels](./labels.md)
+    - [annexes](./annexes.md)
+    - [fichiers statiques](./statics.md)
diff --git a/docs/developer/entrepot/annexes.md b/docs/developer/entrepot/annexes.md
@@ -1,6 +1,6 @@
 # Utilisation des fichiers annexes
 
-Il s'agit d'une [entité](./entities.md) de l'API qui représente des fichiers librement déposés et utilisés par les utilisateurs de l'API Entrepôt.
+Il s'agit d'une [entité](https://geoplateforme.github.io/entrepot/production/concepts/) de l'API qui représente des fichiers librement déposés et utilisés par les utilisateurs de l'API Entrepôt.
 
 ## un ensemble de fichiers de style associés à une configuration
 
@@ -16,7 +16,19 @@ Syntaxe du path :
 
 Structure de cet annexe json :
 
--   `SLD` ou `QML` pour une configuration du type `WFS`
+```ts
+export type Styles = {
+    name: string;
+    current?: boolean;
+    layers: {
+        name?: string;
+        annexe_id: string;
+        url: string;
+    }[];
+}[];
+```
+
+- `SLD` ou `QML` pour une configuration du type `WFS`
 
 ```json
 [
@@ -45,7 +57,7 @@ Structure de cet annexe json :
 
 > Il y a un fichier de style SLD par table. Donc pour chaque table il y a un annexe qui contient le style. Et cette structure json globale répertorie tous les styles associés à une configuration WFS.
 
--   `Mapbox` pour une configuration du type `WMTS-TMS`
+- `Mapbox` pour une configuration du type `WMTS-TMS` (pyramide de tuiles vectorielles)
 
 ```json
 [
@@ -66,3 +78,47 @@ Structure de cet annexe json :
     }
 ]
 ```
+
+## un ensemble de documents liés à une fiche de donnée
+
+Syntaxe du path :
+
+```
+/documents/[datasheet_name]/styles.json
+```
+
+| variable         | description               |        |
+| ---------------- | ------------------------- | ------ |
+| `datasheet_name` | nom de la fiche de donnée | string |
+
+Structure de cet annexe json :
+
+```ts
+export type DatasheetDocument = {
+    type: "link" | "file";
+    url: string;
+    name: string;
+    description?: string;
+    id: string;
+};
+```
+
+```json
+[
+    {
+        "type": "link",
+        "name": "test lien",
+        "description": "test lien desc",
+        "id": "uuid généré automatiquement par cartes.gouv.fr",
+        "url": "https://ign.fr"
+    },
+    {
+        "type": "file",
+        "name": "projet qgis",
+        "description": "un projet qgis",
+        "id": "identifiant de l'annexe",
+        "url": "url complète de l'annexe"
+    }
+    ...
+]
+```
diff --git a/docs/developer/entrepot/entities.md b/docs/developer/entrepot/entities.md
diff --git a/docs/developer/entrepot/labels.md b/docs/developer/entrepot/labels.md
@@ -4,6 +4,8 @@ Certaines entités portent une propriété `labels`, qui est une liste de chaîn
 
 Mais nous utilisons les labels comme des `tags` de la manière suivante : "[clé]=[valeur]". Donc, pas de "=" possible dans les labels.
 
+Exemple : datasheet_name=Ma donnée
+
 ## `annexe`
 
 ### vignette d'une fiche de donnée
@@ -15,7 +17,37 @@ Mais nous utilisons les labels comme des `tags` de la manière suivante : "[clé
 
 ### fichier de style individuel (par ex. contenu du SLD, QML etc)
 
+Un fichier de style déposé via cartes.gouv.fr est stocké d'abord dans un annexe avant d'être référencé dans l'annexe "chapeau" décrit [ici](./annexes.md)
+
 | label            | description               |        |
 | ---------------- | ------------------------- | ------ |
 | `datasheet_name` | nom de la fiche de donnée | string |
 | `type`           | valeur fixe : "style"     | string |
+
+### ensemble de documents liés à une fiche de donnée
+
+| label            | description                   |        |
+| ---------------- | ----------------------------- | ------ |
+| `datasheet_name` | nom de la fiche de donnée     | string |
+| `type`           | valeur fixe : "document-list" | string |
+
+### un document lié à une fiche de donnée
+
+Un document du type fichier est stocké d'abord dans un annexe avant d'être référencé dans l'annexe "chapeau" décrit au-dessus et [ici](./annexes.md)
+
+| label            | description               |        |
+| ---------------- | ------------------------- | ------ |
+| `datasheet_name` | nom de la fiche de donnée | string |
+| `type`           | valeur fixe : "document"  | string |
+
+### fichier GetCapabilities filtrés pour les endpoints WFS, WMS (raster et vecteur) et WMTS
+
+Syntaxe du path :
+
+```
+/[endpoint_technical_name]/capabilities.xml
+```
+
+| label  | description                  |        |
+| ------ | ---------------------------- | ------ |
+| `type` | valeur fixe : "capabilities" | string |
diff --git a/docs/developer/entrepot/statics.md b/docs/developer/entrepot/statics.md
@@ -1,6 +1,6 @@
 # Utilisation des fichiers statiques
 
-Il s'agit d'une [entité](./entities.md) de l'API qui représente des fichiers de configuration utilisés par l'Entrepôt en arrière plan lors des différents traitements.
+Il s'agit d'une [entité](https://geoplateforme.github.io/entrepot/production/concepts/) de l'API qui représente des fichiers de configuration utilisés par l'Entrepôt en arrière plan lors des différents traitements.
 
 Cette entité `static` a seulement une propriété `name`, pas de `tags` ni de `labels`. Donc, afin de pouvoir lier ces fichiers statiques à d'autres entités pour notre usage, nous allons se contenter d'utiliser une nomination particulière.
 

diff --git a/docs/developer/entrepot/tags.md b/docs/developer/entrepot/tags.md
@@ -6,14 +6,14 @@ Certaines entités portent une propriété `tags`, qui est un dictionnaire clé/
 
 | tag                        | description                                                                                                                                               |         |
 | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| `proc_int_id`              | identifiant de l'exécution du traitement "Intégration de données vecteur livrées en base"                                                                 | uuidv4  |
 | `datasheet_name`           | nom de la fiche de donnée                                                                                                                                 | string  |
+| `proc_int_id`              | identifiant de l'exécution du traitement "Intégration de données vecteur livrées en base"                                                                 | uuidv4  |
 | `vectordb_id`              | identifiant de la donnée stockée en sortie du traitement `proc_int_id`                                                                                    | uuidv4  |
 | `data_upload_path`         | chemin vers le fichier téléversé                                                                                                                          |         |
 | `integration_progress`     | progression de l'intégration en base de données (envoi du fichier téléversé à l'API, attente des vérifications et puis le traitement d'intégration en BD) | json(1) |
 | `integration_current_step` | numéro de l'étape courante de integration_progress                                                                                                        | number  |
 
-(1) structure de json :
+(1) structure de json (chaîne json encodée) :
 
 ```json
 // nom de l'étape : statut [waiting, in_progress, successful, failed]
@@ -28,24 +28,41 @@ Certaines entités portent une propriété `tags`, qui est un dictionnaire clé/
 
 ### tags communs
 
+> [!IMPORTANT]
+> Ces tags sont présents sur tous les stored_data
+
 | tag              | description                             |        |
 | ---------------- | --------------------------------------- | ------ |
 | `datasheet_name` | pareil que `datasheet_name` de `upload` | string |
 
 ### tags spécifiques aux stored_data du type `VECTOR-DB`
 
-| tag           | description                                                   |        |
-| ------------- | ------------------------------------------------------------- | ------ |
-| `upload_id`   | identifiant de l'`upload` utilisé lors de l'intégration en BD | uuidv4 |
-| `proc_int_id` | pareil que `proc_int_id` de `upload`                          | uuidv4 |
+| tag              | description                                                   |        |
+| ---------------- | ------------------------------------------------------------- | ------ |
+| `datasheet_name` | -                                                             | -      |
+| `upload_id`      | identifiant de l'`upload` utilisé lors de l'intégration en BD | uuidv4 |
+| `proc_int_id`    | pareil que `proc_int_id` de `upload`                          | uuidv4 |
 
 ### tags spécifiques aux stored_data du type `ROK4-PYRAMID-VECTOR`
 
-| tag                 | description                                                                                 |         |
-| ------------------- | ------------------------------------------------------------------------------------------- | ------- |
-| `proc_pyr_creat_id` | identifiant de l'exécution du traitement "Calcul de pyramide vecteur"                       | uuidv4  |
-| `vectordb_id`       | identifiant de la donnée stockée `VECTOR-DB` utilisée pour le calcul de la pyramide vecteur | uuidv4  |
-| `is_sample`         | vrai s'il s'agit d'un échantillon : pyramide vecteur générée dans une petite zone           | boolean |
+| tag                 | description                                                                                 |                   |
+| ------------------- | ------------------------------------------------------------------------------------------- | ----------------- |
+| `datasheet_name`    | -                                                                                           | -                 |
+| `upload_id`         | -                                                                                           | -                 |
+| `proc_int_id`       | -                                                                                           | -                 |
+| `proc_pyr_creat_id` | identifiant de l'exécution du traitement "Calcul de pyramide vecteur"                       | uuidv4            |
+| `vectordb_id`       | identifiant de la donnée stockée `VECTOR-DB` utilisée pour le calcul de la pyramide vecteur | uuidv4            |
+| `is_sample`         | vrai s'il s'agit d'un échantillon : pyramide vecteur générée dans une petite zone           | "true" \| "false" |
+
+### tags spécifiques aux stored_data du type `ROK4-PYRAMID-RASTER`
+
+| tag                 | description                                                                                             |        |
+| ------------------- | ------------------------------------------------------------------------------------------------------- | ------ |
+| `datasheet_name`    | -                                                                                                       | -      |
+| `upload_id`         | -                                                                                                       | -      |
+| `proc_int_id`       | -                                                                                                       | -      |
+| `vectordb_id`       | -                                                                                                       | -      |
+| `proc_pyr_creat_id` | identifiant de l'exécution du traitement "Calcul ou mise à jour de pyramide raster par moissonnage WMS" | uuidv4 |
 
 ## `configuration`