Wedding Planner System

Система управления свадебными мероприятиями, построенная с использованием .NET 8, Clean Architecture и Domain-Driven Design (DDD).

Доменная область

Wedding Planner - это система для управления свадебными мероприятиями, которая позволяет:

• Парам (Couples) планировать свои свадьбы, управлять бюджетом, гостями и задачами
• Поставщикам услуг (Vendors) предоставлять свои услуги (фотографы, видеографы, флористы, кейтеринг и т.д.)
• Администраторам управлять системой и пользователями

Основные доменные сущности

1. Couple (Aggregate Root) - пара, планирующая свадьбу
2. Wedding (Aggregate Root) - свадебное мероприятие с интегрированными задачами
3. Vendor - поставщик услуг
4. Guest - гость на свадьбе
5. Task (Entity) - задача в рамках планирования свадьбы (часть агрегата Wedding)

Типы пользователей

• Admin - администратор системы
• Bride/Groom - невеста/жених
• Vendors - различные типы поставщиков услуг:
  • Photographer, Videographer, Florist, Caterer
  • WeddingPlanner, Musician, DJ, Decorator
  • MakeupArtist, Hairstylist, WeddingOfficiant
  • BridalShop, Venue, Baker, Jeweler, Transportation

Архитектура

Проект следует принципам Clean Architecture с четким разделением на слои:

src/
├── WeddingPlanner.Domain/           # Доменный слой
├── WeddingPlanner.Application/      # Слой приложения
├── WeddingPlanner.Infrastructure/   # Инфраструктурный слой
└── Gateways/WeddingPlanner.API/    # Слой представления (REST API)

Domain Layer (Доменный слой)

• Entities - доменные сущности с бизнес-логикой
• Value Objects - объекты-значения (Email, PhoneNumber)
• Enums - перечисления доменных концепций
• Events - доменные события
• Common - базовые абстракции (BaseEntity, AggregateRoot, IAggregateRoot)

Паттерны DDD:

• Aggregate Root - корневые агрегаты (Couple, Wedding)
• Proper Aggregate Boundaries - Task интегрирован в Wedding агрегат
• Domain Events - события домена управляются aggregate root
• Value Objects - Email, PhoneNumber с валидацией
• Rich Domain Model - сущности с бизнес-логикой

Application Layer (Слой приложения)

• Interfaces - абстракции репозиториев и сервисов
• UseCases - сценарии использования
• DTOs - объекты передачи данных
• Auth - команды и обработчики аутентификации
• Identity - пользователи системы (ApplicationUser, ApplicationRole)
• Services - интерфейсы сервисов
• EventHandlers - обработчики доменных событий

Паттерны:

• CQRS с использованием MediatR
• Repository Pattern - абстракции репозиториев
• Command/Query Separation - разделение команд и запросов
• Domain Event Handlers - обработка доменных событий через MediatR

Infrastructure Layer (Инфраструктурный слой)

• Persistence - Entity Framework Core, DbContext
• Repositories - реализации репозиториев
• Services - внешние сервисы (OAuth, JWT, Email)
• Configuration - настройка DI контейнера

API Layer (Слой представления)

• Controllers - REST API контроллеры
• Middleware - промежуточное ПО
• Configuration - настройка приложения

Используемые технологии и библиотеки

Core

• .NET 8 - основная платформа
• Entity Framework Core 8.0.8 - ORM для работы с базой данных
• ASP.NET Core Identity 8.0.8 - система аутентификации и авторизации

Архитектурные паттерны

• MediatR 12.4.1 - реализация CQRS и Mediator pattern
• CSharpFunctionalExtensions 2.42.5 - функциональное программирование, Result pattern

Аутентификация и авторизация

• JWT Bearer Authentication - токены доступа
• OAuth 2.0 - интеграция с социальными сетями (Google, Facebook, Apple)
• Refresh Tokens - обновление токенов доступа

База данных

• PostgreSQL - основная СУБД (через Npgsql)
• Entity Framework Migrations - управление схемой БД

Архитектурное тестирование

• NetArchTest.Rules - автоматизированные архитектурные тесты
• FluentAssertions - улучшенные assertions для тестов
• xUnit - основной тестовый фреймворк

Структура проектов

WeddingPlanner.Domain

Common/
├── BaseEntity.cs           # Базовая сущность
├── AggregateRoot.cs       # Корень агрегата
├── IEntity.cs             # Интерфейс сущности
└── IAggregateRoot.cs      # Интерфейс корня агрегата

Entities/
├── Couple.cs              # Агрегат "Пара"
├── Wedding.cs             # Агрегат "Свадьба"
├── Vendor.cs              # Поставщик услуг
├── Guest.cs               # Гость  
└── Task/
    └── Task.cs            # Задача (Entity в составе Wedding агрегата)

