# AGIL Calls ↔ приложение компании: границы и API

Документ отвечает на вопрос «где заканчивается наш продукт и начинается система
заказчика, и через какие API они стыкуются». Он обязателен для интеграторов и
для команды: любой код, нарушающий эти границы, считается дефектом архитектуры.

## 1. Принцип

**AGIL Calls** — real-time слой: комнаты, медиа (WebRTC), чат, файлы, запись,
транскрипт, темы/дизайн-токены, **исполнение** прав, аудит и подписанные ссылки.
Мы не храним и не интерпретируем бизнес-контекст компании.

**Приложение компании** — владелец контекста: каталог сотрудников/IdP, wiki и
внутренние ресурсы, корпоративный AI-агент, правила комплаенса, политика
хранения, SIEM/DLP. Компания решает, **кто и к чему имеет доступ**, и передаёт
это нам декларативно (конфиг, токены с permissions, решения своего AI).

**Стык** — только документированные API:
- компания → нас: `PUT/PATCH` конфига тенанта, `POST /v1/tokens` (с
  `permissions`), access policy, admin API, knowledge/AI endpoint’ы, которые
  вызываем мы;
- мы → компанию: подписанные вебхуки событий, ответы API, MCP-инструменты.

## 2. Контекстная диаграмма

```
┌────────────────────────── Приложение компании ──────────────────────────┐
│  IdP/SSO          Каталог сотрудников        Wiki / внутренние ресурсы  │
│  (Keycloak и др.)       (HR/AD)              (Confluence, RAG-индекс)   │
│        │                    │                         │                 │
│        └──────────┬─────────┴──────────────┬──────────┘                 │
│                   ▼                        ▼                            │
│        ┌────────────────────┐   ┌──────────────────────────┐           │
│        │  Backend компании  │   │ Корпоративный AI-агент    │           │
│        │  (выпуск токенов,  │   │ (LLM + RAG + policy)      │           │
│        │   политика прав)   │   │ POST /ai/analyze          │           │
│        └─────────┬──────────┘   │ POST /knowledge/ask       │           │
│                  │              └──────────▲───────────────┘           │
└──────────────────┼─────────────────────────┼───────────────────────────┘
                   │  REST (x-api-key)        │ HTTPS + HMAC-подпись,
                   │  POST /v1/tokens         │ zod-валидация ответа
                   │  admin API               │
┌──────────────────▼─────────────────────────┴───────────────────────────┐
│                        AGIL Calls (наш продукт)                        │
│  Server: комнаты, WS-сигналинг, статика, access enforcement, аудит      │
│  Widget/SDK: WebRTC mesh, темы, чат, файлы, запись, STT, блюр            │
│  Dashboard: комнаты/инвайты/аудит/безопасность   Editor: темы/фичи      │
│  MCP: инструменты для нейросетей                                        │
│  Local: compliance-правила + экстрактивные заметки (fallback без AI)    │
└───────────────┬───────────────────────────────┬────────────────────────┘
                │ вебхуки (HMAC)                 │ JS SDK / iframe / REST
                ▼                               ▼
        Backend компании                    Браузер сотрудника
```

## 3. Кто что делает

