code-ai-installer 3.0.0 → 4.0.1-a

package/domains/development/.agents/skills/node-express-beast-practices/SKILL.md

@@ -1,729 +1,241 @@
----
-name: node-express-beast-practices
-description: Node.js + Express — REST API, middleware pipeline, сервисный слой, репозитории, централизованная обработка ошибок, валидация (Zod), graceful shutdown, health checks, security headers. Активируй при написании API, рефакторинге Express-приложений, или при вопросах «как правильно организовать backend на Express».
----
-
-# Skill: Node/Express Beast Practices
-
-Конкретные DO/DON'T паттерны для Express API — от архитектуры до graceful shutdown.
-
-**Разделы:**
-1. [Архитектура: слои](#1-архитектура)
-2. [App Factory](#2-app-factory)
-3. [Router + Controller](#3-router--controller)
-4. [Middleware Pipeline](#4-middleware-pipeline)
-5. [Централизованная обработка ошибок](#5-обработка-ошибок)
-6. [Валидация (Zod)](#6-валидация)
-7. [Service + Repository](#7-service--repository)
-8. [Graceful Shutdown и Health Checks](#8-graceful-shutdown)
-9. [Anti-patterns](#9-anti-patterns)
-
----
-
-## 1. Архитектура
-
-```
-src/
-├── app.js                  # Express app factory (no listen)
-├── server.js               # HTTP server + graceful shutdown
-├── config/
-│   └── env.js              # Env validation + export
-├── middleware/
-│   ├── errorHandler.js     # Centralized error handler
-│   ├── requestId.js        # x-request-id injection
-│   ├── validate.js         # Zod validation middleware
-│   └── auth.js             # Auth middleware
-├── routes/
-│   ├── index.js            # Router aggregation
-│   ├── coupons.router.js
-│   └── templates.router.js
-├── controllers/
-│   ├── coupons.controller.js
-│   └── templates.controller.js
-├── services/
-│   ├── coupon.service.js   # Business logic
-│   └── template.service.js
-├── repositories/
-│   ├── coupon.repo.js      # Data access
-│   └── template.repo.js
-├── errors/
-│   └── AppError.js         # Custom error classes
-└── utils/
-    └── asyncHandler.js     # Async wrapper
-```
-
-### Слои и ответственность
-
-| Слой | Отвечает за | НЕ делает |
-|------|-----------|----------|
-| **Router** | URL → Controller mapping | Бизнес-логику |
-| **Controller** | Парсинг req → вызов service → формирование res | SQL/DB, валидацию |
-| **Middleware** | Кросс-сечения (auth, logging, rate limit) | Бизнес-логику |
-| **Service** | Бизнес-логика, оркестрация | Работу с req/res |
-| **Repository** | Доступ к данным (DB, API) | Бизнес-логику |
-
----
-
-## 2. App Factory
-
-### ✅ DO: app отдельно от server (тестируемость)
-
-```js
-// app.js — чистый Express app, без listen()
-import express from 'express';
-import helmet from 'helmet';
-import cors from 'cors';
-import compression from 'compression';
-import { requestIdMiddleware } from './middleware/requestId.js';
-import { errorHandler } from './middleware/errorHandler.js';
-import { routes } from './routes/index.js';
-
-/**
- * Создаёт и конфигурирует Express приложение.
- * @param {{ db: object, logger: object }} deps - зависимости.
- * @returns {express.Express} сконфигурированное приложение.
- */
-export function createApp(deps) {
-  const app = express();
-
-  // ── Security ──
-  app.use(helmet());
-  app.use(cors({ origin: deps.config?.corsOrigin ?? '*' }));
-
-  // ── Parsing ──
-  app.use(express.json({ limit: '1mb' }));
-  app.use(express.urlencoded({ extended: false }));
-
-  // ── Compression ──
-  app.use(compression());
-
-  // ── Request ID ──
-  app.use(requestIdMiddleware);
-
-  // ── Routes ──
-  app.use('/api', routes(deps));
-
-  // ── Health ──
-  app.get('/health', (_req, res) => res.json({ status: 'ok' }));
-
-  // ── 404 ──
-  app.use((_req, _res, next) => {
-    next(new AppError('Route not found', 404));
-  });
-
-  // ── Error Handler (MUST be last) ──
-  app.use(errorHandler(deps.logger));
-
-  return app;
-}
-```
-
-```js
-// server.js — HTTP сервер + graceful shutdown
-import { createApp } from './app.js';
-import { config } from './config/env.js';
-import { logger } from './utils/logger.js';
-import { connectDb } from './db/connection.js';
-
-async function main() {
-  const db = await connectDb(config.databaseUrl);
-  const app = createApp({ db, logger, config });
-
-  const server = app.listen(config.port, () => {
-    logger.info({ port: config.port }, 'Server started');
-  });
-
-  // Graceful shutdown (see section 8)
-  setupGracefulShutdown(server, db);
-}
-
-main().catch((err) => {
-  console.error('Fatal startup error:', err);
-  process.exit(1);
-});
-```
-
----
-
-## 3. Router + Controller
-
-### ✅ DO: тонкие контроллеры, бизнес-логика в service
-
-```js
-// routes/coupons.router.js
-import { Router } from 'express';
-import { CouponController } from '../controllers/coupons.controller.js';
-import { validate } from '../middleware/validate.js';
-import { createCouponSchema, updateCouponSchema } from '../schemas/coupon.schema.js';
-
-/**
- * Роутер для купонов.
- * @param {{ db: object }} deps - зависимости.
- * @returns {Router} Express router.
- */
-export function couponRouter(deps) {
-  const router = Router();
-  const ctrl = new CouponController(deps);
-
-  router.get('/',        ctrl.list);
-  router.get('/:id',     ctrl.getById);
-  router.post('/',       validate(createCouponSchema), ctrl.create);
-  router.patch('/:id',   validate(updateCouponSchema), ctrl.update);
-  router.delete('/:id',  ctrl.remove);
-
-  return router;
-}
-```
-
-```js
-// controllers/coupons.controller.js
-import { asyncHandler } from '../utils/asyncHandler.js';
-import { CouponService } from '../services/coupon.service.js';
-
-export class CouponController {
-  #service;
-
-  /**
-   * @param {{ db: object }} deps - зависимости.
-   */
-  constructor(deps) {
-    this.#service = new CouponService(deps);
-  }
-
-  /**
-   * Возвращает список купонов.
-   * GET /api/coupons
-   */
-  list = asyncHandler(async (req, res) => {
-    const { page = 1, limit = 20 } = req.query;
-    const result = await this.#service.list({ page: +page, limit: +limit });
-    res.json(result);
-  });
-
-  /**
-   * Возвращает купон по ID.
-   * GET /api/coupons/:id
-   */
-  getById = asyncHandler(async (req, res) => {
-    const coupon = await this.#service.getById(req.params.id);
-    res.json(coupon);
-  });
-
-  /**
-   * Создаёт новый купон.
-   * POST /api/coupons
-   */
-  create = asyncHandler(async (req, res) => {
-    const coupon = await this.#service.create(req.body);
-    res.status(201).json(coupon);
-  });
-
-  /**
-   * Обновляет купон.
-   * PATCH /api/coupons/:id
-   */
-  update = asyncHandler(async (req, res) => {
-    const coupon = await this.#service.update(req.params.id, req.body);
-    res.json(coupon);
-  });
-
-  /**
-   * Удаляет купон.
-   * DELETE /api/coupons/:id
-   */
-  remove = asyncHandler(async (req, res) => {
-    await this.#service.remove(req.params.id);
-    res.status(204).end();
-  });
-}
-```
-
-### ✅ DO: asyncHandler для автоматического перехвата ошибок
-
-```js
-// utils/asyncHandler.js
-
-/**
- * Оборачивает async controller в try/catch, передавая ошибку в next().
- * @param {Function} fn - async route handler.
- * @returns {Function} Express middleware.
- */
-export function asyncHandler(fn) {
-  return (req, res, next) => {
-    Promise.resolve(fn(req, res, next)).catch(next);
-  };
-}
-```
-
----
-
-## 4. Middleware Pipeline
-
-### Порядок middleware (критически важен)
-
-```
-1. helmet()              — Security headers
-2. cors()                — CORS
-3. express.json()        — Body parsing
-4. compression()         — Response compression
-5. requestIdMiddleware   — x-request-id
-6. requestLogMiddleware  — Access logging
-7. rateLimiter           — Rate limiting
-8. authMiddleware        — Authentication (route-level)
-9. validate(schema)      — Input validation (route-level)
-10. controller           — Business logic
-11. 404 handler          — Not found
-12. errorHandler         — Centralized error (MUST BE LAST)
-```
-
-### ✅ DO: request ID middleware
-
-```js
-// middleware/requestId.js
-import { randomUUID } from 'node:crypto';
-
-/**
- * Добавляет request ID к каждому запросу для корреляции логов.
- */
-export function requestIdMiddleware(req, _res, next) {
-  req.id = req.headers['x-request-id'] || randomUUID();
-  next();
-}
-```
-
-### ✅ DO: request logging middleware
-
-```js
-// middleware/requestLog.js
-
-/**
- * Логирует HTTP запросы с длительностью.
- * @param {object} logger - структурированный логгер (pino).
- */
-export function requestLogMiddleware(logger) {
-  return (req, res, next) => {
-    const start = performance.now();
-
-    res.on('finish', () => {
-      const duration = Math.round(performance.now() - start);
-      logger.info({
-        method: req.method,
-        url: req.originalUrl,
-        status: res.statusCode,
-        durationMs: duration,
-        requestId: req.id,
-      });
-    });
-
-    next();
-  };
-}
-```
-
----
-
-## 5. Обработка ошибок
-
-### ✅ DO: кастомный AppError
-
-```js
-// errors/AppError.js
-
-/**
- * Базовый класс ошибки приложения с HTTP-кодом.
- */
-export class AppError extends Error {
-  /**
-   * @param {string} message - сообщение для клиента.
-   * @param {number} statusCode - HTTP статус.
-   * @param {object} [details] - дополнительные данные.
-   */
-  constructor(message, statusCode = 500, details = undefined) {
-    super(message);
-    this.name = 'AppError';
-    this.statusCode = statusCode;
-    this.details = details;
-    this.isOperational = true; // отличает от programmer errors
-  }
-}
-
-export class NotFoundError extends AppError {
-  constructor(resource = 'Resource') {
-    super(`${resource} not found`, 404);
-  }
-}
-
-export class ValidationError extends AppError {
-  constructor(details) {
-    super('Validation failed', 400, details);
-  }
-}
-
-export class ConflictError extends AppError {
-  constructor(message = 'Resource already exists') {
-    super(message, 409);
-  }
-}
-
-export class UnauthorizedError extends AppError {
-  constructor(message = 'Authentication required') {
-    super(message, 401);
-  }
-}
-
-export class ForbiddenError extends AppError {
-  constructor(message = 'Access denied') {
-    super(message, 403);
-  }
-}
-```
-
-### ✅ DO: централизованный error handler
-
-```js
-// middleware/errorHandler.js
-
-/**
- * Централизованный обработчик ошибок Express.
- * MUST be the last middleware in the pipeline.
- * @param {object} logger - структурированный логгер.
- */
-export function errorHandler(logger) {
-  // eslint-disable-next-line no-unused-vars -- Express requires 4 params for error middleware
-  return (err, req, res, _next) => {
-    // Operational errors (expected)
-    if (err.isOperational) {
-      logger.warn({
-        err: { message: err.message, statusCode: err.statusCode },
-        requestId: req.id,
-      });
-
-      return res.status(err.statusCode).json({
-        error: err.message,
-        ...(err.details && { details: err.details }),
-      });
-    }
-
-    // Programmer errors (unexpected) — log full stack, return generic message
-    logger.error({
-      err,
-      requestId: req.id,
-      method: req.method,
-      url: req.originalUrl,
-    });
-
-    res.status(500).json({
-      error: 'Internal server error',
-      // ❌ NEVER expose stack trace or internal details
-    });
-  };
-}
-```
-
-### HTTP Status Codes по контракту
-
-| Код | Когда | Класс |
-|-----|-------|-------|
-| 200 | Успех (GET, PATCH, PUT) | — |
-| 201 | Ресурс создан (POST) | — |
-| 204 | Успех без тела (DELETE) | — |
-| 400 | Невалидные данные | `ValidationError` |
-| 401 | Не аутентифицирован | `UnauthorizedError` |
-| 403 | Нет прав | `ForbiddenError` |
-| 404 | Не найден | `NotFoundError` |
-| 409 | Конфликт (дубликат) | `ConflictError` |
-| 422 | Семантическая ошибка | `AppError(msg, 422)` |
-| 429 | Rate limit exceeded | rate limiter middleware |
-| 500 | Внутренняя ошибка | Programmer error |
-
----
-
-## 6. Валидация
-
-### ✅ DO: Zod schema + validation middleware
-
-```js
-// schemas/coupon.schema.js
-import { z } from 'zod';
-
-export const createCouponSchema = z.object({
-  body: z.object({
-    code: z.string().min(3).max(20).toUpperCase(),
-    discount: z.number().min(1).max(100),
-    type: z.enum(['percent', 'fixed']),
-    expiresAt: z.string().datetime().optional(),
-  }),
-});
-
-export const updateCouponSchema = z.object({
-  params: z.object({
-    id: z.string().uuid(),
-  }),
-  body: z.object({
-    code: z.string().min(3).max(20).toUpperCase().optional(),
-    discount: z.number().min(1).max(100).optional(),
-    active: z.boolean().optional(),
-  }),
-});
-```
-
-```js
-// middleware/validate.js
-import { AppError } from '../errors/AppError.js';
-
-/**
- * Middleware для валидации req через Zod schema.
- * @param {import('zod').ZodSchema} schema - Zod schema.
- */
-export function validate(schema) {
-  return (req, _res, next) => {
-    const result = schema.safeParse({
-      body: req.body,
-      query: req.query,
-      params: req.params,
-    });
-
-    if (!result.success) {
-      const errors = result.error.issues.map((issue) => ({
-        path: issue.path.join('.'),
-        message: issue.message,
-      }));
-      return next(new AppError('Validation failed', 400, errors));
-    }
-
-    // ✅ Заменяем req данные на parsed (coerced, defaults applied)
-    req.body = result.data.body ?? req.body;
-    req.query = result.data.query ?? req.query;
-    req.params = result.data.params ?? req.params;
-
-    next();
-  };
-}
-```
-
----
-
-## 7. Service + Repository
-
-### ✅ DO: service layer для бизнес-логики
-
-```js
-// services/coupon.service.js
-import { CouponRepo } from '../repositories/coupon.repo.js';
-import { NotFoundError, ConflictError } from '../errors/AppError.js';
-
-export class CouponService {
-  #repo;
-
-  constructor({ db }) {
-    this.#repo = new CouponRepo(db);
-  }
-
-  /**
-   * Возвращает список купонов с пагинацией.
-   * @param {{ page: number, limit: number }} params
-   * @returns {Promise<{ data: Coupon[], total: number }>}
-   */
-  async list({ page, limit }) {
-    const offset = (page - 1) * limit;
-    const [data, total] = await Promise.all([
-      this.#repo.findAll({ offset, limit }),
-      this.#repo.count(),
-    ]);
-    return { data, total, page, limit };
-  }
-
-  /**
-   * Возвращает купон по ID или выбрасывает NotFoundError.
-   * @param {string} id - ID купона.
-   * @returns {Promise<Coupon>}
-   */
-  async getById(id) {
-    const coupon = await this.#repo.findById(id);
-    if (!coupon) throw new NotFoundError('Coupon');
-    return coupon;
-  }
-
-  /**
-   * Создаёт купон, проверяя уникальность кода.
-   * @param {object} data - данные купона.
-   * @returns {Promise<Coupon>}
-   */
-  async create(data) {
-    const existing = await this.#repo.findByCode(data.code);
-    if (existing) throw new ConflictError(`Coupon code "${data.code}" already exists`);
-    return this.#repo.create(data);
-  }
-
-  async update(id, data) {
-    await this.getById(id); // throws NotFoundError
-    return this.#repo.update(id, data);
-  }
-
-  async remove(id) {
-    await this.getById(id);
-    return this.#repo.remove(id);
-  }
-}
-```
-
-### ✅ DO: repository для доступа к данным
-
-```js
-// repositories/coupon.repo.js
-
-export class CouponRepo {
-  #db;
-
-  constructor(db) {
-    this.#db = db;
-  }
-
-  async findAll({ offset, limit }) {
-    return this.#db.collection('coupons')
-      .find({})
-      .skip(offset)
-      .limit(limit)
-      .toArray();
-  }
-
-  async findById(id) {
-    return this.#db.collection('coupons').findOne({ _id: id });
-  }
-
-  async findByCode(code) {
-    return this.#db.collection('coupons').findOne({ code });
-  }
-
-  async count() {
-    return this.#db.collection('coupons').countDocuments();
-  }
-
-  async create(data) {
-    const result = await this.#db.collection('coupons').insertOne({
-      ...data,
-      active: true,
-      createdAt: new Date(),
-    });
-    return { _id: result.insertedId, ...data };
-  }
-
-  async update(id, data) {
-    const result = await this.#db.collection('coupons').findOneAndUpdate(
-      { _id: id },
-      { $set: { ...data, updatedAt: new Date() } },
-      { returnDocument: 'after' }
-    );
-    return result;
-  }
-
-  async remove(id) {
-    await this.#db.collection('coupons').deleteOne({ _id: id });
-  }
-}
-```
-
----
-
-## 8. Graceful Shutdown
-
-### ✅ DO: graceful shutdown + health check
-
-```js
-// server.js (фрагмент)
-
-/**
- * Настраивает graceful shutdown.
- * @param {import('http').Server} server
- * @param {object} db - database connection.
- */
-function setupGracefulShutdown(server, db) {
-  let isShuttingDown = false;
-
-  async function shutdown(signal) {
-    if (isShuttingDown) return;
-    isShuttingDown = true;
-
-    logger.info({ signal }, 'Graceful shutdown started');
-
-    // 1. Stop accepting new connections
-    server.close(async () => {
-      try {
-        // 2. Close DB connections
-        await db.close();
-        logger.info('Graceful shutdown complete');
-        process.exit(0);
-      } catch (err) {
-        logger.error({ err }, 'Error during shutdown');
-        process.exit(1);
-      }
-    });
-
-    // 3. Force kill after timeout
-    setTimeout(() => {
-      logger.error('Forced shutdown after timeout');
-      process.exit(1);
-    }, 10_000);
-  }
-
-  process.on('SIGTERM', () => shutdown('SIGTERM'));
-  process.on('SIGINT', () => shutdown('SIGINT'));
-
-  // Unhandled errors — log and exit
-  process.on('unhandledRejection', (reason) => {
-    logger.fatal({ reason }, 'Unhandled rejection');
-    process.exit(1);
-  });
-}
-```
-
-### ✅ DO: env validation
-
-```js
-// config/env.js
-import { z } from 'zod';
-
-const envSchema = z.object({
-  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
-  PORT: z.coerce.number().default(3000),
-  DATABASE_URL: z.string().url(),
-  CORS_ORIGIN: z.string().default('*'),
-  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
-});
-
-const parsed = envSchema.safeParse(process.env);
-
-if (!parsed.success) {
-  console.error('❌ Invalid environment variables:', parsed.error.flatten().fieldErrors);
-  process.exit(1);
-}
-
-export const config = parsed.data;
-```
-
----
-
-## 9. Anti-patterns
-
-| ❌ Anti-pattern | ✅ Решение |
-|----------------|-----------|
-| Бизнес-логика в controller | Service layer |
-| SQL/DB в controller | Repository layer |
-| `try/catch` в каждом handler | `asyncHandler` wrapper |
-| `app.listen()` в app.js | Отдельный server.js (тестируемость) |
-| `res.status(500).json({ error: err.message })` | Централизованный error handler |
-| `req.body.email` без валидации | Zod schema + validate middleware |
-| `console.log` для логов | Структурированный logger (pino) |
-| Секреты в коде | Env config + validation |
-| `process.exit()` без cleanup | Graceful shutdown |
-| N+1 запросы в циклах | Batch / aggregate queries |
-| Отсутствие CORS / Helmet | Всегда в middleware pipeline |
-
----
-
-## См. также
-- `$security-baseline-dev` — безопасность в реализации
-- `$observability-logging` — структурированные логи и метрики
-- `$es2025-beast-practices` — современный JavaScript
-- `$testing-strategy-js` — тестирование API (integration tests)
-- `$mongodb-mongoose-best-practices` — MongoDB/Mongoose
+---
+name: node-express-beast-practices
+description: "Node.js + Express — REST API, middleware pipeline, сервисный слой, репозитории, централизованная обработка ошибок, валидация (Zod), graceful shutdown, health checks, security headers. Активируй при написании API, рефакторинге Express-приложений, или при вопросах «как правильно организовать backend на Express»."
+type: discretionary
+domain: development
+owners:
+  - senior_full_stack
+gates:
+  - DEV
+tech:
+  - node
+  - express
+topic:
+  - general
+triggers:
+  - Express API
+  - middleware pipeline
+  - сервисный слой
+  - graceful shutdown Node
+  - health check
+  - security headers
+  - обработка ошибок Express
+related:
+  - node-express-beast-practices-reference
+  - security-baseline-dev
+  - security-baseline-dev-reference
+  - observability-logging
+  - es2025-beast-practices
+  - es2025-beast-practices-reference
+  - testing-strategy-js
+  - mongodb-mongoose-best-practices
+  - mongodb-mongoose-best-practices-reference
+  - tdd-workflow
+  - dev-reference-snippets
+budget_lines: 300
+schema_version: 1
+---
+
+
+# Skill: Node/Express Beast Practices
+
+Decision rules + canonical tables для Express API. Полные DO/DON'T кодовые примеры — в `$node-express-beast-practices-reference`.
+
+**Разделы:**
+1. [Архитектура: слои](#1-архитектура)
+2. [App Factory](#2-app-factory)
+3. [Router + Controller](#3-router--controller)
+4. [Middleware Pipeline](#4-middleware-pipeline)
+5. [Централизованная обработка ошибок](#5-обработка-ошибок)
+6. [Валидация (Zod)](#6-валидация)
+7. [Service + Repository](#7-service--repository)
+8. [Graceful Shutdown и Health Checks](#8-graceful-shutdown)
+9. [Anti-patterns](#9-anti-patterns)
+
+---
+
+## 1. Архитектура
+
+```
+src/
+├── app.js                  # Express app factory (no listen)
+├── server.js               # HTTP server + graceful shutdown
+├── config/env.js           # Env validation + export
+├── middleware/             # errorHandler, requestId, validate, auth
+├── routes/                 # Router aggregation
+├── controllers/            # Thin controllers
+├── services/               # Business logic
+├── repositories/           # Data access
+├── errors/AppError.js      # Custom error classes
+└── utils/asyncHandler.js
+```
+
+### Слои и ответственность
+
+| Слой | Отвечает за | НЕ делает |
+|------|-----------|----------|
+| **Router** | URL → Controller mapping | Бизнес-логику |
+| **Controller** | Парсинг req → вызов service → формирование res | SQL/DB, валидацию |
+| **Middleware** | Кросс-сечения (auth, logging, rate limit) | Бизнес-логику |
+| **Service** | Бизнес-логика, оркестрация | Работу с req/res |
+| **Repository** | Доступ к данным (DB, API) | Бизнес-логику |
+
+---
+
+## 2. App Factory
+
+**Правила:**
+- **app.js отдельно от server.js** — testability (app без listen)
+- **server.js** = HTTP listen + graceful shutdown wiring
+- **deps injection через createApp(deps)** — db, logger, config
+- **errorHandler MUST be last middleware**
+
+> Полный код createApp factory + server.js entry point → `$node-express-beast-practices-reference` §2.
+
+---
+
+## 3. Router + Controller
+
+**Правила:**
+- **Тонкие контроллеры** — парсинг req → вызов service → res; никакой бизнес-логики
+- **Router per domain** — `routes/coupons.router.js` + `controllers/coupons.controller.js`
+- **asyncHandler wrapper** — автоматический catch+next
+- **Class-based controllers** с private fields для service injection
+- Validation middleware **между router и controller** (для каждого write-endpoint)
+
+```js
+// utils/asyncHandler.js
+export function asyncHandler(fn) {
+  return (req, res, next) => {
+    Promise.resolve(fn(req, res, next)).catch(next);
+  };
+}
+```
+
+> Полный код router + controller + DI pattern → `$node-express-beast-practices-reference` §3.
+
+---
+
+## 4. Middleware Pipeline
+
+### Порядок middleware (критически важен)
+
+```
+1. helmet()              — Security headers
+2. cors()                — CORS
+3. express.json()        — Body parsing
+4. compression()         — Response compression
+5. requestIdMiddleware   — x-request-id
+6. requestLogMiddleware  — Access logging
+7. rateLimiter           — Rate limiting
+8. authMiddleware        — Authentication (route-level)
+9. validate(schema)      — Input validation (route-level)
+10. controller           — Business logic
+11. 404 handler          — Not found
+12. errorHandler         — Centralized error (MUST BE LAST)
+```
+
+**Правила:**
+- requestId до логов (для корреляции)
+- rateLimiter перед auth (защита от brute-force на /login)
+- errorHandler **всегда** последний
+
+> Полный код requestId + requestLog middleware → `$node-express-beast-practices-reference` §4.
+
+---
+
+## 5. Обработка ошибок
+
+**Правила:**
+- **Кастомный AppError** с `isOperational = true` (отличает от programmer errors)
+- **Subclass per domain:** NotFoundError, ValidationError, ConflictError, UnauthorizedError, ForbiddenError
+- **Централизованный errorHandler** — `(err, req, res, next)`, 4 параметра обязательны
+- ❌ **NEVER expose stack trace** в production response
+- Operational errors → `warn` + status from err; Programmer errors → `error` + 500 generic
+
+### HTTP Status Codes по контракту
+
+| Код | Когда | Класс |
+|-----|-------|-------|
+| 200 | Успех (GET, PATCH, PUT) | — |
+| 201 | Ресурс создан (POST) | — |
+| 204 | Успех без тела (DELETE) | — |
+| 400 | Невалидные данные | `ValidationError` |
+| 401 | Не аутентифицирован | `UnauthorizedError` |
+| 403 | Нет прав | `ForbiddenError` |
+| 404 | Не найден | `NotFoundError` |
+| 409 | Конфликт (дубликат) | `ConflictError` |
+| 422 | Семантическая ошибка | `AppError(msg, 422)` |
+| 429 | Rate limit exceeded | rate limiter middleware |
+| 500 | Внутренняя ошибка | Programmer error |
+
+> Полный код AppError классов + errorHandler middleware → `$node-express-beast-practices-reference` §5.
+
+---
+
+## 6. Валидация
+
+**Правила:**
+- **Zod schema** per endpoint — body/query/params в одной composed schema
+- **validate(schema) middleware** возвращает 400 с детальным error.issues mapping
+- ✅ Заменяем `req.body/query/params` на parsed (coerced, defaults applied)
+- ❌ Никогда не используй raw `req.body.x` без валидации
+
+> Полный код Zod schemas + validate middleware → `$node-express-beast-practices-reference` §6.
+
+---
+
+## 7. Service + Repository
+
+**Правила:**
+- **Service** — бизнес-логика (uniqueness checks, orchestration, calling repos); throws AppError subclasses
+- **Repository** — только DB операции (find/insert/update/delete); plain async methods
+- **DI через constructor** — `new Service({ db })` → `new Repo(db)`
+- **Private fields** (`#repo`, `#service`) для encapsulation
+- Каждый mutation operation должен вернуть updated entity (для controller)
+
+> Полный код Service + Repository classes (CRUD pattern) → `$node-express-beast-practices-reference` §7.
+
+---
+
+## 8. Graceful Shutdown
+
+**Правила:**
+- **SIGTERM/SIGINT handlers** — `server.close()` → `db.close()` → `process.exit(0)`
+- **isShuttingDown flag** — защита от двойного вызова
+- **Force kill timeout** — 10s default, иначе зависший request заблокирует shutdown
+- **Health endpoint** — `/health` always 200 (для load balancer)
+- **Env validation через Zod** — fail-fast на startup при невалидном config
+
+> Полный код setupGracefulShutdown + env validation (Zod) → `$node-express-beast-practices-reference` §8.
+
+---
+
+## 9. Anti-patterns
+
+| ❌ Anti-pattern | ✅ Решение |
+|----------------|-----------|
+| Бизнес-логика в controller | Service layer |
+| SQL/DB в controller | Repository layer |
+| `try/catch` в каждом handler | `asyncHandler` wrapper |
+| `app.listen()` в app.js | Отдельный server.js (тестируемость) |
+| `res.status(500).json({ error: err.message })` | Централизованный error handler |
+| `req.body.email` без валидации | Zod schema + validate middleware |
+| `console.log` для логов | Структурированный logger (pino) |
+| Секреты в коде | Env config + validation |
+| `process.exit()` без cleanup | Graceful shutdown |
+| N+1 запросы в циклах | Batch / aggregate queries |
+| Отсутствие CORS / Helmet | Всегда в middleware pipeline |
+
+---
+
+## См. также
+- `$node-express-beast-practices-reference` — полный справочник DO/DON'T кода
+- `$security-baseline-dev` — безопасность в реализации
+- `$observability-logging` — структурированные логи и метрики
+- `$es2025-beast-practices` — современный JavaScript
+- `$testing-strategy-js` — тестирование API (integration tests)
+- `$tdd-workflow` — RED→GREEN→REFACTOR для services/controllers
+- `$mongodb-mongoose-best-practices` — MongoDB/Mongoose (repository layer)
+- `$mongodb-mongoose-best-practices-reference` — Mongo code reference
+- `$dev-reference-snippets` — общие dev примеры