---
title: "Адмінська Wiki"
description: "Postgres-сховище знань у Markdown на кшталт Obsidian для адміністраторів, покупців, інтеграторів, агентів ring-mcp і сторінок продуктового NODUS зі Store Research"
locale: "uk"
---
# Адмінська Wiki

> **Info**
> Використовуйте вкладки **Founder** / **Developer** на бічній панелі документації, щоб відфільтрувати цю сторінку. Admin Wiki — це **накопичувальна база знань проєкту** (Markdown + `[[wikilinks]]`), а не файловий каталог MDX у `/docs` і не Markdown CMS новин (NewsRichEditor + shortcode-и). Особисті файли учасників зберігаються в [Ring File Cabinet](/docs/features/file-cabinet.md), а не у wiki-сховищі.

Клони Ring зберігають **операційні знання** у сховищі Postgres: сторінки на рівні tenant і необов’язкові простори **project-order**. Люди редагують їх у `/admin/wiki` та на робочих столах Order Lab, а агенти шукають і змінюють їх через **ring-mcp**, використовуючи те саме WikiKernel.

| Рівень | Де |
|-------|--------|
| UI | `/admin/wiki` · buyer `/my-orders/[id]` · integrator `/my-jobs/[id]` |
| Навігація | Суперменю адміністратора **Content & Blog** → Wiki · заголовок і дії правої панелі |
| Ядро | `features/wiki/**` (`wiki-service.ts`, ACL, wikilinks, search) |
| Колекції | `wiki_pages`, `wiki_links`, `wiki_events` |
| Міграція | `data/migrations/040_wiki_pages.sql` |
| HTTP | `/api/wiki`, `/api/wiki/[id]` |
| MCP | `/api/mcp/v1/wiki*` · інструменти `ring-wiki-*` |

```mermaid
flowchart LR
  AdminUI["/admin/wiki"] --> Kernel["WikiService"]
  DeskUI["my-orders / my-jobs"] --> Kernel
  RingMCP["ring-wiki-*"] --> Kernel
  Kernel --> Pages["wiki_pages"]
  Kernel --> Links["wiki_links"]
  Kernel --> Events["wiki_events"]
```

### For founders

## Чому це важливо для вашого клону

Чати й тікети забувають. Wiki **компілює** те, що ваш клон знає про проєкт поселенця: бренд-рішення, нотатки про деплой, передачу роботи інтегратору — із посиланнями, що залишаються актуальними.

  
- **[Консоль адміністратора](/docs/features/admin.md)** — Wiki з’являється в суперменю адміністратора в розділі Content & Blog і в правій панелі поруч із редактором.

  
- **[Owner Project Lab](/docs/features/owner-project-lab.md)** — Кожне оплачене замовлення проєкту може відкрити сховище проєкту на робочих столах покупця та інтегратора.

  
- **[Замовлення проєктів CRM](/docs/features/owner-project-lab.md)** — Переходьте з дій Wiki до `/admin/crm/orders`, коли сторінка належить завданню ringization.

  
- **[Ring MCP](/docs/development/ring-mcp.md)** — Агенти самостійно створюють і запитують сховище без відкриття UI.

  
- **[Знання агента Store](/docs/features/store.md)** — Research створює wiki-сторінки продуктового NODUS через createProductNodusWikiFromDraft / wikiCreateAction.

### Типові сценарії

1. **Плейбук платформи** — адміністратори зберігають tenant-сторінки про те, “як ми ringize-мо”, платіжні рейки та макроси підтримки.
2. **Мозок окремого замовлення** — покупець та інтегратор спільно використовують сховище `po:{orderId}` для рішень цього клону (без секретів — вони залишаються в `#secrets` Order Lab).
3. **Імпорт агентом** — ring-mcp створює/оновлює концептуальні сторінки, додає операційні події та перевіряє недійсні `[[wikilinks]]`.
4. **Продуктовий NODUS зі Store Research** — **Agent Knowledge → Research** від Vendor/admin записує tenant wiki-сторінку (`Product NODUS — {name}`) і зберігає `productNodusWiki` у продукті — повний NODUS JSON у сховищі, короткий опис Markdown у продукті. Див. [Multi-Vendor Store](/docs/features/store.md).
5. **Посилання між сховищами** — із проєктної сторінки посилайтеся на поняття платформи через `[[@Payments]]` або `[[tenant:Payments]]`.

