Mk
/
supersam
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
supersam/docs/superpowers/plans/2026-03-14-pwa-demo-dashboa...

7.9 KiB
Raw Permalink Blame History

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 в поддерживаемом браузере

  • Зафиксировать итог коротким комментарием в ответе пользователю: что работает офлайн, а что остаётся сетевым ограничением.