godcrm/scripts/training_ru.md

# Добро пожаловать в GOD CRM

GOD CRM -- это гибкая система управления данными, которая позволяет организовать информацию так, как удобно именно вам. Создавайте таблицы, настраивайте представления и автоматизируйте рутинные задачи.

### Ключевые возможности

- **Таблицы** -- Храните любые данные в структурированных таблицах с кастомными полями
- **Представления** -- Смотрите на данные по-разному: таблица, канбан, календарь, галерея
- **Виджеты** -- Создавайте дашборды с визуализацией данных из разных таблиц
- **Автоматизации** -- Автоматизируйте действия при изменении данных

## Быстрый старт

1. **Создайте пространство** -- Пространство -- это контейнер для ваших проектов и таблиц. Например: "Работа", "Личное", "Стартап".
2. **Добавьте таблицу** -- Таблица хранит ваши данные. Каждая запись -- это строка с набором полей (колонок).
3. **Настройте представление** -- Выберите как отображать данные: таблица для детального просмотра, канбан для задач, календарь для событий.
4. **Добавьте виджеты на дашборд** -- Выведите ключевые метрики и данные на дашборд пространства.

---

# Пространства

Пространства -- это верхний уровень организации в GOD CRM. Используйте их для разделения разных областей работы или жизни.

## Что такое пространство?

- **Проекты** -- пространство содержит проекты, каждый со своим набором таблиц и настроек
- **Дашборд** -- у каждого пространства есть дашборд с виджетами для быстрого обзора
- **Кастомизация** -- название, иконка и цвет для быстрой визуальной идентификации

## Примеры использования

### Работа
- CRM клиентов
- Трекер задач
- База знаний

### Личное
- Финансы
- Привычки
- Цели на год

### Стартап
- Roadmap
- Инвесторы
- Метрики

### Обучение
- Курсы
- Книги
- Заметки

---

# Таблицы

Таблицы -- основа GOD CRM. Каждая запись в таблице -- это объект с набором свойств, которые вы определяете сами.

## Создание таблицы

1. Перейдите в проект и нажмите `+ Создать таблицу`
2. Укажите название, иконку и описание таблицы
3. Добавьте колонки (поля) -- они определяют структуру данных
4. Начните добавлять записи через кнопку `+ Добавить`

## Операции с записями

- **Добавить** -- Создайте новую запись в таблице
- **Редактировать** -- Двойной клик открывает карточку записи
- **Импорт** -- Загрузите данные из CSV файла
- **Экспорт** -- Выгрузите данные в CSV или Excel

## Выделение и массовые операции

### Построчное выделение

- Чекбокс слева от каждой строки для выделения
- Чекбокс в заголовке -- выделить/снять все видимые строки
- Выделенные строки подсвечиваются цветом
- Горячие клавиши: Shift+Click для диапазона, Ctrl+A для всех

### Контейнер выделенных

Badge справа от кнопки "Фильтры" показывает количество выделенных строк. Клик открывает меню с действиями:

- По умолчанию -- без сортировки
- Выделенные сверху -- показать выделенные первыми
- Выделенные снизу -- показать выделенные последними
- Снять выделение -- очистить все
- Выбрать все отфильтрованные -- выделить результаты фильтров

### Массовая замена (Find & Replace)

Кнопка "Замена" справа от контейнера открывает модалку для массового изменения данных.

**Применить к:**
- Выделенным строкам -- только отмеченные чекбоксами
- Отфильтрованным строкам -- результаты текущих фильтров
- Всем строкам -- вся таблица без ограничений

**Типы операций:**
- `Заменить значение` -- Draft -> Active
- `Добавить (prefix/suffix)` -- Hello -> Hello World
- `Очистить значение` -- Text -> (пусто)
- `Применить формулу` -- {name} - {code}

**Дополнительно:**
- Поддержка регулярных выражений (regex)
- Учет регистра (case sensitive)
- Предпросмотр изменений перед применением
- Отображение количества затронутых строк

Пример: найти "Draft" и заменить на "Active" в колонке Status для 5 выделенных строк.

---

# Представления

Одни и те же данные можно отображать по-разному. Представления позволяют выбрать наиболее удобный формат для текущей задачи.

## Типы представлений

### Таблица
Классический табличный вид со всеми колонками. Идеален для детального просмотра и редактирования данных.
Применение: CRM с контактами, Инвентарь, База данных

### Канбан
Карточки, сгруппированные по колонкам статуса. Перетаскивайте карточки между колонками.
Применение: Трекер задач, Процесс продаж, Найм сотрудников

### Календарь
Записи отображаются на календаре по датам. Поддерживает события с длительностью.
Применение: Встречи, Дедлайны, Контент-план

### Таймлайн
Gantt-диаграмма с датами начала и окончания. Видна длительность и пересечения.
Применение: Проекты, Roadmap, Планирование

### Галерея
Карточки с превью изображений. Отлично для визуального контента.
Применение: Портфолио, Каталог товаров, Мудборды

### Чек-лист
Список задач с чекбоксами. Отмечайте выполненное, следите за прогрессом.
Применение: To-do листы, Чек-листы, Привычки

### График
Визуализация данных в виде графиков: столбчатые, линейные, круговые.
Применение: Аналитика, Отчеты, Метрики

---

# Типы колонок

Колонки определяют какие данные можно хранить в таблице. Выбирайте правильный тип для валидации и удобного редактирования.

## Доступные типы

### `text` -- Текст
Любой текст, заметки, описания.

**Возможности:**
- Шаблон отображения с переменными: {{name}} ({{code}})
- Префикс и суффикс для форматирования
- Поддержка формул в значении по умолчанию
- Перенос текста: одна строка, авто-перенос, ограниченный

