# ~~План разработки — 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
```