feat(erp): verser les pièces juridiques de 1_DOCUMENTS dans la GED (#88)

Co-authored-by: Gabriel Radureau <[email protected]>
2026-08-13 19:15:01 +02:00
parent 9253ac8d4c
commit 216dc0213b
3 changed files with 529 additions and 0 deletions
@@ -0,0 +1,92 @@
+# 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.