**Настройки:**
- `formula` -- Шаблон с переменными из других колонок
- `prefix` -- Текст перед значением
- `suffix` -- Текст после значения
- `defaultValue` -- Значение по умолчанию для новых строк

Пример: Шаблон: {{first_name}} {{last_name}} -> Иван Иванов

### `number` -- Число
Числа, суммы, количество.

**Возможности:**
- Форматы: обычное число, валюта, процент (%)
- Минимальное и максимальное значение
- Шаг для кнопок +/- в ячейке
- Количество знаков после запятой

**Настройки:**
- `format` -- number | currency | percent
- `min / max` -- Ограничения значений
- `step` -- Шаг изменения (по умолчанию 1)
- `decimals` -- Знаков после запятой (0-10)

Пример: Формат: currency, decimals: 2 -> 1 234,50 руб.

### `select` -- Выбор (Select)
Одно значение из списка опций с цветами.

**Возможности:**
- Список опций с цветовой кодировкой
- Импорт опций из CSV или другой таблицы
- Автоматический сбор опций из существующих данных
- Поддержка relation для подгрузки из связанной таблицы

**Настройки:**
- `options` -- Массив { id, label, color }
- `relation.tableId` -- Таблица-источник опций
- `relation.valueColumn` -- Колонка со значениями
- `relation.labelColumn` -- Колонка с лейблами

Пример: Статус: Новый | В работе | Готово

### `multi-select` -- Мульти-выбор (Multi-Select)
Несколько значений из списка (теги, категории).

**Возможности:**
- Выбор нескольких значений из списка
- Режим relation -- подгрузка опций из связанной таблицы
- 4 формата отображения: badges, list, count, first
- 4 формата хранения: json, comma, semicolon, newline

**Настройки:**
- `relation.tableId` -- Таблица с опциями
- `relation.valueColumn` -- Колонка со значениями (id)
- `relation.labelColumn` -- Колонка с лейблами
- `relation.colorColumn` -- Колонка с цветами (опционально)
- `relation.displayMode` -- badges | list | count | first
- `relation.storageFormat` -- json | comma | semicolon | newline

Пример: Теги: [React] [TypeScript] [Node.js] или "3 тега"

### `datetime` -- Дата и время
Конкретная дата и время.

**Возможности:**
- 3 формата хранения: ISO 8601, Unix (сек), Unix (мс)
- Выбор часового пояса: UTC или браузерный
- 11 форматов отображения
- Поддержка NOW() для текущей даты

**Настройки:**
- `storageFormat` -- ISO8601 | unix | unix_ms
- `timezone` -- UTC | browser
- `displayFormat` -- 25.12.2024 10:30, 25 декабря 2024, и др.

Пример: Хранение: 2024-12-25T10:30:00Z -> Показ: 25 декабря 2024, 13:30

### `time` -- Время (Cron)
Расписание для cron-задач (HH:MM, день месяца).

**Возможности:**
- Ввод времени в формате HH:MM
- Выбор дня месяца для периодических задач
- Интеграция с автоматизациями
- Визуальный редактор расписания

**Настройки:**
- `format` -- HH:MM | cron expression
- `dayOfMonth` -- День месяца (1-31)
- `repeatType` -- daily | weekly | monthly

Пример: 09:00 каждый день или 15:30 каждое 1-е число месяца

### `checkbox` -- Чекбокс
Да/Нет, включено/выключено.

**Возможности:**
- Настраиваемые значения для Да/Нет
- 3 стиля: галочка, переключатель, да/нет
- Значение по умолчанию

**Настройки:**
- `trueValue` -- Значение для "Да" (1, true, yes...)
- `falseValue` -- Значение для "Нет" (0, false, no...)
- `style` -- checkbox | toggle | yesno

Пример: Стиль toggle: ВКЛ / ВЫКЛ

### `url` -- URL (ссылка)
Ссылки на сайты и ресурсы.

**Возможности:**
- Шаблон URL с переменными из других колонок
- Настраиваемый текст ссылки
- Открытие в новой вкладке
- Превью ссылки

**Настройки:**
- `template` -- Шаблон: https://site.com/{{id}}
- `linkText` -- Текст вместо URL

Пример: Шаблон: https://shop.com/products/{{slug}} -> Открыть товар

### `email` -- Email
Электронная почта.

**Возможности:**
- 4 формата отображения
- Кнопка "Написать письмо"
- Копирование по клику
- Маскирование для конфиденциальности

**Настройки:**
- `displayFormat` -- full | link | masked | domain

Пример: Masked: u***@e***.com, Domain: @example.com

### `phone` -- Телефон
Номера телефонов.

**Возможности:**
- 4 формата отображения
- Автоформатирование по стране
- Кнопки: позвонить, WhatsApp, Telegram
- Маскирование для конфиденциальности

**Настройки:**
- `format` -- full | national | international | masked
- `country` -- ru | us | uk | de

Пример: +79001234567 -> 8 (900) 123-45-67 (RU) или +7 *** ***-**-67

### `file` -- Файл
Загрузка файлов.

**Возможности:**
- Загрузка одного или нескольких файлов
- Формула для вычисляемого пути
- Префикс (домен) и суффикс (параметры)
- Форматы: полный URL, имя файла, путь

**Настройки:**
- `formula` -- Шаблон: {{folder}}/{{filename}}
- `prefix` -- Например: https://cdn.site.com/
- `suffix` -- Например: ?v=2

Пример: prefix + formula -> https://cdn.site.com/docs/report.pdf

