docs(atlas): say what the country resolver costs the dashboard, and why

The resolver's comment claimed the places of a city trip share their
coordinates, which they do not. It now says what an uncached place costs
per count and why the dashboard does not queue the Atlas region lookup:
that lookup falls back to Nominatim, and a dashboard load must not send a
user's places to a third party.

The #2875 cases continue the file's AUTH-DB numbering.
This commit is contained in:
Maurice
2026-10-29 15:11:39 +01:00
parent 28a577df5e
commit 724857fc73
2 changed files with 16 additions and 9 deletions
+9 -2
View File
@@ -11,8 +11,15 @@ type LocatedPlace = Pick<PlaceRow, 'lat' | 'lng' | 'address'>;
* background lookup has not finished holds no row there, so a count that read the
* cache alone lost countries the Atlas map shows.
*
* The border lookup is a point-in-polygon test, so each resolver runs it once per
* location: the places of a city trip mostly share their coordinates or address.
* A place without a cached region costs a border lookup on every count: a box
* prefilter, then a point-in-polygon test against the few countries whose box
* holds the point. The resolver runs it once per distinct coordinates and
* address, which only spares repeats of one place (a hotel added to every night
* of a stay, say), since every place keeps its own pin. The dashboard pays this on purpose rather than
* queueing the region lookup the Atlas runs: that lookup falls back to Nominatim
* where the bundle has no region, and a dashboard load must not send a user's
* places to a third party. place_regions fills up once the Atlas looks the places
* up, and from then on the count reads the cache.
*/
export function placeCountryResolver(): (place: LocatedPlace, cached: string | null | undefined) => string | null {
const byLocation = new Map<string, string | null>();
@@ -300,7 +300,7 @@ describe('place countries without a cached region (#2875)', () => {
});
}
it('TRAVEL-2875-001: a place in Vatican City stamps VA on the passport card', async () => {
it('AUTH-DB-123: a place in Vatican City stamps VA on the passport card', async () => {
const { user } = createUser(testDb);
const trip = createTrip(testDb, user.id, { title: 'Rome', start_date: PAST_START, end_date: PAST_END });
await addPlace(trip.id, "St. Peter's Basilica", VATICAN);
@@ -308,7 +308,7 @@ describe('place countries without a cached region (#2875)', () => {
expect((await atlas.getTravelStats(user.id)).countries).toContain('VA');
});
it('TRAVEL-2875-002: any place still waiting for its region lookup counts by its borders', async () => {
it('AUTH-DB-124: any place still waiting for its region lookup counts by its borders', async () => {
const { user } = createUser(testDb);
const trip = createTrip(testDb, user.id, { title: 'Paris', start_date: PAST_START, end_date: PAST_END });
await addPlace(trip.id, 'Louvre', { lat: 48.8606, lng: 2.3376 });
@@ -316,7 +316,7 @@ describe('place countries without a cached region (#2875)', () => {
expect((await atlas.getTravelStats(user.id)).countries).toEqual(['FR']);
});
it('TRAVEL-2875-003: the passport card and the Atlas map list the same visited countries', async () => {
it('AUTH-DB-125: the passport card and the Atlas map list the same visited countries', async () => {
const { user } = createUser(testDb);
const trip = createTrip(testDb, user.id, { title: 'Rome', start_date: PAST_START, end_date: PAST_END });
await addPlace(trip.id, "St. Peter's Basilica", VATICAN);
@@ -331,7 +331,7 @@ describe('place countries without a cached region (#2875)', () => {
expect([...(await atlas.getTravelStats(user.id)).countries].sort()).toEqual(atlasVisited);
});
it('TRAVEL-2875-004: a Vatican place on a trip that has not started stays off the card (#1048)', async () => {
it('AUTH-DB-126: a Vatican place on a trip that has not started stays off the card (#1048)', async () => {
const { user } = createUser(testDb);
const start = new Date(Date.now() + 30 * 86_400_000).toISOString().slice(0, 10);
const trip = createTrip(testDb, user.id, { title: 'Rome, next month', start_date: start, end_date: start });
@@ -340,7 +340,7 @@ describe('place countries without a cached region (#2875)', () => {
expect((await atlas.getTravelStats(user.id)).countries).not.toContain('VA');
});
it('TRAVEL-2875-005: a place without coordinates counts by a country its address spells out, never by a bare code (#2111)', async () => {
it('AUTH-DB-127: a place without coordinates counts by a country its address spells out, never by a bare code (#2111)', async () => {
const { user } = createUser(testDb);
const named = createTrip(testDb, user.id, { title: 'Named', start_date: PAST_START, end_date: PAST_END });
await addPlace(named.id, 'Vatican Museums', { address: 'Viale Vaticano, Vatican City' });
@@ -354,7 +354,7 @@ describe('place countries without a cached region (#2875)', () => {
expect((await atlas.getTravelStats(other.id)).countries).toEqual([]);
});
it('TRAVEL-2875-006: the last trip names Vatican City when that is all it went to', async () => {
it('AUTH-DB-128: the last trip names Vatican City when that is all it went to', async () => {
const { user } = createUser(testDb);
const trip = createTrip(testDb, user.id, {
title: 'Day in the Vatican',
@@ -367,7 +367,7 @@ describe('place countries without a cached region (#2875)', () => {
expect((await atlas.lastTrip(user.id))?.countries).toEqual(['VA']);
});
it('TRAVEL-2875-007: the last trip ranks cached and resolved places together, most places first', async () => {
it('AUTH-DB-129: the last trip ranks cached and resolved places together, most places first', async () => {
const { user } = createUser(testDb);
const trip = createTrip(testDb, user.id, { title: 'Rome', start_date: PAST_START, end_date: PAST_END });
const colosseumId = await addPlace(trip.id, 'Colosseum', { lat: 41.8902, lng: 12.4922 });