docs: PRD for minimal usage dashboard (search, mcp, bot, tunnel, landing)

Made-with: Cursor

Author: ilyar

README.md

@@ -260,6 +260,11 @@ npm-пакет `mcp-tma-client` в `packages/mcp-tma-client/`. Работает
 }
 ```
 
+## Спецификации (PRD)
+
+- `docs/PRD-public-knowledge-search-service.md` — публичный `/knowledge` API
+- `docs/PRD-usage-dashboard-minimal.md` — минимальная панель использования (search, mcp, bot, tunnel, landing)
+
 ## Структура проекта
 
 ```

docs/PRD-usage-dashboard-minimal.md

@@ -0,0 +1,206 @@
+# PRD: минимальная панель использования платформы (Usage Dashboard)
+
+**Версия документа:** 0.1  
+**Дата:** 2026-03-25  
+**Статус:** черновик требований (без реализации)
+
+---
+
+## 1. Резюме
+
+Нужна **минимальная операторская панель** (read-only), показывающая **сводное использование** платформы SpawnDock: сколько уникальных **субъектов** активны, **как израсходованы лимиты** (где применимы) и **какие из пяти контролируемых сервисов** задействованы.
+
+**Контролируемые сервисы (обязательная сегментация в отчётах):**
+
+| ID      | Компонент        | Типовой вход / заметка |
+|---------|------------------|-------------------------|
+| `search` | Knowledge search | Публичный `POST /knowledge/api/v1/search`, внутренние вызовы MCP → search |
+| `mcp`   | MCP / control plane | `mcp-server`: HTTP/SSE, инструменты, preview и пр. |
+| `bot`   | Telegram bot     | Polling/webhook, команды, выдача токенов |
+| `tunnel`| Dev tunnel        | Клиенты `dev-tunnel`, WebSocket к control plane |
+| `landing` | Лендинг / статика | Трафик на корневой лендинг за Caddy (не API) |
+
+Панель **не заменяет** полноценный APM (Grafana/Prometheus); цель — **единый минимальный обзор** для оператора на одном экране или двух.
+
+---
+
+## 2. Цели и критерии успеха
+
+| ID | Цель | Сигнал успеха |
+|----|------|----------------|
+| G1 | Видимость **активности по сервисам** | В панели отображаются счётчики/серии хотя бы за **24ч / 7д** по пяти ID выше |
+| G2 | Видимость **лимитов** там, где они уже есть | Для **search** — попадания в квоты (free/basic), **429**, необязательно поминутно в v0 |
+| G3 | Видимость **«пользователей»** в разумном определении | Оператор видит **число уникальных субъектов** и разбивку по типу (см. §4) без ручного сбора логов |
+| G4 | **Безопасность** | Панель недоступна публично; доступ только **операторам** (см. §8) |
+| G5 | **Минимализм** | MVP без биллинга, без self-service для конечных пользователей |
+
+---
+
+## 3. Не в scope (v0)
+
+- Оплата, счета, лимиты «pro/enterprise» как продукт.
+- Редактирование квот или блокировка пользователей из UI (только просмотр; действия — вне v0 или отдельный PRD).
+- Гарантия 100% сквозной идентичности «один человек = один user_id» между Telegram, браузером и MCP (см. §4.3).
+- Хостинг панели на том же публичном префиксе, что и лендинг, **без** отдельной аутентификации.
+
+---
+
+## 4. Определения: «пользователь» и учёт
+
+### 4.1 Субъект (actor)
+
+Минимальная модель данных для агрегации:
+
+- **`actor_type`**: `api_token` | `telegram_user` | `anonymous_ip` | `tunnel_client` | `unknown`
+- **`actor_key`**: стабильный строковый идентификатор **без** хранения секретов в открытом виде:
+  - `api_token` → **хэш** токена (например SHA-256 с солью из env) или внутренний `token_id`, если позже появится таблица токенов
+  - `telegram_user` → `telegram_user_id` (число)
+  - `anonymous_ip` → IP за доверенным прокси (как в search free-tier)
+  - `tunnel_client` → стабильный client/session id из протокола tunnel (уточнить при инструментировании)
+
+### 4.2 Связь actor ↔ сервис
+
+Каждое значимое событие учёта помечается **`service`** ∈ { `search`, `mcp`, `bot`, `tunnel`, `landing` }.
+
+Один субъект может появляться в **нескольких** сервисах; панель показывает **пересечения** (например «только search», «mcp+bot», таблица или sankey — опционально в v1).
+
+### 4.3 Ограничения идентификации
+
+- **Landing**: чаще всего **без** логина — учёт по **сессии** (cookie/анонимный id) или только агрегаты (просмотры/UV по IP+fingerprint — v1, мягко).
+- **MCP с токеном** и **бот** могут относиться к одному человеку; в v0 допустима **дубликатная** учётная запись в статистике с пометкой «разные actor_type».
+
+---
+
+## 5. Требования к данным по сервисам
+
+### 5.1 `search`
+
+**Уже есть (концептуально):** free/basic tier, лимиты per minute / per day, различие публичного трафика ( `X-Forwarded-For` ) и внутреннего MCP.
+
+**Нужно для панели (instrumentation):**
+
+- Счётчики: `requests_ok`, `requests_429`, по **`tier`** (`free` / `basic`).
+- Разрез по **`actor_key`** (для basic — hash токена; для free — IP или сегмент).
+- Опционально: доля **cache_hit** из `meta` (если включён кэш search).
+
+**Источник:** метрики из процесса `search` (экспорт Prometheus, stdout JSON, или периодический сброс в SQLite/Redis — решение implementer pass).
+
+### 5.2 `mcp`
+
+**Нужно:**
+
+- Счётчики запросов к **чувствительным** маршрутам: например SSE/MCP сессии, вызовы инструментов (хотя бы суммарно).
+- При наличии **Bearer / сессии** — привязка к `api_token` hash или внутреннему session id.
+
+**Источник:** middleware в `mcp-server` (`repo/api`), единый формат лог-события `service=mcp`.
+
+### 5.3 `bot`
+
+**Нужно:**
+
+- События: команды (`/start`, `/gettoken`, и т.д.), активные пользователи за окно.
+- **`actor_key`** = `telegram_user_id`.
+
+**Источник:** hooks в `repo/api` bot polling; избегать логирования секретов.
+
+### 5.4 `tunnel`
+
+**Нужно:**
+
+- Подключения / сессии / переданные байты (минимум: **число активных / новых сессий** за период).
+- Идентификатор клиента — из протокола `repo/dev-tunnel` и бэкенда.
+
+**Источник:** control plane в `repo/api` + при необходимости агент `dev-tunnel`.
+
+### 5.5 `landing`
+
+**Нужно:**
+
+- Базовые **визиты** (page views), опционально **уникальные** по дню.
+- Без PII в сыром виде в панели.
+
+**Источник:** access log Caddy (разбор на edge) или лёгкий **pixel/counter** endpoint за отдельным путём с rate limit.
+
+---
+
+## 6. Функциональные требования (MVP панели)
+
+### 6.1 Экран «Обзор»
+
+- Карточки за период **24ч / 7д** (переключатель):
+  - **Активные субъекты** (уникальные `actor_key`, с разбивкой по `actor_type`).
+  - **События по сервисам** — столбчатая или таблица: `search` | `mcp` | `bot` | `tunnel` | `landing`.
+  - **Search limits:** суммарно **429**, запросы **ok**, (если доступно) **остаток** до дневного/минутного лимита **в агрегате** по tier.
+
+### 6.2 Экран или блок «Search detail»
+
+- Таблица топ-N **субъектов** по числу запросов (обезличенно: префикс хэша, не токен).
+- График или счётчик **429** по времени.
+
+### 6.3 Экран или блок «Сервисы × субъекты» (v0.5, желательно)
+
+- Матрица: сколько субъектов касалось каждого сервиса; простая **venn-подобная** сводка или мультивыбор фильтра.
+
+### 6.4 Обновление данных
+
+- Задержка **≤ 1–5 мин** для агрегатов (достаточно batch/offline rollups).
+
+---
+
+## 7. Нефункциональные требования
+
+- **Retention сырых событий:** v0 — 7–30 дней (конфигурируемо); агрегаты — дольше.
+- **Производительность:** панель не должна сканировать полные текстовые логи в runtime; только БД/TSDB.
+- **GDPR/приватность:** не хранить содержимое запросов search в таблицах панели; максимум длина/хэш для отладки — отдельный флаг.
+
+---
+
+## 8. Безопасность и доступ
+
+- URL панели **не** индексировать; **отдельный** admin-префикс (например `/ops/usage`) за Caddy.
+- Аутентификация v0: **HTTP Basic** с паролем из env, **или** OIDC позже, **или** VPN-only + IP allowlist (решение ops).
+- Роль: только `operator`; аудит входов — желательно (лог).
+
+---
+
+## 9. Зависимости и фазы
+
+### Фаза 0 — контракт событий
+
+- Ввести единую схему **usage event**: `{ ts, service, event_type, actor_type, actor_key, tier?, status?, bytes? }`.
+- Писать в **одно** хранилище (SQLite на VPS / Postgres / ClickHouse lite — выбрать по нагрузке).
+
+### Фаза 1 — сборщики
+
+- Инструментирование **search**, **mcp**, **bot** (минимум).
+- **tunnel** и **landing** — следующими PR.
+
+### Фаза 2 — UI
+
+- Один сервис **static+api** или Next.js micro-app в монорепе; **или** Grafana dashboard + документация, если UI «панели» = дашборд (explicit decision).
+
+---
+
+## 10. Открытые вопросы
+
+1. Единый **Postgres** для control plane + usage или отдельная БД?
+2. Нужен ли **экспорт CSV** для оператора в v0?
+3. Согласовать **имена сервисов** с метриками infra (Kubernetes labels и т.д.), если появятся.
+
+---
+
+## 11. Связанные документы
+
+- `docs/PRD-public-knowledge-search-service.md` — модель лимитов **search** (`free` / `basic`, 429).
+- `OPERATOR.md` (если есть) — деплой, Caddy, секреты.
+
+---
+
+## 12. Утверждение
+
+- Product / Ops: перечень метрик и определение «пользователь».
+- Security: хранение хэшей, доступ к панели, landing tracking.
+
+---
+
+*Конец PRD.*