agent/app/modules/rag_repo

Модуль 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. Диаграмма классов и взаимосвязей

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.

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