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

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,