From 3ab1b23c1fdc07ab88f9be667bad8242814589b5 Mon Sep 17 00:00:00 2001 From: admin Date: Fri, 13 Mar 2026 01:38:53 +0800 Subject: [PATCH] docs: create roadmap (3 phases) --- .planning/REQUIREMENTS.md | 31 ++++-- .planning/ROADMAP.md | 194 ++++++++++++++++++++++++++++++++++++++ .planning/STATE.md | 129 +++++++++++++++++++++++++ 3 files changed, 347 insertions(+), 7 deletions(-) create mode 100644 .planning/ROADMAP.md create mode 100644 .planning/STATE.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 1d8ca4ed6..8a9cfeed7 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -93,13 +93,30 @@ | REQ-ID | Phase | Status | |--------|-------|--------| -| DASH-01 — DASH-07 | TBD | Not planned | -| STAT-01 — STAT-03 | TBD | Not planned | -| SENS-01 — SENS-08 | TBD | Not planned | -| NETW-01 — NETW-06 | TBD | Not planned | -| DATA-01 — DATA-05 | TBD | Not planned | -| CALB-01 — CALB-04 | TBD | Not planned | -| UI-01 — UI-05 | TBD | Not planned | +| DASH-01 — DASH-07 | Phase 1 | Not started | +| UI-01 — UI-05 | Phase 1 | Not started | +| STAT-01 — STAT-03 | Phase 2 | Not started | +| SENS-01 — SENS-08 | Phase 2 | Not started | +| NETW-01 — NETW-06 | Phase 3 | Not started | +| DATA-01 — DATA-05 | Phase 3 | Not started | +| CALB-01 — CALB-04 | Phase 3 | Not started | + +### Phase Mapping Summary + +- **Phase 1: Foundation & Dashboard** (12 requirements) + - Dashboard: DASH-01, DASH-02, DASH-03, DASH-04, DASH-05, DASH-06, DASH-07 + - UI/UX: UI-01, UI-02, UI-03, UI-04, UI-05 + +- **Phase 2: Settings Framework & Core Configuration** (11 requirements) + - Station: STAT-01, STAT-02, STAT-03 + - Sensors: SENS-01, SENS-02, SENS-03, SENS-04, SENS-05, SENS-06, SENS-07, SENS-08 + +- **Phase 3: Data Management & Network Stack** (12 requirements) + - Network: NETW-01, NETW-02, NETW-03, NETW-04, NETW-05, NETW-06 + - Data Management: DATA-01, DATA-02, DATA-03, DATA-04, DATA-05 + - Calibration: CALB-01, CALB-02, CALB-03, CALB-04 + +**Coverage:** 35/35 v1 requirements mapped ✓ --- diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md new file mode 100644 index 000000000..88bb9f066 --- /dev/null +++ b/.planning/ROADMAP.md @@ -0,0 +1,194 @@ +# TCKRTUIYO - Project Roadmap + +**Project:** RTU Web Interface for Rainfall Monitoring +**Version:** v1.0 +**Created:** 2026-03-13 + +--- + +## Overview + +This roadmap delivers a modern web interface for Base Station/Real-Time Unit (RTU) rainfall monitoring. Built for Raspberry Pi Zero 2 W with 7" touchscreen display, supporting both local kiosk mode (1024x600) and remote Full HD access. + +**Core Value:** Real-time rainfall and sensor monitoring with local display and server data transmission. + +--- + +## Phases + +- [ ] **Phase 1: Foundation & Dashboard** - Modern dashboard with real-time sensor display and performance optimization +- [ ] **Phase 2: Settings Framework & Core Configuration** - Settings infrastructure, station config, and sensor calibration +- [ ] **Phase 3: Data Management & Network Stack** - CSV workflows, file management, and network protocols + +--- + +## Phase Details + +### Phase 1: Foundation & Dashboard + +**Goal:** Users can view real-time rainfall, voltage, and station status on a modern, performant dashboard optimized for 7" touchscreen display. + +**Depends on:** Nothing (first phase) + +**Requirements:** DASH-01, DASH-02, DASH-03, DASH-04, DASH-05, DASH-06, DASH-07, UI-01, UI-02, UI-03, UI-04, UI-05 + +**Success Criteria** (what must be TRUE for users): +1. User sees real-time rainfall data (Today, Hourly, MAR Acc, Yearly Acc) updating automatically +2. User sees solar and battery voltage with visual status indicators +3. User sees station ID, version info, current time/date, and communication status (ASU/dBm) +4. User sees login status indicator on dashboard +5. Dashboard loads in <2 seconds on Pi Zero 2 W (LCP <200KB JS bundle) +6. All touch targets are minimum 44px for finger-friendly interaction +7. Dashboard displays correctly in both 1024x600 (kiosk) and Full HD (remote) modes +8. Navigation menu provides access to Settings, Calibration, and Flash Memory sections + +**Plans:** TBD + +--- + +### Phase 2: Settings Framework & Core Configuration + +**Goal:** Users can configure station information, sensors, and calibration parameters through a unified settings interface. + +**Depends on:** Phase 1 (Foundation & Dashboard) + +**Requirements:** STAT-01, STAT-02, STAT-03, SENS-01, SENS-02, SENS-03, SENS-04, SENS-05, SENS-06, SENS-07, SENS-08 + +**Success Criteria** (what must be TRUE for users): +1. User can view and edit Station Info (ID, location details) +2. User can manually set Date and Time through settings interface +3. User can configure Mobile/GPRS settings including Master/SubMaster and Engineer phone numbers +4. User can configure ADC channels with type selection (4-20mA or 0-10vDC), Datum offset, and Range +5. User can configure Rainfall sensor ID and set Danger/Warning/Start thresholds with time windows +6. User can configure Water Level sensor IDs and thresholds +7. User can configure EVAP settings including ID, reset times, and max/min levels +8. User can configure SIREN settings +9. Configuration persists across browser sessions (localStorage + backend sync) +10. Settings interface uses touch-optimized forms with validation feedback + +**Plans:** TBD + +--- + +### Phase 3: Data Management & Network Stack + +**Goal:** Users can manage data files, export CSV data, and configure network protocols for server communication. + +**Depends on:** Phase 2 (Settings Framework & Core Configuration) + +**Requirements:** NETW-01, NETW-02, NETW-03, NETW-04, NETW-05, NETW-06, DATA-01, DATA-02, DATA-03, DATA-04, DATA-05, CALB-01, CALB-02, CALB-03, CALB-04 + +**Success Criteria** (what must be TRUE for users): +1. User can view Flash Memory file list with metadata (filename, size, date) +2. User can view CSV file contents without freezing the interface +3. User can delete CSV files from Flash Memory with confirmation +4. User can export data as CSV with progress indication +5. User can configure Tieda data transmission settings +6. User can configure Local IP Address, Subnet Mask, Gateway, and DNS +7. User can view MAC address in Network settings +8. User can configure Transfer Protocol (FTP/SCP/SFTP/WEBDAV) for data push +9. User can configure Server IP, Port, and File Directory for remote data transmission +10. User can configure Tide Hour settings +11. User can view/set Latitude and Longitude (manual input or GPS) +12. User can view live ADC readings for all channels in Calibration view +13. User can view calculated sensor values based on Datum/Range settings +14. User can reset rainfall tip counters +15. User can reset calibration readings +16. CSV operations run in background (Web Workers) without blocking UI +17. Network status indicators show connectivity state and last sync time + +**Plans:** TBD + +--- + +## Progress Table + +| Phase | Plans Complete | Status | Completed | +|-------|----------------|--------|-----------| +| 1. Foundation & Dashboard | 0/4 | Not started | - | +| 2. Settings Framework & Core Configuration | 0/3 | Not started | - | +| 3. Data Management & Network Stack | 0/3 | Not started | - | + +--- + +## Requirements Coverage + +### Phase 1: Foundation & Dashboard (12 requirements) +- DASH-01: Display real-time rainfall (Today, Hourly, MAR Acc, Yearly Acc) in mm +- DASH-02: Display solar voltage reading +- DASH-03: Display battery voltage with status indicator (HIGH/LOW) +- DASH-04: Display station ID and version info +- DASH-05: Display real-time clock (HH:MM:SS) and date (YYYY-MM-DD) +- DASH-06: Display communication status (ASU/dBm/percentage) +- DASH-07: Display login status indicator +- UI-01: Modern, compact UI design optimized for 1024x600 display +- UI-02: Touch-friendly interface (44px+ touch targets) +- UI-03: Responsive layout for Full HD remote access +- UI-04: Fast performance on Pi Zero 2 W (< 200KB JS bundle) +- UI-05: Navigation menu with utility/settings, calibration, flash memory + +### Phase 2: Settings Framework & Core Configuration (11 requirements) +- STAT-01: View/edit Station Info +- STAT-02: Set Date and Time manually +- STAT-03: Configure Mobile/GPRS settings (Master/SubMaster numbers, Engineer numbers) +- SENS-01: Configure ADC channels (4-20mA, 0-10vDC types) +- SENS-02: Set Datum offset for each ADC channel +- SENS-03: Set Range for each ADC channel +- SENS-04: Configure Rainfall sensor ID and thresholds +- SENS-05: Set Danger/Warning/Start rainfall thresholds with time windows +- SENS-06: Configure Water Level sensor IDs and thresholds +- SENS-07: Configure EVAP settings (ID, reset times, max/min levels) +- SENS-08: Configure SIREN settings + +### Phase 3: Data Management & Network Stack (12 requirements) +- NETW-01: Configure Local IP Address, Subnet Mask, Gateway, DNS +- NETW-02: Display MAC address +- NETW-03: Configure Transfer Protocol (FTP/SCP/SFTP/WEBDAV) +- NETW-04: Configure Server IP, Port, File Directory +- NETW-05: Configure Tide Hour settings +- NETW-06: Display/Set Latitude and Longitude (manual or from GPS) +- DATA-01: View Flash Memory file list +- DATA-02: View CSV file contents +- DATA-03: Delete CSV files from Flash Memory +- DATA-04: Export data via CSV +- DATA-05: Configure Tieda data transmission +- CALB-01: View live ADC readings for all channels +- CALB-02: View calculated sensor values based on Datum/Range +- CALB-03: Reset rainfall tip counters +- CALB-04: Reset calibration readings + +**Total:** 35/35 v1 requirements mapped ✓ + +--- + +## Phase Ordering Rationale + +1. **Phase 1 (Dashboard First):** The dashboard is the core value proposition and has the strictest performance requirements. Validating performance on Pi Zero 2 W hardware early prevents costly architectural changes later. + +2. **Phase 2 (Settings Framework):** Settings infrastructure is required before implementing data management. Configuration persistence and bounded memory patterns must be established before handling file operations. + +3. **Phase 3 (Data & Network Last):** CSV workflows and network protocols add complexity (Web Workers, file operations, protocol handling) that can be deferred until core functionality is stable. + +--- + +## Key Decisions + +| Decision | Rationale | Impact | +|----------|-----------|--------| +| 3-phase coarse structure | Matches coarse granularity config, natural delivery boundaries | Phases align with major functional areas | +| Dashboard first | Core user value + performance validation on target hardware | Early risk mitigation for Pi Zero constraints | +| Settings before data management | Configuration persistence required for data export | Logical dependency chain | +| Network stack in Phase 3 | FTP/SCP/SFTP/WebDAV protocols are complex, deferrable | Reduces initial complexity | + +--- + +## Notes + +- **Performance Budget:** <200KB initial JS gzipped for initial load +- **Touch Target Minimum:** 44px (per Material Design guidelines) +- **Bundle Size Target:** <170KB for dashboard to leave buffer +- **Research Flags:** Phase 3 may need additional research on CSV libraries compatible with Web Workers + +--- + +*Last updated: 2026-03-13* diff --git a/.planning/STATE.md b/.planning/STATE.md new file mode 100644 index 000000000..9ef06b33b --- /dev/null +++ b/.planning/STATE.md @@ -0,0 +1,129 @@ +# Project State + +**Project:** TCKRTUIYO - RTU Web Interface +**Created:** 2026-03-13 +**Status:** Roadmap Created - Awaiting Phase 1 Planning + +--- + +## Project Reference + +**Core Value:** Real-time rainfall and sensor monitoring with local display and server data transmission. + +**Target Hardware:** Raspberry Pi Zero 2 W / 3B + 7" capacitive touchscreen (1024x600) + +**Critical Constraints:** +- Performance: Must run smoothly on Pi Zero 2 W (1GHz quad-core, 512MB RAM) +- Bundle size: <200KB initial JS gzipped +- Display: Fixed 1024x600 for kiosk, responsive for Full HD remote +- Browser: Chromium Kiosk Mode only + +--- + +## Current Position + +``` +[====================] 0% - ROADMAP CREATED +Phase: 0/3 +Plan: 0/0 +Status: Ready to begin Phase 1 +``` + +### Phase Status + +| Phase | Status | Progress | Started | Target Complete | +|-------|--------|----------|---------|-----------------| +| 1. Foundation & Dashboard | Not started | 0% | - | - | +| 2. Settings Framework & Core Configuration | Blocked | 0% | - | - | +| 3. Data Management & Network Stack | Blocked | 0% | - | - | + +--- + +## Current Focus + +**Next Action:** Plan Phase 1 - Foundation & Dashboard + +**Phase 1 Goal:** Users can view real-time rainfall, voltage, and station status on a modern, performant dashboard optimized for 7" touchscreen display. + +**Key Deliverables:** +- Modern dashboard with real-time sensor display +- Performance optimization for Pi Zero 2 W (<200KB bundle) +- Touch-optimized UI (44px+ targets) +- Dual-mode display (1024x600 kiosk + Full HD remote) +- Navigation to Settings, Calibration, and Flash Memory + +--- + +## Performance Metrics + +**Bundle Size Budget:** +- Current: N/A (not built yet) +- Target: <200KB gzipped initial JS +- Limit: 170KB for dashboard to leave buffer + +**Performance Targets:** +- LCP: <2 seconds on Pi Zero 2 W +- Touch targets: Minimum 44px +- Data refresh: 1-5 second intervals with debouncing + +**Quality Gates:** +- [ ] Dashboard loads on actual Pi Zero 2 W hardware +- [ ] Memory bounded (no unbounded growth over 24h) +- [ ] Touch optimized (tested with finger on 7" display) +- [ ] Performance budget met (<170KB initial JS) + +--- + +## Accumulated Context + +### Decisions Made + +| Date | Decision | Rationale | +|------|----------|-----------| +| 2026-03-13 | 3-phase coarse roadmap | Matches granularity config, natural boundaries | +| 2026-03-13 | Dashboard-first approach | Core value + early performance validation | +| 2026-03-13 | React 19 + Vite 8 + Tailwind 4 | Research-validated stack for embedded kiosk | + +### Open Questions + +- Specific CSV library selection for Phase 3 (needs Web Worker compatibility) +- Network protocol prioritization (FTP/SCP/SFTP/WEBDAV - all needed?) +- Hardware API endpoint contracts (coordinate with Python backend) + +### Technical Debt + +None yet - project initialization complete. + +### Known Blockers + +None - ready to begin Phase 1 planning. + +--- + +## Session Continuity + +### Last Session +- **Action:** Roadmap creation +- **Outcome:** 3-phase roadmap created with 35/35 requirements mapped +- **Artifacts:** ROADMAP.md, STATE.md, REQUIREMENTS.md updated + +### Next Expected Session +- **Action:** `/gsd-plan-phase 1` +- **Goal:** Create executable plans for Phase 1: Foundation & Dashboard + +--- + +## Files Reference + +| File | Purpose | +|------|---------| +| `.planning/PROJECT.md` | Project context, core value, constraints | +| `.planning/REQUIREMENTS.md` | v1/v2 requirements with traceability | +| `.planning/ROADMAP.md` | Phase structure and success criteria | +| `.planning/STATE.md` | This file - project state and progress | +| `.planning/research/SUMMARY.md` | Research findings and recommendations | +| `.planning/config.json` | Workflow configuration | + +--- + +*Last updated: 2026-03-13 - Roadmap created, ready to begin Phase 1*