docs(01-foundation-dashboard): create phase 1 plans

2026-03-13 06:23:52 +08:00
parent b85d81c2e8
commit feaed41454
7 changed files with 1571 additions and 0 deletions
--- a/.planning/phases/01-foundation-dashboard/01-RESEARCH.md
+++ b/.planning/phases/01-foundation-dashboard/01-RESEARCH.md
@@ -0,0 +1,176 @@
+# Phase 1: Foundation & Dashboard - Research
+
+**Phase:** 1  
+**Researched:** 2026-03-13  
+**Confidence:** HIGH  
+
+---
+
+## Research Question
+
+What do we need to know to PLAN Phase 1 well? Phase 1 delivers a modern, performant dashboard for rainfall monitoring on Raspberry Pi Zero 2 W hardware.
+
+---
+
+## Key Findings
+
+### Dashboard Requirements (from CONTEXT.md + ROADMAP)
+
+**Must Display:**
+1. Real-time rainfall data (Today, Hourly, MAR Acc, Yearly Acc) — DASH-01
+2. Solar voltage reading — DASH-02  
+3. Battery voltage with HIGH/LOW status indicator — DASH-03
+4. Station ID and version info — DASH-04
+5. Real-time clock (HH:MM:SS) and date (YYYY-MM-DD) — DASH-05
+6. Communication status (ASU/dBm/percentage) — DASH-06
+7. Login status indicator — DASH-07
+
+**UI Requirements:**
+- Modern, compact design optimized for 1024x600 — UI-01
+- Touch-friendly (44px+ touch targets) — UI-02
+- Responsive layout for Full HD remote access — UI-03
+- <200KB JS bundle for Pi Zero 2 W — UI-04
+- Navigation menu to Settings, Calibration, Flash Memory — UI-05
+
+### Implementation Decisions (Locked)
+
+**Layout:**
+- 3-panel layout: Sidebar | Header + Content
+- Header contains: Logo, Time, Date, Station ID, Comm Status, Version, Login Status, Solar Voltage, Battery Voltage
+- Rainfall cards in grid with color-coding
+
+**Dual-Mode Display:**
+- Port 8080 = Kiosk mode (1024x600)
+- Port 9090 = Full HD remote mode
+- Detection via `window.location.port`
+
+**State Management:**
+- Zustand (~1.1KB) for sensor data
+- localStorage + backend sync for settings persistence
+- Offline-first architecture
+
+**Real-time Data:**
+- Polling-based (default 5s, user adjustable)
+- API client with mock fallback for demo/offline
+
+### Technology Stack (from existing research)
+
+**Confirmed Stack:**
+- React 19.2.4 — 15-20% smaller than v18, required for shadcn/ui
+- Vite 8.0.0 — Fast HMR, superior tree-shaking
+- Tailwind CSS 4.2.0 — Zero-runtime CSS
+- React Router 7.x — Type-safe routing
+- Zustand 5.0.11 — ~1.1KB state management
+- shadcn/ui — Tree-shakeable components
+
+**Bundle Budget:** <170KB initial JS (200KB limit with buffer)
+
+### Critical Pitfalls to Avoid
+
+1. **Performance constraints** — Pi Zero 2 W has 1GHz quad-core, 512MB RAM
+2. **Layout thrashing** — Use React.memo, debounce updates
+3. **Unbounded data** — Circular buffers for historical data
+4. **Kiosk anti-patterns** — 44px+ touch targets, no hover-only states
+5. **Memory leaks** — Proper useEffect cleanup
+6. **Blocking operations** — Keep CSV/network for Phase 3
+
+### File Structure (from existing codebase)
+
+**Routes:**
+- `/` — Dashboard (RainfallView)
+- `/utility/*` — Settings
+- `/calibration` — Calibration
+- `/flash-memory` — Flash Memory
+
+**Components to Create/Modify:**
+- `App.tsx` — Add mode detection
+- `Header.tsx` — Modernize with all status info
+- `RainfallView.tsx` — Main dashboard view
+- `stores/sensorStore.ts` — New Zustand store
+- `api/client.ts` — API client with mock fallback
+
+### Dependencies to Add
+
+- `zustand` — State management
+
+---
+
+## Validation Architecture
+
+### Testable Behaviors
+
+1. **Dashboard displays all required data fields**
+   - Rainfall metrics (Today, Hourly, MAR, Yearly)
+   - Voltage readings (Solar, Battery with status)
+   - Station info (ID, Version)
+   - Time/Date display
+   - Communication status
+   - Login indicator
+
+2. **Touch targets meet minimum size**
+   - All interactive elements ≥44px
+   - Preferably 56px for primary actions
+
+3. **Dual-mode display works**
+   - Port 8080 renders kiosk layout
+   - Port 9090 renders expanded layout
+
+4. **Performance budget met**
+   - Initial JS <170KB gzipped
+   - LCP <2s on Pi Zero 2 W
+
+5. **Data updates in real-time**
+   - Polling interval configurable
+   - Updates visible without refresh
+
+6. **Navigation accessible**
+   - Sidebar shows Settings, Calibration, Flash Memory links
+   - Touch-friendly navigation
+
+### Observable Outputs
+
+| Artifact | Location | Verification |
+|----------|----------|--------------|
+| Dashboard component | `src/app/components/views/RainfallView.tsx` | Renders all 7 data fields |
+| Header component | `src/app/components/Header.tsx` | Shows status indicators |
+| Sensor store | `src/app/stores/sensorStore.ts` | Zustand store with mock data |
+| API client | `src/app/api/client.ts` | Fetch with fallback |
+| Mode detection | `src/app/App.tsx` | Port-based routing |
+| Bundle size | Build output | <170KB initial JS |
+
+### Key Connections
+
+- Sensor store → Dashboard view (data flow)
+- API client → Sensor store (update trigger)
+- Mode detection → Layout components (responsive behavior)
+- Header → Sensor store (status indicators)
+
+---
+
+## Standard Stack Recommendations
+
+### What to Use
+- React 19 + Vite 8 + Tailwind 4 (established)
+- Zustand for state (research-validated)
+- React Router 7 for navigation
+- shadcn/ui Card, Badge, Separator components
+- Lucide React for icons
+
+### What NOT to Use  
+- Redux Toolkit (too heavy)
+- TanStack Query (overkill for polling)
+- Material UI (large CSS-in-JS)
+- Real-time libraries (WebSocket/SSE not needed for 5s polling)
+
+---
+
+## Gaps Requiring Decisions
+
+1. **API endpoint contracts** — Coordinate with Python backend team for exact data format
+2. **Color scheme for status indicators** — Use existing TCK brand colors?
+3. **Historical chart implementation** — Recharts is already in dependencies
+4. **Polling interval bounds** — Min/max acceptable values?
+
+---
+
+*Research synthesis for Phase 1 planning. Based on project CONTEXT.md, ROADMAP.md, and existing codebase research.*