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

Implementation Blueprint

Назначение​

Документ описывает, как стандартная backend-реализация Pin должна быть организована на уровне слоев, пакетов, feature slices и повторяемого runtime flow. Это не сервисная спецификация, а корпоративный blueprint для команд реализации.

Принципы​

  • Сервис владеет только своим состоянием, своей схемой и своими контрактами.
  • Общий код живет только в src/building-blocks/*, src/shared/* или src/contracts/*.
  • Domain не зависит от ASP.NET Core, EF Core, MassTransit, Redis, Elasticsearch, ClickHouse и текущего HTTP-запроса.
  • Application определяет commands, queries, validators, ports, orchestration и business policies.
  • Infrastructure реализует persistence, messaging, caching, search, analytics и integration adapters.
  • Api собирает runtime: controllers, auth, policies, middleware, DI, OpenAPI.

Целевая Структура Сервиса​

src/services/<service-name>/
  <Service>.Api/
  <Service>.Application/
  <Service>.Domain/
  <Service>.Infrastructure/
  <Service>.Background/
  <Service>.Migrator/
  <Service>.Contracts/

Структура Application Layer​

<Service>.Application/
  <FeatureGroup>/
    <Feature>/
      <Feature>Command.cs
      <Feature>CommandHandler.cs
      <Feature>CommandResult.cs
      <Feature>CommandValidator.cs
      <Feature>Query.cs
      <Feature>QueryHandler.cs
      <Feature>QueryResult.cs
      <Feature>QueryValidator.cs
      <Feature>Policy.cs
      <Feature>Mapping.cs
  Shared/
    Ports/
    Models/
    Policies/

Правила:

  • один use case живет в одной папке;
  • feature naming отражает бизнес-действие;
  • пустые технические папки Commands, Queries, Handlers, Validators на корне запрещены;
  • feature-specific models и policies лежат рядом с feature;
  • shared contracts выделяются только при реальном повторном использовании.

Остальные Слои​

  • Api группирует endpoints и runtime composition, но не содержит business decisions.
  • Domain группирует aggregates, entities, value objects и invariants.
  • Infrastructure содержит repositories, DbContext, consumers support, adapters и projection implementations.
  • Background содержит consumers и jobs, зеркалируя feature groups.
  • Tests повторяют namespace production-кода и покрывают риски на соответствующем уровне.

Runtime Flow​

Поток Добавления Нового Поведения​

  1. Обновить документацию: contract, entity, event, runbook, dashboard или task spec.
  2. Проверить source of truth, ownership и integration boundaries.
  3. Создать feature slice в Application.
  4. Описать transaction/read boundary, side effects, idempotency и observability.
  5. Реализовать persistence и adapters через общие building blocks.
  6. Добавить tests по риску изменения.
  7. Обновить связанные документы и operational artifacts.

Когда Нужен Rich Domain Model​

Rich model обязателен там, где есть:

  • инварианты;
  • state transitions;
  • audit-sensitive decisions;
  • финансовые проводки или учетные движения;
  • конкурентные изменения;
  • approval workflows;
  • сложные policy rules.

Anemic/read models допустимы для:

  • справочников;
  • projections;
  • search documents;
  • dashboard rows;
  • export rows;
  • простых административных представлений без собственных инвариантов.

Foundation Пакеты​

  1. Talent.Common.Domain
  2. Talent.Common.Application
  3. Talent.Common.Infrastructure
  4. Talent.Common.Messaging
  5. Talent.Common.Observability
  6. Talent.Common.Identity
  7. Talent.Common.Domain.Search
  8. Talent.Common.Analytics

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

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

Связанные Документы​