OpenAPI → T*Backend

Строгий пайплайн: сырые типы остаются в generated/backend.types.ts; домен видит только T*Backend из entities/*/types.

Codegen и изоляция типов

Правило: Не импортируйте schema OpenAPI в converters или api. Один раз алиасьте в T*Backend, затем мапьте во frontend-модели.

011. Скрипты codegen

openapi.steps.scripts.description

package.json

{
  "scripts": {
    "codegen:types": "tsx --env-file=.env scripts/generate-api-types.ts",
    "codegen:paths": "tsx --env-file=.env scripts/generate-api-paths.ts",
    "codegen": "npm run codegen:types && npm run codegen:paths"
  }
}

scripts/generate-api-types.ts

/**
 * Генерация TypeScript-типов из OpenAPI-спецификации.
 * npx tsx --env-file=.env scripts/generate-api-types.ts
 */
import { dirname, join, resolve } from "path";
import { fileURLToPath } from "url";
import { generateApi } from "swagger-typescript-api";

const __dirname = dirname(fileURLToPath(import.meta.url));
const API_URL = process.env.VITE_BASE_URL;
const OUTPUT_DIR = join(resolve(__dirname, ".."), "src/shared/api/generated");

const SPEC_URL = API_URL.endsWith("/openapi.json")
	? API_URL
	: `${API_URL.replace(/\/$/, "")}/openapi.json`;

await generateApi({
	fileName: "backend.types.ts",
	output: OUTPUT_DIR,
	url: SPEC_URL,
	generateClient: false,
	extractEnums: true,
	extractRequestParams: true,
	extractRequestBody: true
});

scripts/generate-api-paths.ts (excerpt)

/**
 * Группирует OpenAPI paths по tags → paths/<tag>.paths.ts
 * Каждый entry: { url, method, _types: { body, query, response } }
 * npx tsx --env-file=.env scripts/generate-api-paths.ts
 */
// См. полный скрипт в blogix-admin / MCP openapi-pattern.md
// Итог:
export const ADMIN_PROMOCODE_PATHS = {
	readPromocodes: {
		url: "/adv-admin/promocode/list",
		method: "POST",
		_types: {} as {
			body: ReadPromocodesRequest;
			query: void;
			response: ReadPromocodesResponse;
		}
	} as const
} as const;

022. Адаптер T*Backend

Только entities/*/types/*-backend.interface.ts может импортировать generated/backend.types. Экспортируйте алиасы TFooBackend (и re-export enum).

entities/[entity]/types/[entity]-backend.interface.ts

// entities/promocode/types/promocode-backend.interface.ts
// ЕДИНСТВЕННОЕ место импорта schema из backend.types.ts
import type {
	CreatePromocodeRequest,
	PromocodeDiscountType,
	PromocodeResponse,
	ReadPromocodesResponse
} from "@/shared/api/generated/backend.types";
import { ADMIN_PROMOCODE_PATHS } from "@/shared/api/generated/paths/admin-promocode.paths";

export type TPromocodeBackend = PromocodeResponse;
export type TPromocodesBackend = ReadPromocodesResponse;
export type TCreatePromocodeRequestBackend = CreatePromocodeRequest;
export type TSetPromocodeActiveQueryBackend =
	typeof ADMIN_PROMOCODE_PATHS.setPromocodeActive._types.query;

export { PromocodeDiscountType };
export type TPromocodeDiscountTypeBackend = PromocodeDiscountType;

033. converters / api

Берите T*Backend и enum из ../types. PATHS разрешены в api/handlers. Прямой backend.types.ts — запрещён.

converters — OK

// entities/promocode/converters/promocode.converters.ts — OK
import type { TPromocodeBackend } from "../types";
import { PromocodeDiscountType } from "../types";

export const mapPromocodeToFrontend = (data: TPromocodeBackend) => ({
	id: data.id,
	code: data.code
	// …
});

converters / api — FORBIDDEN

// ❌ FORBIDDEN in converters / api / handlers / UI
import type { PromocodeResponse } from "@/shared/api";
import { OrderStatus } from "@/shared/api/generated/backend.types";

044. ESLint gate

Ограничьте generated/backend.types глобально; разрешите только в entities/**/types и shared/api/generated. Лучше не реэкспортировать backend.types из @/shared/api.

eslint.config.js

// eslint.config.js — fragment
{
  rules: {
    "no-restricted-imports": [
      "error",
      {
        patterns: [
          {
            group: [
              "**/shared/api/generated/backend.types",
              "**/shared/api/generated/backend.types.ts",
              "@/shared/api/generated/backend.types"
            ],
            message:
              "Raw backend.types.ts types only in entities/*/types as T*Backend. Use ../types aliases elsewhere."
          }
        ]
      }
    ]
  }
},
{
  files: [
    "src/entities/**/types/**/*.{ts,tsx}",
    "src/shared/api/generated/**/*.{ts,tsx}"
  ],
  rules: { "no-restricted-imports": "off" }
}