docs(08-mobile-pwa): create phase plan

2026-03-25 20:34:24 -06:00
parent 467a994d9f
commit d9b022bd4c
5 changed files with 1077 additions and 6 deletions
--- a/.planning/phases/08-mobile-pwa/08-04-PLAN.md
+++ b/.planning/phases/08-mobile-pwa/08-04-PLAN.md
@@ -0,0 +1,143 @@
+---
+phase: 08-mobile-pwa
+plan: 04
+type: execute
+wave: 3
+depends_on:
+  - "08-01"
+  - "08-02"
+  - "08-03"
+files_modified: []
+autonomous: false
+requirements:
+  - MOB-01
+  - MOB-02
+  - MOB-03
+  - MOB-04
+  - MOB-05
+  - MOB-06
+
+must_haves:
+  truths:
+    - "All portal pages render correctly on mobile (320px) and tablet (768px) viewports"
+    - "Bottom tab bar navigation works with RBAC filtering"
+    - "Chat full-screen flow works end-to-end on mobile"
+    - "PWA is installable and shows correct icon/splash"
+    - "Push notifications received on installed PWA"
+    - "No hover-stuck interactions on touch devices"
+  artifacts: []
+  key_links: []
+---
+
+<objective>
+Human verification of all mobile and PWA features across device viewports and interaction modes.
+
+Purpose: Mobile UX cannot be fully validated by automated tests. This checkpoint confirms that the responsive layout, touch interactions, PWA install, and push notifications work correctly on real device viewports.
+
+Output: Human-verified sign-off that all MOB requirements are met.
+</objective>
+
+<execution_context>
+@/home/adelorenzo/.claude/get-shit-done/workflows/execute-plan.md
+@/home/adelorenzo/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/phases/08-mobile-pwa/08-CONTEXT.md
+@.planning/phases/08-mobile-pwa/08-01-SUMMARY.md
+@.planning/phases/08-mobile-pwa/08-02-SUMMARY.md
+@.planning/phases/08-mobile-pwa/08-03-SUMMARY.md
+</context>
+
+<tasks>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <name>Task 1: Verify all mobile and PWA features</name>
+  <files></files>
+  <action>
+    Present the verification checklist to the user. All implementation was completed in Plans 01-03. This task verifies the results.
+
+    What was built:
+    - Bottom tab bar navigation (5 items) with More bottom sheet on mobile
+    - Desktop sidebar preserved on screens >= 768px
+    - Full-screen WhatsApp-style chat flow on mobile
+    - iOS virtual keyboard handling for chat input
+    - PWA manifest with K monogram icons
+    - Service worker with offline caching
+    - Push notifications for AI Employee responses
+    - Offline message queue with auto-drain
+    - Second-visit install prompt
+    - Offline status banner
+
+    How to verify:
+
+    **Setup:** Start the portal with `npm run dev` (or `npm run dev:pwa` with `--experimental-https --webpack` for full PWA testing).
+
+    **MOB-01 — Responsive pages (all viewports):**
+    1. Open Chrome DevTools, toggle device toolbar
+    2. Test at 320px width (iPhone SE): Dashboard, Employees, Chat, Usage, Billing pages
+    3. Test at 768px width (iPad): same pages
+    4. Test at 1024px width (iPad landscape): same pages
+    5. Verify: no horizontal scrolling, no overlapping elements, readable text
+
+    **MOB-02 — Mobile navigation:**
+    1. At 320px width: verify bottom tab bar with 5 icons (Dashboard, Employees, Chat, Usage, More)
+    2. Tap each tab — correct page loads, active indicator shows
+    3. Tap "More" — bottom sheet slides up with Billing, API Keys, Users, etc.
+    4. Test with operator role: verify restricted items hidden in More sheet
+    5. At 768px+: verify sidebar appears, no tab bar
+
+    **MOB-03 — Mobile chat:**
+    1. At 320px: navigate to Chat
+    2. Verify conversation list shows full-width
+    3. Tap a conversation: verify full-screen chat with back arrow + agent name header
+    4. Send a message — verify it appears
+    5. Wait for AI response — verify streaming tokens appear word-by-word
+    6. Tap back arrow — verify return to conversation list
+    7. Start a new conversation — verify agent picker works on mobile
+
+    **MOB-04 — PWA install:**
+    1. Run with `npm run dev:pwa` (--experimental-https --webpack)
+    2. Open Chrome DevTools > Application > Manifest: verify manifest loads with correct name, icons
+    3. Application > Service Workers: verify SW registered
+    4. Run Lighthouse PWA audit: target score >= 90
+    5. If on Android Chrome: verify install prompt appears on second visit
+
+    **MOB-05 — Push notifications:**
+    1. Enable notifications when prompted
+    2. Open a chat conversation, send a message, get a response (verify WebSocket works)
+    3. Close the browser tab / switch away
+    4. Trigger another AI response (e.g., via a second browser window or API call)
+    5. Verify push notification appears on device
+    6. Tap notification — verify it opens the correct conversation
+
+    **MOB-06 — Touch interactions:**
+    1. At 320px, tap all buttons and links — verify immediate visual feedback (no hover-stuck states)
+    2. Verify no tooltips or dropdowns that require hover to trigger
+    3. Verify all tap targets are >= 44px minimum dimension
+
+    Resume signal: Type "approved" to complete Phase 8, or describe issues to address.
+  </action>
+  <verify>
+    <automated>cd /home/adelorenzo/repos/konstruct/packages/portal && npm run build</automated>
+  </verify>
+  <done>
+    Human confirms all six MOB requirements pass on mobile viewports. Lighthouse PWA audit score >= 90. No hover-stuck interactions on touch. Phase 8 complete.
+  </done>
+</task>
+
+</tasks>
+
+<verification>
+All MOB requirements verified by human testing on mobile viewports.
+</verification>
+
+<success_criteria>
+Human confirms all six MOB requirements pass on mobile viewports. Lighthouse PWA audit score >= 90.
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/08-mobile-pwa/08-04-SUMMARY.md`
+</output>