feat(write-skill): GED attach op — upload the source document onto its invoice (erp#43)
document-attach.sh uploads a source piece (the supplier's own PDF) onto an invoice's GED via POST /documents/upload — idempotent by (object, filename, sha256): before any POST the object's GED is listed and a same-named entry is downloaded back and sha256-compared. Identical → deduped no-op; different content → ABORT (refuse-never-repair, overwriteifexists always 0, never Dolibarr's overwrite flag). Read-back after upload: re-list + download + sha256-verify. Module-relative download paths are derived from the listing's fullname (supplier invoices carry an id-derived get_exdir prefix like 9/2/FAF2026013/…, so reconstruction would be wrong). Promote integration: new `attach` op in promote-plan/promote-apply (OP_SCRIPT), object_id resolvable via @ref and #supplierinvoice lookups; a relative `file` resolves against the manifest's directory (replay packs carry pdfs/ beside the manifest, gitignored — README documents the books@ re-fetch message ids). promote-plan prints each file's sha256 (or a loud MISSING) at review time. CLI: `arcodange sandbox attach`. Proof: offline case 12 in tests/run-tests.sh (upload body, dedupe, conflict abort, field refusal, manifest-relative resolution via stubbed /documents); live: manifest-C-ged-attach.json applied twice on the sandbox — run 1 four created, run 2 four deduped, one GED file per FAF2026010-013, stored sha256s equal to the re-fetched sources; tests/replay-idempotency.sh extended with an attach op (4 created → 4 deduped, ged_files count unchanged) and a live same-name/different-bytes abort verified. Closes erp#43 Co-Authored-By: Claude Fable 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01VRShc4QhLLU73FLHx9vskh
This commit is contained in:
Claude Fable 5
@@ -12,13 +12,17 @@ description: >-
|
||||
(thirdparty by exact name, supplier invoice by socid+ref_supplier, customer
|
||||
invoice by socid+date+total+line fingerprint, payment by invoice+amount+
|
||||
normalized transaction id; credit notes excepted, a follow-up), so replaying
|
||||
a manifest — even one that failed mid-run — is a no-op, never a duplicate. Every write goes through dol-write.sh,
|
||||
a manifest — even one that failed mid-run — is a no-op, never a duplicate.
|
||||
Also attaches source documents (the supplier's PDF) onto an invoice's GED
|
||||
(erp#43): upload via the Documents API, idempotent by (object, filename,
|
||||
sha256) — re-attach is a no-op, same name + different content aborts. Every write goes through dol-write.sh,
|
||||
which REFUSES any host that is not the sandbox — the structural guarantee
|
||||
(ADR-0003) that this skill can never mutate production.
|
||||
Use when the user asks to "create a thirdparty / supplier / client fiche",
|
||||
"compléter / mettre à jour la fiche client", "add a contact to a thirdparty",
|
||||
"saisir une facture", "record an invoice with lines", "enregistrer un règlement /
|
||||
paiement", or to rehearse a write before promoting it to prod. SKIP for production writes
|
||||
paiement", "attacher la pièce / le justificatif / le PDF à la facture",
|
||||
or to rehearse a write before promoting it to prod. SKIP for production writes
|
||||
(prod stays read-only via the `dolibarr` skill's `ai_agent` key; promotion is a
|
||||
separate, human-gated replay). Depends on the write-scoped `ai_agent_sandbox`
|
||||
Dolibarr user + its API key.
|
||||
@@ -232,6 +236,31 @@ exits 0 without writing. Otherwise POST `/contacts` → `{"id": <new>,
|
||||
`phone_perso`, `address`, `zip`, `town`, `country_id`, `note_public`,
|
||||
`note_private`. Unknown fields are refused, never dropped.
|
||||
|
||||
### 7 · Attach a source document (GED) — `scripts/document-attach.sh`
|
||||
|
||||
```sh
|
||||
echo '{"modulepart":"facture_fournisseur","ref":"FAF2026013",
|
||||
"file":"pdfs/F1045_ARCODANGE_2026-06-30.pdf"}' | scripts/document-attach.sh
|
||||
echo '{"modulepart":"facture","object_id":19,"file":"/abs/path/piece.pdf",
|
||||
"filename":"stored-name.pdf"}' | scripts/document-attach.sh
|
||||
```
|
||||
Uploads the **source piece** (the supplier's own PDF, a contract…) onto an
|
||||
invoice's GED directory via `POST /documents/upload` (base64 content,
|
||||
`overwriteifexists` always 0). `modulepart`: `facture`/`invoice` (customer) or
|
||||
`facture_fournisseur`/`invoice_supplier`/`supplier_invoice` (supplier). Address
|
||||
the invoice by `object_id` or by Dolibarr `ref` (both = cross-checked; a
|
||||
ref-only lookup matching 0 or 2+ aborts). `filename` defaults to the file's
|
||||
basename. Emits `{object_id, ref, modulepart, filename, sha256, size, deduped}`.
|
||||
|
||||
**Idempotent by (object, filename, sha256) — our own check, never Dolibarr's
|
||||
overwrite flag.** Before any POST the object's GED is listed
|
||||
(`GET /documents?modulepart=…&id=…`, where 404 on a proven-existing object means
|
||||
"no documents yet") and a same-named entry is **downloaded back and
|
||||
sha256-compared**: identical → `{"deduped": true}`, no upload; **different
|
||||
content ABORTS** — silently replacing a stored piece would rewrite evidence
|
||||
(refuse-never-repair). After an upload the file is re-listed, downloaded back
|
||||
and sha256-verified (read-back proof the GED holds exactly the bytes sent).
|
||||
|
||||
## Promote to prod (rehearse → review → replay)
|
||||
|
||||
The ADR-0003 capstone: take a change rehearsed in the sandbox and apply the **same
|
||||
@@ -240,7 +269,11 @@ array of write ops using **symbolic refs** (`@name`) instead of ids, so it is
|
||||
portable from sandbox to prod (an invoice references `@tp1`, the thirdparty created
|
||||
earlier in the run). See `examples/promote-manifest.json`. Op kinds: `thirdparty`,
|
||||
`thirdparty_update` (input: `socid` + `fields`), `contact`, `invoice`, `creditnote`,
|
||||
`payment` — each mapping to its workflow script above.
|
||||
`payment`, `attach` — each mapping to its workflow script above. An `attach` op's
|
||||
relative `file` path resolves against the **manifest's directory** (the manifest
|
||||
is the portable unit: a replay pack carries its `pdfs/` beside it), and
|
||||
`promote-plan` prints the file's sha256 — or a loud MISSING warning — at review
|
||||
time so the content is pinned before any apply.
|
||||
|
||||
```sh
|
||||
scripts/promote-plan.sh change.json # 1. human-readable review
|
||||
@@ -266,7 +299,8 @@ ops answer `deduped=true`, the rest execute. `promote-apply` marks each op
|
||||
(`OK — promote complete (1 created, 2 deduped)`), so an all-`deduped` second run
|
||||
is visible proof of a no-op. Live acceptance: `tests/replay-idempotency.sh`
|
||||
double-applies a self-contained manifest (thirdparty + supplier invoice +
|
||||
payment) on the sandbox and asserts run 2 dedupes all ops with zero new rows.
|
||||
payment + GED attach) on the sandbox and asserts run 2 dedupes all ops with
|
||||
zero new rows and zero new GED files.
|
||||
|
||||
A manifest value can reference another entity two ways, both resolved against the
|
||||
**target** so the same file is portable sandbox↔prod:
|
||||
@@ -313,13 +347,22 @@ sandbox KissMetrics on `--target sandbox` and the prod one on `--target prod`.
|
||||
(ambiguous or role-mismatch aborts), supplier invoice by (socid, ref_supplier)
|
||||
(total mismatch aborts), customer invoice by (socid, date, total, line
|
||||
fingerprint), payment by (invoice, amount, normalized tx id), contact by
|
||||
(socid, email) then (socid, lastname+firstname) — each answering
|
||||
(socid, email) then (socid, lastname+firstname), GED attach by (object,
|
||||
filename, sha256) — each answering
|
||||
`{"deduped": true}` instead of minting a duplicate, so replaying a manifest is
|
||||
always safe. Two holes: a **payment without a `transaction_id`** has no
|
||||
dedupe key and WILL double-pay on a replay, and **`creditnote-create.sh` does
|
||||
not dedupe yet** (supplier-avoir parity follow-up) — do not replay a manifest
|
||||
containing a creditnote op past a mid-run failure. Offline proof:
|
||||
`tests/run-tests.sh`; live double-apply proof: `tests/replay-idempotency.sh`.
|
||||
- **GED attach paths carry a get_exdir prefix for supplier invoices.** A
|
||||
supplier-invoice document lives at `fournisseur/facture/<x>/<y>/<REF>/<file>`
|
||||
(the `<x>/<y>` split derives from the object id), so `/documents/download`
|
||||
needs `0/3/FAF2026014/file.pdf`, not `FAF2026014/file.pdf`. `document-attach.sh`
|
||||
derives the module-relative path from the listing's `fullname` (substring
|
||||
after the last `/facture/`) — never reconstructs it. Customer invoices have
|
||||
no prefix (`facture/<REF>/<file>`). Upload answers the bare filename as a
|
||||
JSON string; the script verifies it and then read-back-verifies the sha256.
|
||||
- **A dedupe lookup that fails (non-404) aborts the op** — the scripts refuse to
|
||||
POST blind, because assuming "no match" on a 403/timeout is precisely how
|
||||
duplicates get minted (cf. the `voir_tous` ACL trap in the `dolibarr` skill:
|
||||
@@ -328,5 +371,5 @@ sandbox KissMetrics on `--target sandbox` and the prod one on `--target prod`.
|
||||
`soc2` (seen in WIP operator payloads) is not a Dolibarr field and the API
|
||||
would drop it silently — `contact-create.sh` refuses it with a pointer to
|
||||
`poste`.
|
||||
- **CLI:** all of these are also `arcodange sandbox {thirdparty|invoice|payment|creditnote|write}`
|
||||
- **CLI:** all of these are also `arcodange sandbox {thirdparty|invoice|payment|creditnote|attach|write}`
|
||||
(JSON on stdin) — `arcodange sandbox help` for the list.
|
||||
|
||||
Reference in New Issue
Block a user