docs planning STATION_EV_INGESTOR_PLAN

Station and EV charger ingestor plan

Status: PLANNED (2026-11-03). Owner request:

1. Stations show the trade name (nome fantasia) as the main name and the legal name (razão social) as a secondary name. People recognise the sign at the forecourt, not the company's registered name.
2. Stations without an official ANP address must show a readable address in the mobile app. Today they show raw coordinates.
3. The ingestor maps every EV charger in Brazil that the open sources know, by cross-matching Open Charge Map (location, connectors, power, operators) with OpenStreetMap (fuel stations, chargers, geometry). This is Part B (EVC-xx). It runs after SNA-01..SNA-03 because it reuses the station names and the address formatter.

Part A task IDs: SNA-xx. One bounded task at a time, B-BR/BUC before behaviour, RED → GREEN → REFACTOR, append-only migrations with real-PostGIS tests, additive API changes only (older APKs stay in use).

1. Findings (origin/main, 2026-11-03)

Names:

• backend/internal/modules/directory/adapters/registry/stage.go parseRecord: DisplayName = RAZAO_SOCIAL. NOME_FANTASIA is an accepted header (policy.go) but never read.
• registry/api_official.go: DisplayName = razaoSocial; nomeFantasia (present in contracts/testdata/registry/registry-api-sample.json) is not parsed.
• registry/loadbatch.go (station-prep batches): DisplayName = business_name_normalized (the legal name). The 13-column ANP registry used by tools/station-prep has no trade-name column. anp_prices.rs (weekly survey) and the RFB establishment data already used by prepare_open_geocode both carry a trade name.
• directory_stations (000002) has only display_name; the public Station schema in contracts/openapi/v1.yaml exposes display_name and official.display_name ("Posto Central LTDA").
• The official price import (official/adapters/jobs/import.go) and the legacy offline RetailStation already prefer the trade name. Only the canonical directory path, which feeds server stations, map, portal and admin, shows the legal name.

Addresses:

• app/.../ui/stations/ServerStationDetailSheet.kt prints "%.5f, %.5f" (latitude, longitude) where an address should be. It never renders station.address.
• app/.../ui/map/MapDiscoveryViewModel.kt ServerStation.addressLabel() shows municipalityCode/state, which is an IBGE number such as 5103403/MT, as the marker subtitle.
• stage.go (registry CSV) keeps only municipio_ibge and uf. It drops LOGRADOURO, NUMERO, COMPLEMENTO, BAIRRO, CEP and MUNICIPIO.
• Address sources already present in the pipeline: ANP registry (CSV/API), RFB establishment by CNPJ, OSM addr:* tags on a matched POI, and IBGE CNEFE address points (address-point tier).

2. Business rules (write first as B-BR entries)

B-BR-STATION-NAME-01, name precedence. display_name is, in order:

1. an approved community display_name correction (000144);
2. the trade name, after normalisation;
3. the legal name.

legal_name is always the legal name from the official source, kept verbatim. The UI shows it as a secondary line only when it differs from display_name after case and whitespace normalisation. A trade name counts as absent when it is any of:

• empty or punctuation only;
• a placeholder (NAO POSSUI, SEM NOME, NAO INFORMADO, -, ., *; keep the list as tested data);
• the CNPJ digits;
• equal to the legal name.

Casing stays verbatim from the source. Title-casing is a separate owner decision. Official and community names stay distinct: official.display_name remains the source's own value.

B-BR-STATION-ADDRESS-01, address precedence. The address shown is the first available of:

1. ANP official address (registry API/CSV);
2. RFB establishment address for the same active CNPJ;
3. OSM addr:* of the POI matched to this station;
4. CNEFE address point;
5. municipality name + UF.

