fix(android): Fixed class protection in builds to resolve the screen freezing issue in release builds (#1110)

* fix(android): Fixed class protection in builds to resolve the screen freezing issue in release builds

Allowed the use of debug signatures as a fallback during local verification

Updated build configurations to correctly handle missing signatures

Added documentation detailing signature requirements for release builds

* fix(android): Check signature configuration only when a release signature is required

Check the release signature configuration only when the task name contains ‘release’ to avoid unnecessary checks during non-release builds

* refactor(android): Optimize signature configuration validation logic and extract variables

Rewrite the signature configuration validation logic, extract properties as separate variables, and add null checks
Add validation of signature requirements for aggregate build tasks

* refactor(android): Optimize the detection logic for the release signature task

Break down complex conditional checks into clearer combinations of multiple conditions to improve code readability and maintainability

* fix(android): Fixed an issue with the normalization of build task names

Added normalization for task names containing colons during processing to ensure that signature verification logic executes correctly

* refactor(android): Optimize the logic for processing Gradle task names
Improve the logic for collecting and processing Gradle task names to ensure more accurate identification of project-related tasks and standardized handling. This prevents signature configuration errors caused by issues with task name formats.

Author: GT-610

CLAUDE.md

@@ -7,6 +7,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ### Development
 
 - `flutter run` - Run the app in development mode
+- `flutter run --release -PallowDebugReleaseSigning=true` - Run Android release locally with explicit debug-signing fallback for verification only
 - `dart run fl_build -p PLATFORM` - Build the app for specific platform (see fl_build package)
 - `dart run build_runner build --delete-conflicting-outputs` - Generate code for models with annotations (json_serializable, freezed, hive, riverpod)
   - Every time you change model files, run this command to regenerate code (Hive adapters, Riverpod providers, etc.)
@@ -93,3 +94,11 @@ This is a Flutter application for managing Linux servers with the following key
   - Before adding new strings, check if it already exists in `libL10n`.
   - Prioritize using strings from `libL10n` to avoid duplication, even if the meaning is not 100% exact, just use the substitution of `libL10n`.
 - Split UI into Widget build, Actions, Utils. use `extension on` to achieve this
+- Android release signing:
+  - Normal release builds must use the real release keystore from `key.properties`.
+  - Debug-signing fallback is for local verification only and must be enabled explicitly with `-PallowDebugReleaseSigning=true`.
+  - Do not use debug-signing fallback for formal release artifacts.
+- Android release artifacts:
+  - CI release builds for Android are split per ABI, not a single fat APK.
+  - Do not judge release size from a local `flutter build apk --release` fat APK.
+  - To reproduce CI-style Android artifacts locally, use `dart run fl_build -p android` or `flutter build apk --release --split-per-abi`.

android/app/build.gradle

@@ -17,11 +17,55 @@ def keystorePropertiesFile = rootProject.file('key.properties')
 if (keystorePropertiesFile.exists()) {
     keystoreProperties.load(new FileInputStream(keystorePropertiesFile))
 } else {
-    System.err.printf(" [!] key.properties not found in %s (%s). Build will fail. \n", rootProject, rootProject.file('.'))
+    System.err.printf(" [!] key.properties not found in %s (%s). \n", rootProject, rootProject.file('.'))
 }
 
-if (keystoreProperties['storeFile'] == null || !file(keystoreProperties['storeFile']).exists()) {
-    System.err.printf(" [!] storeFile defined in key.properties does not exist in %s. Build will fail. \n", file('.'))
+def storeFilePath = keystoreProperties['storeFile']?.toString()?.trim()
+def storePassword = keystoreProperties['storePassword']?.toString()?.trim()
+def keyAlias = keystoreProperties['keyAlias']?.toString()?.trim()
+def keyPassword = keystoreProperties['keyPassword']?.toString()?.trim()
+
+def hasReleaseSigning =
+    storeFilePath &&
+    file(storeFilePath).exists() &&
+    storePassword &&
+    keyAlias &&
+    keyPassword
+
+def allowDebugReleaseSigning = project.findProperty('allowDebugReleaseSigning') == 'true'
+def requestedTaskNames = gradle.startParameter.taskNames
+    .findAll {
+        !it.contains(':') ||
+        (it.startsWith(':') && it.indexOf(':', 1) == -1) ||
+        it.startsWith("${project.path}:") ||
+        it.startsWith(":${project.name}:")
+    }
+    .collect {
+        def normalizedTaskName =
+            (it.startsWith("${project.path}:") || it.startsWith(":${project.name}:"))
+                ? it.substring(it.lastIndexOf(':') + 1)
+                : it.startsWith(':') ? it.substring(1) : it
+        normalizedTaskName.toLowerCase()
+    }
+def aggregateSigningTasks = ['assemble', 'build', 'bundle', 'install']
+def requiresReleaseSigning = requestedTaskNames.any {
+    aggregateSigningTasks.contains(it) ||
+    it == 'release' ||
+    (it.startsWith('assemble') && it.contains('release')) ||
+    (it.startsWith('bundle') && it.contains('release')) ||
+    (it.startsWith('install') && it.contains('release')) ||
+    (it.startsWith('build') && it.contains('release'))
+}
+
+if (requiresReleaseSigning && !hasReleaseSigning) {
+    if (allowDebugReleaseSigning) {
+        System.err.printf(" [!] Release signing is unavailable. Falling back to debug signing because -PallowDebugReleaseSigning=true was provided. \n")
+    } else {
+        throw new GradleException(
+            'Release signing is not configured. Add key.properties with a valid storeFile, ' +
+            'or build with -PallowDebugReleaseSigning=true for local verification only.'
+        )
+    }
 }
 
 def flutterVersionCode = localProperties.getProperty('flutter.versionCode')
@@ -70,16 +114,16 @@ android {
 
     signingConfigs {
         release {
-            keyAlias keystoreProperties['keyAlias']
-            keyPassword keystoreProperties['keyPassword']
-            storeFile keystoreProperties['storeFile'] ? file(keystoreProperties['storeFile']) : null
-            storePassword keystoreProperties['storePassword']
+            keyAlias keyAlias
+            keyPassword keyPassword
+            storeFile storeFilePath ? file(storeFilePath) : null
+            storePassword storePassword
         }
     }
 
     buildTypes {
         release {
-            signingConfig signingConfigs.release
+            signingConfig hasReleaseSigning ? signingConfigs.release : signingConfigs.debug
             minifyEnabled true
             proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
         }

android/app/proguard-rules.pro

@@ -1 +1,2 @@
 -keep class com.jcraft.**  { *; }
+-keep class io.flutter.util.PathUtils { *; }

pubspec.lock

@@ -918,10 +918,10 @@ packages:
     dependency: transitive
     description:
       name: matcher
-      sha256: dc0b7dc7651697ea4ff3e69ef44b0407ea32c487a39fff6a4004fa585e901861
+      sha256: "12956d0ad8390bbcc63ca2e1469c0619946ccb52809807067a7020d57e647aa6"
       url: "https://pub.dev"
     source: hosted
-    version: "0.12.19"
+    version: "0.12.18"
   material_color_utilities:
     dependency: transitive
     description:
@@ -1506,26 +1506,26 @@ packages:
     dependency: "direct dev"
     description:
       name: test
-      sha256: "280d6d890011ca966ad08df7e8a4ddfab0fb3aa49f96ed6de56e3521347a9ae7"
+      sha256: "54c516bbb7cee2754d327ad4fca637f78abfc3cbcc5ace83b3eda117e42cd71a"
       url: "https://pub.dev"
     source: hosted
-    version: "1.30.0"
+    version: "1.29.0"
   test_api:
     dependency: transitive
     description:
       name: test_api
-      sha256: "8161c84903fd860b26bfdefb7963b3f0b68fee7adea0f59ef805ecca346f0c7a"
+      sha256: "93167629bfc610f71560ab9312acdda4959de4df6fac7492c89ff0d3886f6636"
       url: "https://pub.dev"
     source: hosted
-    version: "0.7.10"
+    version: "0.7.9"
   test_core:
     dependency: transitive
     description:
       name: test_core
-      sha256: "0381bd1585d1a924763c308100f2138205252fb90c9d4eeaf28489ee65ccde51"
+      sha256: "394f07d21f0f2255ec9e3989f21e54d3c7dc0e6e9dbce160e5a9c1a6be0e2943"
       url: "https://pub.dev"
     source: hosted
-    version: "0.6.16"
+    version: "0.6.15"
   tuple:
     dependency: transitive
     description: