second-mind-aep/WAMAS System - Требования и спецификация.md

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

### FR-001: Поддержка типов лотков

**Описание**: Система должна поддерживать работу с четырьмя типами лотков (TUB1, TUB2, TUB4, TUB8) с различным количеством активных ячеек.

**Критерии приемки**:

- TUB1: поддержка 1 активной ячейки с одним SKU
- TUB2: поддержка 2 ячеек с различными SKU
- TUB4: поддержка 4 активных ячеек
- TUB8: поддержка 8 активных ячеек (новый тип)
- Валидация соответствия типа лотка и номера ячейки

### FR-002: Контрольное сканирование товаров

**Описание**: Система должна обеспечивать контрольное сканирование товаров с поддержкой различных типов кодов.

**Критерии приемки**:

- Поддержка сканирования SGTIN (2D QR-коды)
- Поддержка сканирования EAN (1D штрих-коды)
- Режим без сканирования для товаров, не требующих контроля
- Валидация минимальной длины сканируемого кода (поле LEN)
- Защита от двойного сканирования (таймер 0.5 сек)

### FR-003: Световая индикация ячеек

**Описание**: Система должна обеспечивать точную световую индикацию активных ячеек для каждого типа лотка.

**Критерии приемки**:

- TUB1: подсветка всех 8 лампочек
- TUB2: подсветка 4 лампочек
- TUB4: подсветка 2 лампочек
- TUB8: подсветка 1 лампочки
- Режим мигания для товаров со специальными маркерами

### FR-004: Печать этикеток

**Описание**: Система должна поддерживать печать этикеток через сетевые принтеры.

**Критерии приемки**:

- Управление сетевыми принтерами через WAMAS-C
- Загрузка файлов из директории `/hcom/to_ssi/print/pbl_network_printer/`
- Использование файла по умолчанию при недоступности основного
- Обработка ошибок печати с соответствующими уведомлениями

### FR-005: Инвентаризация

**Описание**: Система должна поддерживать процесс инвентаризации лотков хранения.

**Критерии приемки**:

- Поячеечная инвентаризация лотков
- Отображение наименований SKU (до 42 символов)
- Ввод фактического количества через интерфейс станции
- Многоэкранное отображение информации с навигацией
- Автоматическая отправка результатов в HOST систему

### FR-006: Обработка маркеров товаров

**Описание**: Система должна обрабатывать специальные маркеры товаров и отображать соответствующие индикации.

**Критерии приемки**:

- Маркер "damaged" → отображение "МЕХ"
- Маркер "careful" → отображение "СТЕКЛ"
- Маркер "scan" + SGTIN=true → отображение "МАРКИР"
- Маркер "scan" + SGTIN=false → отображение "КОНТР"

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

### NFR-001: Производительность

- Время отклика системы на действия оператора: не более 2 секунд
- Пропускная способность: обработка до 100 операций в минуту на станцию
- Время обработки сканирования: не более 1 секунды

### NFR-002: Надежность

- Доступность системы: 99.5% в рабочее время
- Устойчивость к сбоям сети между WAMAS и HOST системой
- Автоматическое восстановление после кратковременных отключений

### NFR-003: Безопасность

- Валидация всех входящих сообщений от HOST системы
- Логирование всех операций для аудита
- Защита от некорректных данных в XML сообщениях

### NFR-004: Совместимость

- Обратная совместимость с существующими процессами WAMAS
- Поддержка существующего протокола HOST Communication
- Совместимость с текущим аппаратным обеспечением PTL станций

### NFR-005: Масштабируемость

- Поддержка до 50 PTL станций одновременно
- Возможность добавления новых типов лотков без изменения архитектуры
- Горизонтальное масштабирование обработки сообщений

## Технические характеристики

### Аппаратные требования

- **PTL станции**: Дисплеи, световые индикаторы, кнопки-мультилайты
- **Сканеры**: Стационарные сканеры 1D/2D кодов на каждой станции
- **Принтеры**: Сетевые принтеры этикеток (один на станцию)
- **Сетевая инфраструктура**: Ethernet подключение для всех устройств

### Программные требования

- **WAMAS-C**: Центральная система управления складом
- **HOST система**: ERP/WMS система верхнего уровня
- **База данных**: Таблицы для хранения данных операций и кодов
- **Файловая система**: Доступ к сетевым директориям для файлов печати

### Протоколы и форматы

- **Обмен данными**: XML сообщения между HOST и WAMAS
- **Коды товаров**: SGTIN (2D QR), EAN (1D штрих-код)
- **Файлы печати**: PDF формат для этикеток
- **Кодировка**: UTF-8 для всех текстовых данных

