PlantUML doc & Human Readable commentary
This commit is contained in:
214
docs/plantuml-human-readable.md
Normal file
214
docs/plantuml-human-readable.md
Normal file
@@ -0,0 +1,214 @@
|
||||
# PlantUML — Format de commentaire human-readable
|
||||
|
||||
Ce document décrit la syntaxe des commentaires attachés aux ressources et aux liens
|
||||
dans les fichiers PlantUML importés par OpenCloud.
|
||||
|
||||
---
|
||||
|
||||
## Syntaxe générale
|
||||
|
||||
```plantuml
|
||||
TypeRessource(varName, "Nom affiché") ' clé: valeur, clé.sous_clé: valeur
|
||||
```
|
||||
|
||||
### Règles de parsing
|
||||
|
||||
| Règle | Détail |
|
||||
|---|---|
|
||||
| Séparateur de paires | `,` |
|
||||
| Séparateur clé/valeur | premier `:` de la paire (les URLs `http://...` sont gérées) |
|
||||
| Sous-objets | notation pointée `access.container.image: nginx` |
|
||||
| Types | auto-inférés : `bool` > `float64` > `string` |
|
||||
| Fallback | JSON brut si le commentaire commence par `{` (compatibilité ascendante) |
|
||||
|
||||
### Comportement à l'import
|
||||
|
||||
Chaque ressource reçoit automatiquement une **instance par défaut**, seedée avec les
|
||||
attributs de la ressource parente. Le commentaire vient ensuite **surcharger** uniquement
|
||||
les champs explicitement renseignés.
|
||||
|
||||
> **Exception :** `WorkflowEvent` n'a pas d'instance (voir section dédiée).
|
||||
|
||||
---
|
||||
|
||||
## Ressources disponibles
|
||||
|
||||
### `Data(var, "nom")` — Données
|
||||
|
||||
Ressource de données. Les attributs qualifient le modèle de données **et** son instance
|
||||
(source d'accès).
|
||||
|
||||
| Clé | Type | Description |
|
||||
|---|---|---|
|
||||
| `type` | string | Type de données (`raster`, `vector`, `tabular`…) |
|
||||
| `quality` | string | Niveau de qualité |
|
||||
| `open_data` | bool | Données en accès libre |
|
||||
| `static` | bool | Données statiques (pas de mise à jour) |
|
||||
| `personal_data` | bool | Contient des données personnelles |
|
||||
| `anonymized_personal_data` | bool | Données personnelles anonymisées |
|
||||
| `size` | float64 | Taille en GB |
|
||||
| `access_protocol` | string | Protocole d'accès (`http`, `s3`, `ftp`…) |
|
||||
| `country` | string | Code pays ISO (`FR`, `DE`…) |
|
||||
| `location.latitude` | float64 | Latitude géographique |
|
||||
| `location.longitude` | float64 | Longitude géographique |
|
||||
| `source` | string | URL / endpoint d'accès à la donnée |
|
||||
|
||||
```plantuml
|
||||
Data(d1, "Satellites L2A") ' type: raster, open_data: true, size: 120.5, source: https://catalogue.example.com, country: FR
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `Processing(var, "nom")` — Traitement
|
||||
|
||||
Ressource de traitement (algorithme, conteneur, service). Les attributs qualifient
|
||||
le modèle de traitement **et** sa configuration d'exécution.
|
||||
|
||||
| Clé | Type | Description |
|
||||
|---|---|---|
|
||||
| `infrastructure` | int | Infrastructure cible : `0`=DOCKER, `1`=KUBERNETES, `2`=SLURM, `3`=HW, `4`=CONDOR |
|
||||
| `is_service` | bool | Traitement persistant (service long-running) |
|
||||
| `open_source` | bool | Code source ouvert |
|
||||
| `license` | string | Licence (`MIT`, `Apache-2.0`, `GPL-3.0`…) |
|
||||
| `maturity` | string | Maturité (`prototype`, `beta`, `production`…) |
|
||||
| `access_protocol` | string | Protocole d'accès |
|
||||
| `country` | string | Code pays ISO |
|
||||
| `location.latitude` | float64 | Latitude |
|
||||
| `location.longitude` | float64 | Longitude |
|
||||
| `access.container.image` | string | Image du conteneur |
|
||||
| `access.container.command` | string | Commande de démarrage |
|
||||
| `access.container.args` | string | Arguments de la commande |
|
||||
|
||||
```plantuml
|
||||
Processing(p1, "NDVI Calc") ' infrastructure: 0, open_source: true, license: MIT, maturity: production, access.container.image: myrepo/ndvi:1.2
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `Storage(var, "nom")` — Stockage
|
||||
|
||||
Ressource de stockage. Produit une instance live (`LiveStorage`) à l'import.
|
||||
|
||||
| Clé | Type | Description |
|
||||
|---|---|---|
|
||||
| `storage_type` | int | Type de stockage (enum) |
|
||||
| `source` | string | URL / endpoint du stockage |
|
||||
| `path` | string | Chemin ou bucket dans le stockage |
|
||||
| `local` | bool | Stockage local |
|
||||
| `security_level` | string | Niveau de sécurité |
|
||||
| `size` | float64 | Taille allouée en GB |
|
||||
| `encryption` | bool | Chiffrement activé |
|
||||
| `redundancy` | string | Politique de redondance |
|
||||
| `throughput` | string | Débit cible |
|
||||
| `access_protocol` | string | Protocole (`s3`, `nfs`, `smb`…) |
|
||||
| `country` | string | Code pays ISO |
|
||||
| `location.latitude` | float64 | Latitude |
|
||||
| `location.longitude` | float64 | Longitude |
|
||||
|
||||
```plantuml
|
||||
Storage(s1, "Minio OVH") ' source: http://minio.example.com:9000, path: /bucket/data, access_protocol: s3, encryption: true, size: 500, country: FR
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `ComputeUnit(var, "nom")` — Unité de calcul
|
||||
|
||||
Ressource de calcul (datacenter, cluster). Produit une instance live (`LiveDatacenter`)
|
||||
à l'import.
|
||||
|
||||
| Clé | Type | Description |
|
||||
|---|---|---|
|
||||
| `architecture` | string | Architecture CPU (`x86_64`, `arm64`…) |
|
||||
| `infrastructure` | int | `0`=DOCKER, `1`=KUBERNETES, `2`=SLURM, `3`=HW, `4`=CONDOR |
|
||||
| `source` | string | URL de l'API du datacenter |
|
||||
| `security_level` | string | Niveau de sécurité |
|
||||
| `annual_co2_emissions` | float64 | Émissions CO₂ annuelles (kg) |
|
||||
| `access_protocol` | string | Protocole d'accès |
|
||||
| `country` | string | Code pays ISO |
|
||||
| `location.latitude` | float64 | Latitude |
|
||||
| `location.longitude` | float64 | Longitude |
|
||||
|
||||
```plantuml
|
||||
ComputeUnit(c1, "Datacenter Rennes") ' source: https://api.dc-rennes.example.com, infrastructure: 1, country: FR, location.latitude: 48.11, location.longitude: -1.68, security_level: high
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `WorkflowEvent(var, "nom")` — Événement déclencheur de workflow
|
||||
|
||||
Crée directement un `NativeTool` de type `WORKFLOW_EVENT` (Kind = 0).
|
||||
Représente le point de départ d'un workflow.
|
||||
|
||||
> **Pas d'instance. Pas de commentaire.**
|
||||
> Le nom du `NativeTool` est forcé à `WORKFLOW_EVENT` à l'import.
|
||||
|
||||
```plantuml
|
||||
WorkflowEvent(e1, "Start")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Liens
|
||||
|
||||
Les commentaires sur les liens qualifient la connexion entre deux ressources
|
||||
(typiquement entre un traitement et un stockage).
|
||||
|
||||
### Syntaxe
|
||||
|
||||
```plantuml
|
||||
source --> destination ' clé: valeur
|
||||
source <-- destination ' clé: valeur
|
||||
source -- destination ' clé: valeur (non directionnel)
|
||||
```
|
||||
|
||||
### Attributs disponibles
|
||||
|
||||
| Clé | Type | Description |
|
||||
|---|---|---|
|
||||
| `storage_link_infos.write` | bool | `true` = écriture, `false` = lecture |
|
||||
| `storage_link_infos.source` | string | Chemin source dans le lien |
|
||||
| `storage_link_infos.destination` | string | Chemin destination dans le lien |
|
||||
| `storage_link_infos.filename` | string | Nom du fichier échangé |
|
||||
|
||||
```plantuml
|
||||
p1 --> s1 ' storage_link_infos.write: true, storage_link_infos.filename: output.tif
|
||||
d1 --> p1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Exemple complet
|
||||
|
||||
```plantuml
|
||||
@startuml
|
||||
!include opencloud.puml
|
||||
|
||||
WorkflowEvent(e1, "Start")
|
||||
|
||||
Data(d1, "Satellites L2A") ' type: raster, open_data: true, size: 120.5, source: https://catalogue.example.com, country: FR
|
||||
|
||||
Processing(p1, "NDVI") ' infrastructure: 0, open_source: true, license: MIT, access.container.image: myrepo/ndvi:1.2
|
||||
|
||||
Storage(s1, "Minio résultats") ' source: http://minio.example.com:9000, path: /results, access_protocol: s3, encryption: true, size: 500, country: FR
|
||||
|
||||
ComputeUnit(c1, "DC Rennes") ' source: https://api.dc.example.com, infrastructure: 1, country: FR, location.latitude: 48.11, location.longitude: -1.68
|
||||
|
||||
e1 --> p1
|
||||
d1 --> p1
|
||||
p1 --> s1 ' storage_link_infos.write: true, storage_link_infos.filename: ndvi.tif
|
||||
s1 --> c1
|
||||
|
||||
@enduml
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Récapitulatif des types de ressources
|
||||
|
||||
| Mot-clé PlantUML | Type Go | Instance | Live | Commentaire |
|
||||
|---|---|---|---|---|
|
||||
| `Data` | `DataResource` | `DataInstance` | non | oui |
|
||||
| `Processing` | `ProcessingResource` | `ProcessingInstance` | non | oui |
|
||||
| `Storage` | `StorageResource` | `StorageResourceInstance` | oui → `LiveStorage` | oui |
|
||||
| `ComputeUnit` | `ComputeResource` | `ComputeResourceInstance` | oui → `LiveDatacenter` | oui |
|
||||
| `WorkflowEvent` | `NativeTool` (Kind=WORKFLOW_EVENT) | aucune | non | non |
|
||||
Reference in New Issue
Block a user