# Sprint 17 — onboarding wizard + help + self-diagnostic + changelog

Цель: «новый пользователь не должен теряться» — onboarding wizard за
4 шага, контекстная help-tooltip-ы, knowledge-base /help, feedback,
admin self-diagnostic /admin/diagnostic, /whats-new из CHANGELOG.

Старт: 2026-06-07 (после Sprint 16). Исполнитель: Claude Opus 4.7.

## Принципы

- Wizard — skip каждого шага доступен.
- Help-tooltip-ы — короткие (≤2 предложения) с deep-link на /help.
- Diagnostic — 7 проверок, async параллельный прогон <1с.
- НЕ трогать: `global.json`, prod admin.food-market.kz, POS WPF.

## Чек-лист

- [x] **1. Onboarding wizard** — `/onboarding-wizard` page с 4 шагами
  (магазин → товар → сотрудник → demo-seed). Каждый skip'абельный.
  После — `localStorage.fm.wizardCompleted=1` и redirect на /dashboard.
  Playwright тесты 9.1-9.3 (smoke + skip + сохранение).
- [x] **2. HelpTooltip + topics** — `src/lib/help-topics.ts` с 13
  topics. `<HelpTooltip topic="key"/>` — popover с title + short +
  deep-link на /help#key. Click-outside / Esc / aria-expanded.
- [x] **3. /help knowledge base** — `/help` страница, 7 markdown
  topics в `src/help/*.md`, загружаются через `import.meta.glob`,
  custom mini-markdown-renderer (headings, lists, bold, code).
  Поиск по title + body на клиенте.
- [x] **4. In-app feedback widget** — `<FeedbackWidget>` в sidebar
  footer. Modal с 3 категориями (Bug/Suggestion/Question). POST
  `/api/feedback` → email на FromEmail из PlatformSettings + Telegram
  (опц.). Rate-limit 5/час per-user.
- [x] **5. /admin/diagnostic** — `/admin/diagnostic` page для
  Admin/SuperAdmin. 7 параллельных проверок (Database, SMTP, MinIO,
  Hangfire, Disk, Certificates, Backup), `Task.WhenAll`, ~1с прогон.
  🟢/🟡/🔴 индикаторы + Details. Опц. `sendTestEmail` чекбокс.
- [x] **6. /whats-new + CHANGELOG** — `scripts/generate-changelog.sh`
  генерирует `CHANGELOG.md` из `git log --grep='feat\|fix'`. Endpoint
  `/api/whats-new` парсит markdown → последние 30 дней. UI `/whats-new`
  с группировкой по дате + icon (Sparkles=feat, Bug=fix).
  Dockerfile.api копирует `CHANGELOG.md` в content-root + создаёт
  `VERSION` файл из `GIT_SHA` build-arg'a.
- [x] **7. Empty-states CTA** — `<EmptyStateWithDemo>` reusable
  component с placeholder'ом для будущих видео-демо и fallback на
  /help#topic.

## Замеры

### Wizard UX-screenshots

Сохранены в `docs/sprint17-screenshots/`:
- `wizard-step-1.png` — магазин (название + адрес)
- `wizard-step-2.png` — первый товар (имя + цена + штрихкод)
- `wizard-step-3.png` — первый сотрудник (Ф.И.О. + email + роль)
- `wizard-step-4.png` — demo-данные («Заполнить» / «Не нужно»)
- `help-page.png` — `/help` с sidebar групп + body topic'ов
- `admin-diagnostic.png` — `/admin/diagnostic` с результатом 7 проверок

### Diagnostic результат на stage'е (вживую)

| Check | Status | Duration | Details |
|---|---|---|---|
| Database | 🟢 Ok | ~50ms | все миграции применены |
| SMTP | 🟡 Warning | ~10ms | SMTP не настроен (PlatformSettings пуст) |
| MinIO | ⚪ Skipped | <10ms | Storage:Type ≠ minio, локальный FS |
| Hangfire | 🟢 Ok | ~10ms | 5 recurring jobs зарегистрировано |
| Disk | 🟢 Ok | ~5ms | свободно > 5 GB |
| Certificates | 🟢 Ok | ~10ms | dev-режим OpenIddict-ключей |
| Backup | 🟡 Warning | <5ms | папка `/opt/food-market-data/backups` не существует на dev-vm (нормально) |
| **Overall** | **🟡 Warning** | ~80ms | 2 warning'a (SMTP + backup) |

### Regression-test suite расширен

