Соглашения разработки

Этот документ фиксирует обязательные соглашения для backend-кода KarmaCode.

TypeScript

• не использовать export default; публичные значения экспортировать именованно через export const;
• функции объявлять стрелочными функциями;
• для контрактов данных предпочитать type, а не interface;
• исключение для стороннего API допустимо только в синтаксисе импорта или объявления класса, когда этого требует библиотека;
• чувствительные данные не включать в логи, ошибки и OpenAPI-примеры.

prisma.config.ts предоставляет именованный prismaConfig, а CommonJS-присваивание используется только потому, что Prisma CLI ожидает конфигурацию как default-модуль. Прикладной код default exports не содержит.

HTTP и OpenAPI

• каждый новый endpoint добавляется вместе с OpenAPI-описанием, примерами ответов и стабильными кодами ошибок;
• интерактивная документация доступна по /docs, машинный документ — по /docs/openapi.json;
• фактический ответ и Swagger-схема проверяются тестом в рамках одного изменения;
• публичная база API — /api/v1; успешный envelope — { "data": ... }, ошибочный — { "error": ... }.

Проверка изменения

Перед завершением задачи должны проходить npm run check, npx prisma validate и проверка production-зависимостей npm run audit:production.