### `image` -- Изображение
Загрузка и отображение изображений.

**Возможности:**
- 4 режима галереи: стек, карусель, сетка, одно фото
- Настраиваемая высота (32-200px)
- Форма: квадрат, скругленный, круг
- Лайтбокс при клике

**Настройки:**
- `galleryMode` -- stack | carousel | grid | single
- `height` -- Высота в пикселях (32-200)
- `shape` -- square | rounded | circle
- `fit` -- cover | contain | fill

Пример: Режим stack: [фото][фото][фото] +3 фото

### `person` -- Пользователь
Ссылка на пользователя системы.

**Возможности:**
- 3 источника: системные пользователи, из таблицы, ручной ввод
- 5 форматов отображения
- Аватар и имя

**Настройки:**
- `source` -- system | table | manual
- `displayFormat` -- name | avatar | avatar_name | email | card

Пример: Иван Иванов или ivan@company.com

### `relation` -- Связь (Relation)
Ссылка на запись из другой таблицы.

**Возможности:**
- Выбор связанной таблицы
- Настраиваемая колонка для отображения
- Переход к связанной записи по клику
- Множественная связь (многие-ко-многим)

**Настройки:**
- `linkedTableId` -- ID связанной таблицы
- `displayColumn` -- Колонка для отображения

Пример: Клиент: -> Иванов Иван (клик открывает карточку)

### `table` -- Встроенная таблица
Отображает записи из другой таблицы, отфильтрованные по текущей строке.

**Возможности:**
- Показывает связанные записи прямо в ячейке
- Фильтрация по ключу текущей строки
- Выбор колонок для отображения
- Пагинация при большом количестве

**Настройки:**
- `sourceTableId` -- Таблица-источник
- `filterColumn` -- Колонка для фильтрации
- `displayColumns` -- Колонки для отображения

Пример: Товар -> [Подтовары: Размер S | Размер M | Размер L]

### `rollup` -- Сводка (Rollup)
Агрегация данных из связанной таблицы.

**Возможности:**
- 10 функций агрегации
- 4 формата вывода: число, валюта, процент, компактный
- Автоматический пересчет при изменении данных

**Настройки:**
- `function` -- sum | count | avg | min | max | percent | range | countAll | countValues | countUnique
- `format` -- number | currency | percent | compact

Пример: Сумма заказов: 125 400 руб. или Кол-во: 47 шт.

### `vector` -- Вектор (AI поиск)
Векторные эмбеддинги для семантического поиска.

**Возможности:**
- AI-эмбеддинги для поиска по смыслу
- Формула для составления текста
- Интеграция с OpenAI text-embedding-ada-002
- Хранение в PostgreSQL + pgvector

**Настройки:**
- `formula` -- Шаблон: {{title}} {{description}}
- `prefix` -- Контекст перед текстом
- `suffix` -- Контекст после текста

Пример: Запрос: "синие джинсы" -> Найдено: "Брюки деним navy" (95%)

### `button` -- Кнопка
Кнопка для действий.

**Возможности:**
- 3 типа действий: открыть URL, webhook, автоматизация
- Поддержка переменных в URL
- 3 стиля: primary, secondary, danger

**Настройки:**
- `action` -- url | webhook | automation
- `url` -- URL с переменными: /edit/{{id}}
- `style` -- primary | secondary | danger

Пример: [Редактировать] -> /admin/edit/{{id}}

### `audio` -- Аудио
Аудио плеер для воспроизведения звуков.

**Возможности:**
- Встроенный аудио плеер в ячейке
- Поддержка URL на аудио файлы
- Формула для вычисления пути
- Префикс (домен CDN)

**Настройки:**
- `formula` -- Шаблон: audio/{{filename}}.mp3
- `prefix` -- URL CDN: https://cdn.site.com/

Пример: [0:00 / 3:45] -> воспроизведение из CDN

### `password` -- Пароль
Зашифрованный текст.

**Возможности:**
- Скрытое отображение: --------
- Безопасное хранение
- Кнопка показать/скрыть
- Копирование в буфер

**Настройки:**
- `showButton` -- Показывать кнопку "глазик"

Пример: Поле ввода: [--------]

### `formula` -- Формула
Вычисляемое поле.

**Возможности:**
- JavaScript выражения
- Доступ к данным других колонок
- Автопересчет при изменении
- Форматирование результата

**Настройки:**
- `expression` -- JS выражение: price * qty
- `format` -- number | currency | percent

Пример: Итого: price * qty * (1 - discount/100) -> 8 500 руб.

### `dialog` -- AI Диалог
AI диалог / переписка.

**Возможности:**
- История переписки с AI
- Контекст из текущей строки
- Интеграция с AI агентами
- Сохранение диалога в строке

**Настройки:**
- `agentId` -- ID AI агента для диалога
- `contextColumns` -- Колонки для контекста

Пример: Диалог с AI по карточке клиента

### `chat` -- AI Чат
AI чат-разговор.

**Возможности:**
- Полноценный чат с AI
- История сообщений
- Стриминг ответов
- Поддержка разных моделей

**Настройки:**
- `model` -- Модель: gpt-4, claude-3, etc.
- `systemPrompt` -- Системный промпт

Пример: Чат с ИИ-ассистентом в ячейке

## Векторная колонка (AI поиск)

### Что такое векторная колонка?

Векторная колонка автоматически создает AI-эмбеддинги (векторные представления) из текстовых данных, что позволяет искать записи по смыслу, а не по точному совпадению слов.

**Применение:**
- Поиск похожих товаров
- Семантический поиск документов
- Рекомендации контента
- Дублирование записей

