144 lines
6.2 KiB
Markdown
144 lines
6.2 KiB
Markdown
---
|
||
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` и её роли в границах индекса. |
|