Перейти к основному содержимому

NuGet Package Structure — Карта Building Blocks

Назначение​

Документ детализирует структуру, содержимое и правила подключения каждого из shared building block пакетов. Является практическим дополнением к Shared Package Map.

Физическая Структура Monorepo​

src/
  building-blocks/
    Talent.Common.Domain/
    Talent.Common.Application/
    Talent.Common.Identity/
    Talent.Common.Infrastructure/
    Talent.Common.Messaging/
    Talent.Common.Observability/
    Talent.Common.Domain.Search/         ← провайдер-нейтральные контракты поиска
    Talent.Common.Infrastructure.ElasticSearch/ ← реализация поиска (Elastic.Clients.Elasticsearch)
    Talent.Common.Analytics/
    Talent.Common.Resilience/
    Talent.Common.Locking/      ← distributed lock (madelson/DistributedLock)
    Talent.Common.Realtime.Core/← SignalR message contracts + IRealtimeProducer
    Talent.Common.Realtime.Hub/ ← PinHubBase, Redis backplane, DI extensions
    Talent.Common.Realtime.Client/ ← IRealtimeProducer для workers/other services
    Talent.Common.Audit/        ← Audit.NET configuration + EF + WebApi
  kernel/
    Pin.Kernel.Abstractions/
    Pin.Kernel.Hosting/
    Pin.Kernel.AspNetCore/
    Pin.Kernel.Migrator/
    Pin.Kernel.Worker/
    Pin.Kernel.Testing/
  contracts/
    Pin.<Service>.Contracts/   ← per-service event/DTO contracts

Talent.Common.Domain​

Назначение: Чистые доменные абстракции без infrastructure dependencies.

NuGet dependencies: только FluentResults (для typed failure).

Содержит:

Talent.Common.Domain/
  Entities/
    Entity.cs               — базовый Entity<TId>
    AggregateRoot.cs        — AggregateRoot<TId> с domain events
    SoftDeletableEntity.cs  — soft delete pattern
    StatusEntity.cs         — stateful entity с FSM helper
  ValueObjects/
    ValueObject.cs          — базовый ValueObject с equality
    TenantId.cs
    BrandId.cs
    UserId.cs
    PartnerId.cs
    AdminUserId.cs
    CorrelationId.cs
    IdempotencyKey.cs
    MoneyAmount.cs          — decimal Amount + CurrencyId (short, справочник handbook)
    ProviderReference.cs    — external provider id (string)
    Email.cs
    PhoneNumber.cs          — E.164
    IpAddress.cs
    SlugValue.cs
  Events/
    IDomainEvent.cs
    DomainEvent.cs          — базовый record
  Errors/
    DomainException.cs      — для impossible states
    DomainError.cs          — typed failure descriptor
  Specifications/
    ISpecification.cs
    CompositeSpecification.cs  — And, Or, Not
  Interfaces/
    IEntity.cs
    IAggregateRoot.cs
    IHasCreatedAt.cs
    IHasUpdatedAt.cs
    IHasConcurrencyToken.cs
    ITenantScoped.cs
    IBrandScoped.cs
    IUserOwned.cs
    IPartnerOwned.cs
    ISoftDeletable.cs

Правила:

  • Нет зависимости на EF, ASP.NET, Redis, Kafka, Serilog.
  • Нет DI registration.
  • Нет HttpContext.
  • Используется в Domain и Application слоях.

Talent.Common.Application​

Назначение: MediatR contracts, actor abstractions, result models, paging, validation markers.

NuGet dependencies: MediatR, FluentValidation, FluentResults, BuildingBlocks.Domain.

Содержит:

