# Domain Glossary

> Ubiquitous language for the ANP Fuel Prices project.
> Code identifiers **must** match these terms exactly.

## Business Terms

| Term | Definition |
|------|------------|
| **PriceSurvey** | A weekly ANP fuel price collection for a fixed date range (Sunday–Saturday). |
| **SurveyWeek** | The date range of a PriceSurvey (start date + end date). |
| **FuelProduct** | A fuel type tracked by ANP (enum). |
| **GeographicScope** | Aggregation level: `NATIONAL`, `REGION`, `STATE`, `MUNICIPALITY`, `STATION`. |
| **AveragePrice** | Statistical summary (mean, min, max, std dev) for a FuelProduct at a GeographicScope. |
| **RetailStation** | A licensed fuel retail point identified by CNPJ. |
| **StationPrice** | The price charged by a RetailStation for a FuelProduct on a collection date. |
| **PriceTable** | The downloadable XLSX file published by ANP for a SurveyWeek. |
| **PriceTableType** | Either `WEEKLY_SUMMARY` or `STATION_DETAIL`. |
| **SyncJob** | A background task that discovers, downloads, and imports new PriceTables. |
| **MunicipalityCatalog** | Persistent IBGE baseline (~5 570 municipalities) merged with ANP-published aliases for national search (v2). |
| **MunicipalityCatalogEntry** | A single municipality in the catalog: `state`, `municipality`, optional `ibgeCode`. ANP week availability is derived at query time, not stored. |
| **MunicipalityLocationKey** | Stable identity pair (`state` + `municipality`) for catalog matching and availability checks. |
| **DataAvailability** | Query-time annotation: `HAS_DATA`, `NO_DATA_THIS_WEEK`, or `NEVER_IN_ANP`. |
| **SearchMatchType** | FTS match quality tier for ranking: `EXACT_PREFIX`, `ACCENT_NORMALIZED`, `TYPO_TOLERANT`, `SUBSTRING`. |
| **SurveyWeekCatalogEntry** | Metadata for one ANP listing week block: `surveyWeek`, summary/station URLs, optional `publishedAt`, optional `operationalNote` (v2). |
| **SurveyWeekSelectionMode** | How the user chose a week in UC-009: `LATEST` or `SPECIFIC`. |
| **ActiveSurveyWeek** | User preference (`UserPreferences.activeSurveyWeek`) for the week currently displayed and synced (BR-019). |
| **Vehicle** | User-owned car profile: display name, `TankCapacity`, single `FuelProduct`, and `VehiclePriceSource`. |
| **TankCapacity** | Value object — tank capacity in liters (> 0, ≤ 200). |
| **TankFillCostEstimate** | Derived value: unit price × `TankCapacity` for the active `SurveyWeek`. |
| **VehiclePriceSourceMode** | How unit price is resolved: `CHEAPEST_STATION` or `SPECIFIC_STATION`. |
| **VehiclePriceSource** | `VehiclePriceSourceMode` plus optional `Cnpj` when mode is `SPECIFIC_STATION`. |
| **PriceDropAlert** | User preference on a `Vehicle` to notify when fuel price drops vs previous imported week. |
| **AlertPriceSource** | Price reference for alerts — same semantics as `VehiclePriceSourceMode` (+ optional CNPJ). |
| **DeviceLocation** | Ephemeral latitude/longitude from Android location APIs; not persisted as PII (UC-012, UC-015). |
| **GeoCoordinates** | Validated latitude/longitude pair (WGS-84) used for station distance calculation (UC-015). |
| **ReverseGeocodeResult** | Resolved `BrazilianState` and municipality name from coordinates. |
| **AddressGeocode** | Resolution of a normalized address into `GeoCoordinates` through Nominatim `/search` (`AddressGeocodeRepository`, UC-015). |
| **NearestStationRecommendation** | Selected `RetailStation` for UC-015: station, unit price, and distance in meters from the device. |
| **StationNavigationQuery** | Normalized address string plus municipality and state for external map apps. |
| **GeocodingAttribution** | OSM/Nominatim attribution requirement whenever geocoding is used — reverse (UC-012) or forward (UC-015) (BR-021). |