| Возможность | AGIL Calls (готово из коробки) | Компания (передаёт нам) | API/контракт |
|---|---|---|---|
| Комната, медиа, чат, файлы | ✅ вся real-time часть | — | SDK/iframe, `/v1/rooms`, `/ws` |
| Дизайн/темы | ✅ токены, пресеты, рендер, аудит контраста | бренд-цвет, логотип, шрифты | `theme` в config, редактор, MCP |
| Вход в комнату | ✅ JWT-проверка, пароли, лобби, kick, lockout | кто и когда получает токен (SSO/каталог) | `POST /v1/tokens` |
| Права на функции | ✅ `resolveAccess` + UI gating + enforcement | политика: роли, per-user гранты, запреты | `PUT /v1/admin/access-policy`, `permissions` в токене |
| Wiki/внутренние ресурсы | ✅ прокси запроса, цитаты, аудит | RAG-поиск, права на документы, выдача ответа | `POST /v1/admin/knowledge/ask` → company endpoint |
| Анализ диалогов | ✅ STT, транскрипт, локальные правила, выдержки | корпоративная модель, свои правила, что хранить | `analysis` поток + `analysis.ready` webhook |
| Соответствие политике | ✅ фиксация findings, аудит, бейджи | сама политика и решения (mute/kick — компания через API) | findings + webhooks |
| Аудит/безопасность | ✅ JSONL-аудит, rate-limit, подписи, IP-хэши | SIEM, DLP, retention | `GET /v1/admin/audit`, `security.event` webhooks |
| Запись/файлы | ✅ хранение, подписанные ссылки, consent | политика хранения/удаления | `retentionMin`, `DELETE /v1/admin/recordings/:id` |
| Идентичность | ✅ проверка подписи, `verified` | IdP, SSO, роли | `identity.mode` (`token` сейчас, `oidc` — roadmap) |

## 4. API-поверхности

### 4.1 Что компания вызывает у нас
| API | Назначение | Auth |
|---|---|---|
| `POST /v1/tokens` | выпуск токена участника (с `permissions`, ролью, TTL) | `x-api-key` |
| `POST /v1/rooms`, `/v1/admin/rooms` | создать тестовую/рабочую комнату (пароль, лимиты) | `x-api-key` (или anonymous в demo) |
| `POST /v1/rooms/:id/invites` | ссылка-приглашение с TTL | `x-api-key` |
| `GET/PATCH/PUT /v1/tenants/:id/config` | тема, фичи, политики, AI/knowledge | public GET / `x-api-key` для записи |
| `GET/PUT /v1/admin/access-policy` | матрица прав | `x-api-key` |
| `GET/PUT /v1/admin/knowledge-agent`, `/v1/admin/ai-agent` | подключение своих AI-агентов (endpoint + имя env-секрета) | `x-api-key` |
| `GET/PUT /v1/admin/webhooks`, `/webhooks/test` | подписка на события | `x-api-key` |
| `GET /v1/admin/audit`, `/security`, `/overview` | аудит, безопасность, метрики | `x-api-key` |
| `GET /openapi.json`, `/docs` | спецификация и интерактивный explorer | — |
| MCP-сервер `@agil/mcp` | те же возможности для LLM-агентов компании | stdio + env |

### 4.2 Что компания предоставляет нам
| Endpoint компании | Формат | Мы делаем |
|---|---|---|
| AI-агент анализа диалогов | `AiAgentRequest` → `AiAgentResponse` (findings + notes/выдержки) | подпись HMAC, таймаут, zod-валидация, broadcast, аудит |
| Knowledge-агент (wiki) | `KnowledgeQueryRequest` → `KnowledgeQueryResponse` (answer + citations) | прокси, enforcement прав, лимиты, аудит, UI-цитаты |
| IdP (OIDC) | JWT + JWKS | проверка подписи, claim-маппинг (roadmap; сейчас `mode:'token'`) |
| Приём вебхуков | `WebhookPayload` + `x-agil-signature` | доставка с ретраями, лог, HMAC |

### 4.3 События, которые мы отправляем
`room.created`, `room.closed`, `participant.joined`, `participant.left`,
`chat.message`, `file.shared`, `recording.ready`, `transcript.ready`,
`analysis.ready`, `knowledge.answer`, `compliance.finding`, `security.event`.

### 4.4 Чат может быть чужим

Виджет поддерживает три режима (`session.chat.ui`): `builtin` (наш чат),
`external` (компания рисует свой чат, мы только передаём сообщения через SDK/
postMessage/API) и `hidden` (наш чат выключен, компания использует свой
мессенджер рядом). Компания может писать в чат звонка со своего бэкенда через
`POST /v1/admin/rooms/:id/chat` (бот/CRM, `kind:'system'`) или от участника через
`POST /v1/rooms/:id/chat` (Bearer join-token), а читать — через вебхук
`chat.message` и/или SDK-события. Так чат остаётся в системе компании, а звонок —
встроенным элементом её страницы (`chrome:'none'`, `inheritHostStyles`).

