add dolibarr-tva-reconciliation, dolibarr-recurring-templates, dolibarr-data-snapshot

V3 bundle — three sibling skills under .claude/skills/, all read-only, all depending on the dolibarr base skill. dolibarr-tva-reconciliation: - tva-by-month.sh: HT + TVA grouped by (year-month × tva_tx), ready for CA3 / CA12 transcription. - tva-line-detail.sh: per-line audit trail with country-based bucket assignment (A1 domestic / A4 intra-UE autoliquidation / E2 export hors UE). Documents the French TVA mental model. - Today every Arcodange line is E2 (KissMetrics, US, autoliquidation 259-1° CGI). The skill scales for the day a French B2B is invoiced. dolibarr-recurring-templates: - list-templates.sh: probes /invoices/templates/{id} since there's no list endpoint. Stops after 5 consecutive empty responses. - inspect-template.sh: full audit per template, with health checks. - Surfaces that the "Kiss Metrics Invoice" template has frequency=0 and nb_gen_done=0 — it is NOT auto-firing. Every KM invoice today was manually duplicated. Cohort-review implication: the deferred 9-month cycle depends on Gabriel clicking "Generate" each month, not on a Dolibarr cron. dolibarr-data-snapshot: - snapshot.sh: bundles every read endpoint the dolibarr-* family uses into one JSON with a content_hash (sha256 of data only, excluding timestamp — so identical state hashes identically across runs). - Use cases: cohort evidence packs, drift detection, archival before a known-risky UI change. - V1 baseline summary captured at examples/snapshot-summary.txt (the ~246 KB snapshot file itself is intentionally not committed). Also extends dolibarr/SKILL.md endpoint catalogue with /invoices/templates/{id} (and its no-list-endpoint quirk + the id-null sentinel for missing ids), plus links to the three new sibling skills. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-29 00:01:06 +02:00
parent d34cba3fa0
commit f19b1d2ef2
16 changed files with 1554 additions and 1 deletions
--- a/.claude/skills/dolibarr-data-snapshot/SKILL.md
+++ b/.claude/skills/dolibarr-data-snapshot/SKILL.md
@@ -0,0 +1,114 @@
+---
+name: dolibarr-data-snapshot
+description: Snapshot the read-only state of the Arcodange Dolibarr instance into a single content-addressable JSON file — status, thirdparties (list + per-id detail), invoices (list + per-id detail + per-id payments), recurring templates, products, bank accounts. Each snapshot includes a `content_hash` (sha256 of the data, EXCLUDING the captured-at timestamp) so two snapshots of identical state hash identically — drift detection is one comparison. Use cases: cohort-review evidence packs, archival before a known-risky change, time-series drift detection between two dates, point-in-time forensics. Use when the user asks "snapshot Dolibarr", "dump the state", "archiver l'ERP", "preuve cohort", "diff entre deux dates". Depends on the `dolibarr` skill. SKIP for one-shot reads (use the other workflow skills directly), for PDF / binary attachments (intentionally excluded — would bloat the snapshot), for write-side changes (this is read-only forensics), and for snapshotting NON-Dolibarr state (bank statements, k8s, etc. — those would be sibling skills).
+requires:
+  bins: ["curl", "jq", "python3"]
+  auth: true
+---
+
+# dolibarr-data-snapshot — point-in-time JSON dump of Dolibarr read state
+
+One script: [`snapshot.sh`](scripts/snapshot.sh). Pulls every read-only endpoint the `dolibarr-*` family uses and bundles into a single JSON file with a content hash. Read-only, no side effects.
+
+Depends on the [dolibarr](../dolibarr/SKILL.md) base skill.
+
+## What's in the snapshot
+
+```json
+{
+  "schema_version": "1",
+  "captured_at": "2026-05-28T21:58:50Z",
+  "instance": "erp.arcodange.lab",
+  "content_hash": "sha256:6b94cd312d55a693d3c533ae6c9a5abef2734dd5bca8d4b1bdd5ca6ea6fc1f9a",
+  "data": {
+    "status":         { ... GET /status ... },
+    "thirdparties":   { "list": [ ... GET /thirdparties ... ], "detail": { "1": { ... GET /thirdparties/1 ... }, ... } },
+    "invoices":       { "list": [ ... ], "detail": { "12": { ... }, ... }, "payments": { "12": [ ... ], ... } },
+    "recurring_templates": { "1": { ... GET /invoices/templates/1 ... }, ... },
+    "products":       [ ... GET /products ... ],
+    "bank_accounts":  [ ... GET /bankaccounts ... ]
+  }
+}
+```
+
+**`content_hash` is the sha256 of `data` only** — it deliberately excludes `captured_at`, `schema_version`, `instance`, and the hash field itself. So two snapshots taken at different moments but reflecting **identical Dolibarr state** have the same `content_hash`. That's what makes drift detection trivial:
+
+```bash
+jq -r .content_hash snap-2026-05.json snap-2026-06.json
+# Same hash → no data changed between the two captures.
+# Different hash → use `jq` / `diff` to find what moved.
+```
+
+## Usage
+
+```bash
+./scripts/snapshot.sh                          # writes ./snapshot-YYYY-MM-DDTHHMMSSZ.json
+./scripts/snapshot.sh --out /tmp/baseline.json
+./scripts/snapshot.sh --print-only             # stdout, no file (pipe-friendly)
+./scripts/snapshot.sh --max-template-id 100    # raise the template-probe upper bound
+```
+
+Live output of the current Dolibarr (captured at [examples/snapshot-summary.txt](examples/snapshot-summary.txt) — the actual JSON is too big to commit verbatim, ~246 KB):
+
+```
+wrote ./snapshot-2026-05-28T215850Z.json (246186 bytes)
+  sha256:6b94cd312d55a693d3c533ae6c9a5abef2734dd5bca8d4b1bdd5ca6ea6fc1f9a
+```
+
+Contents (V1 baseline):
+- 10 thirdparties (KissMetrics + 9 others — prospects / suppliers / etc.)
+- 5 invoices, all KM (1 avoir + 4 regular)
+- 5 per-invoice payment arrays
+- 1 recurring template (Kiss Metrics Invoice — frequency=0, see `dolibarr-recurring-templates`)
+- 2 products (KM-audit, KM-cloud-devops)
+- 3 bank accounts (QONTO, WISE EURO, G.RADUREAU CCA)
+
+## What's intentionally excluded
+
+- **PDF attachments.** `/documents/download` returns base64 bodies up to ~MB each. Including them would 10×–100× the snapshot size. Workflow skills (`dolibarr-invoice-audit`) fetch PDFs on-demand.
+- **`users/info`** — leaks the `ai_agent` account internals. Out of scope for a read-only state dump.
+- **`/setup/modules`** — admin-only, not available to `ai_agent`.
+- **Anything that requires writing** (cron triggers, etc.).
+- **`/payments` list-all** — returns 501 (see base skill catalogue); we get payment data via per-invoice fetches.
+
+## Use cases
+
+### 1. Cohort-review evidence pack
+
+```bash
+./scripts/snapshot.sh --out evidence/dolibarr-2026-05-28.json
+# Send the file as proof of the billing state at that moment.
+# The content_hash signs the data.
+```
+
+### 2. Drift detection between two dates
+
+```bash
+./scripts/snapshot.sh --out snap-may.json
+# ... a month passes ...
+./scripts/snapshot.sh --out snap-jun.json
+jq -r .content_hash snap-may.json snap-jun.json
+# Different → something moved. Find what:
+diff <(jq -S .data snap-may.json) <(jq -S .data snap-jun.json) | head -50
+```
+
+### 3. Archive before a known-risky change
+
+Before manually firing the next M-N invoice, regenerating the PDF template, or any UI change with billing consequences:
+
+```bash
+./scripts/snapshot.sh --out before-change-$(date -u +%Y%m%d).json
+# Make the change ...
+./scripts/snapshot.sh --out after-change-$(date -u +%Y%m%d).json
+# Diff to confirm only the intended state moved.
+```
+
+## Performance
+
+On the current Arcodange instance (5 invoices, 10 thirdparties, 1 template), the snapshot completes in **~2 seconds** with one HTTP call per top-level resource + N calls for per-id fetches. At ~30 thirdparties + ~100 invoices + ~10 templates, expect ~150 calls and ~10 s.
+
+## Out of scope
+
+- **Snapshotting bank statements** (Qonto / Wise CSV exports). Different data source — would be a sibling skill (`arcodange-bank-snapshot` or similar).
+- **Snapshotting Kubernetes state** of the ERP deployment. Sibling skill candidate (`arcodange-k8s-snapshot`).
+- **Schema migrations / drift in the Dolibarr DB itself.** That requires `dolibarr-postgres-readonly` or similar; out of scope here.