feat(postcodes/PA): 87 Correos de Panamá codes (#1039)

[dr5hn]

Summary

• Imports Panama's alphanumeric postal codes (1-letter + 4-digit format, e.g. B7241) for Can we add a postcode for this? #1039
• 100% state FK resolution across 10 of 14 CSC PA states
• Fixes PA regex ^\d{5}$ → ^[A-Z]\d{4}$ (old regex rejected 100% of legitimate codes)

Source

• viquezr-dev/codigos_postales — estafetas.geojson (3.3 MB)
• Upstream: Correos de Panamá publicly published delivery-zone polygons
• License: no formal LICENSE file (Tier 5 per Can we add a postcode for this? #1039 policy)

Coverage

• 87 estafetas with assigned codes (152 source features minus 65 'POR DEFINIR' placeholders)
• 10 provinces covered: Bocas del Toro, Coclé, Colón, Chiriquí, Darién, Herrera, Los Santos, Panamá, Veraguas, Panamá Oeste
• 4 comarcas (EM, KY, NB, NT) absent from source — all marked 'POR DEFINIR' or post-2020

State FK strategy

13-entry PROV_NOMB_TO_ISO2 maps source's uppercase Spanish names (with diacritics) to CSC iso2:

• KUNA_YALA → KY (older spelling — CSC name is "Guna")
• NGÄBE BUGLÉ → NB
• EMBERA → EM

Regex fix

Old: ^\d{5}$ (5-digit numeric — would reject 100% of actual Panama codes)
New: ^[A-Z]\d{4}$ / format @####

Centroid

Source ships MultiPolygon geometries (not centroids). Importer computes unweighted vertex mean — within ~1 km of strict area-weighted centroid for postal-zone-sized polygons.

Test plan

• python3 -m py_compile bin/scripts/sync/import_panama_postcodes.py
• All 87 codes match ^[A-Z]\d{4}$
• 100% state_id valid; state.country_id == 170; state_code == state.iso2
• No auto-managed fields (id, created_at, updated_at, flag)
• Idempotent merge (re-run produces no diff)

🤖 Generated with Claude Code

[github-actions]

CSC Validation Report

PR Format

• ✅ Description provided
• ✅ Data source linked
• ✅ Issue linked (recommended for data changes)
• ✅ Justification / context provided

Labels applied: data:countries, data:postcodes

Schema Validation (337 records)

Errors (blocking):

• ❌ contributions/countries/countries.json: Record 1 ("Afghanistan"): "id" must not be included (auto-managed)
• ❌ contributions/countries/countries.json: Record 1 ("Afghanistan"): "created_at" must not be included (auto-managed)
• ❌ contributions/countries/countries.json: Record 1 ("Afghanistan"): "updated_at" must not be included (auto-managed)
• ❌ contributions/countries/countries.json: Record 1 ("Afghanistan"): "flag" must not be included (auto-managed)
• ❌ contributions/countries/countries.json: Record 2 ("Aland Islands"): "id" must not be included (auto-managed)
• ❌ contributions/countries/countries.json: Record 2 ("Aland Islands"): "created_at" must not be included (auto-managed)
• ❌ contributions/countries/countries.json: Record 2 ("Aland Islands"): "updated_at" must not be included (auto-managed)
• ❌ contributions/countries/countries.json: Record 2 ("Aland Islands"): "flag" must not be included (auto-managed)
• ❌ contributions/countries/countries.json: Record 3 ("Albania"): "id" must not be included (auto-managed)
• ❌ contributions/countries/countries.json: Record 3 ("Albania"): "created_at" must not be included (auto-managed)
• ❌ contributions/countries/countries.json: Record 3 ("Albania"): "updated_at" must not be included (auto-managed)
• ❌ contributions/countries/countries.json: Record 3 ("Albania"): "flag" must not be included (auto-managed)
• ❌ contributions/countries/countries.json: Record 4 ("Algeria"): "id" must not be included (auto-managed)
• ❌ contributions/countries/countries.json: Record 4 ("Algeria"): "created_at" must not be included (auto-managed)
• ❌ contributions/countries/countries.json: Record 4 ("Algeria"): "updated_at" must not be included (auto-managed)
• ❌ contributions/countries/countries.json: Record 4 ("Algeria"): "flag" must not be included (auto-managed)
• ❌ contributions/countries/countries.json: Record 5 ("American Samoa"): "id" must not be included (auto-managed)
• ❌ contributions/countries/countries.json: Record 5 ("American Samoa"): "created_at" must not be included (auto-managed)
• ❌ contributions/countries/countries.json: Record 5 ("American Samoa"): "updated_at" must not be included (auto-managed)
• ❌ contributions/countries/countries.json: Record 5 ("American Samoa"): "flag" must not be included (auto-managed)
• ...and 980 more errors

Warnings:

• ⚠️ contributions/countries/countries.json: Record 1 ("Afghanistan"): unknown field "population"
• ⚠️ contributions/countries/countries.json: Record 1 ("Afghanistan"): unknown field "gdp"
• ⚠️ contributions/countries/countries.json: Record 1 ("Afghanistan"): unknown field "area_sq_km"
• ⚠️ contributions/countries/countries.json: Record 1 ("Afghanistan"): unknown field "postal_code_format"
• ⚠️ contributions/countries/countries.json: Record 1 ("Afghanistan"): unknown field "postal_code_regex"
• ⚠️ contributions/countries/countries.json: Record 2 ("Aland Islands"): unknown field "population"
• ⚠️ contributions/countries/countries.json: Record 2 ("Aland Islands"): unknown field "gdp"
• ⚠️ contributions/countries/countries.json: Record 2 ("Aland Islands"): unknown field "area_sq_km"
• ⚠️ contributions/countries/countries.json: Record 2 ("Aland Islands"): unknown field "postal_code_format"
• ⚠️ contributions/countries/countries.json: Record 2 ("Aland Islands"): unknown field "postal_code_regex"
• ...and 1240 more warnings

Cross-Reference Validation

✅ 174 reference(s) verified

Geo-Bounds Check

✅ All 87 coordinate(s) within expected country bounds

Duplicate Detection

• ⚠️ contributions/countries/countries.json: Record 1 ("Afghanistan") appears to be a duplicate of existing "Afghanistan" (id: 1, distance: 0.0km)
• ⚠️ contributions/countries/countries.json: Record 2 ("Aland Islands") appears to be a duplicate of existing "Aland Islands" (id: 2, distance: 0.0km)
• ⚠️ contributions/countries/countries.json: Record 3 ("Albania") appears to be a duplicate of existing "Albania" (id: 3, distance: 0.0km)
• ⚠️ contributions/countries/countries.json: Record 4 ("Algeria") appears to be a duplicate of existing "Algeria" (id: 4, distance: 0.0km)
• ⚠️ contributions/countries/countries.json: Record 5 ("American Samoa") appears to be a duplicate of existing "American Samoa" (id: 5, distance: 0.0km)
• ⚠️ contributions/countries/countries.json: Record 6 ("Andorra") appears to be a duplicate of existing "Andorra" (id: 6, distance: 0.0km)
• ⚠️ contributions/countries/countries.json: Record 7 ("Angola") appears to be a duplicate of existing "Angola" (id: 7, distance: 0.0km)
• ⚠️ contributions/countries/countries.json: Record 8 ("Anguilla") appears to be a duplicate of existing "Anguilla" (id: 8, distance: 0.0km)
• ⚠️ contributions/countries/countries.json: Record 9 ("Antarctica") appears to be a duplicate of existing "Antarctica" (id: 9, distance: 0.0km)
• ⚠️ contributions/countries/countries.json: Record 10 ("Antigua and Barbuda") appears to be a duplicate of existing "Antigua and Barbuda" (id: 10, distance: 0.0km)

Source URL Verification

✅ 2 source URL(s) accessible

---

❌ 1000 error(s), 1500 warning(s) | Status: Changes required

Please fix the errors above and push a new commit. Refer to our Contribution Guidelines for details.

[dr5hn]

Weekly data-quality review (2026-05-04)

Verdict: clean

Checks

• Schema: ✅ The only change to contributions/countries/countries.json is updating Panama's postal_code_format (##### → @####) and postal_code_regex (^(\d{5})$ → ^([A-Z]\d{4})$). No forbidden fields introduced. The 87 new records in contributions/postcodes/PA.json correctly omit id, flag, created_at, updated_at.
• FK integrity: ✅ All 87 postcode records resolve to valid PA states (per CI cross-reference pass).
• Coordinates: ✅ All 87 PA postcode centroids fall within Panama's bounding box (lat 7.2 → 9.65, lon −82.97 → −77.16).
• Wikidata: N/A.
• Naming convention: N/A (postcode data, not place names).

Note on CI "needs-changes" label

The 1,000 CI schema errors ("id" must not be included, "flag" must not be included, etc.) are false positives. The pr-validator checks every record in contributions/countries/countries.json, including the 249 untouched existing countries that legitimately carry id, created_at, updated_at, flag. This is a pre-existing validator limitation when countries.json is touched — the actual changes in this PR are correct. The needs-changes label can be removed by a maintainer once this is confirmed.

🤖 Automated weekly review — Claude (sonnet-4-6).

---

Generated by Claude Code