Add install_everything.sh, update README.md, WIKI.md

2026-03-13 16:03:04 +08:00
parent e72a3ab85c
commit 99f1b3e095
3 changed files with 506 additions and 3 deletions
--- a/WIKI.md
+++ b/WIKI.md
@@ -1,5 +1,63 @@
 # TCK RTU - Technical Documentation

+## Table of Contents
+
+- [Overview](#overview)
+- [System Architecture](#system-architecture)
+  - [Hardware Requirements](#hardware-requirements)
+  - [Software Architecture](#software-architecture)
+- [Components](#components)
+  - [Dashboard Components](#dashboard-components)
+  - [View Components](#view-components)
+  - [Data Flow](#data-flow)
+- [API Client](#api-client)
+  - [Endpoint](#endpoint)
+  - [Response Format](#response-format)
+  - [Mock Data](#mock-data)
+- [Display Modes](#display-modes)
+  - [Kiosk Mode (Port 8888)](#kiosk-mode-port-8888)
+  - [Remote Mode (Port 9090)](#remote-mode-port-9090)
+- [Navigation](#navigation)
+  - [Menu Structure](#menu-structure)
+  - [View Components List](#view-components-list)
+- [State Management](#state-management)
+  - [Zustand Store Structure](#zustand-store-structure)
+  - [Usage](#usage)
+- [Testing](#testing)
+  - [Test Infrastructure](#test-infrastructure)
+  - [Running Tests](#running-tests)
+  - [Test Structure](#test-structure)
+- [Performance](#performance)
+  - [Bundle Size Targets](#bundle-size-targets)
+  - [Optimizations](#optimizations)
+  - [Performance Tips](#performance-tips)
+- [Deployment](#deployment)
+  - [Build](#build)
+  - [Output](#output)
+  - [Production Server](#production-server)
+- [Start Script](#start-script)
+  - [Usage](#start-script-usage)
+  - [Options](#start-script-options)
+- [Installation Script](#installation-script)
+  - [Quick Install](#quick-install)
+  - [Web Server Setup](#web-server-setup)
+  - [Manual Install](#manual-install)
+- [UI Design Decisions](#ui-design-decisions)
+  - [Layout Principles](#layout-principles)
+  - [Touch Targets](#touch-targets)
+  - [Color Scheme](#color-scheme)
+- [User Flow](#user-flow)
+  - [Kiosk Mode Flow](#kiosk-mode-flow)
+  - [Navigation Buttons](#navigation-buttons)
+- [Future Phases](#future-phases)
+  - [Phase 2: Settings Framework](#phase-2-settings-framework)
+  - [Phase 3: Data Management & Network Stack](#phase-3-data-management--network-stack)
+- [Troubleshooting](#troubleshooting)
+  - [Common Issues](#common-issues)
+  - [Development Tools](#development-tools)
+
+---
+
 ## Overview

 TCKRTUIYO is a web-based interface for Base Station/Real-Time Unit (RTU) monitoring rainfall and related sensors. The system is designed to run on Raspberry Pi Zero 2 W with a 7" capacitive touchscreen display.
@@ -46,6 +104,33 @@ TCKRTUIYO is a web-based interface for Base Station/Real-Time Unit (RTU) monitor
 | BatteryStatus | `BatteryStatus.tsx` | Battery voltage with status indicator |
 | LoginIndicator | `LoginIndicator.tsx` | Login status display |

+### View Components
+
+| View | File | Description |
+|------|------|-------------|
+| Dashboard | `DashboardView.tsx` | Main rainfall monitoring display |
+| Graph | `GraphView.tsx` | Data visualization with charts |
+| Utility | `UtilityView.tsx` | Additional utility functions |
+| Calibration | `CalibrationView.tsx` | Sensor calibration interface |
+| FlashMemory | `FlashMemoryView.tsx` | Data storage management |
+| Setting | `SettingView.tsx` | Main settings hub |
+| Login | `LoginView.tsx` | Authentication interface |
+
+### Settings Sub-Views
+
+| Setting | File | Description |
+|---------|------|-------------|
+| Station Info | `StationInfoView.tsx` | Station ID, version info |
+| Date/Time | `DateTimeSettingView.tsx` | Date, time, timezone configuration |
+| Mobile | `MobileSettingView.tsx` | Mobile network (SIM) settings |
+| ADC | `ADCSettingView.tsx` | ADC calibration |
+| Rainfall | `RainfallSettingView.tsx` | Rainfall sensor settings |
+| EVAP | `EVAPSettingView.tsx` | Evaporation sensor settings |
+| GPRS | `GPRSSettingView.tsx` | GPRS configuration |
+| Level | `LevelSettingView.tsx` | Water level sensor settings |
+| Siren | `SirenSettingView.tsx` | Alarm/siren configuration |
+| Network | `NetworkSettingView.tsx` | WiFi/Ethernet settings |
+
 ### Data Flow

 1. **Sensor Data Collection**
@@ -108,12 +193,13 @@ When the API is unavailable, mock data is automatically generated with realistic

 ## Display Modes

-### Kiosk Mode (Port 8080)
+### Kiosk Mode (Port 8888)

 - Fixed resolution: 1024x600
 - Optimized for 7" touchscreen
 - Compact layouts with 44px+ touch targets
 - No scrollbars - navigation buttons instead
+- **Primary mode for local touchscreen display**

 ### Remote Mode (Port 9090)

@@ -121,6 +207,7 @@ When the API is unavailable, mock data is automatically generated with realistic
 - Full HD optimized
 - Expanded information display
 - Standard scrollbars
+- **For remote access via network**

 ## Navigation

@@ -146,6 +233,19 @@ When the API is unavailable, mock data is automatically generated with realistic
 └── LOGIN
 ```

+### View Components List
+
+All views are located in `sample_interface/src/app/components/views/`:
+
+- `DashboardView.tsx` - Main rainfall dashboard
+- `GraphView.tsx` - Data visualization with chart
+- `UtilityView.tsx` - Utility functions hub
+- `CalibrationView.tsx` - Sensor calibration
+- `FlashMemoryView.tsx` - File management
+- `SettingView.tsx` - Settings hub (side-by-side Display & System settings)
+- `LoginView.tsx` - Login interface
+- Settings sub-views (StationInfo, DateTime, Mobile, ADC, Rainfall, EVAP, GPRS, Level, Siren, Network)
+
 ## State Management

 ### Zustand Store Structure
@@ -267,6 +367,176 @@ python -m http.server 8080
 npx serve dist
 ```

+## Start Script
+
+The `start.sh` script provides an interactive menu for common development commands.
+
+### Usage
+
+```bash
+./start.sh [option]
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `1` or `dev` | Start dev server (port 5173) |
+| `2` or `dev:8888` | Start dev server on port 8888 (kiosk mode) |
+| `3` or `dev:9090` | Start dev server on port 9090 (remote mode) |
+| `4` or `test` | Run tests |
+| `5` or `test:watch` | Run tests in watch mode |
+| `6` or `build` | Build for production |
+| `7` or `preview` | Preview production (port 4173) |
+| `8` or `lint` | Run linter |
+| `9` or `clean` | Clean build artifacts |
+| `10` or `install` | Install dependencies |
+| `p` or `port` | Change default ports |
+| `0` or `exit` | Exit |
+
+**Note**: Port 8888 is recommended for kiosk mode (7" touchscreen), port 9090 for remote access.
+
+## Installation Script
+
+The `install_everything.sh` script automates the entire installation process including:
+- Installing system dependencies (curl, git, nginx)
+- Installing Node.js 20.x
+- Cloning the repository
+- Installing npm dependencies
+- Starting the application
+
+### Quick Install
+
+```bash
+# Option 1: Clone and run locally
+git clone https://github.com/your-repo/tck_rtu.git /opt/tck_rtu
+cd /opt/tck_rtu
+./install_everything.sh
+
+# Option 2: From web server (see below)
+curl -sL http://tckrtuiyo:3000/tck/tck_rtu/install_everything.sh | bash
+
+# Option 3: From GitHub raw
+curl -sL https://raw.githubusercontent.com/your-repo/main/install_everything.sh | bash
+```
+
+### Web Server Setup
+
+To serve the install script from a local web server for Option 2:
+
+```bash
+# Method 1: Using Python (simple)
+sudo mkdir -p /var/www/html/tck/tck_rtu
+sudo cp install_everything.sh /var/www/html/tck/tck_rtu/
+cd /var/www/html/tck/tck_rtu
+sudo python3 -m http.server 3000
+
+# Method 2: Using nginx
+sudo cp install_everything.sh /var/www/html/tck/tck_rtu/
+sudo systemctl start nginx
+
+# Access via:
+# http://<server-ip>:3000/tck/tck_rtu/install_everything.sh
+# or
+# http://tckrtuiyo:80/tck/tck_rtu/install_everything.sh
+```
+
+### Manual Install
+
+If you prefer to install manually:
+
+```bash
+# 1. Install system dependencies (as root)
+sudo apt-get update
+sudo apt-get install -y curl git nginx
+
+# 2. Install Node.js 20.x
+curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -
+sudo apt-get install -y nodejs
+
+# 3. Clone repository
+sudo mkdir -p /opt
+sudo git clone https://github.com/your-repo/tck_rtu.git /opt/tck_rtu
+
+# 4. Install dependencies
+cd /opt/tck_rtu/sample_interface
+sudo npm install
+
+# 5. Run
+cd /opt/tck_rtu
+sudo ./start.sh
+```
+
+## UI Design Decisions
+
+### Layout Principles
+
+1. **Vertical Stacking**: Information flows top-to-bottom
+2. **Controls at Bottom**: Interactive elements (buttons, inputs) placed at bottom for easy thumb access
+3. **Summary at Top**: Key metrics and visualizations at top
+4. **No Scrolling**: All content fits within 1024x600 viewport
+
+### Touch Targets
+
+- Minimum touch target: 44x44px
+- Spacing between targets: 8px minimum
+- Navigation buttons placed next to titles (not just in header)
+
+### Color Scheme
+
+- **Background**: Dark gray (#1a1a2e, #16213e)
+- **Cards**: Slightly lighter gray (#0f3460, #1f4068)
+- **Primary Accent**: Blue (#4d96ff, #3a86ff)
+- **Text**: White/light gray for contrast
+- **Status Colors**:
+  - Green: Good/normal
+  - Yellow/Orange: Warning
+  - Red: Critical/alert
+
+## User Flow
+
+### Kiosk Mode Flow
+
+1. **Boot**: System starts, Chromium launches in kiosk mode
+2. **Load**: App loads at http://localhost:8888
+3. **Dashboard**: Shows rainfall data, clock, battery, signal
+4. **Navigate**: Use side buttons to switch views
+5. **Interact**: Touch screen for settings/siren tests
+
+### Navigation Buttons
+
+- **Horizontal placement**: Next to view titles (not just in header)
+- **Clear labeling**: Icon + text for clarity
+- **Consistent position**: Same location across all views
+
+**Graph View Layout** (example):
+```
+┌─────────────────────────────────────┐
+│ [Icon] Graph View    [↑] [↓]       │  <- Header with nav buttons
+├─────────────────────────────────────┤
+│  Time Range | Data Pts | Avg Value │  <- Summary at top
+├─────────────────────────────────────┤
+│                                     │
+│      Data Visualization             │  <- Chart at bottom
+│                                     │
+└─────────────────────────────────────┘
+```
+
+**Settings View Layout** (example):
+```
+┌─────────────────────────────────────┐
+│ [Icon] Setting         [←] [→]     │
+├─────────────────────────────────────┤
+│  Display Settings │ System Settings│  <- Side-by-side
+├─────────────────────────────────────┤
+│  Date │ Time │ Timezone             │  <- Horizontal
+├─────────────────────────────────────┤
+│  Phone Number │ APN                 │  <- Horizontal (Mobile)
+├─────────────────────────────────────┤
+│  Enable EVAP │ Pan Coef │ Interval  │  <- Horizontal (EVAP)
+└─────────────────────────────────────┘
+```
+
 ## Future Phases

 ### Phase 2: Settings Framework
@@ -297,6 +567,10 @@ npx serve dist
   - Check backend is running
   - Verify CORS settings

+4. **Dev server wrong port**
+   - Use `--port` flag: `npm run dev -- --port 8888`
+   - Not `VITE_PORT=8888` (doesn't work with npm)
+
 ### Development Tools

 - React DevTools