pindo 5.18.6 → 5.18.11

data/lib/pindo/module/android/android_project_helper.rb

@@ -1,7 +1,120 @@
+require "fileutils"
+require "pathname"
+
 module Pindo
   class AndroidProjectHelper
     class << self
 
+      # 永久修复 Unity IL2CPP 工程：将 mergeDebug/mergeReleaseJniLibFolders 对 BuildIl2CppTask 的依赖
+      # 从“硬编码 buildType”改为“匹配所有 merge*JniLibFolders 变体”，避免自定义 buildType（如 workflow）
+      # 或 Unity/AGP 版本差异导致漏掉依赖关系。
+      #
+      # 仅修改 Unity 导出工程（包含 unityLibrary/build.gradle[.kts]）中的 unityLibrary 模块 Gradle 文件。
+      # 幂等：已注入则不会重复写入。
+      #
+      # @return [Boolean] 是否发生了写入变更
+      def ensure_unity_il2cpp_jni_merge_depends_on!(project_path)
+        raise ArgumentError, "project_path 不能为空" if project_path.to_s.empty?
+        raise ArgumentError, "项目目录不存在: #{project_path}" unless File.directory?(project_path)
+
+        unity_library = File.join(project_path, "unityLibrary")
+        return false unless File.directory?(unity_library)
+
+        gradle_path = File.join(unity_library, "build.gradle")
+        kts_path = File.join(unity_library, "build.gradle.kts")
+        target_file = File.file?(kts_path) ? kts_path : (File.file?(gradle_path) ? gradle_path : nil)
+        return false unless target_file
+
+        original = File.read(target_file, encoding: "UTF-8")
+        # 仅在明显是 Unity IL2CPP 工程时介入
+        return false unless original.include?("BuildIl2CppTask")
+
+        dsl = target_file.end_with?(".kts") ? :kts : :groovy
+        updated = normalize_unity_il2cpp_jni_merge_depends_on_text(original)
+        updated = migrate_unity_il2cpp_jni_merge_depends_on_marker_text(updated)
+        updated = ensure_unity_il2cpp_jni_merge_depends_on_text(updated, dsl: dsl)
+
+        return false if updated == original
+
+        File.write(target_file, updated, encoding: "UTF-8")
+        true
+      end
+
+
+      # 根据导出工程 `unityLibrary/build.gradle[.kts]` 中**实际声明**的本地 AAR 依赖，校验并补齐 `unityLibrary/libs`。
+      #
+      # EDM4U 常将部分 AAR 解析到 `Assets/GeneratedLocalRepo/**/m2repository`，导出后 Gradle 仍按 `name + ext:aar`
+      #、`libs/某.aar` 或 `fileTree(dir: 'libs', include: ['*.aar', ...])` 引用；若只拷贝导出目录会缺文件。
+      # 声明来源：`AndroidResolverDependencies.xml` + `GeneratedLocalRepo`（`fileTree` 模式会合并二者中的 .aar 清单）。
+      #
+      # @return [Array<String>] 已在 libs 中存在或本次拷贝的 .aar 文件名
+      def ensure_export_unity_library_aars_from_gradle!(unity_root_path:, export_path:)
+        raise ArgumentError, "unity_root_path 不能为空" if unity_root_path.to_s.empty?
+        raise ArgumentError, "export_path 不能为空" if export_path.to_s.empty?
+        raise ArgumentError, "Unity 工程目录不存在: #{unity_root_path}" unless File.directory?(unity_root_path)
+        raise ArgumentError, "导出目录不存在: #{export_path}" unless File.directory?(export_path)
+
+        unity_library = File.join(export_path, "unityLibrary")
+        gradle_path = %w[build.gradle build.gradle.kts].map { |n| File.join(unity_library, n) }.find { |p| File.file?(p) }
+        libs_dir = File.join(unity_library, "libs")
+        FileUtils.mkdir_p(libs_dir)
+
+        unless gradle_path
+          return []
+        end
+
+        gradle_content = File.read(gradle_path, encoding: "UTF-8")
+        resolver_xml = File.join(unity_root_path, "ProjectSettings", "AndroidResolverDependencies.xml")
+        aar_index = build_android_resolver_aar_index(unity_root_path, resolver_xml)
+
+        required_basenames =
+          if gradle_declares_libs_file_tree_with_aar?(gradle_content)
+            merged_aar_basenames_for_libs_file_tree(aar_index, unity_root_path)
+          else
+            extract_required_aar_basenames_from_unity_library_gradle(gradle_content)
+          end
+
+        return [] if required_basenames.empty?
+
+        satisfied = []
+        missing_after_copy = []
+
+        required_basenames.each do |base|
+          dst = File.join(libs_dir, base)
+          if file_readable_nonbroken?(dst)
+            satisfied << base
+            next
+          end
+
+          src = resolve_aar_source_for_basename(base, aar_index, unity_root_path)
+          unless src
+            missing_after_copy << base
+            next
+          end
+
+          FileUtils.cp(src, dst)
+          satisfied << base
+        end
+
+        unless missing_after_copy.empty?
+          raise Informative, <<~MSG
+            Unity unityLibrary/libs 缺少 Gradle 已声明的 AAR，且无法在 Unity 工程内找到源文件：
+            #{missing_after_copy.sort.join(', ')}
+            Unity 工程: #{unity_root_path}
+            导出目录: #{export_path}
+            Gradle: #{gradle_path}
+            请检查: #{resolver_xml}
+            并在 Unity 中执行：External Dependency Manager → Android Resolver → Force Resolve 后重新导出。
+          MSG
+        end
+
+        satisfied.uniq
+      end
+
+      # 兼容旧调用名（实现已泛化为「按 Gradle 声明补齐 libs」）。
+      def ensure_export_has_firebase_unity_aars!(unity_root_path:, export_path:)
+        ensure_export_unity_library_aars_from_gradle!(unity_root_path: unity_root_path, export_path: export_path)
+      end
 
       def unity_android_project?(project_path)
         # 检查 unityLibrary 模块是否存在
