Core Tables

Базовые таблицы для хранения пользователей, чатов и сообщений. Фундамент всей системы.

Связи и зависимости

Предыдущие шаги: Schema Overview

Следующие шаги: Process Tables, Agent Tables

Необходимые навыки: SQL basics, PostgreSQL, Foreign Keys

ER-диаграмма Core Domain

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│     users       │     │     chats       │     │    groups       │
├─────────────────┤     ├─────────────────┤     ├─────────────────┤
│ id (PK)         │◄────│ user_id (FK)    │     │ id (PK)         │
│ telegram_user_id│     │ group_id (FK)   │────►│ telegram_group_id│
│ username        │     │ telegram_chat_id│     │ group_type      │
│ first_name      │     │ chat_type       │     │ title           │
│ last_name       │     │ title           │     │ is_active       │
│ is_bot          │     └────────┬────────┘     └─────────────────┘
│ is_blocked      │              │
│ metadata        │              │
└─────────────────┘              │
                                 ▼
                    ┌─────────────────────┐
                    │     messages        │
                    ├─────────────────────┤
                    │ id (PK)             │
                    │ chat_id (FK)        │
                    │ telegram_message_id │
                    │ user_id (FK)        │
                    │ process_id (FK)     │
                    │ role (enum)         │
                    │ text                │
                    │ payload (jsonb)     │
                    │ model               │
                    │ prompt_tokens       │
                    │ completion_tokens   │
                    │ latency_ms          │
                    │ created_at          │
                    └─────────────────────┘

users — Пользователи

Хранит информацию о Telegram пользователях. Создаётся при первом взаимодействии.

Поле	Тип	Описание
id	bigint (PK)	Внутренний ID
telegram_user_id	bigint (UNIQUE)	Telegram User ID
username	text	@username (может быть null)
is_bot	boolean	Является ли ботом
is_blocked	boolean	Заблокировал ли пользователь бота
metadata	jsonb	Расширенные данные (язык, настройки)

chats — Чаты

Универсальная таблица для всех типов чатов. Связывает users (private) или groups (group/supergroup).

Поле	Тип	Описание
chat_type	enum	private \| group \| supergroup \| channel
user_id	bigint (FK)	Для private чатов
group_id	bigint (FK)	Для group/supergroup

CONSTRAINT: chats_entity_coherence — гарантирует что private чат имеет user_id, а group чат имеет group_id.

messages — Сообщения

Все сообщения в системе: от пользователей, бота, system prompts. Содержит метрики LLM вызовов.

Поле	Тип	Описание
role	enum	user \| assistant \| system \| tool
text	text	Текст сообщения
payload	jsonb	Структурированные данные (кнопки, media)
process_id	uuid (FK)	Связь с процессом (если применимо)
model	text	Модель LLM (для assistant сообщений)
prompt_tokens	integer	Tokens в запросе
completion_tokens	integer	Tokens в ответе
latency_ms	integer	Время ответа LLM в ms

Типичные запросы

Последние N сообщений в чате:

SELECT m.*, u.username
FROM clowbot.messages m
JOIN clowbot.chats c ON c.id = m.chat_id
LEFT JOIN clowbot.users u ON u.id = m.user_id
WHERE c.telegram_chat_id = $1
ORDER BY m.created_at DESC
LIMIT 20;

Статистика пользователя:

SELECT * FROM mart.vw_users 
WHERE telegram_user_id = $1;

Найти или создать пользователя:

INSERT INTO clowbot.users (telegram_user_id, username, first_name)
VALUES ($1, $2, $3)
ON CONFLICT (telegram_user_id) DO UPDATE SET
  username = EXCLUDED.username,
  first_name = EXCLUDED.first_name,
  updated_at = now()
RETURNING *;

Indexes

idx_messages_chat_created_at — (chat_id, created_at DESC) — быстрая выборка истории чата

idx_messages_user_created_at — (user_id, created_at DESC) — быстрая выборка по пользователю

idx_messages_process_created_at — (process_id, created_at DESC) — сообщения процесса

idx_messages_payload_gin — GIN индекс для JSONB запросов

Marts (Views)

mart.vw_users

Агрегированная статистика пользователей: количество сообщений, last_message_at

mart.vw_messages

Messages с JOIN к chats, users, processes — удобный read-only view

mart.vw_groups

Статистика групп: сообщения, активность

Что делать дальше

→ Process Tables — таблицы для процессов
→ Agent Tables — таблицы для агентов
→ Python Bridge — как Python работает с этими таблицами