From e90b0454c1a349c709aedcf6f185b7ccb967e72d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E2=80=9CNaeel=E2=80=9D?= <tazet@narod.ru>
Date: Sun, 31 May 2026 12:37:49 +0300
Subject: [PATCH] =?UTF-8?q?docs:=20README=20=E2=80=94=20quick=20start,=20a?=
 =?UTF-8?q?rchitecture,=20roles,=20deploy?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..cd40d42
--- /dev/null
+++ b/README.md
@@ -0,0 +1,59 @@
+# IP WhiteList
+
+Self-service портал управления доверенными IPv4-адресами клиентов облачного провайдера.
+Записи исключаются из блокировки системами фильтрации во время DDoS-атак.
+
+**[Техническое задание](docs/ТЗ.md)** · **[Отчёт о соответствии ТЗ](docs/TZ-COMPLIANCE-REPORT.md)**
+
+## Быстрый старт
+
+```bash
+npm install
+cp .env.example .env   # заполнить переменные
+npm start              # http://localhost:3000
+npm test               # 104 API-теста
+npm run test:stress    # 191 стресс-тест
+```
+
+## Переменные окружения
+
+| Переменная | Назначение | По умолчанию |
+|---|---|---|
+| `DEV_MODE` | mock-аутентификация (`true` в dev, **запрещён** в prod) | — |
+| `ADMIN_CLIENT_ID` | clientId администратора | `WZ01112` |
+| `DEFAULT_LIMIT` | лимит записей на компанию | `15` |
+| `DATABASE_URL` | строка подключения PostgreSQL | — |
+| `SESSION_SECRET` | секрет сессий (**обязателен** в prod) | — |
+
+[Полный список в AGENT.md](AGENT.md#4-переменные-окружения)
+
+## Стек
+
+Node.js 18+ / Express 4 / EJS / PostgreSQL 17 / jsonwebtoken RS256
+
+## Архитектура
+
+```
+Browser → UI (EJS, сессия) → api-client → REST API (Bearer JWT) → PostgreSQL
+```
+
+Два слоя: SSR UI для браузера и JSON API для внешних потребителей.
+API — Bearer-only (без сессий), UI — сессия + Bearer-токен внутри.
+
+**[Подробная карта файлов в AGENT.md](AGENT.md#5-структура-файлов--карта-ответственности)**
+
+## Роли
+
+| Роль | clientId | Права |
+|---|---|---|
+| Клиент | Любой | CRUD своих записей в пределах лимита |
+| Администратор | `WZ01112` | CRUD всех записей, изменение лимитов, аудит |
+
+## Деплой
+
+Платформа: Nubes k8s. Редеплой — через Nubes UI из Gitea после `git push`.
+Production URL: `https://white.nodejsk8s.dev.nubes.ru`
+
+## Разработка
+
+Перед любой задачей читать [`AGENT.md`](AGENT.md) — полное руководство для агентов и разработчиков.