arcodange-org/erp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request 'feat(bank-match): exact tx-id match pass (consumes payment transaction_id)' (#28) from claude/bank-match-exact-txid into main

Browse Source
This commit was merged in pull request #28.
This commit is contained in:
arcodange
2026-06-30 00:39:44 +02:00
parent 01e3eaac5e 4b17e5f22c
commit 0688e3d7fd
2 changed files with 42 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
.claude/skills/arcodange-bank-reco/SKILL.md
View File

@@ -175,7 +175,7 @@ V7 adds three improvements that reshape the output buckets:
| Bucket | Meaning | Counts toward exit-1? |
|---|---|---|
| **MATCHED** | Bank ↔ Dolibarr paired. Annotated with match kind: `[wire-ref]` (strong, via `--enrich`) or `[amt+date]` (loose). | No |
| **MATCHED** | Bank ↔ Dolibarr paired. Match kind: `[tx-id]` (exact — the payment's `transaction_id` equals the feed tx id; date-independent), `[wire-ref]` (strong, via `--enrich`), or `[amt+date]` (loose). | No |
| **INTERNAL** | Wise↔Qonto consolidations (5000€ moved between Arcodange's own accounts). | No |
| **AVOIR-NETTED** | Dolibarr AVC + FAC cancellation cycles paired and excluded (the bank only saw the net). | No |
| **BANK-ONLY — known patterns** | Bank movement with a `known-patterns.json` annotation. Intentional gap. | No |
@@ -185,6 +185,18 @@ V7 adds three improvements that reshape the output buckets:
Exit code 0 iff the two "real gap" buckets are empty.
### Matching priority — exact tx-id first
Matching runs in three passes, highest confidence first:
1. **`[tx-id]` (exact)** — a Dolibarr payment whose stored `num` (`llx_bank.num_chq`,
set from the règlement's `transaction_id`, see `dolibarr-sandbox-write`) equals the
feed transaction's own id. **Date-window-independent** — the id is proof, so it
matches even when bank settlement and Dolibarr saisie are weeks apart. Record
payments with their `transaction_id` and reconciliation becomes deterministic.
2. **`[wire-ref]` (strong)** — via `--enrich`, below.
3. **`[amt+date]` (loose)** — the fallback heuristic.
### `--enrich` — wire-reference strong matching
`bank-match.sh --enrich` fetches `/v1/transfers/{id}` for each Wise TRANSFER and reads the `reference` field (the wire memo from the sender, e.g. `FROM KISSMETRICS HOLDINGS INC FOR INVOICE FAC002CL0001002/ VENDOR:DEV`). When the reference contains a `FAC\d+(CL\d+)?` pattern matching a Dolibarr customer invoice, that pairing takes precedence over the loose date+amount match. Only the strong-matched ones get `[wire-ref]`; the rest fall through to `[amt+date]`. Cost: 1 extra HTTP call per Wise transfer.

35
.claude/skills/arcodange-bank-reco/scripts/bank-match.sh
View File

@@ -112,7 +112,10 @@ for t in (json.load(open(os.path.join(work,"qonto.json"))).get("transactions") o
amt = float(t.get("amount") or 0)
sign = "+" if t.get("side") == "credit" else "-"
label = t.get("label") or t.get("operation_type") or "-"
qonto_movs.append({"bank":"Qonto", "date":dt, "sign":sign, "amount":amt, "label":label[:40], "op":t.get("operation_type",""), "matched_dol":None, "matched_internal":False})
# feed_ids: the Qonto transaction's own id — exact-match key against a Dolibarr
# payment whose stored num (num_chq) is that id (set via payment transaction_id).
feed_ids = [str(t["id"])] if t.get("id") else []
qonto_movs.append({"bank":"Qonto", "date":dt, "sign":sign, "amount":amt, "label":label[:40], "op":t.get("operation_type",""), "feed_ids":feed_ids, "matched_dol":None, "matched_internal":False})
# 4b. Normalize Wise
wise_movs = []
@@ -129,7 +132,12 @@ for a in (json.load(open(os.path.join(work,"wise.json"))).get("activities") or [
title = strip(a.get("title") or "")[:40]
res = a.get("resource") or {}
resource_id = str(res.get("id")) if res.get("type") == "TRANSFER" else None
wise_movs.append({"bank":"Wise", "date":dt, "sign":sign, "amount":amt, "label":title, "op":typ, "matched_dol":None, "matched_internal":False, "wise_resource_id":resource_id, "wire_ref":""})
# feed_ids: the Wise activity id and (for transfers) the resource id — either
# may have been stored as the payment's transaction_id; match against both.
feed_ids = []
if a.get("id"): feed_ids.append(str(a["id"]))
if resource_id: feed_ids.append(resource_id)
wise_movs.append({"bank":"Wise", "date":dt, "sign":sign, "amount":amt, "label":title, "op":typ, "feed_ids":feed_ids, "matched_dol":None, "matched_internal":False, "wise_resource_id":resource_id, "wire_ref":""})
# 4b'. If --enrich, load per-transfer wire references and attach to Wise movs
if enrich:
@@ -165,6 +173,7 @@ for fn in os.listdir(os.path.join(work,"dol_pay")):
amt = float(p.get("amount") or 0)
dol_pays.append({"side":"customer", "ref":inv["ref"], "date":d, "amount":amt,
"fk_account":inv.get("fk_account"), "socid":inv.get("socid"),
"num": (p.get("num") or ""),
"matched_bank":None, "netted_against":None})
sup_by_id = {str(r["id"]): r for r in json.load(open(os.path.join(work,"dol_sup.json")))}
@@ -177,6 +186,7 @@ for fn in os.listdir(os.path.join(work,"dol_supay")):
amt = float(p.get("amount") or 0)
dol_pays.append({"side":"supplier", "ref":sup["ref"], "date":d, "amount":amt,
"fk_account":sup.get("fk_account"), "socid":sup.get("socid"),
"num": (p.get("num") or ""),
"matched_bank":None, "netted_against":None})
# 4d.1. AVOIR cycle netting: an AVC (credit note) for -X on socid S cancels out
@@ -204,12 +214,25 @@ for avc in avcs:
avc["netted_against"] = partner["ref"]
partner["netted_against"] = avc["ref"]
# 4e. Match — two-pass:
# 4e. Match — three-pass, highest confidence first:
# PASS 0 (exact) : a Dolibarr payment whose stored num (num_chq = the
# transaction_id recorded with the règlement) equals the feed
# transaction's own id. Date-window-independent — the id is proof.
# PASS 1 (strong) : Wise transfers with an --enrich'd wire reference containing
# a "FAC***" pattern try to match the Dolibarr invoice with
# that exact ref. This is the highest-confidence match.
# a "FAC***" pattern match the Dolibarr invoice with that ref.
# PASS 2 (loose) : remaining bank movements use the date+amount heuristic.
# Netted Dolibarr entries (avoir cycle) are excluded from both passes.
# Netted Dolibarr entries (avoir cycle) are excluded from all passes.
# Pass 0: exact match on the feed transaction id stored as the payment's num
# (num_chq = the transaction_id recorded with the règlement). Date-independent.
for m in [x for x in bank_movs if not x["matched_internal"] and not x["matched_dol"] and x.get("feed_ids")]:
fids = set(m["feed_ids"])
for p in dol_pays:
if (p["matched_bank"] is None and p["netted_against"] is None
and p.get("num") and str(p["num"]) in fids):
m["matched_dol"] = p; m["match_kind"] = "tx-id"
p["matched_bank"] = m
break
# Build customer ref -> dol payment index (only un-netted, un-matched entries)
ref_index = collections.defaultdict(list)