Эта страница только для чтения. Вы можете посмотреть её исходный текст, но не можете его изменить. Сообщите администратору, если считаете, что это неправильно. ====== 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 ``` Параметры: | Параметр | Назначение | Значение по умолчанию | |---|---|---| | `http.port` | Порт локального HTTP API | `8080` | | `database.path` | Путь к файлу SQLite | `goods.db` | | `external_api.base_url` | Базовый адрес внешнего API | не задан | | `external_api.api_key` | Ключ, передаваемый в заголовке `X-API-Key` | не задан | | `external_api.integration_id` | Идентификатор интеграции во внешнем API | `0` | | `external_api.timeout` | Тайм-аут обращения к внешнему API | `5s` | | `external_api.refresh_after` | Интервал до фонового обновления записи | `6h` | Если `base_url` или `api_key` не указаны, внешний API отключается. В этом режиме служба возвращает только данные, уже имеющиеся в SQLite. Путь к конфигурации определяется в следующем порядке: 1. Значение переменной окружения `SOUP_FF_KAZ_CONFIG`. 2. Файл `config.yaml` в текущем рабочем каталоге. 3. Файл `config.yaml` рядом с исполняемым файлом службы. 4. Если файл не найден, используются значения по умолчанию. ==== Установка Windows-службы ==== Установку необходимо выполнять из командной строки `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 ```