**Технология:**
- OpenAI text-embedding-ada-002
- Хранение в PostgreSQL + pgvector
- Косинусное сходство для поиска
- Автоматическая векторизация

### Настройки векторной колонки

**`formula`** (необязательно) -- Формула для создания текста, который будет векторизован. Поддерживает переменные из других колонок.

```
{{title}} {{articul}}
{{description}}
Категория: {{category_id}}
Бренд: {{brand_id}}
```

**`prefix`** (необязательно) -- Текст, добавляемый перед формулой. Используется для контекста. Например: "Товар: "

**`suffix`** (необязательно) -- Текст, добавляемый после формулы. Например: " (в наличии)"

### Пример: Поиск товаров

Пользователь ищет "синие джинсы мужские". Система найдет товары с похожим смыслом, даже если слова отличаются: "Брюки деним navy для мужчин".

Запрос: `синие джинсы мужские` -> Результат: `Брюки деним navy (95% сходство)`

## Действия с колонками

### Создание колонки

1. Клик по кнопке `+ Добавить колонку` в заголовке таблицы
2. Выберите тип колонки из списка (text, number, select и т.д.)
3. Укажите название и системное имя (автоматически генерируется из названия)
4. Настройте параметры в зависимости от типа
5. Нажмите `Сохранить`

### Редактирование
Клик по иконке шестеренки в заголовке колонки или правая кнопка мыши -> Настройки

### Удаление
Настройки колонки -> внизу кнопка "Удалить колонку". Данные будут потеряны!

### Перемещение
Перетащите заголовок колонки влево/вправо для изменения порядка отображения

### Скрытие/Показ
Правая кнопка на заголовке -> Скрыть колонку. Восстановить через меню "Скрытые колонки"

### Дублирование
Настройки колонки -> Дублировать. Создает копию со всеми настройками

### Изменение ширины
Перетащите границу между заголовками колонок или укажите точное значение в пикселях

## Настройки отображения

### Ширина колонки
Размер в пикселях (80-800px). Значения: Авто, 150px (по умолчанию), 200px, 300px...

### Выравнивание текста
Горизонтальное выравнивание содержимого: Слева, По центру, Справа

### Перенос текста
Поведение при переполнении ячейки:
- **nowrap** -- Одна строка с обрезкой ...
- **wrap** -- Автоматический перенос, высота по содержимому
- **ellipsis** -- Ограниченный перенос (2-3 строки) + ...

### Типографика
Размер шрифта (10-24px), **жирный**, *курсив*, `моноширинный`

### Цвета
Цвет текста и цвет фона ячейки

## Формулы и переменные

### Что такое формулы?

Формулы позволяют автоматически вычислять значения на основе других колонок. Используйте переменные в фигурных скобках `{{column_name}}` для подстановки значений.

Пример:
```
{{first_name}} {{last_name}} ({{email}})
```
Результат: Иван Петров (ivan@example.com)

### Синтаксис переменных

**`{{column_name}}`** -- Базовая подстановка значения из колонки
```
{{title}} - {{price}} руб.
```

**`{{value}}`** -- Текущее значение ячейки (для формул типа файл, вектор)
```
Префикс: https://cdn.example.com/
Формула: {{folder}}/{{value}}
Результат: https://cdn.example.com/images/photo.jpg
```

**`NOW()`** -- Специальная функция для текущей даты и времени
```
Значение по умолчанию: NOW()
Результат: 2025-12-13T23:45:00
```

### Где можно использовать формулы

- **Текстовые колонки** -- Шаблон отображения, префикс, суффикс
- **Файлы и изображения** -- Формула пути, префикс URL
- **URL колонки** -- Шаблон ссылки, текст ссылки
- **Векторные колонки** -- Формула векторизации текста
- **Кнопки** -- URL для перехода, webhook endpoint
- **Значения по умолчанию** -- Для любого типа колонки

### Практические примеры формул

- **Полное имя:** `{{first_name}} {{middle_name}} {{last_name}}`
- **URL товара:** `https://shop.com/products/{{id}}/{{slug}}`
- **Путь к файлу:** `{{year}}/{{month}}/{{category}}/{{filename}}`
- **Описание для поиска:** `{{brand}} {{model}} {{color}} {{size}}`

### Важные замечания

- Если колонка не существует, `{{unknown}}` будет выделена красным
- Существующие колонки подсвечиваются `{{name}}` зеленым
- Формулы пересчитываются автоматически при изменении исходных данных
- В формулах учитывается регистр: `{{Name}}` != `{{name}}`

## Настройки колонок

- **Название** -- Отображаемое имя колонки
- **Тип** -- Определяет формат данных
- **Обязательность** -- Требовать заполнение
- **Значение по умолчанию** -- Автоматически подставляется
- **Ширина** -- Размер колонки в таблице
- **Видимость** -- Скрыть/показать колонку

---

# Фильтры и поиск

Фильтры помогают найти нужные записи в большом объеме данных. Комбинируйте условия для точного результата.

## Поиск

Быстрый поиск по всем текстовым полям:

- Введите текст в поле поиска -- результаты обновятся мгновенно
- Поиск работает по названию и текстовым колонкам
- Можно выбрать конкретные колонки для поиска

## Типы фильтров

### Фильтр по выбору
Показать записи с определенными значениями в колонке типа Select/Multiselect.
Пример: `Статус = 'В работе' ИЛИ 'На проверке'`

### Фильтр по дате
Показать записи в определенном диапазоне дат.
Пример: `Дедлайн: с 1 декабря по 31 декабря`

