🗺 Plan-11: Генеральный план EastPay v2 — от текущей точки до финальной версии

Версия: 1.0 | Дата: 2026-02-11 Автор: AI-архитектор | Статус: На утверждении

📍 Текущая точка (Baseline)

Что имеем

Что уже сделано (предыдущие сессии)

• Техническая документация (1355 строк, Section 12: RAG)
• Раздел 12 с полной RAG-архитектурой
• match_documents RPC спроектирован
• Embedding pipeline описан
• Roadmap обновлён (RAG → Phase 2)

🎯 Финальная цель

Telegram-бот EastPay, который:

1. Понимает голос, текст, фото, видео
2. Имеет долгосрочную память (Supabase)
3. Использует RAG для ответов на вопросы о компании
4. Говорит по-человечески (v4 промпт)
5. Открывает Mini App внутри бота
6. Синхронизирует чат с ЛК менеджера
7. Имеет follow-up и ретеншн-систему

📐 Архитектура: финальная картина

flowchart TB
    subgraph TG["📱 Telegram"]
        USER["👤 Клиент"]
        BOT["🤖 EastPay Bot"]
        MINIAPP["📲 Mini App (React)"]
    end

    subgraph N8N["⚙️ n8n Workflow"]
        TRIGGER["Telegram Trigger\n(Webhook)"]
        SWITCH["Switch\n(text/voice/photo/video/start/command)"]
        RAG_NODE["RAG Retrieval\n(Supabase RPC)"]
        AGENT["AI Agent\n(GPT-4o)"]
        MEMORY["Supabase Memory\n(messages table)"]
        TOOLS["Tools:\nrates, deal, order,\nlocations, log, rag_search"]
        SEND["Send to Telegram"]
        SAVE["Save to messages"]
    end

    subgraph SUPA["🗄 Supabase"]
        DB_TABLES["clients, orders,\nlocations, daily_rates"]
        MESSAGES["messages\n(chat history)"]
        DOCUMENTS["documents\n(embeddings + RAG)"]
        EDGE_FN["Edge Functions:\nembed, sync-chat,\nrate-alert"]
        CRON["pg_cron:\nrate-check, follow-up"]
    end

    USER -->|"text/voice/photo"| BOT
    BOT -->|"webhook"| TRIGGER
    TRIGGER --> SWITCH
    SWITCH -->|"text"| RAG_NODE
    RAG_NODE -->|"context + query"| AGENT
    AGENT <-->|"read/write"| MEMORY
    AGENT <-->|"call"| TOOLS
    TOOLS <-->|"SQL/RPC"| DB_TABLES
    AGENT --> SEND
    SEND -->|"reply"| BOT
    AGENT --> SAVE
    SAVE -->|"insert"| MESSAGES
    BOT <-->|"web_app"| MINIAPP
    MINIAPP <-->|"API"| SUPA
    EDGE_FN <-->|"embed/notify"| DOCUMENTS
    CRON -->|"scheduled"| EDGE_FN

📋 ЭТАПЫ РЕАЛИЗАЦИИ

ЭТАП 0: Промпт v4 + n8n Hardening

Цель: Поднять качество диалога с «бот в обменнике» до «живой эксперт финансового консьержа»

0.1. Создать промпт v4 на базе v3

Файл: docs/Promts/4-version-promt.md

Что добавить к v3:

Структура финального промпта:

§0  РОЛЬ (v3 без изменений)
§1  ЧЕЛОВЕЧЕСКИЙ СТИЛЬ (v3 §1)
§2  ПОЗИЦИОНИРОВАНИЕ (v3 §2)
§3  КАТЕГОРИИ ИНТЕНТОВ (v3 §3 + развёрнутые примеры)
§4  COMPLIANCE (v2 §3 + конкретные пороги)
§5  ДАННЫЕ ДЛЯ СБОРА (v2 §4)
§6  ИНСТРУМЕНТЫ — детальные описания (НОВОЕ)
    - get_rates_tool: описание + формат вызова + формат ответа
    - calculate_deal_tool: аналогично
    - create_order_tool: + обязательные поля + валидация
    - get_locations_tool: + что делать, если города нет
    - log_chat_tool: + когда вызывать (тихо, после каждого этапа)
    - rag_search_tool: НОВЫЙ — когда и зачем искать в базе знаний