## FuelProduct Enum

| Value | ANP source label (Portuguese) | Unit |
|-------|-------------------------------|------|
| `ETHANOL` | ETANOL HIDRATADO / ETANOL | R$/liter |
| `GASOLINE_REGULAR` | GASOLINA COMUM | R$/liter |
| `GASOLINE_PREMIUM` | GASOLINA ADITIVADA | R$/liter |
| `DIESEL_S500` | OLEO DIESEL / DIESEL S500 | R$/liter |
| `DIESEL_S10` | OLEO DIESEL S10 / DIESEL S10 | R$/liter |
| `CNG` | GNV | R$/m³ |
| `LPG_P13` | GLP | R$/13 kg |

## BrazilianRegion Enum

`NORTH`, `NORTHEAST`, `CENTRAL_WEST`, `SOUTHEAST`, `SOUTH`

## BrazilianState

27 federative units. Stored as enum with `name`, `abbreviation` (e.g. `SAO_PAULO`, `SP`).

## VehiclePriceSourceMode / AlertPriceSource

Shared enum values:

| Value | Meaning |
|-------|---------|
| `CHEAPEST_STATION` | Minimum `StationPrice` for vehicle fuel in preferred municipality |
| `SPECIFIC_STATION` | Price at a chosen `RetailStation` identified by `Cnpj` |

## Domain Events

| Event | Fired when |
|-------|------------|
| `PriceTableDiscovered` | A new weekly file URL is found on the ANP page |
| `PriceTableDownloaded` | A PriceTable file is saved locally |
| `PriceTableImported` | Rows are parsed and persisted to local DB |
| `PriceTableImportFailed` | Parsing or validation failed |
| `SyncJobCompleted` | A SyncJob finishes (success or partial) |
| `CitySelected` | User selects a municipality for price lookup |
| `FuelProductSelected` | User selects a fuel to view detail or stations |
| `SyncRequested` | User or system triggers a sync (`MANUAL`, `SCHEDULED`, `FIRST_LAUNCH`) |
| `StationDetailRequested` | User requests on-demand station-level download |
| `PreferencesUpdated` | User changes a local preference |
| `CacheCleared` | User clears local data (`ALL` or `STATION_DETAIL_ONLY`) |
| `SurveyWeekSelected` | User selects a survey week for sync and display (UC-009) |
| `VehicleRegistered` | User saves a new `Vehicle` (UC-010) |
| `VehicleUpdated` | User edits an existing `Vehicle` (UC-010) |
| `VehicleRemoved` | User deletes a `Vehicle` (UC-010) |
| `PriceDropAlertConfigured` | User toggles or changes alert source on a vehicle (UC-014) |
| `DeviceLocationResolved` | Reverse geocode succeeded and matched `MunicipalityCatalog` (UC-012) |
| `StationNavigationRequested` | User taps navigate on a station row (UC-013) |

## Business Rules

### BR-001 — Valid Survey Week
**GIVEN** a PriceTable file name  
**WHEN** parsed for date range  
**THEN** start date must be before or equal to end date  
**AND** range must be ≤ 7 days

### BR-002 — Fuel Product Normalization
**GIVEN** a raw product label from ANP (Portuguese)  
**WHEN** imported  
**THEN** it must map to exactly one `FuelProduct` enum value  
**AND** unmapped labels must be logged and skipped (not crash)

### BR-003 — Immutable Price History
**GIVEN** an imported StationPrice or AveragePrice  
**WHEN** the same ANP file is re-imported with corrections  
**THEN** a new record is created referencing the SurveyWeek  
**AND** the previous record is never deleted or overwritten

### BR-004 — Offline Read
**GIVEN** no network connectivity  
**WHEN** user requests prices for a previously synced city  
**THEN** cached data must be returned  
**AND** UI must indicate stale/sync status

### BR-005 — Search Requires Imported Data
**GIVEN** the local database has zero imported `SurveyWeek` records  
**WHEN** user attempts search or location browse  
**THEN** the app must redirect to sync/onboarding  
**AND** must not execute an empty FTS query