Talent.Common.Application/
  Cqrs/
    ICommand.cs               — IRequest<Result<TResult>>
    IQuery.cs                 — IRequest<Result<TResult>>
    IIdempotentCommand.cs     — + IdempotencyKey
    IAuditedRequest.cs        — требует audit record
    IAuthorizedRequest.cs     — permission + policy requirements
    ICacheableQuery.cs        — кешируемый query
    ITransactionalCommand.cs  — требует local transaction
    IProducesIntegrationEvents.cs
  Actors/
    IIdentityContextProvider.cs
    IdentityContext.cs
    ActorSnapshot.cs
    ActorType.cs
  Scope/
    ITenantScopeProvider.cs
    IBrandScopeProvider.cs
    IUserScopeProvider.cs
    IPartnerScopeProvider.cs
    ICorrelationContext.cs
    IIdempotencyContext.cs
  Results/
    PagedResult.cs
    CursorPagedResult.cs
    CommandResult.cs
    QueryResult.cs
  Models/
    PagedQuery.cs
    SortQuery.cs           — generic SortQuery<TField> where TField : struct, Enum
    FreshnessView.cs
    MoneyView.cs           — Amount + CurrencyId (short) + CurrencyCode (display, из CurrencySnapshot)
    LookupResponse.cs
    ResultEntry.cs
  Clock/
    IClock.cs                 — абстракция времени для тестирования
  Authorization/
    IAuthorizationDecisionService.cs
    IPermissionChecker.cs
    IPrivilegedSessionChecker.cs
  Ports/
    IReadPort.cs              — маркер read-only port
    IWritePort.cs             — маркер write port

Talent.Common.Identity​

Назначение: Authentication schemes, actor factories, JWT helpers, policy contracts.

NuGet dependencies: Microsoft.AspNetCore.Authentication.JwtBearer, BuildingBlocks.Application.

Содержит:

Talent.Common.Identity/
  Actors/
    UserActor.cs
    PartnerActor.cs
    AdminActor.cs
    ProviderCallbackActor.cs
    ServiceAccountActor.cs
    SystemJobActor.cs
  Factories/
    IActorFactory.cs
    IUserActorFactory.cs
    IAdminActorFactory.cs
    IPartnerActorFactory.cs
  Authentication/
    PinJwtBearerOptions.cs
    PinJwtBearerHandler.cs    — custom JWT validation
    ServiceAccountAuthHandler.cs
    ProviderCallbackAuthHandler.cs
  Claims/
    ClaimsMappingProfile.cs        — allowlist claims → actor fields
    PinClaimTypes.cs
  Middlewares/
    ActorContextMiddleware.cs
    TenantBrandResolutionMiddleware.cs
    PrivilegedSessionMiddleware.cs
    ProviderCallbackSecurityMiddleware.cs
  Authorization/
    PermissionRequirement.cs
    TenantScopeRequirement.cs
    PrivilegedSessionRequirement.cs
    PinAuthorizationPolicyProvider.cs
  DependencyInjection/
    AddPinIdentity.cs          — extension для IPinApiBuilder
    AddPinJwtBearer.cs
    AddPinServiceAccountAuth.cs
    AddProviderCallbackAuthentication.cs

Правила:

  • Не содержит credentials storage, password hash, session management.
  • Claims mapping использует explicit allowlist, не ClaimsPrincipal напрямую.
  • Пакет не знает о конкретных сервисах Pin.

Talent.Common.Infrastructure​

Назначение: EF/Npgsql helpers, repository pipeline, unit of work, idempotency storage, audit writer, transaction boundary.

NuGet dependencies: Microsoft.EntityFrameworkCore, Npgsql.EntityFrameworkCore.PostgreSQL, BuildingBlocks.Application, BuildingBlocks.Observability.

Содержит:

Talent.Common.Infrastructure/
  EF/
    PinDbContext.cs             — базовый DbContext с conventions
    PinDbContextOptions.cs
    Configurations/
      BaseEntityConfiguration.cs   — common column mappings
      TenantScopedConfiguration.cs — TenantId column conventions
    Interceptors/
      AuditInterceptor.cs           — auto-fill CreatedAt/UpdatedAt
      SoftDeleteInterceptor.cs      — глобальный soft delete query filter
  Repositories/
    IRepository.cs                  — aggregate command repository
    IReadRepository.cs              — read model repository
    RepositoryBase.cs               — базовая реализация
    RepositoryPipelineBuilder.cs
    Interceptors/
      TenantScopeInterceptor.cs     — автоматическая TenantId фильтрация
      BrandScopeInterceptor.cs      — автоматическая BrandId фильтрация
      UserScopeInterceptor.cs     — автоматическая UserId фильтрация
      PartnerScopeInterceptor.cs    — автоматическая PartnerId фильтрация
      SoftDeleteScopeInterceptor.cs — исключение soft-deleted по умолчанию
      MutationScopeInterceptor.cs   — проставление scope полей при записи
      AuditFieldInterceptor.cs      — проставление audit полей
    IScopeBypassPolicy.cs
    IRepositoryAuditWriter.cs
    RepositoryScopeOptions.cs
  UnitOfWork/
    IUnitOfWork.cs
    ITransactionBoundary.cs
    TransactionBoundary.cs
  Idempotency/
    IIdempotencyStore.cs
    IdempotencyRecord.cs
    IdempotencyStore.cs
  Audit/
    IAuditStore.cs
    AuditRecord.cs
    AuditStore.cs
  DependencyInjection/
    AddPinInfrastructure.cs     — extension для IPinInfrastructureBuilder
    AddRepositoryPipeline.cs