Each stored address carries address_source (anp, rfb, osm, cnefe, municipality). The app labels non-ANP addresses as approximate. Raw coordinates are never the address text. They stay available only as an explicit secondary action ("copiar coordenadas" / navigate). Reverse geocoding with public Nominatim is not a bulk source: ADR-003 and the Nominatim usage policy apply. Verify ADR-003 before using any geocoder. No new geocoding service without an ADR.

3. Tasks

SNA-01: Ingestor parses names and full addresses

Execution bounds (2026-11-03): SNA-01A = pure Go rule and CSV/API parsing; SNA-01B = additive Rust v3 enrichment and Go batch admission. Finish both before SNA-02. Actual base emits station-assertion-v2; old v1/v2 remain readable. These are atomic children in one cumulative delivery, not separate PRs.

• CSV (stage.go): read NOME_FANTASIA and the address columns into the assertion (street, number, complement, district, postal_code, municipio, plus municipio_ibge, uf). Use the keys that read/export.go already uses.
• API (api_official.go): parse nomeFantasia.
• Assertion gains LegalName and TradeName. DisplayName becomes the output of a pure domain function implementing B-BR-STATION-NAME-01.
• Station-prep batch: additive trade_name and legal_name fields in the batch assertion contract (schema version bump in contracts/). Rust prep fills trade_name from RFB by CNPJ, else from the latest ANP survey row. Fixtures are synthetic ([P25-TEST]), never real contributor data.
• Tests: table tests for the name rule (placeholders, equality, CNPJ, blanks), CSV/API parsing with and without the trade name, quarantine behaviour unchanged, Rust contract tests.

SNA-02: Storage and projection (append-only migration)

Execution bounds (2026-11-03): SNA-02A = nullable storage and assertion round trips; SNA-02B = name/address projection; SNA-02C = resumable concurrent-safe re-projection job. Finish all before SNA-03, within the same cumulative PR.

• New migration: directory_stations.legal_name TEXT NULL, trade_name TEXT NULL, address_source TEXT NULL with a CHECK on the enum. Add the matching staging and assertion columns where the projection reads them.
• The projection computes display_name and the address with the two rules. Source rows stay immutable.
• Backfill: an idempotent ops/worker job re-projects existing stations from retained assertions. It is resumable, batched, and safe with two dispatchers (SKIP LOCKED). No destructive rewrite.
• Tests: migration recovery test, real-PostGIS projection tests (trade name wins; correction wins; legal-only; placeholder), backfill idempotency and concurrency.

SNA-03: API contract (additive)

• Station: add legal_name (nullable) and address_source (nullable enum). display_name keeps its type; only its value improves. address keeps the documented component keys.
• OpenAPI, handler and contract tests. Shared-cacheable invariance tests still pass. Older APKs ignore the new fields.

SNA-04: Fill addresses for stations without an ANP address

• In station-prep, attach RFB, OSM and CNEFE addresses by the precedence rule, with address_source and the source reference in provenance.
• Report coverage: count of stations per address_source before and after, nationally and per UF. Store it in evidence, with no personal data.
• STOP if a source's licence or terms do not allow this use. Record it and skip that source.

SNA-05: Mobile app

• ServerStation (domain): add legalName and addressSource. Add a formatted addressLine such as "Av. X, 123 – Bairro, Cidade/UF", built from the components and never from coordinates.
• ServerStationDetailSheet: title is displayName, subtitle is legalName when it differs, then the address line plus an "endereço aproximado" label for non-ANP sources. Coordinates move to a secondary copy/navigate action.
• MapDiscoveryViewModel: the marker subtitle uses the address line, falling back to the municipality name, never the IBGE code.
• List rows, the capture station picker (CaptureScreen addressLabel) and search match both names.
• Strings in all 8 locales. Domain unit tests, ViewModel tests, Compose UI test for the detail sheet, and light/dark screenshots.

SNA-06: Other surfaces

The admin panel shows both names and address_source. The portal generator (enterpriseexport/portalgen) and landing use display_name and the address line. Check that nothing still prints coordinates as an address.

SNA-07: Staging delivery and acceptance