§7  ПРАВИЛА КУРСА (v3 §7)
§8  RUNBOOK (v2 §4 алгоритм, слитый с v3 §8)
§9  ШАБЛОНЫ ФРАЗ (v3 §9)
§10 ПРИМЕРЫ (v3 §10 + 3 новых сценария)
§11 ИМЯ/ОБРАЩЕНИЕ (v3 §11)
§12 ДАТА/ВРЕМЯ (v3 §12)
§13 CRITICAL (v3 §13 + RAG правило)

0.2. Модернизировать n8n Workflow

Файл: n8n/Telegram AI Agent Base.json → n8n/Telegram AI Agent v2.json

0.3. Добавить команды бота

ЭТАП 1: Supabase — фундамент данных

Цель: Подготовить БД для персистентной памяти и RAG

1.1. Миграции БД

-- 1. Таблица conversations
CREATE TABLE conversations (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  client_id UUID REFERENCES clients(id),
  telegram_chat_id BIGINT NOT NULL,
  status TEXT DEFAULT 'active',  -- active | archived | escalated
  started_at TIMESTAMPTZ DEFAULT now(),
  last_message_at TIMESTAMPTZ DEFAULT now(),
  metadata JSONB DEFAULT '{}'
);

-- 2. Таблица messages (персистентная память)
CREATE TABLE messages (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  conversation_id UUID REFERENCES conversations(id),
  role TEXT NOT NULL CHECK (role IN ('user', 'assistant', 'system', 'manager')),
  content TEXT NOT NULL,
  metadata JSONB DEFAULT '{}',
  created_at TIMESTAMPTZ DEFAULT now()
);
CREATE INDEX idx_messages_conversation ON messages(conversation_id, created_at);
CREATE INDEX idx_messages_role ON messages(role);

-- 3. Расширение documents
ALTER TABLE documents
  ADD COLUMN IF NOT EXISTS created_at TIMESTAMPTZ DEFAULT now(),
  ADD COLUMN IF NOT EXISTS updated_at TIMESTAMPTZ DEFAULT now(),
  ADD COLUMN IF NOT EXISTS source TEXT DEFAULT 'manual',
  ADD COLUMN IF NOT EXISTS is_active BOOLEAN DEFAULT true,
  ADD COLUMN IF NOT EXISTS category TEXT;

-- 4. HNSW индекс  
CREATE INDEX idx_documents_embedding_hnsw 
  ON documents 
  USING hnsw (embedding vector_cosine_ops)
  WITH (m = 16, ef_construction = 64);

-- 5. Full-text search column
ALTER TABLE documents ADD COLUMN IF NOT EXISTS fts tsvector
  GENERATED ALWAYS AS (to_tsvector('russian', coalesce(content, ''))) STORED;
CREATE INDEX idx_documents_fts ON documents USING gin(fts);

1.2. RPC Functions

-- match_documents (семантический поиск)
CREATE OR REPLACE FUNCTION match_documents(
  query_embedding vector(1536),
  match_threshold float DEFAULT 0.78,
  match_count int DEFAULT 5,
  filter_category text DEFAULT NULL
)
RETURNS TABLE (id bigint, content text, metadata jsonb, similarity float)
LANGUAGE plpgsql AS $$
BEGIN
  RETURN QUERY
  SELECT d.id, d.content, d.metadata,
         1 - (d.embedding <=> query_embedding) AS similarity
  FROM documents d
  WHERE d.is_active = true
    AND 1 - (d.embedding <=> query_embedding) > match_threshold
    AND (filter_category IS NULL OR d.metadata->>'category' = filter_category)
  ORDER BY d.embedding <=> query_embedding
  LIMIT match_count;
END;
$$;

-- save_chat_message
CREATE OR REPLACE FUNCTION save_chat_message(
  p_telegram_chat_id BIGINT,
  p_role TEXT,
  p_content TEXT,
  p_metadata JSONB DEFAULT '{}'
)
RETURNS UUID
LANGUAGE plpgsql AS $$
DECLARE
  v_conversation_id UUID;
  v_message_id UUID;
