ваше сообщение коммита

docs/user-tables-relation-task.md

@@ -0,0 +1,150 @@
+# Техническое задание: Пользовательские таблицы с настраиваемыми связями
+
+## Цель
+Реализовать систему пользовательских таблиц, в которых при создании столбца можно настраивать нужные связи (relation/reference/lookup) с другими таблицами.
+
+---
+
+## Основные требования
+
+1. **Пользователь может создавать любые таблицы** (например, "Клиенты", "Теги", "Продукты", "RAG-таблица" и т.д.).
+2. **Для каждой таблицы можно добавлять столбцы разных типов:**
+   - text, number, date, select, multiselect
+   - relation/reference (связь с другой таблицей)
+   - lookup (вывод связанных данных из другой таблицы)
+3. **Для столбцов типа relation/reference:**
+   - Можно выбрать, с какой таблицей и каким полем устанавливается связь
+   - Можно выбрать тип связи: один-к-одному, один-ко-многим, многие-ко-многим
+   - В ячейке такого столбца пользователь может выбрать одну или несколько строк из связанной таблицы
+4. **Связи хранятся в отдельной таблице связей или в value ячейки (массив id)**
+5. **В интерфейсе:**
+   - При создании/редактировании столбца типа relation пользователь выбирает таблицу и поле для связи
+   - В таблице, в ячейке relation-столбца, отображается выпадающий список/мультивыбор с данными из связанной таблицы
+6. **Фильтрация и поиск:**
+   - Можно фильтровать строки по связанным значениям (например, все вопросы, относящиеся к определённому тегу или продукту)
+7. **Масштабируемость:**
+   - Архитектура должна поддерживать создание большого количества таблиц, столбцов и связей без потери производительности
+
+---
+
+## Примеры сценариев
+
+### 1. Связь "Клиент — Теги"
+- Пользователь создаёт таблицу "Клиенты" и таблицу "Теги"
+- В таблице "Клиенты" добавляет столбец типа relation, связывающий клиента с одним или несколькими тегами
+- В каждой строке можно выбрать теги из справочника
+
+### 2. Связь "Вопрос — Продукты"
+- В RAG-таблице добавляется столбец типа relation к таблице "Продукты"
+- Для каждого вопроса можно выбрать, к каким продуктам он относится
+
+### 3. Lookup-столбец
+- В таблице "Клиенты" можно добавить lookup-столбец, который автоматически подтягивает связанные значения из другой таблицы (например, список продуктов, которыми пользуется клиент)
+
+---
+
+## Требования к backend
+- Расширить модели user_tables, user_columns, user_rows, user_cell_values
+- Добавить таблицу связей (например, table_relations: id, from_row_id, column_id, to_table, to_row_id)
+- API для создания/редактирования столбцов с типом relation
+- API для получения и сохранения связей
+
+## Требования к frontend
+- UI для выбора типа столбца (relation/reference/lookup)
+- UI для выбора связанной таблицы и поля
+- UI для выбора значений в ячейке relation-столбца (выпадающий список, мультивыбор)
+- Фильтрация и отображение связанных данных
+
+---
+
+## Преимущества
+- Максимальная гибкость и масштабируемость
+- Возможность строить сложные взаимосвязанные базы знаний, CRM, RAG-ассистентов
+- Удобство для ИИ и аналитики 
+
+## Типы столбцов для пользовательских таблиц
+
+1. **text** — однострочный текст
+2. **textarea** — многострочный текст (заметки, описания)
+3. **number** — число (целое или дробное)
+4. **date** — дата
+5. **datetime** — дата и время
+6. **time** — только время
+7. **boolean/checkbox** — булево значение (чекбокс)
+8. **select** — выпадающий список (одиночный выбор)
+9. **multiselect** — выпадающий список (множественный выбор)
+10. **file/image** — файл или изображение (загрузка и хранение)
+11. **relation/reference** — связь с другой таблицей (выбор одной или нескольких строк из другой таблицы)
+12. **lookup** — автоматический вывод связанных данных из другой таблицы по relation
+13. **email** — email-адрес с валидацией
+14. **phone** — телефон с валидацией
+15. **url** — ссылка/URL с валидацией
+16. **currency** — число с символом валюты
+17. **percent** — число с отображением в процентах
+18. **color** — выбор цвета (colorpicker)
+19. **user/assignee** — ссылка на пользователя системы (ответственный)
+20. **status** — список статусов (например, “В работе”, “Готово”)
+21. **formula** — вычисляемое поле на основе других столбцов
+22. **progress/rating** — визуальное отображение прогресса, рейтинга (шкала, звёзды)
+23. **json/object** — хранение структурированных данных (JSON) 
+
+## Плейсхолдеры для интеграции с ИИ-ассистентом
+
+- Для каждого столбца при создании автоматически генерируется плейсхолдер (placeholder), который можно использовать в промтах и шаблонах для ИИ-ассистента.
+- Плейсхолдер формируется на основе названия столбца (транслитерация, нижний регистр, замена пробелов на подчёркивания, например: "Партнеры венчурного фонда" → {partners_venchurnogo_fonda}).
+- Плейсхолдер уникален в рамках таблицы. При совпадении имён добавляется суффикс или используется id столбца.
+- В таблице user_columns рекомендуется добавить поле placeholder (string, unique).
+- В интерфейсе при создании/редактировании столбца отображать сгенерированный плейсхолдер (и, при необходимости, давать возможность его редактировать).
+- В системных промтах и шаблонах для LLM/ассистента значения автоматически подставляются по плейсхолдерам.
+
+**Пример использования в промте:**
+```
+Вопрос: {question}
+Ответ: {answer}
+Партнеры: {partners}
+``` 
+
+## Использование плейсхолдеров в системном промте ассистента
+
+- На странице настроек ассистента (`/settings/ai/assistant`) под полем для системного промта автоматически отображается список всех плейсхолдеров, созданных пользователем в пользовательских таблицах.
+- Для каждого плейсхолдера показывается:
+  - Сам плейсхолдер (например, `{partners}`)
+  - Название столбца и таблицы, к которому он относится (например, “Партнеры венчурного фонда” — RAG-таблица)
+- Список плейсхолдеров обновляется автоматически при добавлении/удалении столбцов.
+
+**Инструкция для пользователя:**
+> Используйте плейсхолдеры из списка ниже для подстановки значений из пользовательских таблиц в системный промт. Например:
+> ```
+> Вопрос: {question}
+> Ответ: {answer}
+> Партнеры: {partners}
+> ```
+> Плейсхолдеры автоматически заменяются на соответствующие значения при генерации ответа ассистента. 
+
+## Сценарий: добавление тегов пользователю через пользовательские таблицы
+
+1. **Добавление тега на странице контакта**
+   - На странице контакта (`/contacts/1`) при нажатии на кнопку "Добавить тег" система автоматически создаёт пользовательскую таблицу "Теги клиентов" (если она ещё не создана).
+   - Пользователь может добавить новый тег (например, "VIP", "B2B", "Startup") — он появляется в этой таблице.
+
+2. **Выпадающий список тегов**
+   - После добавления хотя бы одного тега появляется выпадающий список (или мультивыбор), в котором отображаются все теги из таблицы "Теги клиентов".
+   - Пользователь может выбрать один или несколько тегов для текущего контакта.
+
+3. **Связь пользователя с тегом**
+   - При выборе тега для пользователя создаётся связь между пользователем и тегом.
+   - Эта связь хранится в отдельной пользовательской таблице (например, `user_tag_links` или универсальной таблице связей), где фиксируется, какой пользователь связан с каким тегом.
+   - Пример структуры таблицы связей:
+     | id | user_id | tag_id |
+     |----|---------|--------|
+     | 1  | 1       | 2      |
+     | 2  | 1       | 3      |
+
+4. **Обратная связь (теги → пользователи)**
+   - В таблице "Теги клиентов" можно реализовать обратную связь: для каждого тега показывать список пользователей, у которых он установлен (например, через relation/lookup-столбец).
+
+5. **Итог:**
+   - Пользователь может создавать и редактировать теги.
+   - Для каждого контакта можно выбрать теги из выпадающего списка.
+   - Все связи между пользователями и тегами хранятся в отдельной таблице.
+   - Можно быстро получить список всех пользователей с определённым тегом и наоборот.