### Чекліст оператора

- Відкрийте `/admin/wiki` як адміністратор платформи; переконайтеся, що `_schema` створено (заголовок розташований у **правій панелі**).
- Використовуйте **Actions** правої панелі: CRM project orders, News, CRM tasks, Wiki docs.
- Створіть шлях папки (наприклад, `concepts`), задавши **path** для нових сторінок — папки є префіксами шляхів, а не порожніми документами.
- Використовуйте `[[Page]]` для посилань у тому самому сховищі; `[[@Title]]` — щоб цитувати tenant-знання з проєктного сховища.
- На `/my-orders/[id]` або `/my-jobs/[id]` використовуйте **Project Wiki** лише для цього замовлення.
- Ніколи не вставляйте ключі Firebase або токени RingBase у тіла wiki-сторінок.

### Хто що може записувати

| Актор | Tenant-сховище | Проєктне сховище |
|-------|-----------------|------------------|
| Admin / Buyer | Повне читання/запис | Повне (власні замовлення) |
| Integrator | Читання + **лише додавання** | Повне (призначені замовлення) |
| Agent (ring-mcp) | **Лише читання** | Повне |

### For developers

## Реалізація

WikiKernel відповідає за ACL, граф посилань, envelope пошуку та події. Адаптери тонкі: Admin UI, панель робочого столу, HTTP, MCP.

### Домен

- **`vaultKey`**: об’єднання TypeScript `tenant` | `po:{projectOrderId}` — це **поле сторінки**, а не env-змінна і не ключ `ring-config`.
- **SSOT тіла**: `bodyMarkdown` (не Markdown CMS новин) — Admin UI редагує через TipTap із багатим preview та перемикачем **Source Markdown**; збереження все одно записує Markdown. Статті новин використовують NewsRichEditor + shortcode-и `[[embed:]]` / `[[mood:]]` / `[[video:]]` замість wiki `[[wikilinks]]`.
- **Парсер wikilink**: ігнорує fenced- та inline-код (приклади в документації не створюють ребер графа).
- **Lint**: `ring-wiki-lint` / Lint vault; **Create stubs** автоматично створює чернетки концептуальних сторінок для реальних проблем `missing_page`.
- **SSOT графа**: ребра `wiki_links` (`local` | `tenant_ref`)
- **Каталог**: похідний список/пошук — підтримуваного `_index.md` немає
- **Журнал операцій**: `wiki_events`, лише додавання
- **Спеціальна сторінка**: tenant `_schema` створюється під час першого відкриття (конституція агента); тіло застарілого прикладу-посилання одноразово виправляється під час ensure
- **Дерево**: дерево папок перенесено з file-registry-viewer (`buildTree` / expand / кількість папок / ранжований швидкий пошук)

`VaultKey` — лише тип TypeScript у `features/wiki/types.ts`. **Не** додавайте `VAULT_KEY` до `.env` або `ring-config.json`. Файл із `'use server'` не повинен повторно експортувати типи або sync-хелпери — Next трактує кожен export як server action, і повторний export типів стає runtime `ReferenceError: VaultKey is not defined`. Зберігайте actions у `app/_actions/wiki.ts` лише як async-функції; імпортуйте типи з `@/features/wiki/types`.

### Wikilinks

| Форма | Розв’язання |
|------|-------------|
| `[[slug]]` / `[[Title]]` / `[[path/slug]]` / `[[Page\|display]]` | Те саме сховище |
| `[[@Payments]]` / `[[tenant:Payments]]` | Tenant-сховище |

### Карта модулів