### Комбинированные фильтры
Несколько фильтров применяются одновременно (условие И).
Пример: `Статус = 'В работе' И Исполнитель = 'Иван'`

## Сортировка

Упорядочивание записей:

- Клик по заголовку колонки -- сортировка по возрастанию
- Повторный клик -- сортировка по убыванию
- Работает для текста, чисел и дат

---

# Виджеты и дашборды

Виджеты позволяют вынести данные из таблиц на дашборд в удобном формате. Создавайте обзорные панели для быстрого мониторинга.

## Создание виджета

1. Перейдите на дашборд пространства и нажмите `+ Добавить виджет`
2. Выберите тип представления (канбан, календарь, график и т.д.)
3. Укажите таблицу-источник данных
4. Настройте маппинг полей и фильтры в настройках виджета

## Типы виджетов

- Таблица
- Канбан
- Календарь
- Таймлайн
- График
- Чек-лист

## Управление дашбордом

- **Изменение размера** -- перетащите угол виджета
- **Перемещение** -- перетащите виджет за заголовок
- **Настройки** -- нажмите шестеренку в углу виджета
- **Удаление** -- через меню настроек виджета

---

# Автоматизации

Автоматизируйте рутинные действия. Когда происходит определенное событие -- система выполняет заданные действия автоматически.

## Триггеры (когда запускать)

- **Создание записи** -- Когда в таблицу добавляется новая запись
- **Обновление записи** -- Когда изменяется любое поле записи
- **Изменение поля** -- Когда изменяется конкретное поле (например, статус)
- **Удаление записи** -- Когда запись удаляется из таблицы

## Действия (что делать)

- **Отправить уведомление** -- Email или push-уведомление пользователю
- **Обновить запись** -- Автоматически изменить поля записи
- **Создать запись** -- Добавить новую запись в эту или другую таблицу
- **Вызвать Webhook** -- Отправить HTTP-запрос на внешний сервис

## Примеры автоматизаций

- **КОГДА** Статус задачи -> 'Готово' **ТОГДА** Отправить уведомление автору задачи
- **КОГДА** Создана новая заявка **ТОГДА** Назначить ответственного менеджера
- **КОГДА** Дедлайн через 1 день **ТОГДА** Напомнить исполнителю

## Webhooks

Интеграция с внешними сервисами.

Webhooks позволяют отправлять данные из CRM во внешние системы при определенных событиях.

- Интеграция с Telegram ботами
- Синхронизация с внешними CRM
- Отправка данных в аналитические системы
- Запуск процессов в n8n, Zapier, Make

---

# REST API

GOD CRM предоставляет полнофункциональный REST API для интеграции с внешними системами. Все эндпоинты возвращают JSON и требуют аутентификации.

## Аутентификация

API поддерживает два способа аутентификации: JWT токены и API ключи.

### API Ключи (рекомендуется для интеграций)

Создайте API ключ в Настройках -> API Ключи. Ключ начинается с `sk-`

Использование через заголовок X-API-Key:
```
X-API-Key: sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Или через Authorization:
```
Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

### JWT Токены (для веб-приложений)

Получите токен через `POST /api/v3/auth/login`

