feat(core): preprocessing utilities — normalize_number, normalize_columns_map, decode_bytes (#411)

[Gabrymi93]

Sintesi

Nuovo modulo toolkit/core/normalize.py con utility di preprocessing centralizzate per normalizzare numeri in formato italiano, mappare colonne con regex e decodificare bytes con fallback multi-encoding.

Rimpiazza 13 copie identiche nei candidate di dataset-incubator (elezioni-*, iva-regionale).

Contesto collegato

Closes #411

Cosa cambia

• Bug fix
• Nuova funzionalità del motore
• Nuovo plugin sorgente
• Modifica contratto pubblico
• Refactor / performance
• Documentazione
• Dipendenze o CI

Impatto su contratti pubblici

Nessuno. Nuovo codice, nessuna modifica a funzioni esistenti.

Verifica

pytest tests/test_normalize.py -v

• pytest -m pure_unit passa (417 test)
• Nuovo file test tests/test_normalize.py (45 test, marker pure_unit)

Checklist PR

• Perimetro stretto: un modulo, tre funzioni, test
• Issue collegata (feat(core): utility preprocessing — normalize_number, decode_bytes, normalize_columns_map #411)
• Nessuna modifica a contratti esistenti

Cosa contiene

• normalize_number(val, *, strip_dot_zero, empty_values) -> str | None — normalizza numeri formato italiano (1.234,56 → 1234.56, gestisce *** / - / N.D. → None, convalida output con _looks_like_number)
• normalize_columns_map(header, col_map) -> (list[str], list[int]) — mappa colonne via regex con stripping di virgolette/whitespace
• decode_bytes(data, encodings) -> str — decodifica multi-encoding con cp1252 prima di iso-8859-1 (€ corretto)
• decode_csv_bytes(data) -> str — wrapper specializzato per CSV