pindo 5.20.3 → 5.20.5

data/lib/pindo/command/web/autobuild.rb

@@ -366,9 +366,13 @@ module Pindo
                       tasks << message_task
                     end
 
-                    # 8. 创建媒体附件上传任务（如果需要，只依赖 Git 提交任务）
-                    if @args_media_flag
-                      # 获取 Git 管理类型的工作流（不同于 HTML 上传的工作流）
+                    # 8. 获取 Git 管理类型的工作流（media、bind、send 共用，不同于 HTML 上传的包工作流）
+                    # commit 记录挂在 Git 工作流下，媒体附件、包绑定、工作流消息都按它定位
+                    git_app_info_obj = nil
+                    git_workflow_info = nil
+                    if @args_media_flag || @args_bind_flag || @args_send_flag
+                      # 取不到就让异常冒泡：media/bind/send 都依赖它，静默跳过会让命令
+                      # 明明没做用户要求的事却以 0 退出
                       git_app_info_obj, git_workflow_info = PgyerHelper.share_instace.prepare_upload(
                         working_directory: config[:project_path],
                         conf: @args_conf,
@@ -376,48 +380,53 @@ module Pindo
                         manage_type: "git"
                       )
 
+                      unless git_app_info_obj && git_workflow_info
+                        raise Informative, "未获取到 Git 类型的工作流；请在 JPS 后台配置 manage_type=git 的工作流"
+                      end
+                    end
+
+                    # 9. 创建媒体附件上传任务（如果需要，依赖 Git 提交/打 Tag 任务）
+                    if @args_media_flag
                       media_upload_task = Pindo::TaskSystem::JPSUploadMediaTask.new(
                         [],  # 空数组，自动从 JPSMedia/ 目录查找
                         config[:project_path],  # upload_path
                         app_info_obj: git_app_info_obj,
                         workflow_info: git_workflow_info,
-                        project_name: nil
+                        project_name: nil,
+                        required: @options[:media] || false  # 仅用户显式 --media 时，找不到文件才算失败
                       )
                       # 依赖 Git 提交任务
                       media_upload_task.dependencies << git_commit_task.id
+                      # 同样依赖 GitTagTask：并发模式下媒体上传可能与 build/tag 并行，
+                      # 不依赖它就会关联到构建前的 commit，与包绑定的 commit 不一致
+                      media_upload_task.dependencies << git_tag_task.id if git_tag_task
                       tasks << media_upload_task
                     end
 
-                    # 9. 创建 Git Commit 绑定任务（如果需要，依赖上传任务）
+                    # 10. 创建 Git Commit 绑定任务（如果需要，依赖上传任务）
                     bind_package_task = nil  # 声明变量以便后续工作流消息任务使用
                     if @args_bind_flag
                       bind_package_task = Pindo::TaskSystem::JPSBindPackageTask.new(
                         nil,  # app_version_list 为 nil，从依赖任务获取
                         project_dir: config[:project_path],
-                        app_info_obj: config[:app_info_obj],
-                        workflow_info: config[:workflow_info],
+                        app_info_obj: git_app_info_obj,      # 使用 Git app_info_obj
+                        workflow_info: git_workflow_info,    # 使用 Git workflow_info
                         project_name: nil
                       )
-                      # 依赖上传任务和 Git 提交任务
+                      # 依赖上传任务和 Git 任务
+                      # GitTagTask 会提交构建注入文件并移动 HEAD，必须依赖它才能拿到 tag 所在的 commit
                       bind_package_task.dependencies << upload_task.id
                       bind_package_task.dependencies << git_commit_task.id
+                      bind_package_task.dependencies << git_tag_task.id if git_tag_task
                       tasks << bind_package_task
                     end
 
-                    # 10. 创建工作流消息任务（如果需要，发送到测试群）
+                    # 11. 创建工作流消息任务（如果需要，发送到测试群）
                     if @args_send_flag