ValueObjects/
├── Email.cs               # Email с валидацией
└── PhoneNumber.cs         # Телефон с валидацией

Events/
├── IDomainEvent.cs        # Интерфейс доменного события
├── BaseDomainEvent.cs     # Базовое доменное событие
├── CoupleCreatedEvent.cs  # Событие создания пары
├── WeddingCreatedEvent.cs # Событие создания свадьбы
├── InvitationAcceptedEvent.cs  # Событие принятия приглашения
├── InvitationDeclinedEvent.cs  # Событие отклонения приглашения
└── Task/                  # События задач
    ├── TaskCreatedEvent.cs      # Событие создания задачи
    ├── TaskStartedEvent.cs      # Событие начала задачи
    ├── TaskCompletedEvent.cs    # Событие завершения задачи
    ├── TaskCancelledEvent.cs    # Событие отмены задачи
    ├── TaskUpdatedEvent.cs      # Событие обновления задачи
    └── TaskStatusChangedEvent.cs # Событие изменения статуса задачи

Enums/                     # Доменные перечисления

WeddingPlanner.Application

Abstractions/
├── IRepository.cs         # Базовый репозиторий
├── ICoupleRepository.cs   # Репозиторий пар  
├── IWeddingRepository.cs  # Репозиторий свадеб (управляет Tasks)
├── IInvitationRepository.cs
├── ICoupleInvitationRepository.cs
├── IWeddingStyleRepository.cs
└── ITaskTemplateRepository.cs

Auth/Commands/             # CQRS команды аутентификации
├── RegisterUser/
├── LoginUser/
├── RefreshToken/
└── OAuthLogin/

UseCases/                  # Сценарии использования
├── Couples/
└── Weddings/

EventHandlers/             # Обработчики доменных событий
├── TaskCreatedEventHandler.cs
├── TaskCompletedEventHandler.cs
├── TaskStatusChangedEventHandler.cs
└── ...

DTOs/                      # Объекты передачи данных
Identity/                  # Модели пользователей
Services/                  # Интерфейсы сервисов

WeddingPlanner.Infrastructure

Persistence/
├── WeddingPlannerDbContext.cs  # Контекст БД
└── Configurations/             # Конфигурации EF

Repositories/                   # Реализации репозиториев
Services/
├── TokenService.cs            # JWT сервис
├── OAuth/                     # OAuth провайдеры
└── Email/                     # Email сервис

Configuration/
└── DependencyInjection.cs    # Настройка DI

Архитектурные тесты

Проект включает автоматизированные архитектурные тесты для обеспечения соблюдения принципов Clean Architecture и DDD:

Tests/WeddingPlanner.Architecture.Tests

• CleanArchitectureTests - проверка соблюдения принципов Clean Architecture
  • Проверка направления зависимостей между слоями
  • Контроль изоляции Domain layer от внешних зависимостей
  • Валидация корректности использования Infrastructure layer
• DomainDesignTests - проверка соблюдения принципов DDD
  • Валидация наследования Entity от BaseEntity или AggregateRoot
  • Проверка реализации IDomainEvent для доменных событий
  • Контроль правильного управления доменными событиями в агрегатах
• NamingConventionTests - соблюдение соглашений об именовании
  • Repository implementations должны заканчиваться на "Repository"
  • Service classes должны заканчиваться на "Service" (с исключениями для Adapter, Dispatcher, Factory)
  • Command/Query handlers должны заканчиваться на "Handler" (с исключениями для Response DTO)
  • DTO classes должны заканчиваться на "Dto" (с исключениями для Response/Info)

Результаты: 22/22 тестов проходят ✅

Используемые библиотеки для тестирования

• NetArchTest.Rules - архитектурные тесты
• FluentAssertions - улучшенные assertions
• xUnit - тестовый фреймворк

Ключевые особенности архитектуры

1. Clean Architecture

• Независимость от фреймворков - бизнес-логика не зависит от внешних библиотек
• Тестируемость - четкое разделение ответственности
• Независимость от UI - бизнес-логика не зависит от способа представления
• Независимость от базы данных - доменный слой не знает о способе хранения данных

2. Domain-Driven Design (DDD)

• Ubiquitous Language - единый язык между разработчиками и заказчиками
• Bounded Context - четкие границы контекста "Планирование свадеб"
• Aggregate Pattern - консистентность данных через корни агрегатов
• Domain Events - слабая связанность через события

3. CQRS (Command Query Responsibility Segregation)

