houseplan-card/docs/reviews/SPEC-REVIEW-43-r4.md

# SPEC-REVIEW-43-r4

- Issue: #43 «Диалог помощи и обратной связи с обезличенным support report»
- Этап: spec (PROCESS.md §2.4)
- Заход: r4 · блокирующих циклов израсходовано 2 из 4 (до этого раунда)
- Материал: `docs/specs/043-private-support-report.md` на HEAD `cd8d01ac`
  (ветка `issue/43-help-feedback`), плюс код `scripts/support-relay/**` как
  доказательство исполнимости заявленных в §9 контрактов — в объёме, до
  которого дотягивается дельта этого раунда.
- Предыдущий раунд: r3, вердикт **жёлтый**, SHA `c43bf847` (High 0, Medium 1);
  документ `docs/reviews/SPEC-REVIEW-43-r3.md`, опубликован коммитом
  `55b51a02`. SHA r3 в самом документе назван явно (раздел «Материал»); в
  сжатом комментарии-вердикте в issue он не повторён (там только «HEAD»), но
  это не «находка №1 инструкции» — первоисточник (файл ревью) SHA не потерял.
  SHA пересчитан и подтверждён по времени коммитов независимо от текста
  документа: `git log --date=iso-strict` даёт `c43bf847` = `2026-09-02
  01:03:57+03:00`, что на 27 с опережает комментарий-вердикт `r3`
  (`22:21:03Z` = `01:21:03+03:00`, следующий коммит `55b51a02` = сам документ
  ревью, коммит `22:21:09Z`).

## Дельта r3→r4

`git diff c43bf847..HEAD` (без учёта `docs/reviews/SPEC-REVIEW-43-r3.md`,
который сам является артефактом прошлого раунда, а не правкой автора):

- `docs/specs/043-private-support-report.md` — 10 строк добавлено, 0 удалено:
  новый абзац в §9.2 (источник rate-limit), новая строка **AC12a** в §13,
  новая строка обязательной мутации в §14.4;
- `scripts/support-relay/README.md` — 27 строк добавлено: минимальная
  конфигурация автоматизации Home Assistant «House Plan: приёмщик обратной
  связи → личка» (YAML) плюс пояснение, почему `parse_mode: plain_text` не
  косметика.

Дельта строго докс-онли и локальна: адресует ровно два пункта прошлого
вердикта (Medium §9.2 и снятый-с-запиской Low про недокументированную
автоматизацию), кода не трогает, новую подсистему не задевает, объём
несравним с исходной задачей. Полный разбор не требуется — разбор по дельте
плюс всё, до чего эта дельта дотягивается (см. находку ниже: она лежит внутри
того же абзаца §9.2, который дельта редактирует).

## Закрытие раунда r3

| Находка r3 | Чем закрыта | Где видно |
|---|---|---|
| **Medium** — §9.2 не фиксирует источник rate-limit-адреса (только код/README, требование не переживёт рефакторинг `hp_relay/app.py`) | Частично: добавлен абзац в §9.2 «источник — последний элемент `X-Forwarded-For`, потому что прокси перезаписывает заголовок целиком», плюс **AC12a** в §13 и строка мутации в §14.4 | `docs/specs/043-private-support-report.md:446-452` (абзац §9.2), `:539` (AC12a), `:590-591` (§14.4). Текст дословно соответствует тому, что просил r3, **кроме** условности через `trusted_proxy` — см. новую находку ниже, это тот же абзац, не новый пробел, а недозакрытый прежний |
| **Low** (снят с запиской, не блокировал) — минимальная конфигурация вебхук-автоматизации не задокументирована в репозитории | Закрыт: полный YAML автоматизации (webhook-триггер, `local_only: false`, условие по `source`, `telegram_bot.send_message` с `parse_mode: plain_text`) добавлен в README | `scripts/support-relay/README.md:154-180`. Поля `source`/`text` в шаблоне совпадают буквально с тем, что шлёт код: `scripts/support-relay/hp_relay/delivery.py:180-184` (`HaWebhookDelivery.send`) формирует JSON именно с ключами `source`/`report_id`/`text` |

Low закрыт полностью и без оговорок. Medium закрыт **не полностью** — см. находку.

## Унаследовано из r3 (и через r3 — из r2/r1) без повторной проверки

Со ссылкой на `docs/reviews/SPEC-REVIEW-43-r3.md` (SHA `c43bf847`) и
транзитивно на r2 (`docs/reviews/SPEC-REVIEW-43-r2.md`, SHA `e25aa302`):

- §1–§8 — сценарий, UX-контракт, support package v1, backend API preview/
  discard/submit — дельта их не касается;
- §9.1 — два канала доставки (`telegram`/`ha_webhook`), запись до попытки
  доставки, privacy-текст §9.3 (кроме уже переоценённого абзаца §9.2) — не
  менялись этой дельтой, r3 проверил их построчно против кода
  (`hp_relay/delivery.py`, `app.py:107-116`, `config.py:66-68`);
