diff --git a/_bmad-output/implementation-artifacts/1-4-location-resolution-icao-and-address.md b/_bmad-output/implementation-artifacts/1-4-location-resolution-icao-and-address.md new file mode 100644 index 0000000..4d20c61 --- /dev/null +++ b/_bmad-output/implementation-artifacts/1-4-location-resolution-icao-and-address.md @@ -0,0 +1,141 @@ +# Story 1.4: Location Resolution (ICAO & Address) + +Status: ready-for-dev + +## Story + +As a user setting up the device, +I want to type my home airfield ICAO code or my home address/postcode and have the device resolve it to coordinates and show the result for confirmation, +So that I can verify the device is centred on the correct location before committing. + +## Acceptance Criteria + +1. **Given** the user enters a valid ICAO code (e.g. `EGLL`) **When** "Find location" is pressed **Then** the bundled `airports.csv` is queried via `importlib.resources` and the matching lat/lon is returned **And** the resolved location name and coordinates are displayed on the portal for confirmation + +2. **Given** the user enters an address or postcode (e.g. `OX1 1AA`) **When** "Find location" is pressed **Then** the Nominatim API is called once with the input and the resolved lat/lon is displayed for confirmation + +3. **Given** the user enters an ICAO code not present in `airports.csv` **When** "Find location" is pressed **Then** the portal displays: "ICAO code not found — try an address instead" + +4. **Given** Nominatim returns no results **When** "Find location" is pressed **Then** the portal displays: "Location not found — try a different search term" + +5. **Given** tests run in CI **When** location tests execute **Then** Nominatim calls are mocked — no real network calls required in the test suite + +## Tasks / Subtasks + +- [ ] Task 1: Implement `location.resolve(query)` in `src/planemapper/provisioning/location.py` (AC: #1, #2, #3, #4) + - [ ] 1.1 Normalise the input: `query = query.strip().upper()` + - [ ] 1.2 Detect ICAO heuristic: `len(query) == 4 and query.isalpha()` — if true, attempt ICAO lookup first + - [ ] 1.3 ICAO lookup: open `airports.csv` via `importlib.resources.files("planemapper.data").joinpath("airports.csv").open("r", encoding="utf-8")`; parse with `csv.DictReader`; search for row where `row["ident"] == query`; return `(float(row["latitude_deg"]), float(row["longitude_deg"]), row["name"])` + - [ ] 1.4 If ICAO lookup finds no match, raise `ValueError("ICAO code not found — try an address instead")` + - [ ] 1.5 Non-ICAO path: call `requests.get("https://nominatim.openstreetmap.org/search", params={"q": query, "format": "json", "limit": 1}, headers={"User-Agent": "planemapper/0.1 (https://github.com/football2801/planeMapper)"}, timeout=10)` + - [ ] 1.6 Parse Nominatim response: if `results` list is non-empty, return `(float(results[0]["lat"]), float(results[0]["lon"]), results[0]["display_name"])` + - [ ] 1.7 If Nominatim returns an empty list, raise `ValueError("Location not found — try a different search term")` + - [ ] 1.8 Annotate the function signature: `def resolve(query: str) -> tuple[float, float, str]` + +- [ ] Task 2: Add `POST /find-location` route to `src/planemapper/provisioning/portal.py` (AC: #1, #2, #3, #4) + - [ ] 2.1 Import `location` from `planemapper.provisioning` at the top of `portal.py` + - [ ] 2.2 Implement `POST /find-location` — read `request.form["location"]` field + - [ ] 2.3 Call `location.resolve(query)` inside a `try/except ValueError` + - [ ] 2.4 On success: return updated form HTML showing the resolved name and coordinates (e.g. a confirmation section with `lat`, `lon`, `name` values visible) and hidden fields pre-populated with `lat`/`lon` for subsequent form submit + - [ ] 2.5 On `ValueError`: return updated form HTML with the error message displayed inline (no 4xx status — keep the form usable) + - [ ] 2.6 Annotate the route function with return type `str | Response` + +- [ ] Task 3: Write tests in `tests/provisioning/test_location.py` (AC: #1, #2, #3, #4, #5) + - [ ] 3.1 Test ICAO lookup hit: call `resolve("EGLL")` against the real `airports.csv`; assert returned `(lat, lon, name)` is a `tuple[float, float, str]` with plausible UK coordinates + - [ ] 3.2 Test ICAO lookup miss: call `resolve("ZZZZ")`; assert `ValueError` is raised with message `"ICAO code not found — try an address instead"` + - [ ] 3.3 Test Nominatim success: patch `planemapper.provisioning.location.requests.get` with `unittest.mock.patch`; mock return value `.json()` returns `[{"lat": "51.5", "lon": "-0.1", "display_name": "London"}]`; call `resolve("OX1 1AA")`; assert `(51.5, -0.1, "London")` returned + - [ ] 3.4 Test Nominatim empty response: patch `requests.get` as above but `.json()` returns `[]`; call `resolve("nonsense query")`; assert `ValueError` is raised with message `"Location not found — try a different search term"` + - [ ] 3.5 Assert the mock was called exactly once with the expected URL and `User-Agent` header (confirms no real HTTP in CI) + +- [ ] Task 4: Update portal tests in `tests/provisioning/test_portal.py` (AC: #1, #2, #3, #4) + - [ ] 4.1 Add test for `POST /find-location` with a successful resolve (mock `location.resolve` to return `(51.5, -0.1, "London")`); assert 200 and that the response body contains the resolved name and coordinates + - [ ] 4.2 Add test for `POST /find-location` with a `ValueError` from `location.resolve`; assert 200 and that the response body contains the error message text + +- [ ] Task 5: Run quality gates + - [ ] 5.1 `pytest tests/` — all tests pass, 0 failures + - [ ] 5.2 `ruff check .` — zero violations + - [ ] 5.3 `ruff format --check .` — no formatting issues + +## Dev Notes + +### CSV parsing via `importlib.resources` + +Use `csv.DictReader` and access the bundled file through `importlib.resources`: + +```python +import csv +import importlib.resources + +def _lookup_icao(code: str) -> tuple[float, float, str] | None: + traversable = importlib.resources.files("planemapper.data").joinpath("airports.csv") + with traversable.open("r", encoding="utf-8") as fh: + reader = csv.DictReader(fh) + for row in reader: + if row["ident"] == code: + return float(row["latitude_deg"]), float(row["longitude_deg"]), row["name"] + return None +``` + +OurAirports CSV columns used: `ident` (4-letter ICAO code), `name`, `latitude_deg`, `longitude_deg`. + +### ICAO detection heuristic + +```python +query = query.strip().upper() +if len(query) == 4 and query.isalpha(): + # try ICAO first +``` + +This is not a perfect ICAO validator but is sufficient for MVP. A 4-letter all-alpha string is almost certainly an ICAO code in this context. + +### Nominatim call + +```python +import requests + +NOMINATIM_URL = "https://nominatim.openstreetmap.org/search" +USER_AGENT = "planemapper/0.1 (https://github.com/football2801/planeMapper)" + +def _geocode(query: str) -> tuple[float, float, str] | None: + resp = requests.get( + NOMINATIM_URL, + params={"q": query, "format": "json", "limit": 1}, + headers={"User-Agent": USER_AGENT}, + timeout=10, + ) + resp.raise_for_status() + results = resp.json() + if not results: + return None + r = results[0] + return float(r["lat"]), float(r["lon"]), r["display_name"] +``` + +The `User-Agent` header is required by Nominatim's usage policy. + +### Return type and coordinate convention + +`resolve(query: str) -> tuple[float, float, str]` — always `(lat, lon, name)`, never `(lon, lat)`. This convention is used throughout the codebase. + +### Test mock path + +```python +from unittest.mock import patch, MagicMock + +@patch("planemapper.provisioning.location.requests.get") +def test_nominatim_success(mock_get): + mock_resp = MagicMock() + mock_resp.json.return_value = [{"lat": "51.5", "lon": "-0.1", "display_name": "London"}] + mock_get.return_value = mock_resp + lat, lon, name = resolve("OX1 1AA") + assert lat == 51.5 + assert lon == -0.1 + assert name == "London" + mock_get.assert_called_once() +``` + +Patching at `planemapper.provisioning.location.requests.get` (the module where `requests` is imported, not the `requests` package directly) ensures no real HTTP calls reach Nominatim in CI. + +### `airports.csv` file path + +The CSV must be declared as package data in `pyproject.toml` (or `setup.cfg`) so that `importlib.resources` can find it at runtime and during tests. Confirm `[tool.setuptools.package-data]` includes `"planemapper.data" = ["*.csv"]` (this should already be in place from Story 1.1 scaffold). diff --git a/_bmad-output/implementation-artifacts/sprint-status.yaml b/_bmad-output/implementation-artifacts/sprint-status.yaml index 99bbe89..4bbe605 100644 --- a/_bmad-output/implementation-artifacts/sprint-status.yaml +++ b/_bmad-output/implementation-artifacts/sprint-status.yaml @@ -47,7 +47,7 @@ development_status: 1-1-project-scaffold-and-verified-entry-points: done 1-2-configuration-read-write-wipe: done 1-3-wifi-hotspot-and-captive-portal-form: done - 1-4-location-resolution-icao-and-address: backlog + 1-4-location-resolution-icao-and-address: ready-for-dev 1-5-provisioning-execution-tile-download-cache-validation-and-wifi-kill: backlog epic-1-retrospective: optional