Регламент обработки обратной связи (SFHD)

Как обращения пользователей проходят путь от получения до выпуска фикса.
Цель — заложить дисциплину продуктовой команды уже в Pre-Alpha: обращения
не теряются, у каждого прозрачный статус, понятные ориентиры по срокам реакции,
единый путь от получения до релиза.

Адаптировано под нашу реальность:

• Источник правды — YouTrack, проект SFHD (Skyforge Help Desk).
• Команда = основатель (Product Owner + Support + триаж) + ИИ-агенты
  (разработка + автотесты как QA). Агенты работают 24/7, поэтому мелкие баги
  часто чинятся быстро — но жёстких публичных обязательств по срокам мы не
  даём (см. SLA).
• Уведомления автоматические — автор узнаёт о приёме и о решении без ручных
  действий команды.

Технический разбор интеграции (модули, коллекции, джобы) — на странице
Обратная связь → YouTrack. Здесь — процесс.

1. Каналы → единый бэклог SFHD

Все обращения, из какого бы канала ни пришли, сводятся в один бэклог — issue в
проекте SFHD. Единый вход исключает «потерянные» каналы и даёт одну доску
для триажа.

Правило: новый канал не заводит свой бэклог — он тоже конвертируется в issue
SFHD (механика создания issue — AD-672).

2. Регистрация (автоматически)

Обращение фиксируется без участия команды (виджет AD-671 → создание issue
AD-672). Что попадает в карточку:

• ID — issue в SFHD (плюс внутренний feedback_id обращения);
• дата/время получения;
• пользователь (user_id, если вошёл) + email (из формы для гостя или
  email вошедшего — по нему замыкается петля к автору);
• версия продукта;
• браузер / ОС (User-Agent);
• текст обращения;
• авто-контекст: URL страницы, User-Agent; логи/скриншот — если приложены.

Стартовый статус — New. Пользователю сразу уходит авто-подтверждение
получения. Это обязательно, даже если фикс не планируется в ближайшее время:
человек должен видеть, что обращение принято.

3. Классификация (тег issue)

При триаже обращению проставляется категория (тег issue в SFHD):

Реализация на сегодня (AD-672): при создании issue автоматически ставится
грубый тег (bug / idea) по типу обращения из виджета. Финальную категорию
из таблицы уточняет основатель при триаже в YouTrack.

4. Severity → поле Priority YouTrack

Серьёзность обращения задаётся через штатное поле Priority issue. Маппинг:

Severity проставляет основатель на триаже. S5 (пожелания/улучшения) severity не
получают — они живут своим циклом Feature Request (см. ниже).

5. Жизненный цикл обращения

Компактный набор состояний доски SFHD:

New → Triage → (Invalid / Duplicate — выход)
             → Accepted → In Progress → In Review/Testing
             → Done (вошло в релиз) → авто-уведомление автору → Closed

• New — только что получено, ждёт триажа.
• Triage — основатель классифицирует: тег, severity → Priority, дубль/валидность.
• Invalid / Duplicate — терминальный выход из потока (дубль линкуется к
  оригиналу, автор всё равно получает ответ).
• Accepted — принято в работу.
• In Progress — агент реализует фикс.
• In Review / Testing — код-ревью + автотесты (QA-роль агентов).
• Done — фикс вошёл в релиз. Переход в решённое триггерит
  авто-уведомление автору (петля AD-672 → доставка AD-662/665).
• Closed — цикл закрыт.

Мост в бэклог разработки. Принятый на триаже баг/фича заводит атомарный
тикет AD-NNN (проект AD — бэклог разработки), связанный с обращением
SFHD; фикс дальше идёт обычным протоколом тикета. Обращение SFHD — вход и
«петля к автору»; работа живёт в AD. Когда фикс входит в релиз, issue SFHD
переводится в решённое → авто-уведомление автору. Как это встроено в регулярный
анализ (триаж как источник находок наравне с код-ревью) —
docs/dev/review-playbook.md § 5.

