# 🔨 MAX AI Bot — Пошаговая инструкция сборки

> **Что это:** Инструкция для сборки AI-бота в мессенджере MAX через Claude Code за 5 сессий.
> **Подписка:** Claude Max ($100/мес, 5x лимит)
> **Проект:** `/root/max-ai-bot/`
> **ТЗ:** `/root/max-ai-bot/REQUIREMENTS.md`

---

## 📋 Перед началом

### Что должно быть готово:
- [ ] VPS с Ubuntu (уже есть)
- [ ] Node.js 20+ установлен
- [ ] Claude Code установлен и авторизован
- [ ] MAX Bot токен (получить у @MaxBotFather в MAX)
- [ ] DeepSeek API ключ (api.deepseek.com)
- [ ] Ollama установлен (опционально, для fallback)

### Проверка окружения:
```bash
node --version    # должно быть 20+
npm --version     # должно быть 10+
claude --version  # Claude Code установлен
```

### Если Node.js не установлен:
```bash
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -
sudo apt install -y nodejs
```

---

## 🟢 СЕССИЯ 1: Фундамент (каркас + БД + конфиг)

### Что получим:
- Рабочий TypeScript проект
- SQLite база данных с таблицами
- CRUD для лидов, диалогов, базы знаний
- Docker-конфигурация
- Логгер

### Шаг 1.1 — Перейди в папку проекта
```bash
cd /root/max-ai-bot
```

### Шаг 1.2 — Запусти Claude Code
```bash
claude
```

### Шаг 1.3 — Вставь этот промпт:

```
Создай Node.js TypeScript проект — AI-бот для мессенджера MAX.

Прочитай файл /root/max-ai-bot/REQUIREMENTS.md — там полное ТЗ проекта.

В ЭТОЙ сессии реализуй ТОЛЬКО фундамент:

1. ИНИЦИАЛИЗАЦИЯ ПРОЕКТА:
   - package.json с ESM ("type": "module")
   - Зависимости: @maxhub/max-bot-api, better-sqlite3, openai, dotenv, pino
   - Dev: typescript, @types/node, @types/better-sqlite3, tsx
   - Scripts: "dev": "tsx watch src/index.ts", "build": "tsc", "start": "node dist/index.js"
   - tsconfig.json: strict true, ESM, outDir: dist

2. КОНФИГ (src/config/):
   - env.ts — парсинг .env через dotenv, экспорт типизированного объекта config
   - constants.ts — MAX_CONTEXT_MESSAGES=10, RATE_LIMIT_PER_MIN=5, LEAD_SCORE_AFTER_MESSAGES=3

3. ЛОГГЕР (src/utils/logger.ts):
   - pino с красивым форматированием
   - Уровни: info, warn, error

4. БАЗА ДАННЫХ (src/db/):
   - database.ts — инициализация SQLite, создание таблиц при первом запуске:
     * conversations (id, user_id, role, content, created_at)
     * leads (id, user_id, name, service_type, budget, urgency, contact, score, notes, created_at, updated_at)
     * knowledge (id, category, question, answer, keywords)
   
   - conversations.ts:
     * saveMessage(userId: string, role: 'user'|'assistant', content: string)
     * getHistory(userId: string, limit?: number): Message[]
     * clearHistory(userId: string)
   
   - leads.ts:
     * createLead(data: LeadInput): Lead
     * getLead(userId: string): Lead | null
     * updateLead(userId: string, data: Partial<LeadInput>): Lead
     * getLeadsByScore(score: 'hot'|'warm'|'cold'): Lead[]
     * getAllLeads(): Lead[]
   
   - knowledge.ts:
     * loadFromJSON(filePath: string): number (возвращает кол-во загруженных)
     * search(query: string): KnowledgeItem[] (поиск по keywords)
     * getAll(): KnowledgeItem[]
     * getByCategory(category: string): KnowledgeItem[]

5. DOCKER:
   - Dockerfile (multi-stage: build + run)
   - docker-compose.yml (сервис bot, volume для data/)
   
6. ФАЙЛЫ:
   - .env.example с комментариями
   - .gitignore (node_modules, dist, data/, .env)
   - data/knowledge.json — пример базы знаний:
     [
       {"category": "услуги", "question": "Какие услуги вы предоставляете?", "answer": "Мы предоставляем...", "keywords": "услуги, сервис, что делаете"},
       {"category": "цены", "question": "Сколько стоит?", "answer": "Цены зависят от...", "keywords": "цена, стоимость, сколько"},
       {"category": "контакты", "question": "Как связаться?", "answer": "Телефон: ..., Email: ...", "keywords": "контакт, телефон, связь"}
     ]

7. ТОЧКА ВХОДА (src/index.ts):
   - Пока просто: загрузить конфиг, инициализировать БД, загрузить базу знаний, залогировать "Bot foundation ready"
   - Graceful shutdown: process.on('SIGTERM'), process.on('SIGINT')

НЕ ДЕЛАЙ в этой сессии: обработчики бота, AI-интеграцию, клавиатуры.

ПРОВЕРЬ в конце:
- npm install проходит
- npm run build проходит без ошибок
- npm run dev запускается и выводит "Bot foundation ready"
```

