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