- §10, §11 (включая каноническую фразу `Touch editor: supported`), §12;
- §13 AC1–AC11, AC13–AC17 (кроме новой AC12a);
- §15–§20, включая классификацию `scripts/support-relay/**` как class B
  (закрыта в r1→r2, переподтверждена в r3 живым прогоном `process-gate.mjs`);
- полный аудит `hp_relay/{multipart,validate}.py` — вне дельты r2→r3 и вне
  дельты r3→r4, предмет будущего код-ревью по AC5–AC12.

## Находки

### Medium (в скоупе #43, чинится в этой же задаче, вопрос технический — не владельцу)

**§9.2 закрывает находку r3 частично: описывает доверие к `X-Forwarded-For`
как безусловный архитектурный факт, а оно на самом деле включается флагом
конфигурации `HP_RELAY_TRUSTED_PROXY`, который в спеке, AC и списке
обязательных мутаций не упомянут вовсе.**

Читаю код (`scripts/support-relay/hp_relay/app.py:147-158`):

```python
def _source(self) -> str:
    if service.cfg.trusted_proxy:
        forwarded = self.headers.get("X-Forwarded-For", "")
        if forwarded:
            return forwarded.split(",")[-1].strip()
    return self.client_address[0]
```

`trusted_proxy` берётся из `HP_RELAY_TRUSTED_PROXY` (`config.py:82`, default
`"1"`) — то есть чтение последнего элемента `X-Forwarded-For` действует только
при этом флаге; иначе источником становится адрес TCP-соединения, то есть
(при реальной топологии, где Caddy проксирует на `127.0.0.1`) **один и тот же
адрес для всех клиентов**, что не «безопаснее», а means-один общий
частотный бакет на весь публичный эндпоинт: одна активная попытка исчерпывает
лимит для всех источников разом, а не для конкретного клиента, — деградация
той же анти-abuse истории (§16, риск 3), только в обратную сторону.

Новый абзац §9.2 (добавленный этой дельтой) не называет этот флаг вообще:

> «The relay reads the *last* element of `X-Forwarded-For`, because the first
> element is whatever the caller sent, and the reverse proxy in front of it is
> configured to overwrite the header outright rather than append to it.»

Это верно только пока `trusted_proxy=true`; сам разговор о существовании
такого выключателя, о том, что оба продовых хоста (`support.houseplan.tech`,
`support-staging.houseplan.tech`) обязаны держать его включённым, и о
поведении при выключенном — в спеке отсутствует.

**Это ровно тот класс дефекта, который сама находка r3 была призвана
устранить**: в коде — правильно и обдуманно (для флага есть отдельное имя,
дефолт и комментарий в `env.example:18-19`), а в ТЗ — не зафиксировано, значит
не переживёт следующий рефакторинг `hp_relay/app.py` (случайное удаление
`if service.cfg.trusted_proxy:` при сохранении `.split(",")[-1]` тихо
расширит доверие к заголовку на любую топологию, включая прямую экспозицию
порта без прокси). Ни `AC12a`, ни новая строка §14.4 эту ветку не покрывают:
обе называют только подмену индекса элемента (`[0]` вместо `[-1]`), а не
факт, что chтение заголовка вообще управляется флагом.

Проверено также, что тестового покрытия ветки `trusted_proxy=False` нет:
`grep -n "trusted_proxy" scripts/support-relay/tests/test_relay.py` — 0
совпадений. Ветка «адрес TCP-соединения» сейчас не проверяется ни одним
тестом.

**Чем закрыть, не открывая вопрос владельцу** (технический пункт по §7.1,
решает автор ТЗ, ревьюер вправе оспорить):

1. в §9.2 назвать флаг явно: доверие к `X-Forwarded-For` действует только при
   `HP_RELAY_TRUSTED_PROXY=1` (`trusted_proxy` в конфиге), и это обязательное
   состояние для `prod`/`staging` — при выключенном или отсутствующем прокси
   источником становится адрес TCP-соединения, и это осознанно более
   консервативный, а не эквивалентный режим (одна корзина на весь трафик, а
   не «без лимита»);
2. AC12a — добавить условие: гарантия действует только при `trusted_proxy`,
   включённом на обоих продовых хостах; это часть DoR/release, а не просто
   поведение по умолчанию;
3. §14.4 — добавить мутацию: снятие проверки `if service.cfg.trusted_proxy`
   (доверие XFF независимо от флага) должно ронять новый тест, которого
   сейчас нет — то есть пункт 3 требует и код (тест), не только текст ТЗ;
   зафиксировать это явно, а не оставлять как молчаливый пробел.