Merge through the protected dev → main flow. The CD agent deploys to staging (see CD_ZERO_DOWNTIME_PLAN.md). Run the backfill with owner authorization. Acceptance on staging, with evidence in docs/backend/evidence/sna/:

• 20 sampled stations across 5 UFs show the trade name first.
• Legal-only stations still show a name.
• Stations formerly shown with coordinates now show an address or the municipality name.
• Coverage numbers per address_source are recorded.

4. Never

• Invent a name or address.
• Show coordinates as the address.
• Overwrite official source rows.
• Mix community corrections into official.*.
• Put real CNPJ or contributor data in fixtures beyond the public registry test samples.
• Bulk-query public Nominatim.
• Make breaking API changes.

---

Part B: national EV charger mapping (OCM × OSM)

Task IDs: EVC-xx. Same delivery rules as Part A. This part extends the existing EV work and does not replace it: EE-00..EE-31 (docs/planning/EV_FULL_SUPPORT_EXECUTION_PLAN.md), MAP-EV (MAP_EV_EXECUTION_PLAN.md, MAP_EV_SOURCE_REGISTER.md) and EV_SOURCE_RESEARCH.md (EVS-06..EVS-09).

B1. What already exists (origin/main, 2026-11-03)

• OCM reader: tools/station-prep/src/ev_ocm.rs and bin/prepare_charging.rs.
  • Profile ocm-br-20261021-v1 (EE-04) holds 1,298 Brazilian POIs and 2,089 connection groups, pinned to an ocm-export commit.
  • Only open-licence providers are admitted: 1 (CC BY 4.0, 768 POIs), 40 (CC-0, 422) and 57 (CC0, 108).
  • Contacts, comments and media are minimised away.
• OSM reader: tools/station-prep/src/osm_reference.rs and bin/prepare_osm.rs read local PBF files.
  • They already classify amenity=fuel, amenity=charging_station and COMBINED_SITE.
  • They keep operator and socket tags, and carry the ODbL-1.0 / © OpenStreetMap contributors attribution.
  • So far they have only been run on a regional (Curitiba) extract.
• Backend: backend/internal/modules/charging covers prepared import, linking, read, community observations and operational commands. The related migrations are 000115–000118, 000121 (identity links), 000122 (map overlays) and 000132.
• App: ChargingExplore/ChargingCommunity screens, ChargingMarkersSource, the offline ChargingSnapshotImport, and the EV trip planner.
• Rule already designed (MAP_EV_SOURCE_REGISTER.md, "Charger confidence"): an OSM ∩ OCM match within 50 m with the same socket family is labelled "Confirmado por 2 fontes"; a single source stays unconfirmed. It has not been implemented.
• Register drift to fix: SRC-OCM still says PENDING although EE-04 recorded the user authorisation. SRC-OSM is waiting on a pinned national extract.

B2. Coverage reality

• ABVE/Tupi Mobilidade report about 25 thousand public and semi-public charge points (mid-2026), with news reporting close to 30 thousand by September 2026. Those figures count points; OCM and OSM count sites.
• OCM has 1,298 Brazilian sites. The OSM national count has not been measured yet (EVC-01 does it).
• OCM + OSM will therefore cover only part of the real network. The product must say "carregadores mapeados por fontes abertas", never "todos os carregadores do Brasil".
• The rest is filled by:
  • community contributions through the existing charging community flow;
  • later, licensed sources (operator OCPI feeds, Neoenergia, EDP, Shell Recharge…), which need written rights and a separate source admission.

B3. Business rules (B-BR first)

B-BR-EV-SRC-01, admission.

• OCM records are admitted only from providers listed in the rights manifest with a licence and attribution (today: 1, 40, 57). The opendata flag alone is not enough, and a new provider requires a manifest amendment.
• OSM is admitted from a pinned Geofabrik Brazil extract (URL, date, bytes, SHA-256), never from live Overpass queries in production.
• Excluded in both sources:
  • access=private or no;
  • OCM status Removed or Decommissioned;
  • disused:, abandoned: or construction= objects.

