docs use cases uc 003 select location

UC-003 — Select Location (State + City)

Field	Value
ID	UC-003
Name	Select Location
Actors	End User
Layer	UI → Application → Domain

Goal

Let the user choose a Brazilian state and municipality to view fuel prices.

Preconditions

• At least one SurveyWeek imported (BR-005).
• DataReadiness is READY, PARTIAL, or STALE.

Main flow

1. User opens location picker from home or search tab.
2. System displays list of 27 BrazilianState values (localized display names via i18n).
3. User selects a state.
4. System loads all catalog municipalities for the state (BR-016), each annotated with DataAvailability for latest SurveyWeek (BR-006).
5. User selects a municipality from the list (including cities without current-week data).
6. System validates selection exists in MunicipalityCatalog.
7. System persists preferredState and preferredMunicipality (BR-012).
8. System emits CitySelected.
9. System navigates to UC-005 (municipality prices).

Alternative flows

A1 — Municipality has no data for selected week

• WHEN municipality list item has DataAvailability.NO_DATA_THIS_WEEK or NEVER_IN_ANP
• THEN allow selection; UC-005 shows informative empty state (BR-010)

A2 — State has no catalog municipalities

• WHEN municipality list is empty for state
• THEN show empty state (BR-010) with message to pick another state

A3 — User changes location from home

• WHEN user already has a preferred city
• THEN picker pre-selects current state/municipality

Business rules

• BR-005, BR-006, BR-010, BR-012, BR-016

Domain events

• CitySelected(municipality, state, surveyWeekId)

Postconditions

• Home screen reflects selected municipality.
• Preference survives app restart.

i18n keys

• location_picker_title
• location_state_label
• location_municipality_label
• location_empty_state
• location_no_data_this_week