ipam_control/docs/changes/001-ipam-backend/PLAN.md

# IPAM Manager — backend (Python + PostgreSQL) и UI-админка

## Context
Есть макеты «IPAM Manager» (страница 2 канваса): Обзор, Префиксы (дерево, VRF), Адреса в подсети,
Организации, Операторы связи, Устройства (+ типы), Журнал, диалоги создания/редактирования.
Проект пуст. Нужно спроектировать и реализовать API-first приложение: backend на Python с PostgreSQL,
UI-админка — отдельный лёгкий фронт (без сборки), который только визуализирует ответы API.

Решения (согласованы): FastAPI + SQLAlchemy 2 + Alembic + psycopg3; UI — статический SPA (Alpine.js + fetch),
раздаётся тем же приложением; auth — локальные пользователи + JWT; окружение — Docker Compose (postgres + app),
venv в корне для тестов/линтеров.

## Доменная модель (PostgreSQL)
Нативные типы `CIDR` / `INET` — сравнения, вложенность (`<<=`, `>>=`) и семейство (`family()`) считает БД.

| Таблица | Ключевые поля |
|---|---|
| `organizations` | name, short_name, inn (uniq), address, contact_person, phone, email, note |
| `vrfs` | organization_id, name, route_target, note; uniq(org, name) |
| `prefixes` | organization_id, vrf_id, prefix CIDR, description, status (active/reserved/deprecated), parent_id (авто по вложенности, можно задать), is_pool, note; uniq(vrf, prefix) |
| `addresses` | prefix_id, address INET, status (assigned/reserved/deprecated), dns_name, description, device_id, note, updated_at; uniq(prefix, address); CHECK «адрес ∈ префикс» на уровне сервиса |
| `isps` | name, organization_id, contract_number, hotline, note |
| `isp_networks` | isp_id, cidr (несколько IP-блоков на оператора) |
| `device_types` | name (uniq), is_default |
| `devices` | name (hostname), device_type_id, mac, organization_id, note |
| `users` | username (uniq), password_hash (argon2), role (admin/viewer), is_active |
| `audit_log` | ts, user_id, entity_type, entity_id, entity_label, action (created/updated/deleted/assigned), diff JSONB |

Вычисляемое (не хранится): использование префикса (назначено/ёмкость), «свободные» адреса (в макете статус
«Свободен» — пропуски в диапазоне), число префиксов/адресов у организации, число устройств у типа, число IP у устройства.
Правила: VRF/тип нельзя удалить, пока используются (в макете кнопка disabled) → 409.

## API (`/api/v1`, OpenAPI на `/docs`)
- `auth`: `POST /auth/login`, `GET /auth/me` (logout — на клиенте, токен короткоживущий).
- `overview`: `GET /overview` — карточки (префиксов, VRF, адресов, использование, резерв), топ загрузки, последние изменения.
- `organizations`, `isps`, `devices`, `device-types`, `vrfs`: CRUD; списки с `q`, `limit`, `offset`, фильтры (org, тип, vrf).
- `prefixes`: CRUD; `GET /prefixes?org=&vrf=&status=&family=&q=` (дерево через parent_id + utilization);
  счётчики вкладок VRF; `GET /prefixes/{id}`.
- `prefixes/{id}/addresses`: список (`status`, `q`, `limit`/`offset` — «Показать ещё 100»), `POST` назначить,
  `POST .../next` — автоназначение из пула (`is_pool`), сводка «назначено/резерв/свободно».
- `addresses/{id}`: PATCH/DELETE.
- `audit`: `GET /audit` (фильтры, пагинация) — источник «Последних изменений»; полный экран «Журнал» — вне этого этапа.
- Единый формат ошибок `{code, message, fields}`; валидация CIDR/IP/MAC/FQDN в pydantic; 409 на дубли и пересечения.
- Запись в `audit_log` — в сервисном слое в одной транзакции с изменением.

## Структура репозитория
```
app/ main.py config.py db.py security.py
     models/ schemas/ services/ api/v1/
alembic/ (миграция 0001 — вся схема + seed: admin, типы устройств)
web/     index.html, app.js, api.js, styles.css  (IBM Plex, токены цвета из макетов)
tests/   (минимум)
docs/changes/001-ipam-backend/ PLAN.md, SUMMARY.md
docker-compose.yml  Dockerfile  .env.example  requirements.txt  README.md  venv/ (в .gitignore)
```

## UI (web/)
Экраны 1:1 с макетами: логин, Обзор, Префиксы (вкладки VRF, фильтры, «Управление VRF»), Адреса подсети,
Организации, Операторы, Устройства («Управление типами»), модальные формы. Только `fetch` к `/api/v1`, JWT в
`sessionStorage`; 401 → экран логина. Пункт «Журнал» — заглушка со ссылкой на `/audit` (по вопросу №1 из макета).

## Порядок работ (по артефактам из CLAUDE.md)
0. Создать `docs/changes/001-ipam-backend/PLAN.md` (этот план) — до кода.
1. Каркас: docker-compose (postgres:16 + app), Dockerfile, config, venv, Alembic.
2. Модели + миграция 0001 + seed.
3. Auth (login/JWT/роли; viewer — только чтение).
4. Справочники: организации, VRF, операторы, типы, устройства.
5. Префиксы и адреса: вложенность, использование, next-free, проверка «адрес ∈ префикс», пересечения в VRF.
6. Обзор + audit.
7. UI SPA.
8. Тесты, обновить `README.md`, написать `SUMMARY.md`.

## Тесты (минимум, pytest + реальный Postgres из compose)
1. Логин → защищённый эндпоинт (401 без токена, 200 с токеном).
2. Префикс: дубль в VRF → 409; адрес вне префикса → 422.
3. Использование префикса и next-free считаются верно.
4. Удаление VRF/типа «в использовании» → 409.

## Проверка end-to-end
`docker compose up -d --build` → `alembic upgrade head` отрабатывает автоматически → `pytest` зелёный →
открыть `http://localhost:8000/` (UI), войти `admin`, пройти сценарий: организация → VRF → префикс →
назначить адрес → увидеть его в Обзоре и в audit. `http://localhost:8000/docs` — Swagger.

## Допущения (скажите, если не так)
- VRF принадлежит организации (в макете «общий список для организации»).
- Свободные адреса вычисляются, а не хранятся.
- Экран «Журнал» с ротацией/очисткой (страница ROS Manager) в этот этап не входит — только запись и чтение audit.
- Начальный пароль admin задаётся через `.env`, не хардкодится.

## Уточнения по итогам утверждения
- План утверждён пользователем; сохранён в этом файле до начала кода.
- Тесты выполняются против приложения, поднятого в контейнерах (docker compose). Учётные данные для тестов
  генерируются автоматически (случайные пароль admin и секрет JWT в `.env`, файл в .gitignore). Контейнеры локальные, без внешнего доступа.
- Сборка и запуск вспомогательных инструментов (pytest, линтеры, alembic) — из `venv/` в корне проекта.
- Обязательная сверка UI собранного приложения с макетами (все экраны и диалоги страницы «IPAM Manager»);
  расхождения устраняются до завершения работы, результат сверки фиксируется в SUMMARY.md.