Серьёзность — Medium: не открывает утечку данных и не позволяет обойти лимит
сильнее, чем позволяет топология (пока `trusted_proxy` включён по умолчанию
и прокси настроен верно — как сейчас и есть), но ровно то самое несоответствие
кода и ТЗ, которое r3 уже один раз квалифицировал как Medium в этом же
абзаце. Не блокирует по High, но без исправления это жёлтый вердикт.

## Что проверено и признано корректным

- **Low r3 закрыт полностью**: YAML-шаблон автоматизации в README дословно
  совпадает с полями, которые шлёт `HaWebhookDelivery.send`
  (`source`/`report_id`/`text`), включая объяснение, почему `parse_mode:
  plain_text` обязателен (иначе текст пользователя разбирается как разметка).
- **Caddy-конфигурация** (`scripts/support-relay/deploy/Caddyfile.fragment`)
  подтверждена чтением: `header_up X-Forwarded-For {remote_host}` стоит на
  **обоих** сайтах (`support.houseplan.tech`, `support-staging.houseplan.tech`)
  без исключений — то есть при нынешнем деплое реальная топология
  соответствует тому, что описывает новый абзац §9.2 (с оговоркой из находки
  выше: соответствие держится на конфиге, а не на архитектурной гарантии).
- **AC12a и новая строка §14.4** внутренне непротиворечивы и совпадают с уже
  существующим (написанным до r3) тестом `test_client_cannot_pick_its_own_rate_bucket`
  (`scripts/support-relay/tests/test_relay.py:452-467`) — читал тест, он
  действительно шлёт три поддельных `X-Forwarded-For` и проверяет один общий
  ключ корзины в `spool/rate/*.json`.
- **Классификация `scripts/support-relay/**` class B** не затронута дельтой,
  живой прогон `node scripts/process-gate.mjs` на HEAD `cd8d01ac`: «гейт
  пройден, предупреждений 0» (офлайн, диапазон `origin/dev..HEAD`, 10
  коммитов).
- Коммит `cd8d01ac` несёт `Issue: #43` и `User-Visible: no` (docs-only,
  корректно — правки в спеку и README не меняют видимое поведение продукта).

## Чего не проверял и почему

- `npm test` / `npm run build` (сверка трёх копий бандла) — не прогонял сам:
  Validate на этом же SHA `cd8d01ac` завершился success (ссылка дана в
  задании), покрывает `tsc`/`test`/`build`; дельта раунда и так не трогает
  `src/**`, предмета для этих гейтов у неё нет.
- `node scripts/check-docs.mjs` — не требовался: дельта не трогает `src/**`.
- `npm run invariants` / инварианты модели — не требовались: дельта не
  трогает геометрию, `layout`, `marker.space`, `open_spans`.
- `python -m pytest tests_backend -q` — не требовался: дельта не трогает
  `custom_components/**`.
- `python3 -m unittest discover -s scripts/support-relay/tests` — **не
  перегонял сам в этом раунде**: код relay этой дельтой не менялся (только
  документация), а r3 уже прогнал полный набор (35/35 зелёных) и лично
  проверил мутациями оба относящихся к этому раунду теста
  (`test_client_cannot_pick_its_own_rate_bucket`,
  `test_webhook_sends_text_and_keeps_the_package_on_the_node`) на способность
  падать — наследую этот результат из r3 (см. таблицу наследования). Находка
  выше — про то, чего в этом наборе тестов нет (`trusted_proxy=False`), а не
  про то, что существующие тесты красные.
- Браузерные смоки, `npm run golden:verify` — не требовались: `src/**` для
  фичи #43 ещё не реализован (§1–§8 остаются на этапе ТЗ).
- Полный построчный аудит `hp_relay/{multipart,validate}.py` — вне дельты
  r3→r4, предмет будущего код-ревью по AC5–AC12.

## Гейты, которые прогнал сам

| Гейт | Результат |
|---|---|
| `node scripts/process-gate.mjs` | «гейт пройден, предупреждений 0» (офлайн, `origin/dev..HEAD`, 10 коммитов) |
| Чтение `hp_relay/app.py`, `config.py`, `env.example`, `test_relay.py`, `delivery.py`, `Caddyfile.fragment` | вручную, построчно — источник находки и подтверждения закрытий |
| `npx tsc --noEmit` / `npm test` / `npm run build` | не прогонял — Validate зелёный на этом же SHA `cd8d01ac` (см. задание раунда), дельта докс-онли |

## Вывод

Low r3 закрыт полностью. Medium r3 закрыт частично — тот же абзац §9.2
получил формулировку, которая верна только при включённом (по умолчанию, но
не зафиксированном как обязательное условие) флаге `trusted_proxy`, и это
условие не отражено ни в AC12a, ни в §14.4, ни где-либо ещё в ТЗ. High
находок нет. Вердикт — жёлтый, не блокирующий продвижение по High, но
возвращающий ТЗ на правку одного абзаца и одной AC-строки.