Различия

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

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

Предыдущая версия справа и слеваПредыдущая версия
external:projects:soup-ff-kaz:start [2026/06/29 10:22] – удалено - внешнее изменение (Дата неизвестна) 127.0.0.1external:projects:soup-ff-kaz:start [2026/06/29 10:22] (текущий) – ↷ Страница перемещена из projects:soup-ff-kaz:start в external:projects:soup-ff-kaz:start admin
Строка 1: Строка 1:
 +====== 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
 +```