====== Runbook: СКУД Политех (PolytechSKUD*) ======

Этот runbook привязан к группе алертов **polytech_skud** в Prometheus.
Цель — за минуту понять «наша проблема или их», и кому звонить.

===== Архитектура интеграции =====

<code>
lk.olvery.ru  ──►  back-nfc (PassService)
              ──►  back-acs (ExternalPassController)
                 ──►  ApacsProxyDriver (PHP, retry +5)
                    ──►  apacs-proxy (Go, localhost:8099 в контейнере back-acs)
                       ──►  СКУД Политех (mTLS, 192.168.200.138:443)
                          └─ маршрут через IPSec srv-pstu-vpn.tmpm
</code>

===== Источники алертов =====

^ Алерт                          ^ Слой              ^ Кто чинит         ^
| ''PolytechSKUDIntegrationDown''| end-to-end        | смотреть оба ниже |
| ''PolytechApacsProxyDown''     | наш Go-прокси     | мы                |
| ''PolytechSKUDHostUnreachable''| хост Политеха     | Политех + IPSec   |
| ''PolytechSKUDHighLatency''    | end-to-end >20с   | мы (диагностика)  |

===== Когда красное — как локализовать =====

==== 1. Если только PolytechSKUDHostUnreachable ====

Хост СКУД Политех (192.168.200.138:443) не отвечает на TCP-connect с
gw1.olvr через IPSec.

  * Проверь алерт ''IpsecTunnelDown'' — если красный, разорван туннель
    через ''srv-pstu-vpn.tmpm''.
  * Если IPSec зелёный — хост лежит у них. Звонить Политеху, открыть
    им встречную задачу.

==== 2. Если только PolytechApacsProxyDown ====

(будет активен после раскатки OLV-3707 на прод)

Наш Go-прокси ''apacs-proxy'' внутри контейнера ''tpark-it.back-acs.latest''
не отдаёт ''/health''.

  * <code>ssh srv-prod-app docker exec tpark-it.back-acs.latest curl -sS localhost:8099/health</code>
  * Если ответ не ''200 {"status":"ok"}'' — рестарт контейнера:
    <code>ssh srv-prod-app docker restart tpark-it.back-acs.latest</code>
  * Если рестарт не помог — смотреть логи Go-прокси:
    <code>docker logs tpark-it.back-acs.latest 2>&1 | grep -i apacs-proxy</code>
  * Частые причины: проблемы с mTLS-сертификатами Политеха, истёкший
    клиентский cert, конфиг ''APACS_PROXY_URL'' / провайдера в БД.

==== 3. Если PolytechSKUDIntegrationDown красный, а оба нижних зелёные ====

End-to-end проба ''POST /api/nfc/v1/pass'' отдаёт не-2xx-и-не-400, а
наш Go-прокси и их хост по отдельности живы — значит проблема
**между** back-nfc и back-acs.

  * Проверь логи back-nfc (PassService, AcsApiService.post).
  * Проверь логи back-acs (ExternalPassService.create) — есть ли вообще
    запрос, или back-nfc не дошёл до него?
  * Если запрос дошёл и сразу 5xx — лезть в ExternalPassController.

==== 4. Если PolytechSKUDHighLatency, но Down-алертов нет ====

Интеграция работает, но >20с на пробу (baseline 12с, max за 24h
бывает 29с). Это сигнал-разогрев — если регулярно, СКУД у них
тормозит. Длительная высокая latency может стать 504 (apacs-proxy
имеет таймаут на upstream).

  * Открыть письмо/чат Политеху — «у нас фиксируется устойчивая
    высокая задержка на проверке пропусков, проверьте свою сторону».
  * На нашей стороне костыли не нужны — пользователь видит длинную
    проверку пропуска, но успех штатный.

===== Полезные команды =====

==== Прямые пробы ====

<code bash>
# Наш apacs-proxy (после раскатки OLV-3707):
curl -sS https://lk.olvery.ru/api/acs/v1/health/apacs-proxy

# TCP до Политеха через IPSec (с gw1.olvr):
ssh root@gw1.olvr curl -sS -m 5 -k -o /dev/null -w "%{http_code} t=%{time_total}s\n" https://192.168.200.138/

# End-to-end (как мониторинг):
curl -sS -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer <см. blackbox_exporter.yml http_post_polytech_skud>" \
  -d '{"deviceId":"bebd6444-70e0-4763-9f51-9626e2420e19","locationId":36,"userId":10760,"deviceDescription":"manual"}' \
  https://lk.olvery.ru/api/nfc/v1/pass
</code>

==== Что куда ====

  * **back-acs logs**: ''ssh srv-prod-app docker logs tpark-it.back-acs.latest --tail 200''
  * **back-nfc logs**: ''ssh srv-prod-app docker logs tpark-it.back-nfc.latest --tail 200''
  * **apacs-proxy внутри контейнера**: ''docker exec tpark-it.back-acs.latest ps aux | grep apacs''
  * **Prometheus targets**: https://prom1.olvr или ''ssh gw1.olvr curl localhost:9090/api/v1/targets?state=active''

===== История =====

  * **2026-04-21** OLV-3527 — добавлен ''blackbox_polytech_skud'' (1 проба end-to-end), алерты ''PolytechSKUDIntegrationDown'' / ''PolytechSKUDHighLatency''.
  * **2026-05-17** Полноценный инцидент 504 на ''POST /pass'' — алерт сработал штатно, но было невозможно различить «наш слой или их хост». Михаил Андреев попросил разделить.
  * **2026-05-26** OLV-3707 — добавлены ''blackbox_polytech_host'' (TCP до их хоста) и health-эндпоинт ''/api/acs/v1/health/apacs-proxy'' (после раскатки back-acs включается ''blackbox_apacs_proxy_health''). Алерты ''PolytechSKUDHostUnreachable'' / ''PolytechApacsProxyDown'' (последний пока закомментирован, ждёт раскатки).