Pin.Kernel.*​

Pin.Kernel.Abstractions​

Базовые абстракции startup:

PinServiceDescriptor.cs    — описание сервиса (name, process type, capabilities)
IPinStartup.cs
IPinServiceModule.cs
IPinOptionsValidator.cs
IStartupTask.cs
IMigrationStep.cs
IReadinessContributor.cs
Builders/
  IPinApplicationBuilder.cs
  IPinInfrastructureBuilder.cs
  IPinApiBuilder.cs
  IPinMessagingBuilder.cs
  IPinObservabilityBuilder.cs
  IPinWorkerBuilder.cs

Pin.Kernel.Hosting​

PinHost.cs              — CreateWeb(), CreateWorker(), CreateMigrator()
ConfigurationLayerLoader.cs — загрузка в правильном порядке
SecretProvider.cs           — абстракция secret backend
OptionsValidationExtensions.cs

Pin.Kernel.AspNetCore​

BaseWebStartup.cs
BaseGatewayStartup.cs
Startup/
  WebStartupBuilder.cs
Middleware/
  PinCorrelationMiddleware.cs
  PinRequestContextMiddleware.cs
  PinExceptionHandlingMiddleware.cs
  PinSecurityHeadersMiddleware.cs
  PinRequestLoggingMiddleware.cs
  PinHttpMetricsMiddleware.cs
  PinTenantBrandResolutionMiddleware.cs
  PinActorContextMiddleware.cs
  PinIdempotencyMiddleware.cs
  PinRateLimitingMiddleware.cs
Filters/
  PinModelValidationFilter.cs
  PinResultMappingFilter.cs
  PinNotFoundMaskingFilter.cs
  PinAuditActionFilter.cs
  PinResponseHeaderFilter.cs
  PinOpenApiOperationFilter.cs
OpenApi/
  PinOpenApiDefaults.cs
  CorrelationHeaderOperationFilter.cs
  AuthSchemeOperationFilter.cs
  ErrorResponseOperationFilter.cs
ProblemDetails/
  PinProblemDetailsFactory.cs
  ResultToProblemDetailMapper.cs
MediatR/
  Behaviors/
    CorrelationBehavior.cs
    LoggingBehavior.cs
    MetricsBehavior.cs
    ValidationBehavior.cs
    AuthorizationBehavior.cs
    IdempotencyBehavior.cs
    QueryCacheBehavior.cs
    TransactionBehavior.cs
    DomainEventDispatchBehavior.cs
    AuditBehavior.cs

Pin.Kernel.Migrator — Легковесный Standalone Пакет​

Pin.Kernel.Migrator — отдельный пакет, намеренно изолированный от ASP.NET Core. Каждый сервис запускает migrator как отдельный консольный процесс (dotnet run --project src/services/accounting/Pin.Accounting.Migrator). Процесс применяет миграции и завершается с кодом 0 (успех) или 1 (ошибка).

NuGet dependencies — только необходимое:

<!-- Pin.Kernel.Migrator.csproj -->
<ItemGroup>
  <!-- DI + Hosted runner -->
  <PackageReference Include="Microsoft.Extensions.Hosting"              Version="10.*" />
  <PackageReference Include="Microsoft.Extensions.DependencyInjection"  Version="10.*" />

  <!-- EF Core migrations -->
  <PackageReference Include="Microsoft.EntityFrameworkCore"             Version="10.*" />
  <PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL"     Version="10.*" />

  <!-- Structured logging -->
  <PackageReference Include="Serilog.Extensions.Hosting"               Version="8.*" />
  <PackageReference Include="Serilog.Sinks.Console"                    Version="6.*" />

  <!-- Distributed lock (Redis или PostgreSQL advisory lock) -->
  <PackageReference Include="StackExchange.Redis"                      Version="2.*" />

  <!-- Kernel abstractions (без ASP.NET зависимости) -->
  <ProjectReference Include="Pin.Kernel.Abstractions" />
  <ProjectReference Include="Talent.Common.Infrastructure" />