### Шаг 1.4 — Проверь результат:
```bash
npm install
npm run build
npm run dev    # Должно вывести "Bot foundation ready"
```

### Шаг 1.5 — Если есть ошибки:
Скажи Claude Code: `Исправь ошибки компиляции` — он починит.

### ✅ Сессия 1 завершена когда:
- `npm run build` проходит без ошибок
- `npm run dev` выводит "Bot foundation ready"
- Файл `data/bot.db` создаётся автоматически

---

## 🟡 СЕССИЯ 2: MAX Bot API (обработчики + меню)

### Что получим:
- Бот запускается и слушает сообщения в MAX
- /start показывает приветствие с кнопками
- Кнопки меню работают
- Все сообщения сохраняются в БД

### Шаг 2.1 — Подготовь .env:
```bash
cp .env.example .env
nano .env
# Заполни MAX_BOT_TOKEN и ADMIN_USER_IDS
```

### Шаг 2.2 — Запусти Claude Code:
```bash
cd /root/max-ai-bot
claude
```

### Шаг 2.3 — Вставь этот промпт:

```
Продолжаю разработку MAX AI бота.
Прочитай /root/max-ai-bot/REQUIREMENTS.md для полного контекста.
Код из предыдущей сессии уже в /root/max-ai-bot/src/ — изучи его.

В ЭТОЙ сессии реализуй подключение к MAX Bot API:

1. УСТАНОВИ если нужно: @maxhub/max-bot-api (npm install @maxhub/max-bot-api)

2. src/bot/handlers.ts — обработчики сообщений:
   
   a) Команда /start:
      - Отправляет приветственное сообщение:
        "👋 Здравствуйте! Я виртуальный помощник компании.
         Чем могу помочь?"
      - Ниже — inline-клавиатура с 4 кнопками (из keyboards.ts)
   
   b) Текстовое сообщение:
      - Сохраняет в db/conversations
      - Пока отвечает заглушкой: "Обрабатываю ваш запрос... (AI будет подключен в следующем обновлении)"
      - Сохраняет ответ в db/conversations
   
   c) Callback query (нажатие кнопки):
      - "services" → текст об услугах + кнопка "Назад"
      - "calculate" → "Опишите что вам нужно, и я рассчитаю примерную стоимость"
      - "request" → "Оставьте ваше имя и телефон, мы свяжемся с вами"
      - "faq" → список FAQ из базы знаний (db/knowledge.ts)
      - "back" → возврат в главное меню

3. src/bot/keyboards.ts — клавиатуры:
   - mainMenu(): inline-кнопки в 2 столбца:
     [Узнать об услугах] [Рассчитать стоимость]
     [Оставить заявку]  [Частые вопросы]
   - backButton(): одна кнопка "← Назад в меню"
   - faqList(items): кнопки из базы знаний

4. src/bot/middleware.ts:
   - logMessage: логирует каждое входящее сообщение (userId, text, timestamp)
   - rateLimiter: Map<userId, timestamps[]>, блокирует если >5 сообщений в минуту, отвечает "Подождите немного..."
   - isAdmin(userId): проверяет по ADMIN_USER_IDS из конфига

5. ОБНОВИ src/index.ts:
   - Создать экземпляр бота через @maxhub/max-bot-api
   - Подключить middleware
   - Подключить handlers
   - Запустить polling/webhook
   - Логировать "Bot started, listening for messages..."

ВАЖНО: Изучи документацию @maxhub/max-bot-api — как создавать бота, 
отправлять сообщения, обрабатывать callback. Если библиотека не подходит,
используй прямые HTTP-запросы к MAX Bot API (https://max.ru/botapi/).

НЕ ДЕЛАЙ: AI-интеграцию, скоринг лидов — следующие сессии.

ПРОВЕРЬ:
- npm run dev запускает бота
- В MAX: отправь /start → получи приветствие с кнопками
- Кнопки работают, сообщения сохраняются в БД
```

