docs: document nowcast point alarm clients and paging caveats
This commit is contained in:
@@ -9,6 +9,8 @@ bu ortak yapıyı kullanarak noktalı virgüllü CSV satırlarını sırayla iş
|
|||||||
- `common/`: tekrar kullanılabilir API, HMAC, retry ve authentication katmanı
|
- `common/`: tekrar kullanılabilir API, HMAC, retry ve authentication katmanı
|
||||||
- `login.py`: manuel login komutu
|
- `login.py`: manuel login komutu
|
||||||
- `nowcast-geo-register.py`: CSV geo alarm registration istemcisi
|
- `nowcast-geo-register.py`: CSV geo alarm registration istemcisi
|
||||||
|
- `nowcast-point-page.py`, `nowcast-point-get.py`, `nowcast-point-register.py`, `nowcast-point-update.py`, `nowcast-point-unregister.py`: nokta alarm (`/v1/alarms/points`) istemcileri
|
||||||
|
- `nowcast-point-alarm-filter.example.json`, `nowcast-point-registrations.example.csv`, `nowcast-point-update.example.csv`: nokta alarm şablonları
|
||||||
- `.env.example`: güvenli ortam değişkeni şablonu
|
- `.env.example`: güvenli ortam değişkeni şablonu
|
||||||
- `webhook.example.json`: dört webhook authentication seçeneğini içeren şablon
|
- `webhook.example.json`: dört webhook authentication seçeneğini içeren şablon
|
||||||
- `nowcast-geo-alarm-filter.example.json`: ortak nowcast geo alarm filtreleri şablonu
|
- `nowcast-geo-alarm-filter.example.json`: ortak nowcast geo alarm filtreleri şablonu
|
||||||
@@ -151,3 +153,57 @@ python nowcast-geo-register.py nowcast-geo-alarm-registrations.csv \
|
|||||||
--nowcast-filter-config another-nowcast-geo-alarm-filter.json \
|
--nowcast-filter-config another-nowcast-geo-alarm-filter.json \
|
||||||
--debug-log logs/custom-debug.log
|
--debug-log logs/custom-debug.log
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Nokta alarm (nowcast point) istemcileri
|
||||||
|
|
||||||
|
Nokta alarm istemcileri `BE-NowcastPointAlarm` servisinin `/v1/alarms/points` endpoint'lerini çağırır. Tüm komutlarda `--help` seçeneklerin tam dökümünü verir. Gerçek filtre değerleri için `nowcast-point-alarm-filter.example.json` dosyasını `nowcast-point-alarm-filter.json` olarak kopyalayın (git'e eklenmez). Webhook için mevcut `webhook.json` ve `IKLIM_WEBHOOK_INITIALIZED` mekanizması aynen kullanılır.
|
||||||
|
|
||||||
|
| Komut | Ne yapar |
|
||||||
|
| --- | --- |
|
||||||
|
| `nowcast-point-page.py` | Kayıtları sayfa sayfa listeler; SQLite'a (`iklim-sandbox.db`, `registrationId` anahtarlı) yazar, ekrana basar veya `--output` ile CSV/TXT üretir |
|
||||||
|
| `nowcast-point-get.py` | CSV/TXT içindeki `registrationId` (`--by id`) veya `recipientId` (`--by recipient`) değerlerini sorgular |
|
||||||
|
| `nowcast-point-register.py` | CSV satırlarından kayıt oluşturur |
|
||||||
|
| `nowcast-point-update.py` | CSV satırlarıyla kayıtları kısmen günceller (`--dry-run` destekler) |
|
||||||
|
| `nowcast-point-unregister.py` | Listedeki kayıtları siler (onay ve yedekle) |
|
||||||
|
|
||||||
|
### Önemli uyarılar
|
||||||
|
|
||||||
|
- **Page endpoint'inde sıralama (ORDER BY) yoktur.** Tüm sayfalar gezilirken kayıtların sırası garanti değildir; bu yüzden sayfa kayması yaşanabilir (bir kayıt iki kez gelebilir, bir kayıt hiç gelmeyebilir). Backend tarafında `createdAt` ardından `id` ile sıralama önerildi (yeni kayıtlar sona eklenir, `id` eşit zamanlarda sırayı sabitler).
|
||||||
|
- **Tüm kayıtlar çekilirken aynı anda register, update veya unregister yapmayın.** Veri değişirse sayfalar kayar. `nowcast-point-page.py` sonunda sunucunun bildirdiği `totalRecords` ile alınan benzersiz kayıt sayısını karşılaştırır ve fark varsa uyarı verir; bu durumda komutu yeniden çalıştırın. SQLite `registrationId` ile upsert yaptığı için tekrar çalıştırmak kayıt çoğaltmaz.
|
||||||
|
- `accountId` verilmezse ADMIN kullanıcılar tüm hesapları görür. Betik her zaman `/v1/users/me` içindeki `account.id` değerini gönderir (`--account-id` ile değiştirilebilir). Yetki yoksa (403) uyarı verip `accountId` olmadan bir kez daha dener.
|
||||||
|
- Backend her `RuntimeException`'ı HTTP 400 yapar; kayıt bulunamaması da 400 döner. Yalnızca gerçek 404 `NOT_FOUND` olarak işaretlenir.
|
||||||
|
|
||||||
|
### page
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python3 nowcast-point-page.py # tüm sayfalar, ekrana
|
||||||
|
python3 nowcast-point-page.py --output kayitlar.csv # kayitlar-YYYYmmdd-HHMMSS.csv
|
||||||
|
python3 nowcast-point-page.py --page-number 2 --page-size 50 # yalnızca tek sayfa
|
||||||
|
python3 nowcast-point-page.py --recipient-id musteri-1 --recipient-id musteri-2
|
||||||
|
python3 nowcast-point-page.py --polygon "32.8,39.9;32.9,39.9;32.9,40.0;32.8,39.9"
|
||||||
|
```
|
||||||
|
|
||||||
|
- Poligon `lng,lat` çiftlerinden oluşan **düz halkadır**, en az 4 nokta ve kapalı olmalıdır. Filtre, kayıt noktasının poligonla kesişimine bakar; yarıçap yok sayılır.
|
||||||
|
- Çıktıda webhook bilgisi dosya başında bir kez yer alır (CSV'de `#webhook` satırı); `password`, `jwtToken`, `apiKey` ve `secret` alanları `***` ile maskelenir. Her filtre ayrı bir sütundur. API yanıtında `createdAt`/`updatedAt` bulunmadığı için çıktıda da yoktur.
|
||||||
|
- Etkileşimli terminalde ve `--output` verilmediğinde sonunda "SQLite verisi CSV/TXT dosyasına aktarılsın mı?" sorulur.
|
||||||
|
|
||||||
|
### get
|
||||||
|
|
||||||
|
Girdi CSV ise başlıkta `registrationId` (veya `recipientId`) sütunu aranır; TXT ise satır başına bir ID yazılır, boş satırlar ve `#` ile başlayanlar atlanır. `--output` zorunludur; uzantı `.csv` ise noktalı virgüllü CSV, `.txt` ise JSON Lines yazılır. Satır durumları `SUCCESS`, `NOT_FOUND` (HTTP 404) ve `FAILED`'dır (`httpStatus` ve `errorBody` dolar). Bir `recipientId` birden çok kayıt dönerse her kayıt ayrı satırdır.
|
||||||
|
|
||||||
|
### register
|
||||||
|
|
||||||
|
CSV sütunları yalnızca `recipientId;lat;lng;radius` değerleridir (`radius` metre, 0-50000). Filtre CSV'de tekrarlanmaz; ortak `nowcast-point-alarm-filter.json` dosyasından okunur ve her kayda uygulanır (`--filter-config` ile değiştirilir). Sonuç sütunları aynı dosyaya yazılır: `status;httpStatus;registrationId;errorBody`. HTTP 200 dışındaki yanıtlarda cevap gövdesi `errorBody` içine yazılır. `SUCCESS` satırlar yeniden çalıştırmada atlanır. Sonucu belirsiz kalan istek yalnızca `recipientId`, nokta ve yarıçap birebir eşleşirse mevcut kayıtla kurtarılır. Aynı hesap, `recipientId`, nokta ve yarıçap ikinci kez kaydedilemez (400).
|
||||||
|
|
||||||
|
### update
|
||||||
|
|
||||||
|
CSV'de `registrationId` zorunludur; `recipientId;lat;lng;radius` ve filtre sütunları (`lightningType;peakCurrent;inCloudHeight;intersectsAffectedPolygon;intersectsCellPolygon;severityThreshold;speedThreshold;precipitationIntensities`, liste `|` ile ayrılır) isteğe bağlıdır. **Boş hücre gönderilmez**; `lat` ve `lng` birlikte verilmelidir. Önce `--dry-run` ile gövdeleri kontrol edin.
|
||||||
|
|
||||||
|
- Backend PATCH'i bir alanı **temizleyemez** (null = dokunma).
|
||||||
|
- `thunderstorm.speedThreshold` backend PATCH'inde işlenmiyor, değer gönderilse de güncellenmeyebilir (GAIA-476).
|
||||||
|
- Backend sınır güncellemesinde doğrulama yapmaz; yarıçap ve koordinat aralıkları istemcide yerelde doğrulanır.
|
||||||
|
- Webhook güncellemesi bu sürümde desteklenmez.
|
||||||
|
|
||||||
|
### unregister
|
||||||
|
|
||||||
|
Başlamadan önce ortam adı ve URL, silinecek kayıt sayısı ve "geri alınamaz" uyarısı gösterilir; bir hesabın **son kaydı** silinirse webhook tanımı da silinir. Onay için `SİL` yazılmalıdır (`--yes` yoktur). `prod` ortamında ek olarak ortam adı (`prod`) yazdırılır. Silmeden önce her kayıt `get-by-id` ile yedeklenir (`--backup`, kapatmak için `--no-backup`); yedek yazılamazsa hiçbir kayıt silinmez.
|
||||||
|
|||||||
Reference in New Issue
Block a user