</ItemGroup>

Никаких зависимостей на: Microsoft.AspNetCore.*, MassTransit, OpenTelemetry, Polly, SignalR.

Содержит:

Pin.Kernel.Migrator/
  BaseMigratorStartup.cs          — IHostedService: Apply → Lock → Run → Exit
  MigrationOrchestrator.cs        — координирует порядок источников миграций
  DistributedMigrationLock.cs     — distributed lock (Redis SETNX) на время миграции
  Sources/
    EfCoreMigrationSource.cs      — EF Core pending migrations
    SqlFileMigrationSource.cs     — raw SQL файлы (schema seeds, reference data)
    ElasticsearchMigrationSource.cs  — index templates, aliases
    ClickHouseMigrationSource.cs  — DDL таблиц и materialized views
  Extensions/
    MigratorHostBuilderExtensions.cs  — AddPinMigrator(sources)

Точка входа сервисного migrator-а:

// src/services/accounting/Pin.Accounting.Migrator/Program.cs

await PinHost
    .CreateMigrator(args)          // из Pin.Kernel.Hosting (только DI + config layers)
    .ConfigureServices((ctx, services) =>
    {
        services.AddPinMigrator(sources =>
        {
            sources.AddEfCore<AccountingDbContext>();
            sources.AddSqlFiles("migrations/sql");
        });

        services.AddNpgsql<AccountingDbContext>(
            ctx.Configuration.GetConnectionString("AccountingDb")!);
    })
    .RunMigratorAsync();
// Процесс завершается: exit code 0 — успех, 1 — ошибка

Правила:

  • Migrator-процесс не слушает HTTP и не регистрирует health endpoints.
  • DistributedMigrationLock предотвращает параллельный запуск при горизонтальном масштабировании.
  • Каждый источник миграций идемпотентен: повторный запуск не ломает уже применённые миграции.
  • CI pipeline запускает migrator контейнер до запуска service контейнера.

Pin.Kernel.Worker​

BaseBackgroundStartup.cs
WorkerHealthEndpoint.cs
GracefulShutdownCoordinator.cs
DistributedJobLock.cs
CheckpointStore.cs

Pin.Kernel.Testing​

PinWebApplicationFactory.cs
PinTestHostBuilder.cs
KernelStartupAssertions.cs
TestConfigurationBuilder.cs
FakeActorContextModule.cs
FakeClockModule.cs
InMemoryIdempotencyStore.cs
TestCorrelationContext.cs

Talent.Common.Messaging​

Назначение: Kafka envelope, MassTransit conventions, consumer idempotency helpers, event naming.

NuGet dependencies: MassTransit.RabbitMq / MassTransit.Kafka, BuildingBlocks.Application.

Содержит:

Talent.Common.Messaging/
  Envelope/
    IIntegrationEvent.cs          — static abstract members: TopicName, EventType, EventVersion, AggregateType, ProducerService
    IntegrationEventMeta.cs       — generic helper для чтения метаданных через тип-параметр
    IntegrationEventEnvelope.cs
    EventActorSnapshot.cs
    EventTechnicalMetadata.cs
  Conventions/
    PinMassTransitConventions.cs   — топик naming, serializer, retry
    KafkaTopicNamingConvention.cs
    EnvelopeSerializerFactory.cs
  Consumers/
    PinConsumerBase.cs             — базовый consumer с context restore
    IBusinessIdempotencyStore.cs
    ConsumerIdempotencyHelper.cs
  Context/
    MessageContextRestorer.cs          — восстановление correlation/tenant из headers
    MassTransitHeaderPropagator.cs     — добавление context headers при publish
  DependencyInjection/
    AddPinMessaging.cs
    AddPinMassTransit.cs
    AddPinKafkaProducer.cs

Talent.Common.Observability​

Назначение: Logging scopes, OpenTelemetry activities, metrics instruments, masking helpers.

NuGet dependencies: Serilog, OpenTelemetry, OpenTelemetry.Extensions.Hosting, BuildingBlocks.Application.

Содержит:

Talent.Common.Observability/
  Logging/
    PinLoggerFactory.cs
    LogScopeFields.cs           — константы полей scope
    SensitiveMaskingPolicy.cs   — маскирование PII в логах
    SerilogEnricher.cs
  Tracing/
    PinActivitySource.cs
    ActivityPropagator.cs
    TraceContextHelper.cs
  Metrics/
    PinMetrics.cs           — общие counters и histograms
    RedMetricsInstruments.cs    — requests/errors/duration
    BusinessMetricsBase.cs      — базовый класс для бизнес-метрик
  Decorators/
    LoggingDecorator.cs         — generic logging decorator для ports
    TracingDecorator.cs         — generic tracing decorator
    MetricsDecorator.cs         — generic metrics decorator
  DependencyInjection/
    AddPinSerilog.cs
    AddPinOpenTelemetry.cs
    AddPinMetrics.cs

Talent.Common.Domain.Search​

Назначение: провайдер-нейтральные контракты поиска (search-документ, индекс, запрос, rebuild-джоб, scope-фильтр). Не зависит от конкретного движка — реализация в Talent.Common.Infrastructure.ElasticSearch.

NuGet dependencies: BuildingBlocks.Application.

Содержит:

Talent.Common.Domain.Search/
  Documents/
    ElasticsearchDocument.cs    — базовый typed document (DocumentId, TenantId, BrandId?, SchemaVersion...)
    ISearchDocumentMapper.cs    — маппинг source entity → document
  Contracts/
    ISearchIndex.cs             — провайдер-нейтральный индекс (upsert/delete/search)
    SearchIndexResult.cs
    SearchPage.cs               — страница результатов (keyset/offset)
    SearchScopeFilter.cs        — tenant/brand/actor фильтр (до query execution)
  Query/
    SearchQuery.cs              — typed search query (фильтры/пагинация/сортировка)
  Rebuild/
    ISearchRebuildJob.cs        — полная переиндексация из source-of-truth PostgreSQL

Talent.Common.Infrastructure.ElasticSearch​

Назначение: реализация контрактов Talent.Common.Domain.Search на Elasticsearch: индекс-репозиторий, alias/index management, rebuild-оркестрация. Живой пакет SDK (клиент Elastic.Clients.Elasticsearch v9). Пакет Talent.Common.Infrastructure.OpenSearch — устаревшая заглушка, не используется.

NuGet dependencies: Elastic.Clients.Elasticsearch, Talent.Common.Domain.Search, BuildingBlocks.Application.

Содержит:

Talent.Common.Infrastructure.ElasticSearch/
  Repositories/
    IElasticsearchIndexRepository.cs
    ElasticsearchIndexRepository.cs   — реализация ISearchIndex поверх Elastic.Clients.Elasticsearch
  Index/
    IElasticsearchIndexManager.cs
    IElasticsearchAliasManager.cs     — zero-downtime reindex через alias (ADR-0029)
    IndexMigrationRecord.cs
  Rebuild/
    SearchRebuildOrchestrator.cs
  DependencyInjection/
    AddPinElasticsearch.cs

Talent.Common.Analytics​

Назначение: ClickHouse connection/query/ingestion abstractions, batch writer contracts.

NuGet dependencies: ClickHouse.Client, BuildingBlocks.Application.

Содержит:

Talent.Common.Analytics/
  Facts/
    ClickHouseFact.cs          — базовый fact
  Writers/
    IClickHouseBatchWriter.cs
    ClickHouseBatchWriter.cs
    BatchWriterOptions.cs
  Queries/
    IClickHouseQueryClient.cs
    ClickHouseQueryClient.cs
    IClickHouseReportRepository.cs
  Views/
    IClickHouseMaterializedViewManager.cs
  DependencyInjection/
    AddPinClickHouse.cs

Talent.Common.Resilience​

Назначение: Polly + Microsoft.Extensions.Http.Resilience pipelines для внешних HTTP/gRPC вызовов и application ports.

NuGet dependencies: Polly, Polly.Extensions, Microsoft.Extensions.Http.Resilience, Microsoft.Extensions.Resilience.

Содержит:

Talent.Common.Resilience/
  Policies/
    PinResiliencePolicies.cs    — ExternalProviderHttp, InternalServiceHttp, IdempotentPort
    ResiliencePipelineProfiles.cs   — named profiles: "external-provider", "internal-service"
  Decorators/
    ResilientPortDecorator.cs       — generic Scrutor decorator с Polly pipeline
    CircuitBreakerDecorator.cs
    RateLimitDecorator.cs
  Options/
    ResiliencePolicyOptions.cs      — MaxRetries, BackoffMs, CircuitBreakerThreshold
  DependencyInjection/
    AddPinResilience.cs         — регистрирует named pipelines в ResiliencePipelineProvider
    HttpClientResilienceExtensions.cs — .AddResilienceHandler("profile-name")

