Alby96andClaude Opus 5
b4b8d089e6
Puts the controls that change what the map is looking at over the map itself, where they act, and gives them something to search. Search is one field, not two. A string either parses as coordinates or it does not, and the answer is obvious from the text, so making the user declare up front which kind of thing they are looking for would be asking them to do the program's job. Coordinates accept decimal and degrees-minutes-seconds, comma or space separated, with hemisphere letters — including the Italian O for ovest, because someone reading an Italian map will type it and silently reading it as east would put them the wrong side of Greenwich. The 1180 Piedmont municipalities are bundled rather than geocoded online. The app is region-scoped, so a list of one region's towns is small enough to ship (100 KB) and beats a geocoder on every axis that matters: instant, offline, no API key, no rate limit, and it cannot return a result somewhere the app has no radar for. Matching folds accents, so "aglie" finds "Agliè", and prefix matches outrank substring ones — typing "tor" should surface Torino, not the first alphabetical name that happens to contain those letters. tool/generate_places.py derives the list from Istat boundary shapefiles (CC BY 4.0). Two properties of that file cost time and are now written down: the geometry is UTM 32N rather than degrees, and the DBF is UTF-8 despite one bilingual Friulian record that makes strict cp1252 fail. A terminal renders utf-8 and latin-1 output identically, so the encoding cannot be settled by looking at printed text — it took dumping codepoints. A guard in the generator and a test against the shipped asset both check for mojibake now, and the guard caught a real mistake the moment it was written. The target selector switches between following the device, a saved place, and the whole region, and the selection doubles as what the app reopens on: "the place I marked" and "what I see when I open the app" are one idea to the person using it. Dragging the map while it is following stops the camera chasing them but leaves that preference alone, because looking somewhere else now is not the same as changing their mind about next launch. The position marker and the following are MapLibre's own, driven by onCameraTrackingDismissed, so there is no second location stream to keep in step with the map. A test asserts that all 1180 municipalities fall inside the region bounds, which is what actually validates the UTM-to-degrees conversion end to end. Verified on the emulator: the dropdown lists follow, region and both saved places; "aglie" finds Agliè; "44.3841 7.5426" offers the coordinate jump and lands on Cuneo at town-reading zoom; selecting follow moves the map to the device position with the blue dot on it and changes the recentre button to match. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
225 lines
10 KiB
Markdown
225 lines
10 KiB
Markdown
# Roadmap
|
|
|
|
Each milestone ends with `tool/verify.ps1` green and one commit. A milestone is not
|
|
done until its acceptance criteria hold, **and until it has been seen running on the
|
|
emulator** — twice now that step has caught defects the tests did not.
|
|
|
|
Legend: ✅ done · 🔨 in progress · ⛔ blocked on something the project owner must supply
|
|
|
|
> **Scope**: radar on a map, saved places, ground-station observations, official alerts,
|
|
> rain notifications. Forecasts, lightning, a home-screen widget and advertising are all
|
|
> out — see CLAUDE.md.
|
|
|
|
---
|
|
|
|
## M0 — Toolchain and repository hygiene ✅
|
|
|
|
Flutter 3.47.3 stable, Android SDK (platform-tools, platform 36, build-tools 36.0.0),
|
|
JDK 21, environment variables. Commit the removal of the old Xamarin skeleton.
|
|
|
|
**Done.** `flutter doctor -v` reports "No issues found!". Installed: Flutter 3.47.3 at
|
|
`C:\src\flutter` (telemetry disabled), Android SDK at `C:\Android\Sdk` with platform 36,
|
|
build-tools 36.0.0, platform-tools and all licences accepted, and `JAVA_HOME` pointing at
|
|
the JDK 21 a previous Visual Studio install had already left on the machine.
|
|
|
|
## M1 — Scaffold, Italian l10n, region config, CI ✅
|
|
|
|
`flutter create` with applicationId `it.nuvolari.app`; `flutter_localizations` + `intl`
|
|
with `app_it.arb` as template and no hardcoded UI strings; `RegionConfig` loaded from
|
|
`assets/regions/piemonte.json` with parsing tests; `.gitignore`, `env.example.json`,
|
|
`tool/verify.ps1`, `.gitea/workflows/ci.yml`.
|
|
|
|
**Done.** All four stages green; the AAB carries applicationId `it.nuvolari.app`,
|
|
minSdk 24, targetSdk 36. Tests assert against the shipped Piemonte asset and a captured
|
|
copy of the live ARPA CAP feed.
|
|
|
|
> The Gitea instance may have no Actions runner. The workflow file is written to be
|
|
> GitHub-Actions compatible, but `tool/verify.ps1` is the verification that must pass.
|
|
|
|
## M2 — Map, attribution, Sources screen ✅
|
|
|
|
MapLibre on OpenStreetMap tiles, permanent OSM/OpenMapTiles attribution, and a
|
|
Sources / Licenses / Disclaimer screen with the explicit "not an official app"
|
|
disclaimer.
|
|
|
|
**Done and verified on the emulator.** The attribution bar lists only the sources
|
|
actually rendered — crediting OpenStreetMap while showing the offline fallback would be
|
|
a false attribution — and sits below the map, inside a SafeArea, so neither a map control
|
|
nor the system gesture pill can cover a credit the licences require to be visible.
|
|
|
|
Running it caught two defects the unit tests could not: the configured initial zoom put
|
|
the viewport entirely inside the region so the map read as a blank expanse, and the
|
|
attribution bar sat behind the gesture pill. The camera now fits the region bounds at
|
|
runtime, which works at any screen size.
|
|
|
|
## M3 — Animation and timeline ✅
|
|
|
|
`RadarSource` with `MockRadarSource` (synthetic frames in assets), `DpcRadarSource`
|
|
(reads our CDN) and `ArpaRadarSource` (disabled stub). Timeline scrubber, play/pause,
|
|
adjacent-frame prefetch, `FrameCache` LRU, animation suspended in background, graceful
|
|
degradation with a data-age banner.
|
|
|
|
**Done and verified on the emulator.** The overlay is double buffered, the timeline
|
|
lands on the newest frame, playback advances and wraps, scrubbing takes over from
|
|
playback, and the legend is drawn from the manifest rather than a constant.
|
|
|
|
Running it caught three more defects:
|
|
|
|
- The notifier wrote to `state` from inside `build()`, which Riverpod rejects as an
|
|
uninitialised provider. This broke startup, not just tests.
|
|
- Eight-month-old demo frames rendered as "Aggiornato 342535 minuti fa". The age
|
|
formatter now steps up to hours and days.
|
|
- Demo mode sat permanently behind a stale-data warning, so it never showed the
|
|
working state it exists to demonstrate. `MockRadarSource` now shifts the bundled
|
|
timestamps onto the present, leaving images, order and spacing untouched.
|
|
|
|
Frame caching is in memory only for now: mock frames are already in the asset bundle
|
|
and a disk layer belongs with the network adapter, where it would save a real request.
|
|
|
|
---
|
|
|
|
## M4 — Places, search and device location ✅
|
|
|
|
A named point the user keeps, used to frame the map and — once notifications exist — to
|
|
anchor them. Stored in `SharedPreferences` on the device and nowhere else.
|
|
|
|
**Done and verified on the emulator.** The prominent disclosure appears before the
|
|
system dialog, the permission is optional throughout, places survive an app restart and
|
|
a reinstall, and tapping one moves the map onto it.
|
|
|
|
Running it caught three defects the tests could not:
|
|
|
|
- `geolocator` injects `ACCESS_FINE_LOCATION` into the merged manifest, so the system
|
|
dialog offered "Precise" despite the app declaring only coarse. Removed with
|
|
`tools:node="remove"`; the dialog now reads "approximate location" and offers no
|
|
choice.
|
|
- The Play Services fused provider prompts about Location Accuracy, and declining it
|
|
yields no fix at all. Switched to the platform `LocationManager`, which also drops the
|
|
Play Services dependency.
|
|
- `MapLibreMap` leaves `cameraPosition` null unless `trackCameraPosition` is set, so
|
|
"save the map centre" silently saved the region default instead of what the user was
|
|
looking at.
|
|
|
|
A unit test also caught an id collision: ids came straight from the microsecond clock,
|
|
so two places saved in the same microsecond shared an id and rename, remove and the
|
|
duplicate check all acted on the wrong one.
|
|
|
|
**Extended** with search and a target selector, also verified on the emulator:
|
|
|
|
- One search field takes either a municipality name or coordinates, because a string
|
|
either parses as coordinates or it does not and the user should not have to declare
|
|
which they meant. Accent-insensitive: typing "aglie" finds "Agliè". Coordinates accept
|
|
decimal and degrees-minutes-seconds, comma or space separated, with hemisphere letters
|
|
including the Italian **O** for west.
|
|
- The 1180 municipalities are bundled from Istat boundaries rather than geocoded online.
|
|
A test asserts every one of them falls inside the region bounds, which is what
|
|
validates the UTM-to-degrees conversion end to end.
|
|
- A dropdown over the map switches between following the device, a saved place, and the
|
|
whole region; the selection is also what the app reopens on. Dragging the map while it
|
|
is following stops the camera chasing but leaves that preference alone.
|
|
- The blue position marker and the following are MapLibre's own, so there is no custom
|
|
location stream to keep in step with the map.
|
|
|
|
## M5 — Backend worker ⛔
|
|
|
|
The critical path. Until this exists, `DpcRadarSource` has nothing to read and the app
|
|
can only show demo frames.
|
|
|
|
`backend/nuvolari_worker/`: `dpc_client` (with the `origin` header), `crop` (bbox +
|
|
reproject to EPSG:3857 — the source CRS is read from each file, never assumed),
|
|
`palette` (dBZ colormap, legend exported into the manifest), `render` (RGBA PNG,
|
|
transparent below threshold), `manifest`, and a `publisher/` with `LocalPublisher` and
|
|
`S3Publisher`. Also publishes, so the app never polls ARPA directly:
|
|
|
|
- `alerts.json` from the ARPA CAP bulletin;
|
|
- `stations.json` from the ARPA realtime API — rain accumulations
|
|
(1/3/6/12/24 h) and 72 hours of hourly temperature for the 374 stations, joined to
|
|
their coordinates from `/pie_anag`. The feed lags about 4.5 hours, so every reading
|
|
carries its own timestamp and the UI must present it as an observation, never as the
|
|
current conditions.
|
|
|
|
WebSocket trigger on `wss://radar-wss.protezionecivile.it`, with a 5-minute cron as
|
|
fallback.
|
|
|
|
**Accepts when:** `python -m pytest` passes and one full run produces PNGs plus a
|
|
`manifest.json` that the app consumes from a local server, showing real Piedmont
|
|
precipitation on the emulator.
|
|
|
|
**Blocked on (publishing only):** VPS / object storage endpoint and credentials.
|
|
Development proceeds against `LocalPublisher` and a LAN `python -m http.server`.
|
|
|
|
## M6 — Official alerts
|
|
|
|
`ArpaCapAlertSource` reading `alerts.json` from our CDN. Zones `Piem-A`…`Piem-M` with
|
|
levels shown **verbatim** and a link to the official bulletin next to every one.
|
|
|
|
Six level values, not four: `VERDE`, `GIALLO`, `ARANCIONE`, `ROSSO`, plus `BIANCO`
|
|
(avalanche scale, out of season) and `-` (not published). `BIANCO` and `-` are their own
|
|
state and must never be collapsed into `VERDE` — that would report "no alert" where the
|
|
bulletin reports "not assessed".
|
|
|
|
**Accepts when:** the eleven zones render with the levels the live feed carries, the
|
|
captured fixture parses, and every alert view links the official bulletin.
|
|
|
|
## M7 — Rain notifications ⛔
|
|
|
|
FCM topics per geographic cell, subscribed **from the device**, so no user location ever
|
|
reaches a server. The worker publishes per-cell rain state.
|
|
|
|
**Accepts when:** subscribing and unsubscribing works, and a published cell state
|
|
produces a notification on the emulator.
|
|
|
|
**Blocked on:** Firebase project and `google-services.json`.
|
|
|
|
## M8 — Play Store release preparation ⛔
|
|
|
|
Signing config reading `key.properties`, release AAB, target API 36, privacy policy,
|
|
store listing copy, Data safety declaration, prominent disclosure for location.
|
|
|
|
Data safety is unusually simple here: no advertising, no analytics, no accounts, and no
|
|
location leaving the device.
|
|
|
|
**Blocked on:** upload keystore and Play Console account.
|
|
|
|
---
|
|
|
|
## Pending inputs from the project owner
|
|
|
|
| Needed for | Item |
|
|
|---|---|
|
|
| M5 | VPS / object storage endpoint and credentials |
|
|
| M7 | Firebase project and `google-services.json` |
|
|
| M8 | Play Console account and upload keystore |
|
|
| ARPA radar adapter | The email to `info.meteo@arpa.piemonte.it` asking for the real-time access link **and the reuse licence**. Free of charge is not a licence, and without stated terms the frames cannot be republished. |
|
|
|
|
Nothing is needed for the base map: OpenFreeMap requires no key and no account.
|
|
|
|
---
|
|
|
|
## Verifying on the emulator
|
|
|
|
An AVD named `nuvolari` is set up on this machine: API 36.1, `google_apis`, x86_64,
|
|
GPU passthrough to the host. It uses a 2 GB data partition and no SD card because disk
|
|
is tight, and quickboot snapshots are disabled — they cost 2.6 GB to save a few seconds
|
|
of boot, which is the wrong trade here. Expect a cold boot of a minute or so.
|
|
|
|
In VS Code, just press **F5**: every emulator debug configuration boots it first. From a
|
|
shell:
|
|
|
|
```bash
|
|
# Boot it (idempotent — returns at once if a device is attached)
|
|
powershell -File tool/start_emulator.ps1
|
|
|
|
# Build, install, launch
|
|
cd app
|
|
flutter build apk --debug
|
|
adb install -r build/app/outputs/flutter-apk/app-debug.apk
|
|
adb shell am start -n it.nuvolari.app/.MainActivity
|
|
|
|
# Capture what it looks like
|
|
adb exec-out screencap -p > screen.png
|
|
```
|
|
|
|
`flutter run -d emulator-5554` works too and gives hot reload; the steps above are what
|
|
a non-interactive session uses.
|