EventHub/EventHubSpec
3
1
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(geo): канон переведён на внешний геокодер OpenCage

Browse Source 
Стек/Ops/контракт: OpenCage API через прокси бэкенда, ключ не покидает
сервер; source=opencage; free-тариф 2500 запросов/сутки и 1 rps,
402/403/429 апстрима -> 503 geo_unavailable; ToS разрешает хранение
результатов. Self-host Photon исключён из стека.

Refs EventHub/EventHubSpec#21
This commit is contained in:
Aleksey Sabilin
2026-08-18 23:30:23 +03:00
parent 588a282b6d
commit b79fd81260
3 changed files with 23 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files
GEO.md
+19 -19
View File
@@ -19,7 +19,7 @@
**Не используем:** Google Maps JavaScript API, Geocoding/Places, Яндекс JS API / Геокодер, ключи карт.
**Разрешено:** outbound-ссылки на Google Maps и Яндекс.Карты с **нашими** координатами (Photon или пин пользователя). Это не вызов их API и не хранение их ответа.
**Разрешено:** outbound-ссылки на Google Maps и Яндекс.Карты с **нашими** координатами (OpenCage или пин пользователя). Это не вызов их API и не хранение их ответа.
## Стек (вариант Ц)
@@ -27,18 +27,18 @@
|------|--------|----------|
| Карта в браузере | [MapLibre GL JS](https://maplibre.org/) | Leaflet + растр `tile.openstreetmap.org` (политика тайлов OSMF) |
| Тайлы | [OpenFreeMap](https://openfreemap.org/) публичный инстанс, без ключа | Carto/MapTiler Free (не для коммерции EventHub); свой tile-server |
| Геокод | **свой Photon** (Komoot), прокси только через EventHubBack | публичный Nominatim OSMF (1 rps, autocomplete запрещён); `photon.komoot.io` |
| Геокод | **[OpenCage](https://opencagedata.com)** (внешний API), прокси только через EventHubBack, ключ не покидает бэкенд | публичный Nominatim OSMF (1 rps, autocomplete запрещён); `photon.komoot.io`; self-host Photon (вес индекса, RAM) |
| Хранение | `address` + `lat`/`lon` в EventHub | `place_id` Google, сырой ответ Яндекса |
Данные OSM — [ODbL](https://www.openstreetmap.org/copyright). На карте видимая атрибуция: «© OpenStreetMap contributors» со ссылкой на copyright. Не выгружаем базу OSM оптом через Photon.
ToS OpenCage разрешает бессрочно хранить результаты геокодирования — кэш и сохранённые координаты события легальны. Данные OSM — [ODbL](https://www.openstreetmap.org/copyright). На карте видимая атрибуция: «© OpenStreetMap contributors» со ссылкой на copyright.
```
Front (MapLibre) --tiles--> OpenFreeMap
Front --suggest/geocode/reverse--> Back /v1/geo --> Photon (self-host)
Front --suggest/geocode/reverse--> Back /v1/geo --> OpenCage API (ключ в env бэка)
Back --persist--> event.location / calendar.settings.default_location
```
Front **не** ходит в Photon и Nominatim напрямую.
Front **не** ходит в OpenCage и Nominatim напрямую (ключ не должен попасть в браузер).
## Модель данных (уже есть)
@@ -53,7 +53,7 @@ Front **не** ходит в Photon и Nominatim напрямую.
## API геокодирования (контракт Back#77)
`POST` geocode/reverse: user Bearer (пикер). `GET /v1/geo/suggest`: **без токена** (Discover «центр по адресу» для гостя) + rate-limit по IP; с Bearer — тот же лимит на user. Photon с браузера не светим.
`POST` geocode/reverse: user Bearer (пикер). `GET /v1/geo/suggest`: **без токена** (Discover «центр по адресу» для гостя) + rate-limit по IP; с Bearer — тот же лимит на user. Ключ OpenCage с браузера не светим.
Кэш одинаковых `q`+`lang` (ETS/Mnesia, TTL дни). Таймаут апстрима ~3 s.
@@ -77,29 +77,29 @@ Typeahead. Клиент debounce (≥300 ms). Пустой / слишком ко
Тело: `{ "q": "…", "lang": "ru" }` (`lang` опционален, иначе язык пользователя / `ru`).
- `200`: `{ "address": "…", "lat": 55.75, "lon": 37.62, "source": "photon" }`
- `200`: `{ "address": "…", "lat": 55.75, "lon": 37.62, "source": "opencage" }`
- нет хита: `404` `{error: "not_found"}`
- Photon недоступен / таймаут: `503` `{error: "geo_unavailable"}` — **не** 500
- OpenCage недоступен / таймаут / квота (402/403/429): `503` `{error: "geo_unavailable"}` — **не** 500
### `POST /v1/geo/reverse`
Тело: `{ "lat": 55.75, "lon": 37.62, "lang": "ru" }`. Подпись пина после drag.
Тот же shape, что geocode (`source: "photon"`). Нет хита → `200` с `address` из округлённых координат или короткий fallback «lat, lon», без падения пикера. `503` только если Photon недоступен.
Тот же shape, что geocode (`source: "opencage"`). Нет хита → `200` с `address` из округлённых координат или короткий fallback «lat, lon», без падения пикера. `503` только если OpenCage недоступен.
### Degrade
- Geo-эндпоинты: `503` / пустой suggest, не 500 на весь API.
- Create/update события и `default_location`: **не** зависят от Photon. Текстовый адрес сохраняется.
- IFT/stage без Photon: сервис живой; e2e пикера пропускают или проверяют degrade (текстовое поле).
- Create/update события и `default_location`: **не** зависят от геокодера. Текстовый адрес сохраняется.
- IFT/stage без ключа OpenCage: сервис живой; e2e пикера пропускают или проверяют degrade (текстовое поле).
## Ops (контракт DevOps#16)
Не API-ключи Google/Яндекс.
- Compose-сервис **Photon** (JAR + OpenSearch) + volume индекса. Не публиковать Photon в интернет; только сеть compose → EventHubBack.
- Env бэкенда: `PHOTON_URL` (например `http://photon:2322`), `PHOTON_TIMEOUT_MS`. Нет map API keys.
- Выгрузка OSM: **минимум РФ** (+ СНГ/крупные города, если диск позволяет). Planet — если влезает. Обновление индекса — периодический job, не realtime.
- Своего контейнера геокодера нет: бэкенд ходит во внешний OpenCage API (`https://api.opencagedata.com/geocode/v1/json`).
- Env бэкенда: `OPENCAGE_API_KEY` (секрет, только в `.env` стендов), `OPENCAGE_TIMEOUT_MS`, опционально `OPENCAGE_COUNTRYCODE`, `OPENCAGE_THROTTLE_RPS` (1 rps под free-тариф). Нет map API keys.
- Free-тариф OpenCage: 2500 запросов/сутки, 1 rps; 402/403/429 апстрима → `503 geo_unavailable`. ToS разрешает хранение результатов.
- CSP (Traefik / Front): тайлы OpenFreeMap, не Google/Yandex script.
Ориентир CSP (уточнить по фактическому style URL):
@@ -111,9 +111,9 @@ font-src 'self' data: https://fonts.gstatic.com https://tiles.openfreemap.org
worker-src 'self' blob:
```
Geo — same-origin `/v1/geo`. IFT/stage: Photon в compose; без контейнера — degrade, не падение EventHub.
Geo — same-origin `/v1/geo`. IFT/stage: ключ OpenCage в `.env` стенда; без ключа — degrade, не падение EventHub.
**Stage:** свой Photon не запускаем (`PHOTON_URL` пустой). Не используем `photon.komoot.io` как апстрим. Пикер адреса — на IFT при включённом Photon; на stage — текстовый адрес / пин. GPS «рядом» работает без геокодера.
**Stage:** ключ OpenCage в `.env` (внешний сервис — без нагрузки на VPS). Пикер адреса работает на всех стендах с ключом; без ключа — текстовый адрес / пин. GPS «рядом» работает без геокодера.
## Front (контракт Front#74)
@@ -128,7 +128,7 @@ Geo — same-origin `/v1/geo`. IFT/stage: Photon в compose; без контей
3. Мини-карта, перетаскиваемый пин → `POST /v1/geo/reverse`.
4. Ручной lat/lon можно спрятать (advanced), не убирать из контракта API.
Photon `503`: тост/подсказка, карта и ручной адрес остаются.
OpenCage `503`: тост/подсказка, карта и ручной адрес остаются.
### Карточка / просмотр
@@ -219,7 +219,7 @@ Geo-режим, клиент не передал `sort` → **`distance` asc**.
## Критерии приёмки канона
- [x] Этот документ согласован (Spec#21, вариант Ц).
- [ ] DevOps#16: Photon в compose, `PHOTON_URL`, CSP OpenFreeMap; без Google/Yandex keys.
- [ ] Back#77: `/v1/geo/*`, кэш, address-only location; search: geo по календарям, optional radius, `sort=distance`, `distance_km`; тесты (mock Photon).
- [ ] DevOps#16: ключ OpenCage в `.env` стендов, CSP OpenFreeMap; без Google/Yandex keys.
- [ ] Back#77: `/v1/geo/*`, кэш, address-only location; search: geo по календарям, optional radius, `sort=distance`, `distance_km`; тесты (mock OpenCage).
- [ ] Front#74: пикер + мини-карта + outbound Google/Яндекс/OSM; Discover ближайшие (GPS/адрес, пресеты радиуса); e2e/mock.
- [ ] После тестов: BackSpec/FrontSpec сверены с кодом.