food-market/docs/sprint17-progress.md

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.

Чек-лист

• 1. Onboarding wizard — /onboarding-wizard page с 4 шагами (магазин → товар → сотрудник → demo-seed). Каждый skip'абельный. После — localStorage.fm.wizardCompleted=1 и redirect на /dashboard. Playwright тесты 9.1-9.3 (smoke + skip + сохранение).
• 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.
• 3. /help knowledge base — /help страница, 7 markdown topics в src/help/*.md, загружаются через import.meta.glob, custom mini-markdown-renderer (headings, lists, bold, code). Поиск по title + body на клиенте.
• 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.
• 5. /admin/diagnostic — /admin/diagnostic page для Admin/SuperAdmin. 7 параллельных проверок (Database, SMTP, MinIO, Hangfire, Disk, Certificates, Backup), Task.WhenAll, ~1с прогон. 🟢/🟡/🔴 индикаторы + Details. Опц. sendTestEmail чекбокс.
• 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.
• 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 есть, ждём скрин-капсы / видео.