NP Lookup — детальна документація українською

Актуальна версія UI: 10.18.5 (береться з /status)

Огляд і призначення

• Веб‑форма для пошуку міст і вулиць через API Нової Пошти.
• Збереження результату у JSON до GCS з підписаними V4 URL (24 години).
• Інтеграція з Windows‑агентом: автоматичне отримання останнього JSON і збереження в C:\\Integrations.
• Прозорий статус інтеграцій: Secret Manager, Nova Poshta API, GCS Bucket, Signed URL, версія UI.

Архітектура (високий рівень)

Браузер → Flask (Cloud Run) → Nova Poshta API
                    ↓
               Google Cloud Storage ← Secret Manager (NP_API_KEY)
                    ↑
             Signed URL (V4, 24h) → Браузер → 1С/Windows‑служба
      

• Фронтенд: templates/index.html, static/styles.css, static/app.js.
• Бекенд: Flask (Python 3.11): /status, /search/city, /search/street, /details/city, /save, /latest, /metrics, /maintenance/cleanup.
• Деплой: Cloud Run (europe-west4); залежності у backend/requirements.txt.
• Продакшн‑домен: https://np-lookup.sysadmin.express/.

Ендпоїнти та логіка

• GET /status — повертає стан інтеграцій із TTL кешу (стабілізація відображення). Параметри у відповіді: secretOk, npOk, bucketOk, signedUrlOk, uiVersion, підказки npHint/bucketHint/signedUrlHint.
• GET /search/city, GET /search/street — звертаються до API НП з нормалізацією введення, підсвічуванням збігів; у дев‑режимі можливі стаби відповіді.
• GET /details/city — збагачує місто рефами області/району для вибраного SettlementRef/CityRef.
• POST /save — зберігає вибір (flat JSON для 1С) у np-lookup/YYYY-MM-DD/ з імʼям np_YYYYMMDD-HHMMSS_hash8.json; повертає downloadUrl (примусове завантаження) і openUrl (inline), час створення та TTL.
• GET /latest — знаходить найсвіжіший обʼєкт під префіксом np-lookup/ і повертає ті самі поля, що /save.
• GET /maintenance/cleanup — службове автоочищення (за X-CRON-TOKEN) обʼєктів старше RETENTION_HOURS; додатково до політики GCS Lifecycle.

Signed URL (V4) та IAM

• Підпис створюється без приватного ключа через iamcredentials.googleapis.com (signBlob) від імені SERVICE_ACCOUNT_EMAIL.
• Необхідні ролі: для бакету — storage.objectAdmin (для сервісного акаунта), для підпису — на SERVICE_ACCOUNT_EMAIL потрібно делегувати roles/iam.serviceAccountTokenCreator від Cloud Run SA.
• Змінні середовища: PROJECT_ID, REGION, BUCKET_NAME, NP_API_URL, UI_VERSION, SERVICE_ACCOUNT_EMAIL, STATUS_TTL, RETENTION_HOURS.

Формат JSON (плоский, 1С) — розширений

{
  "Area": "Кіровоградська",
  "AreaRef": "dcaadbf9-4b33-11e4-ab6d-005056801329",
  "Region": "Олександрійський",
  "RegionRef": "e4b1308f-4b33-11e4-ab6d-005056801329",
  "MainDescription": "Олександрія",
  "City": "Олександрія",
  "CityRef": "e71c38b4-4b33-11e4-ab6d-005056801329",
  "SettlementRef": "e71c38b4-4b33-11e4-ab6d-005056801329",
  "SettlementTypeCode": "м",
  "DeliveryCity": "e71c38b4-4b33-11e4-ab6d-005056801329",
  "Ref": "e71c38b4-4b33-11e4-ab6d-005056801329",
  "Street": "вул. Перемоги",
  "Present": "вул. Перемоги",
  "SettlementStreetRef": "f0adbb1e-0d4a-11e6-8f84-005056887b8d",
  "SettlementStreetDescription": "Перемоги",
  "StreetRef": "03a3562c-6853-11e6-8304-00505688561d",
  "StreetRefNew": "f0adbb1e-0d4a-11e6-8f84-005056887b8d",
  "StreetRefOld": "03a3562c-6853-11e6-8304-00505688561d",
  "StreetsType": "STR",
  "StreetsTypeDescription": "вулиця",
  "AddressLine": "Кіровоградська, Олександрійський, Олександрія, вул. Перемоги",
  "CreatedAt": "2025-10-08T14:30:48.350Z",
  "Guid": "17426b42f5844956aeeaf912bbec5421"
}
      

