fix: keep Peru geolocation on ubigeo, not Google CPN

[kaio-donadelli]

What is the purpose of this pull request?

Stop Checkout from emitting Google's 5-digit Peru CPN (11701) when stores ship against 6-digit ubigeos in PER.ts (LOC-21884 / Zendesk #1290373).

Summary

• Do not map Google postal_code for Peru; derive ubigeo from department/province/district
• Normalize Google level prefixes and accents so matching works outside Lima
• Refresh Peru ubigeo data from INEI 2025; share hierarchy lookup options with BOL/CHL/COL/CRI

Tests

• yarn --cwd react jest country/__tests__/PER.test.ts
• Full suite: 230 passed

Spec

• specs/per-geolocation-ubigeo-postal-code.md (in this PR)

[vtex-io-ci-cd]

Hi! I'm VTEX IO CI/CD Bot and I'll be helping you to publish your app! 🤖

Please select which version do you want to release:

• Patch (backwards-compatible bug fixes)

• Minor (backwards-compatible functionality)

• Major (incompatible API changes)

And then you just need to merge your PR when you are ready! There is no need to create a release commit/tag.

• No thanks, I would rather do it manually 😞

[vtex-pr-sentinel]

✅ SDD Check — resolved automatically

A spec was found in this PR's files, so this question no longer applies. No action needed.

[evertonstrack]

Fix bacana, e a cobertura de testes ficou boa — os casos de Chincha Alta / acento / Callao / INEI-2025 são exatamente o que eu esperaria ver. Dois pontos que vale discutir antes do merge:

1. Esse bug provavelmente não é específico do Peru — o createPostalCodeFromHierarchyHandler tem o mesmo problema de match exato para BOL/CHL/COL/CRI

O createPostalCodeFromHierarchyHandler (que você extraiu no f649e77 pra unificar BOL, CHL, COL, CRI e PER) faz um lookup por match exato de string, sem normalização de prefixo/acento. BOL.ts, CHL.ts, COL.ts e CRI.ts ainda mapeiam o postal_code do Google diretamente (types: ['postal_code']) e dependem desse handler pra sobrescrever o valor — então, sempre que o Google prefixa o nome de um nível (ex: "Provincia de X", "Región de Y") ou usa uma variante acentuada que não bate byte a byte com o countryData, deveria ocorrer a mesma falha do #1290373: o lookup por hierarquia falha silenciosamente e o código bruto do Google vaza.

Este PR tira o Peru desse helper compartilhado e reimplementa o fix (stripGeoLevelPrefix, normalizeGeoName, findCountryDataKey, o fallback multi-nível) inteiramente dentro de PER.ts. Isso resolve o vazamento pro Peru, mas:

• Desfaz a consolidação do f649e77 pra um dos cinco países.
• BOL/CHL/COL/CRI ficam com o mesmo bug latente, e quem for corrigir isso depois provavelmente vai reinventar essa mesma lógica de normalização.

Vi que você chegou a tirar o Peru do helper compartilhado pra fazer esse fix isolado — será que não faria sentido um caminho de generalizar isso no próprio createPostalCodeFromHierarchyHandler (por exemplo, um modo de match normalizado opcional), pra que os cinco países se beneficiem? Ou você acha mais seguro ir no safe agora (fix isolado só pro Peru, que já resolve o chamado urgente) e deixar a generalização pra depois? Pode ser que eu esteja errado se houver um motivo pro Peru precisar divergir de verdade (ex: a inferência de department / fallback cross-department realmente é específica do Peru) — só quero garantir que a gente não está se comprometendo a resolver esse mesmo chamado mais quatro vezes.

2. Menor: o fallback cross-department descarta um department já resolvido

No handler de postalCode, quando stateKey/cityKey são resolvidos mas neighborhoodKey não, o fallback busca em todos os departments por um par province+district ao invés de tentar primeiro dentro do department já resolvido:

if (!neighborhoodKey) {
  const states = Object.keys(countryData)

  for (let i = 0; i < states.length; i++) {
    const state = states[i]
    const city = findCountryDataKey(countryData[state], address.city.value)
    ...

Hoje isso é seguro — conferi o PER.json e não há nomes de province duplicados entre departments, então a busca global não consegue pegar um district do department errado. Mas é uma invariante implícita do dataset, não algo garantido pelo código — uma futura atualização do INEI que introduza uma province com o mesmo nome em dois departments poderia fazer isso retornar silenciosamente um ubigeo errado, em vez do fallback seguro de "deixar postalCode vazio" que é a base da spec.

Vi que você já tratou o caso do Callao/Lima com esse fallback global — será que não faria sentido restringir a busca pra tentar primeiro dentro do department já resolvido, e só abrir pra todos os departments se isso falhar? Ou você acha mais seguro manter como está (o fallback global direto) por agora, já que hoje não há colisão de nomes nos dados?

3. Precisamos replicar isso pra branch 4.x?

Dei uma olhada na branch 4.x (linha de release paralela, já em v4.29.x) e o react/country/PER.js de lá ainda está no formato antigo: mesmo createPostalCodeFromHierarchyHandler sem normalização, mapeando postal_code do Google direto. Ou seja, o mesmo vazamento de CPN reportado no #1290373 provavelmente também acontece lá (o typo do "Mi Perú" não se aplica — nessa branch já está 070107 por outro motivo).

Não sei se 4.x ainda recebe correções de bug ou se está em manutenção mínima — você sabe se precisamos abrir um PR equivalente pra lá, ou dá pra deixar pra quando/se alguém migrar pra essa branch?

---

Nenhum dos três pontos deveria bloquear o merge sozinho (principalmente o item 2) — o principal é confirmar que o item 1 foi uma escolha consciente e não algo que vai passar despercebido pros outros países, e entender se o item 3 precisa de ação agora.

[kaio-donadelli]

1. Helper compartilhado: generalizei o createPostalCodeFromHierarchyHandler com normalizeKeys / crossFirstLevelFallback / canonicalizeLevels. PER usa os três e continua sem mapear o postal_code do Google (CPN ≠ ubigeo). BOL/CHL/COL/CRI já optaram em normalizeKeys: true.
2. Fallback cross-dept: o scan global só roda depois de tentar o first-level já resolvido.
3. 4.x: vamos portar depois, quando estiver tudo acertado aqui. a 4,x ainda é mantida e recebe correções/atualizações de país.

[sonar-workflows]

Quality Gate passed

Issues

• 0 New Issues
• 5 Fixed Issues
• 0 Accepted Issues

Measures

• 0 Security Hotspots
• 80.60% Coverage (76.00% Estimated after merge)
• 2.70% Duplicated Code (21.50% Estimated after merge)

Project ID: address-form

View in SonarQube