# HDS

> Appeler le module de données de santé par l'API publique, rôles HDS requis, chemins disponibles et principaux endpoints des coffres et documents.

Le module HDS stocke et partage des données de santé dans un cadre certifié : des **coffres** contiennent des **documents** chiffrés et versionnés, partagés avec des utilisateurs, des équipes ou des rôles. Toutes ses opérations passent par l'API publique sous le préfixe `/api/hds`. Le fonctionnement du module et ses guides sont dans [Données de santé (HDS)](/v1.0/hds).

## Conditions d'accès

- L'application doit être déclarée HDS, ce qui se fait depuis la console.
- L'appelant doit porter **au moins un rôle HDS** parmi `HDS_ADMIN`, `HDS_HEALTHCARE`, `HDS_MEDICAL`, `HDS_PATIENT`, `HDS_STORAGE` et `HDS_DELETE`. Chaque opération exige ensuite une permission précise, indiquée avec elle.
- Authentifiez l'appel avec le **jeton Keycloak** de l'utilisateur, dans `Authorization` : le jeton enrichi ne porte pas les rôles HDS.

Les données sont cloisonnées par client : un utilisateur ne voit que les coffres de son client.

## Rôles HDS

| Rôle | Ce qu'il permet |
|---|---|
| `HDS_ADMIN` | Toutes les opérations, y compris l'administration et le journal d'audit |
| `HDS_HEALTHCARE` | Créer et lire des coffres, déposer et lire des documents, partager, recueillir un consentement, accès d'urgence, recherche, export FHIR |
| `HDS_MEDICAL` | Lire coffres, documents, dossiers et consentements ; liens de téléchargement ; recherche ; export FHIR |
| `HDS_PATIENT` | Lire ses coffres et les exporter, déposer et lire des documents, recherche |
| `HDS_STORAGE` | Créer et lire des coffres, gérer documents et dossiers, lire les partages, recherche |
| `HDS_DELETE` | Supprimer documents, coffres et dossiers ; révoquer des partages |

## Conventions propres au module

| Sujet | Règle |
|---|---|
| Préfixe | `https://api.wakastart.app/api/hds/…` |
| Chemins | Les chemins décrits sur cette page, sous `/vaults`, `/shares`, `/break-glass`, `/audit-logs`, `/compliance`, `/access-reviews`, `/search` et `/fhir`. Un chemin non autorisé, ou contenant `..`, donne `403` `HDS path not allowed` |
| Format des erreurs | Le corps d'erreur du module est renvoyé tel quel : `{ "statusCode", "message", "error" }` |
| Pagination | Par curseur : `limit` (défaut 20, 100 au plus) et `cursor` |
| Idempotence | En-tête `Idempotency-Key` sur `POST`, `PUT` et `PATCH` ; réponse rejouée 24 heures avec `X-Idempotency-Replayed: true` |
| Fichiers | `multipart/form-data`, champ `file`, 100 Mo au plus |
| Délai | 30 secondes de traitement (`408` `Request timed out` au-delà) |
| Débit | 100 requêtes par minute |

## L'objet Coffre

| Champ | Type | Description |
|---|---|---|
| `id` | chaîne | Identifiant, préfixé `vlt_` |
| `type` | chaîne | `PATIENT` (dossier d'un patient), `STRUCTURAL` (d'une équipe), `RESEARCH` (étude, sans patient) ou `TEMPORARY` |
| `label` | chaîne (255) | Libellé |
| `status` | chaîne | `ACTIVE`, `ARCHIVED`, `SUSPENDED` ou `DELETED` |
| `ownerId`, `ownerTeamId` | chaîne | Propriétaire ; équipe propriétaire pour un coffre `STRUCTURAL` |
| `patient` | objet | `externalId`, `ins`, `firstName`, `lastName`, `birthDate`, pour un coffre `PATIENT` |
| `retentionPolicy` | chaîne | `STANDARD`, `EXTENDED`, `LEGAL_HOLD` ou `CUSTOM` |
| `storageUsedBytes`, `documentCount` | entier | Occupation |
| `expiresAt` | chaîne ISO 8601 ou `null` | Échéance, obligatoire pour `TEMPORARY` |

## L'objet Document

| Champ | Type | Description |
|---|---|---|
| `id` | chaîne | Identifiant, préfixé `doc_` |
| `status` | chaîne | `ACTIVE`, `ARCHIVED`, `SOFT_DELETED`, `QUARANTINED`, `SEALED` ou `DELETED` |
| `currentVersion` | entier | Version courante |
| `versions` | tableau | `{ version, sizeBytes, hashSha256, uploadedAt, uploadedBy, comment }` |
| `antivirusStatus` | chaîne | `PENDING`, `CLEAN`, `INFECTED` ou `QUARANTINED` |
| `legalHold` | booléen | Conservation légale : le document ne peut pas être supprimé |

## Créer un coffre

::endpoint{method="POST" path="/api/hds/vaults"}

**Permission** : création de coffre (`HDS_HEALTHCARE`, `HDS_STORAGE`, `HDS_ADMIN`).

| Champ | Type | Obligatoire | Règle |
|---|---|---|---|
| `type` | chaîne | oui | `PATIENT`, `STRUCTURAL`, `RESEARCH`, `TEMPORARY` |
| `label` | chaîne | oui | 255 caractères au plus |
| `patient` | objet | pour `PATIENT` | Interdit pour `RESEARCH` |
| `ownerTeamId` | chaîne | pour `STRUCTURAL` | — |
| `expiresAt` | chaîne ISO 8601 | pour `TEMPORARY` | Entre 24 heures et 90 jours |
| `retentionPolicy` | chaîne | non | — |
| `defaultFolders` | tableau de chaînes | non | Dossiers créés d'office |
| `metadata` | objet | non | — |