B-BR-EV-SITE-01, site unit.

• A site is one OSM amenity=charging_station node, way or relation, or one OCM POI. man_made=charge_point children aggregate into their parent site and are never counted twice.
• Connector groups keep the socket family and the quantity each source reports. A reported quantity is not proof of physical EVSEs.

B-BR-EV-MATCH-01, cross-match. Matching is deterministic and one-to-one between an OSM site and an OCM POI:

• Confirmed by 2 sources: distance ≤ 50 m and at least one shared socket family (Type 2, CCS2, CHAdeMO, GB/T, Type 1, Tesla, domestic NBR 14136).
• Probable: distance from 50 to 150 m with the same normalised operator, network or name. Shown as single-source and queued for review.
• Separate: anything else. The site appears once per source.
• Ties break by distance, then by source IDs. Two OSM sites never merge into one OCM POI, or the reverse.
• Conflicting connectors (no shared family within 50 m) go to a conflict queue, never auto-merge.

B-BR-EV-FIELDS-01, field precedence on a confirmed site.

• Geometry: OSM, which carries way/relation footprints.
• Connectors and power: shown per source. Values are never summed and no maximum is invented.
• Operator: OSM operator/network, else the OCM operator.
• Address: the Part A precedence (OSM addr:*, OCM AddressInfo, CNEFE, municipality). Coordinates are never shown as the address.
• Lineage: both source IDs, versions and clocks.
• Status: open-source status is static metadata, never "available now". Community status reports stay separate and dated.

B-BR-EV-STATION-01, link to fuel stations.

• A charger links to an ANP fuel station when any of these holds:
  • OSM tags the same object as both fuel and charging (COMBINED_SITE);
  • the charger is within 75 m of a pinned station (reviewed, osm-mapped or anp-reported tier) with a matching normalised brand or trade name;
  • a reviewed community link exists.
• It is a link in 000121 identity links, never an identity merge. The station page shows "Recarga elétrica" with connectors and power.

B-BR-EV-RIGHTS-01, licences.

• The published charger dataset, API and offline pack contain OSM-derived data, so they follow the recorded T07 ODbL derived-database determination:
  • visible attribution © OpenStreetMap contributors (ODbL);
  • per-POI OCM provider attribution and licence;
  • the derived-database offer at release.
• OCM data is CC BY 4.0, CC0 or CC-0 (OCM moved its own data from CC BY-SA to CC BY 4.0). It may be combined with attribution.
• Missing or mismatched rights block publication of that generation.

B4. Tasks

EVC-00: Inventory and register reconciliation (no behaviour change)

• Read the EE, MAP-EV and EVS docs. Confirm what charging data is live on staging (overlay generation, counts).
• Fix the SRC-OCM/SRC-OSM register rows against EE-04 and T07.
• Baseline counts go to docs/backend/evidence/evc/EVC-00.md.

EVC-01: National source pins

• OCM: refresh the Brazil snapshot from a newly pinned ocm-export commit using sparse paths (data/BR/ plus data/referencedata.json; never clone the world). Verify blob SHAs and the provider licences.
  • If the export is stale or experimental-broken, the alternative is the OCM API with countrycode=BR. The owner obtains the API key, which stays on the VPS or the owner machine and never goes into Git.
• OSM: pin the Geofabrik brazil-latest.osm.pbf (date, bytes, SHA-256). Run prepare_osm nationally with new, versioned streaming limits for disk, memory and time. Never silently raise or truncate the EV limits.
• Record per UF: charging sites, combined sites and fuel sites.
• No network access in tests; fixtures are synthetic.

EVC-02: Normalisation

• One canonical charging-site model for both sources.
• Socket-family mapping table: OSM socket:* keys ↔ OCM ConnectionTypeID, kept as tested contract data.
• Fields: power (kW per group), access, fee, opening hours, operator, network and name.
• Quarantine reasons are explicit, with per-reason counts.

