Предметная область (Entities)

Сущности — это базовые бизнес-единицы проекта. Данный раздел описывает унифицированную структуру любой сущности, основанную на строгих архитектурных правилах.

Структура слоя Entities

Каждая бизнес-сущность внутри src/entities/* обязана следовать жестко-заданной директориальной структуре для изоляции логики и UI.

Файловая структура

Стандартные модули сущности

Полная сущность состоит из следующих обязательных модулей:

01/api

RTK Query эндпоинты сущности. Конвертеры вызываются внутри API-слоя: transformResponse мапит backend T*Backend в frontend-модели, а query — params/body через map*ToBackend. Хуки уже отдают domain-модели — UI не должен повторно мапить DTO.

Изучить архитектуру RTK Query

api/[entity-name].service.ts

import { baseApi } from "@/shared/api/backend";
import type { IPaginationRequest, IPaginationResponse } from "@/shared/types";
import {
	mapEntitiesQueryToBackend,
	mapEntitiesToFrontend
} from "../converters";
import type { TEntitiesBackend, IEntity } from "../types";

/** Converters run here — hooks return frontend models, not raw DTOs */
export const entityApi = baseApi.injectEndpoints({
	endpoints: (builder) => ({
		getEntities: builder.query<
			IPaginationResponse<IEntity>,
			IPaginationRequest
		>({
			query: (filters) => ({
				url: "/entities",
				params: mapEntitiesQueryToBackend(filters)
			}),
			transformResponse: (response: TEntitiesBackend) =>
				mapEntitiesToFrontend(response),
			providesTags: [ENUM_API_TAGS.ENTITIES]
		})
	})
});

02/converters

Мапперы данных. Превращают сырой DTO от сервера в удобную Domain Model. Это изолирует UI-компоненты от внезапных изменений контрактов бекенда.

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

converters/[entity-name].converters.ts

export const mapEntityToFrontend = (data: TEntityBackend): IEntity => ({
	id: data.id,
	type: data.type as ENUM_ENTITY_TYPE,
	dateCreated: formatDate(data.date_created),
	client: data.client,
	status: data.status as ENUM_ENTITY_STATUS
});

export const mapEntitiesToFrontend = (
	response: TEntitiesBackend
): IPaginationResponse<IEntity> => ({
	data: response.items.map(mapEntityToFrontend),
	total: response.total_count
});

export const mapEntityToBackend = (
	data: Partial<IEntityDetail>
): Partial<TEntityDetailBackend> => ({
	id: data.id,
	type: data.type,
	date_created: data.dateCreated,
	client: data.client,
	status: data.status
});

03/handlers

Обработчики MSW (Mock Service Worker). Используются для перехвата сетевых вызовов во время разработки и в интеграционных тестах (Vitest / RTL).

Как работает MSW

handlers/[entity-name].handlers.ts

import { HttpResponse } from "msw";
import { createMockHandler } from "@/shared/api/msw/utils";
import { listEntitiesBackend } from "../mock";

/** Backend DTO responses — converters run in RTK transformResponse */
export const entityHandlers = [
	createMockHandler(
		{ url: "/entities", method: "GET", _types: { body: undefined } },
		() => HttpResponse.json(listEntitiesBackend())
	),
	createMockHandler(
		{ url: "/entities/:id", method: "GET", _types: { body: undefined } },
		({ params }) => {
			const { items } = listEntitiesBackend();
			const entity = items.find((e) => e.id === params.id);
			if (!entity) return new HttpResponse(null, { status: 404 });
			return HttpResponse.json(entity);
		}
	)
];

04/mock

Статические фикстуры и фейковые данные (mock data), используемые для эмуляции ответа сервера в связке с MSW handlers или для Storybook.

Раздел про MSW и мок-данные

mock/[entity-name].mock.ts

import type { TEntityBackend } from "../types";

