Add codebase mapping documents

2026-03-13 01:08:16 +08:00
commit afe1603bbe
7 changed files with 1349 additions and 0 deletions
--- a/.planning/codebase/CONCERNS.md
+++ b/.planning/codebase/CONCERNS.md
@@ -0,0 +1,208 @@
+# Codebase Concerns
+
+**Analysis Date:** 2026-03-13
+
+## Tech Debt
+
+**Mock Data Throughout Application:**
+- Issue: All views contain hardcoded mock data instead of real API integrations
+- Files: 
+  - `src/app/components/views/FlashMemoryView.tsx` (lines 6-25)
+  - `src/app/components/views/RainfallView.tsx` (lines 5-10, 43-49)
+  - `src/app/components/views/ADCSettingView.tsx` (lines 8-13)
+  - `src/app/components/views/CalibrationView.tsx` (lines 6-11)
+  - `src/app/components/views/StationInfoView.tsx` (lines 5-14)
+  - `src/app/components/views/Header.tsx` (lines 56, 77, 91, 97)
+- Impact: Application is not functional for production use; requires complete rewrite of data layer
+- Fix approach: Implement API client layer, create custom hooks for data fetching (useApi, useSensorData), replace all mock constants with API calls
+
+**Missing API Integration Layer:**
+- Issue: No HTTP client configured, no API service layer exists
+- Files: All view files in `src/app/components/views/`
+- Impact: Forms don't submit, data doesn't persist, application is read-only demo
+- Fix approach: Add axios or fetch wrapper, create service modules in `src/app/services/` for each domain (sensors, settings, auth)
+
+**Placeholder Components:**
+- Issue: GraphView contains only placeholder content with no chart implementation
+- File: `src/app/components/views/GraphView.tsx` (lines 17-19)
+- Impact: Core feature is non-functional despite chart component existing (`src/app/components/ui/chart.tsx`)
+- Fix approach: Integrate Recharts with actual data source
+
+## Known Issues
+
+**Exposed Default Credentials:**
+- Issue: Login page displays hardcoded default credentials in the UI
+- File: `src/app/components/views/LoginView.tsx` (lines 54-56)
+- Content: "Default credentials: admin / admin"
+- Impact: Security vulnerability - exposes authentication credentials to all users
+- Fix approach: Remove credential hints from UI, implement secure password reset flow, store credentials server-side only
+
+**Non-Functional Interactive Elements:**
+- Issue: Buttons and actions don't perform actual operations
+- Files:
+  - `src/app/components/views/FlashMemoryView.tsx`: Download and Delete buttons (lines 80-87) are non-functional
+  - `src/app/components/views/SettingView.tsx`: Factory Reset and Reboot System buttons (lines 67-71) lack confirmation dialogs
+  - `src/app/components/views/GPRSSettingView.tsx`: Test Connection button (lines 60-62) has no implementation
+- Impact: Users receive no feedback, destructive actions can occur accidentally
+- Fix approach: Implement action handlers, add confirmation dialogs for destructive operations, add toast notifications for user feedback
+
+## Security Considerations
+
+**No Authentication Implementation:**
+- Risk: Login form is UI-only with no auth logic
+- File: `src/app/components/views/LoginView.tsx` - form submission not handled
+- Current mitigation: None
+- Recommendations: Implement JWT or session-based auth, add ProtectedRoute wrapper, store auth token securely (httpOnly cookies preferred)
+
+**Missing Input Validation:**
+- Risk: All forms accept any input without validation
+- Files: All form-containing views (`*SettingView.tsx`)
+- Current mitigation: None
+- Recommendations: Add Zod or Yup schemas for form validation, validate on blur and submit, display inline error messages
+
+**No HTTPS Enforcement:**
+- Risk: Application may run over unencrypted connections
+- Current mitigation: None visible
+- Recommendations: Add HSTS headers, enforce HTTPS in production builds, validate API URLs use HTTPS
+
+**Hardcoded Sensitive-Looking Configuration:**
+- Risk: Device configuration values exposed in source
+- Files:
+  - `src/app/components/views/StationInfoView.tsx`: Hardcoded station coordinates and serial numbers (lines 5-14)
+  - `src/app/components/views/Header.tsx`: Hardcoded station ID "STN-001" (line 56)
+- Current mitigation: None
+- Recommendations: Move configuration to environment variables or secure config endpoint
+
+## Performance Bottlenecks
+
+**Large Component Files:**
+- Problem: sidebar.tsx is 726 lines, violating single responsibility principle
+- File: `src/app/components/ui/sidebar.tsx`
+- Cause: Multiple components (SidebarProvider, Sidebar, SidebarTrigger, SidebarRail, etc.) in one file
+- Improvement path: Split into separate files: `sidebar-provider.tsx`, `sidebar-trigger.tsx`, `sidebar-menu.tsx`, etc.
+
+**No Code Splitting:**
+- Problem: All routes loaded upfront in single bundle
+- File: `src/app/routes.ts` - static imports of all view components
+- Cause: No lazy loading or dynamic imports
+- Improvement path: Use React.lazy() and Suspense for route-based code splitting
+
+**Direct DOM Manipulation:**
+- Problem: NavigationButtons uses imperative DOM access instead of React refs
+- File: `src/app/components/views/NavigationButtons.tsx` (lines 8-19)
+- Code: `document.getElementById("details-panel")`
+- Improvement path: Use React ref forwarded from DashboardLayout, or use scroll context
+
+## Fragile Areas
+
+**Chart Component Null Returns:**
+- Files: `src/app/components/ui/chart.tsx` (lines 78, 133, 153, 168, 267)
+- Issue: Multiple early `return null` statements may cause React reconciliation issues
+- Safe modification: Ensure parent components handle null returns gracefully, add error boundaries
+
+**Form State Management:**
+- Issue: All forms use uncontrolled inputs with defaultValue only
+- Files: All `*SettingView.tsx` files
+- Why fragile: Form state not tracked, can't validate, can't persist, can't show pending state
+- Safe modification: Convert to controlled inputs with useState, or use React Hook Form library
+
+**Hardcoded Route Paths:**
+- Issue: Route paths defined in multiple places
+- Files:
+  - `src/app/routes.ts` - route definitions
+  - `src/app/components/Sidebar.tsx` (lines 39-87) - navigation links
+- Why fragile: Route changes require updates in multiple files, easy to miss one
+- Safe modification: Create `src/app/constants/routes.ts` with path constants, use throughout app
+
+**No Error Boundaries:**
+- Issue: Single component error can crash entire application
+- Current state: No ErrorBoundary component found
+- Safe modification: Add error boundaries at route level and around complex components
+
+## Scaling Limits
+
+**Current Capacity:**
+- 72 source files, ~13,300 lines of TypeScript
+- No test coverage
+- All data hardcoded (no real data volume)
+
+**Limitations:**
+- No pagination implementation for data lists
+- No virtualization for long lists
+- No caching strategy
+
+**Scaling Path:**
+- Implement React Query or SWR for server state management
+- Add virtualized lists for large datasets
+- Implement proper pagination in data views
+
+## Dependencies at Risk
+
+**React Router v7 Migration:**
+- Current: `react-router` version 7.13.0
+- Risk: Recently released major version, API may change
+- Impact: Route definitions in `src/app/routes.ts` use newer createBrowserRouter API
+- Migration plan: Monitor for breaking changes, lock version if needed
+
+**Tailwind CSS v4:**
+- Current: Version 4.1.12 with @theme inline syntax
+- Risk: New major version with different configuration approach
+- Impact: theme.css uses new v4 syntax
+- Migration plan: Maintain lockfile, test before upgrades
+
+## Missing Critical Features
+
+**Real-Time Data Updates:**
+- Problem: Dashboard shows static values, no live sensor data
+- Blocks: Production deployment for monitoring use cases
+- Priority: High
+
+**Form Validation:**
+- Problem: No validation on any input fields
+- Files: All `*SettingView.tsx` files
+- Blocks: Data integrity, user experience
+- Priority: High
+
+**Error Handling:**
+- Problem: No error states, no user feedback for failures
+- Blocks: Production reliability
+- Priority: High
+
+**API Integration:**
+- Problem: No backend communication
+- Blocks: All CRUD operations
+- Priority: Critical
+
+**Authentication/Authorization:**
+- Problem: Login form is decorative only
+- Blocks: Security requirements
+- Priority: Critical
+
+**Confirmation Dialogs:**
+- Problem: Destructive actions (Factory Reset, Reboot, Delete) have no confirmation
+- Files: `src/app/components/views/SettingView.tsx`, `src/app/components/views/FlashMemoryView.tsx`
+- Priority: Medium
+
+## Test Coverage Gaps
+
+**No Testing Infrastructure:**
+- What's not tested: Everything (100% gap)
+- Files: Zero test files found
+- Risk: No regression protection, no confidence in changes
+- Priority: Critical
+
+**Recommended Testing Stack:**
+- Unit tests: Vitest + React Testing Library for components
+- Integration tests: Test form submissions, navigation flows
+- E2E tests: Playwright for critical user journeys
+
+**Critical Test Priorities:**
+1. Form validation and submission flows
+2. Authentication state management
+3. Data fetching and error handling
+4. Navigation and routing
+5. Settings persistence
+
+---
+
+*Concerns audit: 2026-03-13*