-                      # 获取 Git 工作流信息
-                      git_app_info_obj, git_workflow_info = PgyerHelper.share_instace.prepare_upload(
-                        working_directory: config[:project_path],
-                        conf: @args_conf,
-                        package_type: nil,
-                        manage_type: "git"
-                      )
-
                       workflow_message_task = Pindo::TaskSystem::JPSWorkFlowMessageTask.new(
                         project_id: git_app_info_obj["id"],
-                        workflow_id: git_workflow_info["id"],
-                        branch: 'master',
+                        workflow_id: git_workflow_info[:workflow_id],  # workflow_info 是 symbol key 结构，没有 "id" 键
+                        # branch 不传：由任务从 Git 依赖任务取 resolve 之后的真实发布分支
                         single: true,
                         app_info_obj: git_app_info_obj,
                         workflow_info: git_workflow_info

data/lib/pindo/module/pgyer/pgyerhelper.rb

@@ -198,8 +198,6 @@ module Pindo
 
           puts "package_type #{package_type} manage_type: #{manage_type}"
 
-          Funlog.instance.fancyinfo_success("获取工作流列表成功，共 #{workflows.size} 个工作流")
-
           # 2. 根据 manage_type 或 package_type 过滤工作流
           if manage_type == "git"
             # manage_type 为 git 时，只筛选 manage_type == "git" 的工作流，不看 package_type
@@ -249,6 +247,10 @@ module Pindo
             display_workflows = filtered_workflows
           end
 
+          # 过滤后再报数：只报总数会让人以为剩下的工作流被漏掉了，
+          # 实际是按 manage_type / package_type 筛掉的，两个数字一起给出才不歧义
+          Funlog.instance.fancyinfo_success("获取工作流列表成功，共 #{workflows.size} 个工作流，其中 #{type_desc} #{display_workflows.size} 个")
+
           # 2.5 若指定了 workflow_name，按名称精确匹配（忽略大小写与首尾空格）确定性选择。
           # 只接受完整精确匹配，不做子串模糊匹配，避免 "Production" 误命中 "Legacy Production Upload"。
           if workflow_name && !workflow_name.to_s.strip.empty? && !display_workflows.empty?
@@ -849,6 +851,16 @@ module Pindo
 
                 # 计算上传耗时
                 upload_duration = Time.now - upload_start_time
+
+                # upload_file 失败时返回 nil。不在这里拦住的话，后面会照常打印「上传完成」
+                # 和一个拿完整文件大小除以失败耗时算出来的假速度，再去做无谓的附件上传，
+                # 直到提交包信息前才失败——日志里先 ❌ 后 ✅ 就是这么来的。
+                if upload_res.nil?
+                    Funlog.instance.fancyinfo_error("文件上传失败! 耗时: #{upload_duration.round(2)} 秒")
+                    puts "  失败原因见上方日志；加 --verbose 重跑可看到接口返回的 code/msg"
+                    raise Informative, "上传失败!"
+                end
+
                 upload_speed = file_size_mb / upload_duration
                 puts "✅ 文件上传完成! 耗时: #{upload_duration.round(2)} 秒, 平均速度: #{upload_speed.round(2)} MB/s"
 
@@ -865,8 +877,15 @@ module Pindo
 
                         # 计算附件上传耗时
                         attach_duration = Time.now - attach_start_time
-                        attach_speed = attach_size_mb / attach_duration
-                        puts "✅ 附件上传完成! 耗时: #{attach_duration.round(2)} 秒, 平均速度: #{attach_speed.round(2)} MB/s"
+
+                        # 同主文件：nil 即失败，不能照打「上传完成」。
+                        # 但附件失败不阻断主包流程（下方 rescue 也是这个取向），只如实报告。
+                        if attach_key_url.nil?
+                            Funlog.instance.fancyinfo_warning("附件上传失败! 耗时: #{attach_duration.round(2)} 秒（不影响主包上传）")
+                        else
+                            attach_speed = attach_size_mb / attach_duration
+                            puts "✅ 附件上传完成! 耗时: #{attach_duration.round(2)} 秒, 平均速度: #{attach_speed.round(2)} MB/s"
+                        end
                     end
 
                     if !attach_key_url.nil?
@@ -1780,71 +1799,138 @@ module Pindo
 
         # 获取特定 commit 已绑定的包 ID
         #
+        # 数据源是 commit_log/preview 的 bindVersions。
+        #
+        # 不能用 project_package/bind_list：它按 projectId 查、作用域看似更宽，
+        # 但实测（项目 930 条记录）每条的 commitId、branch、workflowId、commitLogs
+        # 全部为 nil——该接口只返回包本身，不携带 commit 绑定关系，
+        # 按 commitId 过滤会恒得空列表，进而让覆盖式写入误删该 commit 的已有绑定。
+        #
+        # preview 需要传 workflowId，但实测同项目下不同 workflowId（3457 / 2650）
+        # 返回的 bindVersions 完全一致——绑定按 commitId 全局记录，
+        # 不存在"按工作流查漏、覆盖时被删掉"的问题。
+        #
+        # 绑定接口是覆盖式写入，调用方需要把已绑定的包一起提交，因此必须区分
+        # 「确认没有绑定过」和「查不出来」——后者返回空数组会导致已有绑定被静默覆盖丢失。
+        #
         # @param commit_id [String] Git commit SHA（必需）
-        # @param workflow_id [Integer, String] 工作流 ID（必需，API 需要）
-        # @return [Array<String>] 已绑定的包 ID 数组
+        # @param workflow_id [Integer, String] 工作流 ID（必需，接口入参）
+        # @return [Array<String>, nil] 已绑定的包 ID 数组；查询失败或结构异常时返回 nil
         def get_commit_bound_package_ids(commit_id:, workflow_id:)
-            return [] if commit_id.nil? || commit_id.empty?
-            return [] if workflow_id.nil?
+            if commit_id.nil? || commit_id.empty?
+                Funlog.instance.fancyinfo_warning("commit_id 为空，无法查询已绑定的包")
+                return nil
+            end
+
+            if workflow_id.nil? || workflow_id.to_s.empty?
+                Funlog.instance.fancyinfo_warning("workflow_id 为空，无法查询已绑定的包")
+                return nil
+            end
 
             begin
-                # 使用 commit_log/preview API 直接查询特定 commit
                 result = @pgyer_client.get_commit_log_preview(
                     workflowId: workflow_id,
                     commitIds: [commit_id],
-                    params: { onlyCliff: false }  # 需要完整信息
+                    params: { onlyCliff: false }
                 )
 
                 # 兼容两种响应格式
                 response_code = result&.dig("code") || result&.dig("meta", "code")
 
-                if result && (response_code == 0 || response_code == 200)
-                    # 从响应中提取 commit 信息
-                    # preview API 可能返回数组或单个对象
-                    commit_data = result&.dig("data")
-                    commit_list = commit_data.is_a?(Array) ? commit_data : [commit_data].compact
-
-                    # 查找匹配的 commit
-                    commit_info = commit_list.find { |item| item && item["commitId"] == commit_id }
-
-                    if commit_info && commit_info["bindVersions"]
-                        # 从 bindVersions 中提取所有平台的 projectPackageId
-                        bind_versions = commit_info["bindVersions"]
-                        package_ids = []
-
-                        # 遍历所有平台（ipa, apk, zip, mac, exe 等）
-                        bind_versions.each do |_platform, version_info|
-                            if version_info && version_info["projectPackageId"]
-                                package_ids << version_info["projectPackageId"]
-                            end
+                unless result && (response_code == 0 || response_code == 200)
+                    error_msg = result&.dig("msg") || result&.dig("meta", "message") || "未知错误"
+                    Funlog.instance.fancyinfo_warning("查询 Commit #{commit_id[0..7]} 的绑定信息失败: #{error_msg}")
+                    return nil
+                end
+
+                data = result&.dig("data")
+
+                # code=0 且 data=nil 是接口表达「没有这条 commit」的正常响应（实测确认），
+                # 不是畸形响应。此时该 commit 还没进 commit log，不可能有已记录的绑定。
+                # 若误判为 nil，首次绑定（commit log 尚未生成）会被整体阻断。
+                if data.nil?
+                    puts "[PINDO_DEBUG] Commit #{commit_id[0..7]} 不在 commit log 中，视为未绑定" if ENV['PINDO_DEBUG']
+                    return []
+                end
+
+                list = data.is_a?(Array) ? data : [data]
+                matched = list.select { |item| item.is_a?(Hash) && same_commit?(item["commitId"], commit_id) }
+
+                # 接口正常返回但没有这条 commit：该 commit 还没进 commit log，
+                # 也就不可能有已记录的绑定
+                if matched.empty?
+                    puts "[PINDO_DEBUG] Commit #{commit_id[0..7]} 不在 commit log 中，视为未绑定" if ENV['PINDO_DEBUG']
+                    return []
+                end
+
+                # 同一个 commitId 在 commit log 里可能对应多条记录（push 一条、tag 一条，
+                # 实测 commit_log/list 可见），哪条带 bindVersions 没有契约保证。
+                # 只取第一条匹配会漏读绑定，进而让覆盖式写入删掉已有绑定，
+                # 因此合并所有匹配记录的绑定。
+                package_ids = []
+                matched.each do |commit_info|
+                    bind_versions = commit_info["bindVersions"]
+
+                    # 该记录没有绑定信息：未绑定的 commit 就是 null，属正常情况
+                    next if bind_versions.nil?
+
+                    unless bind_versions.is_a?(Hash)
+                        Funlog.instance.fancyinfo_warning("bindVersions 结构异常（#{bind_versions.class}），无法确认已有绑定")
+                        return nil
+                    end
+
+                    # bindVersions 形如 { "ipa" => { "projectPackageId" => "..." }, ... }，
+                    # 每个平台一个包
+                    bind_versions.each do |platform, version_info|
+                        next if version_info.nil?
+
+                        unless version_info.is_a?(Hash)
+                            Funlog.instance.fancyinfo_warning("bindVersions[#{platform}] 结构异常（#{version_info.class}），无法确认已有绑定")
+                            return nil
                         end
 
-                        return package_ids.compact.uniq
-                    else
-                        # 如果没有找到或没有绑定信息，返回空数组（可能是首次绑定）
-                        if ENV['PINDO_DEBUG']
-                            puts "[PINDO_DEBUG] Commit #{commit_id[0..7]} 没有绑定信息"
+                        # 有平台条目却拿不到包 id：静默跳过会得到残缺列表，
+                        # 覆盖写入时等于把那个平台的绑定删掉
+                        package_id = version_info["projectPackageId"]
+                        if package_id.nil? || package_id.to_s.strip.empty?
+                            Funlog.instance.fancyinfo_warning("Commit #{commit_id[0..7]} 的 #{platform} 绑定缺少 projectPackageId，无法确认已有绑定")
+                            return nil
                         end
-                        return []
-                    end
-                else
-                    # 如果获取失败，返回空数组（不阻止绑定流程）
-                    if ENV['PINDO_DEBUG']
-                        error_msg = result&.dig("msg") || result&.dig("meta", "message") || "未知错误"
-                        puts "[PINDO_DEBUG] 获取 commit 绑定包失败: #{error_msg}"
+
+                        package_ids << package_id
                     end
-                    return []
                 end
+
+                puts "[PINDO_DEBUG] Commit #{commit_id[0..7]} 已绑定 #{package_ids.size} 个包: #{package_ids.inspect}" if ENV['PINDO_DEBUG']
+                package_ids.uniq
             rescue => e
-                # 异常时返回空数组，不阻止绑定流程
-                if ENV['PINDO_DEBUG']
-                    puts "[PINDO_DEBUG] 获取 commit 绑定包异常: #{e.message}"
-                    puts "[PINDO_DEBUG] Backtrace: #{e.backtrace[0..2].join("\n")}"
-                end
-                return []
+                Funlog.instance.fancyinfo_warning("查询 commit 已绑定的包异常: #{e.message}")
+                puts "[PINDO_DEBUG] Backtrace: #{e.backtrace[0..2].join("\n")}" if ENV['PINDO_DEBUG']
+                return nil
             end
         end
 
+        # 判断两个 commit SHA 是否指向同一个提交
+        #
+        # 一端是全长 40 位 SHA、另一端是短 SHA（或大小写不同）时，严格 == 会永不命中。
+        # 对覆盖式写入的 bind_commit 来说这不是「查不到」而是「查成空」，
+        # 会把该 commit 上已有的绑定一起删掉，因此按前缀 + 忽略大小写比对。
+        # 要求较短的一方至少 7 字符，避免过短或异常值产生误匹配。
+        #
+        # @param sha_a [String, nil] 待比较的 SHA
+        # @param sha_b [String, nil] 待比较的 SHA
+        # @return [Boolean] 是否同一个提交
+        def same_commit?(sha_a, sha_b)
+            a = sha_a.to_s.strip.downcase
+            b = sha_b.to_s.strip.downcase
+            return false if a.empty? || b.empty?
+
+            shorter, longer = a.length <= b.length ? [a, b] : [b, a]
+            return false if shorter.length < 7
+
+            longer.start_with?(shorter)
+        end
+
         # 获取工作流中已绑定的包 ID（已废弃，请使用 get_commit_bound_package_ids）
         #
         # @deprecated 使用 get_commit_bound_package_ids(commit_id:, workflow_id:) 替代
@@ -1984,10 +2070,11 @@ module Pindo
         # @param project_id [String] 项目 ID
         # @param workflow_id [Integer] 工作流 ID
         # @param commit_id [String] Git commit SHA
-        # @param branch [String] 分支名（可选，默认 'master'）
+        # @param branch [String, nil] 分支名（可选，nil 时不发送分支字段——传错的分支名
+        #   会让 commit 与分支错误关联，比不传更糟）
         # @param single [Boolean] 是否单个提交（可选，默认 true）
         # @return [Hash] 发送结果
-        def send_workflow_message(project_id:, workflow_id:, commit_id:, branch: 'master', single: true)
+        def send_workflow_message(project_id:, workflow_id:, commit_id:, branch: nil, single: true)
             if project_id.nil? || project_id.empty?
                 Funlog.instance.fancyinfo_error("project_id 不能为空")
                 return { success: false, error: "project_id 不能为空" }
@@ -2009,9 +2096,10 @@ module Pindo
                     workflowId: workflow_id,
                     params: {
                         single: single,
+                        # jpsclient 内部归一化为服务端要求的 branches 数组；nil 时不带该字段
                         branch: branch,
                         commitIds: [commit_id]
-                    }
+                    }.compact
                 )
 
                 # 兼容两种响应格式

