802532057b
docs(toc): + bundle-format-spec.md (fixes Diplodoc build — link unreachable)
2026-05-20 19:13:40 +03:00
3365e9462a
docs(toc): зарегистрировать quickstart + cheatsheet + регламент в Diplodoc nav
...
Файлы лежат в docs/integration/ с прошлых MR (!243 , !247 , !248 ), но в
toc.yaml не были включены — Diplodoc не строил их в /docs nav, и
пользователи могли попасть на них только по прямой ссылке.
Добавил три entries в секцию «Интеграция по API» сверху списка:
- 🚀 Quick Start (15 минут) → api-quickstart.md
- 📋 Cheat Sheet → api-cheatsheet.md
- ✅ Регламент — что заводить в НСИ → dictionary-criteria.md
После merge ordinis-docs container пересоберётся, и в admin UI ссылка
"Docs" (top-right) откроет страницу с этими entries в left nav.
2026-05-20 19:09:51 +03:00
1dba9476db
docs(rbac): добавить матрицу realm-ролей Keycloak
...
operator/rbac.md — новая страница с полной матрицей RBAC:
- Scope ACL (ordinis:client:public/internal/restricted)
- Workflow роли (schema:reviewer, schema:publisher, record:reviewer)
- Action matrix (endpoint → required scope + role)
- Типичные профили (consumer, maker, reviewer, publisher, admin)
- Composite role 'ordinis:admin' для one-shot assignment
- Keycloak setup инструкция (Admin Console шаги)
- Диагностика типичных 403 ошибок
toc.yaml — link в раздел Руководство оператора.
operator/index.md, reviewer/index.md — cross-references к rbac.md.
Покрывает Phase 1d enforcement (MR !162 ) — пользователи теперь
знают какие роли назначать в Keycloak realm 'nstart'.
2026-05-13 12:47:50 +03:00
a34c6d4c82
feat(topbar): «Что нового» button + 2026-05-12 state.md update
2026-05-12 17:05:24 +00:00
d790a77313
docs(integrator): v2.x.x update — workflow API + full changelog + schema extensions
2026-05-12 00:26:37 +00:00
a4add2402a
docs(api): pending-endpoints brief for backend team
...
5 endpoints нужны admin-UI для завершения UI-фич:
1. GET /dictionaries/{name}/changelog — History tab + TimeTravel
2. GET /dictionaries/{name}/snapshots — TimeTravel slider marks
3. POST drafts/.../{review,decision,publish} — workflow state machine
4. PATCH /dictionaries/{name}/schema — Fields tab inline edit
5. GET /dictionaries/graph/outgoing — catalog → FK count column
Каждый endpoint содержит: purpose, route, query/body, response example,
errors, frontend integration estimate. Total frontend work after backend
ship — ~14h (1.5 sprint day).
2026-05-11 22:47:24 +03:00
bcfb07f547
docs: split integrator guide (Diplodoc) vs internal docs + add build-docs CI
...
Чёткое разделение audiences:
- docs/ — consumer-facing only, Diplodoc-built. Public contract для
интеграторов (Альтум, BI, third-party).
- docs-internal/ — operator runbooks, status snapshots, legacy tech pages.
НЕ в Diplodoc build, НЕ публикуются.
Изменения:
- Move docs/{ops,status,tech} → docs-internal/{ops,status,tech}
- docs/toc.yaml: убраны секции Operations, Архитектура (legacy), Status
- docs/index.md: убран tab "оператор / on-call", focus на integrators
- docs/README.md: rewritten — scope только integrator guide, editorial
guidelines (no leak internal architecture, stable API contract)
- .yfm: убран явный ignore status/* (теперь не нужно — папка переехала)
- docs-internal/README.md: index для внутренней документации с rationale
разделения
Scrubbing implementation details из Diplodoc страниц:
- events.md: убраны Strimzi/cluster.142 references, OutboxPoller детали,
internal alert names (OrdinisOutboxLagHigh, OrdinisOutboxDLQNonEmpty),
metric names (nsi_outbox_*). Заменены на consumer-observable contract.
- webhooks.md: убраны metric names (nsi_webhook_ssrf_rejected_total),
alert table (OrdinisWebhookHighFailureRate и т.д.). Retry policy
переписана на user-side perspective.
- errors.md: убран alert name OrdinisReadApiErrorBudgetBurnFast, Tempo
endpoint URL, internal connection details.
- x-references.md: OrphanReferenceScanner → general "Ordinis периодически
детектирует". Убраны metric/alert names. Cascade roadmap без link на
internal design doc.
- auth.md: убран file path ScopeContext.java.
- bundle-cuod.md: убран Maven module path.
- caching.md: cascade design link заменён на text reference.
CI:
- .gitlab-ci.yml: новый job build-docs (stage: build) — Node 20 alpine,
pnpm install --frozen-lockfile + pnpm build, artifact docs/_dist на
неделю. Triggers: auto на docs/**, либо manual web. Готов к follow-up
pages-deploy job когда host решён.
- Новый pattern .docs-changes для rules.
Build verified clean: 13 HTML pages, 6.9M, no broken links/refs.
2026-05-07 23:27:03 +03:00
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
Zimin A.N.