Demo: Custom Dashboard Layout

.agent/workflows/manual-testing.md

@@ -0,0 +1,169 @@
+---
+description: Manual testing workflow for PrivacyGUI web application with browser automation
+---
+
+# Manual Testing Workflow
+
+This workflow guides the process of manually testing the PrivacyGUI web application using browser automation.
+
+## Prerequisites
+
+- Ensure you are in the PrivacyGUI project directory
+- Have the router/mock server accessible at localhost
+- User should provide the router password when prompted
+
+## Steps
+
+### 1. Start the Web Server
+
+1. Execute background command: `nohup flutter run -d web-server --web-port 61672 --web-browser-flag --disable-web-security --dart-define force=local --target lib/main.dart < /dev/null > server.log 2>&1 & echo $! > flutter_pid.txt`
+2. Pause for 15 seconds (to give Flutter time to start).
+3. Read the last 20 lines of `server.log`.
+4. Check the Log for "listening on" or URL information.
+5. If successful, proceed with the test task; otherwise, report an error.
+
+### 2. Open Browser and Navigate
+
+Use the `browser_subagent` tool to:
+1. Navigate to `https://localhost` (IMPORTANT: Do NOT include the port number 61672, use default HTTPS port)
+2. If a certificate warning appears, bypass it by clicking "Advanced" → "Proceed to localhost"
+3. Wait for the page to fully load
+
+### 3. Determine Login State
+
+Check the current URL/page state:
+
+#### If Login Page (`#/localLoginPassword`)
+1. The page shows "Log in" with a "Router Password" input field
+2. **Ask the user for the password** if not provided
+3. Click the password input field
+4. Type the provided password
+5. Click "Log in" button or press Enter
+6. Wait for dashboard to load
+
+#### If PNP Flow (Plug and Play Setup)
+The PnP flow is detected when the URL contains `/pnp` or shows setup wizard UI.
+
+**PnP Flow States** (reference: `doc/pnp/pnp-flow.md`):
+
+| State | Description | Expected UI |
+|-------|-------------|-------------|
+| `AdminInitializing` | Initial checks running | Loading spinner |
+| `AdminUnconfigured` | Router not yet configured | "Continue" button shown |
+| `AdminAwaitingPassword` | Password required | Password input field |
+| `AdminInternetConnected` | Connected, auto-advancing | Brief loading then wizard |
+| `WizardConfiguring` | Setup wizard steps | PnpStepper with WiFi/Guest/Network config |
+| `WizardSaved` | Configuration saved | Success message |
+| `WizardWifiReady` | Setup complete | "Done" button to go to dashboard |
+| `NoInternetRoute` | No internet connection | Troubleshooter views |
+
+**PnP Step Components**:
+- **Step 1**: WiFi Configuration (SSID, Password)
+- **Step 2**: Guest Network (Optional)
+- **Step 3**: Network Settings (Name It, Topology)
+- **Final**: Firmware check and completion
+
+### 4. Execute Test Instructions
+
+Based on user's test instructions:
+1. Navigate to the specified page/feature
+2. Perform the requested actions (click buttons, fill forms, etc.)
+3. Capture screenshots at key points
+4. Record any errors or unexpected behaviors
+
+**Common Test Areas**:
+- **Dashboard**: Home, Menu, Network status
+- **Instant-Devices**: Device list, filters, editing
+- **Instant-WiFi**: WiFi settings, SSID changes
+- **Instant-Admin**: Router password, firmware, timezone
+- **Instant-Topology**: Node management, LED settings
+- **Advanced Settings**: Detailed configuration
+- **PnP Troubleshooter**: ISP settings, modem checks
+
+### 5. Generate Test Results
+
+After completing the test, generate a comprehensive report:
+
+#### Create Test Report Artifact
+
+Save to: `<artifact_dir>/test_report.md`
+
+Include:
+1. **Test Summary**: Date, time, test scope
+2. **Environment**: Browser, URL, router model
+3. **Test Steps Executed**: Numbered list of actions taken
+4. **Results**: 
+   - ✅ Passed items
+   - ❌ Failed items with details
+   - ⚠️ Warnings or observations
+5. **Screenshots**: Embed captured screenshots using `![description](path)`
+6. **Video Recording**: Reference the browser recording `.webp` file
+7. **Recommendations**: Any suggested fixes or improvements
+
+#### Example Report Structure
+
+```markdown
+# Manual Test Report
+
+**Date**: YYYY-MM-DD HH:MM
+**Tester**: Gemini Browser Agent
+**Build**: Flutter Web
+
+## Test Scope
+[Description of what was tested]
+
+## Test Environment
+- URL: https://localhost/#/...
+- Router/Mock: [Model info]
+- Browser: Chrome (headless)
+
+## Test Steps & Results
+
+| Step | Action | Expected | Actual | Status |
+|------|--------|----------|--------|--------|
+| 1 | Login with password | Dashboard loads | Dashboard loaded | ✅ |
+| 2 | Click Menu | Menu opens | Menu opened | ✅ |
+| ... | ... | ... | ... | ... |
+
+## Screenshots
+
+![Dashboard after login](path/to/screenshot.png)
+
+## Video Recording
+
+Browser session recorded at: [path/to/recording.webp]
+
+## Issues Found
+[List any bugs or issues discovered]
+
+## Recommendations
+[Suggested fixes or improvements]
+```
+
+### 6. Cleanup (Optional)
+
+If the test is complete and you want to stop the server:
+```bash
+if [ -f flutter_pid.txt ]; then
+  kill $(cat flutter_pid.txt)
+  rm flutter_pid.txt
+  echo "Server stopped"
+else
+  echo "PID file not found"
+fi
+```
+
+## Tips
+
+- **SSL Issues**: Always use `https://localhost` instead of `http://localhost` for API calls to work properly
+- **Flutter Web Rendering**: DOM may appear empty due to Flutter's canvas rendering; use pixel-based clicking
+- **Wait Times**: Allow 3-5 seconds after navigation for Flutter to render
+- **Screenshots**: Capture at every significant state change for documentation
+- **PnP Testing**: May require router reset or mock mode to trigger PnP flow
+
+## Related Documentation
+
+- PnP Flow: `doc/pnp/pnp-flow.md`
+- PnP Overview: `doc/pnp/pnp.md`
+- Test Cases: `doc/tests/cases/`
+- Screenshot Tests: `doc/screenshot_test/`

