anncsu-sdk 0.0.10.dev1__tar.gz → 0.0.10.dev3__tar.gz

{anncsu_sdk-0.0.10.dev1 → anncsu_sdk-0.0.10.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: anncsu-sdk
-Version: 0.0.10.dev1
+Version: 0.0.10.dev3
 Summary: ANNCSU Software Development Kit for API consumption
 Author-email: Francesco Bartoli <francesco.bartoli@geobeyond.it>
 License-File: LICENSE

{anncsu_sdk-0.0.10.dev1 → anncsu_sdk-0.0.10.dev3}/docs/CLI.md

@@ -1789,15 +1789,18 @@ anncsu pa accesso --prognazacc 28586543 --raw
 
 #### `anncsu pa accessi`
 
-List access points (civici) for a street. First searches for the street by municipality code and partial name, then lists all access points.
+List access points (civici) for a street. Resolve the street either by `--denom` (municipality code + base64 partial name) **or** directly by `--prognaz`, then list its access points.
 
 ```bash
-# List all access points for a street
+# List access points by street name (base64)
 anncsu pa accessi --codcom I501 --denom "VklBIFJPTUE="
 
 # Filter by partial civic number
 anncsu pa accessi --codcom I501 --denom "VklBIFJPTUE=" --accparz "1"
 
+# Target a specific odonimo directly by its national progressive
+anncsu pa accessi --codcom H501 --prognaz 920585 --accparz 95
+
 # Production with JSON output
 anncsu pa accessi --codcom I501 --denom "VklBIFJPTUE=" --production --json
 ```
@@ -1807,7 +1810,8 @@ anncsu pa accessi --codcom I501 --denom "VklBIFJPTUE=" --production --json
 | Option | Required | Description |
 |--------|----------|-------------|
 | `--codcom`, `-c` | Yes | Codice Belfiore del comune |
-| `--denom`, `-d` | Yes | Denominazione parziale dell'odonimo - base64 encoded |
+| `--denom`, `-d` | One of denom/prognaz | Denominazione parziale dell'odonimo - base64 encoded |
+| `--prognaz`, `-p` | One of denom/prognaz | Progressivo nazionale dell'odonimo (targets it directly) |
 | `--accparz`, `-a` | No | Valore parziale del civico (default: "1") |
 | `--validation/--production` | No | Environment (default: validation) |
 | `--token-endpoint`, `-e` | No | PDND token endpoint URL |
@@ -1816,6 +1820,10 @@ anncsu pa accessi --codcom I501 --denom "VklBIFJPTUE=" --production --json
 | `--json` | No | Output as JSON |
 | `--raw` | No | Print raw API responses to stderr (odonimo + accessi) |
 
+> **`--denom` is a substring search and can be ambiguous.** E.g. `--denom` for "taranto" matches both `VIA NINO TARANTO` and `VIA TARANTO`. When more than one odonimo matches, the command does **not** silently pick the first: it lists every candidate with its `--prognaz` and exits, so you can re-run targeting the exact one. `--denom` and `--prognaz` are mutually exclusive; provide exactly one.
+
+> **`--accparz` is a substring match on the civico** (not a prefix): `--accparz 9` returns 9, 19, 29, … 91, 97. To list *all* accessi you currently have to union several `accparz` values (e.g. `0`–`9`) and de-duplicate by `prognazacc` — the API has no "list all" wildcard. The esponente comes back in the `Esp.` column: civico 95 may yield three rows (95, 95/A, 95/D), each a distinct `prognazacc`.
+
 **Output columns:** Prog. Naz. Acc., Civico, Esp., Specif., Metrico, Coord X, Coord Y, Quota, Metodo
 
 **JSON output example:**
@@ -2261,6 +2269,7 @@ Options:
 - `--prognaz, -p` - Progressivo nazionale (required unless `--auto-resolve`)
 - `--auto-resolve` / `--denom` - Same as `update`
 - `--data-valid-amm` - Data **fine** validità amministrativa (formato `dd/MM/yyyy`)
+- `--dry-run-cascade` / `--cascade-accessi N` / `--cascade-sezione VALUE` - Verify whether deleting an odonimo cascades to its accessi (see [`--dry-run-cascade` flag](#anncsu-odonimo-delete--dry-run-cascade-flag))
 - Other shared options (`--token-endpoint`, `--server-url`, `--validation/--production`, `--no-verify-ssl`, `--json`, `--raw`, `--dry-run`)
 
 > **Note**: `delete` does NOT accept `--dug`, `--denom-*`, `--codice-comunale`, `--provv-*`, or `--prefettura-*` — Typer rejects them at parse time as unknown options because they have no meaning for a soppressione.
@@ -2375,6 +2384,80 @@ anncsu odonimo delete --codcom A062 --prognaz 9999999
 rm ~/.anncsu/dryrun_pending.json
 ```
 
+#### `anncsu odonimo delete` — `--dry-run-cascade` flag
+
+Answers a specific question empirically: **does deleting an odonimo automatically delete its linked accessi?** It runs a fully self-cleaning cycle on fictitious data, so real records are never touched.
+
+Cycle (default `--cascade-accessi 3`):
+
+| Step | Operation | API / e-service |
+|---|---|---|
+| 1 | `I` — insert a fictitious odonimo (`TEST SDK ...`, `dug=VIA`) | Odonimi |
+| 2 | `I × N` — attach `N` fictitious accessi, capturing each assigned `progr_civico` | Accessi |
+| 3 | confirm each accesso is present, by `progr_civico` (`accessi_before`) | PA Consultazione (`prognazacc`, single-accesso lookup) |
+| 4 | `S` — delete the odonimo | Odonimi |
+| 5 | recheck each accesso by `progr_civico` — survivors mean no cascade (`accessi_after`) | PA Consultazione (`prognazacc`) |
+| 6 | cleanup — delete any surviving accessi, then (if the odonimo S was refused) retry it | Accessi / Odonimi |
+
+> **Why per-`progr_civico` lookups (not the `elencoaccessiprog` listing)?** The listing endpoint requires an `accparz` *civico* filter and rejects a wildcard (`param accparz invalid`). The single-accesso `prognazacc` lookup is exact: a soppressed accesso responds *"non trovati accessi"*, which is the unambiguous "gone" signal.
+
+> **Empirical finding (UAT, 2026-06-01, comune H501)**: there is **no cascade**. The opposite is true — ANNCSU **refuses** to delete an odonimo that still has accessi, returning error **`320`** (`Controllo operazione: Operazione consentita per odonimi privi di accessi`). So the correct order is: delete **all** accessi first, then delete the odonimo. The dry-run reflects this: the first odonimo `S` is recorded as failed in `odonimo_delete` (the finding), then after deleting the accessi it retries the `S` and records the result in `odonimo_deleted_after_cleanup`.
+
+The verdict is reported in `cascade_confirmed`:
+
+- `true` — accessi existed before and **zero** survive ⇒ deletion cascades to accessi.
+- `false` — accessi **survived** the odonimo deletion (the dry-run cleans up the survivors for you).
+- `null` — could not be determined (e.g. no accesso was confirmed present before the delete — see the consistency caveat below).
+
+Options:
+
+- `--dry-run-cascade` - enable the cascade verification (ignores `--prognaz`/`--auto-resolve`).
+- `--cascade-accessi N` - how many fictitious accessi to attach (default `3`, must be ≥ 1). Reproduces the "odonimo with N accessi" scenario; one accesso is enough to detect cascade, more verify that *all* are removed.
+- `--cascade-sezione VALUE` - **required**. The `sezione_censimento` for the fictitious accessi. It must be a census section that **really exists in `--codcom`** — the server rejects unknown sections with error 100 (`Sezione di censimento: X non presente nel Comune`). The PA API does **not** expose it, so it cannot be auto-discovered. Use the ISTAT `SEZ21_ID` (`PROCOM + SEZ`, e.g. **`580911010001`** for Roma/`H501`).
+
+```bash
+# Roma (H501): 3 fake accessi with a known-valid census section.
+# --no-verify-ssl is normally needed on UAT (self-signed cert chain).
+anncsu odonimo delete --codcom H501 --dry-run-cascade \
+    --cascade-sezione 580911010001 --no-verify-ssl --json
+
+# Reproduce a specific scenario with 5 accessi
+anncsu odonimo delete --codcom H501 --dry-run-cascade --cascade-accessi 5 \
+    --cascade-sezione 580911010001 --no-verify-ssl --json
+```
+
+JSON output:
+
+```json
+{
+  "success": true,
+  "fake_denom": "TEST SDK 20260601150301-3f8a1b2c",
+  "fake_prognaz": "9999995",
+  "requested_accessi": 3,
+  "odonimo_insert": { "success": true, "tipo_operazione": "I", "esito": "0", "...": "..." },
+  "accessi_inserted": 3,
+  "accessi_progr_civici": ["35055664", "35055665", "35055666"],
+  "sezione_censimento": "580911010001",
+  "accessi_before": 3,
+  "odonimo_delete": { "success": false, "tipo_operazione": "S", "messaggio": "...codice 320...", "...": "..." },
+  "odonimo_deleted_after_cleanup": true,
+  "accessi_after": 3,
+  "cascade_confirmed": false,
+  "cleanup_accessi_deleted": 3,
+  "cleanup_failed": false,
+  "pending_log_path": "/Users/me/.anncsu/dryrun_pending.json",
+  "error_message": null
+}
+```
+
+The example above shows the **observed UAT behaviour** (no cascade): the first `odonimo_delete` is refused (error 320), the 3 accessi are cleaned up, and `odonimo_deleted_after_cleanup: true` confirms the odonimo was then removed. On a hypothetical cascade-enabled server you would instead see `odonimo_delete.success: true`, `accessi_after: 0`, `cascade_confirmed: true`, and `odonimo_deleted_after_cleanup: null` (no retry needed).
+
+> **Requires three purposes/e-services**: the cascade dry-run authenticates against the **Odonimi** (`I`/`S`), **Accessi** (`I`/`S`), and **PA Consultazione** (lookups) e-services. All three `PDND_PURPOSE_ID_*` must be configured. The Accessi/Odonimi server URLs are auto-corrected from the PDND voucher audience.
+
+> **PA eventual consistency caveat**: `accessi_before`/`accessi_after` are read from the PA Consultazione API, a separate read store that may lag behind the aggiornamento e-services. Only accessi the PA **confirms present before** the delete are tracked, so PA lag cannot produce a false `cascade_confirmed: true`. If PA had not yet indexed the inserts, `accessi_before` is `0` and the verdict is `null` — re-run after a moment.
+
+> **`success` vs `cascade_confirmed`**: `success` means the verification cycle ran end-to-end and left the environment clean. `cascade_confirmed` is the *finding* — `false` is a perfectly successful run that simply discovered there is no cascade.
+
 #### `anncsu odonimo update/delete` — `--auto-resolve` flag
 
 `update` and `delete` both require `--prognaz` to identify the target odonimo. As an alternative, pass `--auto-resolve` together with `--denom` (base64-encoded denomination) to have the CLI look up the `prognaz` automatically via PA API.

{anncsu_sdk-0.0.10.dev1 → anncsu_sdk-0.0.10.dev3}/docs/sdk-pa.md

@@ -178,16 +178,36 @@ if result.res == "OK":
 else:
     print(f"Odonimo non trovato")
 
-# 5. Elenco accessi per l'odonimo
+# 5. Elenco accessi per l'odonimo.
+# NB: ``accparz`` è OBBLIGATORIO (match per sottostringa sul civico) — non
+# esiste un valore "tutti". Vedi la nota sotto.
 accessi = sdk.queryparam.elenco_accessi_get_query_param(
     codcom=codcom,
     denom=denom,
+    accparz="1",  # es. tutti i civici che contengono "1"
 )
 
 for accesso in accessi.data:
-    print(f"Civico: {accesso.civico}, Coordinate: ({accesso.coord_x}, {accesso.coord_y})")
+    # L'esponente torna nel campo dedicato ``esp`` (civico e esponente sono
+    # separati): es. civico="95", esp="A" → 95/A.
+    print(
+        f"Civico: {accesso.civico}{('/' + accesso.esp) if accesso.esp else ''}, "
+        f"Coordinate: ({accesso.coord_x}, {accesso.coord_y})"
+    )
 ```
 
+> **`accparz` è obbligatorio ed è un match per sottostringa** (non prefisso): `accparz="9"`
+> ritorna `9, 19, 29, …, 91, 97` (tutti i civici che *contengono* "9"). **Non esiste un
+> wildcard "elenca tutti"**: per ottenere l'elenco completo bisogna unire più valori di
+> `accparz` (es. `"0"`–`"9"`) e deduplicare per `prognazacc`. Lo stesso vale per
+> `elenco_accessi_prog` (per `prognaz`).
+>
+> **Esponente / specificità**: un accesso è identificato da `civico` (numero) + `esp`
+> (esponente) + `specif`. Più accessi possono condividere lo stesso `civico` con `esp`
+> diversi → `prognazacc` distinti, **tutti** restituiti dalla stessa `accparz`. Es. su
+> VIA TARANTO (H501, prognaz `920585`) il civico `95` ritorna tre accessi: `95`, `95/A`,
+> `95/D`.
+
 ## Gestione Errori
 
 ```python