135 lines
7.9 KiB
Markdown
135 lines
7.9 KiB
Markdown
# PWA Demo Dashboard Implementation Plan
|
||
|
||
> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** Сделать приложение installable PWA и добавить на дашборд панель, которая объясняет PWA и офлайн-работу demo-режима.
|
||
|
||
**Architecture:** PWA-слой реализуется вручную поверх текущего Vite-приложения: `public/manifest.webmanifest`, `public/service-worker.js` и регистрация service worker в `src/main.jsx`. Отдельный клиентский хук инкапсулирует онлайн-статус, установку и готовность PWA, а UI-панель на обзорном дашборде читает этот статус и показывает объяснение ограничений офлайн-demo.
|
||
|
||
**Tech Stack:** React 18, Vite 6, Vitest, existing UI kit, browser Service Worker / PWA APIs.
|
||
|
||
---
|
||
|
||
## Chunk 1: PWA Infrastructure
|
||
|
||
### Task 1: Зафиксировать требования к PWA-статусу в тестах
|
||
|
||
**Files:**
|
||
- Create: `src/hooks/usePwaStatus.test.jsx`
|
||
- Create: `src/test/pwaTestUtils.js`
|
||
|
||
- [ ] Написать падающие тесты для хука `usePwaStatus` на:
|
||
- начальный онлайн-статус из `navigator.onLine`
|
||
- переключение при событиях `online` / `offline`
|
||
- появление install prompt после `beforeinstallprompt`
|
||
- определение standalone-режима через `matchMedia("(display-mode: standalone)")`
|
||
- [ ] Прогнать только новый набор тестов.
|
||
- Run: `npm test -- src/hooks/usePwaStatus.test.jsx`
|
||
- Expected: FAIL из-за отсутствующего хука и/или test utils
|
||
- [ ] Добавить минимальные test utils для стабов `matchMedia`, `BeforeInstallPromptEvent`-подобного объекта и очистки listeners.
|
||
- [ ] Повторно прогнать тесты и убедиться, что они всё ещё падают уже по ожидаемой причине, связанной с отсутствием реализации.
|
||
|
||
### Task 2: Реализовать PWA runtime state
|
||
|
||
**Files:**
|
||
- Create: `src/hooks/usePwaStatus.js`
|
||
- Modify: `src/main.jsx`
|
||
|
||
- [ ] Реализовать `usePwaStatus` с полями:
|
||
- `isOnline`
|
||
- `isInstallAvailable`
|
||
- `isInstalled`
|
||
- `isServiceWorkerSupported`
|
||
- `isOfflineReady`
|
||
- `installApp`
|
||
- [ ] Добавить регистрацию `service-worker.js` в `src/main.jsx` только в production/browser-контексте.
|
||
- [ ] Передать в хук признак готовности service worker через событие `controllerchange`, `message` или локальное состояние регистрации.
|
||
- [ ] Прогнать таргетированные тесты.
|
||
- Run: `npm test -- src/hooks/usePwaStatus.test.jsx`
|
||
- Expected: PASS
|
||
|
||
### Task 3: Добавить manifest, service worker и статические PWA-ресурсы
|
||
|
||
**Files:**
|
||
- Create: `public/manifest.webmanifest`
|
||
- Create: `public/service-worker.js`
|
||
- Create: `public/icons/icon-192.svg`
|
||
- Create: `public/icons/icon-512.svg`
|
||
- Modify: `index.html`
|
||
|
||
- [ ] Добавить manifest с русскими именами приложения, `display: "standalone"`, theme/background colors и иконками.
|
||
- [ ] Подключить manifest и базовые meta tags в `index.html`.
|
||
- [ ] Реализовать `public/service-worker.js` с:
|
||
- версионированным cache name
|
||
- precache app shell (`/`, `/index.html`, manifest, icons)
|
||
- navigation fallback на `/index.html`
|
||
- cache-first для same-origin статических ассетов
|
||
- сообщением клиенту о готовности офлайн-оболочки
|
||
- [ ] Добавить простые SVG-иконки, чтобы build/install не зависели от внешних файлов.
|
||
- [ ] Прогнать сборку.
|
||
- Run: `npm run build`
|
||
- Expected: PASS, в `dist/` появляются manifest и service worker
|
||
|
||
## Chunk 2: Dashboard Demo Panel
|
||
|
||
### Task 4: Зафиксировать UI-поведение панели в тестах
|
||
|
||
**Files:**
|
||
- Create: `src/components/dashboard/PwaDemoPanel.test.jsx`
|
||
- Create: `src/components/dashboard/PwaDemoPanel.jsx`
|
||
|
||
- [ ] Написать падающие тесты для панели на сценарии:
|
||
- показывает объяснение PWA и demo-режима на русском
|
||
- показывает online/offline badge
|
||
- показывает install CTA только когда установка доступна
|
||
- показывает ограничения для backend-интеграций
|
||
- [ ] Прогнать только тест панели.
|
||
- Run: `npm test -- src/components/dashboard/PwaDemoPanel.test.jsx`
|
||
- Expected: FAIL из-за отсутствующего компонента
|
||
- [ ] Реализовать минимальный `PwaDemoPanel` на `Panel`, `Badge`, `Button`.
|
||
- [ ] Повторно прогнать тест панели.
|
||
- Run: `npm test -- src/components/dashboard/PwaDemoPanel.test.jsx`
|
||
- Expected: PASS
|
||
|
||
### Task 5: Встроить панель в обзор дашборда
|
||
|
||
**Files:**
|
||
- Modify: `src/pages/DashboardPage.jsx`
|
||
- Optionally Modify: `src/components/UI/Badge.jsx` if понадобится новый tone
|
||
|
||
- [ ] Подключить `usePwaStatus` в `DashboardPage`.
|
||
- [ ] Разместить `PwaDemoPanel` в обзорной секции рядом с KPI/оперативными блоками без поломки существующей сетки.
|
||
- [ ] Убедиться, что панель рендерится только для авторизованного пользователя и не влияет на другие разделы.
|
||
- [ ] При необходимости добавить новый тон badge для позитивного статуса вместо инлайновых классов.
|
||
- [ ] Прогнать таргетированные тесты хука и панели вместе.
|
||
- Run: `npm test -- src/hooks/usePwaStatus.test.jsx src/components/dashboard/PwaDemoPanel.test.jsx`
|
||
- Expected: PASS
|
||
|
||
## Chunk 3: Verification and Hardening
|
||
|
||
### Task 6: Проверить интеграцию вручную и автоматикой
|
||
|
||
**Files:**
|
||
- Modify: `README.md`
|
||
- Optionally Modify: `docs/architecture.md`
|
||
|
||
- [ ] Обновить README кратким описанием PWA/demo offline behavior.
|
||
- [ ] При необходимости добавить в `docs/architecture.md` модуль `usePwaStatus` и описание PWA-оболочки.
|
||
- [ ] Запустить полный тестовый набор.
|
||
- Run: `npm test`
|
||
- Expected: PASS
|
||
- [ ] Запустить линтер.
|
||
- Run: `npm run lint`
|
||
- Expected: PASS
|
||
- [ ] Запустить production build.
|
||
- Run: `npm run build`
|
||
- Expected: PASS
|
||
- [ ] Выполнить ручную проверку:
|
||
- открыть приложение онлайн
|
||
- войти в demo-режиме
|
||
- убедиться, что сервис-воркер зарегистрирован
|
||
- перевести браузер offline
|
||
- перезагрузить `/dashboard` и убедиться, что оболочка и demo-данные остаются доступны
|
||
- проверить install CTA в поддерживаемом браузере
|
||
- [ ] Зафиксировать итог коротким комментарием в ответе пользователю: что работает офлайн, а что остаётся сетевым ограничением.
|