### Шаг 2.4 — Проверь:
1. `npm run dev`
2. Открой MAX, найди своего бота
3. Отправь `/start` — должно появиться меню с кнопками
4. Нажми каждую кнопку — должны работать

### ✅ Сессия 2 завершена когда:
- Бот отвечает на /start с кнопками
- Кнопки работают
- Сообщения сохраняются в `data/bot.db`

---

## 🔵 СЕССИЯ 3: AI мозг (DeepSeek + Ollama + контекст)

### Что получим:
- Бот отвечает через DeepSeek AI
- При недоступности DeepSeek — fallback на Ollama
- Ответы учитывают историю диалога и базу знаний

### Шаг 3.1 — Подготовь .env:
```bash
nano .env
# Добавь:
# DEEPSEEK_API_KEY=sk-...
# DEEPSEEK_BASE_URL=https://api.deepseek.com
# DEEPSEEK_MODEL=deepseek-chat
# OLLAMA_BASE_URL=http://localhost:11434
# OLLAMA_MODEL=qwen2.5:7b
```

### Шаг 3.2 — Запусти Claude Code:
```bash
cd /root/max-ai-bot
claude
```

### Шаг 3.3 — Вставь этот промпт:

```
Продолжаю разработку MAX AI бота.
Прочитай /root/max-ai-bot/REQUIREMENTS.md для контекста.
Изучи весь текущий код в /root/max-ai-bot/src/.

В ЭТОЙ сессии реализуй AI-интеграцию:

1. src/ai/deepseek.ts — клиент DeepSeek:
   - Использует npm пакет "openai" (DeepSeek совместим с OpenAI API)
   - new OpenAI({ apiKey: config.DEEPSEEK_API_KEY, baseURL: config.DEEPSEEK_BASE_URL })
   - Функция: chat(messages: ChatMessage[]): Promise<string>
   - Timeout: 30 секунд
   - Обработка ошибок: логировать и бросать

2. src/ai/ollama.ts — клиент Ollama (fallback):
   - HTTP запрос к OLLAMA_BASE_URL/api/chat
   - Функция: chat(messages: ChatMessage[]): Promise<string>
   - Timeout: 60 секунд (локальная модель медленнее)
   - Если Ollama недоступен — вернуть стандартный ответ:
     "Извините, я временно не могу обработать запрос. Оставьте контакт, мы свяжемся с вами."

3. src/ai/router.ts — роутер моделей:
   - Функция: getAIResponse(messages: ChatMessage[]): Promise<{text: string, model: string}>
   - Логика: DeepSeek → (ошибка) → Ollama → (ошибка) → стандартный ответ
   - Логирует: какая модель ответила, время ответа

4. src/ai/prompts.ts — системные промпты:
   
   a) DEFAULT_PROMPT:
   ```
   Ты — виртуальный менеджер компании. Твоя задача:
   - Вежливо и профессионально отвечать на вопросы клиентов
   - Рассказывать об услугах и ценах на основе базы знаний
   - Выявлять потребности клиента (что нужно, бюджет, сроки)
   - Мотивировать оставить заявку или контактные данные
   
   Правила:
   - Отвечай кратко (2-4 предложения), по делу
   - Если не знаешь ответа — честно скажи и предложи связаться с менеджером
   - Не выдумывай цены и факты — используй только базу знаний
   - Будь дружелюбным но профессиональным
   ```
   
   b) QUALIFIER_PROMPT (для квалификации):
   ```
   Проанализируй диалог и определи:
   1. Тип услуги (что нужно клиенту)
   2. Бюджет (если упоминался)
   3. Срочность (срочно / не срочно / не определена)
   4. Контактные данные (если оставил)
   5. Скоринг: hot (готов купить), warm (интересуется), cold (просто спрашивает)
   
   Верни JSON: {"service_type": "", "budget": "", "urgency": "", "contact": "", "score": "", "notes": ""}
   ```

5. src/ai/context.ts — сборка контекста:
   - Функция: buildContext(userId: string, userMessage: string): ChatMessage[]
   - Логика:
     a) Системный промпт (DEFAULT_PROMPT)
     b) Если есть релевантные записи в базе знаний — добавить:
        "База знаний:\n" + результаты search по ключевым словам из сообщения
     c) Последние 10 сообщений из истории (db/conversations)
     d) Текущее сообщение пользователя

6. ОБНОВИ bot/handlers.ts:
   - Текстовое сообщение теперь:
     a) Сохранить сообщение пользователя в БД
     b) Собрать контекст через context.ts
     c) Получить ответ через router.ts
     d) Отправить ответ пользователю
     e) Сохранить ответ бота в БД

НЕ ДЕЛАЙ: скоринг лидов, уведомления, админку — следующие сессии.

ПРОВЕРЬ:
- Отправь боту сообщение "Какие у вас услуги?" → получи AI-ответ
- Проверь что контекст работает (задай уточняющий вопрос)
- Отключи интернет → проверь fallback на Ollama (если установлен)
```

