anncsu-sdk 0.0.9.dev28__tar.gz → 0.0.9.dev30__tar.gz

{anncsu_sdk-0.0.9.dev28 → anncsu_sdk-0.0.9.dev30}/PKG-INFO

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

{anncsu_sdk-0.0.9.dev28 → anncsu_sdk-0.0.9.dev30}/docs/CLI.md

@@ -877,22 +877,40 @@ Original coordinates to restore manually:
   metodo: 4
 ```
 
-**Handling Access Points Without Coordinates**: When an access point has no existing coordinates (X, Y, and metodo are all empty), the dry-run uses temporary test coordinates for the update test:
+**Safety skip on legacy NULL `metodo`**: a dry-run **guarantees zero changes** in production. If the target record has an original `metodo` that is not one of the valid OAS values (`"1"`, `"2"`, `"3"`, `"4"`) — typically legacy data imported before the validation rule was enforced — the restore step would fail (ANNCSU error 130, *"Il metodo deve essere obbligatorio e compreso tra 1 e 4"*) and the test update would remain committed permanently.
 
-| Field | Test Value | Description |
-|-------|------------|-------------|
-| X | `12.4922309` | Longitude (Roma Colosseo area) |
-| Y | `41.8902102` | Latitude (Roma Colosseo area) |
-| Z | `null` | Altitude not specified |
-| metodo | `4` | "Altro" (other method) |
+To preserve the dry-run guarantee, the CLI **skips** such records **before any API write call**:
 
-After the test update, the command restores the original empty state. A note is displayed when test coordinates are used:
+- No `gestionecoordinate` request is sent.
+- A warning is printed (or, with `--json`, a structured payload with `"skipped": true` and `"skip_reason": "original_metodo_null_or_invalid"`).
+- Exit code is `0` (the dry-run completed as designed, the record was simply not testable).
 
+JSON output when a record is skipped:
+
+```json
+{
+  "success": true,
+  "original_coordinates": {
+    "prognazacc": "5256880",
+    "codcom": "H501",
+    "civico": "1",
+    "coord_x": null,
+    "coord_y": null,
+    "quota": null,
+    "metodo": null
+  },
+  "test_update": null,
+  "restore": null,
+  "restore_failed": false,
+  "skipped": true,
+  "skip_reason": "original_metodo_null_or_invalid",
+  "error_message": null
+}
 ```
-Note: Access has no coordinates. Using test coordinates (will be cleared after test).
-```
 
-**Note**: If the API does not allow restoring an access point without valid coordinates, the restore operation may fail. In this case, manual intervention may be needed.
+> **Removed in this release**: the prior fallback that injected Roma Colosseo coordinates (`X=12.4922309`, `Y=41.8902102`, `metodo=4`) when the access had no original coordinates. That fallback violated the "dry-run = zero changes" guarantee because the eventual restore to `metodo=NULL` could not succeed. Skip is now the only behaviour.
+
+**Warning Handling (legacy)**: if a restore fails for any *other* reason (e.g. transient network error during the round-trip on a record that did pass the safety check), the command will still display original values for manual recovery — same as before.
 
 ---
 
@@ -1225,12 +1243,13 @@ Dry-Run Results:
 ┌──────────────────────┬───────┐
 │ Metric               │ Value │
 ├──────────────────────┼───────┤
-│ Total tested         │ 10    │
-│ Updates succeeded    │ 10    │
+│ Total tested         │ 8     │
+│ Updates succeeded    │ 8     │
 │ Updates failed       │ 0     │
-│ Restores succeeded   │ 10    │
+│ Restores succeeded   │ 8     │
 │ Restores failed      │ 0     │
 │ Lookup failures      │ 0     │
