Break v3 into 16 tickets

One file per feature, in the v2 shape that worked: goal, context, design,
implementation, acceptance criteria, tests, risks, out of scope -- written before
implementing so the risks are on paper rather than walked into.

Three carry more weight than their size suggests. V3-01 ships the port's first
real migration, and since the destructive fallback is gone, getting addColumn and
a v1-database test right matters more than the feature. V3-08 forces a
routing-engine decision with ongoing cost, so it sits behind a RoutingService
interface mirroring what LocationSource did for GPS. V3-13 is not code at all --
it answers the three questions open since v2, and V3-15 may close unbuilt as a
result, which is a legitimate outcome.

Several tickets record constraints that are easy to lose: no activity picker in
front of Start, because the founding premise is press-and-go with gloves; the
Route-to-Trip foreign key must not cascade, or deleting an old plan deletes the
ride; V3-14 will deliberately break the parity harness by adding GPX <type>, and
that expectation should be updated rather than the check dropped; and V3-16 must
not regress the explicit text colours that exist because of the black-on-black bug.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
2026-08-17 10:41:35 -05:00
parent 82754de9c4
commit 342a8f8382
19 changed files with 982 additions and 0 deletions

View File

@@ -0,0 +1,51 @@
# V3-11 — Offline tile pre-download
**Phase** Ride management · **Depends on** V3-04 · **Size** M · **Status** Not started
## Goal
Have map tiles available where there is no signal.
## Context
`flutter_map` caches what it renders, so a re-viewed ride works. A **mountain ride with no
signal shows blank tiles** — precisely where a map is most wanted.
## Design
**Respect OSM's tile usage policy. Bulk prefetching their public servers is prohibited**
and would get the app blocked. This constraint decides the design:
- Pre-download only a **user-chosen area**, at a **limited zoom range**, with a visible
tile count and size estimate before starting
- Rate-limited, sequential, cancellable
- If this becomes a headline feature, move to a paid tile provider or self-hosted tiles.
Do not scale it on OSM's donated infrastructure.
Natural pairing with V3-07: pre-download the corridor along a planned route rather than a
rectangle — far fewer tiles for the same usefulness.
## Implementation
1. Persistent tile cache with a size cap and eviction (`flutter_map_cache` or similar)
2. Area selection on the map, plus a "download along this route" option
3. Tile count and MB estimate **before** any request
4. Sequential fetch with a delay, a progress indicator and cancellation
5. Settings: cache size, and a way to clear it
## Acceptance criteria
- [ ] A downloaded area renders with the network off
- [ ] Count and size shown before download starts
- [ ] Cancellable mid-download, keeping what has already arrived
- [ ] A hard cap on tiles per request — no unbounded area selection
- [ ] Cache size visible and clearable
## Tests
- Tile-count maths for a bounding box across zoom levels
- Cache eviction at the cap
- Cancellation leaves a consistent cache
- **Manual:** aeroplane mode over a downloaded area
## Risks
- **Abusing OSM's servers.** Cap, rate-limit, and be conservative. A blocked user agent
would break the map for everyone.
- Storage growth. Tiles add up fast; the cap is not optional.
## Out of scope
Vector tiles or a full offline basemap.