# Модуль rag_repo

## 1. Функции модуля
- Прием webhook-событий от Git-провайдеров (`gitea`, `bitbucket`).
- Нормализация payload в единый формат.
- Определение `story_id` и фиксация контекста, необходимого для определения изменений, произведенных в Story.
- Запись контекста коммита в Story-хранилище через `StoryContextRepository`.
- Подготовка данных, которые позволяют ускорять формирование чанков в `rag_session` за счет кэш-переиспользования.

Ускорение `rag_session` обеспечивается связкой полей:
- `project_id` (идентификатор репозитория/проекта),
- `commit_sha` (снимок состояния),
- `changed_files` (точный набор затронутых файлов),
- `story_id` (бизнес-контекст инкремента).

Эта связка позволяет в `rag_session` выполнять delta-индексацию и переиспользовать ранее рассчитанные чанки/эмбеддинги для неизмененных файлов.

## 2. Диаграмма классов и взаимосвязей
```mermaid
classDiagram
    class RagRepoModule
    class RepoWebhookService
    class StoryContextRepository

    RagRepoModule --> RepoWebhookService
    RepoWebhookService --> StoryContextRepository
```

## 3. Описание классов
- `RagRepoModule`: точка входа модуля и публикация webhook endpoint'а.
  Методы: `__init__` — создает сервис обработки webhook; `internal_router` — регистрирует internal route `webhook`.
- `RepoWebhookService`: нормализует payload, извлекает `story_id` и формирует запись commit-контекста.
  Методы: `process` — основной обработчик webhook; `_normalize_gitea` — маппинг payload Gitea; `_normalize_bitbucket` — маппинг payload Bitbucket; `_extract_story_id` — извлечение `story_id` из commit message.
- `StoryContextRepository`: persistence-слой Story-контекста.
  Методы: `record_story_commit` — сохраняет commit, ветку и список измененных файлов в контекст Story.

## 4. Сиквенс-диаграммы API

### POST /internal/rag-repo/webhook
Назначение: принимает webhook коммита, автоматически определяет провайдера (`gitea`/`bitbucket`), извлекает `story_id` и сохраняет commit-контекст для трассировки изменений по Story.
```mermaid
sequenceDiagram
    participant Router as RagRepoModule.APIRouter
    participant Webhook as RepoWebhookService
    participant StoryRepo as StoryContextRepository

    Router->>Webhook: process(payload, headers)
    Webhook->>Webhook: normalize payload + extract story_id
    alt story_id found
        Webhook->>StoryRepo: record_story_commit(...)
        StoryRepo-->>Webhook: ok
    else story_id missing
        Webhook-->>Router: accepted, story_bound=false
    end
    Webhook-->>Router: result
```