Система прослеживаемости OKTO - Руководство пользователя¶

Полное руководство для операторов, менеджеров и администраторов.

Содержание¶

Начало работы
Режимы подключения
Активация устройства
Ежедневные операции
Тестовый режим
Администрирование
Устранение неполадок

Начало работы¶

Системные требования¶

Аппаратное обеспечение: - Linux система x86_64 (Ubuntu 20.04+, Debian 11+ или аналогичные) - Минимум 2ГБ ОЗУ, рекомендуется 4ГБ - 10ГБ дискового пространства - Сетевое подключение (рекомендуется Ethernet)

Дополнительное оборудование: - Сканер штрихкодов (Matrix, Honeywell или совместимый) - Принтер этикеток (Videojet, Markem или ZPL-совместимый) - ПЛК с поддержкой MODBUS TCP

Программное обеспечение: - Docker и Docker Compose (рекомендуется) - Или: JDK 17+, Node.js 20+ (для нативной установки)

Установка¶

Установка через Docker (рекомендуется)¶

# Клонирование или загрузка системы
cd /opt
git clone <repository-url> okto-traceability
cd okto-traceability

# Запуск всех сервисов
docker-compose up -d

# Проверка статуса
docker-compose ps

Нативная установка¶

# Сборка системы
make build

# Запуск граничного сервиса
./gradlew :edge-service:run

# В другом терминале запустите UI оператора
cd operator-ui && npm run dev

Первый вход¶

Откройте веб-браузер
Перейдите на http://localhost:3000 (UI оператора)
Войдите с учетными данными по умолчанию:
Логин: operator
Пароль: operator123

⚠️ Безопасность: Немедленно измените пароли по умолчанию в продакшене!

Режимы подключения¶

Система поддерживает два режима подключения для различных сценариев развертывания.

Режим через локальный сервер¶

Лучше всего подходит для: Фабрик с центральной инфраструктурой, множества производственных линий

[Граничные устройства] → [Фабричный сервер] → [Облако OKTO]

Преимущества: - Централизованное управление - Лучшая устойчивость сети - Локальная агрегация данных - Снижение облачного трафика

Настройка: 1. Разверните фабричный сервер 2. Настройте граничные сервисы для подключения к фабричному серверу 3. Фабричный сервер управляет облачной синхронизацией

Режим прямого подключения к облаку¶

Лучше всего подходит для: Автономных развертываний, удаленных локаций, пилотных программ

[Граничное устройство] → [Облако OKTO]

Преимущества: - Простое развертывание - Не требуется фабричный сервер - Прямая облачная интеграция

Настройка: 1. Разверните только граничный сервис 2. Настройте режим прямого подключения к облаку 3. Активируйте устройство с облачными учетными данными

Проверка текущего режима¶

В UI оператора: 1. Перейдите в Настройки (значок шестеренки) 2. Найдите раздел Режим подключения 3. Текущий режим отображается: "Прямое облако" или "Через локальный сервер"

Переключение режимов¶

Если переключение режимов разрешено:

Перейдите в Настройки → Режим подключения
Выберите нужный режим
Нажмите Применить
Система переподключится

Примечание: Переключение режимов может потребовать повторной активации в режиме прямого облака.

Активация устройства¶

Активация устройства требуется для режима прямого подключения к облаку для аутентификации устройства в облаке OKTO.

Предварительные требования¶

Действующая учетная запись облака OKTO
Устройство зарегистрировано на портале вашей компании в облаке OKTO
Сетевой доступ к app.okto.ru

Шаги активации¶

Шаг 1: Открытие страницы активации¶

Перейдите на http://localhost:3000/provision

Вы увидите мастер активации.

Шаг 2: Вход в систему¶

Введите email облака OKTO
Введите пароль
Нажмите Войти

┌────────────────────────────────────────┐
│       Вход в облако OKTO               │
│                                        │
│  Email: [your.email@company.com    ]   │
│                                        │
│  Пароль: [••••••••••               ]   │
│                                        │
│           [ Войти ]                    │
└────────────────────────────────────────┘

Шаг 3: Выбор устройства¶

После входа вы увидите доступные устройства:

┌────────────────────────────────────────┐
│         Выберите устройство            │
│                                        │
│  ○ Производственная линия 1            │
│    Компания: ООО "Демо Фабрика"        │
│                                        │
│  ● Производственная линия 2            │  ← Выбрано
│    Компания: ООО "Демо Фабрика"        │
│                                        │
│  ○ Станция контроля качества           │
│    Компания: ООО "Демо Фабрика"        │
│                                        │
│           [ Активировать ]             │
└────────────────────────────────────────┘

Выберите устройство и нажмите Активировать.

Шаг 4: Подтверждение¶

При успешной активации:

┌────────────────────────────────────────┐
│      ✓ Устройство активировано!        │
│                                        │
│  Устройство: Производственная линия 2  │
│  Компания: ООО "Демо Фабрика"          │
│  Отрасль: Молоко                       │
│                                        │
│  Ваше устройство теперь подключено к   │
│  облаку OKTO и готово к работе.        │
│                                        │
│      [ Перейти к панели ]              │
└────────────────────────────────────────┘

Деактивация¶

Для сброса активации (например, для смены устройства):

Перейдите на страницу активации
Нажмите Деактивировать (если уже активировано)
Подтвердите действие
Повторите активацию с новым устройством

Ежедневные операции¶

Начало рабочей смены¶

Войдите в UI оператора
Проверьте подключение: индикатор статуса (зеленый = подключено)
Выберите производственную линию (если несколько)
Начинайте сканирование

Сканирование кодов¶

Система обрабатывает сканы штрихкодов автоматически:

┌────────────────────────────────────────────────────────┐
│                    Статус сканирования                  │
├────────────────────────────────────────────────────────┤
│  Сканер: ● Подключен                                   │
│  Режим: Производство                                   │
│                                                         │
│  Последний скан: 010460000000001721ABC123...           │
│  Статус: ✓ Принят                                      │
│                                                         │
│  Статистика за сегодня:                                │
│  ├── Отсканировано: 1 234                              │
│  ├── Принято: 1 220                                    │
│  ├── Отклонено: 10                                     │
│  └── Дубликатов: 4                                     │
└────────────────────────────────────────────────────────┘

Статусы сканирования¶

Статус	Значение	Действие
✓ Принят	Код валиден и записан	Продолжайте сканирование
✗ Отклонен	Неверный формат кода	Проверьте продукт/этикетку
⚠ Дубликат	Код уже отсканирован	Удалите дублирующий элемент
? Неизвестно	Ошибка обработки	Повторите или проверьте систему

Создание коробов¶

Бутылки группируются в коробы:

Начать новый короб: Нажмите Новый короб или скан запускает автосоздание
Сканируйте бутылки: Добавляйте бутылки в текущий короб
Завершить короб: Нажмите Закрыть короб когда полон

┌────────────────────────────────────────────────────────┐
│              Текущий короб: B-2024-001234              │
├────────────────────────────────────────────────────────┤
│  Статус: В процессе                                    │
│  Бутылок: 45 / 50 (90%)                               │
│                                                         │
│  [■■■■■■■■■■■■■■■■■■░░]                                │
│                                                         │
│  [ Закрыть короб ]  [ Отменить короб ]                │
└────────────────────────────────────────────────────────┘

Создание паллет¶

Коробы группируются в паллеты:

Начать новую паллету: Нажмите Новая паллета
Сканируйте коробы: Сканируйте этикетки коробов для добавления
Завершить паллету: Нажмите Закрыть паллету когда полна

Обработка ошибок¶

Неверный код¶

Ошибка: Код отклонен - Неверный GTIN

Причина: Код не соответствует ожидаемому GTIN продукта
Действие: Убедитесь, что сканируете правильный продукт

Дубликат кода¶

Предупреждение: Обнаружен дубликат кода

Причина: Этот код уже был отсканирован
Действие: Удалите дублирующий элемент из производства

Потеря соединения¶

Предупреждение: Режим offline - данные синхронизируются при подключении

Причина: Потеряно сетевое соединение
Действие: Продолжайте работу, данные синхронизируются автоматически при восстановлении связи

Тестовый режим¶

Тестовый режим позволяет тестировать весь функционал без подключения к облаку OKTO.

Активация тестового режима¶

Перейдите на страницу активации (/provision)
Быстро наберите tttt (в течение 2 секунд)
Вы увидите: "Тестовый режим активирован"
Демо-учетные данные появятся автоматически
Нажмите Войти

┌────────────────────────────────────────┐
│     🔧 ТЕСТОВЫЙ РЕЖИМ АКТИВИРОВАН 🔧   │
│                                        │
│  Email: [demo@okto.ru            ]     │
│  Пароль: [demo123                ]     │
│                                        │
│  ⚠ Это тестовая среда.                 │
│  Данные не будут отправлены в облако.  │
│                                        │
│           [ Войти ]                    │
└────────────────────────────────────────┘

Индикатор тестового режима¶

Когда тестовый режим активен, вы увидите баннер:

┌────────────────────────────────────────────────────────┐
│  ⚠ ТЕСТОВЫЙ РЕЖИМ - Нет облачного подключения        │
│                                     [Выйти из теста]   │
└────────────────────────────────────────────────────────┘

Симулятор сканера¶

Тестовый режим включает симулятор сканера для тестирования:

┌─────────────────────────────────┐
│      Симулятор сканера          │
├─────────────────────────────────┤
│  Код: [                    ]    │
│                                 │
│  [ Сгенерировать случайный ]    │
│  [ Симулировать скан       ]    │
│                                 │
│  ─────────────────────────────  │
│  Отрасль: [ Молоко       ▼]     │
│  Режим:   ○ Один  ● Пакетный   │
│  Скорость: [████░░░░░░] 5/сек  │
└─────────────────────────────────┘

