# Runbook — verser un document dans la GED Dolibarr

Public : un agent, quel que soit son modèle, ou l'opérateur.

La question à se poser en premier n'est pas « comment téléverser » mais **« à
quoi ce document se rattache-t-il ? »**. La réponse décide de tout, et l'un des
deux chemins ne marche pas du tout comme son API le prétend.

## Deux GED, pas une

Dolibarr expose deux arbres, et ils n'ont rien en commun :

| Arbre | URL | Contenu | Comment y écrire |
| --- | --- | --- | --- |
| **Répertoires d'objets** | `/ecm/index_auto.php` | pièces rattachées à une facture, un tiers, une charge | **API REST**, `modulepart` de l'objet |
| **Répertoires manuels** | `/ecm/index.php` | ce qui n'a pas d'objet : statuts, KBIS, registre des décisions | **UI uniquement** |

**Règle :** une pièce qui justifie un fait comptable se rattache à son objet,
jamais à la GED manuelle. L'appel de cotisations URSSAF va sur les charges, une
facture fournisseur sur sa facture. La GED manuelle est le dernier recours, pour
ce qui ne se rattache à rien.

## Rattacher à un objet — API

```bash
curl -s -X POST https://erp.arcodange.lab/api/index.php/documents/upload \
  -H "DOLAPIKEY: $(cat test/.ai_agent_prod_prod_write.key)" \
  -H 'Content-Type: application/json' -d @- <<JSON
{"filename":"piece.pdf","modulepart":"tax","subdir":"<ID DE L'OBJET>",
 "filecontent":"<BASE64>","fileencoding":"base64","overwriteifexists":1}
JSON
```

`subdir` est l'**identifiant nu** de l'objet (`2`), rien d'autre. Vérifier sur
l'onglet Documents de l'objet que le compteur a bougé.

## Verser dans la GED manuelle — script

```bash
cd test
DOLIBARR_ADDRESS=https://erp-sandbox.arcodange.lab deno run -A provisionGed.ts
```

Production, double opt-in comme toute écriture de production :

```bash
DOLIBARR_ADDRESS=https://erp.arcodange.lab \
ARCO_ALLOW_PRODUCTION=erp.arcodange.lab \
ARCO_PROD_CONFIRM=I-UNDERSTAND-THIS-WRITES-PROD \
  deno run -A provisionGed.ts
```

`--dry-run` liste ce qui serait versé sans rien écrire, et vérifie déjà que
chaque pièce du manifeste existe sur le disque.

Ce qui est versé est déclaré dans **`test/gedManifest.ts`** — répertoires et
pièces. Ajouter un document, c'est ajouter une ligne au manifeste et relancer :
le script est idempotent, une pièce déjà présente n'est pas re-versée.

## Les cinq pièges, tous rencontrés

1. **L'API ment sur `modulepart=ecm`.** Elle répond le nom du fichier — donc
   succès — et ne dépose rien que la GED sache retrouver : l'arbre affiche « Pas
   de documents téléversés » et `/documents/download` répond **404** sur le
   chemin qu'on vient d'écrire. Elle accepte de surcroît **n'importe quel
   `subdir`** sans broncher. Pour la GED manuelle, **passer par l'UI**, qui écrit
   au bon endroit *et* inscrit la pièce à l'index — c'est l'index qui alimente
   compteurs et recherche. Une pièce non indexée est une pièce perdue.
2. **Un répertoire ne se crée que par l'UI**, sur
   `/ecm/dir_add_card.php?action=create&module=ecm`. Le formulaire répond
   « existe déjà » quand c'est le cas : cela vaut succès pour un script
   idempotent, ce n'est pas une erreur.
3. **L'arbre est replié et monté en JS.** `innerText` sur son conteneur renvoie
   vide alors que les répertoires existent ; ses ancres portent `href="#"`, le
   chemin vit dans l'attribut `rel`, et l'identifiant de section dans le
   `onclick`. Les sous-répertoires n'arrivent en DOM qu'au **dépliage**. Lire
   trop tôt, ou chercher un lien `section=`, fait conclure à un arbre vide.
4. **Plafond de 2 Mo** (`MAX_FILE_SIZE`). Au-delà, le formulaire accepte la
   soumission, n'écrit rien et **n'affiche aucune erreur** : le fichier
   disparaît en silence. Le script contrôle la taille avant d'envoyer. Pour
   relever la limite : `MAIN_UPLOAD_DOC` côté Dolibarr, `upload_max_filesize`
   côté PHP.
5. **La case « écraser » ne s'applique pas de façon fiable** : chaque passe
   ajoutait un doublon. L'idempotence se joue sur le **nom du fichier**, relu
   dans le répertoire avant et après.

## Vérifier

Toujours par les **noms**, jamais par un compteur : un compteur juste peut
recouvrir deux exemplaires d'une pièce et l'absence d'une autre. C'est ce que
fait le script en fin de course, et c'est ce qui a mis au jour l'échec silencieux
de l'API.