d5268b9395
docs: Diplodoc setup + полное руководство интеграции по API
...
Новая документация-as-code на платформе Diplodoc (Yandex open-source) с
YFM (Yandex Flavored Markdown). Build → static HTML, deployable куда угодно.
Что добавлено:
- package.json + .yfm + toc.yaml — Diplodoc setup, навигация для sidebar
- index.md — главная страница с tabs для разных audiences
- README.md — инструкция для contributors
Раздел integration/api/ — 11 страниц про интеграцию consumers:
- index — обзор + глоссарий
- auth — Keycloak service accounts, scope mapping
- read-endpoints — GET /dictionaries, list/by-key, spatial filters
- events — Kafka outbox топики, partition keys, idempotency, DLQ
- webhooks — HMAC, SSRF guard, retry policy, test ping endpoint
- bitemporal — validFrom/validTo + history, future-dated entries, bulk close/export
- x-references — FK syntax, validation errors, scope hiding, orphan scanner, v2 cascade preview
- caching — TTL / push / snapshot strategies, hybrid pattern
- errors — full error code reference (validation/auth/conflict/server), retry strategy
- best-practices — 33 numbered rules для consumers
- bundle-cuod — все 40 справочников с FK графом и сценариями
Обновлены:
- ops/README.md — link на новую integration/api/, убран inline <br>
- ops/slo.md — broken cross-repo links заменены на text references
Build:
cd docs && pnpm install && pnpm build
→ ./_dist (20 HTML files, 7.1M)
pnpm serve # → http://localhost:8088
CI deploy job для GitLab Pages — в roadmap (см. docs/README.md).
Существующий tech/api-integration.md оставлен в toc как legacy
(содержимое мигрировано + расширено в integration/api/).
2026-05-07 23:19:02 +03:00
bcedddef71
docs(ops): SLO/SLI definitions + error budget framework
...
7 SLI с конкретными порогами и justification:
- read-api availability (99.5% v1 target)
- read-api p99 latency < 500ms target / 1s alert
- writer 5xx error rate < 1%
- outbox publish lag (≤ 50 normal, alert > 100)
- outbox DLQ size = 0 strict
- outbox publish error rate ~0
- postgres availability (99.9% v1 target)
Error budget framework для 99.5% уровня (~216 мин/мес downtime).
Burn rate alerts — TODO.
Notification routing — TODO (Slack/Telegram per severity).
Что не покрывает v1: Grafana dashboards, distributed tracing, log
aggregation, capacity planning. См. observability stack roadmap для v2.
2026-05-05 20:32:37 +03:00
adc40aca22
docs(ops): operator runbook — kafka, outbox DLQ, db migrations + index
...
Карточки процедур для on-call. Self-contained: можно открыть в момент
инцидента без необходимости понимать всю архитектуру.
- README.md — index by symptom + быстрые гайды по 401, 500, admin-ui 502.
- kafka-restart.md — pause/unpause, replicas=0 fix, force-delete, restart
consumer'ов после Kafka up.
- outbox-dlq.md — диагностика DLQ через UI/API/SQL, типичные причины
(orphan topic, ACL, broken payload), replay через UPDATE dlq_at=NULL.
- db-migrations.md — Liquibase changelog, добавление, откат, recovery
failed migration через DELETE databasechangelog.
Vault unseal был отдельным коммитом ранее.
2026-05-05 17:26:30 +03:00
0fb20dc8d4
docs(ops): vault unseal runbook + auto-unseal migration plan
...
Triage card для on-call: где взять unseal-keys (1Password placeholder,
уточнить с DevOps lead), как запустить script либо ручную процедуру,
что проверить после, troubleshooting типовых проблем.
Также: §7 — план миграции на auto-unseal (Transit / Yandex KMS) когда
определимся с master Vault или KMS-backend.
2026-05-05 16:56:45 +03:00
Zimin A.N.