• Команды - операции изменения состояния
• Запросы - операции чтения данных
• MediatR - медиатор для обработки команд и запросов

4. Паттерн Result

• CSharpFunctionalExtensions - обработка ошибок без исключений
• Railway Oriented Programming - композиция операций
• Явная обработка ошибок - Result вместо исключений

Аутентификация и авторизация

JWT Authentication

• Access Tokens - короткоживущие токены (15 минут)
• Refresh Tokens - долгоживущие токены для обновления
• Claims-based authorization - авторизация на основе ролей и claims

OAuth 2.0 Integration

• Google OAuth - аутентификация через Google
• Facebook OAuth - аутентификация через Facebook
• Apple OAuth - аутентификация через Apple

Роли системы

• Admin - полный доступ к системе
• Bride/Groom - управление своими свадьбами
• Vendor - управление услугами и заказами
• User - базовая роль

База данных

Entity Framework Core

• Code First подход с миграциями
• Fluent API для конфигурации сущностей
• Repository Pattern для абстракции доступа к данным
• Unit of Work через DbContext

Основные таблицы

• Couples - пары
• Weddings - свадьбы
• Vendors - поставщики
• Guests - гости
• Tasks - задачи
• AspNetUsers - пользователи Identity
• AspNetRoles - роли Identity

Интеграционные события

Система поддерживает два типа интеграционной шины событий:

InMemory Event Bus (по умолчанию)

• Обработка событий внутри одного процесса приложения
• Подходит для разработки и простых развертываний
• Нет персистентности событий

Kafka Event Bus

• Распределенная обработка событий через Apache Kafka
• Персистентность и гарантия доставки сообщений
• Масштабируемость и fault tolerance

Конфигурация

Development (Kafka включена):

{
  "IntegrationEventBus": {
    "Type": "Kafka",
    "Kafka": {
      "Enabled": true,
      "BootstrapServers": "localhost:9092",
      "TopicPrefix": "weddingplanner-dev"
    }
  }
}

Production (InMemory по умолчанию):

{
  "IntegrationEventBus": {
    "Type": "InMemory"
  }
}

Основные события

• TaskCreatedIntegrationEvent - создание задачи
• TaskStatusChangedIntegrationEvent - изменение статуса задачи
• CreateStoryFromTemplateIntegrationEvent - создание истории из шаблона
• CreateTaskFromTemplateIntegrationEvent - создание задачи из шаблона

Запуск и разработка

Локальная разработка с Kafka

1. Запуск Kafka инфраструктуры:

   ./scripts/start-kafka.sh

2. Запуск приложения:

   cd src/Gateways/WeddingPlanner.API
   dotnet run --environment Development

3. Мониторинг Kafka:

   • Kafka UI: http://localhost:8080
   • API Swagger: http://localhost:5005

4. Остановка Kafka:

   ./scripts/stop-kafka.sh

Переключение на InMemory

Для развертывания без Kafka измените в appsettings.json:

{
  "IntegrationEventBus": {
    "Type": "InMemory"
  }
}

Мониторинг событий

# Мониторинг топиков Kafka
./scripts/monitor-kafka-topics.sh

# Просмотр всех сообщений из конкретного топика
./scripts/monitor-kafka-topics.sh weddingplanner-dev.taskcreatedintegrationevent

Документация

• Kafka Setup Guide - подробное руководство по настройке Kafka
• Kafka Testing Guide - руководство по тестированию интеграции

Как обновлять этот README

Когда обновлять

1. Добавление новых доменных сущностей - обновить раздел "Доменная область"
2. Изменение архитектуры - обновить диаграммы и описания слоев
3. Добавление новых библиотек - добавить в раздел "Технологии"
4. Новые функции - описать в соответствующих разделах
5. Изменение структуры проекта - обновить структуру папок

Что включать

1. Назначение изменений - зачем сделано изменение
2. Влияние на архитектуру - как изменения влияют на общую структуру
3. Новые зависимости - если добавлены новые библиотеки
4. Примеры использования - для новых API или паттернов
5. Миграции БД - если изменена структура данных

Формат обновлений

## История изменений

### [Дата] - Описание изменения
- **Что добавлено:** описание новой функциональности
- **Что изменено:** описание модификаций
- **Влияние на архитектуру:** как изменения влияют на общую структуру
- **Новые зависимости:** список добавленных библиотек
- **Миграции:** описание изменений в БД

Поддержание актуальности

1. После каждого крупного рефакторинга обновлять архитектурные диаграммы
2. При добавлении новых модулей обновлять структуру проекта
3. При изменении доменной модели обновлять описание сущностей
4. При добавлении новых интеграций обновлять раздел технологий
5. Регулярно проверять соответствие README текущему состоянию кода