Перевірки та логіка

• Фронтенд: перевірка української мови введення (тільки укр. букви), мінімум 4 літери для пошуку; скидання стану при зміні міста; блокування поля вулиці до вибору міста; кнопка «Зберегти» активна лише після вибору міста і вулиці.
• Фронтенд: у фокус‑режимі запускається прогрес на 45с; поза фокусом — прогресбар 30с під час /save; після успішного збереження форсується оновлення /status для уникнення затримок кешу.
• Бекенд: /status кешується на STATUS_TTL секунд; можна форсувати оновлення GET /status?force=1. У дев‑режимі /save повертає 501, якщо бакет не налаштовано.
• Signed URL: створюється пара посилань — downloadUrl (attachment) та openUrl (inline), TTL 24 години; генерація через IAM signBlob.
• Метрики: /metrics містить агрегати cities_found, streets_found, np_api_calls, saves_ok/saves_fail, errors (сьогодні).
• Автоочищення: /maintenance/cleanup очищає обʼєкти старше RETENTION_HOURS з токеном X-CRON-TOKEN; додатково діє політика GCS Lifecycle.

Запуск і технічні параметри

• Локально: python backend/main.py (порт 8080); UI: /, довідка: /readme.
• Продакшн: Gunicorn у Cloud Run; змінні середовища: PROJECT_ID, REGION, BUCKET_NAME, NP_API_URL, UI_VERSION, SERVICE_ACCOUNT_EMAIL, STATUS_TTL, RETENTION_HOURS.
• Права: storage.objectAdmin для бакету; iam.serviceAccountTokenCreator делеговано для SERVICE_ACCOUNT_EMAIL від Cloud Run SA.
• Статика: /static обслуговує CSS/JS/ікони; шаблони в templates/.
• Формат файлу: JSON UTF‑8; імʼя np_YYYYMMDD-HHMMSS_hash8.json у np-lookup/YYYY-MM-DD/; Content-Disposition для downloadUrl — attachment.

Параметри середовища (детально)

