Soup FF Kaz Service

`soup-ff-kaz-service` — Windows-служба, которая возвращает казахскую локализацию товара по штрихкоду. Данные хранятся в локальной базе SQLite. Если товара нет в базе, служба запрашивает его во внешнем API и сохраняет полученный результат.

## Назначение

Служба предоставляет HTTP API:

- `GET /api/v1/good/{штрихкод}/kz` — получить наименование, состав и условия хранения товара на казахском языке; - `GET /api/v1/version` — получить версию и Git-коммит установленной сборки.

По умолчанию HTTP-сервер слушает порт `8080`.

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

- Windows с правами локального администратора для установки службы; - свободный TCP-порт для HTTP API; - доступ к внешнему API, если требуется автоматическое получение переводов;

## Конфигурация

Создайте файл `config.yaml`:

```yaml http:

port: 8080

database:

path: goods.db

external_api:

base_url: https://example.kz
api_key: replace-with-api-key
integration_id: 1
timeout: 5s
refresh_after: 6h

```

Параметры:

Если `base_url` или `api_key` не указаны, внешний API отключается. В этом режиме служба возвращает только данные, уже имеющиеся в SQLite.

Путь к конфигурации определяется в следующем порядке:

1. Значение переменной окружения `SOUP_FF_KAZ_CONFIG`. 2. Файл `config.yaml` в текущем рабочем каталоге. 3. Файл `config.yaml` рядом с исполняемым файлом службы. 4. Если файл не найден, используются значения по умолчанию.

Установку необходимо выполнять из командной строки `cmd.exe`, запущенной от имени администратора.

Перейдите в каталог развертывания:

```bat cd /d D:\path\to\soupFFKazService\deploy ```

Проверьте версию:

```bat soup-ff-kaz-service.exe version ```

Установите и запустите службу:

```bat soup-ff-kaz-service.exe install soup-ff-kaz-service.exe start ```

Системное имя службы:

```text soup-ff-kaz-service ```

Отображаемое имя в оснастке «Службы»:

```text Soup FF Kaz Service for FoodFactory ```

При необходимости откройте входящий TCP-порт в Windows Firewall. Пример для порта `8080`:

```bat netsh advfirewall firewall add rule name=«Soup FF Kaz Service HTTP» dir=in action=allow protocol=TCP localport=8080 ```

Правило требуется только при обращении к API с других компьютеров.

## Проверка установки

Проверить состояние службы:

```bat sc query soup-ff-kaz-service ```

Проверить HTTP API:

```bat curl http://localhost:8080/api/v1/version ```

Пример ответа:

```json {

"version": "1.0.0",
"commit": "0123456"

} ```

Запрос данных товара:

```bat curl http://localhost:8080/api/v1/good/210012340500/kz ```

Пример успешного ответа:

```json {

"code": "1234",
"name": "Тауар атауы",
"composition": "Құрамы",
"storage_conditions": "Сақтау шарттары"

} ```

Если товар не найден, API возвращает HTTP `200` и пустые поля:

```json {

"code": "",
"name": "",
"composition": "",
"storage_conditions": ""

} ```

## Принцип работы

Обработка запроса выполняется следующим образом:

1. Клиент отправляет `GET /api/v1/good/{штрихкод}/kz`. 2. Служба разбирает штрихкод и извлекает код товара. 3. Выполняется поиск товара в таблице `goods` локальной базы SQLite. 4. Если запись найдена, она сразу возвращается клиенту. 5. Если запись устарела, служба дополнительно запускает ее обновление из внешнего API в фоне. Клиент при этом получает текущие данные без ожидания обновления. 6. Если записи в SQLite нет, служба синхронно обращается во внешний API. 7. Полученные данные сохраняются в SQLite и возвращаются клиенту. 8. Если товар отсутствует и во внешнем API, клиент получает объект с пустыми полями.

Для одной записи одновременно выполняется не более одного фонового обновления.

Внешний запрос имеет вид:

```text GET {base_url}/api/v1/goods/{код_товара}/kz?integration_id={integration_id} X-API-Key: {api_key} ```

Поддерживаются два формата штрихкода:

- 12 цифр, начинающихся с `2`; - Code 128 в формате из четырех частей, например `01.1.001234.0,500`.

## Хранение данных

При первом запуске служба автоматически создает файл SQLite и таблицу `goods`.

Для каждого товара хранятся:

- код; - казахское наименование; - состав; - условия хранения; - время последней синхронизации.

Путь `database.path` может быть абсолютным или относительным. Для предсказуемой работы Windows-службы рекомендуется использовать абсолютный путь, например:

```yaml database:

path: C:\ProgramData\SoupFFKazService\goods.db

```

Учетная запись службы должна иметь права на создание и изменение файла базы данных и его каталога.

## Журналы

Служба пишет:

- основные события запуска и остановки в Windows Event Log; - структурированные HTTP-логи в каталог `logs`.

Если конфигурация загружена из файла, каталог `logs` создается рядом с этим файлом. Имя текущего журнала содержит дату:

```text soup-ff-kaz-service-2026-06-24.log ```

Журнал ротируется по дням и размеру. Старые файлы архивируются и удаляются согласно настройкам ротации службы.

## Обновление службы

Остановите службу:

```bat soup-ff-kaz-service.exe stop ```

Замените исполняемый файл и при необходимости обновите `config.yaml`, затем запустите службу:

```bat soup-ff-kaz-service.exe start ```

После обновления проверьте версию и доступность API:

```bat soup-ff-kaz-service.exe version curl http://localhost:8080/api/v1/version ```

## Удаление службы

Запустите `cmd.exe` от имени администратора:

```bat soup-ff-kaz-service.exe stop soup-ff-kaz-service.exe remove ```

Удаление регистрации службы не удаляет автоматически базу SQLite, конфигурацию и журналы.

## Диагностический запуск

Для запуска без регистрации в Windows SCM:

```bat soup-ff-kaz-service.exe debug ``` Для остановки диагностического процесса нажмите `Ctrl+C`.

## Основные команды

```text soup-ff-kaz-service.exe debug soup-ff-kaz-service.exe install soup-ff-kaz-service.exe start soup-ff-kaz-service.exe stop soup-ff-kaz-service.exe pause soup-ff-kaz-service.exe continue soup-ff-kaz-service.exe remove soup-ff-kaz-service.exe version ```