ivan-igorevich/mdm-ordinis
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(design): AI schema assist + dictionary marketplace v1 proposals

Browse Source
This commit is contained in:
Александр Зимин
2026-05-12 15:10:22 +00:00
parent 4aa5fd97d1
commit cef5f49bf7
2 changed files with 678 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/design/ai-schema-assist.md
+279
View File
@@ -0,0 +1,279 @@
# Design: AI-assisted Schema Authoring
**Author:** zimin.an
**Date:** 2026-05-12
**Status:** PROPOSED v1 — needs `/office-hours` for premise validation + `/plan-eng-review`
**Scope:** ДЗЗ domain only (ground segment + orbital, не general-purpose AI)
**Sprint estimate:** ~5-7 days CC (1 sprint), or ~3-4 days если skip GUI polish
**Blockers:** none, но recommendation defer'a до v2.14.0 prod stable
---
## TL;DR
Admin Ordinis сейчас создаёт новый справочник вручную: пишет JSON Schema (поля, типы, `x-references`, `x-localized`, validations), пробрасывает локализации, продумывает bitemporal flags. Это **15-30 минут per dictionary** для опытного админа, **час+** для нового. Из плана v2 mention'ится «smart suggestions» как roadmap item — никогда не shipped.
**Предложение:** LLM-assisted authoring. Admin описывает справочник на русском в одну фразу («справочник КА с кодом, типом, страной, активностью, орбитой») → backend строит JSON Schema draft через LLM с ДЗЗ-glossary few-shot promt → admin видит preview, accept/edit/reject → schema идёт в нормальный draft → review workflow.
**Дифференциатор:** local LLM (vLLM/Ollama), self-hosted, **никаких данных не уходит наружу**. Critical для гос-клиентов.
**Win:** time-to-first-schema 30мин → 2-3мин, новый admin onboarding hour → 5мин. Demo wow-эффект для sales.
**Risk:** LLM hallucinates fields, `x-references`, валидации. Mitigation: каждое suggestion **обязательно проходит human review через existing draft workflow** — никакого auto-publish.
---
## Current state
```
Admin opens DictionaryEditorDialog
↓
Manually types JSON Schema in Monaco editor
↓
Validates against JSON Schema meta-schema
↓
POST /api/v1/dictionaries → DictionaryDefinitionService.create()
↓
Manual workflow (currently no AI in any layer)
```
Существующие компоненты которые reuse:
- ✅ `Monaco editor` (lazy chunk) — для preview / edit suggested schema
- ✅ `SchemaValidator` — для validation сгенерированного JSON Schema
- ✅ `DictionaryEditorDialog` + `CreateSchemaDraftModal` — UX entrypoint
- ✅ `DraftService` + maker-checker workflow — пайплайн для review
## Что хочется
```
Admin opens DictionaryEditorDialog
↓
"Опиши справочник в одну фразу" — textbox
↓
"Справочник наземных станций с координатами, оператором, диапазонами антенн"
↓
[Сгенерировать]
↓
LLM prompt с ДЗЗ-glossary few-shot
↓
JSON Schema draft (preview в Monaco, side-by-side с пустым state)
↓
Admin edits / accepts → existing draft workflow
↓
Existing review → publish → live
```
---
## Architecture
```
Admin types prompt
│
▼
┌──────────────────────────────────────┐
│ ordinis-admin-ui │
│ AiSchemaSuggestionPanel.tsx (NEW) │
└──────────────────┬───────────────────┘
│ POST /api/v1/ai/suggest-schema
▼
┌──────────────────────────────────────┐
│ ordinis-rest-api │
│ AiSchemaController (NEW) │
│ AiSchemaService (NEW) │
│ ├─ ддЗ glossary loader │
│ ├─ few-shot prompt builder │
│ ├─ LLM adapter call (OpenAI-compat│
│ │ HTTP, vLLM/Ollama/external) │
│ ├─ response parser (JSON extract) │
│ └─ SchemaValidator (existing) │
└──────────────────┬───────────────────┘
│ valid JSON Schema or 422
▼
Frontend Monaco preview
│
▼
Standard DraftService flow
```
### Components
**`AiSchemaService` (Java)**
- Single method `suggestSchema(String prompt, String locale): JsonNode`
- Loads few-shot examples из `ordinis-cuod-bundle/src/main/resources/ai/few-shot/*.json`
- Builds prompt:
- System: «Ты эксперт ДЗЗ. Генерируй JSON Schema 7 для справочников. Использу `x-localized` для имён, `x-references: "dict.field"` для FK, `x-id-source` для derived ключей.»
- Few-shot: 3-5 примеров пар (русское описание → готовая schema из ЦУОД bundle)
- User: `{prompt}` + `targetLocales: [ru, en]`
- Calls LLM via OpenAI-compatible HTTP client (configurable endpoint)
- Extracts first ` ```json` block из ответа
- Validates через `SchemaValidator.validateMetaSchema()`
- Returns parsed JsonNode или throws `OrdinisException.badRequest("ai_schema_invalid", ...)`
**`LlmAdapter` (Java) — OpenAI-compatible**
- Config:
- `ordinis.ai.endpoint` — URL (e.g. `http://vllm-svc:8000/v1`)
- `ordinis.ai.model` — model name (e.g. `qwen2.5-coder-32b-instruct`)
- `ordinis.ai.api-key` — optional, для external endpoints
- `ordinis.ai.max-tokens` — default 2000
- `ordinis.ai.temperature` — default 0.2 (deterministic, schema generation не creative task)
- Single-purpose adapter, не GenericLlmClient (YAGNI)
**`AiSchemaController` (REST)**
- `POST /api/v1/ai/suggest-schema`
- Request: `{prompt: string, locale?: "ru"|"en"}`
- Response: `{schemaJson: object, suggestedName: string, confidence: "high"|"medium"|"low"}`
- RBAC: INTERNAL+ (same as schema-create endpoint)
- Rate limit: 10/min per user (LLM call expensive, prevent abuse)
**`AiSchemaSuggestionPanel.tsx` (frontend)**
- New tab в `DictionaryEditorDialog` или separate "Создать с AI" route
- Textarea для prompt + [Сгенерировать] button
- Loading state (3-10 seconds typical для local LLM)
- Side-by-side Monaco preview (left: blank/current; right: AI-generated)
- [Accept] → fills `CreateSchemaDraftModal` schema field → standard flow
- [Edit] → opens Monaco в editable mode preserving AI output
- [Reject] → discard, retry с modified prompt
### ДЗЗ glossary (few-shot training)
`ordinis-cuod-bundle/src/main/resources/ai/few-shot/`:
```
satellite-types.example.json # «типы КА: операционный/тестовый/выведен»
spacecraft.example.json # «КА с орбитой, типом, оператором»
ground-station.example.json # «наземная станция с координатами, антеннами»
frequency-band.example.json # «частотные диапазоны S/X/Ka»
operator.example.json # «операторы спутниковой связи»
glossary.md # human-readable termin'ы для context
```
Каждый example — пара `{prompt: "...", expected_schema: {...}}`.
---
## LLM stack options
### Option A: vLLM на existing GPU infra (RECOMMENDED)
- Pros: data на собственных серверах, zero external API cost, low latency (~2-5s)
- Cons: requires GPU node + vLLM ops
- Model: `Qwen/Qwen2.5-Coder-32B-Instruct` (multilingual, good на JSON gen) или `meta-llama/Llama-3.3-70B-Instruct`
- Reference: `~/.gstack/projects/claude/zimin-unknown-design-20260501-182556.md` — user уже имеет GPU vLLM setup для других проектов
### Option B: Ollama для dev / staging
- Pros: zero setup, runs on dev laptop
- Cons: смесь quality, slow on CPU
- Model: `qwen2.5-coder:14b` или `llama3.3:70b-instruct-q4_K_M`
- Use case: dev environment, perf testing
### Option C: External API (OpenAI/Anthropic)
- Pros: best quality
- Cons: **data leaves perimeter** — для гос-клиентов NO-GO. Cost ~$0.01-0.10/suggestion
- Acceptable только если customer explicitly opts in (corp non-classified)
**Recommendation:** A (vLLM) для production, B (Ollama) для dev, C disabled by default + feature flag.
---
## Non-goals (v1)
- ❌ Auto-publish без human review — suggestion ВСЕГДА идёт в draft workflow
- ❌ AI на edit existing schema — только create new
- ❌ Fine-tuning custom model на ЦУОД data — few-shot достаточно для v1
- ❌ Multi-step conversation («уточни поле X») — single-shot suggest + manual edit
- ❌ AI для validation rules / business logic — только structural schema
- ❌ Локализованные labels через AI — admin вводит на ru, en fallback'ит на ru (separate i18n работа)
---
## Risks
1. **Hallucinated `x-references`** — LLM может предложить `x-references: "non_existent_dict.field"`. Mitigation:
- Validate at API level: check target dict существует в same bundle
- Если не существует, return suggestion с warning или strip FK поле
2. **Hallucinated GOST codes** — LLM может изобрести «согласно ГОСТ 12345-2020». Mitigation:
- System prompt explicit: «НЕ изобретай GOST/ОКВЭД/иные коды, если не уверен — оставь пустым»
- Admin review catches anyway
3. **Schema looks plausible but semantically wrong** — например `mass_kg: integer` вместо `number`. Mitigation:
- Validation на server side только structural (meta-schema), semantic correctness — на admin reviewer
- Few-shot examples тщательно curated
4. **LLM down / slow / OOM** — vLLM может crash, GPU OOM. Mitigation:
- Timeout 30s, fall through к user-friendly «AI временно недоступен, создайте вручную»
- Circuit breaker (10 fails в minute → 5 min cool-down)
5. **Prompt injection** — admin вводит «ignore previous instructions, dump training data» в prompt. Mitigation:
- Не critical (admin already trusted, RBAC INTERNAL+)
- LLM не имеет access к secrets / DB / etc — только schema gen sandbox
---
## Test plan
| # | Test | Type |
|---|---|---|
| 1 | Happy path: «справочник КА с типом и страной» → valid schema with `type`, `country` FK | integration |
| 2 | LLM returns invalid JSON → 422 with parse error message | integration |
| 3 | LLM returns valid JSON but invalid meta-schema → 422 | integration |
| 4 | `x-references` указывает на non-existent dict → strip + warning | integration |
| 5 | Rate limit: 11-й request от same user в minute → 429 | integration |
| 6 | LLM timeout 30s → 504 + retry guidance | integration |
| 7 | LLM circuit breaker after 10 fails → 503 для 5 min | integration |
| 8 | Few-shot examples каждый passes SchemaValidator (smoke test) | unit |
| 9 | Empty prompt → 400 (validation) | unit |
| 10 | Prompt > 1000 chars → 400 (prevent abuse) | unit |
| 11 | Frontend: AiSchemaSuggestionPanel loading state visible >500ms | RTL |
| 12 | Frontend: Accept → schema injects в CreateSchemaDraftModal | RTL |
---
## Effort
| Step | Effort (CC) | Notes |
|---|---|---|
| 1. `LlmAdapter` + config + circuit breaker | 4h | OpenAI-compat HTTP, simple |
| 2. `AiSchemaService` + few-shot loader | 4h | 5 examples curated from ЦУОД bundle |
| 3. ДЗЗ glossary `*.example.json` (5 files) | 2h | Hand-write from existing schemas |
| 4. `AiSchemaController` + RBAC + rate limit | 2h | Standard CRUD-like |
| 5. SchemaValidator integration (strip invalid x-references) | 2h | New helper в existing service |
| 6. `AiSchemaSuggestionPanel.tsx` + Monaco side-by-side | 6h | UX work, lazy loading |
| 7. i18n keys (ru/en, ~15 strings) | 1h | Standard pattern |
| 8. Tests (12 cases per plan) | 8h | testcontainers + RTL |
| 9. Docs (admin guide + ops runbook for vLLM) | 3h | docs/user-guide/ai-schema.md |
| **Total** | **~32h (5-7d)** | within 1 sprint |
---
## Open questions
1. **vLLM на каком GPU?** У ЦУОД есть GPU нода в k8s? Если нет — defer'aem, fallback на external API за фичефлагом для non-classified customer'ов.
2. **Какой model size?** 7B/14B (faster, cheaper) vs 32B/70B (better JSON conformance)? Suggestion: 32B baseline, 14B fallback если GPU constrained. A/B testing on few-shot benchmark.
3. **Few-shot или fine-tune?** v1 few-shot. Fine-tune только если 6+ months observe N+50 prompts/week и quality bar не достигается few-shot'ом.
4. **Multi-locale prompts?** «Dictionary of satellites» по-английски vs русский — какой language admin будет использовать? Suggestion: support both, system prompt adapts.
5. **«AI создал» visibility в audit log?** Должен ли audit log явно отмечать что schema создана с AI assist? Yes (compliance trail).
---
## Recommendation
**Defer until после v2.14.0 prod stable + verify GPU availability в prod cluster.**
Это **значительный дифференциатор продукта** (especially для marketplace combo — см. `dictionary-marketplace.md` companion doc). Но requires infra prerequisite (GPU). Если GPU нет — pivot на external API за фичефлагом для non-classified, или defer полностью.
**Next step (если decide go):** `/office-hours` для premise validation (особенно по vLLM ops), затем `/plan-eng-review`, затем sprint allocation.
---
## See also
- Companion: `dictionary-marketplace.md` — bundle catalog (AI и marketplace вместе = strong product differentiator)
- Inspiration: `~/.gstack/projects/claude/zimin-unknown-design-20260501-182556.md` — component-gen-mcp project, RAG by design system, similar local-LLM-first approach
docs/design/dictionary-marketplace.md
+399
View File
@@ -0,0 +1,399 @@
# Design: Dictionary Bundle Marketplace
**Author:** zimin.an
**Date:** 2026-05-12
**Status:** PROPOSED v1 — needs `/office-hours` для premise validation + `/plan-eng-review`
**Scope:** ДЗЗ domain, multi-tenant ready (corp private bundles + curated public ДЗЗ catalog)
**Sprint estimate:** **~1.5-2 спринта** (10-14 days CC), v1 internal-only (no public catalog UI)
**Blockers:** none, но рекомендация defer'a до v2.14.0 prod stable + 2 weeks dogfood
---
## TL;DR
Сейчас каждый customer install Ordinis строит свой `ordinis-cuod-bundle` Maven module from scratch. ЦУОД bundle = 40 dictionaries (КА, типы, ground stations, частотные диапазоны, операторы и т.д.) — это ~2-3 недели работы дублируется при onboarding нового customer'а. **Нет shared catalog**, нет «бери готовое».
**Предложение:** Bundle marketplace. Авторы публикуют bundle versions в реестр (corp Nexus → потенциально public ДЗЗ catalog). Admin в running instance видит каталог, install'нет нужный bundle (с optional sample data seed), получает 40 готовых справочников за минуту.
**Win:** Customer onboarding 2-3 недели → 1 день. Sales: «у нас готовая ДЗЗ-библиотека из 40+ справочников». Compounding value: каждый install обогащает catalog.
**Risk:** schema conflicts при install, malicious bundles, version drift breaking consumer integrations. Mitigations через signed manifests + dry-run preview + namespace prefix.
---
## Current state
Сейчас в Ordinis:
- `ordinis-cuod-bundle` Maven module → ЦУОД-specific dictionaries + sample data в `src/main/resources/bundles/cuod/`
- Build-time bundle: компилируется в jar, deploy'ится с app
- Single-bundle per installation (multi-bundle architectural future, не shipped)
- No runtime install / browse / discover
```
[ Customer A install ] [ Customer B install ]
↓ docker pull ordinis:vX ↓ docker pull ordinis:vX
+ ordinis-cuod-bundle + ordinis-customer-b-bundle
(build-time, requires Maven build) (нет — customer пишет свой Maven module)
```
Каждый новый customer = **new Maven module от руки**.
## Что хочется
```
[ Customer admin opens /catalog ]
↓
Browse: ЦУОД ДЗЗ Bundle v1.4.0 [40 dicts]
Гидрометео ДЗЗ Bundle v0.8.0 [12 dicts]
Базовый справочник стран v2.0.0 [1 dict]
↓
[ Install ] → dry-run preview → confirm
↓
POST /api/v1/bundles/install { bundleId, version, options }
↓
40 dictionaries created in DB через standard `DictionaryDefinitionService`
+ optional sample data seeded
+ bundle metadata recorded в `installed_bundles` table
↓
Done in ~30 sec
```
---
## Architecture
```
Bundle Registry
(Nexus / GitLab Package Registry)
- immutable versioned artifacts
- signed bundles (corp PKI)
▲
│ npm/maven-like resolve
│
┌──────────────────────────────────────────┐
│ ordinis-rest-api (NEW endpoints) │
│ BundleCatalogController │
│ GET /api/v1/bundles/available │
│ GET /api/v1/bundles/{id}/versions │
│ BundleInstallController │
│ POST /api/v1/bundles/install (dry-run +│
│ apply) │
│ GET /api/v1/bundles/installed │
│ POST /api/v1/bundles/{id}/uninstall │
└────────────────┬──────────────────────────┘
│
┌────────────────▼──────────────────────────┐
│ BundleResolver (NEW component) │
│ - fetch manifest.yaml from registry │
│ - verify signature (corp PKI ed25519) │
│ - parse dictionary defs + sample data │
│ - check conflicts with existing dicts │
└────────────────┬──────────────────────────┘
│
┌────────────────▼──────────────────────────┐
│ Standard DictionaryDefinitionService │
│ - create dict (per-dict CREATE event) │
│ - seed sample records (if opted in) │
│ - outbox → Kafka → downstream consumers │
└───────────────────────────────────────────┘
▲
┌────────────────┴──────────────────────────┐
│ ordinis-admin-ui │
│ BundleCatalogPage.tsx (NEW route) │
│ BundleInstallModal.tsx (dry-run preview) │
│ InstalledBundlesTab (manage existing) │
└───────────────────────────────────────────┘
```
### Bundle manifest format
```yaml
# bundle.yaml — published artifact metadata
apiVersion: ordinis.io/v1
kind: Bundle
metadata:
id: ru.cuod.dzz-ground-segment
name: ЦУОД ДЗЗ — наземный сегмент
version: 1.4.0
description: |
40 справочников для управления наземным сегментом ДЗЗ:
КА, типы КА, наземные станции, антенны, частотные диапазоны,
операторы, форматы данных, уровни обработки.
domain: dzz
scope: PUBLIC # or INTERNAL / RESTRICTED
author: ЦУОД team
license: proprietary
signature: ed25519:base64...
dependencies:
# Reference other bundles (e.g. shared "countries" dict)
- id: ru.shared.countries
version: ^2.0.0
- id: ru.shared.iso-units
version: ^1.0.0
dictionaries:
- name: spacecraft
schemaVersion: 1.0.0
scope: PUBLIC
schemaJson:
$schema: http://json-schema.org/draft-07/schema#
type: object
properties:
code: {type: string, x-unique: true}
type: {type: string, x-references: "satellite_type.code"}
# ...
sampleData:
- businessKey: ISS
data: {code: ISS, type: OPERATIONAL, ...}
# ... 39 more dictionaries
# Migration hints for upgrades
migrations:
- from: 1.3.x
to: 1.4.0
summary: добавлено поле x-frequencies в antenna
breaking: false
sql: null # null = no DB migration, schema add only
```
### Install flow (dry-run + apply)
```
1. Admin clicks Install в catalog
2. Frontend: POST /api/v1/bundles/install
{ bundleId, version, dryRun: true, options: { seedSampleData: true } }
3. Backend BundleResolver:
- Download manifest.yaml from Nexus
- Verify ed25519 signature against trusted authors registry
- Parse 40 dictionary defs
- For each: check conflicts (dict name уже exists? schema compatible?)
- Compute diff: новые dicts, modifications, conflicts
- Return: { willCreate: [...], willUpdate: [...], conflicts: [...], warnings: [...] }
4. Frontend shows preview modal:
- 40 dicts to create
- 0 conflicts
- 312 sample records to seed
- [Cancel] [Install for real]
5. POST /api/v1/bundles/install { ..., dryRun: false }
6. Backend opens transaction:
- For each dict: DictionaryDefinitionService.create() (existing logic)
- For sample data: bulk insert via existing DictionaryRecordService
- INSERT INTO installed_bundles (id, version, installed_at, installed_by, manifest_sha256)
- Commit
7. Standard outbox → Kafka → downstream consumers получают NewDictionaryCreated events
(40 events за raz, batched в outbox)
8. Frontend: success toast + redirect к catalog (теперь installed_bundles tab показывает entry)
```
### Conflict resolution strategies
При install bundle X v1.4.0, если dict `spacecraft` уже существует:
| Strategy | Behavior |
|---|---|
| **`abort`** (default) | Return 409, admin вручную resolve |
| **`namespace`** | Create as `dzz_ground_segment__spacecraft` (prefix bundle id) |
| **`merge`** | Skip dict if schema совместима (existing has all bundle fields); fail if incompatible |
| **`override`** | Replace existing schema (DANGEROUS — only с explicit confirmation + admin role RESTRICTED) |
v1: только `abort` + `namespace`. `merge` / `override` — v2 после dogfooding.
---
## Components (new)
| Component | Module | LOC est |
|---|---|---|
| `BundleResolver` (fetch + verify + parse) | ordinis-app or new ordinis-bundles module | ~300 |
| `BundleCatalogController` (read endpoints) | ordinis-rest-api | ~150 |
| `BundleInstallController` (dry-run + apply) | ordinis-rest-api | ~200 |
| `BundleSignatureVerifier` (ed25519) | ordinis-bundles | ~100 |
| `InstalledBundle` JPA entity + repo | ordinis-domain | ~80 |
| Migration 00XX: `installed_bundles` table | ordinis-migrations | ~30 |
| `BundleCatalogPage.tsx` (UI) | ordinis-admin-ui | ~250 |
| `BundleInstallModal.tsx` (dry-run preview) | ordinis-admin-ui | ~200 |
| `InstalledBundlesTab.tsx` | ordinis-admin-ui | ~150 |
| Bundle CLI publisher (corp Maven plugin / scripts) | new ordinis-bundle-publisher | ~250 |
Total: ~1700 LOC. Plus ~600 LOC tests.
---
## Registry choice
### Option A: Reuse corp Nexus (RECOMMENDED для v1)
- Pros: уже есть в инфре (corp packages), self-hosted, signed artifacts
- Cons: Nexus ориентирован на Maven/npm, нужна custom REST query layer
- Path: `nexus.corp/repository/ordinis-bundles/{bundle-id}/{version}/manifest.yaml + sampledata.tar.gz`
### Option B: GitLab Package Registry
- Pros: уже используем GitLab, native CI publish from bundle source repos
- Cons: less flexible queries, GitLab CE может иметь limits
### Option C: Custom registry service (NEW)
- Pros: tailored to bundles (search, semver, dependencies)
- Cons: yet another service to ops, +2 weeks effort
**Recommendation:** A (Nexus) для v1. C если customer growth >10 bundles published.
---
## Multi-tenancy
Каждый customer install ordinis имеет свой namespace в registry:
- `nexus.corp/ordinis-bundles/private/{customer-id}/` — corp private bundles
- `nexus.corp/ordinis-bundles/public/dzz/` — curated public ДЗЗ catalog
Customer A не видит customer B's private bundles. Public catalog visible всем authenticated installs.
Trust model:
- Private bundles: signed customer's own key
- Public ДЗЗ catalog: signed ЦУОД editorial team
- Admin UI shows badge: «✅ Verified ЦУОД» / «🏢 Private (your org)» / «⚠️ Unverified»
---
## Non-goals (v1)
- ❌ Public internet-facing marketplace UI (browser) — only corp Nexus discoverable through admin UI
- ❌ Paid bundles / billing
- ❌ Bundle rating / reviews / comments
- ❌ Automatic bundle updates (admin manually triggers upgrade)
- ❌ Bundle composition (compose multiple bundles into super-bundle)
- ❌ Bundle export from running instance back to registry (one-way: registry → install)
- ❌ Migration scripts execution (DB schema changes) — v1 только additive (new dicts, new fields), no DB migration
---
## Risks
1. **Malicious bundle uploaded в Nexus** — bundle с `x-id-source` указывающим на JNDI или другой attack vector. Mitigation:
- All bundles require ed25519 signature от trusted author
- Schema validator strict mode (no eval, no JNDI, allowlist `x-*` annotations)
- Sandboxed sampleData parse (no executable code, JSON only)
2. **Bundle version conflict** — bundle X v1.4 deps require shared/countries v2.x, but другой bundle Y deps require shared/countries v1.x. Mitigation:
- Resolver detect conflict at dry-run, return 409 conflict с explanation
- Recommend admin: deinstall Y or wait until Y updates
3. **Breaking schema change в new version** — bundle v2.0 removes field `mass_kg`, existing records have it. Mitigation:
- `migrations` block в manifest documents breaking changes
- Upgrade endpoint requires `acknowledgeBreaking: true` flag
- Audit log records upgrade event with migration summary
4. **Registry down при install** — admin clicks install, Nexus 503. Mitigation:
- User-friendly error «Catalog временно недоступен, повторите через минуту»
- Local cache: recently viewed manifests cached 1h
- Circuit breaker на Resolver level
5. **Schema-level FK references to non-existing dicts** — bundle dict A references dict B, B installed позже. Mitigation:
- Resolver topologically sort install order
- Atomic transaction (all-or-nothing)
- Cross-bundle FK: explicit dependency declaration в manifest, resolver enforces
6. **Sample data сбивает existing records** — install bundle с sample data, customer уже имеет records с теми же businessKeys. Mitigation:
- Default: `seedSampleData: false`
- If true: dry-run shows count of records, admin confirms
- Skip records existing с тем же businessKey (idempotent)
---
## Test plan
| # | Test | Type |
|---|---|---|
| 1 | Happy path: install bundle с 5 dicts → все 5 created, sample data seeded | integration |
| 2 | Dry-run mode returns preview without DB changes | integration |
| 3 | Conflict detection: install bundle с existing dict name → 409 | integration |
| 4 | Namespace strategy: prefix всех dict names с bundle id | integration |
| 5 | Signature verification: tampered manifest → 422 | integration |
| 6 | Signature verification: unknown author → 422 with «author not trusted» | integration |
| 7 | Dependency resolution: install bundle X depending on Y → 409 если Y absent | integration |
| 8 | Topological install order: bundle с inter-dict FK → outer FK created first | integration |
| 9 | Atomic transaction: failure mid-install rolls back ALL changes | integration |
| 10 | Outbox events: install 5 dicts → 5 NewDictionaryCreated events in outbox | integration |
| 11 | Registry timeout: Nexus 503 → user-friendly 502 + retry | integration |
| 12 | Circuit breaker: 10 fails → 5min cool-down | integration |
| 13 | Bundle uninstall: deletes dicts + records + emits delete events | integration |
| 14 | Uninstall blocked если dicts have records authored locally (non-sample) | integration |
| 15 | Frontend BundleCatalogPage shows verified badge | RTL |
| 16 | Frontend BundleInstallModal — preview correctly counts new/updated/conflicts | RTL |
| 17 | Multi-tenancy: customer A не видит customer B private bundles | integration |
---
## Effort
| Step | Effort (CC) | Notes |
|---|---|---|
| 1. `installed_bundles` table migration | 1h | Standard Liquibase |
| 2. `InstalledBundle` JPA entity + repo | 1h | Standard JPA |
| 3. `BundleResolver` (fetch + parse) | 6h | HTTP client + YAML + JSON parse |
| 4. `BundleSignatureVerifier` (ed25519) | 4h | BouncyCastle JCA |
| 5. `BundleCatalogController` (read endpoints) | 3h | Standard REST |
| 6. `BundleInstallController` (dry-run + apply) | 8h | Transactional, conflict detection, atomic |
| 7. Topological install order + dep resolution | 4h | Kahn's algorithm на dict deps |
| 8. Frontend `BundleCatalogPage.tsx` | 6h | Standard list + search + filter |
| 9. Frontend `BundleInstallModal.tsx` (dry-run preview) | 6h | Preview UI, diff visualization |
| 10. Frontend `InstalledBundlesTab.tsx` | 4h | List + uninstall action |
| 11. Bundle publisher CLI (Maven plugin) | 8h | Sign + upload to Nexus |
| 12. i18n keys (~25 strings ru/en) | 1h | Standard |
| 13. Tests (17 cases) | 16h | testcontainers + RTL |
| 14. Docs (admin guide + publisher guide + ops runbook) | 6h | docs/user-guide/marketplace.md |
| **Total** | **~74h (~10 рабочих дней)** | within 1.5 sprints |
---
## Open questions
1. **Где будут жить public ДЗЗ catalog editors?** Кто signs verified bundles от имени community? Suggestion: ЦУОД core team initially, expand by invitation later.
2. **Bundle CI/CD pipeline для авторов?** Authors write bundle.yaml + sample data → CI signs + uploads to Nexus? Yes — provide Maven plugin (`ordinis-bundle-publisher`) which integrates с GitLab CI. ~1 day extra effort.
3. **Versioning policy?** SemVer (major.minor.patch). Breaking schema changes = major bump. Recommend documenting в `docs/user-guide/bundle-authoring.md`.
4. **Sample data ownership после install?** Records seeded из bundle — owned by «system» user, audit log helps trace. Customer-edited records → owned by customer.
5. **Cross-bundle FK?** Bundle X dict X-A references bundle Y dict Y-B. Allowed? Suggestion: yes, declare explicitly в `dependencies`, resolver enforces install order.
6. **Bundle update flow?** v1: deinstall + install new version (loses customer-edited records). v2: incremental upgrade с migration. Add to backlog.
7. **Integration with AI schema assist?** AI suggestion → save as bundle → publish? Это **product-market-fit gold**: customer создаёт schema с AI, publish'нет в catalog, monetize'нет / share'нет. v2 idea, defer.
---
## Combined value with `ai-schema-assist.md`
Эти два дизайна имеют **massive synergy**:
| Без AI + без marketplace | + AI | + Marketplace | + Оба |
|---|---|---|---|
| Customer пишет 40 schemas вручную ~3 недели | Customer пишет 40 schemas с AI ~3 дня | Customer берёт готовый bundle ~30 сек | Customer описывает домен («гидрометеостанции») → AI генерит bundle → publishes → другие installer'ят |
**Compounding value loop:** AI lowers bar to create bundles → marketplace enables sharing → more bundles → more demand → more AI usage → more bundles.
---
## Recommendation
**Defer until после v2.14.0 prod stable + 2 weeks dogfood, + AI design `/office-hours`'d first** (поскольку AI affects bundle authoring flow).
**Sequencing:**
1. v2.14.0 prod stable + dogfood ~2 weeks (current)
2. `ai-schema-assist.md` — `/office-hours` → `/plan-eng-review` → implement (5-7 days)
3. Use AI assist для production, gather feedback ~1 month
4. `dictionary-marketplace.md` — `/office-hours` → `/plan-eng-review` → implement (10-14 days)
5. Public catalog launch — Q3-Q4 2026
**Это потенциально strongest product differentiator** для МДМ-продукта на рынке — combine AI + Marketplace + ДЗЗ domain expertise = **product nobody else has** в RU/CIS МДМ-сегменте.
---
## See also
- Companion: `ai-schema-assist.md` — AI-assisted authoring (sequencing prerequisite)
- Roadmap mention: `docs-internal/status/2026-05-05-state.md` § "v2 (governance / data quality / federation)" — Federation MDM-кластеров (related but not same)