• PROJECT_ID — ідентифікатор GCP проєкту.
• REGION — регіон сервісу (рекомендовано europe-west4).
• BUCKET_NAME — назва бакету GCS для збереження JSON і метрик.
• NP_API_URL — базова адреса API НП (https://api.novaposhta.ua/v2.0/json/).
• UI_VERSION — версія UI (MAJOR.MINOR.PATCH), показується у хедері та /status.
• SERVICE_ACCOUNT_EMAIL — сервісний акаунт для підпису V4 (через IAM signBlob).
• STATUS_TTL — TTL кешу /status (секунди); напр. 60.
• RETENTION_HOURS — години утримання обʼєктів до автоочищення (/maintenance/cleanup).
• METRICS_BLOB_PATH — шлях до метрик у бакеті (дефолт np-lookup/metrics/metrics.json).
• CANONICAL_DOMAIN — канонічний домен (np-lookup.sysadmin.express).
• ENFORCE_CANONICAL — якщо true, бекенд редіректить GET/HEAD на канонічний домен.
• CRON_TOKEN — токен авторизації для Cloud Scheduler запиту на /maintenance/cleanup.

Перевірки середовища

• PROJECT_ID: gcloud config get-value project відповідає прод‑проєкту; /status показує коректний uiVersion і зелений статус доступів.
• BUCKET_NAME: після POST /save зʼявляється файл у gs://<BUCKET_NAME>/np-lookup/YYYY-MM-DD/; /latest видає Signed URL.
• SERVICE_ACCOUNT_EMAIL: /latest повертає робочий Signed URL (V4); у логах немає помилок IAM signBlob.
• CRON_TOKEN: виклик GET /maintenance/cleanup з заголовком X-CRON-TOKEN проходить; без токена — 401.

Windows‑агент

• Інсталятор /static/np_agent_install.bat підвищує права, перевіряє C:\\Integrations, створює системне завдання для /static/np-agent.ps1 (щохвилини).
• Дедуплікація: маркер .processed по повному шляху та імені; незалежна від наявності файлу.
• Логи: ротація за розміром (>1 МБ), автоочищення архіву за 7 днів; діагностика: .latest.

Деплой та експлуатація

• Швидкий деплой: deploy/cloud_run_deploy.ps1 -ProjectId <id> -BucketName <bucket>.
• Повний сценарій: deploy/cloud_run.ps1 (вмикає API, створює Artifact Registry, налаштовує IAM і Cloud Scheduler; потребує CRON_TOKEN).
• Cloud Build бакет: gs://np-lookup-ivancom-dev_cloudbuild, політика Delete(age=14).

Домен і маршрутизація (канонічний)

• Канонічний домен: https://np-lookup.sysadmin.express/ — використовується всюди (UI, агент, інтеграції).
• Регіон: europe-west4 — домен має бути прив’язаний лише у цьому регіоні (один domain‑mapping).
• DNS: CNAME для np-lookup.sysadmin.express → ghs.googlehosted.com.
• Перевірка: gcloud beta run domain-mappings list --region=europe-west4 та gcloud beta run domain-mappings describe --domain=np-lookup.sysadmin.express --region=europe-west4 --format="yaml".
• Виправлення маршруту: видалити дубль у неканонічному регіоні (gcloud beta run domain-mappings delete --domain=np-lookup.sysadmin.express --region=europe-west1) і, за потреби, перевизначити у europe-west4 з --force-override.
• Верифікація сервісу: gcloud run services describe np-lookup --region=europe-west4 --format="value(status.url)"; у браузері перевірити / та /status (мають бути реальні дані, не стаби).
• Агент: використовує базовий URL https://np-lookup.sysadmin.express; при неправильному domain‑mapping може опитувати «чужий» сервіс.

Політика версій та журнал змін

• Версія MAJOR.MINOR.PATCH (приклад 10.18.5) відображається у UI та /status.
• Журнал змін ведеться тут; для кожного оновлення — детальний опис змін, що впливають на UI/бекенд/деплой.

Докладний журнал змін

• 10.18.5 — Узгоджено версію UI_VERSION та оновлено документацію (uk/en/pl). Додано і підтверджено перевірки середовища: PROJECT_ID (прод і зелений стан у /status), BUCKET_NAME (об’єкт у gs://<BUCKET_NAME>/np-lookup/YYYY-MM-DD/ після POST /save, валідний Signed URL у GET /latest), SERVICE_ACCOUNT_EMAIL (робочий V4 Signed URL у GET /latest, відсутні помилки/таймаути IAM signBlob у логах), CRON_TOKEN (проходить GET /maintenance/cleanup з заголовком X-CRON-TOKEN; без токена — 401).
• 10.18.2 — Коментарі агентів локалізовано та розширено (укр., технічні блоки: мережа, TLS, таймаути, інтеграція з Планувальником, безпека). Read.me (uk/en/pl) доповнено розділом «Параметри середовища» та деталізованим журналом змін. DEPLOY.md — виправлено приклад шляху до скрипта, актуалізовано поради щодо domain‑mapping.
• 10.18.1 — Розширений формат JSON (місто: MainDescription, SettlementTypeCode, DeliveryCity, Ref; вулиця: SettlementStreetRef/Description, Present, StreetsType/Description). Форс‑оновлення статусів після /save, TTL статусу 60с у дев, оновлено Read.me (uk/en/pl).
• 10.18.0 — Українські коментарі в усьому проекті; стабілізація старту /status (легкий режим), таймаут IAM signBlob 5с, контрольована обробка Signed URL у /latest; оновлені Read.me (uk/en/pl).

Система тестування (нова)

• Фронтенд (локально): запустити python backend/main.py, перевірити форми, бейджі статусів, прогрес‑фокус, локалізацію uk/en/pl, перемикач тем. Валідація: лише укр. літери, мінімум 4 символи.
• Бекенд (локально): перевірити /status, /search/city?q=Київ, /search/street?q=Хрещатик&settlementRef=..., /details/city?cityRef=..., /latest, /metrics, /maintenance/cleanup (з X-CRON-TOKEN).
• Signed URL: після /save перевірити доступність downloadUrl (attachment) та openUrl (inline), TTL 24 години.
• Агент Windows: у тестовій директорії перевірити роботу /static/np-agent.ps1 вручну, валідувати дедуплікацію через .processed, діагностику через .latest, ротацію логів.
• Редіректи: /readme має коректно перенаправляти за Accept-Language; перевірити канонічний домен (ENFORCE_CANONICAL).
• Експериментальний модуль: встановити FEATURE_EXPERIMENTAL=1 та перевірити /exp/ping, /exp/status.
• Метрики: збереження через /save має збільшувати лічильники; /metrics містить агрегати за сьогодні та загалом.

Windows агент: перевстановлення після викату

• Завантажити інсталятор: https://np-lookup.sysadmin.express/static/np_agent_install.bat (автоматично підніме права Адміністратора).
• Що робить інсталятор: готує C:\Integrations, видаляє старе завдання, завантажує np-agent.ps1 з /static, створює системне завдання Планувальника "NP Lookup Agent" (SYSTEM, щохвилини).
• Перевірка: schtasks /Query /TN "NP Lookup Agent"; ручний запуск powershell -NoProfile -ExecutionPolicy Bypass -File C:\Integrations\np-agent.ps1; лог у C:\Integrations\np-agent.log.
• Стан і дедуп: файли .latest і .processed у C:\Integrations; дублювань не має бути при повторних запусках.
• Канонічний домен: агент використовує https://np-lookup.sysadmin.express; перед перевстановленням переконайтесь у коректному domain‑mapping (europe-west4).
• Тест бека: GET /latest має повертати валідний Signed URL; після POST /save — новий обʼєкт у gs://<BUCKET_NAME>/np-lookup/YYYY-MM-DD/.

# Приклад локального запуску (Windows)
set FLASK_ENV=development
set UI_VERSION=10.18.5
python backend\main.py

# Перевірки бекенду (PowerShell)
curl http://localhost:8080/status
curl "http://localhost:8080/search/city?q=Київ"
curl "http://localhost:8080/readme-uk"  # рендер документації
      

Деталізація політики версій

• MAJOR: зміни, що ламають сумісність (API, формат JSON, архітектура).
• MINOR: нові можливості, що сумісні (нові поля, маршрути, UI‑фічі).
• PATCH: багфікси, правки стилів/локалізації, дрібні оптимізації.
• Процедура оновлення: оновити UI_VERSION у змінних середовища; оновити Read.me (uk/en/pl); перевірити /status і відображення у хедері; додати запис у «Останні оновлення».
• Посилання: докладно у deploy/VERSIONING.md; тести описані у deploy/TESTING.md.

Останні оновлення (скорочено)

• 10.18.1 — Розширений формат JSON (місто: MainDescription, SettlementTypeCode, DeliveryCity, Ref; вулиця: SettlementStreetRef/Description, Present, StreetsType/Description). Форс‑оновлення статусів після /save, TTL статусу 60с у дев, оновлено Read.me (uk/en/pl).
• 10.18.0 — Українські коментарі в усьому проекті; стабілізація старту /status (легкий режим), таймаут IAM signBlob 5с, контрольована обробка Signed URL у /latest; оновлені Read.me (uk/en/pl).
• 10.17.14 — Типографіка і локалізація блоку «Користувач»; переписаний опис агента; уніфіковані мітки.
• 10.17.13 — Read.me: редірект за Accept‑Language; застосування тем; оновлення UI_VERSION.
• 10.17.12 — Агента: дедуп, ротація логів; розширені коментарі; синхронізація версій.