Авто-закрытие парного SFHD при мерже (AD-1045). Раньше «когда фикс
входит в релиз, issue SFHD переводится в решённое» было ручной операцией —
AD-тикет закрывался автоматически (youtrack-sync), а его связанный SFHD
нет, и список обращений «не таял», хотя работа была сделана. Теперь связка
закрывается СРАЗУ И АВТОМАТИЧЕСКИ: если заголовок смерженного AD-NNN несёт
номер парного обращения в скобках (конвенция — AD-1043 — … (SFHD-84)),
youtrack-sync парсит его и переводит SFHD-NN в состояние Solved
(кастомное поле State доски SFHD) + оставляет комментарий-трейс.
Идемпотентно (уже Solved — но-оп) и best-effort по правам токена (нет
доступа к проекту SFHD — честный WARNING в логе job-ы, AD-сторона уже
закрыта и не откатывается). Код — scripts/youtrack_sync.py
(parse_sfhd_id/close_paired_sfhd).

Гейт: обращения НЕ от основателя (AD-857, SFHD-67). Обращение, автор
которого не основатель (аноним или залогиненный не-админ), не идёт по мосту
выше автоматически — оно попадает в очередь модерации /admin/moderation
(approval_status="pending" в коллекции feedback) и ждёт решения
основателя (одобрить / отклонить с причиной). Не заводить AD-тикет по
SFHD-issue, если связанное обращение ещё pending — перед созданием
тикета сверьтесь функцией feedback_store.approval_status_by_id(feedback_id)
(feedback_id — в теле issue, блок «Контекст обращения»); pending —
тикет не заводим, ждём решения. Обращение основателя апрува не требует
(approval_status="not_required" — поведение без изменений). Отклонённый
автор получает уведомление «обращение не будет реализовано» (механизм —
как у Feature Request «Отклонено» ниже). Best-effort маркер в самом issue —
тег needs-founder-approval; источник истины — поле в Mongo, не тег.

Feature Request — отдельная ветка

После триажа запрос новой возможности идёт не по багфикс-циклу, а получает
одно из состояний (без фиксированного SLA на реализацию):

• Запланировано — берём в roadmap;
• На рассмотрении — идея принята к обдумыванию, сроков нет;
• Отклонено — не вписывается в продукт (с причиной автору).

Ключевое для системы: переход issue в «решено/Done» автоматически
уведомляет автора. Состояния доски настраиваются в проекте SFHD.

6. SLA — ориентиры Pre-Alpha

Это best-effort ориентиры, а не публичные обязательства. Команда = один
основатель + ИИ-агенты 24/7. Агенты работают ночью, поэтому мелкие баги нередко
чинятся быстро — но жёстких сроков перед пользователем мы не гарантируем.

Ужесточаем по мере роста команды. Целевой ориентир при штате — таблица из
оригинального регламента (напр., S1: первичный ответ 2 часа и т.д.). Пока —
внутренние ориентиры, а не контракт с пользователем.

7. Правила Pre-Alpha

Обязательные к соблюдению даже при минимальной команде:

1. Каждое обращение получает авто-подтверждение и обязательно проходит
   триаж — даже если фикс не планируется.
2. Feature Request — без фиксированного SLA на реализацию; после триажа:
   Запланировано / На рассмотрении / Отклонено.
3. Перед каждым релизом основатель делает ревизию открытого бэклога
   SFHD и формирует список вошедших фиксов → в changelog и в текст
   уведомления автору («войдёт в версию X»).

8. Лёгкие KPI (ежемесячно)

Метрики держим простыми; автоматизируем позже.

• % обращений, прошедших триаж в срок (по ориентирам выше);
• 100% обращений имеют категорию + приоритет;
• S1 быстро получает владельца;
• FRT — среднее время первого ответа;
• MTTR — среднее время до решения;
• Reopen Rate ≤ 5% — доля переоткрытых после «решено»;
• Топ-10 частых проблем;
• Число обращений по релизам.

9. Как это ложится на код

Регламент опирается на уже смердженную механику эпика AD-673. Соответствие
шагов процесса и реализации:

Приоритет конфигурации YouTrack: админ-конфиг (/admin/integrations, AD-674)
→ env → вшитый дефолт. Проект по умолчанию — SFHD, URL —
https://aagafonov.youtrack.cloud; на проде основателю достаточно ввести один
токен. Подробности — Обратная связь → YouTrack.

Связи

Часть эпика AD-673; опирается на AD-671 / AD-672 / AD-674, AD-662 /
AD-665, AD-609; перекликается с методологией ревью (AD-634). Триаж
обращений как источник находок регулярного ревью —
docs/dev/review-playbook.md § 5 (AD-718).
Процессный документ (AD-675).