# Приложение Д: Архитектура и связи *Приложение Д к РГ-СМК-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 даёт фильтр, формат и роутинг. **Настройка:** 1. В Zulip: создать incoming webhook bot, сгенерировать URL на нужный канал/тему (или направить на n8n). 2. В BookStack (`Settings → Webhooks`): endpoint = URL n8n (или Zulip напрямую); выбрать события (создание/обновление страницы), не «все подряд». 3. Включить асинхронную очередь BookStack (`bookstack-queue.service`), чтобы вебхуки не тормозили интерфейс. 4. В n8n: ветка по полке/книге → формирование сообщения → отправка в Zulip incoming webhook. **Маршрутизация (полка → канал):** | Событие в BookStack | Куда в Zulip | | --- | --- | | Полка «СМК»: страница создана/обновлена | `#качество` › тема `База знаний: обновления` | | Полка «Инженерный»: страница создана/обновлена | `#проектирование` › `База знаний: обновления` | | Полка «Коммерческий»: страница обновлена | `#продажи` › `База знаний: обновления` | | Любая полка: удаление страницы | `#общее` (или служебный лог) | Уведомления держать тихими: только создание/обновление страниц, не каждый промежуточный сейв. Обсуждение изменения — в Zulip под `Регламент:`, со ссылкой на страницу KB; сам документ остаётся каноном в BookStack. --- ## 5. Индексация Onyx * **Источники:** Zulip (обсуждение), BookStack/KB (канон), CRM/ERP (сущности). * **Приоритет в ответах:** KB — для «что является истиной», Zulip — для «что нового по статусу». * **Якоря retrieval:** сущности (контрагент/объект/проект) и префиксы тем — по ним строятся ассистенты и срезы. * **Доступ:** индексируется то, что видит токен коннектора; закрытые полки/каналы — не подписывать или отдельный document set. --- ## 6. Ключевые потоки 1. **Обновление канона.** Правка страницы в KB → webhook → n8n → уведомление в `#качество`; Onyx переиндексирует страницу. Канон один, в BookStack. 2. **Решение → норма.** `Решение:` в Zulip, если становится правилом, оформляется страницей в KB и дальше живёт каноном. 3. **Сквозной запрос.** Вопрос в Onyx → ответ собирается из KB (канон) + Zulip (статус) + CRM/ERP (сущность), с цитатами. 4. **Жизнь заказа.** Сущность в 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` — приложение Г: словарь.