Talent.Common.Locking​

Назначение: Distributed locking через madelson/DistributedLock. Redis backend для операционных locks, PostgreSQL для migration locks.

NuGet dependencies: DistributedLock.Core, DistributedLock.Redis, DistributedLock.Postgres, BuildingBlocks.Application.

Содержит:

Talent.Common.Locking/
  IPinLockProvider.cs           — TryAcquire / Acquire / IDistributedLockHandle
  Providers/
    RedisLockProvider.cs            — Redis SETNX locks
    PostgresLockProvider.cs         — PostgreSQL advisory locks
  Jobs/
    DistributedJobRunner.cs         — RunExclusive(jobName, job, lockTimeout)
  Conventions/
    LockKeyConventions.cs           — PinLockKeys.IncentiveClaim(userId, offerId) etc.
  DependencyInjection/
    AddPinLocking.cs            — LockingBackend enum: Redis | Postgres

Talent.Common.Realtime.Core​

Назначение: Message contracts, channel constants и интерфейсы реального времени. Используется во всех сервисах — нет SignalR dependency.

NuGet dependencies: только BuildingBlocks.Application.

Talent.Common.Realtime.Core/
  Contracts/
    IRealtimeNotificationPublisher.cs   — SendToUser, SendToBrand, SendToUser
    IRealtimeProducer.cs                — NotifyUser, NotifyBrand (via MQ)
    RealtimeEnvelope.cs                 — internal MQ envelope
    RealtimeTarget.cs
  Messages/
    BalanceUpdatedMessage.cs
    WithdrawalStatusChangedMessage.cs
    IncentiveActivatedMessage.cs
    IncentiveExpiringSoonMessage.cs
    CompetitionLeaderboardMessage.cs
    SystemNotificationMessage.cs
    GameSessionExpiredMessage.cs
  Constants/
    RealtimeEvents.cs                   — snake_case event name constants

Talent.Common.Realtime.Hub​

Назначение: SignalR Hub base class, Redis backplane, DI setup. Только для сервисов, хостящих SignalR Hub (user-api).

NuGet dependencies: Microsoft.AspNetCore.SignalR, Microsoft.AspNetCore.SignalR.StackExchangeRedis, Realtime.Core.

Talent.Common.Realtime.Hub/
  PinHubBase.cs                       — auth, group management, logging
  SignalRNotificationPublisher.cs         — IRealtimeNotificationPublisher via IHubContext
  Relay/
    RealtimeNotificationRelay.cs          — BackgroundService: Redis PubSub → SignalR
  Options/
    SignalRBackplaneOptions.cs
  DependencyInjection/
    AddPinSignalR.cs                  — Hub + Redis backplane + Relay registration

Talent.Common.Realtime.Client​

Назначение: IRealtimeProducer реализация через Redis PubSub. Используется в background workers и других микросервисах без Hub.

NuGet dependencies: StackExchange.Redis, Realtime.Core.

Talent.Common.Realtime.Client/
  MqRealtimeProducer.cs                   — Redis PubSub publish
  DependencyInjection/
    AddPinRealtimeClient.cs

Talent.Common.Audit​

Назначение: Audit.NET конфигурация, DataProvider для PostgreSQL, EF change tracking audit, WebApi action audit.

NuGet dependencies: Audit.NET, Audit.NET.EntityFramework, Audit.WebApi, BuildingBlocks.Application.

Talent.Common.Audit/
  Configuration/
    AuditNetConfiguration.cs            — глобальный Setup() с custom fields
    AuditNetOptions.cs
    AuditNetStartupService.cs           — IHostedService для отложенной конфигурации
  DataProvider/
    PinEfAuditDataProvider.cs       — пишет в PostgreSQL schema "audit"
  Entities/
    AuditEvent.cs                       — EF entity для хранения audit records
  Attributes/
    AuditApiActionAttribute.cs          — [AuditApiAction("event-type")]
  Filters/
    AuditApiGlobalFilter.cs             — MVC filter для admin API
  Masking/
    AuditSensitiveMasker.cs             — маскирование PII перед записью
  DependencyInjection/
    AddPinAuditNet.cs

Health Checks в Kernel Packages​

Pin.Kernel.AspNetCore — Web Service Health​

Каждый web сервис регистрирует стандартные probes автоматически через AddPinHealthChecks():

