<!--
  Copyright (c) 2024-2025 Тарабанов Александр Викторович
  All rights reserved.
  
  This software is proprietary and confidential.
  Unauthorized copying, modification, or distribution is prohibited.
  
  For licensing inquiries: info@hb3-accelerator.com
  Website: https://hb3-accelerator.com
  GitHub: https://github.com/HB3-ACCELERATOR
-->

# Техническое задание: Пользовательские таблицы с настраиваемыми связями

## Цель
Реализовать систему пользовательских таблиц, в которых при создании столбца можно настраивать нужные связи (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. **Итог:**
   - Пользователь может создавать и редактировать теги.
   - Для каждого контакта можно выбрать теги из выпадающего списка.
   - Все связи между пользователями и тегами хранятся в отдельной таблице.
   - Можно быстро получить список всех пользователей с определённым тегом и наоборот. 