feat: default locale Russian, geo determines language for other countries

- localization-svc: defaultLocale ru, resolveLocale only by geo - web-svc: DEFAULT_LOCALE ru, layout lang=ru, embeddedTranslations fallback ru - countryToLocale: default ru when no country or unknown country Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-23 15:10:38 +03:00
parent 8fc82a3b90
commit cd6b7857ba
606 changed files with 26148 additions and 14297 deletions
--- a/docs/architecture/01-perplexity-analogue-design.md
+++ b/docs/architecture/01-perplexity-analogue-design.md
@@ -0,0 +1,695 @@
+# Архитектура аналога Perplexity.ai — полная спецификация
+
+Документ описывает полную архитектуру системы на базе микросервисов K3s с акцентом на:
+- **ВСЕ сервисы в `services/`.** Папка `apps/` удаляется. Микросервисная архитектура: chat, search, discover, finance, travel, auth, library, memory, create, notifications, projects, web (UI), cache-worker.
+- **~10 000 DAU** (ежедневных пользователей)
+- **Клиентская логика** — максимум на клиенте; персональные данные — только для аккаунтов
+- **Предварительная обработка и кэш** — новости, finance, travel, повторяющиеся запросы
+- **Полное совпадение** с Perplexity.ai по страницам и логике
+
+---
+
+## 1. Карта страниц (URL-структура, 1:1 Perplexity)
+
+| URL | Страница | Описание |
+|-----|----------|----------|
+| `/` | Home | Поисковая строка + виджеты discover/новости |
+| `/search`, `/search/new?q=` | Search | Поисковый чат (Quick/Pro/Deep) |
+| `/c/[threadId]` | Chat/Thread | Окно конкретного чата/треда |
+| `/finance` | Finance | Рынок, heatmap, вкладки |
+| `/finance/[ticker]` | Ticker Detail | Детальная страница акции/индекса |
+| `/finance/predictions/[id]` | Predictions | Polymarket prediction markets |
+| `/travel` | Travel | Trending, Inspiration Cards, отели, маршруты |
+| `/discover` | Discover | Новости по темам (или часть Home) |
+| `/library` | Library | История поисков, сохранённые треды |
+| `/spaces` | Spaces | Список проектов/пространств |
+| `/spaces/templates` | Space Templates | Шаблоны Spaces |
+| `/collections/[id]` | Collections | Публичные коллекции (read-only Space) |
+| `/patents` | Patents | Поиск и анализ патентов |
+| Profile/Settings | Account | Профиль, Preferences, Personalize, Billing, My Connectors |
+| — | Desktop app | Electron/Tauri (pplx.ai-аналог) |
+| — | iOS / Android | Нативные приложения, voice search |
+| — | Chrome extension | Расширение для браузера |
+
+---
+
+## 2. Карта функциональностей
+
+### 2.1 Сводная матрица
+
+| Категория | Функционал | Клиент | Сервер (обязательно) | Кэш/Фоново |
+|-----------|------------|--------|----------------------|------------|
+| **Поиск** | Quick Search | ✅ UI, локальное состояние | LLM, Researcher | ✅ Кэш по query_hash |
+| **Поиск** | Pro Search | ✅ UI, стриминг | LLM, Mastra workflow | ✅ Кэш по query_hash |
+| **Поиск** | Deep Research | ✅ UI, прогресс | LLM, Mastra | ✅ Кэш по query_hash |
+| **Discover** | Новости по темам | ✅ Рендер | Агрегация | ✅ **Pre-compute + Redis** |
+| **Finance** | Рынок, heatmap, watchlist | ✅ Рендер, watchlist в LS | Агрегация данных | ✅ **Pre-compute + Redis** |
+| **Travel** | Маршруты, отели | ✅ UI stepper | Агрегация, LLM | ✅ **Pre-compute популярных** |
+| **Проекты** | Spaces, файлы | ✅ CRUD UI | Хранение файлов, эмбеддинги | — |
+| **Чат** | Сообщения, история | ✅ localStorage / IndexedDB | Только LLM, без хранения | Опционально: user preference |
+| **Медиа** | Images, Videos | ✅ Рендер | SearXNG proxy | ✅ Кэш по query |
+| **Виджеты** | Погода, акции, калькулятор | ✅ Калькулятор на клиенте | API-прокси | ✅ Погода/акции по ключу |
+| **Профиль** | Account, prefs | ✅ Preferences в LS | Auth только (SSO) | — |
+| **Биллинг** | Тарифы, оплата | ✅ UI | ЮKassa, лимиты | — |
+| **Collections** | Публичные шаблоны | ✅ Рендер | projects-svc | Redis/PostgreSQL |
+| **Library** | История, сохранённое | ✅ UI | library-svc (аккаунты) | PostgreSQL |
+| **Memory** | Персональная память AI | ✅ UI | memory-svc | PostgreSQL + Redis |
+| **Create/Labs** | Дашборды, отчёты, экспорт | ✅ UI | chat-svc + create-svc | — |
+| **Patents** | Поиск патентов | ✅ Рендер | search-svc + patents API | Redis |
+| **Export thread** | Экспорт тредов в PDF/MD | ✅ UI | create-svc / library-svc | — |
+| **Notifications** | Push, email, напоминания | ✅ Клиент + SW | notifications-svc | — |
+| **PWA/Офлайн** | Service worker, установка | ✅ SPA | Static + SW | — |
+| **Model Council** | 3 модели параллельно, синтез | ✅ UI (Max) | chat-svc | — |
+| **Background Assistant** | Фоновые задачи (Max) | ✅ Desktop/Mobile | chat-svc + queue | — |
+
+### 2.2 Детальное описание функциональностей
+
+#### A. Поисковый чат (Core)
+| Функция | Описание |
+|---------|----------|
+| Quick Search | 1 запрос, базовые модели, без хранения истории |
+| Pro Search | Многошаговый поиск, Mastra workflow, параллельные actions |
+| Deep Research | Расширенный анализ, отчёт, визуализация этапов |
+| **Answer Modes** | Standard, Focus, Academic, Writing + вертикали (Travel, Finance) |
+| **Travel Mode** | Отдельный системный промпт, фокус на отели/маршруты/бронирование |
+| Классификация | Classifier → skipSearch, sources, widgets |
+| Actions | webSearch, academicSearch, socialSearch, scrapeURL, uploadsSearch (параллельно) |
+| Writer | Финальный ответ с цитированием источников |
+| **Step-by-step Learning** | Режим обучения: подсказки, guided questions, уровень сложности |
+| **Response preferences** | Настройки формата/стиля ответов (Preferences) |
+| **Input bar «+»** | Меню: файлы, источники, режимы (Quick/Pro/Deep/Create/Learn) |
+| **Model Council** | Запуск 3 моделей параллельно → сравнение → синтез ответа (Max) |
+
+#### B. Discover (Новости)
+| Функция | Описание |
+|---------|----------|
+| Агрегация новостей | По темам: tech, finance, travel, world, science |
+| Суммаризация | LLM-сводка каждой новости/блока |
+| Обновление | Фоновая задача каждые 15–30 мин |
+| Кэш | Redis: `discover:{topic}:{date}` TTL 30 мин |
+
+#### C. Finance
+| Функция | Описание |
+|---------|----------|
+| Market Summary | Индексы, futures, VIX |
+| Heatmap S&P 500 | Сектора, gainers/losers |
+| **Вкладки** | Crypto, Earnings, Predictions, Screener, Politicians Watchlist, Watchlist |
+| Recent Developments | Новости с суммаризацией и таймстампами |
+| **Popular Spaces for Finance Research** | Блок коллекций по категории finance (SEC, Buffett, S&P Transcripts) |
+| Standouts | Выделенные акции с кратким LLM-анализом |
+| Watchlist | Клиент: localStorage; сервер: агрегация данных по тикерам |
+| **Analyst ratings** | Рейтинги аналитиков по акциям (FMP, Benzinga и т.п.) |
+| **Auditable financials** | Ссылки на SEC filings в ответах и на странице тикера |
+| **ETF Holdings** | Детали холдингов ETF на странице тикера |
+| **Heatmap hover** | Live-синтез причины движения цены при наведении (LLM on demand) |
+| **Stock graphs** | Графики в ответах чата (мобильный/desktop) |
+| Кэш | Redis: `finance:summary`, `finance:heatmap`, `finance:news:{ticker}` TTL 2–5 мин |
+
+#### D. Travel
+| Функция | Описание |
+|---------|----------|
+| Trending Destinations | Карточки с изображениями (pre-compute) |
+| **Inspiration Cards** | Курируемые статьи («Лучшие тропы в Словении», «Лесные отели в Швеции») |
+| Поиск мест, маршруты | Генерация itineraries (LLM) |
+| Отели | Tripadvisor (рейтинги, отзывы, ссылки) |
+| **Партнёрское бронирование** | Tripadvisor, Selfbook (прямое бронирование) |
+| Stepper UI | Поиск → Места → Маршрут → Отели → Билеты |
+| Answer Mode: Travel | Вертикаль чата с фокусом на путешествия |
+| Кэш | Redis: `travel:trending`, `travel:inspiration`, `travel:itinerary:{hash}` TTL 1–24 ч |
+
+#### E. Collections (публичные)
+| Функция | Описание |
+|---------|----------|
+| Collections | Публичные read-only Spaces с предзагруженным контекстом |
+| Категории | finance, travel, product, research — для Popular Spaces |
+| Примеры | SEC Findings, Buffett letters, S&P 500 Transcripts |
+| API | `GET /collections?category=finance`, `GET /collections/:id` |
+
+#### F. Проекты (Spaces)
+| Функция | Описание |
+|---------|----------|
+| CRUD проектов | Создание, переименование, архивация |
+| Файлы в проекте | Загрузка, парсинг, эмбеддинги |
+| Чаты в проекте | Контекст проекта во всех чатах |
+| Internal Knowledge Search | Поиск по файлам + веб |
+| Space Templates | Шаблоны под финансы, маркетинг, продукт, travel |
+
+#### G. Library
+| Функция | Описание |
+|---------|----------|
+| История поисков | Список тредов для авторизованного пользователя |
+| Сохранённое | Saved threads, закладки |
+| **Гости** | Только localStorage/IndexedDB, при закрытии — потеря |
+| **Аккаунты** | Синхронизация на сервере (library-svc, PostgreSQL) |
+
+#### H. Медиа
+| Функция | Описание |
+|---------|----------|
+| Search Images | SearXNG, LLM формирует query |
+| Search Videos | SearXNG, LLM формирует query |
+| Кэш | Redis: `media:images:{query_hash}`, `media:videos:{query_hash}` TTL 1 ч |
+
+#### I. Виджеты
+| Функция | Описание |
+|---------|----------|
+| Weather | API (Open-Meteo и т.п.) |
+| Stock | Yahoo Finance / Financial Modeling Prep |
+| Calculation | **Полностью на клиенте** (mathjs и т.п.) |
+| Кэш | Погода/акции: Redis по location/ticker TTL 5–15 мин |
+
+#### J. Профиль и Connectors
+| Функция | Описание |
+|---------|----------|
+| Account | Аватар, имя, email (только просмотр) |
+| Preferences | Appearance, Language, Autosuggest, Homepage widgets, **Response preferences** |
+| Personalize | Watchlists, настройки персонализации |
+| Billing | Подписка, история платежей |
+| **My Connectors** | Интеграции (Google Drive, Dropbox и т.п.) — Pro/общие пользователи |
+| **App Connectors** | Enterprise: SharePoint, OneDrive, Box — автосинхронизация файлов в Space |
+
+#### K. Memory (персональная память AI)
+| Функция | Описание |
+|---------|----------|
+| Хранение | memory-svc, PostgreSQL (user_id, key, value, embedding) |
+| Извлечение | Семантический поиск по памяти при каждом запросе (если Pro/Max) |
+| Формат | Факты, предпочтения, контекст из прошлых тредов |
+| UI | Просмотр/удаление памяти в Profile → Personalize |
+| Enterprise Memory | Организационная память (org_id), доступна всем участникам |
+
+#### L. Create / Labs
+| Функция | Описание |
+|---------|----------|
+| Генерация | Таблицы, отчёты, дашборды по запросу (Pro) |
+| Экспорт | .xlsx, .csv, .md, .pdf из ответов |
+| Image generation | Генерация изображений (Pro, DALL·E/Stable Diffusion) |
+| API | `POST /api/v1/create` — тип (table/dashboard/image), prompt |
+
+#### M. Patents
+| Функция | Описание |
+|---------|----------|
+| Страница | `/patents` — поиск по USPTO, EPO, патентам РФ |
+| Интеграция | patents API или Google Patents; LLM-суммаризация |
+| Кэш | Redis `patents:{query_hash}` TTL 1 ч |
+
+#### N. Enterprise
+| Функция | Описание |
+|---------|----------|
+| **Audit logs** | Логи: query, answer, model, sources, user_id, timestamp (compliance) |
+| **Granular feature access** | Доступ к API, список Spaces, модели по ролям админа |
+| **Domain-based sign-up** | Ограничение регистрации по верифицированным доменам email |
+| **Usage guidelines** | Guidelines организации на homepage для членов |
+| **Enterprise Memory** | Общая память на уровень org |
+
+#### O. Клиентские приложения
+| Платформа | Описание |
+|----------|----------|
+| **Desktop** | Electron или Tauri, единый код с web |
+| **iOS / Android** | React Native или Capacitor; **voice search** (Web Speech API / native) |
+| **Chrome extension** | Всплывающее окно, быстрый поиск со страницы |
+| **PWA / Офлайн** | Service worker кэширует статику (JS, CSS, assets); workbox; установка на домашний экран; офлайн-fallback |
+
+#### O.1 Export thread
+| Функция | Описание |
+|---------|----------|
+| API | `POST /api/v1/library/threads/:id/export` или `POST /api/v1/export` с `contentType: 'thread'` |
+| Форматы | PDF, Markdown |
+| Реализация | create-svc или library-svc; рендер треда → PDF (puppeteer/jsPDF) или MD (template) |
+| UI | Кнопка Export в окне чата/треда |
+
+#### O.2 Notifications
+| Функция | Описание |
+|---------|----------|
+| **Push** | Web Push API (VAPID); уведомление при готовности ответа (Pro/Deep); настройки в Preferences |
+| **Email** | Опция «уведомить по email при завершении» для долгих запросов (Deep Research) |
+| **Напоминания** | «Напомнить через N» — отложенная задача, push/email по расписанию |
+| **Сервис** | notifications-svc; очереди (Redis/Bull) или вызов от chat-svc по событию |
+
+#### O.3 Model Council (Max)
+| Функция | Описание |
+|---------|----------|
+| Логика | Запрос → параллельный запуск 3 выбранных моделей (GPT-4, Claude, и др.) |
+| Синтез | Отдельный LLM-вызов для сравнения и сведения в единый ответ |
+| UI | Выбор моделей в input bar; side-by-side или сводный вид |
+| API | `POST /api/v1/chat` с `modelCouncil: true`, `models: ['gpt-4','claude','...']` |
+
+#### O.4 Background Assistant (Max)
+| Функция | Описание |
+|---------|----------|
+| Назначение | Выполнение задач в фоне (Desktop/Mobile app), когда приложение свёрнуто |
+| Архитектура | Queue (Redis/Bull); worker подхватывает задачи; push при готовности |
+| Сценарии | «Найди отели в Париже» → фон → уведомление с результатом |
+| API | `POST /api/v1/tasks` (создать фоновую задачу); polling или WebSocket/SSE для статуса |
+
+#### P. Образование
+| Функция | Описание |
+|---------|----------|
+| **Step-by-step Learning** | Режим в input bar «+»; ответы с подсказками, guided questions |
+| **Quizzes / Flashcards** | Генерация тестов и карточек по теме (Pro/Education) |
+| **Education Pro** | Тариф со скидкой для студентов/преподавателей (верификация) |
+
+---
+
+## 3. Микросервисы K3s
+
+### 3.1 Карта сервисов
+
+```
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                              CLIENT (SPA / PWA)                                  │
+│  Next.js (SSR для статики) / React SPA — максимум логики, localStorage, IndexedDB │
+└─────────────────────────────────────────────────────────────────────────────────┘
+                                        │
+                    ┌───────────────────┼───────────────────┐
+                    │                   │                   │
+                    ▼                   ▼                   ▼
+┌───────────────────────┐ ┌───────────────────────┐ ┌───────────────────────┐
+│   API Gateway         │ │   Auth Service         │ │   Web (CDN/Static)    │
+│   (Kong / Traefik)    │ │   (Keycloak/Supabase)  │ │   S3/MinIO + CDN      │
+└───────────────────────┘ └───────────────────────┘ └───────────────────────┘
+                    │
+                    ▼
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                         BACKEND MICROSERVICES (K3s)                               │
+├─────────────────────────────────────────────────────────────────────────────────┤
+│                                                                                  │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐            │
+│  │ chat-svc    │  │ search-svc  │  │ discover-svc│  │ finance-svc │            │
+│  │ LLM, Mastra │  │ SearXNG,    │  │ News feed   │  │ Market data │            │
+│  │ Writer      │  │ Scraper     │  │ Summari-zer│  │ Heatmap     │            │
+│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘            │
+│                                                                                  │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐            │
+│  │ travel-svc  │  │ media-svc   │  │ projects-svc│ │ cache-worker│            │
+│  │ Itineraries │  │ Images/Videos│ │ Files,      │  │ Pre-compute │            │
+│  │ Tripadvisor │  │ SearXNG     │  │ Embeddings  │  │ Background  │            │
+│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘            │
+│                                                                                  │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐            │
+│  │ billing-svc │  │ upload-svc  │  │ library-svc │  │ memory-svc   │            │
+│  │ ЮKassa      │  │ File parse  │  │ Threads,     │  │ AI Memory,   │            │
+│  │ Subscriptions│ │ Embeddings  │  │ History      │  │ Enterprise  │            │
+│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘            │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  # Create, Audit, Notifications   │
+│  │ create-svc  │  │ audit-svc   │  │notifications│                                    │
+│  │ Tables,     │  │ Query+Answer│  │ Push, Email │                                    │
+│  │ Dashboards  │  │ logging     │  │ Reminders   │                                    │
+│  └─────────────┘  └─────────────┘  └─────────────┘                                    │
+│                                                                                  │
+└─────────────────────────────────────────────────────────────────────────────────┘
+                    │
+                    ▼
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                         ИНФРАСТРУКТУРА                                           │
+│  Redis (кэш + сессии) │ PostgreSQL (billing, projects) │ MinIO (файлы)          │
+│  SearXNG (self-hosted) │ LLM Provider (OpenAI/Ollama)   │ Vector DB (optional)   │
+└─────────────────────────────────────────────────────────────────────────────────┘
+```
+
+### 3.2 Описание микросервисов
+
+| Сервис | Язык | Replicas (10k DAU) | Назначение |
+|--------|------|--------------------|------------|
+| **api-gateway** | — (Kong/Traefik) | 2 | Роутинг, rate limit, JWT validation |
+| **auth-svc** | Node/Go | 2 | SSO (Google, Apple, Email magic link), JWT |
+| **chat-svc** | Node.js | 3–5 | LLM, Mastra workflow, Writer, streaming |
+| **search-svc** | Node.js | 3 | SearXNG, scrape, Researcher actions |
+| **discover-svc** | Node.js | 2 | Агрегация новостей, суммаризация (фоново) |
+| **finance-svc** | Node.js | 2 | Market data, heatmap, news по тикерам |
+| **travel-svc** | Node.js | 2 | Itineraries, Tripadvisor, trending |
+| **media-svc** | Node.js | 2 | Images/Videos через SearXNG |
+| **projects-svc** | Node.js | 2 | CRUD проектов, файлы, эмбеддинги, **Collections** |
+| **billing-svc** | Node.js | 1 | ЮKassa, subscriptions, лимиты |
+| **upload-svc** | Node.js | 2 | Парсинг PDF/DOCX, embedding, chunking |
+| **library-svc** | Node.js | 2 | История тредов, сохранённое для аккаунтов |
+| **memory-svc** | Node.js | 2 | Персональная память AI, Enterprise Memory, векторный поиск |
+| **create-svc** | Node.js | 1–2 | Create (таблицы, дашборды), экспорт, image generation |
+| **audit-svc** | Node.js | 1 | Audit logs для Enterprise (query, answer, model, user) |
+| **notifications-svc** | Node.js | 1–2 | Web Push, Email, напоминания; очереди задач |
+| **cache-worker** | Node.js | 1–2 | Cron: pre-compute discover, finance, travel inspiration |
+
+### 3.3 K3s манифесты (базовая структура)
+
+```yaml
+# namespaces
+perplexica-prod
+perplexica-cache
+
+# Deployments с HPA
+chat-svc:     min 2, max 8, CPU 70%
+search-svc:   min 2, max 6
+discover-svc: min 1, max 4
+finance-svc:  min 1, max 4
+travel-svc:   min 1, max 3
+media-svc:    min 1, max 4
+projects-svc: min 1, max 4 (включая Collections)
+upload-svc:   min 1, max 4
+library-svc:  min 1, max 3
+memory-svc:   min 1, max 3
+create-svc:   min 1, max 2
+audit-svc:    min 1, max 1
+notifications-svc: min 1, max 2
+billing-svc:  min 1, max 2
+cache-worker: min 1, max 1 (CronJob)
+auth-svc:     min 2, max 4
+```
+
+---
+
+## 3. Стратегия кэширования и предобработки
+
+### 3.1 Ключевой принцип
+
+> **Не суммировать и не обрабатывать по запросу то, что можно сделать заранее и переиспользовать.**
+
+### 3.2 Кэш-слои
+
+| Слой | Что кэширует | Ключ | TTL | Источник |
+|------|--------------|------|-----|----------|
+| **Discover** | Новости по теме + суммаризация | `discover:{topic}` | 30 мин | cache-worker каждые 15 мин |
+| **Finance** | Market summary, heatmap | `finance:summary`, `finance:heatmap` | 5 мин | cache-worker каждые 2 мин |
+| **Finance** | News по тикеру | `finance:news:{ticker}` | 15 мин | cache-worker при обновлении |
+| **Travel** | Trending destinations | `travel:trending` | 6 ч | cache-worker каждые 4 ч |
+| **Travel** | Inspiration Cards | `travel:inspiration` | 6 ч | cache-worker каждые 4 ч |
+| **Travel** | Популярные маршруты | `travel:itinerary:{hash}` | 24 ч | On first request, reuse |
+| **Search** | Идентичные запросы | `search:{query_hash}:{mode}` | 1–24 ч | On first request |
+| **Media** | Images/Videos query | `media:{type}:{query_hash}` | 1 ч | On first request |
+| **Widgets** | Погода, акции | `widget:{type}:{key}` | 5–15 мин | On first request |
+
+### 3.4 Cache-worker (фоновые задачи)
+
+```
+Cron расписание:
+├── */2 * * * *   finance:summary, finance:heatmap
+├── */15 * * * *  discover:{topic} для всех тем
+├── 0 */4 * * *   travel:trending, travel:inspiration (Inspiration Cards)
+└── 0 * * * *     Инвалидация устаревших search cache
+```
+
+### 3.5 Логика поискового кэша
+
+1. Входящий запрос → `query_hash = sha256(normalize(query) + mode + sources)`
+2. Проверка Redis: `GET search:{query_hash}`
+3. Если есть → отдать из кэша (без LLM)
+4. Если нет → выполнить полноценный flow, сохранить в кэш
+5. Популярные запросы (частота > N/день) → приоритет в cache-worker для pre-warm
+
+---
+
+## 4. Клиентская архитектура (без хранения данных)
+
+### 4.1 Что на клиенте (включая My Connectors UI)
+
+| Компонент | Реализация |
+|-----------|------------|
+| UI/UX | React, Next.js (SSR только для статики) |
+| Состояние чата | Zustand/Context — в памяти, при refresh теряется (или опционально IndexedDB) |
+| Preferences | localStorage: theme, language, units |
+| Watchlist (finance) | localStorage |
+| Калькулятор | Полностью локально (mathjs) |
+| Роутинг | Client-side |
+| **PWA / Офлайн** | Service worker (Workbox): кэш static (JS, CSS, assets); offline fallback; manifest для установки |
+
+### 4.2 Что храним / не храним
+
+**Не храним на сервере (гости):**
+- История чатов — только в памяти/IndexedDB клиента
+- Preferences — только в localStorage
+
+**Храним для аккаунтов:**
+- История тредов, сохранённое — library-svc (PostgreSQL)
+- Projects, файлы, подписка — projects-svc, billing-svc
+- Кэш поиска — обезличенный по query_hash, без user_id
+
+### 4.3 Режимы пользователя
+
+| Режим | Данные | Описание |
+|-------|--------|----------|
+| **Гость** | Всё на клиенте | Чат в памяти, при закрытии — потеря |
+| **Аккаунт** | Auth + billing | Проекты, подписка — в БД; чаты опционально |
+
+### 4.4 UI/UX требования
+
+| Область | Требование |
+|---------|------------|
+| **Discover, Finance, Travel** | Skeleton/placeholder при cold start; timeout с сообщением; кнопка повтора при ошибке |
+| **Поиск (Pro/Deep)** | Отображение этапов (Classifier → Researcher → Writer); оценка времени ожидания |
+| **Загрузка файлов** | Прогресс по этапам: парсинг → chunking → эмбеддинги; индикация; кнопка Cancel; timeout 300 с |
+| **Гости** | Предупреждение при закрытии: история теряется без аккаунта; CTA «Сохранить в аккаунт» |
+| **Rate limit** | Сообщение при 429; предупреждение при 80% лимита; предложение апгрейда при достижении |
+| **Ошибки** | Сообщение + Retry/Cancel; fallback при частичном сбое (например, виджет не загрузился) |
+| **Travel Stepper** | Сохранение состояния шагов при уходе; скелетон между шагами |
+| **Мобильный** | Адаптивность heatmap, Discover; жесты; SettingsButtonMobile |
+
+---
+
+## 5. API контракты (основные)
+
+### 5.1 Chat/Search
+
+```
+POST /api/v1/chat
+  Body: { query, mode?, sources?, fileIds?, answerMode?, learningMode?, responsePrefs? }
+  answerMode: 'standard' | 'focus' | 'academic' | 'writing' | 'travel' | 'finance'
+  learningMode: boolean  # Step-by-step Learning
+  responsePrefs: { format?, length?, tone? }  # из Preferences
+  Response: SSE stream
+  Cache: Проверка query_hash до вызова LLM
+
+POST /api/v1/search/cached
+  Query: ?q=...&mode=...
+  Response: JSON (если есть в кэше) или 404 → fallback на /chat
+```
+
+### 5.2 Discover
+
+```
+GET /api/v1/discover?topic=tech|finance|travel|...
+  Response: { items: [{ title, summary, source, url }] }
+  Source: Redis, refresh от cache-worker
+```
+
+### 5.3 Finance
+
+```
+GET /api/v1/finance/summary
+GET /api/v1/finance/heatmap
+GET /api/v1/finance/news/:ticker
+GET /api/v1/finance/watchlist?tickers=AAPL,GOOG
+GET /api/v1/finance/analyst-ratings/:ticker   # Analyst ratings
+GET /api/v1/finance/sec-filings/:ticker       # Ссылки на SEC filings
+GET /api/v1/finance/etf-holdings/:symbol       # ETF Holdings
+GET /api/v1/finance/price-context/:ticker     # Heatmap hover: LLM-синтез причины движения
+  Response: JSON из Redis / live
+```
+
+### 5.4 Travel
+
+```
+GET /api/v1/travel/trending
+GET /api/v1/travel/inspiration     # Inspiration Cards (pre-compute)
+POST /api/v1/travel/itinerary
+  Body: { destination, days, preferences }
+  Cache: По hash параметров
+```
+
+### 5.5 Collections
+
+```
+GET /api/v1/collections?category=finance|travel|product|research
+GET /api/v1/collections/:id
+  Response: Публичный Space с контекстом (read-only)
+```
+
+### 5.6 Library
+
+```
+GET /api/v1/library/threads        # Для авторизованных
+POST /api/v1/library/threads      # Сохранить тред
+DELETE /api/v1/library/threads/:id
+```
+
+### 5.7 Auth
+
+```
+POST /auth/login/email
+GET  /auth/oauth/{provider}
+POST /auth/refresh
+GET  /auth/me
+```
+
+### 5.8 Connectors
+
+```
+GET /api/v1/connectors            # Список доступных (Pro)
+POST /api/v1/connectors/:type    # Подключить (Google Drive, Dropbox)
+DELETE /api/v1/connectors/:id    # Отключить
+```
+
+### 5.9 Memory
+
+```
+GET  /api/v1/memory               # Список записей памяти (Pro/Max)
+POST /api/v1/memory              # Добавить запись (внутренний вызов от chat-svc)
+DELETE /api/v1/memory/:id        # Удалить запись
+```
+
+### 5.10 Create / Labs
+
+```
+POST /api/v1/create
+  Body: { type: 'table' | 'dashboard' | 'image', prompt, context? }
+  Response: { url?, data?, imageUrl? }
+  
+POST /api/v1/export
+  Body: { format: 'xlsx' | 'csv' | 'md' | 'pdf', contentId?, contentType?: 'create' | 'thread' }
+  Body (thread): { format: 'pdf' | 'md', threadId }
+  Response: blob / download URL
+```
+
+### 5.10.1 Export thread
+
+```
+POST /api/v1/library/threads/:id/export
+  Query: ?format=pdf|md
+  Response: blob (application/pdf или text/markdown)
+  Реализация: create-svc или library-svc + puppeteer/jsPDF для PDF
+```
+
+### 5.11 Patents
+
+```
+GET /api/v1/patents?q=...
+  Response: { patents: [{ title, abstract, filingDate, url, summary }] }
+  Source: Google Patents / USPTO API; LLM-суммаризация; Redis кэш
+```
+
+### 5.12 Enterprise Audit
+
+```
+GET /api/v1/admin/audit-logs?from=&to=&userId=
+  Response: [{ query, answerSnippet, model, sources, userId, timestamp }]
+  Только для org admin
+```
+
+### 5.13 Notifications
+
+```
+POST /api/v1/notifications/subscribe     # Web Push подписка (VAPID)
+  Body: { endpoint, keys: { p256dh, auth } }
+  
+POST /api/v1/notifications/preferences  # Настройки: push при ответе, email, напоминания
+  Body: { pushOnAnswer?, emailOnDeepResearch?, reminders?: [...] }
+  
+POST /api/v1/notifications/remind       # «Напомнить через N»
+  Body: { threadId?, query?, remindAt: ISO8601 }
+```
+
+### 5.14 Model Council (Max)
+
+```
+POST /api/v1/chat
+  Body: { ..., modelCouncil: true, models: ['gpt-4o','claude-sonnet','...'] }
+  Response: SSE с этапами: 3 ответа → синтез
+```
+
+### 5.15 Background Assistant (Max)
+
+```
+POST /api/v1/tasks                    # Создать фоновую задачу
+  Body: { query, mode?, callback?: 'push' | 'poll' }
+  Response: { taskId }
+  
+GET /api/v1/tasks/:id                 # Статус задачи
+  Response: { status, result?, error? }
+```
+
+---
+
+## 6. Порядок реализации (best practices)
+
+### Фаза 0 — Инфраструктура
+1. K3s кластер, PostgreSQL, Redis, MinIO
+2. API Gateway (Traefik/Kong)
+3. Auth-svc (Keycloak или Supabase Auth)
+
+### Фаза 1 — Ядро
+4. chat-svc с Mastra (Classifier → parallel actions → Writer)
+5. search-svc (SearXNG, actions)
+6. cache-worker + Redis стратегия
+7. Кэш для search по query_hash
+
+### Фаза 2 — Discover + Finance
+8. discover-svc + cache-worker pre-compute
+9. finance-svc + cache-worker
+10. Клиент: Discover, Finance страницы
+
+### Фаза 3 — Travel
+11. travel-svc, Tripadvisor, Selfbook
+12. Inspiration Cards (cache-worker), Stepper UI
+13. Answer Mode: Travel
+
+### Фаза 4 — Проекты, Collections, Library, биллинг
+14. projects-svc, upload-svc, **Collections** (Popular Spaces по категориям)
+15. library-svc (история для аккаунтов)
+16. billing-svc, ЮKassa
+17. Клиент: Spaces UI, Library, Profile, Billing, My Connectors
+
+### Фаза 5 — Memory, Create, Finance+, Patents, Enterprise
+18. memory-svc (персональная память, Enterprise Memory)
+19. create-svc (таблицы, дашборды, экспорт, image generation)
+20. finance-svc: Analyst ratings, SEC links, ETF Holdings, heatmap hover, stock graphs
+21. Patents page: search-svc + patents API, `/patents`
+22. audit-svc (Enterprise audit logs)
+23. Enterprise: domain sign-up, usage guidelines, granular feature access
+24. Step-by-step Learning, Response preferences, Input bar «+»
+
+### Фаза 6 — Клиенты и образование
+25. Desktop app (Electron/Tauri)
+26. iOS / Android (React Native/Capacitor), voice search
+27. Chrome extension
+28. Step-by-step Learning UI, Quizzes/Flashcards
+29. Education Pro тариф
+
+### Фаза 7 — Export, Notifications, PWA, Model Council, Background
+30. Export thread: POST /library/threads/:id/export (PDF, MD)
+31. PWA: Service worker (Workbox), manifest, offline fallback
+32. notifications-svc: Web Push (VAPID), email, напоминания
+33. Model Council (Max): параллельный запуск 3 моделей, синтез
+34. Background Assistant (Max): POST /tasks, queue, push при готовности
+
+### Фаза 8 — Оптимизация
+35. Pre-warm популярных запросов в cache-worker
+36. CDN для статики
+37. Мониторинг, алерты, SLO
+
+---
+
+## 7. Латенси по сценариям (пользователь)
+
+| Сценарий | Ожидаемое время | Cold / промах кэша |
+|----------|-----------------|--------------------|
+| Discover / Finance (кэш) | &lt;500 ms | 5–30 с |
+| Finance редкий тикер | 10–20 с (cold fill) | — |
+| Travel itinerary | 15–60 с | — |
+| Pro/Deep Search | 30–120 с | — |
+| Загрузка файла (эмбеддинги) | 30–300 с | — |
+| Медиа (Images/Videos) | 3–10 с | — |
+
+## 8. Оценка нагрузки (10k DAU)
+
+| Метрика | Оценка | Решение |
+|---------|--------|---------|
+| RPS пиковый | ~50–100 | HPA, 3–5 реплик chat-svc |
+| LLM вызовов/день | ~30k (3 на юзера) | Кэш снижает до ~10k |
+| Redis memory | ~4–8 GB | Кэш discover/finance/search |
+| Storage | ~100 GB | Файлы проектов, логи |
+
+---
+
+## 9. Безопасность и compliance
+
+- HTTPS везде
+- JWT с коротким TTL (15 мин), refresh token
+- Rate limiting: 100 req/min на IP, 300 Pro Search/день (Free)
+- Не логировать персональные запросы в plaintext
+- Кэш — только по hash, без привязки к user_id