data/lib/pindo/module/source_files_guard.rb

@@ -26,6 +26,12 @@ module Pindo
       '**/src/main/res'
     ].freeze
 
+    # Unity 工程判定即要求该文件存在（BuildHelper#unity_project?），故用精确路径而非 glob，
+    # 避免匹配到 Packages 下嵌入工程里的同名副本。
+    UNITY_PATTERNS = [
+      'ProjectSettings/ProjectSettings.asset'
+    ].freeze
+
     EXCLUDED_PATH_COMPONENTS = %w[
       .git
       .gradle
@@ -56,9 +62,12 @@ module Pindo
         source_paths(project_path, ANDROID_PATTERNS)
       end
 
-      # Unity 平台工程导出到已忽略的 GoodPlatform，不提交 Unity 源码配置。
-      def unity(_project_path)
-        []
+      # 导出的平台工程落在已忽略的 GoodPlatform 里，不需要提交。
+      # 但 ProjectSettings.asset 是 Unity 源码配置，构建期间会被 Unity 写入
+      # （版本号、编译宏等），性质与 iOS 的 project.pbxproj / Info.plist 相同，
+      # 不提交就会在构建后残留为未提交改动，且 tag 上拿不到构建实际用的配置。
+      def unity(project_path)
+        source_paths(project_path, UNITY_PATTERNS)
       end
 
       private

data/lib/pindo/module/task/model/git/git_commit_task.rb

@@ -122,6 +122,12 @@ module Pindo
         # skip_without_tag 模式：跳过所有 git 同步操作，直接返回
         if @process_type == Pindo::UncommittedFilesProcessType::SKIP_WITHOUT_TAG
           coding_branch = get_current_branch_name
+          # 该模式不合并分支，代码就停在当前分支上，随 task_param 传给工作流消息任务的
+          # 分支必须是当前分支——用默认的 master 或探测出的发布分支，会发出
+          # 「feature 分支的 commit + master 分支名」这种自相矛盾的组合。
+          # detached HEAD 时取不到分支名（current_branch_name 返回 nil），保持 nil，
+          # 让下游工作流消息不带分支发送，而不是把字面量 "HEAD" 当成分支名。
+          @release_branch = Pindo::GitHandler.current_branch_name(local_repo_dir: root_dir)
           @build_number, @commit_hash = git_repo_helper.get_build_number_from_commit(project_dir: root_dir)
 
           # 版本号仍按正常优先级计算，仅"不打 tag / 不升版本"，避免硬编码 0.0.0 污染 build.gradle 与下游上传参数

data/lib/pindo/module/task/model/git/git_tag_task.rb

@@ -78,13 +78,19 @@ module Pindo
 
           # 4. 创建并推送 Tag
           tag_name = "#{@tag_pre}#{@build_version}"
-          git_repo_helper.create_and_push_tag(
+          tag_result = git_repo_helper.create_and_push_tag(
             project_dir: root_dir,
             tag_name: tag_name,
             tag_type: @tag_type
           )
+
+          # 5. 固化 commit 快照：commit_build_changes 与分支合并都可能移动 HEAD，
+          # 下游绑定/消息任务必须拿到「tag 这一刻」的 commit，而不是它们读取时的 HEAD
+          capture_git_commit_info
+
+          tag_result
         ensure
-          # 5. 还原 stash
+          # 6. 还原 stash
           restore_stash(root_dir, stash_name) if stash_saved
         end
       end

data/lib/pindo/module/task/model/git_task.rb

@@ -25,6 +25,9 @@ module Pindo
         @build_number = nil
         @commit_hash = nil
 
+        # commit 信息快照（由子类在 do_work 中调用 capture_git_commit_info 固化）
+        @git_commit_info = nil
+
         # 通过 project_path 获取 git_root_path
         @git_root_path = @project_path ? Pindo::GitHandler.git_root_directory(local_repo_dir: @project_path) : nil
 
@@ -91,6 +94,24 @@ module Pindo
         Pindo::GitHandler.git!(%W(-C #{@git_root_path} rev-parse --abbrev-ref HEAD)).strip
       end
 
+      # 固化当前 HEAD 的 commit 信息快照
+      #
+      # build_task_param 默认在被读取时才去读 HEAD，若期间有其它任务移动了 HEAD
+      # （例如 GitTagTask 会提交构建注入文件），不同时刻读到的 commit 就不一致。
+      # 子类在 do_work 中调用本方法，即可把「任务完成那一刻」的 commit 固定下来。
+      def capture_git_commit_info
+        return unless @git_root_path
+
+        # 传入任务自身的 tag 前缀，自定义 --tag_pre 时才能正确识别 HEAD 上的版本 tag
+        info = Pindo::GitHandler.get_latest_conventional_commit(
+          project_dir: @git_root_path,
+          tag_prefix: @tag_pre
+        )
+        @git_commit_info = info if info && info[:commit_id]
+      rescue => e
+        Funlog.instance.fancyinfo_warning("固化 git commit 信息失败: #{e.message}")
+      end
+
       # 构建任务参数（供其他任务使用）
       def build_task_param
         return {} unless @status == TaskStatus::SUCCESS
@@ -110,8 +131,12 @@ module Pindo
         # 添加 git commit 信息（供 JPSUploadMediaTask 等任务使用）
         if @git_root_path
           begin
-            # 获取当前 HEAD commit 信息
-            git_commit_info = Pindo::GitHandler.get_latest_conventional_commit(project_dir: @git_root_path)
+            # 优先使用任务内固化的快照；没有快照时回退到读取当前 HEAD
+            git_commit_info = @git_commit_info ||
+                              Pindo::GitHandler.get_latest_conventional_commit(
+                                project_dir: @git_root_path,
+                                tag_prefix: @tag_pre
+                              )
             if git_commit_info
               param[:git_commit_id] = git_commit_info[:commit_id]
               param[:git_commit_time] = git_commit_info[:commit_time]

data/lib/pindo/module/task/model/jps/jps_bind_package_task.rb

@@ -27,8 +27,9 @@ module Pindo
       # @option options [String] :git_commit_time Git commit 时间（可选）
       # @option options [String] :git_commit_desc Git commit 描述（可选）
       # @option options [String] :project_dir 项目目录（可选，用于自动获取 commit 信息）
-      # @option options [Hash] :app_info_obj JPS 应用信息对象（可选，继承自基类）
-      # @option options [Hash] :workflow_info 工作流信息（可选，继承自基类）
+      # @option options [Hash] :app_info_obj JPS 应用信息对象（可选，继承自基类，本任务不使用）
+      # @option options [Hash] :workflow_info 工作流信息（必需，用于取 workflow_id；
+      #   回读绑定走 commit_log/preview，该接口以 workflowId 为入参）
       # @option options [String] :project_name 项目名称（可选，继承自基类）
       def initialize(app_version_list = nil, options = {})
         # 兼容性处理：如果传入的是单个 Hash，转为数组
@@ -48,6 +49,11 @@ module Pindo
         # 设置任务优先级为 LOW，确保在上传任务之后执行
         options[:priority] ||= TaskPriority::LOW
 
+        # 重试延迟加随机抖动：绑定是「读取 → 合并 → 覆盖」，两个进程冲突后若都按固定
+        # 延迟重试，会在同一时刻再次相撞。抖动只降低碰撞概率，消除不了竞态——
+        # 根治需要服务端提供原子追加或 CAS（见 do_work 里的说明）。
+        options[:retry_delay] ||= self.class.default_retry_delay + rand(0..4)
+
         super("绑定 包到Git工作流", options)
       end
 
@@ -136,8 +142,10 @@ module Pindo
           raise "无法登录 JPS，请检查配置"
         end
 
-        # 6. 获取工作流 ID
-        workflow_id = @workflow_info&.dig(:workflow_id) || @workflow_info&.dig('id')
+        # 6. 获取工作流 ID（commit_log/preview 的入参；绑定本身按 commitId 全局记录，
+        # 同项目下任一 workflowId 查到的 bindVersions 都相同）
+        workflow_id = @workflow_info&.dig(:workflow_id) || @workflow_info&.dig('workflow_id') ||
+                      @workflow_info&.dig(:id) || @workflow_info&.dig('id')
         unless workflow_id
           raise "缺少 workflow_info，无法获取 workflow_id"
         end
@@ -148,6 +156,12 @@ module Pindo
           workflow_id: workflow_id
         )
 
+        # 查询失败（nil）时中止：绑定接口是覆盖式写入，带着不完整的列表提交
+        # 会把该 commit 上已绑定的其它平台包冲掉。宁可报错让用户重试或补绑。
+        if existing_bound_ids.nil?
+          raise "无法确认 Commit #{@git_commit_id[0..7]} 已绑定的包，为避免覆盖丢失已中止绑定，请重试"
+        end
+
         if existing_bound_ids.any?
           puts "  📋 当前 Commit 已绑定的包: #{existing_bound_ids.size} 个"
         end
@@ -172,6 +186,20 @@ module Pindo
 
         if bind_result[:success]
           Funlog.instance.fancyinfo_success("绑定成功！")
+
+          # 10. 写后回读校验
+          #
+          # 已知限制：「查询 → 合并 → 覆盖」跨进程不是原子的，客户端消除不了这个竞态。
+          # bind_commit 的入参只有 {commitId, projectPackageIds}，既没有 revision/CAS
+          # 也没有追加语义，同项目下的其它接口同样不提供（已核对全部 project_package/
+          # commit_log 接口）。因此本校验只能发现「本次写入的包在回读时不见了」，
+          # 发现不了「本次写入覆盖掉了别人刚加的包」——后者要等对方回读时才暴露。
+          #
+          # 根治需要服务端支持，二选一即可：
+          #   1) bind_commit 增加 append 语义（只追加不覆盖）
+          #   2) 返回并校验 revision，做乐观并发控制
+          verify_bound_packages(pgyer_helper, workflow_id, merged_package_ids)
+
           puts ""
 
           {
@@ -193,6 +221,35 @@ module Pindo
 
       private
 
+      # 写后回读校验：确认期望绑定的包都在服务端的绑定列表里
+      #
+      # 查询失败时只告警不失败——包已经写进去了，回读失败不代表绑定失败。
+      # 只有确认「期望的包没在列表里」才判定为被并发覆盖，抛异常交给任务重试。
+      #
+      # @param pgyer_helper [PgyerHelper] 已登录的 helper
+      # @param workflow_id [Integer, String] 工作流 ID
+      # @param expected_ids [Array<String>] 本次写入的包 ID 列表
+      def verify_bound_packages(pgyer_helper, workflow_id, expected_ids)
+        actual_ids = pgyer_helper.get_commit_bound_package_ids(
+          commit_id: @git_commit_id,
+          workflow_id: workflow_id
+        )
+
+        if actual_ids.nil?
+          Funlog.instance.fancyinfo_warning("绑定后回读校验未能完成，请到 JPS 确认绑定结果")
+          return
+        end
+
+        missing_ids = expected_ids - actual_ids
+        return if missing_ids.empty?
+
+        # 抛出后由任务的重试机制重新走「查询 → 合并 → 写入」，对两种成因都收敛：
+        # 并发覆盖时会重新读到对方的包并一起写回；服务端写后读延迟时下一次读到的即是新值。
+        raise "绑定结果校验失败：#{missing_ids.size} 个包未出现在绑定列表中" \
+              "（其它进程同时绑定覆盖了本次结果，或服务端写入尚未可见），" \
+              "缺失包 ID: #{missing_ids.join(', ')}"
+      end
+
       # 从依赖任务获取 app_version_list
       def fetch_app_version_from_dependencies
         # 获取所有 JPSUploadTask 的数据（可能有多个平台的上传任务）
@@ -210,10 +267,8 @@ module Pindo
 
       # 从依赖任务获取或自动获取 git commit 信息
       def fetch_git_commit_info
-        # 1. 优先从 GitTagTask 依赖任务获取（打 tag 后的 commit 信息更准确）
-        git_data = get_data_param_by_key(:git_tag)
-        # 2. 降级到 GitCommitTask
-        git_data = get_data_param_by_key(:git_commit) if git_data.nil? || git_data.empty?
+        # 1. 从依赖任务获取（优先 GitTagTask，降级 GitCommitTask）
+        git_data = git_commit_data_param
 
         if git_data && git_data[:task_param]
           param = git_data[:task_param]
@@ -222,7 +277,7 @@ module Pindo
           @git_commit_desc = param[:git_commit_desc] if param[:git_commit_desc]
         end
 
-        # 3. 如果依赖任务都没有提供，且指定了 project_dir，使用自动获取
+        # 2. 如果依赖任务都没有提供，且指定了 project_dir，使用自动获取
         if (@git_commit_id.nil? || @git_commit_id.empty?) && @project_dir
           # 查找 git 仓库根目录
           git_root = Pindo::GitHandler.git_root_directory(local_repo_dir: @project_dir)

data/lib/pindo/module/task/model/jps/jps_upload_media_task.rb

@@ -33,12 +33,16 @@ module Pindo
       # @option options [Hash] :app_info_obj JPS 应用信息对象（可选，继承自基类）
       # @option options [Hash] :workflow_info 工作流信息（可选，继承自基类）
       # @option options [String] :project_name 项目名称（可选，继承自基类）
+      # @option options [Boolean] :required 用户是否显式要求上传媒体（默认 false）。
+      #   为 true 时找不到媒体文件会让任务失败；--bind/--send 隐式带出的媒体上传保持
+      #   宽松，因为「项目里没有 JPSMedia 文件」是常态，不该让整条构建失败。
       def initialize(file_paths, upload_path, options = {})
         @file_paths = file_paths || []                  # 要上传的文件路径列表
         @upload_path = upload_path                      # 项目路径
         @git_commit_id = options[:git_commit_id]        # Git commit SHA
         @git_commit_time = options[:git_commit_time]    # Git commit 时间
         @git_commit_desc = options[:git_commit_desc]    # Git commit 描述
+        @required = options.fetch(:required, false)     # 是否为用户显式要求
 
         # 设置任务优先级为 LOW，确保在其他任务之后执行
         options[:priority] ||= TaskPriority::LOW
@@ -97,10 +101,8 @@ module Pindo
 
         # 2. 如果没有提供 git_commit_id，尝试从依赖任务获取或自动获取
         if @git_commit_id.nil? || @git_commit_id.empty?
-          # 2.1 优先从 GitTagTask 依赖任务获取（打 tag 后的 commit 信息更准确）
-          git_data = get_data_param_by_key(:git_tag)
-          # 2.2 降级到 GitCommitTask
-          git_data = get_data_param_by_key(:git_commit) if git_data.nil? || git_data.empty?
+          # 2.1 从依赖任务获取（优先 GitTagTask，降级 GitCommitTask）
+          git_data = git_commit_data_param
 
           if git_data && git_data[:task_param]
             param = git_data[:task_param]
@@ -110,7 +112,7 @@ module Pindo
             @git_commit_desc = param[:git_commit_desc] if param[:git_commit_desc]
           end
 
-          # 2.3 如果依赖任务都没有提供，使用 get_latest_conventional_commit
+          # 2.2 如果依赖任务都没有提供，回退到读取当前仓库状态
           if @git_commit_id.nil? || @git_commit_id.empty?
             git_info = Pindo::GitHandler.get_latest_conventional_commit(project_dir: git_root)
             @git_commit_id = git_info[:commit_id]
@@ -154,6 +156,13 @@ module Pindo
           puts "  ❌ 没有找到有效的 media 文件"
           puts "  提示: 请在项目根目录创建 JPSMedia/ 目录并放入要上传的图片或视频文件"
           puts ""
+
+          # 用户显式传了 --media 却没有文件可传：任务系统只看异常不看 result[:success]，
+          # 这里不抛出的话命令会以 0 退出，等于悄悄没做用户要求的事
+          if @required
+            raise "没有找到有效的 media 文件；请在 JPSMedia/ 目录放入图片或视频后重试"
+          end
+
           return {
             success: false,
             success_urls: [],