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

2026-02-27 21:28:09 +03:00
parent 1e376aff24
commit e8805ffe29
171 changed files with 6400 additions and 556 deletions
--- a/README.ARCH.md
+++ b/README.ARCH.md
@@ -0,0 +1,155 @@
+# Архитектура приложения
+
+Документ описывает модульную архитектуру backend-приложения, связи между модулями и контрактные границы.
+
+## 1. Диаграмма модулей и взаимосвязей
+
+```mermaid
+flowchart LR
+    UI["Клиент / Frontend"] --> API["FastAPI (app/main.py)"]
+
+    API --> CHAT["chat модуль"]
+    API --> RAG["rag модуль"]
+    API --> AGENT_INTERNAL["internal tools API"]
+
+    CHAT -->|AgentRunner| AGENT["agent модуль"]
+    AGENT -->|RagRetriever| RAG
+    AGENT --> DB[(PostgreSQL + pgvector)]
+    CHAT --> DB
+    RAG --> DB
+
+    AGENT --> GIGA["GigaChat API"]
+    RAG --> GIGA
+
+    AGENT_INTERNAL --> AGENT
+
+    APP["ModularApplication\n(app/modules/application.py)"] --> CHAT
+    APP --> AGENT
+    APP --> RAG
+```
+
+### Внутренние слои `agent`
+
+```mermaid
+flowchart TB
+    ROUTER["Router\n(intent + context)"] --> ORCH["Orchestrator\n(task spec + plan + execution + quality)"]
+    ORCH --> GRAPHS["Action Graphs\nLangGraph"]
+
+    ORCH --> METRICS["Quality Metrics\n(faithfulness/coverage)"]
+    METRICS --> DB[(agent_quality_metrics)]
+```
+
+## 2. Описание модулей
+
+### Модуль `app/modules/chat`
+
+- Цель: принять пользовательский запрос, управлять задачей обработки, отдать результат и прогресс.
+- Кратко о реализации:
+  - `ChatModule` публикует HTTP API (`/api/chat/*`, `/api/tasks/*`, `/api/events`).
+  - `ChatOrchestrator` запускает обработку асинхронной задачи, публикует SSE-события, обрабатывает retry и ошибки.
+  - `TaskStore`, `DialogSessionStore`, `IdempotencyStore` держат состояние задач/диалогов.
+- С кем взаимодействует:
+  - с `agent` через контракт `AgentRunner`.
+  - с `rag` для проверки `rag_session_id`.
+  - с `shared/event_bus` для стриминга прогресса.
+  - с БД через `ChatRepository` (`dialog_sessions`, `chat_messages`).
+- Контракты:
+  - потребляет `AgentRunner.run(...)` из `app/modules/contracts.py`.
+
+### Модуль `app/modules/agent`
+
+- Цель: интеллектуальная обработка запроса, маршрутизация, оркестрация сценария, генерация ответа/changeset.
+- Кратко о реализации:
+  - `GraphAgentRuntime` выполняет pipeline: route -> task spec -> orchestrator -> post-processing.
+  - Router (`engine/router/*`) выбирает `domain/process` и хранит routing-context.
+  - Orchestrator (`engine/orchestrator/*`) строит и валидирует plan, исполняет шаги, запускает графовые/функциональные actions.
+  - Graphs (`engine/graphs/*`) выполняют целевые действия (QA, edits, docs).
+  - Рассчитывает quality-метрики (`faithfulness`, `coverage`) и сохраняет их в БД.
+  - Поддерживает внутренний инструмент получения страниц Confluence (`/internal/tools/confluence/fetch`).
+- С кем взаимодействует:
+  - с `rag` через контракт `RagRetriever`.
+  - с `shared/checkpointer` (LangGraph checkpoints в PostgreSQL).
+  - с GigaChat (LLM-запросы, промпты).
+  - с БД через `AgentRepository` (`router_context`, `agent_quality_metrics`).
+- Контракты:
+  - реализует `AgentRunner` (используется `chat`).
+  - потребляет `RagRetriever` (реализуется `rag`).
+
+### Модуль `app/modules/rag`
+
+- Цель: индексация проектных файлов и retrieval релевантного контекста.
+- Кратко о реализации:
+  - API для snapshot/changes индексации и retrieval.
+  - Индексация хранит чанки, эмбеддинги и состояние job.
+  - Retrieval ищет релевантные куски в `rag_chunks` (pgvector).
+- С кем взаимодействует:
+  - с `agent` (выдача контекста через `RagRetriever`).
+  - с БД (`rag_sessions`, `rag_chunks`, `rag_index_jobs`).
+  - с GigaChat Embeddings.
+- Контракты:
+  - реализует `RagRetriever` и `RagIndexer` из `app/modules/contracts.py`.
+
+### Модуль `app/modules/shared`
+
+- Цель: общие инфраструктурные компоненты, переиспользуемые всеми модулями.
+- Кратко о реализации:
+  - `db.py`: engine/session factory.
+  - `event_bus.py`: pub/sub для SSE.
+  - `retry_executor.py`: общий retry.
+  - `checkpointer.py`: PostgresSaver для LangGraph.
+  - `bootstrap.py`: инициализация схем БД на старте.
+- С кем взаимодействует:
+  - со всеми бизнес-модулями (`chat`, `agent`, `rag`).
+- Контракты:
+  - внутренние инфраструктурные API без отдельного публичного контракта уровня `contracts.py`.
+
+### Модуль `app/modules/contracts.py`
+
+- Цель: зафиксировать межмодульные интерфейсы и отделить реализацию от потребителей.
+- Кратко о реализации:
+  - `AgentRunner`, `RagRetriever`, `RagIndexer` определены как `Protocol`.
+- С кем взаимодействует:
+  - используется `chat` (как потребитель `AgentRunner`), `agent` (как потребитель `RagRetriever`), `rag` (как реализация `RagRetriever`/`RagIndexer`).
+- Контракты:
+  - это и есть контрактный слой.
+
+### Модуль композиции `app/modules/application.py`
+
+- Цель: централизованный wiring зависимостей.
+- Кратко о реализации:
+  - `ModularApplication` создаёт `EventBus`, `RetryExecutor`, репозитории и модули.
+  - На `startup()` выполняет bootstrap БД.
+- С кем взаимодействует:
+  - со всеми модулями, но не содержит бизнес-логики.
+- Контракты:
+  - использует `contracts.py` для сборки зависимостей без жёсткого сцепления по реализациям.
+
+## 3. Ключевые контрактные границы
+
+- `chat -> agent`: только через `AgentRunner`.
+- `agent -> rag`: только через `RagRetriever`.
+- `rag`: не зависит от `agent` internals.
+- `application.py`: единственная точка связывания реализаций.
+
+## 4. Схема данных (кратко)
+
+- `chat`: `dialog_sessions`, `chat_messages`.
+- `rag`: `rag_sessions`, `rag_chunks`, `rag_index_jobs`.
+- `agent`:
+  - `router_context` — контекст маршрутизации по диалогу.
+  - `agent_quality_metrics` — пер-сценарные quality-метрики для отчетности:
+    - `faithfulness_score`, `coverage_score`, `quality_status`, `metrics_json`, `created_at`.
+  - `story_records` — карточка Story (статус, владелец, метаданные).
+  - `story_artifacts` — артефакты по Story (analytics/doc_increment/test_model и версии).
+  - `story_links` — внешние связи Story (тикеты, документы, URL).
+
+## 5. Поток обработки запроса
+
+1. Пользователь отправляет сообщение в `chat`.
+2. `chat` создаёт task и вызывает `AgentRunner.run(...)`.
+3. `agent/router` выбирает маршрут (domain/process).
+4. `agent/orchestrator` строит `TaskSpec` и `ExecutionPlan`.
+5. Выполняются шаги плана (function/actions/graph steps).
+6. Формируется `answer` или `changeset`.
+7. Считаются `faithfulness/coverage`, сохраняются в `agent_quality_metrics`.
+8. `chat` возвращает результат и стримит прогресс через SSE.