nettopo-go/TECH_SPEC.md

Техническое задание (v1)

Цель

Создать кроссплатформенное веб-приложение на Go для:

• обнаружения устройств в сети;
• базовой идентификации устройств;
• получения LLDP-соседей;
• построения карты связей между устройствами.

Платформы и запуск

• Backend: Go 1.22+
• ОС: Linux и Windows
• Запуск: стандартными средствами (без Docker)
• Reverse proxy: Nginx (Linux) или IIS (Windows, опционально)

Функциональные требования v1

• ручной запуск скана по заданным CIDR;
• ping sweep по диапазонам;
• проверка базовых TCP-портов (22, 80, 443, 161);
• SNMP v2c: sysName, sysDescr, sysObjectID;
• сбор LLDP соседей по SNMP;
• сохранение результатов скана в БД;
• построение базового графа связей устройств (/links, /topology);
• история сканов и сравнение изменений (/api/scans/diff?from=&to=).

Нефункциональные требования

• кроссплатформенная сборка (Linux/Windows);
• устойчивость к частичным ошибкам в сети;
• конфигурируемые таймауты и параллелизм;
• разграничение прав (admin, viewer);
• логирование ошибок и действий.

Архитектура

• cmd/server — запуск HTTP API
• internal/api — обработчики и роуты
• internal/scans — логика создания/ведения scan jobs
• internal/scanner/* — ping, ports, snmp, lldp (поэтапно)
• internal/store — миграции PostgreSQL
• web — интерфейс (следующий этап)

Текущее состояние реализации

• готов API-каркас (health, создание и чтение scan jobs);
• реализован выбор хранилища: memory или postgres через env;
• добавлены автоматические миграции таблиц при старте;
• добавлены endpoints результатов: hosts, ports, snmp, lldp, links, topology;
• подготовлены конфиги для запуска как сервис на Linux и за IIS на Windows.

Минимальные API

• GET /health
• POST /api/scans
• GET /api/scans/{id}
• GET /api/scans/{id}/topology
• GET /api/scans/diff?from=&to=

Модель данных (минимум)

• users
• snmp_credentials
• scan_jobs
• devices
• open_ports
• lldp_neighbors
• links

SNMP OID минимум

• 1.3.6.1.2.1.1.5.0 (sysName)
• 1.3.6.1.2.1.1.1.0 (sysDescr)
• 1.3.6.1.2.1.1.2.0 (sysObjectID)
• 1.0.8802.1.1.2.1.4.1.1.5 (lldpRemChassisId)
• 1.0.8802.1.1.2.1.4.1.1.7 (lldpRemPortId)
• 1.0.8802.1.1.2.1.4.1.1.9 (lldpRemSysName)

Этапы

1. Каркас API и scan jobs
2. PostgreSQL и миграции
3. Ping + port scan
4. SNMP system + LLDP
5. Граф топологии в UI
6. История и diff

Критерии приемки v1

• скан по CIDR создается и завершается;
• живые узлы фиксируются в результатах;
• SNMP-доступные устройства читаются;
• LLDP-связи строятся минимум на тестовой сети;
• топология отображается в интерфейсе;
• приложение запускается на Linux и Windows (нужна ваша проверка на 2 ОС).