BEGIN
  -- Найти или создать conversation
  SELECT id INTO v_conversation_id
  FROM conversations
  WHERE telegram_chat_id = p_telegram_chat_id AND status = 'active'
  ORDER BY last_message_at DESC LIMIT 1;

  IF v_conversation_id IS NULL THEN
    INSERT INTO conversations (telegram_chat_id)
    VALUES (p_telegram_chat_id)
    RETURNING id INTO v_conversation_id;
  END IF;

  -- Сохранить сообщение
  INSERT INTO messages (conversation_id, role, content, metadata)
  VALUES (v_conversation_id, p_role, p_content, p_metadata)
  RETURNING id INTO v_message_id;

  -- Обновить timestamp
  UPDATE conversations SET last_message_at = now()
  WHERE id = v_conversation_id;

  RETURN v_message_id;
END;
$$;

-- get_conversation_history
CREATE OR REPLACE FUNCTION get_conversation_history(
  p_telegram_chat_id BIGINT,
  p_limit INT DEFAULT 20
)
RETURNS TABLE (role TEXT, content TEXT, created_at TIMESTAMPTZ)
LANGUAGE plpgsql AS $$
BEGIN
  RETURN QUERY
  SELECT m.role, m.content, m.created_at
  FROM messages m
  JOIN conversations c ON c.id = m.conversation_id
  WHERE c.telegram_chat_id = p_telegram_chat_id
    AND c.status = 'active'
  ORDER BY m.created_at DESC
  LIMIT p_limit;
END;
$$;

1.3. RLS Policies

ALTER TABLE conversations ENABLE ROW LEVEL SECURITY;
ALTER TABLE messages ENABLE ROW LEVEL SECURITY;

-- Service role full access (для n8n)
CREATE POLICY "service_role_all_conversations" ON conversations
  FOR ALL USING (auth.role() = 'service_role');

CREATE POLICY "service_role_all_messages" ON messages
  FOR ALL USING (auth.role() = 'service_role');

ЭТАП 2: RAG Pipeline (3-4 дня)

Цель: Наполнить базу знаний и подключить семантический поиск

2.1. Edge Function embed

Путь: supabase/functions/embed/index.ts

Логика:
1. Получает document_id из pgmq очереди
2. Загружает content из documents
3. Вызывает OpenAI text-embedding-3-small
4. Записывает embedding в documents.embedding
5. Обновляет updated_at

2.2. Наполнение Knowledge Base

2.3. Триггер auto-embedding

-- Триггер: при INSERT/UPDATE documents → отправить в pgmq
CREATE OR REPLACE FUNCTION queue_document_for_embedding()
RETURNS TRIGGER AS $$
BEGIN
  PERFORM pgmq.send('embed_queue', jsonb_build_object(
    'document_id', NEW.id,
    'action', TG_OP
  ));
  RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER trg_documents_embed
  AFTER INSERT OR UPDATE OF content ON documents
  FOR EACH ROW EXECUTE FUNCTION queue_document_for_embedding();

2.4. pg_cron для обработки очереди

SELECT cron.schedule(
  'process-embed-queue',
  '*/1 * * * *',  -- каждую минуту
  $$SELECT net.http_post(
    url := 'https://cvzsgjksswowqgfxvrsb.supabase.co/functions/v1/embed',
    headers := '{"Authorization": "Bearer <SERVICE_ROLE_KEY>"}'::jsonb
  );$$
);

ЭТАП 3: n8n ↔ Supabase Memory + RAG

Цель: Заменить Simple Memory на Supabase, подключить RAG

3.1. Заменить Simple Memory

БЫЛО:
  Simple Memory (RAM, 50 messages, теряется)

СТАЛО:
  n8n Code Node «Load History»:
    → RPC get_conversation_history(telegram_chat_id, 20)
    → Форматируем в [{role, content}]
    → Передаём в AI Agent как chat history

3.2. Сохранение сообщений

БЫЛО:
  Ничего не сохраняется (только log_chat_tool иногда)

СТАЛО:
  ДО AI Agent:
    → Supabase Insert: save_chat_message(chat_id, 'user', user_input)
  
  ПОСЛЕ AI Agent:
    → Supabase Insert: save_chat_message(chat_id, 'assistant', ai_output)

3.3. RAG Node в workflow

НОВЫЙ NODE (Code Node) перед AI Agent:

1. Получить user_input
2. Вызвать OpenAI Embeddings (text-embedding-3-small)
3. Вызвать Supabase RPC match_documents(embedding, 0.78, 3)
4. Если результаты есть:
   context = results.map(r => r.content).join('\n---\n')
   Добавить к systemMessage:
   "Контекст из базы знаний:\n{context}"
5. Передать обогащённый prompt в AI Agent

