---
компонент: МастерАпп — «Капюшон»
статус: черновик v2
обновлено: 2026-08-28
имя во вселенной: Капюшон (предложено, требует утверждения)
связано: [[chesuyka]] — поверхности и мерка · [[ada]] — та же витрина как PWA
сверено: WEBAPP_INTEGRATION.md — гайд платформы ботов AI Delivery
---

# МастерАпп

## Что это

**МастерАпп — единственная дверь в мессенджере.** Один бот, одна кнопка, а за ней — всё:
агенты пространства и чешуйки, между которыми человек выбирает сам.

Открывается как карманный вебапп внутри Telegram, MAX или WhatsApp. Внутри — плитки: слева «Финансы»,
рядом «Отпуска», дальше «Контент-завод», «Пульс клиента», «Реферальная программа». Нажал —
попал. Вернулся — снова список.

В каноне эта сущность уже работает, просто не названа. Выпуск №4 «Дело о восьми иконках»:
«у каждого сотрудника есть апп под кодовым названием AI Delivery: восемь агентов Алины —
от зарплаты и отпусков до прокачки собственного аватара». Вот этот апп и есть МастерАпп.

**И он уже реализован.** Это не концепция и не задача на будущее: встроенный вебапп живёт по
адресу `${WEBHOOK_URL}/agents`, и боты платформы открывают его как цель по умолчанию для кнопки
«Открыть приложение». Всё, что ниже, — описание того, как он устроен и что можно заменить своим.

## Зачем он нужен

Без него каждая чешуйка и каждый агент требуют **своего бота**: своя ссылка, своя подписка,
своя установка, своё место в списке чатов. Пять чешуек — пять ботов, и человек не помнит,
в каком из них лежит то, что ему сейчас нужно.

| | Без МастерАппа | С ним |
|---|---|---|
| Ботов у человека | по одному на возможность | **один** |
| Новая чешуйка | новый бот, новая рассылка «установите» | плитка появляется сама |
| Права | у каждого бота свои | считаются один раз, на входе |
| Вход в систему | в каждом заново | один раз, дальше внутри |
| Брендирование | в каждом отдельно | в одном месте |

Главное — четвёртая строка. Личность резолвится **один раз при открытии мастера**, дальше
человек ходит внутри уже узнанным. Это то, ради чего мастер и существует.

---

# Имя во вселенной

## Предложение: **Капюшон**

Кобра собрана из **чешуек**. А **капюшон** — то единственное, что она раскрывает навстречу
человеку: раскрылся — и видно всё, что она есть. Имя ложится в один ряд с чешуйками, потому что
взято из той же анатомии, и сразу объясняет функцию: одна поверхность, за которой всё остальное.

| Поле досье | Значение |
|---|---|
| **Имя** | Капюшон |
| **В продукте** | МастерАпп: единая дверь в мессенджере. Внутри — агенты и чешуйки, между которыми выбирает человек |
| **В комиксе** | Раскрытый капюшон кобры; на внутренней стороне — сетка шестигранных чешуек-иконок, каждая тихо светится. Раскрывается навстречу — закрывается за спиной |
| **Чувствует** | Собранность — «всё моё при мне. Скажи, что нужно» |
| **Реплика** | «Не ищи, где это лежит. Смотри сюда» |
| **С кем дружит** | Чешуйки (показывает их), Оркестратор (передаёт ему выбор), Гриф (решает, какие плитки видны), Ада (та же витрина, но на домашнем экране) |

Запасные варианты, если «Капюшон» не приживётся: **Веер** (раскрывается, и в нём все грани)
и **Прихожая** (комната, из которой все двери). Оба слабее: не из анатомии кобры.

## Как добавить в канон

1. **Строка в таблице сущностей** `COBRA-CANON.md` — рядом с Чешуйками:
   `| **Капюшон** | МастерАпп: одна дверь в мессенджере, за ней агенты и чешуйки | раскрытый капюшон с сеткой чешуек |`
2. **Страница героя** `site/entity-hood.html` по образцу `entity-arti.html`: кто это в продукте,
   кто в комиксе, где встречается. Нужна иллюстрация — генерится через `generate-art.mjs`.
3. **Упоминание в выпуске №4** — там сущность уже показана, но безымянная. Достаточно назвать:
   «восемь иконок» это и есть Капюшон.