Sprint 16 baseline (35 тестов) + Sprint 17 добавил 7 flow-тестов
в `flows/09-onboarding-wizard.spec.ts`:
- 9.1 wizard рендерится с progress-bar
- 9.2 skip всех 4 шагов → /dashboard + wizardCompleted=1
- 9.3 сохранение названия магазина → org.name обновлён в API
- 9.4 /help рендерит topic'и + поиск работает
- 9.5 /api/admin/diagnostic/run возвращает 7 проверок
- 9.6 POST /api/feedback ok с минимальным payload
- 9.7 /api/whats-new возвращает buildVersion + items

**Result**: 7/7 ✓ за ~20 секунд. Suite теперь **42 flow + 60 visual + 6 wizard-screenshots**.

### Bundle impact

| | До Sprint 17 | После | Δ |
|---|---|---|---|
| Initial JS (raw) | 706.76 KB | **723.37 KB** | +17 KB |
| Initial JS (gzip) | 196.50 KB | **200.53 KB** | +4 KB |

Новые страницы (HelpPage, WhatsNewPage, AdminDiagnosticPage,
OnboardingWizardPage) — все lazy chunks. В initial bundle только
`<FeedbackWidget>` (Modal-обёртка), `<HelpTooltip>` и
`<EmptyStateWithDemo>` (~4 КБ gzip суммарно).

## Журнал

### 2026-06-07 старт
Sprint 16 закрыт (6/6 ✓). Поехали по onboarding-чек-листу.

### 2026-06-07 п.5,6 (backend endpoints)
DiagnosticController с 7 параллельными проверками + FeedbackController
с rate-limit + WhatsNewController парсер CHANGELOG.md.

### 2026-06-07 п.1 (wizard)
`OnboardingWizardPage` с 4 step-компонентами. State через useState,
api-mutate через TanStack Query. `/onboarding-wizard` маршрут.
Skip-кнопка в footer'е каждого шага. `fm.wizardCompleted` в
localStorage предотвращает повторный показ.

### 2026-06-07 п.2-3 (HelpTooltip + /help)
`help-topics.ts` с 13 keys. `<HelpTooltip>` с click-popover, aria-label,
Esc/click-outside dismiss. `/help` страница — `import.meta.glob` на
`src/help/*.md` + парсер front-matter + mini-markdown renderer без
зависимости от markdown-it.

### 2026-06-07 п.4 (feedback widget)
`<FeedbackWidget>` в sidebar footer. Modal с 3 категориями. API
возвращает `deliveredEmail`/`deliveredTelegram` булевые — фронт
показывает «отправлено через {каналы}» в toast.

### 2026-06-07 п.7 (empty-state)
`<EmptyStateWithDemo>` reusable. Placeholder для видео-демо
(`demoVideoUrl` prop) — пока показывает кнопку «Подробнее в базе
знаний» ссылкой на `/help#topic`.

### 2026-06-07 deploy + retest
- Сначала упал TS build из-за апострофа в строке single-quoted
  (`refresh'е` ломал литерал) — исправил переключением на двойные.
- Неиспользуемый interface `OrgSettings` — удалил.
- DiagnosticController вернул `overall: 2` (enum как int) —
  добавил `[JsonStringEnumConverter]` на CheckStatus enum.
- 7/7 wizard/help/diagnostic/feedback/whats-new e2e тестов ✓.
- 6 wizard-screenshots сохранены в `docs/sprint17-screenshots/`.

## Итог

Все 7 пунктов ✓. Локальные числа:
- **Wizard**: 4 шага + skip, 7 Playwright тестов ✓ за 20 секунд.
- **Help**: 7 markdown topics + 13 keys в HelpTooltip mapping.
- **Diagnostic**: 7 проверок, прогон ~80ms на stage'е, на текущий
  момент 🟡 (2 warning'a — SMTP не настроен + нет backup-папки).
- **Feedback**: email + Telegram дубль, 5/час rate-limit.
- **CHANGELOG**: 307 строк из git log за 90 дней.
- **/whats-new**: возвращает buildVersion + items до 30 дней назад.
- **Regression suite**: **42 flows + 60 visual + 6 wizard-shots** ✓.

Следующее расширение (TODO для будущих спринтов):
- Расставить `<HelpTooltip>` рядом с заголовком на Loyalty, Promotions
  и других новых страницах — компонент готов.
- Banner «Появились новые функции» при mismatch'е
  `localStorage.fm.lastSeenBuildVersion` с фактическим
  `BuildVersion` — endpoint готов, нужно вписать в AppLayout.
- Видео-демо в `<EmptyStateWithDemo>` — placeholder есть, ждём
  скрин-капсы / видео.