ййй

2026-03-27 15:51:10 +03:00
parent 15586f9a8c
commit 0bff171936
1245 changed files with 99621 additions and 543076 deletions
@@ -0,0 +1,166 @@
+---
+id: api-rag-session-create
+title: Создание RAG-сессии и запуск snapshot-индексации
+doc_type: api_method
+domain: rag
+status: draft
+owner: system-analyst
+source_of_truth: code
+related_docs:
+  - arch-rag-package
+  - logic-rag-indexing
+  - entity-rag-session
+  - entity-rag-index-job
+related_code:
+  - src/app/modules/rag/module.py
+  - src/app/schemas/rag_sessions.py
+  - src/app/schemas/indexing.py
+entities:
+  - RagSession
+  - IndexJob
+tags:
+  - rag
+  - api
+  - session
+  - snapshot
+---
+# Создание RAG-сессии и запуск snapshot-индексации
+
+## Summary
+- Purpose: создать новую `RagSession` и асинхронно поставить полную индексацию snapshot-файлов.
+- Actor: внешний клиент модуля RAG.
+- Trigger: первичная загрузка файлов проекта в индекс.
+- Endpoint: `POST /api/rag/sessions`
+- Main entities: `RagSession`, `IndexJob`.
+- Main logic: создание UUID-сессии, постановка snapshot job, возврат идентификаторов сессии и job.
+- Main errors: в коде endpoint нет собственной бизнес-валидации сверх pydantic; ошибки индексации проявляются позже в job status.
+- Source of truth: `src/app/modules/rag/module.py`, `src/app/schemas/rag_sessions.py`.
+
+## Назначение
+
+Метод открывает новую RAG-сессию и запускает первичную индексацию файлов. Он используется как основной публичный вход для нового API пакета `rag`.
+
+## Контекст
+
+В отличие от legacy `/api/index/snapshot`, этот endpoint всегда создаёт новый `rag_session_id`, что позволяет независимо хранить несколько снимков одного проекта.
+
+## Технический use case
+
+### Основной сценарий
+
+1. Клиент передаёт `project_id` и массив `files`.
+2. `RagSessionStore.create` создаёт новую запись в `rag_sessions`.
+3. `IndexingOrchestrator.enqueue_snapshot` создаёт `IndexJob` и запускает фоновую обработку.
+4. API сразу возвращает `rag_session_id`, `index_job_id` и стартовый статус.
+
+### Альтернативные ветки
+
+- Если часть файлов не подлежит индексации, они будут отфильтрованы уже внутри indexing pipeline, а не на этапе ответа API.
+- Ошибки индексации не меняют синхронный ответ create endpoint, а отражаются в последующем статусе job.
+
+## Функциональные требования
+
+### Request validation
+- `project_id` обязателен и не может быть пустым.
+- `files` передаются списком объектов `FileSnapshot`.
+- Для каждого файла обязательны `path`, `content`, `content_hash`.
+
+### Processing rules
+- На каждый вызов создаётся новая `RagSession`.
+- Snapshot job создаётся сразу после сохранения сессии.
+- Ответ не ждёт завершения индексации.
+
+### State changes
+- В `rag_sessions` появляется новая запись.
+- В `rag_index_jobs` появляется новая запись в статусе `queued`.
+
+### Side effects
+- Запуск фоновой `asyncio` task.
+- Последующая публикация progress events в EventBus.
+
+## Contract
+
+### Endpoint
+- Method: `POST`
+- Path: `/api/rag/sessions`
+- Auth: определяется внешним слоем приложения, внутри endpoint не задана.
+- Idempotent: нет.
+- Timeout: короткий, так как endpoint не ждёт индексацию.
+- Retry: допустим только на стороне клиента с пониманием, что будет создана новая сессия.
+
+### Request
+| Field | Type | Required | Constraints | Description |
+|------|------|----------|-------------|-------------|
+| `project_id` | `string` | yes | `min_length=1` | идентификатор проекта |
+| `files` | `array<FileSnapshot>` | yes | может быть пустым, но схема обязана соблюдаться | snapshot файлов для первичной индексации |
+| `files[].path` | `string` | yes | `min_length=1` | путь файла |
+| `files[].content` | `string` | yes | без дополнительных ограничений | содержимое файла |
+| `files[].content_hash` | `string` | yes | `min_length=1` | hash содержимого для cache reuse |
+
+### Response
+| Field | Type | Description |
+|------|------|-------------|
+| `rag_session_id` | `string` | идентификатор созданной сессии |
+| `index_job_id` | `string` | идентификатор фоновой задачи индексации |
+| `status` | `IndexJobStatus` | стартовый статус задачи, обычно `queued` |
+
+### External contract refs
+- OpenAPI: формируется FastAPI по `response_model=RagSessionCreateResponse`.
+- Schema: `RagSessionCreateRequest`, `RagSessionCreateResponse`.
+- DTO / serializer: `src/app/schemas/rag_sessions.py`, `src/app/schemas/indexing.py`.
+- Additional refs: `logic-rag-indexing`.
+
+## Errors
+
+| error_id | http_code | when | client_behavior | retry |
+|----------|-----------|------|-----------------|-------|
+| `validation_error` | `422` | нарушена pydantic-схема request | исправить payload | no |
+
+## Нефункциональные требования
+
+### Security
+- Авторизация и аутентификация находятся вне этого метода.
+
+### Observability
+- Logs: прямое логирование в endpoint отсутствует.
+- Metrics: отдельные API-метрики не выделены.
+- Traces: отсутствуют.
+- Audit: факт вызова материализуется через `RagSession` и `IndexJob`.
+
+### Reliability
+- Даже при дальнейшей ошибке индексации клиент может получить статус через job endpoint.
+- Фоновая задача создаётся немедленно после ответа.
+
+### Performance
+- Время ответа не зависит от размера snapshot, кроме времени сериализации request.
+
+## Связанные блоки логики
+- `logic-rag-indexing`
+
+## Связанные сущности
+- `RagSession`
+- `IndexJob`
+
+## Связанный код
+
+### Files
+- `src/app/modules/rag/module.py`
+- `src/app/schemas/rag_sessions.py`
+- `src/app/schemas/indexing.py`
+
+### Symbols
+- `RagModule.public_router.create_rag_session`
+- `RagSessionStore.create`
+- `IndexingOrchestrator.enqueue_snapshot`
+
+## Связанные документы
+- `arch-rag-package`
+- `logic-rag-indexing`
+- `entity-rag-session`
+- `entity-rag-index-job`
+
+## История изменений
+
+| Date | Source | Changes |
+|------|--------|---------|
+| 2026-03-13 | code | Задокументирован публичный endpoint создания RAG-сессии. |