### Шаг 3.4 — Проверь:
1. `npm run dev`
2. Напиши боту "Привет, какие услуги?" — должен ответить через AI
3. Задай уточняющий вопрос — должен помнить контекст
4. Проверь логи — какая модель отвечает

### ✅ Сессия 3 завершена когда:
- Бот отвечает через DeepSeek
- Контекст работает (помнит предыдущие сообщения)
- База знаний используется в ответах

---

## 🟣 СЕССИЯ 4: Лиды + скоринг + уведомления

### Что получим:
- Автоматическая квалификация лидов
- Уведомления о горячих лидах
- Аналитика

### Шаг 4.1 — Запусти Claude Code:
```bash
cd /root/max-ai-bot
claude
```

### Шаг 4.2 — Вставь этот промпт:

```
Продолжаю разработку MAX AI бота.
Прочитай /root/max-ai-bot/REQUIREMENTS.md для контекста.
Изучи весь текущий код в /root/max-ai-bot/src/.

В ЭТОЙ сессии реализуй квалификацию лидов и уведомления:

1. src/services/lead-scorer.ts:
   
   - Функция: scoreLead(userId: string): Promise<Lead | null>
   - Логика:
     a) Получить историю диалога (db/conversations)
     b) Если сообщений < 3 — рано квалифицировать, вернуть null
     c) Отправить историю в AI с QUALIFIER_PROMPT (из prompts.ts)
     d) Распарсить JSON-ответ
     e) Создать или обновить лид в БД (db/leads)
     f) Вернуть лид
   
   - Функция: shouldScore(userId: string): boolean
     a) Проверить: прошло ли >= 3 новых сообщений с последнего скоринга
     b) Не скорить чаще чем раз в 5 сообщений

2. src/services/notifications.ts:
   
   - Функция: notifyHotLead(lead: Lead, chatHistory: Message[])
     a) Формирует карточку:
        🔥 ГОРЯЧИЙ ЛИД!
        👤 Имя: {name || "не указано"}
        🛠 Услуга: {service_type}
        💰 Бюджет: {budget || "не озвучен"}
        ⚡ Срочность: {urgency}
        📱 Контакт: {contact || "не оставил"}
        📝 Заметки: {notes}
        
        Последние 3 сообщения:
        ...
     b) Отправляет в NOTIFY_CHAT_ID через бота
   
   - Функция: sendDailySummary()
     a) Считает за сегодня: всего диалогов, новых лидов, горячих/тёплых/холодных
     b) Формирует сводку:
        📊 Сводка за {дата}
        💬 Диалогов: X
        👥 Новых лидов: Y
        🔥 Горячих: Z | 🟡 Тёплых: W | 🔵 Холодных: V
     c) Отправляет в NOTIFY_CHAT_ID

3. src/services/analytics.ts:
   
   - Функция: getStats(period: 'day'|'week'|'month'): Stats
     * totalConversations: число уникальных userId с сообщениями за период
     * totalMessages: общее число сообщений
     * totalLeads: число лидов
     * hotLeads / warmLeads / coldLeads: по скорингу
     * conversionRate: hotLeads / totalConversations * 100

4. ИНТЕГРАЦИЯ в bot/handlers.ts:
   - После каждого AI-ответа:
     a) Проверить shouldScore(userId)
     b) Если да — запустить scoreLead(userId) в фоне (не блокируя ответ)
     c) Если результат = hot → notifyHotLead()

5. CRON для daily summary:
   - В index.ts: setInterval или node-cron → sendDailySummary() каждый день в 20:00

НЕ ДЕЛАЙ: админ-команды, воронку курса — следующая сессия.

ПРОВЕРЬ:
- Поговори с ботом 5+ сообщений → должен появиться лид в БД
- Если лид горячий → уведомление в NOTIFY_CHAT_ID
- Проверь data/bot.db → таблица leads заполняется
```

