Приложение Д: Архитектура и связи

Приложение Д к РГ-СМК-Zulip-01.

Карта системного ландшафта: какие системы за что отвечают, что куда передаётся и каким механизмом. Термины — в словаре (приложение Г).

Стек одним предложением: сущности — в CRM/ERP, документы — в KB (BookStack), обсуждение — в Zulip, поиск поверх всех — Onyx; склейка событий — через n8n.

1. Слои и поиск

                  ЛЮДИ — сотрудники АйТека
     пишут/читают в Zulip и BookStack · спрашивают Onyx
          │                  │                   │
          ▼                  ▼                   ▼
  ┌──────────────┐  ┌──────────────┐   ┌──────────────┐
  │    Zulip     │  │ BookStack KB │   │  CRM / ERP   │   ИСТОЧНИКИ
  │ обсуждение,  │  │ канон:       │   │ сущности:    │   ИСТИНЫ
  │ статусы,     │  │ регламенты,  │   │ контрагент / │
  │ заказы(темы) │  │ стандарты,КД │   │ объект/проект│
  └──────┬───────┘  └──────┬───────┘   └──────┬───────┘
         │ коннектор       │ коннектор        │ коннектор
         └─────────────────┴──────┬───────────┘
                                  ▼
                         ┌────────────────┐
                         │      Onyx      │  RAG-поиск, цитируемые ответы
                         │ индекс 3-х     │  приоритет: KB = канон,
                         │ источников     │  Zulip = свежий статус
                         └────────────────┘

Каждый слой — единственный источник истины в своей зоне: Zulip = что происходит и как пришли к решению; KB (BookStack) = что является истиной (документы); CRM/ERP = сущности и транзакции. Onyx ничего не хранит сам — он индексирует все три и отвечает поверх них.

2. Интеграции (событийная склейка)

  BookStack ──webhook (событие, Slack-формат)──► n8n ──► Zulip
   (изменилась страница канона)               маршрут   (уведомление в
                                              по полке   #качество и др.)

  CRM/ERP ◄──── интеграция / API (LeanTech) ────► GRACE
            (стыковка данных)                  (приложение АйТека)

n8n — шина-оркестратор: принимает события, маршрутизирует и форматирует. GRACE — приложение АйТека; его стыковку с данными (CRM/ERP) ведёт LeanTech.

3. Связи — что куда и как

Откуда → Куда	Механизм	Что передаётся	Отвечает
Zulip → Onyx	коннектор Zulip (бот)	темы/сообщения (обсуждение)	LeanTech
BookStack → Onyx	коннектор BookStack	канон-страницы	LeanTech
CRM/ERP → Onyx	коннектор / API	сущности	LeanTech
BookStack → Zulip	webhook → n8n → incoming webhook	уведомления об изменении канона	LeanTech
CRM/ERP ↔ GRACE	интеграция / API	данные (стыковка)	LeanTech
Zulip ↔ CRM/ERP	ссылки в карточке проекта (+ API)	связь темы-заказа с записью	LeanTech + Продажи
Onyx → Люди	чат / поиск	цитируемые ответы	—

Граница доступа = граница индексации: коннектор видит только то, что разрешено его токену. Чувствительное (цены, переговоры, закрытые полки KB) — не индексируется либо идёт в отдельный document set.

4. BookStack ↔ Zulip — how-to

BookStack умеет отправлять исходящие вебхуки в Slack-совместимом формате (Zulip их принимает напрямую), и их можно фильтровать по событию аудит-лога. Два варианта:

Просто: вебхук BookStack → напрямую в Zulip incoming webhook URL → одна тема в одном канале. Без маршрутизации.
С маршрутизацией (рекомендуется): вебхук BookStack → n8n → нужный канал/тема в зависимости от полки. n8n даёт фильтр, формат и роутинг.

Настройка:

В Zulip: создать incoming webhook bot, сгенерировать URL на нужный канал/тему (или направить на n8n).
В BookStack (Settings → Webhooks): endpoint = URL n8n (или Zulip напрямую); выбрать события (создание/обновление страницы), не «все подряд».
Включить асинхронную очередь BookStack (bookstack-queue.service), чтобы вебхуки не тормозили интерфейс.
В n8n: ветка по полке/книге → формирование сообщения → отправка в Zulip incoming webhook.

Маршрутизация (полка → канал):

Событие в BookStack	Куда в Zulip
Полка «СМК»: страница создана/обновлена	`#качество` › тема `База знаний: обновления`
Полка «Инженерный»: страница создана/обновлена	`#проектирование` › `База знаний: обновления`
Полка «Коммерческий»: страница обновлена	`#продажи` › `База знаний: обновления`
Любая полка: удаление страницы	`#общее` (или служебный лог)

Уведомления держать тихими: только создание/обновление страниц, не каждый промежуточный сейв. Обсуждение изменения — в Zulip под Регламент:, со ссылкой на страницу KB; сам документ остаётся каноном в BookStack.

5. Индексация Onyx

Источники: Zulip (обсуждение), BookStack/KB (канон), CRM/ERP (сущности).
Приоритет в ответах: KB — для «что является истиной», Zulip — для «что нового по статусу».
Якоря retrieval: сущности (контрагент/объект/проект) и префиксы тем — по ним строятся ассистенты и срезы.
Доступ: индексируется то, что видит токен коннектора; закрытые полки/каналы — не подписывать или отдельный document set.

6. Ключевые потоки

Обновление канона. Правка страницы в KB → webhook → n8n → уведомление в #качество; Onyx переиндексирует страницу. Канон один, в BookStack.
Решение → норма. Решение: в Zulip, если становится правилом, оформляется страницей в KB и дальше живёт каноном.
Сквозной запрос. Вопрос в Onyx → ответ собирается из KB (канон) + Zulip (статус) + CRM/ERP (сущность), с цитатами.
Жизнь заказа. Сущность в CRM/ERP → карточка Проект: в Zulip ссылается на запись → статус по шлюзам G0–G8 → применимые стандарты подтягиваются из KB.

7. Границы и ответственность

LeanTech (партнёр по внедрению): платформа Zulip, KB/BookStack, Onyx, n8n; все коннекторы и интеграции; стыковка GRACE.
Отдел менеджмента качества (СМК): владелец процесса и словаря; контроль соблюдения; раздел СМК в KB.
Отдел цифровизации АйТека: разработка приложения GRACE.
Ведущие отделы стадий: наполнение своих каналов и разделов KB.

Полная матрица — регламент, п. 6.

Связанные документы

itech-zulip-reglament-start.md — ядро (стандарт).
itech-zulip-ontology.md — приложение А: грамматика тем.
itech-zulip-channels-valuestream.md — приложение Б: карта потока.
itech-zulip-project-entity-model.md — приложение В: сущностная модель.
itech-glossary.md — приложение Г: словарь.