4. **Строка в пяти столпах** — не нужна. Капюшон не отдельный столп, а способ показать
   существующие.

---

# Как устроен

## Один вход, много назначений

```
бот в Telegram / MAX / WhatsApp
    └── МастерАпп  ←── личность резолвится здесь, один раз:
                        initData → /api/webapp/auth  (Telegram, MAX)
                        ?t=      → /api/webapp/exchange (WhatsApp, браузер)
         ├── агент «Финансы»        → чат с агентом
         ├── агент «Отпуска»        → чат с агентом
         ├── Контент-завод          → карманная раскладка чешуйки
         ├── Пульс клиента          → карманная раскладка чешуйки
         └── Реферальная программа  → карманная раскладка чешуйки
```

Плитки бывают двух родов, и это разные вещи:

- **Агент** — за плиткой начинается разговор. Мастер передаёт выбор Оркестратору и открывает
  диалог с нужным агентом.
- **Чешуйка** — за плиткой открывается интерфейс: её карманная раскладка, та самая, что описана
  в спецификации чешуйки. Отдельного приложения не появляется.

## Что мастер обязан уметь

| Умение | Зачем |
|---|---|
| Собрать список плиток под конкретного человека | у разных ролей разный набор |
| Открыть плитку без перезагрузки | иначе каждое возвращение — новая загрузка и новая подпись |
| Вернуться назад в список | системной кнопкой хоста, не своей |
| Открыть нужную секцию по `?open=` | агент приводит человека прямо туда, где его ждут |
| Пережить закрытие | вернулся через час — там, где был |
| Показать, что нового | точка на плитке: пришло согласование, ответил клиент |

Плюс четыре вызова, без которых мастер считается недоделанным:

| Когда | Что вызвать |
|---|---|
| приложение загрузилось | `Telegram.WebApp.ready()` / `WebApp.ready()` — иначе не уйдёт заставка |
| закрывается | `POST /api/bot/{botId}/user/{userId}/stopProject` — остановить сессию проекта |
| выгружается | `POST /api/bot/{botId}/logout` |
| открылся с `?open=coin_packs` | сразу показать экран пополнения, если у бота `is_paymentable` |

## Что приезжает в адресе

Платформа собирает ссылку сама и дописывает к базовому адресу один и тот же набор параметров:

```
{base_url}?t={одноразовый_токен}
           [&ref={uuid_владельца}]
           [&authProjectId={id_проекта}]
           [&platform=whatsapp]
           [&open={секция}]
```

| Параметр | Когда | Зачем |
|---|---|---|
| `t` | **всегда** | одноразовый токен, за которым доверенная пара `(bot_id, user_id)`. Основной способ узнать человека вне контейнера мессенджера |
| `ref` | только у владельца бота | UUID владельца — узнать его между сессиями |
| `authProjectId` | если настроено | проект режима регистрации `agent`; интерфейс может прятать его из списка |
| `platform` | только у WhatsApp | подсказка «мы в браузере, SDK нет». Дописывается платформой, руками не передавать |
| `open` | в особых случаях | открыть сразу нужную секцию, например `coin_packs` — экран пополнения |

**`open` — это и есть механизм прямых ссылок.** Не выдумывать свой формат: платформа уже умеет
приводить человека в нужную секцию, и агент должен пользоваться этим параметром.

Легаси `botId` / `userId` в адресе хук авторизации ещё принимает, но они небезопасны и текущим
кодом ботов не дописываются. В новом коде на них не опираться.

## Права: набор плиток считает сервер

**Список плиток собирает сервер мастера** — по роли человека, по тому, что ему открыто,
и по настройкам установки.

Роль спрашивается у платформы: `GET /api/bot/{botId}/user/{userId}/role` → `owner`, `admin`,
`member` или `guest`. ⚠️ Это **не те же роли, что в рабочем пространстве Кобры**
(`owner` / `admin` / `user`) — модели разные, и путать их нельзя: в кармане человек может быть
`guest`, будучи при этом администратором пространства.

Правило прежнее и жёсткое: **плитку не «скрываем в интерфейсе», а не отдаём в ответе.**
Иначе список всех возможностей компании достаётся любому, кто откроет отладчик.

---

# Настройка внешнего вида