## Схема проекта

### Архитектура системы

```mermaid
graph TB
    HOST[HOST System<br/>ERP/WMS] 
    WAMAS[WAMAS-C<br/>Controller]
    PTL1[PTL Station #001]
    PTL2[PTL Station #002]  
    PTLX[PTL Station #XXX]
    
    subgraph Equipment1 ["PTL Station Equipment"]
        DISP[Display]
        LIGHTS[Light Indicators]
        SCAN[Scanner]
        PRINT[Printer]  
        BTN[Buttons/Multilights]
    end
    
    HOST <==>|XML Messages| WAMAS
    WAMAS -->|Control Commands| PTL1
    WAMAS -->|Control Commands| PTL2
    WAMAS -->|Control Commands| PTLX
    
    PTL1 --> DISP
    PTL1 --> LIGHTS
    PTL1 --> SCAN
    PTL1 --> PRINT
    PTL1 --> BTN
```

### Взаимодействие компонентов

```mermaid
sequenceDiagram
    participant HOST as HOST System
    participant WAMAS as WAMAS-C Controller
    participant PTL as PTL Station Hardware
    
    HOST->>WAMAS: disp-add, tub-type, inventory-new-add
    WAMAS->>PTL: Station Commands
    PTL->>WAMAS: Hardware Status & Scan Data
    WAMAS->>HOST: pick-response, print-response, inventory-response
    
    Note over HOST,PTL: XML Protocol Communication
```

### База данных

```mermaid
erDiagram
    RESERVE_LINES_OW {
        int TRANSFERID PK
        int order_id
        int order_line_id
        string station_id
        boolean print
        boolean SGTIN
        int LEN
        string marker
    }
    
    TUB_TYPE_OW {
        int TRANSFERID PK  
        int box_number
        string tu_type
    }
    
    INVENTORY_OW {
        int TRANSFERID PK
        int box_number
        string tu_type
        string station_id
    }
    
    PICK_WO {
        int TRANSFERID PK
        int picked
        int pick_status
        string station_id
        int tub_number
    }
    
    PICK_CODE_WO {
        int TRANSFERID PK
        string item_code
    }
    
    PRINT_WO {
        int TRANSFERID PK
        int print_status
        string station_id
        int order_id
    }
    
    PICK_WO ||--o{ PICK_CODE_WO : "TRANSFERID"
```

## Use Cases

### UC-001: Сборка заказа с маркированным товаром (SGTIN)

```mermaid
flowchart TD
    A[Лоток прибывает на станцию] --> B[Отображение 'МАРКИР' и количества]
    B --> C[Подсветка ячейки лотка]
    C --> D[Оператор берет товар]
    D --> E[Сканирование SGTIN QR-код]
    E --> F{Длина кода >= LEN?}
    F -->|Нет| G[Сообщение 'Пересканировать']
    G --> E
    F -->|Да| H{QR читается?}
    H -->|Нет| I[Сканирование эталонного QR]
    I --> J[Режим 1.5.3]
    H -->|Да| K{Двойное сканирование?}
    K -->|Да| L[Сообщение 'ПОВТОР']
    L --> M[Мигание кнопки №2]
    M --> N[Нажатие кнопки №2]
    N --> B
    K -->|Нет| O[Уменьшение счетчика]
    O --> P{Все единицы отсканированы?}
    P -->|Нет| D
    P -->|Да| Q[Отображение 'ПОДТВЕРДИТЬ']
    Q --> R[Нажатие кнопки-мультилайт]
    R --> S[Отправка pick-response с item_code]
```

**Актеры**: Оператор склада, WAMAS-C, HOST система

**Предусловия**:

- Лоток хранения находится на станции
- Получено задание disp-add с SGTIN=true, marker="scan"

**Основной поток**:

1. Система отображает "МАРКИР" и количество на дисплее
2. Загорается подсветка нужной ячейки лотка
3. Оператор берет единицу товара
4. Оператор сканирует SGTIN (QR-код)
5. Система проверяет длину кода (должна быть >= LEN)
6. Система уменьшает счетчик на дисплее
7. Повторяется пп. 3-6 для всех единиц
8. Система просит подтверждение "ПОДТВЕРДИТЬ"
9. Оператор нажимает кнопку-мультилайт
10. Система отправляет pick-response с item_code для каждой единицы

**Альтернативные потоки**:

