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

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

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

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

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

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

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

01/api

Отвечает исключительно за сетевое взаимодействие с backend-приложением в рамках одной сущности. Принимает аргументы для запроса и возвращает сырые DTO, которые затем обязательно передаются в конвертеры.

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

api/[entity-name].api.ts

import { mainApi } from "@/shared/api";

export const entityApi = mainApi.injectEndpoints({
	endpoints: (builder) => ({
		getEntities: builder.query<TResponse, TFilters>({
			query: (filters) => ({ url: "/entities" }),
			providesTags: [ENUM_API_TAGS.ENTITIES]
		})
	})
});

02/converters

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

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

converters/[entity-name].converters.ts

export const mapEntityToFrontend = (data: IEntityBackend): 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 mapEntityToBackend = (data: Partial<IEntityDetail>): 
	Partial<IEntityDetailBackend> => ({
		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, http } from "msw";
import { ENV } from "@/shared/config";
import { ENTITIES_MOCK } from "../mock";

export const entityHandlers = [
	http.get(`${ENV.VITE_API_URL}/entities`, ({ request }) => {
		const url = new URL(request.url);
		return HttpResponse.json({
			data: [...ENTITIES_MOCK],
			total: ENTITIES_MOCK.length
		});
	}),
	http.get(`${ENV.VITE_API_URL}/entities/:id`, ({ params }) => {
		const entity = ENTITIES_MOCK.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 { IEntityDetail } from "../types";

export const ENTITIES_MOCK: IEntityDetail[] = [
	{
		id: "ENT-001",
		type: "individual",
		dateCreated: "2024-03-15T12:00:00Z",
		client: "John Doe",
		pax: 2,
		dates: { from: "2024-04-01", to: "2024-04-10" },
		status: "CONFIRMED",
		// ... full fields
	}
];

05/schema

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

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

schema/[entity-name].schema.ts

import { z } from "zod";
import { i18nKey } from "@/shared/config";

const msg = i18nKey<TEntityKeys>();

export const ENTITY_SCHEMA = z.object({
	client: z.string().min(1, { message: msg("errors.client.required") }),
	status: z.enum(["PENDING", "CONFIRMED"]),
	pax: z.number().min(1)
});

export type TEntitySchema = z.infer<typeof ENTITY_SCHEMA>;

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].types.ts

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;
}