3.4. Новый tool: rag_search_tool

{
  "name": "rag_search_tool",
  "type": "n8n-nodes-base.supabaseTool",
  "parameters": {
    "operation": "invokeFunction",
    "functionName": "match_documents",
    "functionParameters": {
      "query_embedding": "/* embedded query */",
      "match_threshold": 0.78,
      "match_count": 3,
      "filter_category": "={{ $json.category || null }}"
    }
  }
}

Альтернатива: Если n8n Supabase Tool не поддерживает vector → использовать HTTP Request node с Supabase REST API.

ЭТАП 4: Telegram Bot Architecture

Цель: Профессиональный бот с правильными UX-паттернами

4.1. BotFather Setup

/setcommands:
start - Начать работу с EastPay
help - Как я могу помочь
rates - Актуальные курсы
menu - Главное меню
status - Статус заявки
support - Связаться с менеджером

4.2. Welcome Message — полная переработка

БЫЛО:
  <b>EAST PAY</b>
  Обмен валют и зарубежные платежи.
  [Совершить обмен] → eastpaycripto.ru
  [Чат с поддержкой] → @eastpay_support

СТАЛО:
  <b>Привет! Я — AI-ассистент EastPay 💼</b>

  Помогу с обменом валют, платежами и переводами
  в Москве, Дубае, Пхукете и других городах.

  Просто напишите, что вам нужно. Например:
  «Какой курс USDT в Москве?»

  [🏦 Открыть приложение] ← web_app кнопка
  [💬 Написать менеджеру] ← @eastpay_support
  [📊 Актуальные курсы] ← callback /rates

4.3. Inline Keyboard Menus

// Главное меню (по команде /menu)
{
  inline_keyboard: [
    [{ text: "📊 Курсы валют", callback_data: "cmd_rates" }],
    [{ text: "💱 Обменять", callback_data: "cmd_exchange" }],
    [{ text: "📋 Мои заявки", callback_data: "cmd_orders" }],
    [{ text: "🏦 Открыть приложение", web_app: { url: MINI_APP_URL } }],
    [{ text: "👤 Поддержка", url: "https://t.me/eastpay_support" }]
  ]
}

4.4. Webhook Hardening

4.5. Error Handling в n8n

НОВЫЙ FLOW:
  Error Trigger → Code Node (форматирование) → 
    → Telegram: "Произошла техническая ошибка. Менеджер свяжется с вами."
    → Supabase: log error в messages (role: 'system')
    → (опционально) Telegram notification менеджеру

ЭТАП 5: Mini App v2 — React

Цель: Полноценное приложение внутри Telegram

5.1. Стек

React + Vite + TypeScript
Tailwind v4 + Shadcn/UI
Supabase SDK (@supabase/supabase-js)
Telegram Web App API

5.2. Экраны

5.3. Telegram Web App API Integration

// hooks/useTelegram.ts
export function useTelegram() {
  const tg = window.Telegram?.WebApp;
  return {
    tg,
    user: tg?.initDataUnsafe?.user,
    themeParams: tg?.themeParams,
    expand: () => tg?.expand(),
    close: () => tg?.close(),
    ready: () => tg?.ready(),
    mainButton: tg?.MainButton,
    backButton: tg?.BackButton,
  };
}

5.4. Валидация initData (КРИТИЧНО для безопасности!)

// Edge Function: validate-telegram-init
import { createHmac } from 'node:crypto';

function validateInitData(initData: string, botToken: string): boolean {
  const params = new URLSearchParams(initData);
  const hash = params.get('hash');
  params.delete('hash');
  
  const dataCheckString = [...params.entries()]
    .sort(([a], [b]) => a.localeCompare(b))
    .map(([k, v]) => `${k}=${v}`)
    .join('\n');
  
  const secretKey = createHmac('sha256', 'WebAppData')
    .update(botToken)
    .digest();
  
  const calculatedHash = createHmac('sha256', secretKey)
    .update(dataCheckString)
    .digest('hex');
  
  return calculatedHash === hash;
}

ЭТАП 6: Синхронизация и Realtime

Цель: Связать все компоненты в единую систему

6.1. Edge Function sync-chat-to-telegram

Триггер: INSERT в messages WHERE role = 'manager'
Действие: Отправить сообщение клиенту в Telegram через Bot API

6.2. Realtime подписки

6.3. Edge Function rate-alert-notifier

