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