f56c6efab1
Sprint 17 — onboarding-контур: 4-шаг wizard, контекстный help, in-app
feedback, admin self-diagnostic, /whats-new из CHANGELOG.md.
Ключевые цифры:
- Wizard: 4 шага + skip каждого, 7 e2e тестов ✓ за 20 секунд.
- Diagnostic: 7 параллельных проверок, ~80ms на stage.
- Bundle impact: initial +4 KB gzip (только FeedbackWidget +
HelpTooltip + EmptyStateWithDemo в основном bundle; страницы lazy).
- Regression-suite: 35 → 42 flows + 60 → 66 visual snapshots.
Backend (новые endpoint'ы):
- /api/admin/diagnostic/run — 7 параллельных проверок (DB, SMTP,
MinIO, Hangfire, диск, сертификаты, бэкап). Task.WhenAll, ~80ms.
- /api/feedback — POST {category, message}, email на FromEmail +
Telegram (если SupportTelegram:* настроены). Rate-limit 5/час.
- /api/whats-new — парсер CHANGELOG.md, возвращает {buildVersion,
items}. Dockerfile.api копирует CHANGELOG.md в content-root +
пишет VERSION из GIT_SHA build-arg.
Frontend:
- /onboarding-wizard — 4-step builder, состояние в useState,
localStorage.fm.wizardCompleted после завершения.
- <HelpTooltip topic="key"/> — popover на каждой странице, mapping
src/lib/help-topics.ts (13 keys).
- /help — knowledge base, 7 markdown topics через import.meta.glob,
mini-renderer без heavy deps, fuzzy search.
- /whats-new — список из /api/whats-new, иконки по типу (feat/fix).
- /admin/diagnostic — Admin/SuperAdmin only, 🟢/🟡/🔴 индикаторы.
- <FeedbackWidget> в sidebar footer + ссылки на /help и /whats-new.
- <EmptyStateWithDemo> placeholder для будущих видео-демо.
scripts/generate-changelog.sh — git log feat:/fix: за 90 дней
→ CHANGELOG.md (307 строк сгенерировано).
Wizard UX-screenshots в docs/sprint17-screenshots/ (6 PNG: 4 шага +
help + diagnostic).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
158 lines
8.7 KiB
Markdown
158 lines
8.7 KiB
Markdown
# 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 есть, ждём
|
||
скрин-капсы / видео.
|