Заказчики разные, и мастер — первое, что они видят. Кастомизация устроена ступенями:
чем выше ступень, тем больше свободы и тем дороже.

## Ступень 0 — Фирменный

Логотип, акцентный цвет, имя приложения, приветствие. Настройки в админке, применяется сразу.
**Подходит почти всем.**

## Ступень 1 — Состав и порядок

Какие плитки показывать, как они названы, в каком порядке, в каких группах, что спрятать.
Тоже настройки — но уже про смысл, а не про цвет.

Здесь же — **стартовое поведение**: открывать список или сразу самую частую плитку.

## Ступень 2 — Своя обложка

Свой фон и обложка, свои иконки плиток, свой текст приветствия, свой порядок разделов,
собственная плитка-баннер со ссылкой куда угодно. Настройки плюс загрузка картинок.

Внешне это уже приложение заказчика, хотя код наш.

## Ступень 3 — Полностью свой мастер

Заказчик получает **не наш экран, а собственное приложение-витрину**. Стандартный мастер
при этом выключается.

Механика проще, чем кажется: **это одно поле** — `bot.custom_webapp_url` в настройках бота
(или `PATCH /api/bot/{id}`). Платформа дописывает к вашему адресу тот же самый набор параметров
из раздела выше, а дальше всё на вас.

А вот «дальше всё на вас» — как раз сложная часть. Чтобы полноценно заменить встроенный мастер,
приложение обязано:

1. определить мессенджер — по SDK или по `?platform=whatsapp`;
2. резолвить личность — `/api/webapp/auth` или `/api/webapp/exchange`, и закэшировать;
3. забрать данные — `GET /api/user/{userId}?bot_id=` и `GET /api/bot/{botId}/info`;
4. показать список проектов — `GET /api/bot/{botId}/user/{userId}/projects`;
5. обработать `?open=coin_packs`;
6. сделать «Поделиться» с ветками под каждый мессенджер;
7. вызвать `ready()` после загрузки;
8. вызвать `stopProject` при закрытии;
9. вызвать `logout` при выгрузке.

Девять пунктов — это и есть настоящая цена ступени 3, а не «поменяли ссылку».

Когда это оправдано: у заказчика своя навигация, свой язык, свои сущности на главном экране —
например витрина каталога вместо списка плиток, а чешуйки прячутся внутрь его логики.

⚠️ Важно понимать, что происходит на этой ступени: **свой мастер — это уже чешуйка.**
По мерке всё сходится — одна боль («попасть туда, куда нужно»), три экрана, свой словарь.
Значит и делается он как чешуйка, со своим манифестом, правами и документацией, а не как
«ещё одна настройка». Считать его настройкой — самый быстрый способ получить неподдерживаемый
форк на каждого клиента.

| Ступень | Что меняется | Кто делает | Срок |
|---|---|---|---|
| 0 · Фирменный | цвет, логотип, имя | администратор | минуты |
| 1 · Состав | плитки, порядок, группы | администратор | минуты |
| 2 · Обложка | фон, иконки, приветствие, баннер | администратор + дизайнер | часы |
| 3 · Свой мастер | всё | разработка: одно поле `custom_webapp_url` + девять обязанностей | недели |

---

# Мастер на разных хостах

Раскладка одна, хостов несколько — как и у остальных поверхностей:

| Хост | Что меняется |
|---|---|
| **Telegram** | контейнер Mini App, `initData` → `/api/webapp/auth`, «назад» системной кнопкой |
| **MAX** | то же, но мост MAX Bridge (`window.WebApp`) |
| **WhatsApp** | контейнера нет: обычная вкладка браузера, только `?t=` и `?platform=whatsapp`. SDK-методы не вызывать, кнопок не больше трёх |
| **ADA (PWA)** | мастер становится **главным экраном приложения**; `initData` неоткуда взять, работает путь с `?t=` |
| **Кобра** | внутри рабочего места мастер не нужен: там есть рейл и правая панель, они и есть навигация |

Последняя строка важна. **В Кобре мастер не показывать** — он дублирует то, что уже делает
интерфейс рабочего места, и только путает оператора.

# «Поделиться» — своя ветка на каждый мессенджер

Мастер умеет отдать ссылку на проект наружу. Дилинки готовит платформа:
`GET /api/bot/{botId}/project/{projectId}/share?platform=…` возвращает сразу все —
`{link, token, telegram, max, whatsapp}`.