Возможности: - Ручной ввод: Введите код и нажмите "Симулировать скан" - Генерация случайных: Создание валидных кодов для выбранной отрасли - Пакетный режим: Симуляция быстрого сканирования для стресс-тестирования

Демо-данные¶

Тестовый режим включает предварительно настроенные данные:

Данные	Значение
Компания	ООО "Демо Фабрика"
Отрасль	Молоко
Устройства	3 демо-устройства
Линии	2 производственные линии
GTIN продукта	04600000000001

Выход из тестового режима¶

Нажмите Выйти из теста в баннере, или: 1. Перейдите в Настройки 2. Отключите тестовый режим 3. Повторите активацию с реальными учетными данными

Администрирование¶

Управление пользователями¶

Роли:

Роль	Права
Администратор	Полный доступ, управление пользователями
Менеджер	Отчеты, управление коробами
Оператор	Сканирование, базовые операции
Наблюдатель	Только просмотр

Создание пользователей (только Администратор):

Перейдите в Панель управления (localhost:3001)
Перейдите в Пользователи
Нажмите Создать
Заполните данные и назначьте роль
Сохраните

Управление терминалами¶

Регистрация терминалов:

Панель управления → Терминалы
Нажмите Добавить терминал
Введите данные терминала
Назначьте производственную линию
Сохраните

Статусы терминалов:

Статус	Значение
🟢 Онлайн	Подключен и активен
🟡 Простаивает	Подключен, но неактивен
🔴 Офлайн	Не подключен
⚪ Неизвестно	Статус недоступен

Настройки подключения¶

Глобальные настройки (влияют на все устройства):

Панель управления → Настройки → Подключение
Установите режим подключения по умолчанию
Настройте поведение при отказе
Сохраните

Переопределение для устройства:

Панель управления → Терминалы
Выберите терминал
Измените режим подключения
Сохраните

Просмотр логов¶

Системные логи:

# Docker
docker-compose logs -f edge-service

# Нативный
tail -f logs/edge-service.log

Журнал аудита: - Панель управления → Журнал аудита - Фильтр по пользователю, действию, дате

Устранение неполадок¶

Проблемы с подключением¶

"Ошибка облачного подключения"¶

Симптомы: Красный индикатор подключения, ошибки синхронизации

Решения: 1. Проверьте сеть: ping app.okto.ru 2. Убедитесь, что firewall разрешает HTTPS (порт 443) 3. Проверьте статус активации устройства 4. Убедитесь, что облачные учетные данные не истекли

"Фабричный сервер недоступен"¶

Симптомы: Не удается синхронизироваться с локальным сервером

Решения: 1. Проверьте, что фабричный сервер запущен 2. Проверьте сетевой путь к серверу 3. Проверьте hostname/IP в конфигурации 4. Проверьте правила firewall

Проблемы со сканером¶

"Сканер не обнаружен"¶

Решения: 1. Проверьте физическое подключение 2. Убедитесь, что сканер включен 3. Проверьте права доступа к последовательному порту 4. Перезапустите граничный сервис

"Неверные коды от сканера"¶

Решения: 1. Очистите линзу сканера 2. Проверьте программирование сканера 3. Проверьте настройки символики штрихкода 4. Протестируйте с известным хорошим штрихкодом

Проблемы синхронизации¶

"Очередь синхронизации растет"¶

Симптомы: Размер очереди увеличивается, данные не синхронизируются

Решения: 1. Проверьте статус подключения 2. Проверьте облачные/серверные учетные данные 3. Проверьте логи сервера на ошибки 4. Перезапустите граничный сервис если завис

Получение помощи¶

Помощь в терминале:

./docs/cli/okto-help troubleshoot

Сбор логов:

# Собрать все логи для поддержки
make collect-logs

Статус системы:

# Быстрая проверка системы
./test-suite/quick-check.sh

Горячие клавиши¶

Комбинация	Действие
`tttt`	Активация тестового режима (на странице активации)
`Ctrl+L`	Переключение языка
`Ctrl+S`	Открыть настройки
`Escape`	Закрыть диалоги

Краткий справочник¶

URL-адреса¶

Сервис	URL
UI Оператора	http://localhost:3000
Панель управления	http://localhost:3001
Grafana	http://localhost:3002

Учетные данные по умолчанию¶

Пользователь	Пароль	Роль
admin	admin123	Администратор
manager	manager123	Менеджер
operator	operator123	Оператор

API Endpoints¶

Endpoint	Описание
GET /health	Состояние системы
GET /api/v1/scanner/status	Статус сканера
GET /api/v1/connection/status	Статус подключения
GET /api/v1/sync/status	Статус очереди синхронизации

Команды терминала¶

make docker-up      # Запуск всех сервисов
make docker-down    # Остановка всех сервисов
make docker-logs    # Просмотр логов
make docs           # Открыть документацию

Назад к README | API Reference | Deployment Guide