### 4.5 «Свернуть звонок» и навигация по приложению

`layout.minimized` — плавающая панель/пузырь поверх страниц приложения
(звонок не прерывается), плюс Document Picture-in-Picture (Chromium).
`layout.persistAcrossPages` + `AGILCalls.resume()` — восстановление звонка после
перехода по SPA/страницам (sessionStorage handoff; медиа пересоздаётся при
полной навигации). В SPA рекомендуется монтировать виджет один раз в layout
приложения — тогда звонок непрерывен.


## 5. Данные и приватность

- Мы храним: конфиги тенантов, события аудита (IP — только SHA-256 с солью),
  метаданные комнат/файлов/записей, транскрипты (retention настраивается),
  findings/notes. Не храним: wiki-контент, каталог сотрудников, пароли в
  открытом виде (только scrypt-хэш комнаты), секреты AI/IdP (только **имя**
  env-переменной).
- Наружу уходят: запросы к AI/knowledge endpoint’ам компании (подписаны HMAC,
  содержат identity и минимально необходимый контекст), вебхуки (подписаны).
- Управление: `session.aiAgent.sendTranscripts/sendChat/retentionMin`,
  `session.knowledgeAgent` (вкл/выкл, роли), `DELETE` записей, TTL файлов и
  токенов, отзыв API-ключа (ротация на стороне компании).
- 152-ФЗ/GDPR: согласие на запись (`recording.consentRequired`), минимизация
  данных, сроки хранения, право на удаление (удаление записи/транскрипта),
  локальный (on-prem) режим — вся платформа разворачивается в контуре компании.

## 6. Безопасность стыка

- Все исходящие вызовы компании: **только HTTPS** (в проде), таймауты,
  HMAC-SHA256 подпись тела, `requestId` для идемпотентности, ограничение размера
  ответа, zod-валидация; ответы моделей не исполняются.
- Защита от SSRF: endpoint’ы задаются только через admin API (не из браузера) и
  валидируются (https, запрет localhost/private IP в проде) — рекомендация
  эксплуатации; в dev допускаются http/localhost.
- Секреты компании живут в env на нашем сервере (значение) и в конфиге — только
  имя переменной. Ключ не попадает в клиентский бандл и логи.
- Вебхуки: компания проверяет `x-agil-signature` и `x-agil-timestamp` (защита от
  повторов), отвечает 2xx; остальное — ретраи с backoff.

## 7. Варианты развёртывания

1. **SaaS AGIL** — мы в облаке, компания вызывает наш API из своего бэкенда.
2. **VPC/on-prem компании** — весь стек в контуре компании, данные не покидают
   периметр; AI/knowledge — внутренние endpoint’ы.
3. **Hybrid** — медиа/API у нас, AI/knowledge и аудит-экспорт в контуре компании
   через вебхуки.

## 8. Чек-лист интеграции (для компании)

1. Создать tenant + API-ключ (`AGIL_API_KEYS`).
2. Настроить тему/фичи: `PATCH /v1/tenants/:id/config` или редактор `/editor/`.
3. Определить роли/права: `PUT /v1/admin/access-policy`; выпускать токены с
   `permissions` из своего каталога.
4. Подключить IdP (сейчас — выпуск токенов; OIDC — roadmap) и `identity.mode`.
5. Подключить AI-агента (`PUT /v1/admin/ai-agent`) и/или knowledge-агента
   (`PUT /v1/admin/knowledge-agent`), указать env-секреты.
6. Подписаться на вебхуки (`PUT /v1/admin/webhooks`), проверить
   `/v1/admin/webhooks/test`.
7. Встроить виджет (SDK/iframe), передать токен и `tenantId`.
8. Проверить `/docs`/`/openapi.json`, нагрузки, retention, TLS/TURN, бэкапы.