EVC-03: Cross-match (conflation)

• Implement B-BR-EV-MATCH-01 and B-BR-EV-FIELDS-01 in station-prep (Rust) as a pure, deterministic step with golden outputs. Use a spatial grid index, not O(n²).
• Output: canonical sites with sources[], confidence (two-source / single-source), a review queue and a conflict queue.
• Tests cover every band: ≤ 50 m with a shared socket, 50–150 m with the same operator, no shared socket, one-to-one ties, charge_point aggregation, private and removed records.
• Real-run evidence: matched, OSM-only, OCM-only, probable and conflict counts nationally and per UF, plus a 30-site manual spot check against satellite or street imagery recorded by the owner.

EVC-04: Link chargers to fuel stations

• Implement B-BR-EV-STATION-01 using the Part A trade names, through the existing linking adapter (000121).
• Real-PostGIS tests: the 75 m band, brand mismatch, combined sites, and a re-run that stays idempotent.

EVC-05: Rights manifest and attribution

• A per-generation rights manifest carries the OSM extract identity and the OCM provider licences.
• Attribution strings go into the API response (additive sources field), the app detail sheet and the offline pack.
• Prepare the ODbL derived-database offer artefact for release.
• Publication is blocked when rights are missing (negative test).

EVC-06: Backend import and publication

• Reuse the prepared import (000115/000116 batch order).
• Add only the minimum append-only columns needed for confidence, source lineage and the station link.
• The generation swap is atomic. The kill switch keeps the last good generation.
• Anomaly guard: refuse publication when the site count drops by more than 15 % per UF versus the previous generation, unless the owner overrides.
• OpenAPI changes are additive (confidence, sources, linked_station_id). Shared-cache invariance tests stay green.

EVC-07: App

• Map charger pins with a "Confirmado por 2 fontes" badge.
• Filters by connector family and minimum power.
• Charger detail:
  • name and operator;
  • address line from the SNA-05 formatter;
  • connector groups with power per source;
  • source and licence attribution;
  • "reportar status" (existing community flow).
• The fuel station detail shows linked chargers.
• Offline snapshot update.
• Strings in all 8 locales; unit, ViewModel and Compose UI tests; light and dark screenshots.

EVC-08: Refresh cadence

• A scheduled worker/ops job: OCM weekly, OSM monthly (new pins).
• Every run produces a diff report (added, removed, moved > 50 m, connector changes).
• A site disappears only when its source drops it. A confirmed site that loses one source becomes single-source.
• No live public Overpass or OCM polling from the API path.

EVC-09: Coverage and honesty

• A coverage report per UF and municipality: sites mapped versus the ABVE/Tupi benchmark (points ≠ sites, so the unit difference is stated).
• In-app wording reads "mapeados por fontes abertas", with an "adicionar carregador" prompt in gap areas through the existing community flow.
• Candidate licensed sources are listed for the owner; none is contacted or admitted without authorisation.

EVC-10: Staging delivery and acceptance

Deploy through the CD agent (CD_ZERO_DOWNTIME_PLAN.md). Owner-authorised import of the national generation. Acceptance:

• national counts match the manifest;
• 30 spot-checked sites are correct;
• confirmed badges show only on two-source matches;
• linked fuel stations show their chargers;
• attribution is visible;
• the kill switch and rollback work.

Evidence goes in docs/backend/evidence/evc/.

B5. Never

• Claim complete national coverage.
• Treat static open-source status as live availability.
• Sum connector counts across sources.
• Merge identities instead of linking them.
• Poll public Overpass or the OCM API from production paths.
• Clone the world OCM export.
• Admit an OCM provider without a recorded licence.
• Drop OSM or OCM attribution.
• Put contacts, comments or photos from OCM into Abastevo content.
• Put an API key in Git.