### BR-006 — Default Survey Week
**GIVEN** multiple `SurveyWeek` records exist  
**WHEN** the app needs a default week for display  
**THEN** it must select the most recent successfully imported week by `endDate`  
**AND** never a failed or partial-import week unless explicitly chosen by the user

### BR-007 — Minimum Search Length
**GIVEN** the municipality search field  
**WHEN** the query has fewer than 2 characters  
**THEN** no FTS query is executed  
**AND** a hint is shown to the user

### BR-008 — Station Detail Opt-out
**GIVEN** `syncStationDetail` is enabled (default: `true`)  
**WHEN** UC-001 sync runs for a survey week  
**THEN** the system must download and import `STATION_DETAIL` together with `WEEKLY_SUMMARY`

**GIVEN** the user has disabled `syncStationDetail` and no local `StationPrice` exists  
**WHEN** user opens station list  
**THEN** the app must offer on-demand download  
**AND** must not auto-download station files in background sync

### BR-009 — ANP Data Attribution
**GIVEN** any screen displaying price data  
**WHEN** rendered to the user  
**THEN** ANP source attribution must be visible  
**AND** link to official ANP page must be available in settings

### BR-010 — Empty Municipality Is Not an Error
**GIVEN** a valid municipality with no rows for the selected `SurveyWeek`  
**WHEN** prices are requested  
**THEN** show empty state UI  
**AND** do not throw or show generic error

### BR-011 — Sync Failure Preserves Cache
**GIVEN** a sync job fails at any stage  
**WHEN** the failure is handled  
**THEN** existing imported data must remain intact  
**AND** no rollback of previously imported weeks

### BR-012 — Preferred Location Persistence
**GIVEN** user selects a municipality  
**WHEN** selection is confirmed  
**THEN** persist `preferredState` and `preferredMunicipality` locally  
**AND** restore on next app launch as default home location

### BR-013 — Station Detail Retention Window
**GIVEN** `stationDetailRetentionWeeks` is set to N  
**WHEN** retention cleanup runs after import  
**THEN** delete `StationPrice` rows older than the N most recent weeks  
**AND** never delete `AveragePrice` summary rows in the same operation

### BR-014 — Wi-Fi Only Background Sync
**GIVEN** `autoSyncOnWifi` is true  
**WHEN** WorkManager scheduled sync runs  
**THEN** require unmetered network constraint  
**AND** manual sync may proceed on metered with optional user confirmation

### BR-015 — Single Active Sync Job
**GIVEN** a `SyncJob` is in a non-terminal state  
**WHEN** another sync is requested  
**THEN** reject or queue the second request  
**AND** never run two imports concurrently

### BR-016 — Municipality Catalog Completeness
**GIVEN** IBGE catalog loaded  
**WHEN** user searches  
**THEN** every federative unit municipality appears in the index regardless of current week data  
**AND** catalog must contain at least 5 570 entries

### BR-017 — Intelligent Search Ranking
**GIVEN** query ≥ 2 characters  
**WHEN** FTS runs  
**THEN** rank matches as: exact prefix > accent-normalized prefix > typo-tolerant token prefix > substring  
**AND** always tie-break by state abbreviation (alphabetical)

### BR-018 — Week Selection Before Sync
**GIVEN** `autoDownloadLatestWeek` is disabled (BR-020)  
**WHEN** `UserPreferences.activeSurveyWeek` is null  
**THEN** show week picker before download starts  
**AND** do not trigger UC-001 until a week is selected

### BR-019 — Active Survey Week
**GIVEN** user selected week W and summary data for W is imported  
**WHEN** any price screen resolves the display week  
**THEN** use W instead of BR-006 default-latest  
**AND** keep W until user changes `activeSurveyWeek` or clears cache

### BR-020 — Auto-Download Latest Survey Week
**GIVEN** `autoDownloadLatestWeek` is enabled (default: `true`)  
**WHEN** onboarding completes, app cold-starts, or background sync runs  
**THEN** discover the ANP catalog, set `activeSurveyWeek` to the newest entry, and trigger UC-001 for that week  
**AND** skip the week picker unless the user disabled this preference