Контекст для ИИ-ассистента

⚠️ Основной контекст для ИИ перенесен в комментарии Program.cs для лучшей доступности. Этот файл содержит архитектурную документацию для людей.

---

История изменений

[2025-07-22] - Kafka интеграция для интеграционных событий

• Что добавлено:
  • Apache Kafka поддержка для интеграционных событий
  • Docker Compose конфигурация для локального Kafka кластера
  • Скрипты автоматизации: start-kafka.sh, stop-kafka.sh, monitor-kafka-topics.sh
  • Kafka UI для визуального мониторинга (http://localhost:8080)
  • Полная конфигурация Producer и Consumer настроек
• Что изменено:
  • InMemoryIntegrationEventBus и KafkaIntegrationEventBus сделаны internal
  • Добавлена IOptions<> конфигурация для event bus
  • Development environment настроен на использование Kafka по умолчанию
• Интеграционные события:
  • TaskCreatedIntegrationEvent - создание задач
  • TaskStatusChangedIntegrationEvent - изменение статусов
  • CreateStoryFromTemplateIntegrationEvent - создание историй из шаблонов
  • CreateTaskFromTemplateIntegrationEvent - создание задач из шаблонов
• Архитектурные улучшения:
  • Единый интерфейс IIntegrationEventBus для InMemory и Kafka реализаций
  • Автоматическое создание топиков с правильным naming convention
  • Graceful fallback с InMemory при недоступности Kafka
  • Comprehensive error handling и logging
• Инфраструктура:
  • Confluent Kafka 7.6.0 через Docker
  • Kafka UI для мониторинга и отладки
  • Автоматизированные скрипты управления
  • Полная документация в docs/KAFKA_SETUP.md и docs/KAFKA_TESTING.md
• Тестирование:
  • Архитектурные тесты для InternalsVisibleTo конфигурации
  • Интеграционные тесты для Kafka event bus
  • Мониторинг скрипты для отладки событий

[2025-07-12] - Архитектурные улучшения: Clean Architecture & DDD compliance

• Что исправлено: Критические нарушения принципов Clean Architecture
  • Удалены Infrastructure зависимости из Application layer
  • Консолидированы DTO - убраны дубликаты из Infrastructure
  • Task entity интегрирован в Wedding агрегат (исправление DDD aggregate boundaries)
• Что добавлено:
  • Автоматизированные архитектурные тесты (22 теста)
  • Проверка соблюдения Clean Architecture принципов
  • Валидация DDD паттернов и naming conventions
• Архитектурные улучшения:
  • Task теперь правильно является Entity в составе Wedding агрегата
  • Domain events управляются только aggregate root (Wedding)
  • Удален ITaskRepository - операции с Task через IWeddingRepository
  • Применен принцип YAGNI для очистки TODO и Legacy кода
• Влияние на архитектуру:
  • Правильные границы агрегатов согласно DDD
  • Устранены нарушения зависимостей Clean Architecture
  • Упрощена архитектура за счет удаления лишних абстракций
• Результаты:
  • 22/22 архитектурных тестов проходят
  • 143/143 domain тестов проходят
  • Весь solution компилируется без ошибок
  • Codebase очищен от технического долга

[2025-01-09] - Реализация доменных событий в DDD стиле

• Что добавлено: Полноценная система доменных событий для агрегатов
• Что изменено: Обновлена архитектура для поддержки событийно-ориентированного подхода
• Влияние на архитектуру: Добавлен слой обработки событий в Application Layer
• Новые зависимости: Использование MediatR для публикации и обработки доменных событий
• Доменные события:
  • CoupleCreatedEvent - событие создания пары
  • WeddingCreatedEvent - событие создания свадьбы
  • InvitationAcceptedEvent / InvitationDeclinedEvent - события для приглашений
  • События задач: TaskCreatedEvent, TaskStartedEvent, TaskCompletedEvent, TaskCancelledEvent, TaskUpdatedEvent, TaskStatusChangedEvent
• Обработчики событий:
  • TaskCreatedEventHandler - обработка создания задач
  • TaskCompletedEventHandler - обработка завершения задач
  • TaskStatusChangedEventHandler - обработка изменения статуса задач
• Архитектурные улучшения:
  • Реализован абстрактный класс BaseInvitation для общей логики приглашений
  • Добавлен enum InvitationType для типизации приглашений
  • Все события наследуются от BaseDomainEvent который реализует IDomainEvent
  • Агрегаты теперь генерируют события при выполнении бизнес-операций

---

Этот README должен служить единственным источником истины о структуре и назначении системы. При любых архитектурных изменениях обязательно обновляйте соответствующие разделы.