pg_cron (каждые 30 минут):
  → Проверить daily_rates: изменение > 3%
  → Найти клиентов с подпиской на уведомления
  → Отправить Telegram message: "Курс X изменился на Y%"

ЭТАП 7: AI Agent v2 — Follow-up & Retention

Цель: Бот, который сам инициирует контакт

7.1. pg_cron Follow-up Jobs

7.2. Антиспам

-- user_preferences таблица
CREATE TABLE user_preferences (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  client_id UUID REFERENCES clients(id) UNIQUE,
  notifications_enabled BOOLEAN DEFAULT true,
  preferred_pairs TEXT[] DEFAULT '{}',
  preferred_cities TEXT[] DEFAULT '{}',
  daily_message_limit INT DEFAULT 50,
  created_at TIMESTAMPTZ DEFAULT now()
);

7.3. Команда /stop

/stop → user_preferences.notifications_enabled = false
        → "Уведомления отключены. Напишите /start, чтобы снова включить."

ЭТАП 8: Production Hardening

Цель: Стабильная работа в проде

📊 Порядок реализации (сводка)

gantt
    title EastPay v2 — Master Plan
    dateFormat  YYYY-MM-DD
    axisFormat  %d.%m

    section Этап 0: Промпт + n8n
    Промпт v4                    :e0a, 2026-02-12, 2d
    n8n Workflow v2               :e0b, after e0a, 2d
    Команды бота                  :e0c, after e0a, 1d

    section Этап 1: Supabase фундамент
    Миграции (conversations, messages)  :e1a, after e0b, 2d
    RPC Functions                       :e1b, after e1a, 1d
    RLS Policies                        :e1c, after e1b, 1d

    section Этап 2: RAG Pipeline
    Edge Function embed            :e2a, after e1c, 2d
    Наполнение KB (30 docs)        :e2b, after e2a, 2d
    pgmq + auto-embed trigger      :e2c, after e2a, 1d

    section Этап 3: n8n Integration
    Supabase Memory                :e3a, after e2b, 2d
    RAG Node в workflow            :e3b, after e3a, 2d

    section Этап 4: Telegram Bot
    BotFather + Welcome v2         :e4a, after e0c, 1d
    Webhook Hardening              :e4b, after e3b, 1d
    Error Handling                 :e4c, after e4b, 1d

    section Этап 5: Mini App v2
    React Setup + Auth             :e5a, after e4c, 3d
    Экраны (Rates, Calculator)     :e5b, after e5a, 3d
    Чат + Realtime                 :e5c, after e5b, 2d

    section Этап 6: Синхронизация
    sync-chat Edge Function        :e6a, after e5c, 2d
    Realtime подписки              :e6b, after e6a, 1d
    rate-alert-notifier            :e6c, after e6b, 1d

    section Этап 7: Retention
    pg_cron follow-up              :e7a, after e6c, 2d
    Антиспам + preferences         :e7b, after e7a, 2d

    section Этап 8: Production
    Мониторинг + тесты             :e8a, after e7b, 3d

🔑 Ключевые решения для обсуждения

[!IMPORTANT] Следующие решения требуют вашего подтверждения:

1. LLM модель: GPT-4o (рекомендую) vs GPT-4o-mini (текущий) vs другая?

   • GPT-4o: лучше для финансовых диалогов, дороже (~$5/1M input tokens)
   • GPT-4o-mini: дешевле (~$0.15/1M), но хуже с нюансами

   Ответ: GPT-5.1 лушче

2. Mini App URL: Какой домен? app.eastpay.ru? Netlify? Supabase Hosting?

Ответ: Netlify да, домен уже там, можно сделать app.eastpay.online

3. Telegram Bot Token: Используем текущего бота EastPay или создаём нового для тестирования?

Ответ: используем текущего

4. Knowledge Base: Есть ли готовые тексты (FAQ, описания услуг) или нужно генерировать?

Ответ: нет, но нужно будет сгенерировать нам (дам больше материалов)

5. n8n hosting: Где развёрнут n8n? Self-hosted? n8n Cloud? (Влияет на webhook URL)

Ответ: n8n на нашем Self-hosted уже развернут

6. Приоритет: Начинаем с Этапа 0 (промпт + n8n) или с Этапа 1 (Supabase)?

Ответ: начинаем с Этапа 0 (промпт + n8n)

📎 Связанные документы