.agent/workflows/service-decoupling-audit.md

@@ -0,0 +1,193 @@
+---
+description: Audit service layer decoupling from JNAP and document service contracts for future protocol migration
+---
+
+# Service Decoupling Audit Workflow
+
+This workflow checks the current state of service-layer decoupling from JNAP-specific implementations and documents service contracts for future USP/TR migration.
+
+## Prerequisites
+
+- Access to `lib/core/data/services/` directory
+- Access to `lib/page/**/services/` directories
+- Understanding of JNAP actions in `lib/core/jnap/actions/`
+
+---
+
+## Step 1: Identify All Services
+
+// turbo
+```bash
+cd /Users/austin.chang/flutter-workspaces/privacyGUI/PrivacyGUI
+find lib -name "*_service.dart" -type f | head -50
+```
+
+List all service files and categorize them:
+- **Core Services**: `lib/core/data/services/`
+- **Feature Services**: `lib/page/**/services/`
+
+---
+
+## Step 2: Check JNAP Coupling in Each Service
+
+For each service file, check for direct JNAP dependencies:
+
+// turbo
+```bash
+cd /Users/austin.chang/flutter-workspaces/privacyGUI/PrivacyGUI
+grep -l "JNAPAction\|JNAPResult\|JNAPSuccess\|JNAPError\|JNAPTransaction" lib/core/data/services/*.dart lib/page/**/services/*.dart 2>/dev/null | head -30
+```
+
+**Decoupling Criteria:**
+| Level | Criteria | Status |
+|-------|----------|--------|
+| 🔴 High Coupling | Service directly uses `JNAPAction`, `JNAPResult` | Needs refactoring |
+| 🟡 Medium Coupling | Service uses `RouterRepository` but abstracts JNAP | Acceptable |
+| 🟢 Low Coupling | Service uses protocol-agnostic interfaces | Ideal |
+
+---
+
+## Step 3: Analyze RouterRepository Usage
+
+Check how services interact with RouterRepository:
+
+// turbo
+```bash
+cd /Users/austin.chang/flutter-workspaces/privacyGUI/PrivacyGUI
+grep -n "routerRepositoryProvider\|RouterRepository" lib/core/data/services/*.dart lib/page/**/services/*.dart 2>/dev/null | head -50
+```
+
+Document the usage pattern:
+- `send()` - Single JNAP command
+- `transaction()` - Batch JNAP commands  
+- `scheduledCommand()` - Polling JNAP commands
+
+---
+
+## Step 4: Document Service Contracts
+
+For each service, create a contract document with the following template:
+
+```markdown
+## [ServiceName]
+
+**Location**: `lib/path/to/service.dart`
+
+**Responsibility**: Brief description of what this service does
+
+**Dependencies**:
+- RouterRepository (JNAP communication)
+- Other services or providers
+
+### Read Operations
+| Operation | Description | JNAP Action(s) |
+|-----------|-------------|----------------|
+| getXxx() | Description | JNAPAction.xxx |
+
+### Write Operations
+| Operation | Description | JNAP Action(s) |
+|-----------|-------------|----------------|
+| setXxx() | Description | JNAPAction.xxx |
+
+### Data Models
+- Input: List of input types
+- Output: List of output/state types
+
+### Side Effects
+- Does this trigger device restart?
+- Does this require polling for completion?
+```
+
+---
+
+## Step 5: Generate Service-JNAP Mapping Table
+
+// turbo
+```bash
+cd /Users/austin.chang/flutter-workspaces/privacyGUI/PrivacyGUI
+grep -h "JNAPAction\." lib/core/data/services/*.dart lib/page/**/services/*.dart 2>/dev/null | grep -o "JNAPAction\.[a-zA-Z]*" | sort | uniq -c | sort -rn | head -30
+```
+
+Create a mapping table for migration planning:
+
+| JNAP Action | Used By Service(s) | USP Equivalent (TBD) |
+|-------------|-------------------|----------------------|
+| getDeviceInfo | DashboardManagerService, PollingService | Device.DeviceInfo. |
+| getDevices | DeviceManagerService, PollingService | Device.Hosts.Host. |
+| ... | ... | ... |
+
+---
+
+## Step 6: Check Domain Model Independence
+
+Verify that domain models don't expose JNAP-specific structures:
+
+// turbo
+```bash
+cd /Users/austin.chang/flutter-workspaces/privacyGUI/PrivacyGUI
+grep -l "fromMap\|fromJson" lib/core/jnap/models/*.dart | head -20
+```
+
+**Model Checklist:**
+- [ ] Field names are domain-specific, not JNAP-specific
+- [ ] Factory constructors handle data transformation
+- [ ] Models are in `lib/core/jnap/models/` (acceptable for now)
+
+---
+
+## Step 7: Generate Audit Report
+
+Create a summary report at:
+`/Users/austin.chang/flutter-workspaces/privacyGUI/PrivacyGUI/docs/service-decoupling-audit.md`
+
+Report should include:
+1. **Executive Summary**: Overall decoupling status
+2. **Service Inventory**: List of all services with coupling level
+3. **JNAP Action Usage**: Which actions are used and where
+4. **Migration Readiness**: Services ready for protocol swap
+5. **Recommendations**: Priority actions for better decoupling
+
+---
+
+## Step 8: Update Service Documentation
+
+For services with missing contracts, add documentation comments:
+
+```dart
+/// [ServiceName] - Brief description
+///
+/// ## Responsibilities
+/// - List of responsibilities
+///
+/// ## JNAP Actions Used
+/// - `JNAPAction.xxx` - Purpose
+/// - `JNAPAction.yyy` - Purpose
+///
+/// ## Future Migration Notes
+/// - USP equivalent operations (when known)
+/// - Special considerations
+class ServiceName {
+  // ...
+}
+```
+
+---
+
+## Output Artifacts
+
+After completing this workflow, you should have:
+
+1. **Service Inventory List** - All services with their locations
+2. **Coupling Assessment** - Red/Yellow/Green status for each service
+3. **JNAP Action Mapping** - Complete list of JNAP actions and their services
+4. **Service Contracts** - Documented interfaces for each service
+5. **Audit Report** - Summary document for planning
+
+---
+
+## When to Run This Workflow
+
+- Before starting USP/TR integration planning
+- After adding new services
+- During quarterly architecture reviews
+- Before major refactoring efforts

.github/workflows/deploy-demo.yml

@@ -12,6 +12,11 @@ on:
         options:
           - demo
           - staging
+      custom_layout:
+        description: 'Enable custom dashboard layout'
+        required: false
+        default: true
+        type: boolean
 
 # 設定 GitHub Pages 所需的權限
 permissions:
@@ -56,6 +61,7 @@ jobs:
         run: |
           flutter build web \
             --release \
+            --dart-define=custom_layout=${{ inputs.custom_layout }} \
             --target=lib/main_demo.dart \
             --base-href "/PrivacyGUI/demo/"
 

.vscode/launch.json

@@ -30,7 +30,9 @@
             ],
             "toolArgs": [
                 "--dart-define",
-                "force=local"
+                "force=local",
+                "--dart-define",
+                "custom_layout=true"
             ],
             "program": "lib/main.dart"
         }