- 5а. Код слишком короткий → "Пересканировать"
- 5б. QR не читается → сканирование эталонного кода → режим 1.5.3
- 4а. Двойное сканирование → "ПОВТОР" → возврат к п.3

### UC-002: Сборка заказа с обычным товаром (EAN)

```mermaid
flowchart TD
    A[Лоток прибывает на станцию] --> B[Отображение 'КОНТР' и количества]
    B --> C[Подсветка ячейки лотка]
    C --> D[Оператор берет товар]
    D --> E[Сканирование EAN штрих-код]
    E --> F{Код читается?}
    F -->|Нет| G[Сканирование эталонного кода]
    G --> E
    F -->|Да| H{Защита от двойного сканирования<br/>0.5 сек}
    H -->|Блокировка| H
    H -->|OK| I[Уменьшение счетчика]
    I --> J{Все единицы отсканированы?}
    J -->|Нет| D
    J -->|Да| K[Отправка pick-response с item_code]
```

**Актеры**: Оператор склада, WAMAS-C, HOST система

**Предусловия**:

- Лоток хранения находится на станции
- Получено задание disp-add с SGTIN=false, marker="scan"

**Основной поток**:

1. Система отображает "КОНТР" и количество на дисплее
2. Загорается подсветка нужной ячейки лотка
3. Оператор берет единицу товара
4. Оператор сканирует EAN (штрих-код)
5. Система уменьшает счетчик на дисплее
6. Повторяется пп. 3-5 для всех единиц
7. Система отправляет pick-response с item_code

**Альтернативные потоки**:

- 4а. Код не читается → сканирование эталонного кода
- 4б. Защита от двойного сканирования (таймер 0.5 сек)

### UC-003: Печать этикетки

```mermaid
flowchart TD
    A[Получено задание с print=true] --> B[Отображение 'УПАК' и стрелки к принтеру]
    B --> C[Подсветка кнопки-мультилайт у принтера]
    C --> D[Оператор нажимает кнопку принтера]
    D --> E[Загрузка файла этикетки]
    E --> F{Файл доступен?}
    F -->|Нет| G[Использование default_label.pdf]
    F -->|Да| H[Отправка на принтер]
    G --> H
    H --> I{Печать успешна?}
    I -->|Да| J[print-response status=1]
    I -->|Нет| K[Сообщение 'ОШИБКА ПЕЧАТИ']
    K --> L[Повторное нажатие кнопки]
    L --> M[print-response status=2]
    J --> N[Продолжение основного процесса]
    M --> N
```

**Актеры**: Оператор склада, WAMAS-C, Принтер, HOST система

**Предусловия**:

- Получено задание disp-add с print=true
- Принтер подключен и готов

### UC-004: Инвентаризация лотка

```mermaid
flowchart TD
    A[Получено задание inventory-new-add] --> B[Лоток прибывает на станцию]
    B --> C[Отображение 'ИНВЕНТАРИЗАЦИЯ']
    C --> D[Оператор подтверждает кнопкой №2]
    D --> E[Подсветка первой ячейки]
    E --> F[Отображение наименования SKU<br/>до 3 экранов]
    F --> G[Отображение 'КОЛ-ВО: 0']
    G --> H[Оператор вводит количество +/-]
    H --> I[Подтверждение кнопкой №2]
    I --> J{Есть еще ячейки?}
    J -->|Да| K[Переход к следующей ячейке]
    K --> E
    J -->|Нет| L[Отправка inventory-response]
    L --> M[Лоток покидает станцию]
    
    style A fill:#e1f5fe
    style L fill:#c8e6c9
    style M fill:#c8e6c9
```

**Актеры**: Оператор склада, WAMAS-C, HOST система

**Предусловия**:

- Получено задание inventory-new-add
- Лоток прибыл на станцию

### UC-005: Валидация типа лотка

```mermaid
flowchart TD
    A[Получено сообщение disp-add] --> B[Получено сообщение tub-type]
    B --> C[Проверка соответствия tu_type и compartment_id]
    C --> D{Соответствие корректно?}
    D -->|Да| E[Обработка задания]
    D -->|Нет| F[Запись в таблицу со статусом error]
    
    G[Правила валидации:<br/>TUB1: compartment_id = 1<br/>TUB2: compartment_id = 1,2<br/>TUB4: compartment_id = 1,2,3,4<br/>TUB8: compartment_id = 1,2,3,4,5,6,7,8]
    
    style D fill:#fff3e0
    style F fill:#ffcdd2
    style E fill:#c8e6c9
```

**Актеры**: WAMAS-C, HOST система

**Предусловия**: Получено сообщение disp-add

