From 47243b9f163183eb3e1e216b134e240bd02a236a Mon Sep 17 00:00:00 2001 From: cherninkiy Date: Wed, 13 May 2026 14:25:58 +0300 Subject: [PATCH 01/19] feat(worker): migrate to .NET 10 and install Microsoft.Agents.AI - update all projects TargetFramework from net8.0 to net10.0 - add Microsoft.Agents.AI 1.5.0 package to Worker - add Microsoft.Agents.AI.Abstractions 1.5.0 package to Shared - update Microsoft.EntityFrameworkCore to 10.0.* across all projects - update Microsoft.Extensions.Diagnostics.HealthChecks to 10.0.* - update Microsoft.Extensions.Hosting to 10.0.* - update Npgsql.EntityFrameworkCore.PostgreSQL to 10.0.* - update Microsoft.AspNetCore.OpenApi to 10.0.* (replaces Swashbuckle) - update Microsoft.AspNetCore.Mvc.Testing to 10.0.* in test projects - update Microsoft.EntityFrameworkCore.InMemory to 10.0.* - update Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore to 10.0.* - replace Swashbuckle.AspNetCore with Scalar.AspNetCore 2.14.11 - replace AddSwaggerGen() with AddOpenApi() in Program.cs - replace UseSwagger()/UseSwaggerUI() with MapOpenApi()/MapScalarApiReference() - add using Scalar.AspNetCore to Program.cs - update EFCore.NamingConventions from 8.0.3 to 10.0.1 - fix CS8625 warning in DocumentProcessingServiceTests (null literal) - fix CS8604 warning in DocumentProcessingServiceTests (possible null reference) - remove redundant System.Text.Json package from IntegrationTests - remove redundant Microsoft.Extensions.Diagnostics.HealthChecks from ApiGateway --- docs/AGENTIC_READINESS.md | 35 +++ docs/AGENTIC_ROADMAP.md | 248 ++++++++++++++++++ src/ApiGateway/ApiGateway.csproj | 17 +- src/ApiGateway/Program.cs | 17 +- src/Shared/Shared.csproj | 3 +- src/Worker/Worker.csproj | 13 +- .../ApiGateway.UnitTests.csproj | 10 +- .../IntegrationTests/IntegrationTests.csproj | 5 +- .../DocumentProcessingServiceTests.cs | 5 +- .../Worker.UnitTests/Worker.UnitTests.csproj | 6 +- 10 files changed, 323 insertions(+), 36 deletions(-) create mode 100644 docs/AGENTIC_READINESS.md create mode 100644 docs/AGENTIC_ROADMAP.md diff --git a/docs/AGENTIC_READINESS.md b/docs/AGENTIC_READINESS.md new file mode 100644 index 0000000..42e46b8 --- /dev/null +++ b/docs/AGENTIC_READINESS.md @@ -0,0 +1,35 @@ +# Agentic Readiness Report + +## Статус: в процессе + +## Результат миграции + +> Заполнить после завершения + +## Архитектура + +> Описать финальную архитектуру + +## Особенности миграции на .NET 10 + MAF + +### Проблема совместимости пакетов + +При переходе с `net8.0` на `net10.0` обнаружена несовместимость версий NuGet-пакетов: + +- **MassTransit 8.5.9** объявляет зависимость от `Microsoft.Extensions.Diagnostics.HealthChecks (>= 10.0.0)` для .NET 10 +- В проектах было `Version="8.0.*"` — это вызывало `NU1605: Detected package downgrade` +- **Решение**: обновить все пакеты `Microsoft.Extensions.*` и `Microsoft.EntityFrameworkCore.*` до версий 10.x + +> Подробности заполнить после завершения + +### Миграция на Microsoft Agent Framework + +> Описать ключевые решения и особенности + +## Пример: создание нового агента (TranslationAgent) + +> Пример кода и инструкция + +## Метрики + +> До/после миграции \ No newline at end of file diff --git a/docs/AGENTIC_ROADMAP.md b/docs/AGENTIC_ROADMAP.md new file mode 100644 index 0000000..b59f429 --- /dev/null +++ b/docs/AGENTIC_ROADMAP.md @@ -0,0 +1,248 @@ +# Переход на Microsoft Agent Framework (MAF) + +## Цель + +Миграция воркера с линейной обработки PDF на **оркестрируемый workflow** с чекпоинтами через Microsoft Agent Framework. Архитектура должна позволять легко добавлять новых агентов (перевод, NER, суммаризация) без изменения ядра. + +## Требования + +- **.NET SDK**: 10.0 (уже установлено: 10.0.107) +- **MAF пакет**: `Microsoft.Agents.AI` 1.5.0 +- **Чекпоинты**: PostgreSQL (EF Core) +- **Шаги workflow**: + - `DownloadDocument` — скачивание файла из storage + - `ParseDocument` — извлечение текста через PdfPig + - `ExtractText` — OCR fallback через Tesseract + - `SaveResult` — сохранение текста в БД + - `UpdateStatus` — обновление статуса документа +- **Масштабируемость**: архитектура должна позволять легко добавлять новых агентов + +## Архитектура + +### Текущая архитектура (MVP) + +``` +MassTransit Consumer → DocumentProcessingService → PdfTextExtractor → TesseractOcrService + ↓ + Repository (PostgreSQL) +``` + +Линейная цепочка вызовов. При падении воркера — полный рестарт с нуля. + +### Целевая архитектура (Agentic) + +``` +┌─────────────────────────────────────────────────────────────┐ +│ MassTransit Consumer │ +│ (приём сообщений из RabbitMQ, retry/DLQ — без изменений) │ +└──────────────────────────┬──────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ DocumentProcessingAgent (MAF) │ +│ │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ Download │──▶│ Parse │──▶│ Extract │ │ +│ │ Document │ │ Document │ │ Text │ │ +│ └──────────────┘ └──────────────┘ └──────────────┘ │ +│ │ checkpoint │ checkpoint │ checkpoint │ +│ ▼ ▼ ▼ │ +│ ┌──────────────┐ ┌──────────────┐ │ +│ │ Save │──▶│ Update │ │ +│ │ Result │ │ Status │ │ +│ └──────────────┘ └──────────────┘ │ +│ │ checkpoint │ checkpoint │ +└─────────────────────────────────────────────────────────────┘ + │ + ▼ + ┌────────────────────────┐ + │ CheckpointStore │ + │ (PostgreSQL + EF Core)│ + └────────────────────────┘ +``` + +### Принцип работы чекпоинтов + +Каждый шаг MAF-агента сохраняет своё состояние в `workflow_checkpoints` таблицу PostgreSQL. Если воркер упадёт после `ParseDocument`, при рестарте агент продолжит с `ExtractText`, а не сначала. + +### Расширяемость для новых агентов + +Новый агент (например, перевод) добавляется как отдельный класс, реализующий общий интерфейс `IAgent`: + +```csharp +// Пример: агент перевода (не реализуем сейчас) +public class TranslationAgent : IAgent +{ + public string AgentName => "Translation"; + + public async Task ExecuteAsync( + AgentContext context, + CancellationToken cancellationToken) + { + // 1. Получить текст из предыдущего шага (SaveResult) + var text = context.GetPreviousResult("SaveResult"); + + // 2. Вызвать LLM или сервис перевода + var translated = await _translationService.TranslateAsync(text, context.TargetLanguage); + + // 3. Сохранить результат + return AgentResult.Success(translated); + } +} +``` + +Оркестратор может объединять агентов в pipeline: + +```csharp +// Пример pipeline: PDF → текст → перевод +var pipeline = agentOrchestrator + .AddAgent() // текущий агент + .AddAgent() // новый агент + .Build(); +``` + +## Этапы реализации + +### Этап 1: Миграция на .NET 10 и установка MAF + +- [ ] Обновить `Worker.csproj` на `net10.0` +- [ ] Обновить `ApiGateway.csproj` на `net10.0` +- [ ] Обновить `Shared.csproj` на `net10.0` +- [ ] Обновить тестовые проекты на `net10.0` +- [ ] Установить `Microsoft.Agents.AI` 1.5.0 в Worker +- [ ] Установить `Microsoft.Agents.AI.Abstractions` в Shared +- [ ] Проверить что solution собирается + +**Коммит**: `feat(worker): migrate to .NET 10 and install Microsoft.Agents.AI` + +--- + +### Этап 2: Модели данных для чекпоинтов + +- [ ] Создать `WorkflowCheckpoint` модель в Shared +- [ ] Создать `AgentDefinition` модель в Shared +- [ ] Добавить `DbSet` в `AppDbContext` +- [ ] Добавить `DbSet` в `AppDbContext` +- [ ] Создать SQL миграцию для новых таблиц +- [ ] Обновить `db/init.sql` + +**Коммит**: `feat(shared): add workflow checkpoint and agent definition models` + +--- + +### Этап 3: Интерфейсы агентов + +- [ ] Создать `IAgent` интерфейс в Shared +- [ ] Создать `IAgentOrchestrator` интерфейс в Shared +- [ ] Создать `AgentContext` класс в Shared +- [ ] Создать `AgentResult` класс в Shared +- [ ] Создать `ICheckpointStore` интерфейс в Shared + +**Коммит**: `feat(shared): define agent abstractions (IAgent, IAgentOrchestrator, AgentContext)` + +--- + +### Этап 4: Реализация CheckpointStore (PostgreSQL) + +- [ ] Создать `PostgreSqlCheckpointStore` в Worker +- [ ] Реализовать `SaveCheckpointAsync` +- [ ] Реализовать `LoadCheckpointAsync` +- [ ] Реализовать `DeleteCheckpointAsync` +- [ ] Добавить регистрацию в DI + +**Коммит**: `feat(worker): implement PostgreSQL checkpoint store for MAF` + +--- + +### Этап 5: Реализация DocumentProcessingAgent + +- [ ] Создать класс `DocumentProcessingAgent` в Worker +- [ ] Реализовать `DownloadDocument` — скачивание из storage +- [ ] Реализовать `ParseDocument` — PdfPig извлечение +- [ ] Реализовать `ExtractText` — Tesseract OCR fallback +- [ ] Реализовать `SaveResult` — сохранение текста +- [ ] Реализовать `UpdateStatus` — обновление статуса +- [ ] Каждый шаг должен сохранять чекпоинт +- [ ] При старте — проверка существующего чекпоинта (resume) + +**Коммит**: `feat(worker): implement DocumentProcessingAgent with MAF checkpoints` + +--- + +### Этап 6: Рефакоринг PdfProcessingConsumer + +- [ ] Заменить вызов `DocumentProcessingService` на `DocumentProcessingAgent` +- [ ] Сохранить MassTransit retry/DLQ как базовую защиту +- [ ] Добавить логирование прогресса workflow +- [ ] Обработка ошибок — чекпоинты позволяют resume + +**Коммит**: `feat(worker): refactor consumer to use MAF DocumentProcessingAgent` + +--- + +### Этап 7: Обновление Program.cs и DI + +- [ ] Зарегистрировать `DocumentProcessingAgent` в DI +- [ ] Зарегистрировать `PostgreSqlCheckpointStore` в DI +- [ ] Обновить конфигурацию MAF +- [ ] Удалить старый `DocumentProcessingService` (или оставить для fallback) + +**Коммит**: `feat(worker): register MAF services in DI container` + +--- + +### Этап 8: Тесты + +- [ ] Создать `DocumentProcessingAgentTests` +- [ ] Тест `DownloadDocument` с mock storage +- [ ] Тест `ParseDocument` с тестовым PDF +- [ ] Тест `ExtractText` с mock OCR +- [ ] Тест `SaveResult` с in-memory DB +- [ ] Тест `UpdateStatus` с проверкой статуса +- [ ] Тест resume после checkpoint +- [ ] Обновить существующие тесты при необходимости + +**Коммит**: `test(worker): add DocumentProcessingAgent unit tests with checkpoint scenarios` + +--- + +### Этап 9: Документация и отчёт + +- [ ] Обновить `README.md` — описать новую архитектуру +- [ ] Создать `docs/AGENTIC_READINESS.md` — отчёт на русском +- [ ] Отметить все пункты в этом roadmap как выполненные +- [ ] Пример создания нового агента (перевод) в документации + +**Коммит**: `docs: add agentic architecture documentation and readiness report` + +--- + +## Формат коммитов + +Используется формат из `.gitmessage.txt`: + +``` +(): + + + +