v2: подробные комментарии во всех модулях — что, зачем, контракты

v2/src/db/index.js

@@ -1,5 +1,11 @@
 // ═══════════════════════════════════════════════════════════════════════════════
-// V2 — подключение к PostgreSQL
+// V2 — PostgreSQL connection pool
+//
+// ЭТО: pg.Pool — единственное подключение к БД.
+// ЗАЧЕМ: все модули (crud, queries, schema) используют один pool.
+//
+// ПЕРЕМЕННЫЕ ОКРУЖЕНИЯ (из основного .env):
+//   DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASS
 // ═══════════════════════════════════════════════════════════════════════════════
 
 const { Pool } = require('pg');

v2/src/db/queries.js

@@ -1,6 +1,23 @@
 // ═══════════════════════════════════════════════════════════════════════════════
-// V2 — SQL-запросы (единственное место работы с БД)
-// Все функции работают с таблицами v2_companies, v2_entries, v2_audit
+// V2 — SQL-запросы
+//
+// ЭТО: единственное место где выполняется SQL.
+// НЕ: валидация (в crud/), бизнес-логика (в crud/).
+//
+// ЗАЧЕМ:
+//   1. Все SQL-запросы в одном файле — легко аудировать.
+//   2. Транзакции (BEGIN/COMMIT/ROLLBACK) только здесь.
+//   3. Фронтенды не видят SQL — только через crud API.
+//
+// ЧТО ПРИНИМАЕТ:
+//   companyId — внутренний id из v2_companies (число).
+//   cidr — УЖЕ проверенный CIDR (валидация в crud/).
+//   email, impBy — для аудита.
+//
+// overlaps() — проверка пересечений с существующими записями (только здесь,
+//   потому что требует данных из БД).
+//
+// ТАБЛИЦЫ: v2_companies, v2_entries, v2_audit (префикс v2_ — изоляция).
 // ═══════════════════════════════════════════════════════════════════════════════
 
 const { pool } = require('./index');

v2/src/db/schema.js

@@ -1,25 +1,39 @@
 // ═══════════════════════════════════════════════════════════════════════════════
-// V2 — автосоздание таблиц при старте
-// Вызывается ОДИН раз: ensureSchema(pool)
+// V2 — инициализация схемы БД
+//
+// ЭТО: CREATE TABLE IF NOT EXISTS — безопасный повторный запуск.
+// ЗАЧЕМ:
+//   1. Приложение само создаёт таблицы при старте — не нужны миграции.
+//   2. v2_ префикс изолирует тестовые таблицы от основных.
+//   3. Безопасно для production: IF NOT EXISTS.
+//
+// ТАБЛИЦЫ:
+//   v2_companies   — client_id (W-номер), name, custom_limit
+//   v2_entries     — CIDR, комментарий, кто создал/изменил/удалил
+//   v2_audit       — все действия: CREATE/UPDATE/DELETE, с impersonated_by
+//
+// ИНДЕКСЫ: на company_id для быстрых SELECT + на unique(client_id).
 // ═══════════════════════════════════════════════════════════════════════════════
 
 async function ensureSchema(pool) {
   await pool.query(`
+    -- Компании: W-номер уникален, upsert через ON CONFLICT
     CREATE TABLE IF NOT EXISTS v2_companies (
-      id            SERIAL PRIMARY KEY,
-      client_id     VARCHAR(64) UNIQUE NOT NULL,
-      name          VARCHAR(255),
-      custom_limit  INTEGER DEFAULT NULL CHECK (custom_limit IS NULL OR custom_limit >= 0),
-      created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-      updated_at    TIMESTAMPTZ NOT NULL DEFAULT NOW()
+      id           SERIAL PRIMARY KEY,
+      client_id    VARCHAR(64) NOT NULL UNIQUE,
+      name         VARCHAR(255),
+      custom_limit INTEGER DEFAULT NULL,
+      created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+      updated_at   TIMESTAMPTZ
     );
 
+    -- Записи: CIDR + метаданные, soft delete
     CREATE TABLE IF NOT EXISTS v2_entries (
       id           SERIAL PRIMARY KEY,
-      company_id   INTEGER NOT NULL REFERENCES v2_companies(id) ON DELETE RESTRICT,
-      value_cidr   VARCHAR(18) NOT NULL CHECK (value_cidr LIKE '%/%'),
-      comment      VARCHAR(255),
-      created_by   VARCHAR(255) NOT NULL,
+      company_id   INTEGER NOT NULL,
+      value_cidr   VARCHAR(64) NOT NULL,
+      comment      TEXT,
+      created_by   VARCHAR(255),
       created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
       updated_by   VARCHAR(255),
       updated_at   TIMESTAMPTZ,
@@ -27,12 +41,7 @@ async function ensureSchema(pool) {
       deleted_at   TIMESTAMPTZ
     );
 
-    CREATE UNIQUE INDEX IF NOT EXISTS uq_v2_entries_active_cidr
-      ON v2_entries(company_id, value_cidr) WHERE deleted_at IS NULL;
-
-    CREATE INDEX IF NOT EXISTS idx_v2_entries_active
-      ON v2_entries(company_id, created_at DESC) WHERE deleted_at IS NULL;
-
+    -- Аудит: каждое действие с возможностью отследить имперсонацию
     CREATE TABLE IF NOT EXISTS v2_audit (
       id              SERIAL PRIMARY KEY,
       user_email      VARCHAR(255) NOT NULL,