**GIVEN** the user disabled `autoDownloadLatestWeek`  
**WHEN** no `activeSurveyWeek` is set  
**THEN** require manual week selection (BR-018) before sync

### BR-021 — Nominatim Usage Compliance
**GIVEN** a reverse geocode request  
**WHEN** calling the public Nominatim API  
**THEN** send a custom `User-Agent` identifying the app  
**AND** enforce max 1 request per second (client-side throttle)  
**AND** cache successful rounded `(lat, lon)` → municipality results locally  
**AND** never run periodic bulk geocoding in background  
**AND** display OSM attribution where geocoding is used

### BR-022 — One Fuel Product per Vehicle
**GIVEN** a `Vehicle`  
**WHEN** saved  
**THEN** exactly one `FuelProduct` is bound  
**AND** tank fill cost uses only that product's price

### BR-023 — Tank Fill Cost Price Source
**GIVEN** a vehicle with `CHEAPEST_STATION` mode  
**WHEN** station detail exists for the active week  
**THEN** use the cheapest `StationPrice` for that fuel in the preferred municipality  
**ELSE** fall back to `AveragePrice.minimum` if available  
**AND** show informative empty state if neither exists (BR-010)

**GIVEN** a vehicle with `SPECIFIC_STATION` mode  
**WHEN** the chosen CNPJ has a price for the active week  
**THEN** use that `StationPrice`  
**ELSE** apply the same fallback chain as above

### BR-024 — Multiple Vehicles on Home
**GIVEN** the user registered N vehicles (N ≥ 1)  
**WHEN** home renders the tank fill cost section  
**THEN** show one card per vehicle in registration order  
**AND** preserve stable vertical layout (placeholder height matches filled card)

### BR-025 — Price Drop Alert Eligibility
**GIVEN** `PriceDropAlert` enabled for a vehicle  
**WHEN** a new `SurveyWeek` is imported and evaluated  
**THEN** compare current price source vs the previous imported week for the same municipality and fuel  
**AND** emit a local notification only if current < previous  
**AND** never notify without `POST_NOTIFICATIONS` granted

### BR-026 — Station Navigation Query
**GIVEN** a `RetailStation` address from ANP  
**WHEN** the user taps **Navigate**  
**THEN** build a `StationNavigationQuery` with normalized address plus municipality and state  
**AND** open the system geo app chooser (Maps, Waze, or other handlers)

### BR-027 — Maximum Registered Vehicles
**GIVEN** the user already has 3 saved vehicles  
**WHEN** attempting to add another  
**THEN** reject the operation with an informative UI message  
**AND** do not persist a fourth vehicle

### BR-028 — Nearest Best-Price Station
**GIVEN** imported station prices for one `FuelProduct` and the user's `DeviceLocation`  
**WHEN** the user requests the nearest best-price station (UC-015)  
**THEN** consider at most 8 cheapest candidates  
**AND** resolve candidate addresses through Nominatim with local cache and max 1 request per second (BR-021)  
**AND** accept only candidates priced within 2% above the cheapest  
**AND** accept only candidates within the user-configured radius (3/5/10/15 km, default 3 km) of the device location  
**AND** select the nearest candidate inside that band and radius, breaking ties by lowest price  
**AND** report failure — never a partial guess — when no candidate resolves, geocoding fails, or no candidate lies within the radius  
**AND** never persist device coordinates

## Acronyms

| Acronym | Meaning |
|---------|---------|
| ANP | Agência Nacional do Petróleo, Gás Natural e Biocombustíveis |
| IBGE | Instituto Brasileiro de Geografia e Estatística |
| LPC | Levantamento de Preços de Combustíveis (Fuel Price Survey) |
| CNPJ | Cadastro Nacional da Pessoa Jurídica (Brazilian company tax ID) |
| CNG | Compressed Natural Gas (GNV in Brazil) |
| LPG | Liquefied Petroleum Gas (GLP in Brazil) |
| OSM | OpenStreetMap — data provider for Nominatim geocoding |