```bash
curl -s -X POST https://api.wakastart.app/api/hds/vaults \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: 3f1c9b2e-0d4a-4c7e-9b1a-5e6f7a8b9c0d" \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "PATIENT",
    "label": "Dossier de Jeanne Exemple",
    "patient": { "externalId": "PAT-0042", "firstName": "Jeanne", "lastName": "Exemple", "birthDate": "1980-04-12" },
    "defaultFolders": ["Ordonnances", "Comptes rendus"]
  }'
```

**Réponse `201`** : l'objet Coffre, au statut `ACTIVE`, dont l'appelant est propriétaire.

**Erreurs** : `400` `Vault quota exceeded: <n>/<max>` ; `403` `Insufficient HDS permissions for this operation`.

## Déposer un document

::endpoint{method="POST" path="/api/hds/vaults/{vaultId}/documents"}

**Permission** : dépôt (`HDS_HEALTHCARE`, `HDS_PATIENT`, `HDS_STORAGE`, `HDS_ADMIN`). Corps `multipart/form-data` : `file` (100 Mo au plus), `comment` et `folderId` facultatifs.

```bash
curl -s -X POST https://api.wakastart.app/api/hds/vaults/vlt_8f2a1c/documents \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F "file=@compte-rendu.pdf" \
  -F "comment=Consultation du 23 octobre"
```

Le fichier est analysé par l'antivirus puis chiffré. Un fichier déjà présent dans le coffre (même empreinte) n'est pas dupliqué : la réponse renvoie le document existant avec `deduplicated: true`. Si l'analyse n'est pas terminée, le document est créé au statut `QUARANTINED`.

**Erreurs** : `400` `Infected file detected — upload denied` ; `400` `Document quota exceeded: <n>/<max>` ; `413` `Storage quota exceeded`.

## Autres opérations

| Opération | Méthode et chemin (sous `/api/hds`) | Permission principale |
|---|---|---|
| Lister ses coffres (possédés et partagés) | `GET /vaults` (`type`, `status`, `search`, `limit`, `cursor`) | Lecture de coffre |
| Lire, modifier un coffre | `GET /vaults/{id}`, `PATCH /vaults/{id}` (`label`, `metadata`, `status`) | Lecture ; propriétaire pour modifier |
| Sceller un coffre | `POST /vaults/{id}/seal` | Propriétaire |
| Exporter les métadonnées d'un coffre | `GET /vaults/{id}/export` | `HDS_PATIENT`, `HDS_ADMIN` |
| Supprimer un coffre | `DELETE /vaults/{id}` | `HDS_DELETE`, `HDS_ADMIN` |
| Lister, lire, supprimer des documents | `GET /vaults/{vaultId}/documents`, `GET …/documents/{id}`, `DELETE …/documents/{id}` | Lecture ; suppression |
| Gérer les versions | `POST …/documents/{id}/versions`, `GET …/documents/{id}/versions`, `POST …/documents/{id}/versions/{v}/rollback` | Dépôt ; lecture |
| Lien de téléchargement | `POST …/documents/{id}/presign` (`expiresInSeconds` de 60 à 3 600, défaut 300 ; `version`) | Lien de téléchargement |
| Vignette | `GET …/documents/{id}/thumbnail` | Lien de téléchargement |
| Dossiers | `GET`, `POST`, `PATCH`, `DELETE /vaults/{vaultId}/folders…` | Dossiers |
| Partages | `POST /shares` (`vaultId`, cible utilisateur, équipe ou rôle, `level` `READ`, `READ_WRITE` ou `FULL_CONTROL`, `expiresAt`), `GET /shares`, `DELETE /shares/{id}` | Propriétaire, `HDS_HEALTHCARE`, `HDS_ADMIN` |
| Consentements | `POST`, `GET`, `DELETE /vaults/{vaultId}/consents` | `HDS_HEALTHCARE` pour recueillir |
| Accès d'urgence | `POST /break-glass` (justification de 20 caractères au moins) | `HDS_HEALTHCARE` |
| Recherche | `GET /search/documents`, `GET /search/vaults` (`q`, `limit`, `cursor`…) | Recherche |
| Export FHIR | `GET /fhir/…` | Export FHIR |
| Journal d'audit HDS | `GET /audit-logs`, `GET /audit-logs/integrity-check` | `HDS_ADMIN` |
| Rapports de conformité | `GET /compliance/rgpd`, `/compliance/hds`, `/compliance/nis2` ; `POST /compliance/reports` | Conformité |
| Revues d'accès | `/access-reviews` | Revue d'accès |

Un document supprimé passe en `DELETED` et est purgé définitivement 30 jours plus tard, à la date `hardDeleteScheduledAt`. Un document sous conservation légale ou scellé ne peut pas être supprimé : `403` `Cannot delete document under legal hold` ou `Cannot delete sealed document`.


## Erreurs propres au relais

| Statut | Message | Cause |
|---|---|---|
| `403` | `Rôle(s) HDS requis: HDS_ADMIN, HDS_HEALTHCARE, HDS_MEDICAL, HDS_PATIENT, HDS_STORAGE, HDS_DELETE (mode: any)` | L'appelant ne porte aucun rôle HDS, ou s'est authentifié avec le seul jeton enrichi |
| `403` | `HDS path not allowed` | Chemin hors liste |
| `503` | `HDS service unavailable` | Module momentanément indisponible |
| `503` | `Auth check unavailable` | Vérification de révocation indisponible ; réessayez |