// Pin.Kernel.AspNetCore/HealthChecks/

// Endpoints:
//   /health/live  — liveness: процесс жив, нет deadlock
//   /health/ready — readiness: зависимости доступны, можно принимать трафик

// Kubernetes probe конфигурация (пример):
// livenessProbe:
//   httpGet: { path: /health/live, port: 8080 }
//   initialDelaySeconds: 10
//   periodSeconds: 15
// readinessProbe:
//   httpGet: { path: /health/ready, port: 8080 }
//   initialDelaySeconds: 20
//   periodSeconds: 10
//   failureThreshold: 3
public static IPinApiBuilder AddPinHealthChecks(
    this IPinApiBuilder builder)
{
    builder.Services
        .AddHealthChecks()
        // PostgreSQL — основная БД
        .AddNpgsql(
            connectionStringFactory: sp => sp.GetRequiredService<IConfiguration>()
                .GetConnectionString("Db")!,
            name:    "postgresql",
            tags:    ["ready", "db"],
            timeout: TimeSpan.FromSeconds(5))
        // Redis — cache + locks + realtime
        .AddRedis(
            redisConnectionStringFactory: sp => sp.GetRequiredService<IConfiguration>()
                .GetConnectionString("Redis")!,
            name:    "redis",
            tags:    ["ready", "cache"],
            timeout: TimeSpan.FromSeconds(3))
        // Kafka — messaging
        .AddKafka(
            config: new ProducerConfig
            {
                BootstrapServers = builder.Configuration["Kafka:BootstrapServers"],
            },
            name:    "kafka",
            tags:    ["ready", "messaging"],
            timeout: TimeSpan.FromSeconds(5))
        // Liveness: всегда healthy если процесс отвечает
        .AddCheck("liveness", () => HealthCheckResult.Healthy(), tags: ["live"]);

    // Отдельные endpoints для k8s
    builder.Services.Configure<HealthCheckPublisherOptions>(options =>
    {
        options.Delay = TimeSpan.FromSeconds(5);
    });

    return builder;
}

// Регистрация endpoints в middleware pipeline:
app.MapHealthChecks("/health/live",  new HealthCheckOptions
{
    Predicate      = check => check.Tags.Contains("live"),
    ResponseWriter = UIResponseWriter.WriteHealthCheckUIResponse,
});

app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
    Predicate      = check => check.Tags.Contains("ready"),
    ResponseWriter = UIResponseWriter.WriteHealthCheckUIResponse,
});

Опциональные Checks (подключаются per-service)​

// Внешний провайдер (payment gateway, KYC)
builder.Services.AddHealthChecks()
    .AddUrlGroup(
        uri:     new Uri("https://api.stripe.com/v1/ping"),
        name:    "stripe-api",
        tags:    ["ready", "external"],
        timeout: TimeSpan.FromSeconds(5))
    // Elasticsearch
    .AddElasticsearch(
        baseAddressFactory: sp => sp.GetRequiredService<IConfiguration>()["Elasticsearch:Url"]!,
        name:    "elasticsearch",
        tags:    ["ready", "search"])
    // ClickHouse
    .AddCheck<ClickHouseHealthCheck>(
        name:    "clickhouse",
        tags:    ["ready", "analytics"]);

Pin.Kernel.Worker — Worker Health Endpoint​

// Worker не имеет HTTP pipeline, но регистрирует minimal health endpoint:
// GET /health/live  — liveness для k8s

public static IPinWorkerBuilder AddPinWorkerHealthChecks(
    this IPinWorkerBuilder builder)
{
    builder.Services
        .AddHealthChecks()
        .AddNpgsql(...)
        .AddRedis(...)
        .AddKafka(...);

    // Minimal ASP.NET Core endpoint ТОЛЬКО для health (не полный web pipeline)
    builder.Services.AddHealthCheckServer(port: 8081);

    return builder;
}

Правила Shared Code​

  • Shared package не импортирует сервисный project.
  • Все extension methods называются AddPin<Capability>.
  • Options classes валидируются через ValidateOnStart.
  • Shared package не знает Accounting, GameHost, Partner, Incentive как бизнес-домены.
  • Любой persistent shared mechanism имеет migration strategy.
  • Если механизм требует business decision, shared package предоставляет interface, сервис реализует policy.

Ссылки​

Обратные ссылки​

Автоссылки: где используется этот документ.