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

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

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

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

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

03Детальное описание модулей

/api

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

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

api/booking-order.service.ts

import { authApi } from "@/entities/auth/api/auth.api";

export const bookingOrderApi = authApi.injectEndpoints({
	endpoints: (builder) => ({
		getBookingOrders: builder.query<TResponse, TFilters>({
			query: (filters) => ({ url: "/booking/orders" }),
			providesTags: [ENUM_API_TAGS.BOOKING_ORDERS]
		})
	})
});

/converters

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

converters/booking-order.converters.ts

export const mapBookingOrderToFrontend = (data: IBookingOrderBackend): IOrder => ({
	orderId: data.order_id,
	orderType: data.order_type as ENUM_ORDER_TYPE_OPTIONS_TYPE,
	dateCreated: formatDate(data.date_created),
	client: data.client,
	status: data.status as ENUM_ORDER_STATUS_TYPE
});

export const mapBookingOrderToBackend = (data: Partial<IOrderDetail>): Partial<IBookingOrderDetailBackend> => ({
	order_id: data.orderId,
	order_type: data.orderType,
	date_created: data.dateCreated,
	client: data.client,
	status: data.status
});

/handlers

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

handlers/booking-order.handlers.ts

import { HttpResponse, http } from "msw";
import { ENV } from "@/shared/config";
import { BOOKING_ORDERS_MOCK } from "../mock";

export const bookingOrderHandlers = [
	http.get(`${ENV.VITE_API_URL}/booking/orders`, ({ request }) => {
		const url = new URL(request.url);
		return HttpResponse.json({
			data: [...BOOKING_ORDERS_MOCK],
			total: BOOKING_ORDERS_MOCK.length
		});
	}),
	http.get(`${ENV.VITE_API_URL}/booking/orders/:id`, ({ params }) => {
		const order = BOOKING_ORDERS_MOCK.find((o) => o.orderId === params.id);
		if (!order) return new HttpResponse(null, { status: 404 });
		return HttpResponse.json(order);
	})
];

/mock

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

mock/booking-order.mock.ts

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

export const BOOKING_ORDERS_MOCK: IOrderDetail[] = [
	{
		orderId: "ORD-001",
		orderType: "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
	}
];

/schema

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

schema/order.schema.ts

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

const msg = i18nKey<TBookingOrderKeys>();

export const BOOKING_ORDER_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 TBookingOrderSchema = z.infer<typeof BOOKING_ORDER_SCHEMA>;

/slice

Хранит локальное состояние сущности (UI-слой), не связанное с кэшом сервера. Например: текущий выбранный элемент.

slice/order.slice.ts

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

interface IOrderSliceState {
	selectedOrderId: string | null;
}

const initialState: IOrderSliceState = {
	selectedOrderId: null
};

export const orderSlice = createSlice({
	name: "bookingOrder",
	initialState,
	reducers: {
		setSelectedOrder: (state, action: PayloadAction<string>) => {
			state.selectedOrderId = action.payload;
		}
	}
});

/ui

Набор "глупых" (dumb) компонентов отображения, привязанных к данной сущности. Не содержат логики запросов.

ui/order-card.tsx

interface IOrderCardProps {
	order: IOrder;
	onSelect: (id: string) => void;
}

export const OrderCard = ({ order, onSelect }: IOrderCardProps) => (
	<Card onClick={() => onSelect(order.orderId)}>
		<CardHeader>{order.client}</CardHeader>
		<CardContent>Pax: {order.pax}</CardContent>
	</Card>
);

/types

Каталог TypeScript интерфейсов, описывающих сущность. Подразделяется на *.interface.ts и *.types.ts.

types/order.interface.ts

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

export interface IOrder {
	orderId: string;
	orderType: ENUM_ORDER_TYPE_OPTIONS_TYPE;
	dateCreated: string;
	client: string;
	pax: number;
	dates: IOrderDates;
	status: ENUM_ORDER_STATUS_TYPE;
}