docs: каноничный plan.md, остальные планы → [DEPRECATED]

2026-05-30 07:22:49 +03:00
parent f853ed9a6b
commit 09ffa4c385
7 changed files with 644 additions and 632 deletions
@@ -1,118 +1,107 @@
-# ~~План разработки — IP WhiteList Microservice~~ [LEGACY]
+# IP WhiteList — План разработки

-> ⚠️ **УСТАРЕЛО.** Этот план содержит ошибки (async ORM, неполные требования, отсутствие тестов).
-> Актуальный план: `plan-v2.md`
-
-> **Автор:** GitHub Copilot (DeepSeek V4 Flash)
-> **Дата:** 2026-05-29
+> **Дата:** 2026-05-30  
+> **Основание:** [WhiteIPlist.txt](../WhiteIPlist.txt) (ТЗ) + фактический код в [ipwhitelist-app](../../ipwhitelist-app)  
+> **Статус:** каноничный — единственный актуальный план

 ---

-## Стек
+## 1. Текущее состояние

-| Слой | Технология |
-|---|---|
-| Бэкенд | Python 3.11+ / FastAPI |
-| БД | PostgreSQL |
-| ORM | SQLAlchemy (async) + Alembic (миграции) |
-| Фронтенд | Jinja2 + HTMX + минимальный CSS |
-| Авторизация | Keycloak OIDC (на старте — заглушка/мок) |
-| Валидация | Pydantic + встроенный `ipaddress` |
+### Готово ✅
+
+| Слой | Файлы | Что есть |
+|---|---|---|
+| БД | `sql/schema.sql` | `companies`, `whitelist_entries` (soft delete), `audit_log` + индексы |
+| Валидатор | `src/validators.js` | Все 14 запрещённых диапазонов Приложения А, /22–/32, нормализация host-битов, проверка пересечений |
+| CRUD | `src/queries.js` | `createEntry`, `updateEntry`, `deleteEntry` (soft), `listEntries`, `getExportCIDRs`, `getAudit`, `getLimit` |
+| UI | `views/index.ejs` | Список, форма добавления, кнопка удаления, стиль Nubes |
+| Роуты | `server.js` | `GET /`, `POST /add`, `POST /delete/:id`, `GET /export`, `GET /healthz` |
+
+### Написано в queries.js, но не подключено к роутам
+
+- `updateEntry` — нет `POST /update/:id`, нет UI редактирования
+- `getAudit` — нет страницы аудита
+- `listEntries(companyId, includeDeleted=true)` — флаг есть, не используется

 ---

-## Этапы
+## 2. Что требует ТЗ, но отсутствует

-### Этап 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 или ручная инструкция
+| # | Требование | Готовность |
+|---|---|---|
+| 1 | Редактирование записи из UI | ❌ queries есть, роута нет |
+| 2 | Админ-панель (все компании, лимиты, аудит, фильтры) | ❌ |
+| 3 | OIDC Keycloak вместо base64-заглушки | ❌ |
+| 4 | Суммаризация CIDR в `/export` | ❌ отдаёт сырой список |
+| 5 | Клиентская валидация (JS в форме) | ❌ |
+| 6 | Переключатель компаний (multi-company) | ❌ |
+| 7 | Просмотр soft-deleted записей админом | ❌ |
+| 8 | Изменение `custom_limit` для компании | ❌ |

 ---

-## Файловая структура (план)
+## 3. Порядок реализации
+
+### Этап 1 — Пользовательский сценарий (client-flow)
+
+- [x] Валидатор IPv4/CIDR — полный
+- [x] Создание / удаление / экспорт
+- [ ] **Добавить `POST /update/:id`** в `server.js`
+- [ ] **Добавить inline-форму редактирования** в `views/index.ejs`
+- [ ] **Клиентская валидация** (JS: формат, маска, длина комментария)
+
+### Этап 2 — Административная панель
+
+- [ ] Определение admin-роли (`clientId === 'WZ01112'` + чекбокс)
+- [ ] `GET /admin` — страница со всеми компаниями
+- [ ] `POST /admin/limit/:companyId` — изменение custom_limit
+- [ ] `GET /admin/audit` — журнал аудита
+- [ ] Фильтр по компании + показ удалённых записей
+
+### Этап 3 — Авторизация Keycloak OIDC
+
+- [ ] `npm install openid-client`
+- [ ] Замена base64-decode на проверку подписи JWT
+- [ ] Маппинг claims → `req.user` (clientId, email, role)
+- [ ] Оставить `DEV_MODE` только для локальной разработки
+
+### Этап 4 — Экспорт и Multi-company
+
+- [ ] `npm install cidr-tools` — суммаризация в `GET /export`
+- [ ] Переключатель активной компании (если несколько `clientId` в claims)
+
+### Этап 5 — Завершение
+
+- [ ] Автотесты (`jest` + `supertest`)
+- [ ] Пагинация (если лимит > 50)
+- [ ] Сверка всех пунктов ТЗ
+
+---
+
+## 4. Что НЕ делать
+
+- ❌ Не переписывать на Python/FastAPI
+- ❌ Не менять схему БД
+- ❌ Не переписывать `validators.js` (он полный)
+- ❌ Не переписывать `queries.js`
+- ❌ Не делать SPA
+
+---
+
+## 5. Зависимости для установки

 ```
-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
+npm install cidr-tools openid-client
+npm install --save-dev jest supertest
 ```
+
+Всё остальное — в рамках Express + EJS + pg.
+
+---
+
+## 6. Риски
+
+- **Admin-роль:** неясно как «отдельный чек-бокс» из ТЗ попадает в токен — требует уточнения с командой Keycloak
+- **Multi-company claims:** ТЗ говорит о нескольких компаниях, но в claims только `clientID` — нужен реальный формат
+- **IP-ограничение `/export`:** делать в приложении или на уровне ingress — решить при деплое