Workflows Development — Создание workflow

Пошаговое руководство: от идеи до работающего процесса в продакшене. Следуй этим шагам чтобы создать новый workflow правильно.

Карта процесса

WORKFLOW DEVELOPMENT LIFECYCLE

   PLAN ────▶ BUILD ────▶ TEST ────▶ DEPLOY
   Планир.    Создание    Тестир.    Деплой

ЭТАПЫ:
  Plan:   Определить JTBD, входы/выходы
  Build:  Создать workflow в n8n editor
  Test:   Проверить через API и Telegram
  Deploy: Синхронизировать и активировать

Шаг 1: Планирование

1.1 Определить JTBD (Job To Be Done)

Прежде чем создавать workflow, ответь на вопросы:

?

Какую задачу решает workflow?

Например: "Найти информацию в интернете и выдать краткую сводку"

Вход

Какие входные данные?

Например: query (string), chat_id (number)

Выход

Какие выходные данные?

Например: answer (string), sources (array)

SLA

Какой SLA?

Например: "Ответ в течение 30 секунд"

1.2 Создать контракт в clowbot.processes

INSERT INTO clowbot.processes (
  code,
  name,
  description,
  jtbd,
  n8n_workflow_id,
  input_schema,
  output_schema,
  steps_expected,
  sla_seconds,
  visibility,
  is_active
) VALUES (
  'my_new_process',
  'My New Process',
  'Description of what it does',
  'When I need X, I want Y, so I can Z',
  'my_new_workflow',
  '{"type":"object","properties":{"query":{"type":"string"}}}',
  '{"type":"object","properties":{"answer":{"type":"string"}}}',
  '["receive_webhook", "process", "respond"]',
  30,
  'user',
  false  -- false пока тестируем
);

Шаг 2: Создание в n8n

2.1 Открыть n8n Editor

# n8n editor доступен по адресу
http://localhost:5678

# Или через Docker
docker compose exec n8n n8n start --tunnel

2.2 Типичная структура workflow

ТИПИЧНЫЙ WORKFLOW

   WEBHOOK ────▶ CODE ────▶ HTTP/LLM ────▶ RESPONSE
   Trigger       Node        Node           Node
      │            │             │            │
      │       Валидация     Внешний API   Возврат
      │       Подготовка    LLM вызов     результата
      │       Логика
      │
      ▼
   Принимает JSON:
   {
     "query": "...",
     "chat_id": 123
   }

2.3 Настройка Webhook Node

HTTP Method

POST — для всех процессов

Path

Оставь пустым — n8n сгенерирует автоматически

Authentication

Header Auth — используй INTERNAL_API_TOKEN

Response Mode

On Received или Last Node

2.4 Сохранить workflow

После создания workflow в editor:

  1. 1. Нажми Save в editor
  2. 2. Скачай JSON: Download → Workflow JSON
  3. 3. Сохрани в n8n/workflows/my_new_workflow.json

Важно: Имя файла

Имя файла JSON должно совпадать с n8n_workflow_id в контракте процесса (без расширения .json).

Шаг 3: Тестирование

3.1 Импортировать и активировать

# Добавить workflow в слоты для тестирования
./scripts/n8n_slot_switch.sh promote my_new_workflow --sync

# Проверить что webhook зарегистрирован
docker compose exec postgres psql -U clowbot -d clowbot -c \
  "SELECT name, webhookPath FROM public.webhook_entity \
   JOIN public.workflow_entity ON id = \"workflowId\" \
   WHERE name = 'my_new_workflow';"

3.2 Smoke test через curl

# Получить webhook path из БД
WEBHOOK_PATH=$(docker compose exec postgres psql -U clowbot -d clowbot -Atc \
  "SELECT n8n_webhook_path FROM clowbot.processes WHERE code = 'my_new_process'")

# Тестовый запрос
curl -X POST "http://localhost:5678${WEBHOOK_PATH}" \
  -H "Content-Type: application/json" \
  -H "X-Internal-Token: ${INTERNAL_API_TOKEN}" \
  -d '{"query": "test query", "chat_id": 123}'

3.3 Проверить логи

# Логи n8n
docker compose logs n8n --tail=50

# Логи процесса в БД
SELECT
  pr.id,
  pr.status,
  pr.error_details,
  pr.created_at
FROM clowbot.process_runs pr
JOIN clowbot.processes p ON p.id = pr.process_id
WHERE p.code = 'my_new_process'
ORDER BY pr.created_at DESC
LIMIT 5;

Шаг 4: Деплой

4.1 Активировать процесс

-- Включить процесс
UPDATE clowbot.processes
SET is_active = true
WHERE code = 'my_new_process';

4.2 Убедиться что workflow в слотах

# Проверить слоты
./scripts/n8n_slot_switch.sh list

# Если нужно -- добавить в слоты
./scripts/n8n_slot_switch.sh promote my_new_workflow --sync

4.3 Финальный тест через Telegram

Отправь команду в Telegram и проверь что процесс работает end-to-end:

/my_new_process тестовый запрос

Чек-лист перед деплоем

[ ]
JTBD определён— Понятно какую задачу решает workflow
[ ]
Контракт в БД— clowbot.processes запись создана
[ ]
JSON файл сохранён— n8n/workflows/my_new_workflow.json
[ ]
Webhook работает— curl тест прошёл успешно
[ ]
Error handling— Обработаны ошибки API/LLM
[ ]
Timeout настроен— SLA соответствует ожиданиям
[ ]
is_active = true— Процесс активирован
[ ]
В слотах— Workflow в active_workflow_slots.txt

Типичные ошибки

404 Webhook Not Found

Причина: Workflow не активен или webhook path не синхронизирован

Решение: Запусти n8n_sync_workflows.sh

Timeout

Причина: Workflow выполняется дольше SLA

Решение: Увеличь sla_seconds или оптимизируй workflow

Slot Limit Exceeded

Причина: Уже 5 активных workflows

Решение: Используй n8n_slot_switch.sh demote

Связанные разделы

← Processes Contract

Контракт процесса

Slot Policy →

Управление слотами