feat(quick-2): initialize v2 project from sample_interface

- Copy React app structure from sample_interface/src/ - Copy package.json, vite.config.ts, postcss.config.mjs - Copy guidelines/ design system
2026-03-12 12:29:56 +08:00
parent 65e8907307
commit 6a74db1e5c
79 changed files with 7422 additions and 0 deletions
--- a/v2/guidelines/Guidelines.md
+++ b/v2/guidelines/Guidelines.md
@@ -0,0 +1,458 @@
+# Data Station Dashboard Design Guidelines
+
+## Overview
+This dashboard is designed for 7-inch capacitive touchscreen displays used in industrial/environmental monitoring stations. The interface prioritizes touch-friendly interactions, clear information hierarchy, and robust functionality for field use.
+
+---
+
+## Design Language
+
+### Color Palette
+
+**Background Colors:**
+- Primary Background: `bg-gray-900` - Main content areas
+- Secondary Background: `bg-gray-950` - Sidebar, header, elevated surfaces
+- Tertiary Background: `bg-gray-800` - Cards, input fields, nested elements
+
+**Accent Colors:**
+- Primary Action: `bg-blue-600`, `hover:bg-blue-700` - Buttons, active states
+- Success/Positive: `text-green-400` - Online status, calibrated sensors, positive values
+- Warning: `text-yellow-400` - Pending states, warnings
+- Error/Critical: `text-red-400` - Offline status, errors, delete actions
+- Info: `text-blue-400` - Icons, informational highlights
+- Data Values: `text-cyan-400`, `text-purple-400` - Different data categories
+
+**Text Colors:**
+- Primary Text: `text-white` - Headings, labels
+- Secondary Text: `text-gray-300` - Body text, menu items
+- Tertiary Text: `text-gray-400` - Supporting information, metadata
+- Disabled Text: `text-gray-500` - Disabled states
+
+**Border Colors:**
+- Default Borders: `border-gray-700` - Cards, inputs, dividers
+
+### Typography
+
+**Font Sizes:**
+- Page Headers: `text-2xl` (h1)
+- Card Titles: `text-sm` to `text-base`
+- Body Text: `text-sm`
+- Metadata/Labels: `text-xs`
+- Tiny Text: `text-[10px]` (for dense information)
+- Monospace: Use `font-mono` for time, data values, file contents
+
+**Font Weights:**
+- Bold: `font-bold` - Page headers, important labels
+- Semibold: `font-semibold` - Card titles, emphasized values
+- Normal: Default weight for body text
+
+### Spacing
+
+**Component Spacing:**
+- Between major sections: `space-y-4`
+- Within cards: `space-y-3` or `space-y-4`
+- Compact spacing: `space-y-2`
+- Card padding: `p-3` or `p-4`
+- Grid gaps: `gap-3` or `gap-4`
+
+**Touch Targets:**
+- Minimum button height: `h-14` (56px) for primary touch actions
+- Standard button size: `size-lg` 
+- Navigation buttons: `h-14 w-14` (56x56px minimum)
+- List items: `p-2` to `p-3` for adequate touch area
+
+---
+
+## Navigation
+
+### Sidebar Navigation
+
+**Structure:**
+- Collapsible sidebar with icon-only mode
+- Width: `w-64` (expanded), `w-16` (collapsed)
+- Always visible on left side
+- Dark background (`bg-gray-950`)
+
+**Menu Hierarchy:**
+- Primary menu items: Icon + Label
+- Expandable items: Show chevron indicator
+- Sub-menu items: Indented with `pl-11`
+- Active state: `bg-blue-600 text-white`
+- Hover state: `hover:bg-gray-800 hover:text-white`
+
+**Menu Items:**
+1. HOME - Rainfall dashboard (default view)
+2. GRAPH - Data visualization
+3. UTILITY - Expandable with 10 sub-items
+4. CALIBRATION - Sensor calibration
+5. FLASH MEMORY - File manager
+6. SETTING - System settings
+7. LOGIN - Authentication
+
+### Page Navigation
+
+**No Traditional Scrollbars:**
+- All scrollbars are hidden for touchscreen usability
+- Use permanent Up/Down buttons in top-right corner
+- Buttons: 56x56px, `bg-blue-600`, positioned `fixed top-20 right-4`
+- Smooth scroll behavior with 300px increments
+
+**Routing:**
+- Use React Router for multi-page navigation
+- Route structure: `/` (home), `/graph`, `/utility/[setting]`, etc.
+- URL updates on navigation for state management
+
+---
+
+## UI Elements
+
+### Buttons
+
+**Primary Button:**
+- Style: `bg-blue-600 hover:bg-blue-700 text-white`
+- Use for: Main actions, saving, applying settings
+- Size: Default or `size-lg` for touch
+
+**Secondary Button (Outline):**
+- Style: `variant="outline" border-gray-700 text-gray-300 hover:bg-gray-800`
+- Use for: Alternative actions, cancel, secondary functions
+
+**Destructive Button:**
+- Style: `variant="outline" border-red-700 text-red-400 hover:bg-red-950`
+- Use for: Delete, reset, dangerous actions
+
+**Icon Buttons:**
+- Size: Minimum 44x44px for touch
+- Include text labels when space allows
+- Use Lucide React icons consistently
+
+### Cards
+
+**Standard Card:**
+```tsx
+<Card className="bg-gray-900 border-gray-700">
+  <CardHeader>
+    <CardTitle className="text-white">Title</CardTitle>
+  </CardHeader>
+  <CardContent>
+    {/* Content */}
+  </CardContent>
+</Card>
+```
+
+**Data Display Card:**
+- Use color-coded backgrounds for data categories
+- Format: Value (large) + Unit (small)
+- Example: `text-4xl font-bold text-blue-400` for values
+
+### Form Elements
+
+**Input Fields:**
+- Style: `bg-gray-800 border-gray-700 text-white`
+- Labels: `text-gray-300` above inputs
+- Grid layout for multiple fields: `grid grid-cols-2 gap-4`
+
+**Switches:**
+- Use for enable/disable settings
+- Layout: Label on left, switch on right
+- Container: `flex items-center justify-between p-3 bg-gray-800 rounded`
+
+**Dropdowns:**
+- Style: `bg-gray-800 border border-gray-700 rounded text-white`
+- Use native `<select>` for simplicity on touchscreens
+
+### Status Indicators
+
+**Icon + Text Pattern:**
+- Wifi status: `<Wifi className="w-3 h-3 text-green-500" />` + status text
+- Battery: `<Battery className="w-3 h-3 text-green-500" />` + voltage
+- Solar: `<Sun className="w-3 h-3 text-yellow-500" />` + voltage
+
+**Status Colors:**
+- Online/Active/Good: Green (`text-green-400/500`)
+- Pending/Warning: Yellow (`text-yellow-400/500`)
+- Offline/Error: Red (`text-red-400/500`)
+- Neutral/Info: Blue (`text-blue-400`)
+
+**Dot Indicators:**
+- Use `w-2 h-2 rounded-full` for compact status
+- Paired with text labels
+
+---
+
+## Panels
+
+### Header Panel
+
+**Layout:**
+- Fixed height, spans full width
+- Background: `bg-gray-950 border-b border-gray-700`
+- Padding: `px-4 py-2`
+- Flexbox: `flex items-center gap-4`
+
+**Content (Left to Right):**
+1. Logo (8x8 icon + optional text)
+2. Spacer (`flex-1`)
+3. Real-time clock (HH:MM:SS format, `font-mono`)
+4. Date (YYYY-MM-DD format, `font-mono`)
+5. Station ID
+6. Communication Status (icon + text)
+7. Version number
+8. Login status (dot + text)
+9. Solar voltage (icon + value)
+10. Battery voltage (icon + value)
+
+**Responsive Behavior:**
+- Items wrap with `flex-wrap` on smaller displays
+- Hide optional labels when space is tight
+- Maintain minimum readability
+
+### Details Panel
+
+**Container:**
+- ID: `details-panel` (for scroll control)
+- Style: `h-full overflow-y-auto bg-gray-800 p-4 scroll-smooth`
+- No visible scrollbar (hidden via CSS)
+
+**Content Structure:**
+- Page header with icon + title at top
+- Main content in cards
+- Consistent `space-y-4` between sections
+
+### Sidebar Panel
+
+**Structure:**
+- Fixed width, full height
+- Collapsible toggle in header
+- Scrollable menu area
+- Z-index layering for overlays
+
+---
+
+## Component Naming Conventions
+
+### Files and Folders
+
+**Views/Pages:**
+- Location: `/src/app/components/views/`
+- Naming: `[Feature]View.tsx` (e.g., `RainfallView.tsx`, `SettingView.tsx`)
+- Export: Named export matching filename
+
+**Layout Components:**
+- Location: `/src/app/components/`
+- Naming: `[Purpose].tsx` (e.g., `Header.tsx`, `Sidebar.tsx`, `DashboardLayout.tsx`)
+
+**Routes:**
+- Location: `/src/app/routes.ts`
+- Path naming: Lowercase with hyphens (e.g., `/utility/station-info`)
+
+### Variables and Constants
+
+**State Variables:**
+- camelCase: `sidebarCollapsed`, `selectedFile`, `isOnline`
+- Boolean prefix: `is`, `has`, `should`
+
+**Constants:**
+- camelCase for objects/arrays: `menuItems`, `mockFiles`, `rainfallData`
+- UPPERCASE for true constants: `SCROLL_AMOUNT`
+
+**Props:**
+- camelCase: `collapsed`, `onToggle`, `selectedFile`
+- Event handlers: `on[Action]` prefix
+
+---
+
+## Data Display Patterns
+
+### Rainfall Card View
+
+**Layout:**
+- Grid: `grid grid-cols-2 gap-4`
+- Four cards: Today, Hourly, MAR Acc, Yearly Acc
+- Each card: Label (top), Value (large center), Unit (small)
+
+**Color Coding:**
+- Today: Blue (`text-blue-400`, `bg-blue-500/20`)
+- Hourly: Cyan (`text-cyan-400`, `bg-cyan-500/20`)
+- MAR Acc: Green (`text-green-400`, `bg-green-500/20`)
+- Yearly Acc: Purple (`text-purple-400`, `bg-purple-500/20`)
+
+### List Views
+
+**Recent Data:**
+- Container: `space-y-2`
+- Item: `flex justify-between items-center p-2 bg-gray-800 rounded`
+- Timestamp on left (`text-gray-400`)
+- Value on right (`text-blue-400 font-semibold`)
+- Hover: `hover:bg-gray-750 transition-colors`
+
+### File Manager (Flash Memory)
+
+**Two-Column Layout:**
+- Left: 30% width, file list
+- Right: 70% width, file content
+- Grid: `grid grid-cols-[30%_70%] gap-4`
+
+**File List:**
+- Clickable items with selection state
+- Selected: `bg-blue-600 text-white`
+- Unselected: `bg-gray-800 text-gray-300`
+- File icon + name + metadata (size, date)
+
+**File Content:**
+- Monospace font for code/logs
+- Action buttons in header (Download, Delete)
+- Metadata footer
+
+### Settings Views
+
+**Form Pattern:**
+- Card-based groupings
+- Switch + Label rows for toggles
+- Input fields in grids for related values
+- Action buttons at bottom (full width or flex)
+
+---
+
+## Icon Usage
+
+**Icon Library:**
+- Use Lucide React exclusively
+- Size: `w-5 h-5` for menu items, `w-6 h-6` for page headers
+- Color: Match parent text color or use accent colors
+
+**Common Icons:**
+- Home: `<Home />`
+- Graph: `<BarChart3 />`
+- Settings: `<Settings />`
+- Utility: `<Wrench />`
+- Calibration: `<Gauge />`
+- Flash Memory: `<HardDrive />`
+- Login: `<LogIn />`
+- Info: `<Info />`
+- Time: `<Clock />`
+- Network: `<Network />`
+- Sensors: `<Activity />`, `<CloudRain />`, `<Wind />`
+- Actions: `<Download />`, `<Trash2 />`, `<Check />`
+- Navigation: `<ChevronUp />`, `<ChevronDown />`, `<ChevronRight />`
+
+---
+
+## Touchscreen Interaction Guidelines
+
+### Touch Targets
+- Minimum size: 44x44px (preferably 56x56px for critical actions)
+- Adequate spacing between adjacent targets
+- Visual feedback on touch (hover states still apply)
+
+### Gestures
+- Primary interaction: Tap/Click
+- Scrolling: Via Up/Down buttons (no swipe scrolling reliance)
+- No hover-dependent functionality
+- No right-click menus
+
+### Visual Feedback
+- Active states: Background color change
+- Loading states: Consider adding when needed
+- Transitions: `transition-colors` for smooth state changes
+- Button press: Visual depression or color shift
+
+---
+
+## Responsive Behavior
+
+**Target Screen Size:**
+- Primary: 7-inch touchscreen (approximately 800x480 to 1024x600)
+- Orientation: Landscape preferred
+
+**Adaptation Rules:**
+- Header items wrap when needed
+- Grid layouts adjust column count
+- Text truncates with ellipsis when necessary
+- Navigation remains accessible (sidebar stays visible)
+
+**Text Wrapping:**
+- Truncate with `truncate` class where space is limited
+- Allow wrap with `flex-wrap` for multi-item containers
+
+---
+
+## Performance Considerations
+
+**Optimization:**
+- Mock data for demonstrations
+- Real-time updates at reasonable intervals (1 second for clock)
+- Smooth scroll animations (`scroll-smooth`)
+- Efficient re-renders (use React best practices)
+
+**Data Updates:**
+- Clock: Update every 1000ms
+- Sensor data: Typical intervals 5-60 seconds
+- File lists: Update on demand
+
+---
+
+## Accessibility Notes
+
+**While optimized for touchscreen:**
+- Maintain keyboard navigation where possible
+- Use semantic HTML elements
+- Provide descriptive labels
+- Color is not the only indicator (use icons + text)
+- Sufficient contrast ratios for readability
+
+---
+
+## Technical Specifications
+
+**Framework:**
+- React 18.3.1
+- React Router 7.13.0 (Data mode)
+- Tailwind CSS 4.1.12
+
+**Component Library:**
+- Radix UI components (via shadcn/ui pattern)
+- Lucide React for icons
+
+**Styling:**
+- Tailwind utility classes
+- Minimal custom CSS (only for scrollbar hiding)
+- Dark theme by default
+
+**File Structure:**
+```
+/src/app/
+-- App.tsx              (Entry point with RouterProvider)
+-- routes.ts            (Route configuration)
+-- components/
+¦   +-- DashboardLayout.tsx
+¦   +-- Header.tsx
+¦   +-- Sidebar.tsx
+¦   +-- NavigationButtons.tsx
+¦   +-- views/           (All page views)
+¦   +-- ui/              (Reusable UI components)
+-- styles/
+    +-- theme.css        (Design tokens, custom CSS)
+    +-- tailwind.css     (Tailwind imports)
+    +-- fonts.css        (Font imports)
+```
+
+---
+
+## Future Enhancement Guidelines
+
+**When adding new features:**
+1. Follow existing naming conventions
+2. Maintain consistent color palette
+3. Ensure touch-friendly sizing
+4. Add route to `routes.ts`
+5. Add menu item to `Sidebar.tsx` if applicable
+6. Use existing UI component patterns
+7. Test on target screen size
+8. Consider real-time data update needs
+
+**Common Additions:**
+- New utility settings: Follow existing setting view patterns
+- New data displays: Use card-based layouts with color coding
+- New navigation items: Add to `menuItems` array with icon
+- New status indicators: Use icon + text + color pattern