IPWhiteList/docs/plan.md

План разработки — IP WhiteList Microservice [LEGACY]

⚠️ УСТАРЕЛО. Этот план содержит ошибки (async ORM, неполные требования, отсутствие тестов). Актуальный план: plan-v2.md

Автор: GitHub Copilot (DeepSeek V4 Flash) Дата: 2026-05-29

---

Стек

Слой	Технология
Бэкенд	Python 3.11+ / FastAPI
БД	PostgreSQL
ORM	SQLAlchemy (async) + Alembic (миграции)
Фронтенд	Jinja2 + HTMX + минимальный CSS
Авторизация	Keycloak OIDC (на старте — заглушка/мок)
Валидация	Pydantic + встроенный ipaddress

---

Этапы

Этап 1 — Каркас проекта

• Структура проекта: app/, templates/, static/, migrations/
• requirements.txt (FastAPI, SQLAlchemy, asyncpg, Alembic, Jinja2, python-keycloak)
• Конфигурация (.env, config.py)
• docker-compose.yml с PostgreSQL

Этап 2 — Модели БД и миграции

• Модель Company (id, clientId, name, individual_limit)
• Модель WhitelistEntry (id, company_id, value, comment, created_by, created_at, updated_at, deleted_at, deleted_by)
• Модель AuditLog (id, user_email, company_id, action, old_value, new_value, timestamp)
• Alembic initial migration

Этап 3 — Валидация IPv4

• Валидатор: одиночный IPv4 / CIDR
• Проверка маски: /32 – /22 (шире /21 — отказ)
• Нормализация host-битов в 0
• Запрет серых/приватных диапазонов (Приложение А из ТЗ)
• Проверка дубликатов и пересечений в пределах компании

Этап 4 — CRUD + Бизнес-логика

• Создание записи (с проверкой лимита)
• Просмотр таблицы записей (для клиента — свои компании, для админа — все)
• Редактирование (с повторной валидацией)
• Soft delete (deleted_at, deleted_by)
• Лимиты: глобальный default 15, индивидуальный per-company

Этап 5 — Аудит

• Запись всех изменяющих операций в AuditLog
• Просмотр журнала (только админ)

Этап 6 — Внешний endpoint

• GET /api/v1/whitelist/aggregated — txt-файл
• Суммаризация (агрегация) CIDR всех компаний
• Только активные (не soft-deleted) записи

Этап 7 — Авторизация (заглушка → Keycloak)

• Заглушка: header X-Client-ID, X-User-Email, X-Role
• Роли: client / admin
• Переключатель компаний (для пользователей в нескольких компаниях)
• Позже: полноценный OIDC через Keycloak

Этап 8 — UI (Jinja2 + HTMX)

• Страница входа / редирект на Keycloak
• Таблица записей с фильтрами
• Форма создания/редактирования (с клиентской валидацией)
• Индикатор лимита: «использовано X из N»
• Админка: фильтр по компаниям, просмотр удалённых, журнал аудита

Этап 9 — Деплой

• Systemd unit / Dockerfile
• Nginx reverse proxy (если нужно)
• CI/CD или ручная инструкция

---

Файловая структура (план)

IPWhiteList/
├── app/
│   ├── __init__.py
│   ├── main.py              # FastAPI app
│   ├── config.py             # Настройки из .env
│   ├── models.py             # SQLAlchemy модели
│   ├── schemas.py            # Pydantic схемы
│   ├── validators.py         # IPv4/CIDR валидация
│   ├── crud.py               # CRUD-операции
│   ├── auth.py               # Авторизация (заглушка → Keycloak)
│   ├── routers/
│   │   ├── __init__.py
│   │   ├── entries.py        # CRUD whitelist
│   │   ├── admin.py          # Админка
│   │   └── external.py       # Внешний endpoint
│   └── utils.py              # Суммаризация CIDR, лимиты
├── templates/
│   ├── base.html
│   ├── index.html            # Таблица записей
│   ├── entry_form.html       # Форма создания/редактирования
│   └── admin/
│       ├── audit.html        # Журнал аудита
│       └── limits.html       # Управление лимитами
├── static/
│   └── style.css
├── migrations/
│   └── alembic/
├── docs/
│   ├── plan.md               # Этот файл
│   └── WhiteIPlist.docx      # Исходное ТЗ
├── .env.example
├── docker-compose.yml
├── requirements.txt
└── README.md