| Мессенджер | Кнопка | Действие |
|---|---|---|
| Telegram | «Поделиться в Telegram» | `openTelegramLink` на `t.me/share/url?url=…&text=…` |
| MAX | «Поделиться в MAX» | `shareMaxContent({link, text})` → запасное `shareContent` → `openLink` |
| WhatsApp | «Поделиться в WhatsApp» | `https://wa.me/?text=<text>%0A<link>` |

Если бот не настроен на мессенджере, поле приходит пустым — **кнопку прятать**, а не показывать
неработающей.

# Правила отображения

1. **Плитка объясняет себя за секунду** — понятная иконка и слово, а не аббревиатура.
2. **Не больше того, что помещается на экран без прокрутки** — если плиток больше девяти,
   значит нужны группы, а не длинный список.
3. **Пустых плиток нет.** Возможность, которой у человека нет, не показывается серой —
   она не показывается вовсе.
4. **Возврат всегда одинаковый** — из любой плитки одна и та же кнопка возвращает в список.
5. **Индикатор нового не врёт.** Точка на плитке означает, что там действительно ждут именно
   этого человека, а не что там вообще что-то произошло.
6. **Первый экран не спрашивает разрешений** — ни уведомлений, ни геолокации. Сначала польза.

# Чек-лист

- [ ] один бот на пространство, а не по боту на возможность
- [ ] подпись проверяется один раз, на входе в мастер
- [ ] список плиток собирает сервер по роли; скрытая плитка не приходит в ответе
- [ ] переход в плитку и назад — без перезагрузки и без повторной подписи
- [ ] есть прямые ссылки в конкретную плитку и внутрь неё
- [ ] состояние переживает закрытие приложения
- [ ] «назад» — системная кнопка хоста
- [ ] в Кобре мастер не показывается
- [ ] `ready()`, `stopProject` и `logout` вызываются в нужные моменты
- [ ] `?open=` обрабатывается, свой формат прямых ссылок не выдуман
- [ ] роль берётся из `/api/bot/{botId}/user/{userId}/role` и не путается с ролью в Кобре
- [ ] WhatsApp учтён: SDK не вызывается, кнопок не больше трёх
- [ ] «Поделиться» ветвится по мессенджеру, пустые дилинки прячутся
- [ ] ступени кастомизации 0–2 закрыты настройками, без правок кода
- [ ] решено, что ступень 3 — это отдельная чешуйка со своим манифестом

# Где обычно ломается

1. **Бот на каждую чешуйку** — человек не помнит, в каком боте что лежит, и не пользуется ничем.
2. **Плитки скрыты только в интерфейсе** — полный список возможностей компании виден в отладчике.
3. **Каждое возвращение в список — новая загрузка** — мастер начинает восприниматься как тормоз,
   и им перестают пользоваться.
4. **Нет прямых ссылок** — агент не может позвать человека в нужный экран, и единая дверь
   превращается в список.
5. **Серые недоступные плитки** — витрина того, что вам не дали. Раздражает и провоцирует вопросы.
6. **Кастомный мастер как настройка** — форк на каждого клиента, который некому поддерживать.
   Ступень 3 — это чешуйка, и делается по её правилам.
7. **Мастер внутри Кобры** — дублирует рейл и правую панель, путает оператора.
8. **Свой формат прямых ссылок** — платформа уже присылает `?open=`, а самодельный параметр
   она не поставит, и агент не сможет привести человека в нужную секцию.
9. **Роли перепутаны** — `guest` в кармане и `admin` в пространстве это про разные системы.
10. **`custom_webapp_url` поставили, а девять обязанностей не сделали** — приложение открывается,
    но заставка висит, сессии не закрываются и «Поделиться» не работает.

# Источники

- Канон COBRA: выпуск №4 «Дело о восьми иконках» — апп AI Delivery, восемь агентов Алины
- `COBRA-CANON.md` — таблица сущностей, куда добавляется Капюшон
- [Спецификация чешуйки](manifest-chesuyka.md) — карманная раскладка, мерка, права
- [ADA](manifest-ada.md) — тот же мастер как главный экран PWA

---

_Источник: `cobra-components/master-app.md` в репозитории audio-talks. Эта копия обновляется скриптом `sync-components.mjs` — правки вносить в источник, не здесь._