| Зона | Шлях |
|---------|------|
| Типи / ACL / парсер / пошук | `features/wiki/types.ts`, `acl.ts`, `wikilink-parser.ts`, `search-score.ts` |
| Сервіс | `features/wiki/wiki-service.ts` |
| Визначення актора (buyer/integrator) | `features/wiki/resolve-wiki-actor.ts` |
| Робочий простір адміністратора | `features/wiki/components/wiki-workspace.tsx` |
| Панель робочого столу | `features/wiki/components/wiki-desk-panel.tsx` |
| Server actions | `app/_actions/wiki.ts` (лише async exports) |
| Права панель | секція `wiki` `admin-nav-config` rail + `admin-rail.tsx` |
| MCP-маршрути | `app/api/mcp/v1/wiki/**` |
| BackendSelector | `wiki_pages`, `wiki_links`, `wiki_events` |

### Інструменти ring-mcp

| Інструмент | Роль |
|------|------|
| `ring-wiki-search` | `matches[]` у формі Legiox (лексичний пошук) |
| `ring-wiki-list` / `get` | Каталог + зворотні посилання |
| `ring-wiki-create` / `update` / `delete` | CRUD (`confirm` для delete); створення/запис агентом у tenant заборонено |
| `ring-wiki-lint` | Сироти / недійсні посилання |
| `ring-wiki-events` | Список або додавання до журналу операцій |

### Застосуйте міграцію

```bash
psql "$DATABASE_URL" -f data/migrations/040_wiki_pages.sql
```

Також присутня в `data/schema.sql` для чистих інсталяцій. Окремі env-змінні для wiki не потрібні, окрім наявних Postgres `DATABASE_URL` / токена сервісу MCP.

### Викликайте WikiService лише з адаптерів

```typescript
import * as WikiService from '@/features/wiki/wiki-service'
import { resolveWikiActor } from '@/features/wiki/resolve-wiki-actor'
import type { VaultKey } from '@/features/wiki/types'

const actor = await resolveWikiActor({
  userId: session.user.id,
  role: session.user.role,
  orderId, // when scoping a project vault
})
await WikiService.ensureTenantSchema(actor)
const vault: VaultKey = 'tenant'
const pages = await WikiService.listPages(actor, vault)
```

MCP-обробники встановлюють `isAgent: true`, тому правила запису tenant застосовуються, навіть якщо роль токена сервісу — superadmin.

### Додавання замість заміни

```typescript
await WikiService.updatePage(actor, pageId, {
  bodyMarkdown: '## Note\nIntegrator addendum…',
  mode: 'append', // required for integrator on tenant
})
```

Wiki не повинна зберігати env-секрети Order Lab. Натомість спрямовуйте операторів до панелей `#secrets` / project-config (`features/crm/orders/*`).

- [features/admin](/docs/features/admin.md) — Наступний крок: SSOT навігації консолі адміністратора — Wiki розташована в Content & Blog і в правій панелі.

- [features/owner-project-lab](/docs/features/owner-project-lab.md) — Той самий процес: сховища проєктів відкриваються на робочих столах покупця My Projects та інтегратора Order Lab; стіл CRM orders — це дія правої панелі.

- [development/ring-mcp](/docs/development/ring-mcp.md) — Залежність: інструменти ring-wiki-* використовують той самий токен сервісу MCP, що й інструменти news/entity.

- [features/news](/docs/features/news.md) — Див. також: news — це Markdown-shortcode-и через NewsRichEditor; не зберігайте там тіла wiki.

- [architecture/data-model](/docs/architecture/data-model.md) — Поглиблення: шаблон колекцій JSONB (`id` + `data`), який використовують wiki_pages та споріднені таблиці.

- [features/file-cabinet](/docs/features/file-cabinet.md) — Див. також: спільні хелпери FileTree (`components/file-tree/tree-helpers.ts`) і такий самий шаблон JSONB id+data у таблицях file_cabinet_*.

- [features/store](/docs/features/store.md) — Той самий процес: Research у Agent Knowledge записує сторінки Product NODUS у tenant-сховище.