### Шаг 4.3 — Проверь:
1. Поговори с ботом 5+ сообщений, упомяни бюджет и срочность
2. Проверь получил ли владелец уведомление
3. Посмотри БД: `sqlite3 data/bot.db "SELECT * FROM leads;"`

### ✅ Сессия 4 завершена когда:
- Лиды создаются автоматически после 3+ сообщений
- Горячие лиды → уведомление владельцу
- Статистика считается корректно

---

## 🔴 СЕССИЯ 5: Админка + воронка курса + финал

### Что получим:
- Полный набор админ-команд
- Воронка продажи курса
- README и готовность к продакшену

### Шаг 5.1 — Запусти Claude Code:
```bash
cd /root/max-ai-bot
claude
```

### Шаг 5.2 — Вставь этот промпт:

```
Финальная сессия разработки MAX AI бота.
Прочитай /root/max-ai-bot/REQUIREMENTS.md для контекста.
Изучи весь текущий код в /root/max-ai-bot/src/.

В ЭТОЙ сессии реализуй всё оставшееся:

1. src/admin/commands.ts — админ-команды (только для ADMIN_USER_IDS):

   /stats [day|week|month] — статистика:
   📊 Статистика за {период}
   ━━━━━━━━━━━━━━━━━━
   💬 Диалогов: {X}
   📨 Сообщений: {Y}
   👥 Лидов: {Z}
   🔥 Горячих: {A} | 🟡 Тёплых: {B} | 🔵 Холодных: {C}
   📈 Конверсия: {D}%
   
   /leads [hot|warm|cold|all] — список лидов:
   Для каждого лида:
   #{id} | {score_emoji} {name || userId}
   🛠 {service_type} | 💰 {budget}
   📅 {created_at}
   ---
   
   /export — выгрузка CSV:
   - Генерировать CSV: id, user_id, name, service_type, budget, urgency, contact, score, created_at
   - Отправить файлом в чат
   
   /kb — показать базу знаний:
   📚 База знаний ({count} записей):
   По категориям, кратко.
   
   /update_kb — обновить базу знаний:
   - Ожидает файл JSON в следующем сообщении
   - Парсит и загружает через db/knowledge.ts
   - Отвечает: "✅ Загружено {N} записей"
   
   /set_prompt {текст} — изменить системный промпт:
   - Сохраняет в файл data/custom_prompt.txt
   - prompts.ts проверяет: если файл существует — использовать его вместо DEFAULT_PROMPT
   - Отвечает: "✅ Промпт обновлён"
   
   /help — список всех админ-команд

2. src/admin/dashboard.ts:
   - Функция: generateDashboard(): string
   - Красивый текстовый дашборд со всей статистикой
   - Вызывается по команде /dashboard

3. ВОРОНКА КУРСА:
   
   a) В keyboards.ts добавить кнопку "📚 О курсе" в главное меню
   
   b) В handlers.ts — callback "course":
      - Текст о курсе (из knowledge.ts, категория "курс")
      - Кнопки: "Подробнее", "Купить курс", "Назад"
   
   c) Callback "buy_course":
      - Отправить ссылку на оплату (из конфига COURSE_PAYMENT_URL)
      - Сохранить в leads как отдельный тип
   
   d) В handlers.ts — если пришёл webhook оплаты (POST /webhook/payment):
      - Пометить лид как "paid"
      - Отправить клиенту ссылку на материалы (COURSE_MATERIALS_URL из конфига)
      - Уведомить админа: "💰 Новая оплата курса!"
      (Реализовать как заглушку — конкретный платёжный провайдер подключим позже)

4. README.md:
   
   # MAX AI Bot
   
   ## Описание
   AI-бот для мессенджера MAX — автоматический менеджер по продажам.
   
   ## Возможности
   - AI-диалог с клиентами (DeepSeek + Ollama fallback)
   - Автоматическая квалификация лидов (горячий/тёплый/холодный)
   - Мгновенные уведомления о горячих лидах
   - База знаний об услугах и ценах
   - Админ-панель (статистика, экспорт, настройки)
   - Воронка продажи курса
   
   ## Быстрый старт
   1. Скопировать .env.example → .env, заполнить
   2. npm install
   3. npm run dev (разработка) или npm run build && npm start (продакшен)
   4. docker-compose up -d (Docker)
   
   ## Настройка
   ### База знаний
   Редактировать data/knowledge.json, затем /update_kb
   
   ### Промпт
   /set_prompt {новый промпт} или редактировать data/custom_prompt.txt
   
   ## Админ-команды
   /stats, /leads, /export, /kb, /update_kb, /set_prompt, /dashboard, /help

5. ФИНАЛЬНАЯ ПРОВЕРКА:
   - npm run build — без ошибок
   - npm start — бот запускается
   - Все команды работают
   - docker-compose up -d — контейнер запускается

Это последняя сессия. Убедись что ВСЁ работает.
```