export const ENTITIES_MOCK: TEntityBackend[] = [
	{
		id: "ENT-001",
		type: "individual",
		date_created: "2024-03-15T12:00:00Z",
		client: "John Doe",
		pax: 2,
		status_code: "CONFIRMED"
	}
];

05/schema

Single Source of Truth для типов данных сущности. Содержит Zod-объекты со встроенной интернационализацией (i18n) ошибок.

Использование Zod

schema/[entity-name]-create.schema.ts

import { z } from "zod";
import { i18nKey } from "@/shared/config";
// прямой путь к form.types — не barrel "../types"
import { ENUM_FORM_ENTITY_CREATE } from "../types/entity-create-form.types";

const msg = i18nKey<TEntityKeys>();
const F = ENUM_FORM_ENTITY_CREATE;

/** Runtime only — inferred form types belong in types/ (одна пара на операцию) */
export const ENTITY_CREATE_SCHEMA = z.object({
	[F.CLIENT]: z.string().min(1, { message: msg("errors.client.required") }),
	[F.STATUS]: z.enum(["PENDING", "CONFIRMED"]),
	[F.PAX]: z.number().min(1)
});

types/[entity-name]-create-form.types.ts

import type { FieldValues } from "react-hook-form";
import { z } from "zod";
// только import type — в рантайме зависимость schema → form.types односторонняя
import type { ENTITY_CREATE_SCHEMA } from "../schema";

export const ENUM_FORM_ENTITY_CREATE = {
	CLIENT: "client",
	STATUS: "status",
	PAX: "pax"
} as const;

export type ENUM_FORM_ENTITY_CREATE_TYPE =
	(typeof ENUM_FORM_ENTITY_CREATE)[keyof typeof ENUM_FORM_ENTITY_CREATE];

export type TEntityCreateSchema = z.infer<typeof ENTITY_CREATE_SCHEMA> &
	FieldValues;

06/slice

Redux-стейт сущности (если она хранит глобальные данные). Часто здесь же лежат селекторы и экшены. Важно: стейт должен зависеть только от Domain Model, а не от DTO.

slice/[entity-name].slice.ts

import { createSlice, PayloadAction } from "@reduxjs/toolkit";

interface IEntitySliceState {
	selectedId: string | null;
}

const initialState: IEntitySliceState = {
	selectedId: null
};

export const entitySlice = createSlice({
	name: "entity",
	initialState,
	reducers: {
		setSelectedEntity: (state, action: PayloadAction<string>) => {
			state.selectedId = action.payload;
		}
	}
});

07/ui

Dump-компоненты или Smart-компоненты уровня сущности. Например: UserCard, UserAvatar. Могут быть переиспользованы в разных фичах и виджетах.

ui/[entity-name]-card.tsx

interface IEntityCardProps {
	entity: IEntity;
	onSelect: (id: string) => void;
}

export const EntityCard = ({ entity, onSelect }: IEntityCardProps) => (
	<Card onClick={() => onSelect(entity.id)}>
		<CardHeader>{entity.client}</CardHeader>
		<CardContent>Pax: {entity.pax}</CardContent>
	</Card>
);

08/types

Глобальные TS-интерфейсы и типы для конкретной сущности (например, интерфейс Domain Model, если Zod не покрывает всю логику или требуется выделить часть типов). Рекомендуется использовать выведение типов из Zod-схем, но если это невозможно, типы описываются здесь.

Выведение типов в Zod

types/[entity-name].interface.ts

import type { IPaginationRequest, IPaginationResponse } from "@/shared/types";

export interface IEntityDates {
	from: string;
	to: string;
}

export interface IEntity {
	id: string;
	type: ENUM_ENTITY_TYPE;
	dateCreated: string;
	client: string;
	pax: number;
	dates: IEntityDates;
	status: ENUM_ENTITY_STATUS;
}

export type TEntitiesPage = IPaginationResponse<IEntity>;
export interface IEntitiesQuery extends IPaginationRequest {}