feat: Add dynamic upper bound for speed test gauge based on historical data (#628)

* docs: Add UI Kit Library principle and translate constitution to English

- Add Article XIV: UI Kit Library Principle with mandatory UI component usage rules
- Translate all remaining Chinese content in constitution.md to English
- Update "Last Amended" date to 2026-02-11

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* feat: Add implement-feature-with-checks skill for automated constitution compliance

Create new Claude Code skill that automatically enforces project constitution principles during feature implementation.

Key features:
- Requirements clarity check before implementation starts
- Integrates with brainstorming skill for unclear requirements
- Enforces UI Kit Library usage with component verification
- Mandates test coverage (Service ≥90%, Provider ≥85%, Overall ≥80%)
- Automates testing execution (unit tests + screenshot tests)
- Runs code formatting (dart format) and analysis (flutter analyze)
- Validates architecture compliance (layer separation, error handling)
- Provides decision trees and examples for common scenarios

The skill automatically triggers on keywords like 實作, 創建, 新增, 開發, 修改, 重構, 修正, etc., ensuring consistent adherence to constitution without manual reminders.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* feat: Add dynamic upper bound for speed test gauge based on historical data

The speed test gauge now automatically adjusts its upper limit based on
historical test results, providing better visualization across different
network speed ranges.

Changes:
- Add helper methods to calculate maximum historical speed and round to
  nearest hundred
- Generate appropriate markers dynamically based on the upper bound
- Update meterView and _startButton to use dynamic markers instead of
  fixed 100 Mbps limit

Behavior:
- No history: defaults to 100 Mbps (maintains backward compatibility)
- With history: uses maximum speed from history, rounded up to nearest
  hundred (e.g., 345 Mbps → 400 Mbps upper bound)
- Markers are distributed appropriately for different speed ranges
  (100-200, 200-500, 500-1000, 1000+ Mbps)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: Ensure gauge markers stay sorted and within upper bound (#624)

Fix marker generation bug in _generateMarkers for 500-1000 Mbps range.
Previously, when upperBound was less than 750 (e.g., 600 or 700), the
method unconditionally added 750 marker, resulting in unsorted list
that exceeded the upper bound.

Changes:
- Add conditional check before adding 750 marker (only if upperBound >= 750)
- Ensure markers list maintains ascending order
- Ensure all markers stay within upperBound

Before: upperBound=600 → [0, 100, 200, 300, 400, 500, 750, 600] (unsorted)
After: upperBound=600 → [0, 100, 200, 300, 400, 500, 600] (sorted)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* refactor: Extract gauge calculation logic to SpeedTestGaugeUtils

Extract the 4 gauge calculation methods from SpeedTestWidget into a
reusable SpeedTestGaugeUtils class with comprehensive unit tests.

Changes:
- Create SpeedTestGaugeUtils class with 4 static methods:
  - calculateMaxHistoricalSpeed(): Find max speed from history
  - roundUpToHundred(): Round up to nearest hundred
  - calculateGaugeUpperBound(): Calculate dynamic upper bound
  - generateMarkers(): Generate appropriate markers for different ranges
- Add 39 comprehensive unit tests covering all edge cases
- Refactor SpeedTestWidget to use the new utils class
- Remove 4 private methods from SpeedTestWidget (130 lines)

Benefits:
- Improved testability: 100% test coverage for calculation logic
- Better code organization: Follows project pattern (feature/utils/)
- Reusability: Utils can be used in other contexts
- Maintainability: Centralized logic with clear documentation

Testing:
- All 39 utils tests pass
- All 23 existing health_check tests pass (regression)
- Static analysis clean

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: PeterJhongLinksys

lib/page/health_check/shared_widgets/speed_test_widget.dart

@@ -9,6 +9,7 @@ import 'package:privacy_gui/page/health_check/models/health_check_server.dart';
 import 'package:privacy_gui/page/health_check/models/speed_test_ui_model.dart';
 import 'package:privacy_gui/page/health_check/providers/health_check_provider.dart';
 import 'package:privacy_gui/page/health_check/providers/health_check_state.dart';
+import 'package:privacy_gui/page/health_check/utils/speed_test_gauge_utils.dart';
 import 'package:privacy_gui/route/constants.dart';
 import 'package:privacy_gui/utils.dart';
 import 'package:ui_kit_library/ui_kit.dart';
@@ -223,6 +224,13 @@ class SpeedTestWidget extends ConsumerWidget {
   Widget meterView(
       BuildContext context, HealthCheckState state, WidgetRef ref) {
     final result = state.result ?? SpeedTestUIModel.empty();
+
+    // Calculate dynamic upper bound and markers based on historical data
+    final upperBound = SpeedTestGaugeUtils.calculateGaugeUpperBound(state);
+    final isSmallGauge = (meterSize ?? 220) < 130;
+    final markers = SpeedTestGaugeUtils.generateMarkers(upperBound,
+        isSmallGauge: isSmallGauge);
+
     // Format the live meter value for display.
     final formattedLiveValue = NetworkUtils.formatBitsWithUnit(
         (state.meterValue * 1000).toInt(),
@@ -237,20 +245,7 @@ class SpeedTestWidget extends ConsumerWidget {
       child: AppGauge(
         size: meterSize ?? context.colWidth(3),
         value: meterValueMbps, // Value must be in Mbps for the meter scale
-        // Reduce clutter: show minimal or no labels if meter is small
-        markers: (meterSize ?? 220) < 130
-            ? const <double>[0, 100]
-            : const <double>[
-                0,
-                1,
-                5,
-                10,
-                20,
-                30,
-                50,
-                75,
-                100
-              ], // Markers are in Mbps
+        markers: markers, // Dynamic markers based on historical data
         centerBuilder: (context, value) {
           // The content inside the meter (e.g., live speed).
           final isSmall = (meterSize ?? 220) < 130;
@@ -540,11 +535,18 @@ class SpeedTestWidget extends ConsumerWidget {
   /// Builds the initial "Go" button to start the test.
   Widget _startButton(BuildContext context, WidgetRef ref,
       {SpeedTestUIModel? lastResult}) {
+    // Calculate dynamic upper bound and markers for idle state
+    final healthCheckState = ref.watch(healthCheckProvider);
+    final upperBound =
+        SpeedTestGaugeUtils.calculateGaugeUpperBound(healthCheckState);
+    final markers =
+        SpeedTestGaugeUtils.generateMarkers(upperBound, isSmallGauge: true);
+
     return Container(
       alignment: Alignment.center,
       child: AppGauge(
         size: meterSize ?? 220,
-        markers: const <double>[0, 100], // Default markers for start button
+        markers: markers, // Dynamic markers based on historical data
         // displayIndicatorValues: false, // assuming unsupported or default
         // indicatorPathStrokeWidth: 8,
         // markerRadius: 2,

lib/page/health_check/utils/speed_test_gauge_utils.dart

@@ -0,0 +1,206 @@
+import 'package:privacy_gui/page/health_check/models/speed_test_ui_model.dart';
+import 'package:privacy_gui/page/health_check/providers/health_check_state.dart';
+
+/// Utility class for calculating speed test gauge parameters.
+///
+/// This class provides helper methods to determine dynamic gauge bounds and markers
+/// based on historical speed test results. All methods are static and pure functions.
+class SpeedTestGaugeUtils {
+  // Private constructor to prevent instantiation
+  SpeedTestGaugeUtils._();
+
+  /// Calculates the maximum speed (in Mbps) from historical speed test results.
+  ///
+  /// This method examines both [state.historicalSpeedTests] and [state.latestSpeedTest]
+  /// to find the highest download or upload speed recorded.
+  ///
+  /// **Parameters:**
+  /// - [state]: The current [HealthCheckState] containing speed test history
+  ///
+  /// **Returns:**
+  /// - The maximum speed in Mbps (converted from Kbps)
+  /// - Returns 100.0 as default if no valid history exists
+  ///
+  /// **Examples:**
+  /// ```dart
+  /// final maxSpeed = SpeedTestGaugeUtils.calculateMaxHistoricalSpeed(state);
+  /// // Returns 150.5 if the fastest recorded speed was 150.5 Mbps
+  /// ```
+  static double calculateMaxHistoricalSpeed(HealthCheckState state) {
+    final allTests = <SpeedTestUIModel>[];
+
+    // Include historical tests
+    if (state.historicalSpeedTests.isNotEmpty) {
+      allTests.addAll(state.historicalSpeedTests);
+    }
+
+    // Include latest test if it's not already in historical
+    if (state.latestSpeedTest != null &&
+        !state.historicalSpeedTests.contains(state.latestSpeedTest)) {
+      allTests.add(state.latestSpeedTest!);
+    }
+
+    if (allTests.isEmpty) {
+      return 100.0; // Default to 100 Mbps if no history
+    }
+
+    double maxSpeed = 0.0;
+
+    for (final test in allTests) {
+      // Download speed (convert Kbps to Mbps)
+      if (test.downloadBandwidthKbps != null &&
+          test.downloadBandwidthKbps! > 0) {
+        final downloadMbps = test.downloadBandwidthKbps! / 1024.0;
+        if (downloadMbps > maxSpeed) {
+          maxSpeed = downloadMbps;
+        }
+      }
+
+      // Upload speed (convert Kbps to Mbps)
+      if (test.uploadBandwidthKbps != null && test.uploadBandwidthKbps! > 0) {
+        final uploadMbps = test.uploadBandwidthKbps! / 1024.0;
+        if (uploadMbps > maxSpeed) {
+          maxSpeed = uploadMbps;
+        }
+      }
+    }
+
+    // If all values were null or zero, return default
+    return maxSpeed > 0 ? maxSpeed : 100.0;
+  }
+
+  /// Rounds up a speed value to the nearest hundred (ceiling).
+  ///
+  /// This ensures gauge markers are at clean, readable intervals.
+  /// The minimum return value is always 100.0.
+  ///
+  /// **Parameters:**
+  /// - [speed]: The speed value in Mbps to round up
+  ///
+  /// **Returns:**
+  /// - The rounded value, minimum 100.0
+  ///
+  /// **Examples:**
+  /// ```dart
+  /// SpeedTestGaugeUtils.roundUpToHundred(89.0);   // Returns 100.0
+  /// SpeedTestGaugeUtils.roundUpToHundred(345.0);  // Returns 400.0
+  /// SpeedTestGaugeUtils.roundUpToHundred(1234.0); // Returns 1300.0
+  /// SpeedTestGaugeUtils.roundUpToHundred(56.0);   // Returns 100.0 (minimum)
+  /// ```
+  static double roundUpToHundred(double speed) {
+    // Ensure minimum is 100
+    if (speed < 100) {
+      return 100.0;
+    }
+
+    // Round up to nearest hundred
+    return (speed / 100).ceil() * 100.0;
+  }
+
+  /// Calculates the dynamic upper bound for the speed test gauge.
+  ///
+  /// This combines [calculateMaxHistoricalSpeed] and [roundUpToHundred]
+  /// to determine an appropriate maximum value for the gauge display.
+  ///
+  /// **Parameters:**
+  /// - [state]: The current [HealthCheckState] containing speed test history
+  ///
+  /// **Returns:**
+  /// - The calculated upper bound in Mbps (minimum 100.0, rounded to hundreds)
+  ///
+  /// **Examples:**
+  /// ```dart
+  /// final upperBound = SpeedTestGaugeUtils.calculateGaugeUpperBound(state);
+  /// // If max historical speed is 234 Mbps, returns 300.0
+  /// ```
+  static double calculateGaugeUpperBound(HealthCheckState state) {
+    final maxHistorical = calculateMaxHistoricalSpeed(state);
+    return roundUpToHundred(maxHistorical);
+  }
+
+  /// Generates appropriate marker values for the speed gauge.
+  ///
+  /// The markers are distributed to provide meaningful reference points based
+  /// on the upper bound. Different ranges use different marker intervals:
+  ///
+  /// - **100 Mbps**: `[0, 1, 5, 10, 20, 30, 50, 75, 100]`
+  /// - **100-200 Mbps**: `[0, 10, 20, 30, 50, 75, 100, 150, upperBound]`
+  /// - **200-500 Mbps**: `[0, 50, 100, 150, ..., upperBound]` (50 Mbps intervals)
+  /// - **500-1000 Mbps**: `[0, 100, 200, ..., 500, 750, upperBound]` (100 Mbps intervals)
+  /// - **1000+ Mbps**: `[0, 200, 400, ..., upperBound]` (200 Mbps intervals)
+  ///
+  /// **Small gauge mode** (when [isSmallGauge] is true): Returns only `[0, upperBound]`
+  ///
+  /// **Parameters:**
+  /// - [upperBound]: The maximum value for the gauge in Mbps
+  /// - [isSmallGauge]: If true, returns simplified markers for compact display (default: false)
+  ///
+  /// **Returns:**
+  /// - A sorted list of marker values in ascending order
+  ///
+  /// **Examples:**
+  /// ```dart
+  /// SpeedTestGaugeUtils.generateMarkers(100.0);
+  /// // Returns [0, 1, 5, 10, 20, 30, 50, 75, 100]
+  ///
+  /// SpeedTestGaugeUtils.generateMarkers(300.0);
+  /// // Returns [0, 50, 100, 150, 200, 250, 300]
+  ///
+  /// SpeedTestGaugeUtils.generateMarkers(300.0, isSmallGauge: true);
+  /// // Returns [0, 300]
+  /// ```
+  static List<double> generateMarkers(
+    double upperBound, {
+    bool isSmallGauge = false,
+  }) {
+    if (isSmallGauge) {
+      return [0, upperBound];
+    }
+
+    if (upperBound <= 100) {
+      // Default case: 0-100 Mbps
+      return const [0, 1, 5, 10, 20, 30, 50, 75, 100];
+    } else if (upperBound <= 200) {
+      // 100-200 Mbps range
+      return [0, 10, 20, 30, 50, 75, 100, 150, upperBound];
+    } else if (upperBound <= 500) {
+      // 200-500 Mbps range
+      // Generate markers at 50 Mbps intervals up to 300, then 100 Mbps intervals
+      final markers = <double>[0];
+      for (double i = 50; i <= 300; i += 50) {
+        markers.add(i);
+      }
+      for (double i = 400; i < upperBound; i += 100) {
+        markers.add(i);
+      }
+      markers.add(upperBound);
+      return markers;
+    } else if (upperBound <= 1000) {
+      // 500-1000 Mbps range
+      // Generate markers at 100 Mbps intervals, with an extra marker at 750 if applicable
+      final markers = <double>[0];
+      for (double i = 100; i <= 500; i += 100) {
+        markers.add(i);
+      }
+      // Only add 750 if upperBound is >= 750 to maintain sorted order
+      if (upperBound >= 750) {
+        markers.add(750);
+      }
+      if (upperBound != 1000) {
+        markers.add(upperBound);
+      } else {
+        markers.add(1000);
+      }
+      return markers;
+    } else {
+      // 1000+ Mbps range
+      // Generate markers at 200 Mbps intervals
+      final markers = <double>[0];
+      for (double i = 200; i < upperBound; i += 200) {
+        markers.add(i);
+      }
+      markers.add(upperBound);
+      return markers;
+    }
+  }
+}