### Шаг 5.3 — Финальная проверка:
```bash
# Сборка
npm run build

# Запуск
npm start

# Или через Docker
docker-compose up -d
docker-compose logs -f
```

### Шаг 5.4 — Тест всех функций:
- [ ] /start → меню с кнопками
- [ ] Текстовое сообщение → AI-ответ
- [ ] 5+ сообщений → лид в БД
- [ ] Горячий лид → уведомление
- [ ] /stats → статистика
- [ ] /leads → список лидов
- [ ] /export → CSV файл
- [ ] /kb → база знаний
- [ ] /set_prompt → промпт обновлён
- [ ] Кнопка "О курсе" → воронка

### ✅ Сессия 5 завершена когда:
- Все тесты пройдены
- `docker-compose up -d` — бот работает в контейнере
- README.md написан

---

## 🎯 Итого

| Сессия | Что делаем | ~Время CC |
|--------|-----------|-----------|
| 1 | Фундамент (каркас + БД) | 20-30 мин |
| 2 | MAX Bot API (обработчики) | 20-30 мин |
| 3 | AI мозг (DeepSeek/Ollama) | 25-35 мин |
| 4 | Лиды + скоринг + уведомления | 25-35 мин |
| 5 | Админка + курс + финал | 30-40 мин |

**Общее время Claude Code:** ~2-3 часа
**Твоё время:** ~1-2 часа на проверку между сессиями

---

## ⚠️ Частые проблемы

**Claude Code зависает / не заканчивает:**
→ Скажи: "Заверши текущую задачу и проверь что npm run build проходит"

**Ошибки TypeScript:**
→ Скажи: "Исправь все ошибки компиляции в npm run build"

**Бот не отвечает в MAX:**
→ Проверь токен в .env
→ Проверь логи: `npm run dev` покажет ошибки

**DeepSeek не отвечает:**
→ Проверь API ключ
→ Проверь доступность: `curl https://api.deepseek.com/v1/models -H "Authorization: Bearer sk-..."`

**@maxhub/max-bot-api не работает:**
→ Скажи Claude Code: "Используй прямые HTTP-запросы к MAX Bot API вместо библиотеки"