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
parent d5268b9395
commit bcfb07f547
23 changed files with 232 additions and 215 deletions
@@ -1,42 +1,44 @@
-# Ordinis docs (Diplodoc / YFM)
+# Ordinis Integrator Guide (Diplodoc / YFM)

-Документация Ordinis НСИ ЦУОД ОДХ построена через **Diplodoc** (open-source
-documentation platform от Yandex). Markdown source — YFM (Yandex Flavored
-Markdown) с расширениями для tabs, notes, includes, mermaid диаграмм.
+Consumer-facing документация Ordinis НСИ ЦУОД. Build через **Diplodoc**
+(open-source documentation platform от Yandex), source — YFM (Yandex
+Flavored Markdown).
+
+**Scope:** только то, что нужно интеграторам (Альтум team, BI, third-party
+consumers). Operator runbooks, архитектурные deep-dives и project state —
+во внутренней документации в [`../docs-internal/`](../docs-internal/),
+не в Diplodoc build.

 ## Структура

 ```
 docs/
-├── package.json           # @diplodoc/cli + scripts
-├── .yfm                   # Diplodoc config (langs, plugins)
-├── toc.yaml               # Содержание / навигация (рендерится в sidebar)
-├── index.md               # Главная страница
-├── integration/           # Интеграция по API
-│   ├── api/               # Главы для consumers
-│   │   ├── index.md       # Обзор
-│   │   ├── auth.md        # Keycloak / JWT
-│   │   ├── read-endpoints.md
-│   │   ├── events.md      # Kafka outbox
-│   │   ├── webhooks.md
-│   │   ├── bitemporal.md
-│   │   ├── x-references.md
-│   │   ├── caching.md
-│   │   ├── errors.md
-│   │   ├── best-practices.md
-│   │   └── bundle-cuod.md
-│   └── altum-imaging-order.md   # Прикладной сценарий
-├── ops/                   # Operator runbook
-│   ├── README.md
-│   ├── slo.md
-│   ├── outbox-dlq.md
-│   ├── db-migrations.md
-│   ├── vault-unseal.md
-│   └── kafka-restart.md
-├── status/                # State snapshots (исключено из build)
-│   └── *-state.md
-└── tech/                  # Legacy технические страницы
-    └── api-integration.md
+├── package.json           # @diplodoc/cli + build scripts
+├── .yfm                   # Diplodoc config
+├── toc.yaml               # Содержание / sidebar
+├── index.md               # Главная (integrator-focused tabs)
+└── integration/
+    ├── api/               # 11 глав про API integration
+    │   ├── index.md
+    │   ├── auth.md
+    │   ├── read-endpoints.md
+    │   ├── events.md
+    │   ├── webhooks.md
+    │   ├── bitemporal.md
+    │   ├── x-references.md
+    │   ├── caching.md
+    │   ├── errors.md
+    │   ├── best-practices.md
+    │   └── bundle-cuod.md
+    └── altum-imaging-order.md
+```
+
+Внутренние материалы (НЕ в Diplodoc build):
+```
+docs-internal/
+├── ops/      # Operator runbook (on-call)
+├── status/   # Project state snapshots
+└── tech/     # Legacy technical pages
 ```

 ## Сборка
@@ -48,62 +50,40 @@ cd docs
 pnpm install
 pnpm build           # → ./_dist (HTML)
 pnpm serve           # → http://localhost:8088
-# либо одной командой:
-pnpm dev
+pnpm dev             # build + serve одной командой
 ```

-Build output (`_dist/`) — статический HTML, можно деплоить в:
+Build output (`_dist/`) — статический HTML, deployable в:
 - GitLab Pages
- S3 + CloudFront
- nginx/ingress на cluster.142
+- S3 / object storage
+- nginx/ingress на k8s cluster

-## Автор содержимого
+## Editorial guidelines

-| Раздел | Owner |
-|---|---|
-| `/` (index, integration/api/*) | zimin.an@nstart.space |
-| `ops/*` | on-call rotation team |
-| `integration/altum-imaging-order.md` | Альтум team contact |
+Этот set документации — **public contract** для интеграторов:

-## Что не committable
+1. **Не leak'аем internal architecture** — никаких internal alert names,
+   service paths, internal infrastructure URLs.
+2. **API contract стабилен** — изменения требуют semver bump + announcement.
+3. **Consumer-side examples** для каждой концепции (Python, Node, либо Spring).
+4. **Версионирование** через bundle / API major.

- `_dist/` — build output (gitignore'нут)
- `node_modules/` — dependencies (gitignore'нут)
-
-## Deployment
-
-В roadmap — GitLab CI job `build-docs`:
-
-```yaml
-build-docs:
-  stage: build
-  image: node:18
-  script:
-    - cd docs
-    - pnpm install --frozen-lockfile
-    - pnpm build
-  artifacts:
-    paths: [docs/_dist]
-    expire_in: 1 week
-  rules:
-    - changes: ["docs/**/*"]
-```
-
-Затем deploy в GitLab Pages либо как отдельный k8s deployment с nginx.
+Для operator-side / dev-side материалов — `docs-internal/` либо design docs
+в `~/.gstack/projects/claude/`.

 ## YFM extensions используются

 - `{% list tabs %}` — табы для switching между audiences
 - `{% note info|warning|tip %}` — выделенные блоки
 - `mermaid` code blocks — диаграммы (graph LR, gantt)
- Cross-links в `toc.yaml` — sidebar navigation
- `varsPreset: external` — для shared includes (TBD when нужно)
+- `toc.yaml` cross-links — sidebar navigation

 ## Roadmap

+- [x] Базовая структура integration guide (11 страниц)
 - [ ] CI job `build-docs` в `.gitlab-ci.yml`
- [ ] GitLab Pages deployment
- [ ] Search через Diplodoc search plugin
- [ ] EN translation (i18n via `langs:` в `.yfm`)
+- [ ] GitLab Pages / k8s ingress deployment
+- [ ] Search plugin
+- [ ] EN translation (через `langs:` в `.yfm`)
 - [ ] Includes для shared snippets (auth examples, error tables)
- [ ] Versioning — separate doc trees per Ordinis major version
+- [ ] Versioning — separate doc trees per API major version