первый коммит

app/modules/rag_repo/README.md

@@ -0,0 +1,56 @@
+# Модуль 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
+```