Merge branch 'docs/cheatsheet-real-examples' into 'main'

docs(cheatsheet): real examples — FK dep, locale switch, time-travel

See merge request 2-6/2-6-4/terravault/ordinis!246

docs/integration/api-cheatsheet.md

@@ -9,11 +9,12 @@
 ## Auth
 
 ```bash
+# client_credentials (для service-to-service интеграторов)
 TOKEN=$(curl -s -X POST https://auth.nstart.space/realms/nstart/protocol/openid-connect/token \
-  -d client_id=ordinis -d grant_type=password -d scope=openid \
+  -d grant_type=client_credentials \
-  -d username=$USER -d password=$PASS | jq -r .access_token)
+  -d client_id=$KC_CLIENT_ID -d client_secret=$KC_CLIENT_SECRET | jq -r .access_token)
 
-curl -H "Authorization: Bearer $TOKEN" $ORDINIS/api/v1/me/notifications/settings
+curl -H "Authorization: Bearer $TOKEN" $ORDINIS/api/v1/spacecraft/records?as_scope=PUBLIC,INTERNAL
 ```
 
 Scopes: `PUBLIC` (anon ok) · `INTERNAL` (auth) · `RESTRICTED` (admin).
@@ -185,6 +186,75 @@ Action types (13): `DICTIONARY_CREATED · SCHEMA_UPDATED · SCHEMA_PUBLISHED ·
 | 502 | `llm_error` | AI: LLM upstream |
 | 503 | `circuit_open` | AI: circuit breaker |
 
+## Реальные примеры (staging 265)
+
+### FK-зависимость: кто использует справочник
+
+```bash
+curl -s "$ORDINIS/api/v1/dictionaries/satellite_type/dependents" | jq
+# [
+#   {
+#     "sourceDict": "spacecraft",
+#     "sourceDisplayName": "Космические аппараты",
+#     "sourceField": "satellite_type_code",
+#     "targetField": "code",
+#     "onClose": "BLOCK",
+#     "activeRecordsInSourceDict": 14
+#   }
+# ]
+```
+
+**Семантика**: `spacecraft.satellite_type_code` ссылается на `satellite_type.code`. На staging 14 КА используют этот справочник, и `onClose: BLOCK` означает что нельзя удалить тип КА пока на него ссылаются записи (без cascade-close).
+
+Другие живые FK на staging:
+- `ground_station` ← `antenna.ground_station` (4 records, BLOCK)
+- `spacecraft_status` ← `spacecraft.status`
+- `country` ← `spacecraft.country`
+
+### Локализация записи (Accept-Language)
+
+```bash
+# default ru-RU
+curl -s "$ORDINIS/api/v1/spacecraft/records/1999-068A?as_scope=PUBLIC" | jq '.data | {mission, operator}'
+# {"mission": "Глобальный мониторинг суши и атмосферы", "operator": "НАСА"}
+
+# en-US
+curl -sH "Accept-Language: en-US" \
+  "$ORDINIS/api/v1/spacecraft/records/1999-068A?as_scope=PUBLIC" | jq '.data | {mission, operator}'
+# {"mission": "Global land and atmosphere monitoring", "operator": "NASA"}
+```
+
+⚠️ Только Accept-Language header. `?locale=` query param backend сейчас игнорирует. Schema endpoint (`/dictionaries/{name}`) **не локализуется** вообще — всегда возвращает на defaultLocale.
+
+### Time-travel: запись на момент в прошлом
+
+```bash
+# Запись на 14.05.2026 12:00 UTC (точно после её validFrom = 11:34)
+curl -s "$ORDINIS/api/v1/test1/records/Dima_record_test_1?as_scope=PUBLIC&at=2026-05-14T12:00:00Z" \
+  | jq '{businessKey, validFrom, validTo, data}'
+# 200 OK — запись действительная на указанный момент
+
+# До validFrom → 404 record_not_active (это ожидаемо)
+curl -s "$ORDINIS/api/v1/test1/records/Dima_record_test_1?as_scope=PUBLIC&at=2026-05-01T00:00:00Z" | jq '.code'
+# "record_not_active"
+```
+
+### History — все ревизии записи
+
+```bash
+curl -s "$ORDINIS/api/v1/dictionaries/spacecraft/records/1999-068A/history?as_scope=PUBLIC" | jq '.[0] | {revisionNumber, revisionType, updatedAt}'
+```
+
+### Schema time-travel (changelog diff)
+
+```bash
+# Список ревизий
+curl -s "$ORDINIS/api/v1/dictionaries/test1/changelog" | jq '.currentVersion, (.entries | length)'
+
+# Diff конкретной ревизии (before/after JSON-Schema)
+curl -s "$ORDINIS/api/v1/dictionaries/test1/changelog/22/diff" | jq '{eventType, occurredAt, before: .before.properties | keys, after: .after.properties | keys}'
+```
+
 ## 60-second smoke
 
 ```bash
@@ -195,6 +265,7 @@ curl -s $ORDINIS/api/v1/version | jq                                          #
 curl -s $ORDINIS/api/v1/dictionaries | jq 'length'                            # 37 на prod / 39 на staging
 curl -s $ORDINIS/api/v1/dictionaries/spacecraft | jq '.scope'                 # "PUBLIC"
 curl -s "$ORDINIS/api/v1/spacecraft/records?as_scope=PUBLIC" | jq '.[0].businessKey'
+curl -s "$ORDINIS/api/v1/dictionaries/satellite_type/dependents" | jq 'length'  # 1 (spacecraft зависит)
 curl -s "$ORDINIS/api/v1/search?q=spacecraft" | jq '.total'                   # >0
 curl -s $ORDINIS/api/v1/ai/info | jq '.enabled'                               # true / false
 ```