```
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

### Базовый URL

```
https://crm.hltrn.cc/api/v3
```

## Управление API ключами

**GET** `/api-keys` -- Получить список ваших API ключей

**POST** `/api-keys` -- Создать новый API ключ

Request Body:
```json
{
  "name": "string",
  "scopes": ["*"],
  "expires_in_days": "number"
}
```

**DELETE** `/api-keys/:id` -- Удалить (отозвать) API ключ

### Доступные права (scopes)

- `*` -- полный доступ
- `tables:read`
- `tables:write`
- `rows:read`
- `rows:write`
- `widgets:read`
- `widgets:write`

## Таблицы API

**GET** `/tables` -- Получить список всех таблиц

**POST** `/tables` -- Создать новую таблицу

Request Body:
```json
{
  "name": "string",
  "space_id": "number",
  "emoji": "string"
}
```

**GET** `/tables/:id` -- Получить информацию о таблице

**PATCH** `/tables/:id` -- Обновить таблицу

Request Body:
```json
{
  "name": "string",
  "emoji": "string"
}
```

**DELETE** `/tables/:id` -- Удалить таблицу

## Колонки API

**GET** `/tables/:tableId/columns` -- Получить колонки таблицы

**POST** `/tables/:tableId/columns` -- Создать колонку

Request Body:
```json
{
  "name": "string",
  "type": "text|number|select|datetime|...",
  "options": "object"
}
```

**PATCH** `/columns/:id` -- Обновить колонку

**DELETE** `/columns/:id` -- Удалить колонку

### Типы колонок

text, number, select, multi_select, datetime, time, checkbox, url, email, phone, rating, file, image, relation, lookup, formula, rollup, json, vector

## Записи API

**GET** `/tables/:tableId/rows` -- Получить записи таблицы
Query: `?limit=50&offset=0&sort=column_id&order=asc`

**POST** `/tables/:tableId/rows` -- Создать запись

Request Body:
```json
{
  "values": {
    "column_id": "value"
  }
}
```

**GET** `/rows/:id` -- Получить запись по ID

**PATCH** `/rows/:id` -- Обновить запись

Request Body:
```json
{
  "values": {
    "column_id": "new_value"
  }
}
```

**DELETE** `/rows/:id` -- Удалить запись

**POST** `/tables/:tableId/rows/batch` -- Массовое создание записей

Request Body:
```json
{
  "rows": [
    { "values": {} },
    { "values": {} }
  ]
}
```

## Представления API

**GET** `/tables/:tableId/views` -- Получить представления таблицы

**POST** `/tables/:tableId/views` -- Создать представление

Request Body:
```json
{
  "name": "string",
  "type": "table|kanban|calendar|gallery",
  "config": "object"
}
```

**PATCH** `/views/:id` -- Обновить представление

**DELETE** `/views/:id` -- Удалить представление

## Виджеты API

**GET** `/dashboards/:dashboardId/widgets` -- Получить виджеты дашборда

**POST** `/dashboards/:dashboardId/widgets` -- Создать виджет

Request Body:
```json
{
  "type": "chart|stat|kanban|calendar|...",
  "config": "object",
  "position": { "x": 0, "y": 0, "w": 2, "h": 2 }
}
```

**PATCH** `/widgets/:id` -- Обновить виджет

**DELETE** `/widgets/:id` -- Удалить виджет

### Типы виджетов

- chart -- графики
- stat -- статистика
- kanban -- канбан-доска
- calendar -- календарь
- task_list -- список задач
- table -- мини-таблица

## Вебхуки API

**GET** `/tables/:tableId/webhooks` -- Получить вебхуки таблицы

**POST** `/tables/:tableId/webhooks` -- Создать вебхук

Request Body:
```json
{
  "url": "string",
  "events": ["row.created", "row.updated", "row.deleted"],
  "secret": "string"
}
```

**DELETE** `/webhooks/:id` -- Удалить вебхук

### События вебхуков

- `row.created` -- создание записи
- `row.updated` -- обновление записи
- `row.deleted` -- удаление записи

## Внешние источники API

**GET** `/data-sources` -- Получить список источников данных

**POST** `/data-sources` -- Создать внешний источник

Request Body:
```json
{
  "name": "string",
  "type": "postgres|mysql|api",
  "connection": "object"
}
```

**POST** `/data-sources/:id/sync` -- Синхронизировать данные

**DELETE** `/data-sources/:id` -- Удалить источник

## Vector API (Семантический поиск)

### Что это?

Vector API позволяет создавать векторные эмбеддинги текста и искать похожие записи по смыслу, а не по точному совпадению слов. Использует OpenAI embeddings и PostgreSQL с расширением pgvector.

| Параметр | Значение |
|----------|----------|
| Модель | text-embedding-ada-002 |
| Размерность | 1536 dimensions |
| Сходство | Cosine similarity |

**POST** `/api/v3/ai/vector/embed` -- Создать и сохранить эмбеддинг для текста

Request Body:
```json
{
  "workspaceId": "number",
  "tableId": "number",
  "rowId": "number",
  "text": "string",
  "metadata": "object"
}
```

Пример запроса /embed:
```json
{
  "workspaceId": 1,
  "tableId": 5,
  "rowId": 123,
  "text": "Смартфон Apple iPhone 15 Pro 256GB Blue Titanium",
  "metadata": {
    "category": "electronics",
    "price": 99999
  }
}
```

**POST** `/api/v3/ai/vector/search` -- Поиск похожих записей по тексту запроса

Request Body:
```json
{
  "workspaceId": "number",
  "queryText": "string",
  "tableId": "number",
  "limit": "number (default: 10)",
  "metadataFilters": "object"
}
```

Пример запроса /search:
```json
{
  "workspaceId": 1,
  "queryText": "телефон айфон синий",
  "tableId": 5,
  "limit": 5,
  "metadataFilters": {
    "category": "electronics"
  }
}
```

Пример ответа:
```json
{
  "success": true,
  "results": [
    {
      "rowId": 123,
      "similarity": 0.94,
      "metadata": {
        "category": "electronics",
        "text_content": "Смартфон Apple iPhone 15 Pro 256GB Blue Titanium"
      }
    },
    {
      "rowId": 124,
      "similarity": 0.89,
      "metadata": {
        "text_content": "iPhone 15 Blue 128GB"
      }
    }
  ],
  "count": 2
}
```

**POST** `/api/v3/ai/vector/batch` -- Массовое создание эмбеддингов

Request Body:
```json
{
  "workspaceId": "number",
  "items": [
    { "tableId": "number", "rowId": "number", "text": "string", "metadata": "object" }
  ]
}
```

**POST** `/api/v3/ai/vector/generate-cell` -- Создать эмбеддинг для векторной колонки с учетом формулы

Request Body:
```json
{
  "tableId": "number",
  "rowId": "number",
  "columnId": "number"
}
```

### Как работает /generate-cell

Этот эндпоинт читает настройки векторной колонки (formula, prefix, suffix), подставляет значения из других колонок строки, формирует итоговый текст и создает эмбеддинг.

1. Формула колонки: Префикс: "Товар: " + Formula: {{title}} {{category}} + Суффикс: " в наличии"
2. Данные строки: title: "iPhone 15", category: "Смартфоны"
3. Итоговый текст: "Товар: iPhone 15 Смартфоны в наличии"
4. Создание эмбеддинга через OpenAI API

**GET** `/api/v3/ai/vector/stats/:workspaceId` -- Получить статистику по эмбеддингам

### Требования

- **OPENAI_API_KEY** -- API ключ OpenAI в переменных окружения
- **PostgreSQL + pgvector** -- база данных с расширением для векторов
- **База business_crm_vectors** -- отдельная БД для хранения эмбеддингов

## Примеры использования

### Создание записи (cURL)

```bash
curl -X POST https://crm.hltrn.cc/api/tables/1/rows \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "values": {
      "name": "Новый клиент",
      "email": "client@example.com",
      "status": "new"
    }
  }'
```

### JavaScript/Fetch

```javascript
const response = await fetch('/api/tables/1/rows', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    values: {
      name: 'Новый клиент',
      email: 'client@example.com',
    }
  })
});

