release: bump version to 0.49.0
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
linkong
127
docs/technical/en/location-pipeline-user.md
Normal file
127
docs/technical/en/location-pipeline-user.md
Normal file
@@ -0,0 +1,127 @@
|
||||
# Earth Location Candidate Collection User Guide
|
||||
|
||||
Location candidate collection helps fill or verify coordinates for compute centers and BGP collectors on Earth. Users do not type coordinates by hand; the backend ranks source coordinates, open organization-registry results, and online geocoding results into a previewable candidate list.
|
||||
|
||||
## Supported Entities
|
||||
|
||||
Currently supported:
|
||||
|
||||
- Compute centers: TOP500 supercomputers and Epoch AI GPU clusters.
|
||||
- BGP collectors: RIPE RIS `rrcXX` collectors.
|
||||
|
||||
BGP events inherit the location of their owning collector. Events do not have a separate collection button yet; future ASN facility, prefix geography, or PeeringDB resolvers should use the same pipeline.
|
||||
|
||||
## What Users See
|
||||
|
||||
Clicking a compute center or BGP collector on Earth opens a detail card with location fields:
|
||||
|
||||
| Field | Meaning |
|
||||
| --- | --- |
|
||||
| Location precision | Precise coordinates, site-level, city-level, or unconfirmed |
|
||||
| Location source | Source coordinates, ROR organization registry, Nominatim online search, or stored BGP collector locations |
|
||||
| Location confidence | Relative confidence reported by the backend resolver |
|
||||
| Verification status | Confirmed, estimated, or online result pending confirmation |
|
||||
| Resolution reason | Why the location was selected |
|
||||
| Matched location name | Canonical name from an open source, online result, or stored collector location |
|
||||
| Verified at | Verification date for confirmed locations; online candidates are usually empty |
|
||||
|
||||
Compute-center GeoJSON no longer renders country centroids, unknown locations, or `[0, 0]` placeholders. Records that cannot reach city-level precision are returned in the endpoint's `unresolved` list and can be improved through candidate collection.
|
||||
|
||||
A compute center with a `?` marker on Earth is not unresolved. It already has coordinates, but the coordinates still need confirmation, either because `needs_confirmation=true` or because the source is online geocoding. Truly unresolved records have no trustworthy coordinates and are therefore absent from the globe.
|
||||
|
||||
## Collect Candidates
|
||||
|
||||
1. Open `http://localhost:3000/earth`.
|
||||
2. Enable the `Compute centers` or `BGP observation` layer.
|
||||
3. Click an object to open its detail card.
|
||||
4. Click `自动采集坐标候选` or `重新自动采集坐标`.
|
||||
5. Wait for up to five candidates to appear.
|
||||
6. Click `预览` on a candidate row; Earth flies to that latitude and longitude.
|
||||
|
||||
Candidate rows show:
|
||||
|
||||
- Candidate name.
|
||||
- Precision: precise, site, or city.
|
||||
- Resolver source.
|
||||
- Confidence.
|
||||
- Coordinates.
|
||||
|
||||
Clicking `保存` on a candidate row writes the selected compute-center candidate into the location dimension table. After the save succeeds, the compute-center layer refreshes; if the record was previously in the unresolved queue, the unresolved count decreases.
|
||||
|
||||
## Unresolved Queue And Adopt All
|
||||
|
||||
The notification badge on the compute-center layer row shows the current unresolved count. Clicking it opens a fixed queue beside the layer panel:
|
||||
|
||||
1. The queue contains only compute centers without trustworthy coordinates.
|
||||
2. Row-level `采集` calls the candidate endpoint and shows up to five previewable candidates.
|
||||
3. Header-level `一键采用` walks the list from top to bottom, chooses the highest-confidence candidate with valid coordinates, and saves it.
|
||||
4. Each successful save immediately removes that row, renumbers the remaining rows, and updates the badge count.
|
||||
5. When the batch completes, the frontend refreshes the compute-center layer so UI state and backend state converge.
|
||||
|
||||
If a record has no saveable candidate, the system does not invent a country centroid, vendor headquarters, or hard-coded hint. The row stays in the queue with the backend failure reason and attempted queries so an operator can supply better evidence later.
|
||||
|
||||
## Backend APIs
|
||||
|
||||
The frontend buttons call:
|
||||
|
||||
```http
|
||||
POST /api/v1/visualization/compute-centers/{source_id}/collect-location
|
||||
POST /api/v1/visualization/compute-centers/{source_id}/location
|
||||
POST /api/v1/bgp/collectors/{collector_id}/collect-location
|
||||
```
|
||||
|
||||
Both `collect-location` endpoints use the same response shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"candidates": [],
|
||||
"best_candidate": {},
|
||||
"attempted_queries": [],
|
||||
"context": {}
|
||||
}
|
||||
```
|
||||
|
||||
When no candidate reaches city-level precision, `success` is `false` and the response includes `failure_reason` plus the attempted queries. This helps distinguish missing source fields, open-source gaps, and online geocoding misses.
|
||||
|
||||
## Registry Maintenance
|
||||
|
||||
Compute centers and BGP collectors no longer maintain local candidate registries. Compute-center accepted locations are stored in the `compute_center_locations` database dimension table keyed by `(source, source_id)`. BGP collector current locations are stored in the `bgp_collector_locations` database dimension table; the old RIPE RIS city-level coordinates are used only as initialization seed data and still require confirmation.
|
||||
|
||||
For compute centers, prefer maintaining:
|
||||
|
||||
- `source` / `source_id`: for example `top500` + `top500_50`.
|
||||
- `name` / `operator` / `site`.
|
||||
- `city` / `country`.
|
||||
- `latitude` / `longitude`.
|
||||
- `precision`: `precise`, `site`, or `city`.
|
||||
- `confidence`: confidence from 0 to 1.
|
||||
- `location_source` / `source_url` / `source_note` / `raw_payload`: evidence source.
|
||||
- `needs_confirmation` / `verification_status` / `verified_at`: manual verification status and date.
|
||||
|
||||
For BGP collectors, prefer maintaining:
|
||||
|
||||
- `collector_id`: for example `rrc12`.
|
||||
- `site` / `operator`: site and operator.
|
||||
- `city` / `country` / `region`.
|
||||
- `latitude` / `longitude`.
|
||||
- `precision`: `precise`, `site`, or `city`.
|
||||
- `confidence`: confidence from 0 to 1.
|
||||
- `source` / `source_url` / `raw_payload`: evidence source.
|
||||
- `verification_status` / `verified_at`: manual verification status and date.
|
||||
|
||||
If only the city is known, use city-level precision. Do not enter a precise-looking coordinate that has not been verified.
|
||||
|
||||
## Common Questions
|
||||
|
||||
### Why are some compute centers missing on Earth?
|
||||
|
||||
Earth only renders coordinates that reach city-level precision or better. If source data, verified storage, and online geocoding all fail, the record is returned as `unresolved` instead of being rendered at a misleading country center or `[0, 0]`.
|
||||
|
||||
### Why do online results need confirmation?
|
||||
|
||||
Nominatim/OpenStreetMap results may match same-name cities, organizations, or campuses. They are useful for previewing candidates, but should be manually confirmed before being persisted as verified locations.
|
||||
|
||||
### Why do BGP events no longer all land in Amsterdam?
|
||||
|
||||
The old behavior could match common fields like `operator="RIPE NCC"` and incorrectly promote `rrc00`. BGP event inheritance now uses a strict owning-collector lookup in the DB-backed cache instead of registry fuzzy matching.
|
||||
Reference in New Issue
Block a user