## Host Communication процессы

### Обмен данными HOST → WAMAS

#### MSG-001: disp-add (Задание на резервирование товара)

```mermaid
graph LR
    subgraph "HOST System"
        A[Create Task]
    end
    
    subgraph "XML Message"
        B[disp-add<br/>TRANSFERID<br/>order_id<br/>print=true/false<br/>SGTIN=true/false<br/>marker=scan/damaged/careful<br/>LEN=минимальная длина]
    end
    
    subgraph "WAMAS Database"
        C[RESERVE_LINES_OW<br/>Table]
    end
    
    A --> B
    B --> C
```

**Назначение**: Создание задания на сборку товара из лотка хранения **Формат**: XML **Таблица**: RESERVE_LINES_OW

**Структура сообщения**:

```xml
<record_type="disp-add" TRANSFERID="12900129" tub_number="110002556">
  <disp-add-line 
    order_id="1877865" 
    order_line_id="1" 
    station_id="PTL001" 
    geo_code="001.01.01.01" 
    compartment_id="1" 
    ordered="5"
    host_order_line_id="1863829413" 
    print="true" 
    SGTIN="true"
    LEN="20"
    marker="scan">
  </disp-add-line>
</disp-add>
```

**Ключевые поля**:

- `TRANSFERID`: Уникальный идентификатор сообщения
- `print`: Флаг необходимости печати этикетки (true/false)
- `SGTIN`: Наличие SGTIN кодов у товара (true/false)
- `LEN`: Минимальная длина сканируемого кода
- `marker`: Специальные маркеры (damaged/careful/scan)

#### MSG-002: tub-type (Определение типа лотка)

```mermaid
graph LR
    subgraph "HOST System"
        A[Define Tub Type]
    end
    
    subgraph "XML Message"
        B[tub-type<br/>TRANSFERID<br/>box_number<br/>tu_type=TUB1/TUB2/TUB4/TUB8]
    end
    
    subgraph "WAMAS Database"
        C[TUB_TYPE_OW<br/>Table]
    end
    
    A --> B
    B --> C
```

**Назначение**: Сообщение о типе лотка для валидации операций **Формат**: XML **Таблица**: TUB_TYPE_OW

**Структура сообщения**:

```xml
<tub-type TRANSFERID="12900130" box_number="110002556" tu_type="TUB4"/>
```

#### MSG-003: inventory-new-add (Задание на инвентаризацию)

```mermaid
graph LR
    subgraph "HOST System"
        A[Create Inventory Task]
    end
    
    subgraph "XML Message"
        B[inventory-new-add<br/>TRANSFERID<br/>box_number<br/>tu_type<br/>station_id<br/>sku_names]
    end
    
    subgraph "WAMAS Database"
        C[INVENTORY_OW<br/>Table]
    end
    
    A --> B
    B --> C
```

**Назначение**: Создание задания на инвентаризацию лотка **Формат**: XML **Таблица**: INVENTORY_OW

**Структура сообщения**:

```xml
<inventory-new-add TRANSFERID="12900131" box_number="110002556" tu_type="TUB2" station_id="PTL001">
  <inventory-line compartment_id="1" sku_name="Товар 1"/>
  <inventory-line compartment_id="2" sku_name="Товар 2"/>
</inventory-new-add>
```

### Обмен данными WAMAS → HOST

#### MSG-101: pick-response (Отчет о сборке заказа)

```mermaid
graph LR
    subgraph "WAMAS Database"
        A[PICK_WO<br/>Table]
        B[PICK_CODE_WO<br/>Table]
    end
    
    subgraph "XML Message"
        C[pick-response<br/>TRANSFERID<br/>picked quantity<br/>pick_status<br/>item_codes array]
    end
    
    subgraph "HOST System"
        D[Process Results]
    end
    
    A --> C
    B --> C
    C --> D
```

**Назначение**: Подтверждение выполнения операции сборки с деталями **Формат**: XML **Таблицы**: PICK_WO, PICK_CODE_WO

**Структура сообщения**:

```xml
<pick-response 
  TRANSFERID="12900141" 
  tote_number="40009681" 
  geo_code="001.01.01.01"
  customer_code="448359" 
  host_order_id="1280449" 
  station_id="PTL001"
  tub_number="110002964" 
  pick_status="1" 
  compartment_id="1" 
  picked="2">
  <pick-response-line item_code="SGTIN:123456789012345"/>
  <pick-response-line item_code="SGTIN:123456789012346"/>
</pick-response>
```

#### MSG-102: print-response (Отчет о печати)