const newRow = await response.json();
console.log('Created row:', newRow.id);
```

## Обработка ошибок

API возвращает стандартные HTTP коды и JSON с описанием ошибки:

| Код | Описание |
|-----|----------|
| `200` | OK -- успешно |
| `201` | Created -- создано |
| `400` | Bad Request -- ошибка запроса |
| `401` | Unauthorized -- не авторизован |
| `404` | Not Found -- не найдено |
| `500` | Server Error -- ошибка сервера |

Формат ошибки:
```json
{
  "error": true,
  "message": "Table not found",
  "code": "TABLE_NOT_FOUND"
}
```

---

# AI Агенты

Интеллектуальные помощники, которые понимают ваши данные и помогают работать с ними. Агенты могут отвечать на вопросы, анализировать данные и выполнять задачи.

## Что такое AI Агенты?

AI Агенты -- это настраиваемые AI-помощники на базе GPT-4, Claude или других моделей. Каждый агент имеет свою роль, знания и инструменты.

- **Персонализация** -- Настройте системный промпт, модель и инструменты под свои задачи
- **Контекст данных** -- Агент понимает структуру ваших таблиц и может работать с данными
- **Множество провайдеров** -- OpenAI, Anthropic, Google, Ollama -- выбирайте подходящую модель
- **Мониторинг** -- Отслеживание использования токенов, стоимости и качества ответов

## Быстрый старт

1. **Создайте пространство "AI Agents"** -- Или используйте существующее. В пространстве должны быть таблицы: Agents, Models, Providers, API Keys.
2. **Добавьте API ключ провайдера** -- В таблицу API Keys добавьте ключ от OpenAI, Anthropic или другого провайдера.
3. **Создайте агента** -- В таблице Agents создайте запись с именем, описанием, системным промптом и выбором модели.
4. **Начните диалог** -- Нажмите на иконку чата в правом нижнем углу и выберите агента.

## Настройка агента

- `name` -- Имя агента для отображения в списке
- `description` -- Краткое описание назначения агента
- `system_prompt` -- Системный промпт, определяющий поведение и роль агента
- `model` -- Связь с таблицей Models -- выбор AI модели
- `provider_id` -- Связь с таблицей Providers -- выбор провайдера API
- `api_key_id` -- Связь с таблицей API Keys -- ключ для авторизации
- `tools` -- JSON массив доступных инструментов агента
- `is_active` -- Checkbox -- активен ли агент для использования

## AI агенты и векторный поиск

### Семантический поиск данных

AI агенты могут использовать векторный поиск для интеллектуального анализа данных. Вместо точного совпадения слов, агент понимает смысл запроса и находит релевантные записи.

### Пример 1: Поиск похожих товаров

**Вопрос:** "Найди товары похожие на iPhone 15"

**Агент:** Использует Vector API для поиска товаров с похожими характеристиками: смартфоны премиум-класса, большой экран, хорошая камера -> находит Samsung S24 Ultra, Google Pixel 8 Pro

### Пример 2: Поиск документов по смыслу

**Вопрос:** "Где информация про работу с клиентами?"

**Агент:** Ищет документы семантически связанные с CRM, клиентским сервисом, продажами -> находит "CRM Руководство", "Обработка заявок", "Скрипты продаж"

### Пример 3: Рекомендации

**Вопрос:** "Что еще может понравиться клиенту, который купил ноутбук для дизайна?"

**Агент:** Анализирует покупку через векторный поиск -> рекомендует графический планшет, внешний монитор 4K, мышь для дизайнеров, подписку Adobe Creative Cloud

### Как включить векторный поиск для агента

1. Создайте векторную колонку в нужной таблице
2. Настройте формулу векторизации (какие поля включать)
3. Добавьте инструмент `vector_search` агенту
4. В системном промпте укажите, когда использовать векторный поиск

## Поддерживаемые провайдеры

- **OpenAI** -- GPT-4, GPT-4 Turbo, GPT-3.5
- **Anthropic** -- Claude 3.5, Claude 3 Opus
- **Google** -- Gemini 1.5 Pro, Gemini Flash
- **Ollama** -- Llama 3.2, Mistral, CodeLlama

## Логи сообщений

Все взаимодействия с агентами автоматически логируются в таблицу "Message Logs":

- agent_name
- user_id
- model
- message
- response
- tokens_in/out
- status
- timestamp

## Советы

- **Системный промпт** -- Четко определите роль агента. Например: "Ты аналитик продаж. Отвечай кратко и по делу."
- **Выбор модели** -- GPT-4 Turbo для сложных задач, GPT-3.5 для простых -- экономьте токены разумно.
- **Переменные в промптах** -- Используйте шаблоны вида {{table.column}} для динамической подстановки данных из таблиц.

---

# AI Agents API

API для работы с AI-агентами, провайдерами и моделями. Позволяет управлять искусственным интеллектом в вашем рабочем пространстве.

## Обзор возможностей

- **AI Агенты** -- Создание и управление интеллектуальными помощниками
- **Чат с агентами** -- Отправка сообщений и получение ответов от AI
- **Провайдеры** -- OpenAI, Anthropic, Google, Ollama
- **Модели** -- GPT-4, Claude, Gemini и другие

## Базовый URL

```
https://crm.hltrn.cc/api/v3/ai
```

## Агенты

**GET** `/ai/agents` -- Получить список всех агентов

**GET** `/ai/agents/:spaceId` -- Получить агентов для конкретного пространства

**POST** `/ai/agents` -- Создать нового агента

Request Body:
```json
{
  "name": "string",
  "description": "string",
  "model": "gpt-4-turbo",
  "provider": "openai",
  "system_prompt": "string",
  "tools": ["string"]
}
```

**PATCH** `/ai/agents/:id` -- Обновить агента

Request Body:
```json
{
  "name": "string",
  "model": "string",
  "system_prompt": "string"
}
```

**DELETE** `/ai/agents/:id` -- Удалить агента

## Чат с агентом

**POST** `/ai/chat` -- Отправить сообщение агенту и получить ответ

Request Body:
```json
{
  "agentId": "number",
  "message": "string",
  "conversationId": "string",
  "context": "object"
}
```

Пример ответа:
```json
{
  "success": true,
  "response": "Привет! Я готов помочь вам с задачами...",
  "conversationId": "conv_abc123",
  "model": "gpt-4-turbo",
  "usage": {
    "promptTokens": 150,
    "completionTokens": 85,
    "totalTokens": 235
  }
}
```

**GET** `/ai/conversations/:conversationId` -- Получить историю диалога

**DELETE** `/ai/conversations/:conversationId` -- Удалить диалог

## Провайдеры AI

**GET** `/ai/providers` -- Получить список провайдеров AI

Поддерживаемые провайдеры:

- `openai` -- OpenAI (GPT-4, GPT-3.5)
- `anthropic` -- Anthropic (Claude)
- `google` -- Google (Gemini)
- `ollama` -- Ollama (локальные модели)

**POST** `/ai/providers` -- Добавить провайдера

Request Body:
```json
{
  "name": "string",
  "provider_key": "openai|anthropic|google|ollama",
  "base_url": "string",
  "is_active": true
}
```

**PATCH** `/ai/providers/:id` -- Обновить провайдера

**DELETE** `/ai/providers/:id` -- Удалить провайдера

## Модели

**GET** `/ai/models` -- Получить список всех моделей

**GET** `/ai/models?providerId=:id` -- Получить модели конкретного провайдера

Популярные модели:

- **OpenAI:** gpt-4-turbo, gpt-4o, gpt-3.5-turbo
- **Anthropic:** claude-3-5-sonnet-20241022, claude-3-opus
- **Google:** gemini-1.5-pro, gemini-1.5-flash
- **Ollama:** llama3.2, mistral, codellama

**POST** `/ai/models` -- Добавить модель

Request Body:
```json
{
  "provider_id": "number",
  "model_id": "gpt-4-turbo",
  "display_name": "GPT-4 Turbo",
  "context_window": 128000,
  "is_active": true
}
```

**PATCH** `/ai/models/:id` -- Обновить модель

**DELETE** `/ai/models/:id` -- Удалить модель

## Обновление моделей

**POST** `/ai/providers/:providerId/refresh-models` -- Обновить список моделей от провайдера через API

Пример ответа:
```json
{
  "success": true,
  "message": "Обновлено моделей: 17",
  "added": 12,
  "updated": 5,
  "models": [
    { "model_id": "gpt-4-turbo", "display_name": "GPT-4 Turbo" },
    { "model_id": "gpt-4o", "display_name": "GPT-4o" }
  ]
}
```

**Важно:** Для обновления моделей требуется настроенный API ключ провайдера в таблице API Keys. Поддерживается автоматическое обновление для OpenAI и Anthropic.

## API Ключи для AI

API ключи провайдеров хранятся в таблице "API Keys" пространства "AI Agents".

Структура записи API Key:
```json
{
  "provider": "openai",
  "key_name": "OpenAI API",
  "api_key": "sk-...",
  "is_active": true,
  "last_used": "2024-01-15"
}
```

## Инструменты агентов

Агенты могут использовать инструменты для взаимодействия с CRM.

| Инструмент | Описание |
|------------|----------|
| `get_workspace_info` | Получить информацию о пространствах, проектах и таблицах |
| `query_table_data` | Выполнить запрос к данным таблицы |
| `create_table` | Создать новую таблицу |
| `create_row` | Добавить запись в таблицу |
| `update_row` | Обновить запись в таблице |
| `create_dashboard` | Создать дашборд |
| `create_widget` | Добавить виджет на дашборд |
| `search_records` | Поиск записей по критериям |

## Примеры использования

### Отправить сообщение агенту (cURL)

```bash
curl -X POST https://crm.hltrn.cc/api/v3/ai/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "agentId": 1,
    "message": "Покажи статистику продаж за этот месяц",
    "context": {
      "spaceId": 5,
      "tableId": 12
    }
  }'
```

### JavaScript / Fetch

```javascript
const response = await fetch('/api/v3/ai/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    agentId: 1,
    message: 'Создай отчет по задачам',
    conversationId: 'conv_existing_id' // опционально
  })
});

const { response: aiResponse, usage } = await response.json();
console.log('AI ответил:', aiResponse);
console.log('Использовано токенов:', usage.totalTokens);
```

### Обновить модели провайдера

```javascript
// Получить свежий список моделей от OpenAI
const result = await fetch('/api/v3/ai/providers/1/refresh-models', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
});

const { added, updated, models } = await result.json();
console.log(`Добавлено: ${added}, обновлено: ${updated}`);
```

## Обработка ошибок

| Код | Описание |
|-----|----------|
| `400` | Неверный запрос |
| `401` | Не авторизован |
| `404` | Агент не найден |
| `500` | Ошибка AI провайдера |

Формат ошибки AI:
```json
{
  "success": false,
  "error": "AI_PROVIDER_ERROR",
  "message": "OpenAI API rate limit exceeded",
  "details": {
    "provider": "openai",
    "model": "gpt-4-turbo"
  }
}
```