docs(cheatsheet): добавить конкретные примеры с реальными dicts

После Postman demo audit — в cheatsheet не хватало живых примеров,
которые можно скопировать и сразу проверить. Добавил:

* FK-зависимость:
  GET /dictionaries/satellite_type/dependents →
  [{sourceDict: spacecraft, sourceField: satellite_type_code,
    onClose: BLOCK, activeRecordsInSourceDict: 14}]
  + список других живых FK на staging (ground_station, country etc).

* Локализация записи через Accept-Language:
  ru: НАСА / Глобальный мониторинг суши и атмосферы
  en: NASA / Global land and atmosphere monitoring
  + warning что ?locale= игнорируется и schema endpoint вообще
  не локализуется.

* Time-travel: 14.05.2026 12:00 → 200, 14.05.2026 00:00 → 404
  record_not_active (ожидаемое поведение, не bug).

* History и changelog/diff живые примеры с test1.

Также убрал password-grant из Auth (используется client_credentials —
это правильный flow для server-to-server интеграторов). И добавил
dependents проверку в 60-second smoke.
This commit is contained in:
Zimin A.N.
2026-05-20 11:52:04 +03:00
parent 648b0fdf52
commit f3c3e33289
+74 -3
View File
@@ -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 username=$USER -d password=$PASS | jq -r .access_token)
-d grant_type=client_credentials \
-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
```