Различия

Показаны различия между двумя версиями страницы.

Ссылка на это сравнение

Предыдущая версия справа и слеваПредыдущая версия
Следующая версия		Предыдущая версия
external:projects:soup-ff-kaz:start [2026/06/29 10:22] – ↷ Страница перемещена из projects:soup-ff-kaz:start в external:projects:soup-ff-kaz:start adminexternal:projects:soup-ff-kaz:start [2026/07/13 12:57] (текущий) – admin
Строка 1: Строка 1:
 ====== Soup FF Kaz Service ====== ====== Soup FF Kaz Service ======
  
-`soup-ff-kaz-service` — Windows-служба, которая возвращает казахскую локализацию товара по штрихкоду. Данные хранятся в локальной базе SQLite. Если товара нет в базе, служба запрашивает его во внешнем API и сохраняет полученный результат.+soup-ff-kaz-service — Windows-служба, которая возвращает казахскую локализацию товара по штрихкоду. Данные хранятся в локальной базе SQLite. Если товара нет в базе, служба запрашивает его во внешнем API и сохраняет полученный результат. 
 +При печати этикетки из Food Factory внутри макета выполняется запрос в службу soup-ff-kaz-service, в макет этикетки добавляется информация на казахском языке (Наименование, состав, условия хранения).
  
-## Назначение+==== Назначение ====
  
 Служба предоставляет HTTP API: Служба предоставляет HTTP API:
  
-- `GET /api/v1/good/{штрихкод}/kz` — получить наименование, состав и условия хранения товара на казахском языке; +- GET /api/v1/good/{barcode(EAN13, CODE128}/kz — получить наименование, состав и условия хранения товара на казахском языке  
-- `GET /api/v1/version` — получить версию и Git-коммит установленной сборки.+
  
-По умолчанию HTTP-сервер слушает порт `8080`.+- GET /api/v1/version — получить версию приложения  
  
-## Системные требования +По умолчанию 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 +
-```+