diff --git a/docs/specs/043-private-support-report.md b/docs/specs/043-private-support-report.md index 2b2ceb9a..fa94e73f 100644 --- a/docs/specs/043-private-support-report.md +++ b/docs/specs/043-private-support-report.md @@ -1,60 +1,645 @@ -# ТЗ #43 — Отчёт для поддержки без персональных данных +# ТЗ #43 — Помощь и обратная связь с обезличенным support package - Issue: https://github.com/Matysh/houseplan-card/issues/43 -- Приоритет: P2 -- Статус ТЗ: draft, privacy defaults нормативны +- Приоритет: P2, feature +- Ревизия: 2 (2026-09-01), полная переработка после финального решения владельца +- Трек: полный — новый View UX, frontend + backend + внешний relay, + privacy/security contract и обязательная touch-поддержка -## Цель +## 1. Сценарий -Пользователь копирует воспроизводимый технический snapshot, предварительно -видя весь текст. Default report не содержит данных, по которым можно -восстановить дом, устройства или адреса. +Домашний администратор видит проблему на плане или хочет предложить улучшение. +Сейчас ему приходится отдельно искать чат/репозиторий, выяснять версии, вручную +экспортировать план и гадать, какие данные можно безопасно показывать. В результате +репорт часто нельзя воспроизвести либо пользователь пересылает лишние сведения о +доме и устройствах. -## Формат +В обычной шапке House Plan администратор открывает «Помощь и обратная связь», +читает версию и документацию, пишет сообщение и при желании осознанно прикладывает +подготовленный House Plan обезличенный диагностический пакет. До отправки он видит +состав, размер и точные байты вложения. После успешной отправки получает номер +репорта, по которому можно продолжить разговор в Telegram или GitHub. -Versioned JSON/text envelope `houseplan_support_report: 1`: +Персона: **Home admin** из `docs/SCOPE.md`. Основная поверхность — View в desktop, +phone/tablet и HA Companion. Диалог, открытый поверх View, полностью поддерживается +на touch по `docs/TOUCH-SUPPORT.md`; редакторы остаются desktop-first, но тот же +диалог в них не деградирует. -- card, integration и HA versions; -- browser engine family/major и supported feature flags без user-agent string; -- model/config/layout schema versions и revisions; -- counts: spaces, rooms, room drafts, physical/open walls, partitions, - columns, openings по типу, decor по kind, markers по lifecycle/status; -- read-only validation result: stable codes + counts; -- optimizer/migration pending flags; -- active House Plan Repair issue ids/codes без descriptions/user values; -- registry authority level (`full|limited|unknown`) и last sync age bucket; -- checksum только структуры/schema, не raw config. +## 2. Что человек увидит до и после -## Privacy allowlist +**До:** блок «О карточке» спрятан в конце общих настроек; отдельной ссылки на +USER-GUIDE нет; формы обратной связи и безопасного общего диагностического +вложения нет. HA diagnostics и обычный backup требуют ручных действий и содержат +данные, которые нельзя автоматически отправлять третьей стороне. -Report строится исключительно из typed allowlist projection. Запрещены: -space/room/device/entity names и ids, area/floor/config-entry ids, coordinates, -polygons, URLs, filenames/paths, descriptions, templates/live values, IP/host, -HA installation id, exact timestamps событий. Redaction после сериализации не -считается защитой. +**После:** сразу после кнопки общих настроек находится круглая кнопка помощи. Она +открывает единый диалог с версией, GitHub, Telegram, языковой ссылкой на USER-GUIDE +и формой «Отправить репорт/предложение». Сообщение обязательно, контакт +необязателен. Чекбокс диагностического пакета по умолчанию выключен. При включении +пользователь предупреждён о точной геометрии дома, может проверить или скачать +ровно отправляемый JSON и только затем нажать «Отправить». Успех показывает номер +репорта; отказ ничего не стирает и предлагает повторить либо забрать пакет вручную. -Adversarial fixture заполняет каждое запрещённое поле уникальным sentinel; -ни один sentinel/его URL-encoded/base64 form не встречается в report. +## 3. Проблема и подтверждённое текущее состояние -## Архитектура +### 3.1 UI -Backend read-only `houseplan/support/report` выполняет authoritative schema, -store и Repair projection; frontend добавляет card/browser flags. Command -доступен authenticated user, не делает writes/services и возвращает stable -error codes. Если backend старый, frontend создаёт reduced report и явно это -пишет. +- Header-кнопка общих настроек живёт в `src/houseplan-card.ts` и рендерится при + `_norm && _canEdit`; kiosk скрывает всю шапку. +- «О карточке» находится в `src/houseplan-editor-runtime.ts` внутри диалога общих + настроек: версия, GitHub и Telegram. +- Editor runtime уже загружается лениво при открытии общих настроек. Новый диалог + использует ту же lazy boundary: обычный холодный View не должен платить размером + формы поддержки и её логики. -## UX +### 3.2 Диагностика и backup -General Settings → Maintenance → «Скопировать отчёт для поддержки». Открывается -wide `hp-dialog` с plain-text preview, предупреждением privacy и действиями -Copy/Download/Cancel. Clipboard failure предлагает `.json` download. Никакой -автоматической отправки/телеметрии. +- `houseplanDiagnostics()` отдаёт только узкую frontend-сводку registry/bindings. +- #295 добавила копируемую runtime-диагностику geometry preflight, но только для + одного класса отказов. +- `custom_components/houseplan/diagnostics.py` предназначен для HA Download + diagnostics. Его redaction не является allowlist: marker/settings payload и + внутренние ids нельзя пересылать автоматически. +- `create_export()` строит согласованный переносимый backup до 8 MiB, однако + обычный backup содержит имена, ссылки, ids, свободный текст и точную геометрию. + Он служит источником структуры и snapshot-механики, но **не** готовым support + attachment. -## Приёмка +### 3.3 Transport -- sentinel privacy corpus зелёный frontend/backend; -- preview полностью равен copied/downloaded bytes; -- report работает при invalid config, limited registry и active Repairs; -- copy/download доступен keyboard/touch; -- документация перечисляет включённые и исключённые категории. +В репозитории нет feedback endpoint. Публичный GitHub issue раскрывает вложение; +Telegram share и `mailto:` не умеют без ручного шага приложить большой JSON; +секрет почты/GitHub нельзя вшивать ни в card bundle, ни в Python integration. +Поэтому direct submit требует отдельного доверенного relay с секретами только на +его стороне. + +## 4. Решения владельца + +1. В шапке после общих настроек появляется отдельная кнопка с иконкой вопроса в + кружке. +2. «О карточке» целиком переезжает из общих настроек в новый диалог. +3. В диалоге есть ссылка на `docs/USER-GUIDE.ru.md` только для русского языка; + любой другой язык ведёт на английский `docs/USER-GUIDE.md`. +4. Форма содержит необязательный контакт, обязательное сообщение и opt-in + диагностическое вложение. +5. Q1–Q4 приняты по defaults из issue: project-controlled HTTPS relay, точная + геометрия в support snapshot, preview точных байтов, доступ только `can_write`, + отсутствие кнопки в kiosk. +6. Подпись контактного поля на русском фиксирована владельцем: + **«Контакт для связи (email/tg/WhatsApp), необязательно.»** + +## 5. Скоуп + +### 5.1 Входит + +- Help/Feedback-кнопка в текущей шапке и отдельный `hp-dialog`; +- перенос существующего блока «О карточке» без потери ссылок; +- языковая ссылка на USER-GUIDE; +- форма и её состояния validation/building/sending/success/error; +- backend allowlist-проекция и псевдонимизация текущего согласованного snapshot; +- preview-token, гарантирующий «просмотренные байты = отправленные байты»; +- backend submit в фиксированный project-controlled relay; +- минимальный deployable relay, который валидирует payload, ограничивает abuse и + пересылает обращение в закрытый support-mailbox; +- privacy notice, rate limit, retention и документированный ручной recovery; +- RU/EN/DE/FR i18n, unit/backend/receiver/smoke/golden/touch/security tests; +- обновление пользовательской и архитектурной документации. + +### 5.2 Не входит + +- автоматическая telemetry, фоновые или периодические отчёты; +- создание публичного GitHub issue либо отправка в публичный Telegram-чат; +- двусторонний встроенный support-chat, история обращений и статус тикета; +- произвольные пользовательские вложения; +- исходные plan/backdrop images, PDF, manuals и другие бинарные файлы; +- сохранённый optimizer/import undo-backup и история версий плана; +- настройка пользователем собственного endpoint; +- доступ household/guest-пользователей без `can_write`; +- kiosk-кнопка; +- изменение остальных backup/export/HA diagnostics flows; +- сбор HA state values, журналов, stack traces или exception messages. + +## 6. UX-контракт + +### 6.1 Кнопка + +- Иконка: `mdi:help-circle-outline` в существующей круглой `.btn`-оболочке. +- Порядок справа: zoom controls → General Settings → Help/Feedback. +- Условие видимости **то же, что у General Settings**: `_norm && _canEdit`; + kiosk не рендерит интерактивную поверхность. +- Кнопка видна в View, Plan, Devices и Backdrop editor. Открытие диалога не меняет + mode, zoom, selection, черновик или unsaved form другого редактора. +- Доступное имя: локализованное «Помощь и обратная связь». + +### 6.2 Диалог + +Заголовок: «Помощь и обратная связь», icon `mdi:help-circle-outline`, wide +`hp-dialog`, `dismiss-on-scrim`. Порядок блоков: + +1. **О карточке** — текущая версия card, GitHub и Telegram, без изменения URL. +2. **Документация** — ссылка «Руководство пользователя»: + - effective language `ru` → + `https://github.com/Matysh/houseplan-card/blob/main/docs/USER-GUIDE.ru.md`; + - `en`, `de`, `fr`, неизвестный/пустой язык → английский `USER-GUIDE.md`. + Ссылка открывается в новой вкладке с `rel="noopener noreferrer"`. +3. **Отправить репорт/предложение** — форма ниже. + +Из General Settings удаляются только label/version/GitHub/Telegram строки. Все +настройки, backup и plan maintenance остаются на месте; высвободившийся блок не +заменяется дублирующей ссылкой. + +### 6.3 Поля формы + +1. Однострочный ``: + «Контакт для связи (email/tg/WhatsApp), необязательно.» + - optional; + - trim по краям; + - максимум 320 Unicode code points; + - формат не валидируется как email/phone: допустим username или пояснение; + - автозаполнение отключено (`autocomplete="off"`), значение не сохраняется. +2. Многострочный `