Repository navigation
docs product stations catalog
This document does not describe new runtime behavior.
Catalog fuel retailers independently of participation in ANP's price survey. A business registration, ANP authorization, observed physical opening and a mapped location are different facts with different dates. Authorization publication must never become an inferred inauguration date. Absence from a feed means verification is unavailable, not proof of unlawful activity.
The initial public catalog accepts records whose identity/address and authorization evidence satisfy the frozen P25 policy. Community-only suggestions remain private to their submitter and authorized operators until reviewed. P27 freezes a separate reviewed-unverified publication policy before any such visibility; no unverified suggestion is automatically published by this plan. A station without reviewed coordinates can be text-searchable; it cannot claim precise proximity or routing.
- D01 — Source separation: Directory owns stable station identity, source assertions and reviewed location. Official owns dated ANP price observations; Community owns submitted prices and consensus. Catalog insertion creates neither a price nor trust, and never fabricates an ANP price-survey observation.
- D02 — Identity and succession: Validate full branch CNPJ as text using existing numeric/alphanumeric rules. Use SIMP/authorization as additional source identifiers after their scopes are verified. Enforce unique active identifiers transactionally; retain validity history. Different identifiers at one address, or nearby points, are review candidates, never automatic merges. Any succession, duplicate consolidation or identifier reassignment needs an audited, reversible decision preserving references to prices/social facts.
- D03 — Provenance and clocks: Record source, source identifier/reference, content checksum, parser/policy version, published/effective dates when supplied, fetched time, validated time and catalog publication time. Unknown timestamps stay unknown. Replaying identical input/policy is idempotent; corrections retain supersession history. Restricted owner/contributor data never enters public provenance.
- D04 — Independent states: Model authorization verification, operating status, publication eligibility and location quality separately. P25 freezes wire values and allowed transitions before migrations/API. An active CNPJ, map point, vote or photograph alone proves none of the other states. Unknown/stale status is displayed honestly; paid status does not affect verification.
- D05 — Publication and withdrawal: Publish only validated records from complete reconciled input with explicit atomic boundaries. A broken, truncated or missing page cannot retire records. A single missing row does not mean closure. Closure/revocation requires sourced status evidence or an audited review. Late contradictory evidence cannot silently replace newer accepted facts.
- D06 — Location: Reuse append-only location revisions and the existing reviewed-point projection. Validate latitude/longitude, CRS/SRID, source accuracy and address match; missing/ambiguous/centroid positions stay unreviewed. A user pin or capture GPS is a private suggestion to review, not a canonical station point. Do not publish the contributor's precise GPS.
- D07 — Account and ownership: Suggestions, corrections and owner-status reads require an active free app account plus existing signed-request proof. Anonymous contributor proof alone is insufficient. All public catalog reads may remain anonymous. Knowing a public CNPJ or submitting a station grants no ownership, moderation privilege or exclusive editing rights.
- D08 — Submission and abuse: Freeze bounded structured inputs, account quotas, idempotency keys and safe error/status projections before coding. Concurrent submissions for one station converge without losing each author's private request status. Evidence of suspicious activity routes to review; community vote counts do not grant publication power. Reports/appeals reuse moderation authority, never auto-delete another user's station.
- D09 — Media and privacy: Reuse P15/P16 controls and local lightweight capture/encoding. A suggested photo is optional unless the frozen review policy explicitly requires it for a particular unresolved case. Every photo copy expires within the existing maximum 24 hours; no reset on rebinding/retry. Durable decisions retain only policy-approved minimal metadata. After expiry, insufficient cases require fresh evidence or remain unresolved. No raw photos, credentials, private documents, submitter GPS or contact/provider identity in Git, fixtures, logs or public APIs.
- D10 — Source access: Fetch only approved HTTPS origins with redirect/DNS/IP validation, deadlines, byte/row/page limits, bounded retries and global quotas. No caller-provided fetch URL or remote request in a public search handler. Disable XML external entities/DTD fetching and formula execution. Credentials stay in operator secrets, not task payloads or logs. A provider timeout leaves the last validated state intact and its freshness visible.
- D11 — License and representations: Record storage/redistribution/attribution rights per source before enabling it. OSM and commercial-provider assertions retain provenance and may require separate storage/views; physical separation alone does not settle license obligations. No copying of a restricted provider into an unrestricted permanent catalog. Partner messages require agreed authority and independent authorization verification.
- D12 — Measured freshness: Distinguish opening-to-source delay, source-publication-to-fetch delay, eligibility-to-catalog delay and human-review age. The proposed 24–48-hour objective begins when a record has sufficient validated evidence for publication; it is not a national inauguration SLA. Define eligibility/exclusions before measurement; report unresolved/quarantined records separately so the objective cannot hide backlog. A photo or membership fee never accelerates trust.
Actor: scheduled worker/operator. Fetch a complete versioned CSV or bounded API query; stage, validate identifiers/addresses/statuses, reconcile and publish through Directory. Missing page, layout change, oversize input or excessive unexplained delta quarantines the run and preserves the previous accepted catalog. Prove leading zeros/alphanumeric CNPJ, replay, duplicate rows, conflicting facts and concurrent first creation.
Actor: DOU discovery worker. Read approved daily editions, retain edition/act reference and classify ANP grant, correction, revocation or unrelated act. Extract structured assertions, verify against the official act/API and reconcile. Unknown wording, amendments, conflicting chronology or ambiguous establishment needs review. No LLM-generated interpretation is sole publication authority. Test multiple establishments in one act, republication, operator succession and outage catch-up.
Actor: active free account. Search for duplicates first; submit structured suggestion with optional evidence and location; receive a private request ID. Existing station detection may resolve to its canonical ID without publishing the submitter's identity. Failed signature, revoked session, replay, quota violation, another owner's evidence and conflicting idempotency payload are rejected. Submission never proves operation or grants editing ownership.
Actor: automated verifier for policy-approved exact official matches, otherwise an authorized reviewer. Review source/status/address/location conflicts, record reason and versioned decision, and publish eligible facts atomically. Expired evidence is inaccessible and cannot be relinked to extend retention. User cancellation, simultaneous reviewer actions, appeal and a new source correction have explicit tested transitions. Use existing moderation ports; no unaudited database editing.
Actor: anonymous reader or signed contributor. Read searchable stations even without official/community prices. Render no-price, authorization freshness and unknown coordinates explicitly. Resolve legacy full CNPJ to server UUID via a declared Directory read contract before contribution/rating/comment/report; never cast CNPJ to UUID or synthesize a price row. Account/social permissions and 280-scalar feedback rules remain unchanged. Test offline cache, pagination, unknown server state and denied/stale target.
Actor: worker/operator. Apply authorized corrections or closure with a new revision, retaining referenced station IDs and source history. Lease fencing, concurrent importer/suggestion, duplicate job, database failure, restore replay and binary rollback cannot publish partial state or resurrect private evidence. User data erasure follows existing privacy workflows rather than an unlimited audit exception.
Actor: operator/verified partner adapter. Admit OSM or a contracted feed only after need, rights, schema, authentication, quota and freshness are documented. Supplement only the permitted attributes, flag conflicts and route candidates through the same verifier. Disable a provider without deleting unrelated facts. Owner representation, if introduced, needs independent proof and is separate from authorization and station editing privileges.
Actor: operator. Exercise a frozen synthetic workload, dependency outages, backlog/recovery and review queues; report valid denominators, hardware/configuration, exact revision and unmet budgets. Run anonymous read/contribution/social regressions while imports execute. A simulated 48-hour clock proves behavior, not 30 days of live service. Public freshness guarantees wait for measured source and staffing evidence.
Verified representation is now explicitly planned in STATION_PROFILE_REPRESENTATION / P30–P33, superseding P28-T04. Directory remains owner of Station/operator identities; a profile grant is scoped to an account/station/operator revision and never inferred from source/suggestion/partner access.
P25/P27 must update the owning versioned OpenAPI, fixtures, Data Model and privacy inventory before their new handlers/migrations. Names in this document are semantic targets, not endpoints or tables claimed to exist. Existing account writes, Directory UUIDs, anonymous reads, cache allowlists and media ownership remain in force. Unknown additive states have cautious client fallbacks. Native iOS work is deferred until an explicit request; Kotlin contracts preserve portable domain/application code.
Target: an active free account may propose a correction to an existing directory station. Corrections are community assertions; they never overwrite an official fact in place (D8). The fields available in this batch are location, display name, brand, address and operating status. Fuel products, services and EV connectors join the same contract after the dossier (A5) and their own validators land.
- COR-01 — Target and fields. Every correction names one station UUID and exactly one field. Payloads are structured JSON validated by a per-field validator; unknown fields and unknown top-level members are rejected. A correction never creates a station, a price, a trust rating or ownership.
-
COR-02 — Official/community separation. The official/ANP projection and
the station's canonical identity remain unchanged. An accepted location
becomes a new
reviewedlocation revision through the existing ladder; an accepted name/brand/address/status becomes a community-layer assertion with its own label, source and observed date. Community consensus alone never changes an official field. -
COR-03 — Proof, quota and idempotency. Submission requires a live free
account session and the existing signed-request proof. The account quota is
20 submissions per rolling day. One open correction per account + station +
field is allowed.
(account_id, client_submission_id)is unique; the same key with the same body replays the record, the same key with another body is a conflict. Anonymous contributor proof alone is insufficient. -
COR-04 — Field validation. Location must be a finite WGS84 point inside
Brazil and inside the station municipality polygon (500 m buffer), and may
not exceed the allowed distance from the current point unless the payload
carries accepted evidence. The request may carry only a coarse proximity
bucket (for example
same_municipality,within_1km); raw contributor GPS is never stored or published (P16). Name/brand/address are normalized, length-bounded, escaped on output and checked against the station context. An optional note is at most 280 scalar values and rejects URLs, e-mail addresses, phone numbers and CPF/CNPJ-like personal identifiers. -
COR-05 — Consensus and review. Consensus counts distinct accounts and
distinct device keys; new accounts weigh less, and correlated submissions
(same device, network or time window) count once. A correction matching
official evidence (for example an ANP point within 50 m of the proposed pin,
or an equal ANP name/brand) may become
auto_verifiedwith the evidence attached; everything else waits for an operator review. Review decisions are append-only and carry a mandatory reason. A community location accepted by review becomesreviewed; auto-verified official matches become the corresponding official tier, neverreviewed. -
COR-06 — Status lifecycle. Frozen values are
pending,auto_verified,accepted,rejected,expired,cancelled,supersededandfrozen. Onlypending/auto_verifiedare open;cancelledis owner-only;expiredfollows the evidence/policy window; a newer accepted correction supersedes an older open one for the same station+field;frozenis a review hold for flip-flopping. Every transition is audited. A decision after a cancellation, a duplicate reviewer decision or a foreign-owner action fails closed. - COR-07 — Privacy, retention and erasure. Owner reads are private and never list who suggested what to the public. Evidence follows the existing 24-hour private-media rules and EXIF stripping; expired evidence cannot be re-linked to extend retention. Account erasure deletes or anonymizes correction rows according to P13, while retaining the minimal audited decision metadata required by the moderation policy. No personal name, CPF, personal phone/e-mail or precise contributor GPS enters Git, logs or public APIs.
- COR-08 — Abuse and audit. Per-account/day and per-device/network controls bound flooding; a bounded per-station queue and a 30-day cooldown per station+field after a decision apply unless new evidence arrives. Closed/permanently-closed proposals never hide a station without ANP revocation evidence or staff review. A rejection ratio over a window lowers weight and may pause intake reversibly and with an audit record. Every staff decision records decider kind/id, reason and evidence; payment or subscription never affects review, intake or trust.
- Home
- Roadmap
- docs-README
- docs-android-build
- docs-android-design-system
- docs-android-forum
- docs-android-games
- docs-android-map-engine
- docs-android-navigation
- docs-android-ocr-image
- docs-android-ocr-live-framing
- docs-android-premium-area
- docs-android-premium-integration
- docs-android-release
- docs-android-ui-containers
- docs-architecture-android-stack
- docs-architecture-android
- docs-architecture-backend
- docs-architecture-data-sources
- docs-architecture-overview
- docs-architecture-sources-ev-research
- docs-architecture-sources-national-limits
- docs-architecture-sources-national-stations
- docs-architecture-sources-register
- docs-assets-app-tutorial-CAPTURE_CONTRACT
- docs-assets-app-tutorial-FABLE_LANDING_POLISH_PROMPT
- docs-assets-app-tutorial-README
- docs-assets-attribution
- docs-assets-brand-README
- docs-assets-flags-ATTRIBUTION
- docs-assets-fuel-icons-README
- docs-assets-games-fuel-v1-README
- docs-assets-home-icons-README
- docs-assets-landing-fleet-android-20261012-BRIEF
- docs-assets-landing-hero-20261011-BRIEF
- docs-assets-landing-illustrated-20261012-BRIEF
- docs-assets-landing-illustrated-20261012-README
- docs-assets-landing-minimal-20261012-BRIEF
- docs-assets-landing-open-data-20261026-BRIEF
- docs-assets-landing-redesign-20261011-PREPARATION_EVIDENCE
- docs-assets-landing-redesign-20261011-README
- docs-assets-landing-redesign-20261011-REFERENCE_BRIEF
- docs-assets-landing-sync-20261012-BRIEF
- docs-assets-map-icons-README
- docs-backend-anp-ingestion
- docs-backend-api
- docs-backend-community-pricing
- docs-backend-data-model
- docs-backend-domain-model
- docs-backend-driver-private-data
- docs-backend-forum-architecture
- docs-backend-forum-bulletins
- docs-backend-forum-sources
- docs-backend-payments-provider-admission
- docs-backend-payments-provider-register
- docs-backend-photos-capture
- docs-backend-photos-subset-submission
- docs-backend-premium-api
- docs-backend-premium-cloud-protocol
- docs-backend-testing
- docs-backend-toolchain
- docs-brand-app-icons
- docs-brand-identity
- docs-decisions-001-kotlin-compose-stack
- docs-decisions-002-price-import-immutability
- docs-decisions-003-nominatim-reverse-geocode
- docs-decisions-005-modular-monolith-and-postgresql
- docs-decisions-006-official-catalog-and-exact-contracts
- docs-decisions-007-anonymous-proof-of-possession
- docs-decisions-008-privacy-and-retention
- docs-decisions-009-community-consensus-and-projections
- docs-decisions-010-private-object-evidence
- docs-decisions-012-licensing-and-hosted-business
- docs-decisions-015-kotlin-multiplatform-shared-domain
- docs-decisions-016-android-commercial-community-ios-deferred
- docs-decisions-017-station-profile-and-verified-representation
- docs-decisions-021-community-first-contribution
- docs-decisions-022-comaps-derived-native-map-engine
- docs-decisions-023-admin-suite-granted-tiers-contributors
- docs-decisions-025-private-abastevo-empresas-organization-boundary
- docs-decisions-026-multilingual-public-site
- docs-decisions-README
- docs-enterprise-README
- docs-enterprise-architecture
- docs-enterprise-backlog-INDEX
- docs-enterprise-backlog-ep00-governance
- docs-enterprise-backlog-ep01-platform
- docs-enterprise-backlog-ep02-organizations
- docs-enterprise-backlog-ep03-identity-access
- docs-enterprise-backlog-ep04-sync
- docs-enterprise-backlog-ep05-fleet-meters
- docs-enterprise-backlog-ep06-trips
- docs-enterprise-backlog-ep07-gps-navigation
- docs-enterprise-backlog-ep08-fuelings
- docs-enterprise-backlog-ep09-documents
- docs-enterprise-backlog-ep10-expenses-finance
- docs-enterprise-backlog-ep11-maintenance
- docs-enterprise-backlog-ep12-fuel-stock
- docs-enterprise-backlog-ep13-intelligence
- docs-enterprise-backlog-ep14-station-claims
- docs-enterprise-backlog-ep15-station-commerce
- docs-enterprise-backlog-ep16-subscriptions
- docs-enterprise-backlog-ep17-data
- docs-enterprise-backlog-ep18-imports-notifications-integrations
- docs-enterprise-backlog-ep19-back-office
- docs-enterprise-backlog-ep20-release
- docs-enterprise-business-rules
- docs-enterprise-contract
- docs-enterprise-conventions
- docs-enterprise-data-offering
- docs-enterprise-decisions
- docs-enterprise-domain-model
- docs-enterprise-glossary
- docs-enterprise-journeys
- docs-enterprise-modules-back-office
- docs-enterprise-modules-data
- docs-enterprise-modules-documents
- docs-enterprise-modules-expenses-finance
- docs-enterprise-modules-fleet
- docs-enterprise-modules-fuel-stock
- docs-enterprise-modules-fuelings
- docs-enterprise-modules-gps-navigation
- docs-enterprise-modules-identity
- docs-enterprise-modules-imports-notifications-integrations
- docs-enterprise-modules-intelligence
- docs-enterprise-modules-maintenance
- docs-enterprise-modules-organizations
- docs-enterprise-modules-station-claims
- docs-enterprise-modules-station-commerce
- docs-enterprise-modules-subscriptions
- docs-enterprise-modules-trips
- docs-enterprise-offline-sync
- docs-enterprise-permissions
- docs-enterprise-portal-routes
- docs-enterprise-privacy-security
- docs-enterprise-product-vision
- docs-enterprise-source-admission
- docs-enterprise-state-model
- docs-enterprise-testing
- docs-enterprise-ux-app
- docs-enterprise-ux-web
- docs-operations-README
- docs-operations-backup
- docs-operations-deploy-agent
- docs-operations-dou-editions
- docs-operations-edge-cache
- docs-operations-enterprise-activation
- docs-operations-map-static-overlay
- docs-operations-moderation-feedback
- docs-operations-moderation-profiles
- docs-operations-monitoring
- docs-operations-operator-access
- docs-operations-payments
- docs-operations-premium-billing
- docs-operations-recovery
- docs-operations-registry-daily-sync
- docs-operations-registry-runs
- docs-product-README
- docs-product-admin-tiers
- docs-product-community-community-first
- docs-product-community-experience
- docs-product-community-metrics
- docs-product-community-moderation
- docs-product-community-safety
- docs-product-community-terms-pt-br
- docs-product-driver-suite-README
- docs-product-driver-suite-android-state
- docs-product-driver-suite-cloud-sync
- docs-product-driver-suite-cost-profiles-and-maintenance
- docs-product-driver-suite-driver-model-and-earnings
- docs-product-driver-suite-foundation-decisions
- docs-product-driver-suite-gps-lifecycle
- docs-product-driver-suite-mobile-hub
- docs-product-driver-suite-odometer-review
- docs-product-driver-suite-outbox-wire
- docs-product-driver-suite-quick-refuel
- docs-product-driver-suite-reports
- docs-product-driver-suite-shifts-and-distance
- docs-product-driver-suite-signed-commands
- docs-product-ev-README
- docs-product-ev-charging-stop-planner
- docs-product-ev-energy-model
- docs-product-ev-financial-method
- docs-product-ev-journey-ui
- docs-product-ev-preparation
- docs-product-ev-typed-data
- docs-product-exploration
- docs-product-forum-contract
- docs-product-forum-policies
- docs-product-glossary
- docs-product-landing-content
- docs-product-landing-guides
- docs-product-landing-organic-growth-i18n-plan
- docs-product-licensing
- docs-product-map-discovery
- docs-product-map-favorites-and-trips
- docs-product-map-reports-routing-guidance
- docs-product-notification-content
- docs-product-official-prices
- docs-product-open-source-business
- docs-product-overview
- docs-product-payments-README
- docs-product-payments-offer-policy
- docs-product-premium-README
- docs-product-premium-financial-method
- docs-product-premium-source-policy
- docs-product-stations-catalog
- docs-product-stations-fuel-feedback
- docs-product-stations-fuel-quality
- docs-product-stations-identity-and-ev-catalog
- docs-product-stations-profile-contract
- docs-product-stations-profile-representation
- docs-product-stations-registry-sources
- docs-product-vehicle-registration
- docs-product-vehicles-and-occurrences
- docs-security-android-terms-acceptance
- docs-security-free-account-access
- docs-security-identity-profile
- docs-security-media-location-policy
- docs-security-privacy-notice
- docs-security-privacy-policy
- docs-security-retention
- docs-security-risks
- docs-security-security-privacy
- docs-store-README
- docs-store-play-readiness
- docs-store-play-store-listing
- docs-store-ugc-safety
Source: AlexandreZanata/Abastevo @ e4a67580fc368a59bc1c0f1e0466fc011313f330