init: ТЗ, правила copilot, планы от моделей (DeepSeek, Claude, GPT-5.4, Gemini)

2026-05-29 19:54:41 +03:00
commit 65de34ba4a
6 changed files with 948 additions and 0 deletions
@@ -0,0 +1,118 @@
+# ~~План разработки — 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
+```