```mermaid
graph LR
    subgraph "WAMAS Database"
        A[PRINT_WO<br/>Table]
    end
    
    subgraph "XML Message"
        B[print-response<br/>TRANSFERID<br/>print_status=1/2<br/>station_id<br/>order_id]
    end
    
    subgraph "HOST System"
        C[Update Print Status]
    end
    
    A --> B
    B --> C
```

**Назначение**: Подтверждение статуса печати этикетки **Формат**: XML  
**Таблица**: PRINT_WO

**Структура сообщения**:

```xml
<print-response 
  TRANSFERID="169954915" 
  print_status="1" 
  station_id="PTL001" 
  order_id="1877865"/>
```

**Статусы печати**:

- `1`: Печать выполнена успешно
- `2`: Ошибка печати

#### MSG-103: inventory-response (Результаты инвентаризации)

```mermaid
graph LR
    subgraph "WAMAS Database"
        A[INVENTORY_WO<br/>Table]
    end
    
    subgraph "XML Message"
        B[inventory-response<br/>TRANSFERID<br/>box_number<br/>station_id<br/>actual quantities]
    end
    
    subgraph "HOST System"
        C[Update Inventory]
    end
    
    A --> B
    B --> C
```

**Назначение**: Передача результатов инвентаризации лотка **Формат**: XML

**Структура сообщения**:

```xml
<inventory-response 
  TRANSFERID="12900131" 
  box_number="110002556" 
  station_id="PTL001">
  <inventory-line compartment_id="1" actual_qty="15"/>
  <inventory-line compartment_id="2" actual_qty="0"/>
</inventory-response>
```

### Процессы интеграции

#### INT-001: Инициация сборки заказа

```mermaid
sequenceDiagram
    participant HOST as HOST System
    participant WAMAS as WAMAS-C
    participant PTL as PTL Station
    participant OP as Operator
    
    HOST->>WAMAS: tub-type (определение типа лотка)
    WAMAS->>WAMAS: Сохранение типа лотка
    HOST->>WAMAS: disp-add (задание на сборку)
    WAMAS->>WAMAS: Валидация tu_type vs compartment_id
    
    alt Валидация успешна
        WAMAS->>PTL: Активация станции
        PTL->>OP: Отображение задания
        
        alt Требуется печать (print=true)
            PTL->>OP: "УПАК" + подсветка принтера
            OP->>PTL: Нажатие кнопки принтера
            PTL->>PTL: Печать этикетки
            PTL->>WAMAS: Статус печати
            WAMAS->>HOST: print-response (status=1)
        end
        
        PTL->>OP: Отображение товара + подсветка ячейки
        OP->>PTL: Сборка товара (с/без сканирования)
        PTL->>WAMAS: Результат операции
        WAMAS->>HOST: pick-response (с item_code если было сканирование)
        
    else Ошибка валидации
        WAMAS->>WAMAS: Запись в таблицу со статусом error
    end
```

#### INT-002: Обработка ошибок

```mermaid
flowchart TD
    A["Получение сообщения"] --> B{"Валидация OK?"}
    B -->|"Нет"| C["Запись в таблицу с error"]
    B -->|"Да"| D["Обработка на PTL"]
    D --> E{"Принтер доступен?"}
    E -->|"Нет"| F["print-response status=2"]
    E -->|"Да"| G["Печать OK"]
    G --> H["print-response status=1"]
    F --> I["Продолжение без печати"]
    H --> I
    I --> J{"Сканирование OK?"}
    J -->|"Ошибка"| K["Эталонный код или режим исключения"]
    J -->|"OK"| L["pick-response с кодами"]
    K --> M["pick-response без кодов"]
    L --> N["Завершение"]
    M --> N

    style C fill:#ffcccc
    style F fill:#ffffcc
    style K fill:#ffffcc
```

#### INT-003: Мониторинг и логирование

```mermaid
graph TB
    subgraph "Входящие события"
        A[XML Messages]
        B[Scan Operations]  
        C[Print Events]
        D[Validation Results]
    end
    
    subgraph "Система логирования"
        E[Message Logger]
        F[Operation Logger]
        G[Error Logger]
        H[Performance Monitor]
    end
    
    subgraph "Метрики и отчеты"
        I[Response Time]
        J[Success Rate]
        K[Station Load]
        L[Error Statistics]
    end
    
    A --> E
    B --> F  
    C --> F
    D --> G
    
    E --> I
    F --> J
    F --> K
    G --> L
    
    style G fill:#ffcccc
    style L fill:#ffcccc
```