@@ -349,6 +462,266 @@ module Pindo
 
       private
 
+      def normalize_unity_il2cpp_jni_merge_depends_on_text(content)
+        return content if content.to_s.empty?
+
+        out = content.dup
+
+        # 清理旧的 hardcode 片段（只针对 BuildIl2CppTask + merge(Debug|Release)JniLibFolders 的 dependsOn）
+        out.gsub!(/^\s*project\(\s*['"]:unityLibrary['"]\s*\)\.merge(?:Debug|Release)JniLibFolders\.dependsOn\s+BuildIl2CppTask\s*\n?/m, "")
+        out.gsub!(/^\s*merge(?:Debug|Release)JniLibFolders\.dependsOn\s+BuildIl2CppTask\s*\n?/m, "")
+
+        # 清理旧的 findByName 判定（保守：仅删提到 merge(Debug|Release)JniLibFolders 的行）
+        out.gsub!(/^\s*if\s*\(\s*project\(\s*['"]:unityLibrary['"]\s*\)\.tasks\.findByName\(\s*['"]merge(?:Debug|Release)JniLibFolders['"]\s*\)\s*\)\s*\n?/m, "")
+
+        # 也清理一些常见的单行 if(...) 写法（保守：只删包含 mergeXJniLibFolders + BuildIl2CppTask 的行）
+        out.gsub!(/^\s*if\s*\([^\n]*merge(?:Debug|Release)JniLibFolders[^\n]*\)\s*[^\n]*BuildIl2CppTask[^\n]*\n?/m, "")
+
+        # 如果上面把 afterEvaluate 块内容清空了，这里移除“空壳 afterEvaluate { }”避免残留无意义块，
+        # 后续由 ensure_* 重新按目标写法注入。
+        #
+        # 仅移除“块内无任何非空白/非注释内容”的 afterEvaluate，避免误删业务逻辑。
+        out.gsub!(/^\s*afterEvaluate\s*\{\s*\n(?:(?:\s*\/\/[^\n]*\n)|(?:\s*\n))*\s*\}\s*\n?/m, "")
+
+        out
+      end
+
+      # 迁移旧注入块：如果历史版本把 marker + afterEvaluate 注入在文件尾部（android 块外），
+      # 这里先移除旧块，再按新规则（插入 android {} 内部）重新注入，确保与目标工程写法一致。
+      def migrate_unity_il2cpp_jni_merge_depends_on_marker_text(content)
+        return content if content.to_s.empty?
+
+        marker = "PINDO_UNITY_IL2CPP_JNI_MERGE_DEPENDS_ON"
+        idx = content.index(marker)
+        return content unless idx
+
+        # 从 marker 行开始，尝试定位其后的 afterEvaluate { ... } 并用花括号计数移除该段
+        line_start = content.rindex("\n", idx) || 0
+        line_start = 0 if line_start == 0
+        after_eval = content.index("afterEvaluate", idx)
+        return content unless after_eval
+
+        brace_open = content.index("{", after_eval)
+        return content unless brace_open
+
+        brace_close = find_matching_brace_simple(content, brace_open)
+        return content unless brace_close
+
+        # 删除到 afterEvaluate 块结束行尾
+        line_end = content.index("\n", brace_close) || brace_close
+        content[0...line_start] + content[(line_end + 1)..].to_s
+      end
+
+      def ensure_unity_il2cpp_jni_merge_depends_on_text(content, dsl:)
+        return content if content.to_s.empty?
+
+        marker = "PINDO_UNITY_IL2CPP_JNI_MERGE_DEPENDS_ON"
+        # 已经注入过（新老位置都带 marker），则认为已满足；调用方如需迁移会先 migrate_* 移除再注入
+        return content if content.include?(marker)
+
+        # 已存在等价实现（但没有 marker）时，不再重复注入，避免出现多个 afterEvaluate 块。
+        return content if unity_il2cpp_jni_merge_depends_on_already_present?(content)
+
+        snippet = unity_il2cpp_jni_merge_depends_on_snippet(marker, dsl: dsl)
+        inject_into_android_block_text(content, snippet)
+      end
+
+      def unity_il2cpp_jni_merge_depends_on_snippet(marker, dsl:)
+        if dsl == :kts
+          <<~KTS.rstrip
+            // #{marker}
+            afterEvaluate {
+                tasks.matching { it.name.startsWith("merge") && it.name.endsWith("JniLibFolders") }.configureEach {
+                    dependsOn(BuildIl2CppTask)
+                }
+            }
+          KTS
+        else
+          <<~GRADLE.rstrip
+            // #{marker}
+            afterEvaluate {
+              tasks.matching { it.name.startsWith("merge") && it.name.endsWith("JniLibFolders") }.configureEach {
+                  dependsOn BuildIl2CppTask
+              }
+            }
+          GRADLE
+        end
+      end
+
+      # 将 snippet 插入到 android { ... } 的末尾（最后一个 } 之前）。
+      # 如果找不到 android 块，则回退到文件末尾追加（但 Unity 导出工程一般都有 android）。
+      def inject_into_android_block_text(content, snippet)
+        android_open = content.index(/\bandroid\s*\{/)
+        return content.rstrip + "\n\n" + snippet + "\n" unless android_open
+
+        brace_open = content.index("{", android_open)
+        return content.rstrip + "\n\n" + snippet + "\n" unless brace_open
+
+        brace_close = find_matching_brace_simple(content, brace_open)
+        return content.rstrip + "\n\n" + snippet + "\n" unless brace_close
+
+        inner = content[(brace_open + 1)...brace_close]
+        # 采用 android 块的缩进风格：取 android 关键字所在行的缩进，然后 +4
+        line_start = content.rindex("\n", android_open) || 0
+        line_start = 0 if line_start == 0
+        base_indent = content[line_start..android_open].match(/^\s*/).to_s
+        snippet_indented = indent_block_text(dedent_block_text(snippet), base_indent + "    ")
+
+        # 避免插入过多空行：统一只在前后各保留一个换行
+        updated_inner = inner.rstrip + "\n" + snippet_indented.rstrip + "\n"
+        content[0..brace_open] + updated_inner + content[brace_close..]
+      end
+
+      # 判定是否已经存在等价的「merge*JniLibFolders dependsOn BuildIl2CppTask」逻辑（不依赖 marker）。
+      # 这用于避免 Unity 工程本身已包含同等逻辑时重复插入。
+      def unity_il2cpp_jni_merge_depends_on_already_present?(content)
+        return false if content.to_s.empty?
+
+        # 仅在存在 BuildIl2CppTask 时才认为可能等价
+        return false unless content.include?("BuildIl2CppTask")
+
+        has_matching =
+          content.match?(/tasks\.matching\s*\{\s*it\.name\.startsWith\(\s*["']merge["']\s*\)\s*&&\s*it\.name\.endsWith\(\s*["']JniLibFolders["']\s*\)\s*\}/) ||
+          content.match?(/tasks\.matching\s*\{\s*it\.name\.startsWith\(\s*["']merge["']\s*\)\s*&&\s*it\.name\.endsWith\(\s*["']JniLibFolders["']\s*\)\s*\}\.configureEach/)
+
+        return false unless has_matching
+
+        # dependsOn 允许 Groovy 简写或括号写法
+        content.match?(/dependsOn\s*(?:\(\s*)?BuildIl2CppTask(?:\s*\))?/)
+      end
+
+      # 去掉 block 的公共前导缩进（保留相对缩进）
+      def dedent_block_text(text)
+        lines = text.to_s.lines
+        indents = lines.filter_map do |l|
+          next if l.strip.empty?
+
+          l[/^\s*/].to_s.length
+        end
+        return text if indents.empty?
+
+        cut = indents.min
+        lines.map do |l|
+          l.strip.empty? ? l : l.sub(/^\s{0,#{cut}}/, "")
+        end.join
+      end
+
+      def indent_block_text(text, indent)
+        text.to_s.lines.map do |l|
+          l.strip.empty? ? l : (indent + l)
+        end.join
+      end
+
+      # 简单花括号匹配（不解析字符串/注释）：用于 Unity 导出 Gradle（结构相对规整）。
+      def find_matching_brace_simple(str, open_brace_index)
+        depth = 0
+        i = open_brace_index
+        while i < str.length
+          ch = str.getbyte(i)
+          if ch == 123 # {
+            depth += 1
+          elsif ch == 125 # }
+            depth -= 1
+            return i if depth == 0
+          end
+          i += 1
+        end
+        nil
+      end
+
+      def file_readable_nonbroken?(path)
+        return false unless path && File.exist?(path)
+        return false unless File.file?(path)
+
+        return File.exist?(path) if File.symlink?(path)
+
+        true
+      end
+
+      # implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar']) 等：按 Resolver + GeneratedLocalRepo 合并 .aar 清单
+      def gradle_declares_libs_file_tree_with_aar?(content)
+        return false unless content.include?("fileTree")
+
+        libs_dir_arg = %q{['"]\.?/?libs['"]}
+        content.scan(/fileTree\s*\(\s*dir\s*:\s*#{libs_dir_arg}\s*,\s*include\s*:\s*(\[[^\]]+\])/im) do |m|
+          return true if gradle_file_tree_include_lists_aar?(m[0])
+        end
+        content.scan(/fileTree\s*\(\s*include\s*:\s*(\[[^\]]+\])\s*,\s*dir\s*:\s*#{libs_dir_arg}\s*\)/im) do |m|
+          return true if gradle_file_tree_include_lists_aar?(m[0])
+        end
+
+        # Kotlin: fileTree(mapOf("dir" to "libs", "include" to listOf("*.jar", "*.aar")))
+        if content.match?(/fileTree\s*\(\s*mapOf/im) && content.match?(/"dir"\s+to\s+"libs"/m)
+          return true if content.match?(/(?:listOf|setOf)\s*\([^)]*["'][^"']*\.aar["']/m)
+        end
+
+        false
+      end
+
+      def gradle_file_tree_include_lists_aar?(include_bracket_text)
+        include_bracket_text.match?(/['"][^'"]*\*[^'"]*\.aar['"]/)
+      end
+
+      def merged_aar_basenames_for_libs_file_tree(aar_index, unity_root_path)
+        bases = aar_index.keys.dup
+        generated = File.join(unity_root_path, "Assets", "GeneratedLocalRepo")
+        if File.directory?(generated)
+          Dir.glob(File.join(generated, "**", "*.aar")).each do |p|
+            bases << File.basename(p) if File.file?(p)
+          end
+        end
+        bases.uniq
+      end
+
+      def extract_required_aar_basenames_from_unity_library_gradle(content)
+        names = []
+        dep_types = %w[implementation api compileOnly runtimeOnly debugImplementation releaseImplementation]
+        dep_alt = dep_types.join("|")
+
+        content.scan(/(?:#{dep_alt})\s*\(\s*name\s*:\s*['"]([^'"]+)['"]\s*,\s*ext\s*:\s*['"]aar['"]/im) { names << "#{Regexp.last_match(1)}.aar" }
+        content.scan(/(?:#{dep_alt})\s*\(\s*ext\s*:\s*['"]aar['"]\s*,\s*name\s*:\s*['"]([^'"]+)['"]/im) { names << "#{Regexp.last_match(1)}.aar" }
+        content.scan(/(?:#{dep_alt})\s*\(\s*name\s*=\s*["']([^'"]+)["']\s*,\s*ext\s*=\s*["']aar["']/im) { names << "#{Regexp.last_match(1)}.aar" }
+        content.scan(/(?:#{dep_alt})\s*\(\s*ext\s*=\s*["']aar["']\s*,\s*name\s*=\s*["']([^'"]+)["']/im) { names << "#{Regexp.last_match(1)}.aar" }
+
+        content.scan(/['"](?:\.\/)?libs\/([^'"]+\.aar)['"]/i) { names << Regexp.last_match(1) }
+
+        names.uniq
+      end
+
+      def build_android_resolver_aar_index(unity_root_path, resolver_xml)
+        index = {}
+        return index unless File.file?(resolver_xml)
+
+        require "rexml/document"
+        doc = REXML::Document.new(File.read(resolver_xml, encoding: "UTF-8"))
+        doc.elements.each("dependencies/files/file") do |e|
+          rel = e.text.to_s.strip
+          next if rel.empty?
+          next unless rel.end_with?(".aar")
+
+          abs = Pathname.new(rel).absolute? ? rel : File.join(unity_root_path, rel)
+          base = File.basename(rel)
+          (index[base] ||= []) << abs
+        end
+        index
+      rescue StandardError => e
+        raise Informative, "解析 AndroidResolverDependencies.xml 失败: #{e.message}\n请在 Unity 中执行 EDM4U Force Resolve 后重试。"
+      end
+
+      def resolve_aar_source_for_basename(basename, aar_index, unity_root_path)
+        (aar_index[basename] || []).each do |abs|
+          return abs if File.file?(abs)
+        end
+
+        generated = File.join(unity_root_path, "Assets", "GeneratedLocalRepo")
+        if File.directory?(generated)
+          hit = Dir.glob(File.join(generated, "**", basename)).find { |p| File.file?(p) }
+          return hit if hit
+        end
+
+        nil
+      end
+
       def extract_modules_from_settings(content)
         modules = []
         # 兼容 include ':app' / include(":app", ":lib")

data/lib/pindo/module/android/gradle_helper.rb

@@ -205,7 +205,9 @@ module Pindo
         end
 
         # 生成 Wrapper
-        generate_gradle_wrapper(gradle_dir, gradle_version)
+        ok = generate_gradle_wrapper(gradle_dir, gradle_version)
+        ensure_gradlew_runnable!(gradle_dir)
+        ok
       end
 
       # 解析gradle版本
@@ -244,7 +246,30 @@ module Pindo
         end
 
         # 生成 Wrapper
-        generate_gradle_wrapper(gradle_dir, gradle_version)
+        ok = generate_gradle_wrapper(gradle_dir, gradle_version)
+        ensure_gradlew_runnable!(gradle_dir)
+        ok
+      end
+
+      # 确保工程根目录下 gradlew 可被当前环境执行：补齐执行位；在 macOS 上尝试移除
+      # com.apple.quarantine（无该属性时 xattr 失败可忽略）。用于避免
+      # 「bad interpreter: Operation not permitted」类错误，无用户交互。
+      def ensure_gradlew_runnable!(gradle_dir)
+        return if gradle_dir.nil? || gradle_dir.to_s.empty?
+
+        gradlew = File.join(gradle_dir, "gradlew")
+        return unless File.file?(gradlew)
+
+        begin
+          st = File.stat(gradlew)
+          File.chmod(st.mode | 0o111, gradlew)
+        rescue StandardError
+          # 只读卷等场景下忽略
+        end
+
+        return unless RUBY_PLATFORM.match?(/darwin/i)
+
+        system("xattr", "-d", "com.apple.quarantine", gradlew, out: File::NULL, err: File::NULL)
       end
 
       # =================== 私有辅助方法 ===================

data/lib/pindo/module/android/keystore_helper.rb

@@ -122,14 +122,34 @@ module Pindo
         @pindo_managed_signing_paths = []
       end
 
+      # 打包结束后恢复本次被修改的 Gradle 签名配置（仅恢复被本次任务改动过的文件）
+      def restore_managed_signing_config!
+        backups = @pindo_managed_gradle_backups || {}
+        backups.each do |path, original_content|
+          next if path.nil? || path.to_s.empty?
+          next unless original_content.is_a?(String)
+          next unless File.exist?(path)
+
+          File.write(path, original_content)
+        end
+      ensure
+        @pindo_managed_gradle_backups = {}
+      end
+
+      # 清理本次写入到进程 ENV 的签名变量（避免后续任务误继承）
+      def cleanup_managed_signing_env!
+        keys = @pindo_managed_env_keys || []
+        keys.each { |k| ENV.delete(k.to_s) if k }
+      ensure
+        @pindo_managed_env_keys = []
+      end
+
       # 将签名配置应用到 Android 工程
       #
       # 默认（与工程手写的 RELEASE_* 约定一致）：只拉取 JPS、拷贝 jks 到项目 signing/，并设置当前进程
       # RELEASE_KEYSTORE_PATH / RELEASE_KEYSTORE_PASSWORD / RELEASE_KEY_ALIAS / RELEASE_KEY_PASSWORD，不修改 build.gradle。
       # RELEASE_KEYSTORE_PATH 使用 jks 的绝对路径，便于 app 子模块内 `file(System.getenv(...))` 引用。
       #
-      # 若需恢复自动改写 signingConfigs，设置环境变量：PINDO_INJECT_ANDROID_SIGNING_GRADLE=1
-      #
       # @param project_dir [String] 项目目录
       # @param build_type [String] 构建类型 "debug" 或 "release"
       # @return [Boolean] 是否成功
@@ -139,6 +159,8 @@ module Pindo
         raise ArgumentError, "bundle_id 不能为空" if bundle_id.blank?
 
         reset_managed_signing_paths!
+        reset_managed_gradle_backups!
+        reset_managed_env_keys!
 
         main_module = Pindo::AndroidProjectHelper.get_main_module(project_dir)
         unless main_module
@@ -170,19 +192,16 @@ module Pindo
           raise "JPS keystore 未拷贝到工程 signing/（无法解析路径），Gradle 将回退到 build.gradle 中的本地 jks；请检查 JPS 证书是否下载成功"
         end
 
-        abs_keystore = File.expand_path(File.join(project_dir, rel_plain))
-
-        inject_gradle = Pindo::Options::GlobalOptionsState.instance[:injectsigning]
-        if inject_gradle
-          if gradle_file.end_with?(".kts")
-            ensure_keystore_config_kts(gradle_file, project_dir, build_type, sign_config, bundle_id: bundle_id)
-          else
-            ensure_keystore_config_groovy(gradle_file, project_dir, build_type, sign_config, bundle_id: bundle_id)
-          end
-          export_jps_release_signing_env!(cfg, keystore_path_for_env: rel_plain)
+        if gradle_file.end_with?(".kts")
+          ensure_keystore_config_kts(gradle_file, project_dir, build_type, sign_config, bundle_id: bundle_id)
         else
-          export_jps_release_signing_env!(cfg, keystore_path_for_env: abs_keystore)
+          ensure_keystore_config_groovy(gradle_file, project_dir, build_type, sign_config, bundle_id: bundle_id)
         end
+        # 注意：部分 Unity 导出工程/多模块工程的 Gradle rootProject 目录可能不是 project_dir，
+        # 相对路径（如 signing/xxx.jks）会被解析到错误的模块目录下（如 launcher/signing/...）。
+        # 这里改为导出绝对路径，确保与 keystore 创建/拷贝目录保持一致。
+        keystore_abs = File.expand_path(File.join(project_dir, rel_plain))
+        export_jps_release_signing_env!(cfg, keystore_path_for_env: keystore_abs)
         true
       end
 
@@ -244,6 +263,14 @@ module Pindo
         @pindo_managed_signing_paths = []
       end
 
+      def reset_managed_gradle_backups!
+        @pindo_managed_gradle_backups = {}
+      end
+
+      def reset_managed_env_keys!
+        @pindo_managed_env_keys = []
+      end
+
       def register_managed_signing_path!(path)
         return if path.nil? || path.to_s.empty?
 
@@ -251,6 +278,23 @@ module Pindo
         @pindo_managed_signing_paths << path
       end
 
+      def register_managed_gradle_backup!(path, original_content)
+        return if path.nil? || path.to_s.empty?
+        return unless original_content.is_a?(String)
+
+        @pindo_managed_gradle_backups ||= {}
+        # 同一文件只备份一次：第一次写入前的内容即为“原始内容”
+        @pindo_managed_gradle_backups[path] ||= original_content
+      end
+
+      def register_managed_env_key!(key)
+        return if key.nil? || key.to_s.empty?
+
+        @pindo_managed_env_keys ||= []
+        @pindo_managed_env_keys << key.to_s
+        @pindo_managed_env_keys.uniq!
+      end
+
       # 将 JPS 返回的路径/口令/别名写入当前进程环境变量，供 Gradle / bundletool 子进程继承（与 build.gradle 中 RELEASE_* 名称一致）
       def export_jps_release_signing_env!(cfg, keystore_path_for_env:)
         return unless cfg.is_a?(Hash)
@@ -258,6 +302,7 @@ module Pindo
         if keystore_path_for_env && !keystore_path_for_env.to_s.empty?
           ENV[ENV_RELEASE_KEYSTORE_PATH] =
             keystore_path_for_env
+          register_managed_env_key!(ENV_RELEASE_KEYSTORE_PATH)
         end
 
         sp = cfg["storePassword"]
@@ -270,6 +315,10 @@ module Pindo
         ENV[ENV_RELEASE_KEYSTORE_PASSWORD] = sp_plain.to_s if sp_plain && !sp_plain.to_s.empty?
         ENV[ENV_RELEASE_KEY_PASSWORD] = kp_plain.to_s if kp_plain && !kp_plain.to_s.empty?
         ENV[ENV_RELEASE_KEY_ALIAS] = ka.to_s if ka && !ka.to_s.empty?
+
+        register_managed_env_key!(ENV_RELEASE_KEYSTORE_PASSWORD) if sp_plain && !sp_plain.to_s.empty?
+        register_managed_env_key!(ENV_RELEASE_KEY_PASSWORD) if kp_plain && !kp_plain.to_s.empty?
+        register_managed_env_key!(ENV_RELEASE_KEY_ALIAS) if ka && !ka.to_s.empty?
       end
 
       # Groovy：解析 storePassword/keyPassword（支持 System.getenv、可选 ?: 回退、或历史明文）
@@ -517,6 +566,7 @@ module Pindo
         if content == original_content
           puts "  ✓ build.gradle 无需修改"
         else
+          register_managed_gradle_backup!(gradle_file, original_content)
           File.write(gradle_file, content)
           puts "  ✓ build.gradle 已更新"
         end
@@ -571,6 +621,7 @@ module Pindo
         if content == original_content
           puts "  ✓ build.gradle.kts 无需修改"
         else
+          register_managed_gradle_backup!(gradle_file, original_content)
           File.write(gradle_file, content)
           puts "  ✓ build.gradle.kts 已更新"
         end
@@ -1285,34 +1336,52 @@ module Pindo
 
       # =================== 写入 keystore 配置的辅助方法 ===================
 
-      # 生成签名配置代码块（Groovy）——与工程约定：RELEASE_* + ?: 本地回退（明文仅回退串，来自 JPS 的敏感值走本次进程 ENV）
+      # 生成签名配置代码块（Groovy）
+      # 注意：签名信息只允许从环境变量读取，严禁在 build.gradle 中写入任何明文（包括回退密码/alias/路径）。
       def generate_signing_config_groovy(config_name, pindo_config)
-        rel_fb = escape_gradle_double_quoted(signing_keystore_fallback_relative(pindo_config))
-        alias_fb = escape_gradle_double_quoted(pindo_config["keyAlias"])
-
         <<~GROOVY
           #{config_name} {
-                  def keystorePath = System.getenv("#{ENV_RELEASE_KEYSTORE_PATH}") ?: "#{rel_fb}"
-                  storeFile rootProject.file(keystorePath)
-                  storePassword System.getenv("#{ENV_RELEASE_KEYSTORE_PASSWORD}") ?: "123456"
-                  keyAlias System.getenv("#{ENV_RELEASE_KEY_ALIAS}") ?: "#{alias_fb}"
-                  keyPassword System.getenv("#{ENV_RELEASE_KEY_PASSWORD}") ?: "123456"
+                  def signingEnvVars = ["#{ENV_RELEASE_KEYSTORE_PATH}", "#{ENV_RELEASE_KEYSTORE_PASSWORD}", "#{ENV_RELEASE_KEY_ALIAS}", "#{ENV_RELEASE_KEY_PASSWORD}"]
+                  def missing = signingEnvVars.findAll { !System.getenv(it) }
+                  if (!missing.isEmpty()) {
+                      throw new GradleException("Missing required environment variables for release signing: ${missing.join(', ')}")
+                  }
+                  def keystorePath = System.getenv("#{ENV_RELEASE_KEYSTORE_PATH}")
+                  def keystoreFile = rootProject.file(keystorePath)
+                  if (!keystoreFile.exists()) {
+                      throw new GradleException("Keystore file not found: ${keystoreFile.absolutePath}")
+                  }
+                  storeFile keystoreFile
+                  storePassword System.getenv("#{ENV_RELEASE_KEYSTORE_PASSWORD}")
+                  keyAlias System.getenv("#{ENV_RELEASE_KEY_ALIAS}")
+                  keyPassword System.getenv("#{ENV_RELEASE_KEY_PASSWORD}")
               }
         GROOVY
       end
 
       # 生成签名配置代码块（Kotlin DSL）
       def generate_signing_config_kts(config_name, pindo_config)
-        rel_fb = escape_gradle_double_quoted(signing_keystore_fallback_relative(pindo_config))
-        alias_fb = escape_gradle_double_quoted(pindo_config["keyAlias"])
-
         <<~KOTLIN
           create("#{config_name}") {
-                  val keystorePath = System.getenv("#{ENV_RELEASE_KEYSTORE_PATH}") ?: "#{rel_fb}"
-                  storeFile = rootProject.file(keystorePath)
-                  storePassword = System.getenv("#{ENV_RELEASE_KEYSTORE_PASSWORD}") ?: "123456"
-                  keyAlias = System.getenv("#{ENV_RELEASE_KEY_ALIAS}") ?: "#{alias_fb}"
-                  keyPassword = System.getenv("#{ENV_RELEASE_KEY_PASSWORD}") ?: "123456"
+                  val signingEnvVars = listOf(
+                      "#{ENV_RELEASE_KEYSTORE_PATH}",
+                      "#{ENV_RELEASE_KEYSTORE_PASSWORD}",
+                      "#{ENV_RELEASE_KEY_ALIAS}",
+                      "#{ENV_RELEASE_KEY_PASSWORD}",
+                  )
+                  val missing = signingEnvVars.filter { System.getenv(it).isNullOrBlank() }
+                  if (missing.isNotEmpty()) {
+                      throw GradleException("Missing required environment variables for release signing: ${missing.joinToString(\", \")}")
+                  }
+                  val keystorePath = System.getenv("#{ENV_RELEASE_KEYSTORE_PATH}")
+                  val keystoreFile = rootProject.file(keystorePath)
+                  if (!keystoreFile.exists()) {
+                      throw GradleException("Keystore file not found: ${keystoreFile.absolutePath}")
+                  }
+                  storeFile = keystoreFile
+                  storePassword = System.getenv("#{ENV_RELEASE_KEYSTORE_PASSWORD}")
+                  keyAlias = System.getenv("#{ENV_RELEASE_KEY_ALIAS}")
+                  keyPassword = System.getenv("#{ENV_RELEASE_KEY_PASSWORD}")
               }
         KOTLIN
       end