---
id: entity-rag-session
title: Сущность RagSession
doc_type: domain_entity
domain: rag
status: draft
owner: system-analyst
source_of_truth: code
related_docs:
  - arch-rag-package
  - logic-rag-indexing
  - api-rag-session-create
  - api-rag-session-changes
  - api-rag-session-job
related_code:
  - src/app/modules/rag/session_store.py
  - src/app/modules/rag/persistence/session_repository.py
  - src/app/modules/rag/persistence/schema_repository.py
entities:
  - RagSession
tags:
  - rag
  - session
  - domain-entity
---
# Сущность RagSession

## Summary
- Domain: rag
- Purpose: связать индекс и связанные job с конкретным проектом или его рабочим снимком.
- Entity role: корневая сущность области RAG indexing/retrieval.
- Main attributes: `rag_session_id`, `project_id`, `created_at`.
- Lifecycle: создаётся до первой индексации и используется как scope всех retrieval-запросов.
- Invariants: `rag_session_id` уникален, `project_id` обязателен.
- Related APIs: `POST /api/rag/sessions`, `POST /api/rag/sessions/{rag_session_id}/changes`, `GET /api/rag/sessions/{rag_session_id}/jobs/{index_job_id}`.
- Related logic: snapshot indexing, change indexing, retrieval filtering.
- Source of truth: `src/app/modules/rag/session_store.py`, таблица `rag_sessions`.

## Назначение

`RagSession` определяет границу индекса для проекта. Все документы, задачи и retrieval-запросы внутри `rag` привязаны к этой сущности.

## Контекст

Сессия используется и в новом API с UUID, и в legacy/internal режиме, где `project_id` может совпадать с `rag_session_id`. Через неё сервис восстанавливает `repo_id`, который затем участвует в кэшировании документов.

## Роль в доменной модели

`RagSession` является владельцем набора индексированных документов и асинхронных `IndexJob`. Без неё нельзя безопасно выполнять reindex или retrieval, потому что именно она задаёт scope таблицы `rag_chunks`.

## Атрибуты

| attribute | type | required | description | constraints |
|-----------|------|----------|-------------|-------------|
| `rag_session_id` | `str` | yes | уникальный идентификатор сессии | primary key, non-empty |
| `project_id` | `str` | yes | идентификатор проекта или workspace | non-empty |
| `created_at` | `timestamp with time zone` | yes | время создания записи в БД | default `CURRENT_TIMESTAMP` |

## Состояния и жизненный цикл

### Основные состояния
- created
- active
- reused via legacy/internal API

### Переходы состояний
1. `RagSessionStore.create(project_id)` создаёт новую сессию с UUID.
2. `RagSessionStore.put(rag_session_id, project_id)` создаёт или обновляет сессию с заданным ключом.
3. После создания сессия используется для indexing и retrieval до тех пор, пока не будет заменена новым идентификатором на уровне вызывающего сервиса.

## Инварианты и ограничения

- `project_id` не должен быть пустым.
- Для retrieval и indexing используется только один `rag_session_id` за операцию.
- `RagService._resolve_repo_id` использует `project_id` этой сущности как `repo_id` для cache scope.

## Связи с другими сущностями

| entity | relation | description |
|--------|----------|-------------|
| `IndexJob` | one-to-many | одна сессия может иметь много задач индексации |
| `RagDocument` | one-to-many | все записи в `rag_chunks` привязаны к одной сессии |

## Использование в системе

### Related API
- `POST /api/rag/sessions`
- `POST /api/rag/sessions/{rag_session_id}/changes`
- `GET /api/rag/sessions/{rag_session_id}/jobs/{index_job_id}`

### Related UI
- Прямого UI в репозитории не обнаружено.

### Related logic
- `logic-rag-indexing`
- `logic-rag-retrieval`

### Related integrations
- PostgreSQL таблица `rag_sessions`

## Функциональные требования

- Сессия должна создаваться до постановки snapshot job.
- При change indexing запрос должен ссылаться на существующую сессию в новом публичном API.
- Legacy/internal API может создавать запись с предсказуемым `rag_session_id`, равным `project_id`.

## Нефункциональные требования

### Audit / history
- Время создания фиксируется в таблице `rag_sessions`.

### Security
- Отдельных прав доступа на уровне сущности внутри модуля нет.

### Observability
- Основная наблюдаемость сессии идёт через связанные `IndexJob`.

## Связанный код

### Files
- `src/app/modules/rag/session_store.py`
- `src/app/modules/rag/persistence/session_repository.py`
- `src/app/modules/rag/persistence/schema_repository.py`

### Symbols
- `RagSession`
- `RagSessionStore.create`
- `RagSessionStore.put`
- `RagSessionStore.get`

## Связанные документы

- `arch-rag-package`
- `logic-rag-indexing`
- `api-rag-session-create`
- `api-rag-session-changes`
- `api-rag-session-job`

## История изменений

| Date | Source | Changes |
|------|--------|---------|
| 2026-03-13 | code | Добавлено описание сущности `RagSession` и её роли в границах индекса. |