+│ Metodo NULL skipped  │ 2     │
 └──────────────────────┴───────┘
 ```
 
@@ -1238,12 +1257,13 @@ JSON output:
 ```json
 {
   "run_id": "abc123-def456",
-  "total_tested": 10,
-  "updates_succeeded": 8,
+  "total_tested": 8,
+  "updates_succeeded": 6,
   "updates_failed": 2,
-  "restores_succeeded": 8,
+  "restores_succeeded": 6,
   "restores_failed": 0,
   "lookup_failures": 0,
+  "metodo_null_skipped": 2,
   "errors": [
     {
       "row_id": 4,
@@ -1258,15 +1278,24 @@ JSON output:
       "operation": "dryrun_update",
       "http_status": 400,
       "error_detail": "body.richiesta.accesso.coordinate.x: Max length is '12', found '14'"
+    },
+    {
+      "row_id": 12,
+      "progr_civico": "33013500",
+      "operation": "dryrun_skip",
+      "http_status": null,
+      "error_detail": "original_metodo_null_or_invalid: None"
     }
   ]
 }
 ```
 
+**Safety skip on legacy NULL `metodo`**: same semantics as `coordinate dry-run` — records whose original `metodo` is not in `{"1", "2", "3", "4"}` are skipped **before any API write** to preserve the "dry-run = zero changes" guarantee. Counted in the dedicated `metodo_null_skipped` field; logged in `bulk_results` with `operation = 'dryrun_skip'` and `error_detail = 'original_metodo_null_or_invalid: <value>'`, so they appear in the **Error Details** section alongside other failures (distinguishable by the `operation` column).
+
 When there are errors, the text output also includes an **Error Details** table showing
 row, progr_civico, operation, HTTP status, and error message for each failed operation.
 
-Exits with code 1 if any restores failed (manual intervention may be needed).
+Exits with code 1 if any restores failed (manual intervention may be needed). Skipped records do NOT cause a non-zero exit.
 
 #### `anncsu coordinate bulk resume`
 
@@ -2236,6 +2265,8 @@ Options:
 
 > **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.
 
+> **Note on the S response shape**: the server response for a soppressione **does not** carry `esito` (it is `null`). The CLI infers success from the presence of `data_FINE` and `data_fine_valid_amm` in the `dati` payload — those mark the closure timestamp of the odonimo. When the CLI shows `Operation 'S' successful!`, this is the path that was taken. The behaviour is identical between the real `delete` and `delete --dry-run` since both call the same `_build_result` helper.
+
 #### `anncsu odonimo status`
 
 Check the status of the Odonimi API service:

{anncsu_sdk-0.0.9.dev28 → anncsu_sdk-0.0.9.dev30}/docs/sdk-odonimi.md

@@ -199,6 +199,64 @@ L'operazione effettiva è determinata dal campo `Richiesta.tipo_operazione`:
 |--------|-------------|
 | `show_status` | Verifica stato del servizio |
 
+## Response shape (asimmetria fra I/R e S)
+
+Le tre operazioni **non** rispondono con la stessa forma. Verificato empiricamente su UAT 2026-05-25.
+
+### I e R — `esito` valorizzato
+
+```json
+{
+  "idRichiesta": "316768",
+  "esito": "0",
+  "messaggio": "OK",
+  "dati": [{"codcom": "H501", "progr_nazionale": "1342677", ...}]
+}
+```
+
+Detection di successo: `esito == "0"`.
+
+### S — `esito` omesso, marker `data_FINE`
+
+```json
+{
+  "idRichiesta": "316775",
+  "dati": [{
+    "codcom": "H501",
+    "progr_nazionale": "1342672",
+    "dug": "VIA",
+    "denom_delibera": "TEST SDK INSERT 20260525",
+    "data_inizio": "25/05/2026",
+    "data_FINE": "25/05/2026",
+    "data_ini_valid_amm": "25/05/2026",
+    "data_fine_valid_amm": "25/05/2026"
+  }]
+}
+```
+
+`esito` e `messaggio` sono assenti / `null`. Il marker di successo per S è la presenza di `data_FINE` (alias Speakeasy: `data_fine`) o di `data_fine_valid_amm` nel primo elemento di `dati`.
+
+### Detection lato client (programmatic)
+
+Se usi l'SDK direttamente, replica questo pattern (è esattamente quello che usa la CLI `_build_result`):
+
+```python
+def is_success(response, tipo_operazione: str) -> bool:
+    esito = getattr(response, "esito", None)
+    dati = getattr(response, "dati", []) or []
+    if esito is not None:
+        return esito == "0"
+    if tipo_operazione == "S" and dati:
+        first = dati[0]
+        return bool(
+            getattr(first, "data_fine", None)              # alias per data_FINE
+            or getattr(first, "data_fine_valid_amm", None)
+        )
+    return False
+```
+
+Una check ingenua `esito == "0"` produce un **false-negative** sulle S che vanno a buon fine — è una causa nota di errori in codice cliente.
+
 ## Validazione Odonimo
 
 L'SDK fornisce un modello `ValidatedOdonimo` con validazione delle business rules ANNCSU. Va sempre usato prima della chiamata API per intercettare errori a livello locale.

{anncsu_sdk-0.0.9.dev28 → anncsu_sdk-0.0.9.dev30}/src/anncsu/cli/commands/bulk.py

@@ -572,6 +572,7 @@ def bulk_dry_run(
                     "restores_succeeded": dry_result.restores_succeeded,
                     "restores_failed": dry_result.restores_failed,
                     "lookup_failures": dry_result.lookup_failures,
+                    "metodo_null_skipped": dry_result.metodo_null_skipped,
                     "errors": [
                         {
                             "row_id": e[0],
@@ -605,6 +606,10 @@ def bulk_dry_run(
                     "Restores failed", f"[red]{dry_result.restores_failed}[/red]"
                 )
                 table.add_row("Lookup failures", str(dry_result.lookup_failures))
+                table.add_row(
+                    "Metodo NULL skipped",
+                    f"[yellow]{dry_result.metodo_null_skipped}[/yellow]",
+                )
                 console.print(table)
 
                 if errors:

{anncsu_sdk-0.0.9.dev28 → anncsu_sdk-0.0.9.dev30}/src/anncsu/cli/commands/coordinate.py

@@ -40,6 +40,7 @@ from anncsu.common.modi import AuditContext, ModIConfig
 from anncsu.common.security import Security as PASecurity
 from anncsu.common.session import get_config_dir
 from anncsu.coordinate import AnncsuCoordinate
+from anncsu.coordinate.bulk.dryrun import _is_safely_restorable
 from anncsu.coordinate.models import Accesso, Coordinate, Richiesta, Security
 from anncsu.coordinate.models.validated import ValidatedRispostaOperazione
 from anncsu.pa import AnncsuConsultazione
@@ -829,6 +830,32 @@ def dry_run(
         console.print(f"  Quota: {original.quota or 'N/A'}")
         console.print(f"  Metodo: {original.metodo or 'N/A'}\n")
 
+    # Pre-flight safety check: skip records whose original ``metodo`` is not
+    # one of the valid OAS values (``"1".."4"``). For such legacy records the
+    # update would succeed but the restore would fail with ANNCSU code 130,
+    # leaving the production data permanently overwritten. The dry-run
+    # guarantees "zero changes", so we bail out before any API write.
+    if not _is_safely_restorable(original.metodo):
+        if not json_output:
+            console.print(
+                "[yellow]Skipped:[/yellow] original ``metodo`` is "
+                f"{original.metodo!r}, which is not a valid restorable value "
+                "(expected '1', '2', '3', or '4'). No update or restore was "
+                "attempted to preserve the dry-run guarantee.\n"
+            )
+        skip_result = DryRunResult(
+            success=True,
+            original_coordinates=original,
+            test_update=None,
+            restore=None,
+            restore_failed=False,
+            skipped=True,
+            skip_reason="original_metodo_null_or_invalid",
+        )
+        if json_output:
+            print(skip_result.model_dump_json(indent=2))
+        return
+
     # Step 2: Perform test update
     if not json_output:
         console.print("[bold]Step 2:[/bold] Performing test update...\n")
@@ -841,31 +868,13 @@ def dry_run(
         modi_audience=coord_server,
     )
 
-    # Check if access has existing coordinates
-    has_coordinates = original.coord_x and original.coord_y and original.metodo
-
-    if has_coordinates:
-        # Use existing coordinates for test
-        test_coordinate = Coordinate(
-            x=original.coord_x,
-            y=original.coord_y,
-            z=original.quota,
-            metodo=original.metodo,
-        )
-    else:
-        # Access has no coordinates - use test values (Roma Colosseo area)
-        # These will be restored to empty after the test
-        if not json_output:
-            console.print(
-                "[yellow]Note:[/yellow] Access has no coordinates. "
-                "Using test coordinates (will be cleared after test).\n"
-            )
-        test_coordinate = Coordinate(
-            x="12.4922309",  # Roma - Colosseo longitude
-            y="41.8902102",  # Roma - Colosseo latitude
-            z=None,
-            metodo="4",  # Metodo 4 = Altro
-        )
+    # Use the original coordinates as test payload (round-trip).
+    test_coordinate = Coordinate(
+        x=original.coord_x,
+        y=original.coord_y,
+        z=original.quota,
+        metodo=original.metodo,
+    )
 
     test_richiesta = Richiesta(
         accesso=Accesso(

{anncsu_sdk-0.0.9.dev28 → anncsu_sdk-0.0.9.dev30}/src/anncsu/cli/commands/odonimo.py

@@ -972,17 +972,8 @@ def _execute_operation(
     if raw_output:
         _print_raw(response)
 
-    esito = getattr(response, "esito", None)
-    success = esito == "0"
-
-    result = OdonimoOperationResult(
-        success=success,
-        tipo_operazione=tipo_operazione,
-        id_richiesta=getattr(response, "id_richiesta", None),
-        esito=esito,
-        messaggio=getattr(response, "messaggio", None),
-        dati_count=len(getattr(response, "dati", []) or []),
-    )
+    result = _build_result(response, tipo_operazione)
+    success = result.success
 
     if json_output:
         print(result.model_dump_json(indent=2))

{anncsu_sdk-0.0.9.dev28 → anncsu_sdk-0.0.9.dev30}/src/anncsu/cli/models.py

@@ -324,7 +324,13 @@ class DryRunResult(BaseModel):
     original_coordinates: OriginalCoordinates = Field(
         description="Original coordinates before the test"
     )
-    test_update: CoordinateUpdateResult = Field(description="Result of the test update")
+    test_update: CoordinateUpdateResult | None = Field(
+        default=None,
+        description=(
+            "Result of the test update. ``None`` when the dry-run was skipped "
+            "(see ``skipped`` / ``skip_reason``) because no API write was attempted."
+        ),
+    )
     restore: CoordinateUpdateResult | None = Field(
         default=None, description="Result of the restore operation"
     )
@@ -332,6 +338,20 @@ class DryRunResult(BaseModel):
         default=False,
         description="Whether restore failed (requires manual intervention)",
     )
+    skipped: bool = Field(
+        default=False,
+        description=(
+            "Whether the dry-run was skipped before any API write because the "
+            "original record cannot be safely restored (e.g. legacy NULL metodo)."
+        ),
+    )
+    skip_reason: str | None = Field(
+        default=None,
+        description=(
+            "Machine-readable reason when ``skipped`` is ``True``. "
+            "Currently the only value is ``original_metodo_null_or_invalid``."
+        ),
+    )
     error_message: str | None = Field(
         default=None, description="Error message if operation failed"
     )

{anncsu_sdk-0.0.9.dev28 → anncsu_sdk-0.0.9.dev30}/src/anncsu/coordinate/bulk/dryrun.py

@@ -13,6 +13,7 @@ from anncsu.coordinate.models.richiestaoperazione import (
 )
 
 DEFAULT_MAX_RECORDS = 10
+VALID_METODO_VALUES = frozenset({"1", "2", "3", "4"})
 
 
 def _extract_http_error(e: Exception) -> tuple[int | None, str]:
@@ -22,6 +23,20 @@ def _extract_http_error(e: Exception) -> tuple[int | None, str]:
     return http_status, error_detail
 
 
+def _is_safely_restorable(metodo: str | None) -> bool:
+    """A record can be safely dry-run-tested only if its original ``metodo``
+    is one of the valid OAS values (``"1".."4"``).
+
+    Records with NULL / empty / out-of-range ``metodo`` are legacy data
+    that pre-date the current API validation rule. The update would
+    succeed (the new CSV value is valid) but the restore would fail with
+    ANNCSU error 130 — leaving the record permanently overwritten. To
+    preserve the "dry-run = zero changes" guarantee, such records are
+    skipped before any write call.
+    """
+    return metodo in VALID_METODO_VALUES
+
+
 @dataclass
 class DryRunResult:
     """Result of a bulk dry-run operation."""
@@ -33,6 +48,7 @@ class DryRunResult:
     restores_failed: int
     lookup_failures: int
     run_id: str
+    metodo_null_skipped: int = 0
 
 
 class BulkDryRunner:
@@ -77,6 +93,7 @@ class BulkDryRunner:
         restores_succeeded = 0
         restores_failed = 0
         lookup_failures = 0
+        metodo_null_skipped = 0
 
         # Track which rows were successfully updated (need restore)
         rows_to_restore: list[dict] = []
@@ -130,6 +147,21 @@ class BulkDryRunner:
                 original_metodo=lookup_data.metodo,
             )
 
+            # Step 2b: Pre-flight — skip records whose original metodo is not
+            # one of {"1","2","3","4"}. Otherwise the restore would fail
+            # (ANNCSU error 130) and leave the record permanently overwritten.
+            if not _is_safely_restorable(lookup_data.metodo):
+                metodo_null_skipped += 1
+                self.db.insert_result(
+                    row_id=row_id,
+                    run_id=self.run_id,
+                    operation="dryrun_skip",
+                    error_detail=(
+                        f"original_metodo_null_or_invalid: {lookup_data.metodo!r}"
+                    ),
+                )
+                continue
+
             # Step 3: Update with new coordinates from CSV
             try:
                 response = self._call_update(row)
@@ -216,6 +248,7 @@ class BulkDryRunner:
             restores_succeeded=restores_succeeded,
             restores_failed=restores_failed,
             lookup_failures=lookup_failures,
+            metodo_null_skipped=metodo_null_skipped,
             run_id=self.run_id,
         )