net-connector 0.6.0 → 0.7.1

data/lib/net/connector/netdisco/inventory_budget.rb

@@ -23,21 +23,21 @@ module Net
         # 在追加正文前计数；不能靠 Content-Length 或 JSON 解析后的大小限制内存。
         def consume_bytes(size, response_bytes:)
           remaining
-          check_limit!(:max_response_bytes, response_bytes + size)
-          check_limit!(:max_inventory_bytes, @bytes + size)
+          validate_limit!(:max_response_bytes, response_bytes + size)
+          validate_limit!(:max_inventory_bytes, @bytes + size)
           @bytes += size
         end
 
         # 去重前的记录同样占用清单内存；兼容查询也使用这个累计计数。
         def consume_devices(size)
           remaining
-          check_limit!(:max_devices, @devices + size)
+          validate_limit!(:max_devices, @devices + size)
           @devices += size
         end
 
         private
 
-        def check_limit!(name, value)
+        def validate_limit!(name, value)
           return if value <= @options.fetch(name)
 
           raise Client::Error.new("Netdisco inventory exceeded #{name}", code: name), cause: nil

data/lib/net/connector/netdisco/plan.rb

@@ -4,15 +4,18 @@ module Net
   module Connector
     module Netdisco
       # 固定一份清单上的选择结果与跳过原因，供预览和执行复用。
-      Plan = Data.define(:mode, :inventory, :ready, :outcomes) do
+      Plan = Data.define(:mode, :inventory, :ready, :outcomes, :allow_fixed_name_reuse) do
         # Data 只冻结对象自身；这里复制并冻结可能由调用方修改的计划容器。
-        def initialize(mode:, inventory:, ready:, outcomes:)
+        def initialize(mode:, inventory:, ready:, outcomes:, allow_fixed_name_reuse: false)
           unless inventory.is_a?(Array) && ready.is_a?(Array) && outcomes.is_a?(Array)
             raise ArgumentError, "plan inventory, ready tasks, and outcomes must be Arrays"
           end
 
           tasks = ready.map { |task| task.is_a?(Array) ? task.dup.freeze : task }.freeze
-          super(mode: mode, inventory: inventory.dup.freeze, ready: tasks, outcomes: outcomes.dup.freeze)
+          raise ArgumentError, "allow_fixed_name_reuse must be boolean" unless [true, false].include?(allow_fixed_name_reuse)
+
+          super(mode: mode, inventory: inventory.dup.freeze, ready: tasks, outcomes: outcomes.dup.freeze,
+                allow_fixed_name_reuse: allow_fixed_name_reuse)
         end
 
         # 按清单顺序返回选中的设备。
@@ -26,7 +29,7 @@ module Net
           end
 
           selected_indices = {}
-          filenames = {}
+          selected_filenames = {}
           previous_index = -1
           ready.each do |task|
             unless task.is_a?(Array) && task.size == 2 && task.first.is_a?(Integer)
@@ -39,9 +42,11 @@ module Net
             end
             if mode == :tftp
               filename = device.tftp_filename
-              raise ArgumentError, "plan cannot upload multiple devices to one TFTP filename" if filenames.key?(filename)
+              if selected_filenames.key?(filename) && !(allow_fixed_name_reuse && device.vendor == :palo_alto)
+                raise ArgumentError, "plan cannot upload multiple devices to one TFTP filename"
+              end
 
-              filenames[filename] = true
+              selected_filenames[filename] = true
             end
             selected_indices[index] = true
             previous_index = index
@@ -51,7 +56,7 @@ module Net
             result = outcomes[index]
             next if selected_indices[index] && result.nil?
 
-            unless !selected_indices[index] && valid_skipped_outcome?(result, device, filenames)
+            unless !selected_indices[index] && valid_skipped_outcome?(result, device, selected_filenames)
               raise ArgumentError, "plan outcome does not match its inventory slot"
             end
           end
@@ -61,7 +66,7 @@ module Net
         private
 
         # 跳过结果不携带执行产物；文件冲突必须有本批次实际执行的目标作为依据。
-        def valid_skipped_outcome?(result, device, filenames)
+        def valid_skipped_outcome?(result, device, selected_filenames)
           return false unless result.is_a?(Outcome) && result.device.equal?(device) && result.backup.nil? &&
                               result.error_code.nil? && result.error_type.nil? &&
                               result.started_at.nil? && result.finished_at.nil?
@@ -69,7 +74,7 @@ module Net
           return result.status == device.issue unless device.ready?
 
           result.status == :sample_limit ||
-            (mode == :tftp && result.status == :remote_filename_collision && filenames.key?(device.tftp_filename))
+            (mode == :tftp && result.status == :remote_filename_collision && selected_filenames.key?(device.tftp_filename))
         end
       end
     end

data/lib/net/connector/netdisco/planner.rb

@@ -13,21 +13,23 @@ module Net
         end
 
         # 生成本地或 TFTP 备份计划，明确记录每台未执行设备的原因。
-        def call(mode:, limit_per_vendor:)
+        def call(mode:, limit_per_vendor:, allow_fixed_name_reuse: false)
           self.class.validate_limit!(limit_per_vendor)
-          candidates = @inventory.each_with_index.select { |device, _index| device.ready? }
-          selected = if limit_per_vendor
-                       candidates.group_by { |device, _index| device.vendor }.values.flat_map do |entries|
-                         entries.sort_by { |device, _index| device.host }.first(limit_per_vendor)
-                       end
-                     else
-                       candidates
-                     end
-          selected_indices = selected.to_h { |_device, index| [index, true] }
-          filenames = {}
+          ready_tasks = @inventory.each_with_index.filter_map do |device, index|
+            [index, device] if device.ready?
+          end
+          selected_tasks = if limit_per_vendor
+                             ready_tasks.group_by { |_index, device| device.vendor }.values.flat_map do |tasks|
+                               tasks.sort_by { |_index, device| device.host }.first(limit_per_vendor)
+                             end
+                           else
+                             ready_tasks
+                           end
+          selected_indices = selected_tasks.to_h { |index, _device| [index, true] }
+          first_index_by_filename = {}
           if mode == :tftp
             # 先按采样顺序保留每个目标的首台设备，再按清单顺序输出结果。
-            selected.each { |device, index| filenames[device.tftp_filename] ||= index }
+            selected_tasks.each { |index, device| first_index_by_filename[device.tftp_filename] ||= index }
           end
           outcomes = Array.new(@inventory.size)
           ready = @inventory.each_with_index.filter_map do |device, index|
@@ -37,14 +39,16 @@ module Net
             elsif !selected_indices.key?(index)
               outcomes[index] = skipped(device, :sample_limit)
               nil
-            elsif mode == :tftp && filenames.fetch(device.tftp_filename) != index
+            elsif mode == :tftp && first_index_by_filename.fetch(device.tftp_filename) != index &&
+                  !(allow_fixed_name_reuse && device.vendor == :palo_alto)
               outcomes[index] = skipped(device, :remote_filename_collision)
               nil
             else
               [index, device].freeze
             end
           end
-          Plan.new(mode: mode, inventory: @inventory, ready: ready.freeze, outcomes: outcomes.freeze)
+          Plan.new(mode: mode, inventory: @inventory, ready: ready.freeze, outcomes: outcomes.freeze,
+                   allow_fixed_name_reuse: allow_fixed_name_reuse)
         end
 
         # 限制单厂商采样数，空值表示选择所有就绪设备。

data/lib/net/connector/netdisco/progress.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+require "io/console"
+
+module Net
+  module Connector
+    module Netdisco
+      # 共享一个实例接收并发会话事件和任务回调；人类进度不混入 JSON 输出。
+      class Progress
+        def initialize(io: $stderr, enabled: true, verbose: false)
+          @io, @enabled, @verbose = io, enabled, verbose
+          @tty = io.respond_to?(:tty?) && io.tty?
+          @stages = {}
+          @task_started = {}
+          @failures = Hash.new(0)
+          @started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          @succeeded = @failed = @unverified = 0
+          @mutex = Mutex.new
+          @total = @completed = @active = 0
+        end
+
+        def reading_inventory
+          write(nil, "正在读取 Netdisco 设备清单")
+        end
+
+        def plan(plan, concurrency:, limit_per_vendor: nil)
+          @mutex.synchronize do
+            @total = plan.ready.size
+            @completed = @active = 0
+            @run_started = monotonic
+            mode = limit_per_vendor ? "抽样（每厂商最多 #{limit_per_vendor} 台）" : "全量"
+            emit(nil, "#{mode} | 清单 #{plan.inventory.size} 台；本次 #{@total} 台；跳过 #{plan.inventory.size - @total} 台；并发 #{concurrency}")
+          end
+        end
+
+        def start(device)
+          @mutex.synchronize do
+            @active += 1
+            @stages[device.host] = "登录"
+            @task_started[device.host] = monotonic
+            @verbose ? emit(device.host, "开始备份（#{device.vendor}）") : refresh
+          end
+        end
+
+        # 只显示已脱敏事件中的阶段和安全命令，不显示设备回显或异常原文。
+        def event(event)
+          return unless event.is_a?(Log::Event)
+
+          unless @verbose
+            @mutex.synchronize do
+              host = event.fields[:host]
+              @stages[host] = "采集" if @stages.key?(host) && event.name == "login_complete" && event.fields[:status] == "ok"
+              refresh
+            end
+            return
+          end
+
+          fields = event.fields
+          message = case event.name
+                    when "connect" then "正在连接并登录（#{fields[:protocol]}）"
+                    when "login_complete"
+                      fields[:status] == "ok" ? "登录成功" : "登录失败（#{fields[:code]}）"
+                    when "connect_failed" then "连接失败（#{fields[:code]}）"
+                    when "command_start" then "执行命令：#{fields[:text]}；等待响应"
+                    when "command_complete"
+                      fields[:status] == "response_received" ? "命令响应完成（#{fields[:duration_ms]} ms）" :
+                        "命令失败（#{fields[:code]}）"
+                    when "operation_complete"
+                      fields[:status] == "completed" ? "脚本处理完成" : "脚本处理失败（#{fields[:code]}）"
+                    end
+          write(fields[:host], message) if message
+        end
+
+        def result(outcome)
+          @mutex.synchronize do
+            @completed += 1
+            @active -= 1
+            @stages.delete(outcome.device.host)
+            @task_started.delete(outcome.device.host)
+            @failures[outcome.error_code || outcome.status] += 1 unless outcome.success?
+            outcome.success? ? @succeeded += 1 : @failed += 1
+            @unverified += 1 if outcome.status == :reported_uploaded && outcome.backup&.verification != :server_verified
+            message = case outcome.status
+                      when :backed_up then "备份已保存（#{outcome.backup.bytes} 字节）"
+                      when :reported_uploaded
+                        outcome.backup&.verification == :server_verified ? "配置已归档（#{outcome.backup.server_bytes} 字节）" :
+                          "设备报告上传完成；服务器文件尚未核验"
+                      when :saved_with_error then "备份有产物但未完全成功（#{outcome.error_code}）"
+                      when :reported_with_error then "设备报告上传但收尾异常（#{outcome.error_code}）"
+                      else "未完成（#{outcome.error_code || outcome.status}）"
+                      end
+            hint = failure_hint(outcome.error_code)
+            message = "#{message}；#{hint}" if hint
+            if @verbose || !outcome.success?
+              emit(outcome.device.host, "#{message}；耗时 #{outcome.duration_ms} ms")
+            elsif !@tty && ((@completed % 25).zero? || @completed == @total)
+              emit(nil, status_line)
+            end
+            refresh
+          end
+        end
+
+        def finish(report)
+          summary = report.summary
+          failures = report.outcomes.reject { |item| item.success? || %i[filtered sample_limit].include?(item.status) }
+                           .group_by { |item| item.error_code || item.status }.transform_values(&:size)
+          unless failures.empty?
+            write(nil, "未完成分类：#{failures.sort_by { |code, count| [-count, code.to_s] }.map { |code, count| "#{code}=#{count}" }.join("，")}")
+          end
+          write(nil, "批次结束：成功 #{summary[:succeeded]}，部分成功 #{summary[:partial]}，失败 #{summary[:failed]}，跳过 #{summary[:skipped]}；耗时 #{(Process.clock_gettime(Process::CLOCK_MONOTONIC) - @started_at).round(1)} 秒；结果 #{report.policy_success? ? "完成" : "未完成"}")
+          unverified = summary[:verification]&.fetch(:unverified, 0) || 0
+          write(nil, "其中 #{unverified} 台仅设备报告上传完成，服务器文件尚未核验") if unverified.positive?
+          return unless !report.callback_errors.empty? || report.report_error
+
+          write(nil, "回调异常 #{report.callback_errors.size}，报告错误 #{report.report_error || "无"}")
+        end
+
+        # 心跳只负责显示；退出、异常或中断时先唤醒并回收线程。
+        def with_updates
+          return yield unless @enabled && @tty && !@verbose
+
+          lock = Mutex.new
+          signal = ConditionVariable.new
+          stopped = false
+          worker = Thread.new do
+            loop do
+              stop = lock.synchronize do
+                signal.wait(lock, 1) unless stopped
+                stopped
+              end
+              break if stop
+
+              tick
+            end
+          end
+          yield
+        ensure
+          if worker
+            lock.synchronize { stopped = true; signal.broadcast }
+            worker.value
+            @mutex.synchronize { clear_refresh }
+          end
+        end
+
+        def tick
+          @mutex.synchronize { refresh(force: true) }
+        end
+
+        def location(path)
+          write(nil, "报告：#{path}")
+        end
+
+        private
+
+        def failure_hint(code)
+          case code
+          when :authentication_failed then "设备拒绝认证，请核对账号、密码或 AAA 策略"
+          when :authentication_error then "认证交互未完成，请核对认证方式或设备 AAA 日志"
+          when :host_key_untrusted then "主机密钥尚未信任，请确认指纹并登记"
+          when :host_key_changed then "已登记主机密钥发生变化，请核实设备身份"
+          when :login_timeout then "未在期限内获得登录提示，请检查 SSH 握手与登录交互"
+          when :connection_timeout then "SSH 连接或握手超时，请检查服务与网络"
+          when :device_error then "设备拒绝命令，请核对厂商映射和账号权限"
+          end
+        end
+
+        def status_line
+          percent = @total.positive? ? @completed * 100 / @total : 0
+          "#{@completed}/#{@total} #{percent}% | 成功 #{@succeeded} 未完成 #{@failed} | 登录 #{@stages.values.count("登录")} 采集 #{@stages.values.count("采集")} 排队 #{[@total - @completed - @active, 0].max}"
+        end
+
+        def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        def duration(seconds)
+          total = seconds.round
+          format("%02d:%02d:%02d", total / 3600, total / 60 % 60, total % 60)
+        end
+
+        def timing_line
+          elapsed = [monotonic - (@run_started || @started_at), 0].max
+          rate = elapsed.positive? ? @completed / elapsed : 0
+          eta = if @completed == @total && @total.positive?
+                  "00:00:00"
+                elsif @completed >= 5 && rate.positive?
+                  "约 #{duration((@total - @completed) / rate)}"
+                else
+                  "估算中"
+                end
+          line = "耗时 #{duration(elapsed)} | #{format("%.1f", rate)} 台/秒 | 剩余 #{eta}"
+          host, started = @task_started.min_by { |_key, value| value }
+          if started && monotonic - started >= 10
+            line += " | 最久 #{host} #{@stages[host]} #{(monotonic - started).floor}s"
+          end
+          line
+        end
+
+        def refresh(force: false)
+          return unless @enabled && @tty && !@verbose
+
+          now = monotonic
+          return if !force && @refreshing && @completed < @total && @last_refresh && now - @last_refresh < 0.2
+
+          @last_refresh = now
+          divider = fit_terminal("-" * 100)
+          lines = [divider, fit_terminal(status_line), fit_terminal(timing_line), divider]
+          return if @refreshing && @last_status == lines
+
+          clear_refresh
+          @last_status = lines
+          @io.write(lines.join("\n"))
+          @io.flush
+          @refreshing = true
+        end
+
+        # 留一列避免终端自动换行，窄窗口也不会留下旧进度行。
+        def fit_terminal(line)
+          columns = @io.respond_to?(:winsize) ? @io.winsize.last : 120
+          columns = 120 unless columns.positive?
+          width = 0
+          text = line.gsub(/[[:cntrl:]]/, " ")
+          text.each_char.take_while do |character|
+            width += character.ord > 255 ? 2 : 1
+            width < columns
+          end.join
+        rescue IOError, SystemCallError
+          line
+        end
+
+        def clear_refresh
+          return unless @refreshing
+
+          @io.write("\r\e[2K" + ("\e[1A\r\e[2K" * (@last_status.length - 1)))
+          @refreshing = false
+        end
+
+        def write(host, message)
+          @mutex.synchronize { emit(host, message) }
+        end
+
+        def emit(host, message)
+          return unless @enabled
+
+          percent = @total.positive? ? " #{(@completed * 100.0 / @total).floor}%" : ""
+          clear_refresh
+          line = "[#{Time.now.strftime("%H:%M:%S")}] [#{@completed}/#{@total}#{percent} 执行中 #{@active}] [#{host || "批次"}] #{message}"
+          line = "[#{Time.now.strftime("%H:%M:%S")}] #{host ? "#{host}  " : ""}#{message}" unless @verbose
+          @io.write(line.gsub(/[[:cntrl:]]/, " ") + "\n")
+          @io.flush
+        end
+      end
+    end
+  end
+end

data/lib/net/connector/netdisco/report/files.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "text"
+
+module Net
+  module Connector
+    module Netdisco
+      class Report
+        # 示例与批次入口共享唯一摘要结构；保存结果先于终端成功提示。
+        class Files
+          def self.write(report, directory:, plan:, concurrency:)
+            destination = File.join(directory, "summary.json")
+            finalized = report.with(report_location: destination)
+            Text.write(directory: directory, report: finalized, plan: plan, concurrency: concurrency)
+            Storage::PrivateFile.write(destination, JSON.pretty_generate(finalized.summary))
+            finalized
+          rescue StandardError => error
+            location = if Storage::PrivateFile.receipt_error?(error) && error.receipt.committed? && error.receipt.path == destination
+                         destination
+                       end
+            failed = report.with_report_error(error, location: location)
+            begin
+              saved = failed.with(report_location: destination)
+              Storage::PrivateFile.write(destination, JSON.pretty_generate(saved.summary))
+              failed = saved
+            rescue StandardError
+              # JSON 仍无法保存时，返回带有已知提交位置的失败报告。
+            end
+            begin
+              Text.write(directory: directory, report: failed, plan: plan, concurrency: concurrency)
+            rescue StandardError
+              # 文本输出不能覆盖首次保存失败。
+            end
+            failed
+          end
+        end
+      end
+    end
+  end
+end

data/lib/net/connector/netdisco/report/text.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "../../storage/private_file"
+require_relative "../report"
+
+module Net
+  module Connector
+    module Netdisco
+      class Report
+        # 将批次结果写为人类可读的文本摘要。
+        class Text
+          def self.write(directory:, report:, plan:, concurrency:)
+            summary = report.summary
+            failed = report.outcomes.reject { |item| item.success? || %i[filtered sample_limit].include?(item.status) }
+            groups = failed.group_by { |item| item.error_code || item.status }
+            lines = ["网络设备备份报告", "=" * 72,
+                     "开始时间：#{report.started_at.getlocal("+08:00").strftime("%Y-%m-%d %H:%M:%S %:z")}",
+                     "结束时间：#{report.finished_at.getlocal("+08:00").strftime("%Y-%m-%d %H:%M:%S %:z")}",
+                     "清单：#{plan.inventory.size} 台；本次：#{plan.ready.size} 台；并发：#{concurrency}",
+                     "成功：#{summary[:succeeded]}；部分成功：#{summary[:partial]}；失败：#{summary[:failed]}；跳过：#{summary[:skipped]}",
+                     "耗时：#{(report.duration_ms.to_f / 1000).round(1)} 秒；批次状态：#{summary[:status]}",
+                     "成功策略：#{report.policy}；策略通过：#{report.policy_success?}",
+                     "回调异常：#{report.callback_errors.size}；报告错误：#{report.report_error || "无"}",
+                     "状态计数：#{report.counts.map { |key, value| "#{key}=#{value}" }.join("，")}",
+                     "未完成分类：#{groups.empty? ? "无" : groups.map { |key, items| "#{key}=#{items.size}" }.join("，")}",
+                     "-" * 72, "未完成设备："]
+            lines.concat(failure_lines(failed))
+            lines << "无" if failed.empty?
+            lines << "TFTP 成功仅表示设备报告上传完成；服务器文件核验结果请查看 summary.json。" if report.mode == :tftp
+            lines += ["=" * 72, "备份目录：#{directory}", "完整明细：#{File.join(directory, "summary.json")}"]
+            Net::Connector::Storage::PrivateFile.write(File.join(directory, "summary.txt"), lines.join("\n") + "\n")
+          end
+
+          def self.failure_lines(failed)
+            failed.map do |item|
+              label = item.device.name.to_s.gsub(/[[:cntrl:]]/, " ")
+              "#{item.device.host} | #{label} | #{item.status} | #{item.error_code || "无错误码"} | #{item.duration_ms} ms"
+            end
+          end
+          private_class_method :failure_lines
+        end
+      end
+    end
+  end
+end

data/lib/net/connector/netdisco/report.rb

@@ -9,21 +9,21 @@ module Net
       # 唯一的批量报告契约，分开呈现成功策略、清单覆盖和受控诊断。
       class Report
         extend Forwardable
-        SUCCESS = %i[backed_up reported_uploaded].freeze
-        ATTEMPTED = [*SUCCESS, :failed, :saved_with_error, :reported_with_error].freeze
-        IGNORABLE = %i[filtered sample_limit].freeze
-        private_constant :SUCCESS, :ATTEMPTED, :IGNORABLE
+        SUCCESS_STATUSES = %i[backed_up reported_uploaded].freeze
+        ATTEMPTED_STATUSES = [*SUCCESS_STATUSES, :failed, :saved_with_error, :reported_with_error].freeze
+        IGNORABLE_STATUSES = %i[filtered sample_limit].freeze
+        private_constant :SUCCESS_STATUSES, :ATTEMPTED_STATUSES, :IGNORABLE_STATUSES
 
-        attr_reader :batch, :policy, :duration_ms, :report_diagnostic
+        attr_reader :batch, :policy, :duration_ms, :report_diagnostic, :log_directory
         def_delegators :@batch, *Batch.members, :success?, :status, :counts
 
         def self.validate_policy!(policy)
-          raise ArgumentError, "success_policy must be strict or selected" unless %i[strict selected].include?(policy)
+          raise ArgumentError, "success_policy must be strict, selected or verified" unless %i[strict selected verified].include?(policy)
 
           policy
         end
 
-        def initialize(batch, policy: :strict, duration_ms: nil, report_diagnostic: nil)
+        def initialize(batch, policy: :strict, duration_ms: nil, report_diagnostic: nil, log_directory: nil)
           self.class.validate_policy!(policy)
           raise ArgumentError, "report requires a Batch" unless batch.instance_of?(Batch)
           unless duration_ms.nil? || (duration_ms.is_a?(Numeric) && duration_ms.real? && duration_ms.finite? && duration_ms >= 0)
@@ -33,6 +33,8 @@ module Net
             raise ArgumentError, "report_diagnostic must be a Diagnostic"
           end
 
+          raise ArgumentError, "verified policy requires TFTP mode" if policy == :verified && batch.mode != :tftp
+          @log_directory = log_directory&.dup&.freeze
           @batch, @policy, @duration_ms, @report_diagnostic = batch, policy, duration_ms, report_diagnostic
           freeze
         end
@@ -42,32 +44,36 @@ module Net
           return batch.success? if policy == :strict
           return false unless callback_errors.empty? && report_error.nil?
 
-          outcomes.any? { |item| SUCCESS.include?(item.status) } &&
-            outcomes.all? { |item| SUCCESS.include?(item.status) || IGNORABLE.include?(item.status) }
+          return false if policy == :verified && outcomes.any? { |outcome| outcome.success? && !server_verified?(outcome) }
+
+          outcomes.any? { |outcome| SUCCESS_STATUSES.include?(outcome.status) } &&
+            outcomes.all? { |outcome| SUCCESS_STATUSES.include?(outcome.status) || IGNORABLE_STATUSES.include?(outcome.status) }
         end
 
         def with(**attributes)
           self.class.new(batch.with(**attributes), policy: policy, duration_ms: duration_ms,
-                          report_diagnostic: report_diagnostic)
+                          report_diagnostic: report_diagnostic, log_directory: log_directory)
         end
 
         def with_report_error(error, location: nil)
           diagnostic = Diagnostic.from(error, phase: :report)
           self.class.new(batch.with(report_location: location, report_error: diagnostic.error_type),
-                          policy: policy, duration_ms: duration_ms, report_diagnostic: diagnostic)
+                          policy: policy, duration_ms: duration_ms, report_diagnostic: diagnostic, log_directory: log_directory)
         end
 
         # 手工构造的批次同样经过诊断白名单，不序列化任意异常内容。
         def summary
-          data = batch_summary
-          data.merge(
+          batch_data = batch_summary
+          batch_data.merge(
             schema_version: 2, policy: policy, policy_success: policy_success?, duration_ms: duration_ms,
-            coverage: { complete: !outcomes.empty? && outcomes.all? { |item| ATTEMPTED.include?(item.status) },
-                        attempted: outcomes.count { |item| ATTEMPTED.include?(item.status) },
-                        skipped: outcomes.count { |item| !ATTEMPTED.include?(item.status) } },
-            devices: device_summaries(data.fetch(:devices)),
+            coverage: { complete: !outcomes.empty? && outcomes.all? { |outcome| ATTEMPTED_STATUSES.include?(outcome.status) },
+                        attempted: outcomes.count { |outcome| ATTEMPTED_STATUSES.include?(outcome.status) },
+                        skipped: outcomes.count { |outcome| !ATTEMPTED_STATUSES.include?(outcome.status) } },
+            devices: device_summaries(batch_data.fetch(:devices)),
             callback_errors: callback_errors.map { |entry| { host: entry[:host], error_type: ErrorMetadata.type(entry[:error_type]) } },
             report_location: report_location, report_error: ErrorMetadata.type(report_error),
+            verification: mode == :tftp ? { verified: outcomes.count { |outcome| server_verified?(outcome) },
+                                            unverified: outcomes.count { |outcome| outcome.backup.is_a?(TftpReceipt) && !server_verified?(outcome) } } : nil,
             report_diagnostic: report_diagnostic&.to_h
           )
         end
@@ -83,28 +89,44 @@ module Net
             total: outcomes.size,
             succeeded: outcomes.count(&:success?),
             partial: outcomes.count(&:partial?),
-            failed: outcomes.count { |item| item.status == :failed },
+            failed: outcomes.count { |outcome| outcome.status == :failed },
             skipped: outcomes.count(&:skipped?),
             counts: counts,
             callback_errors: callback_errors,
-            devices: outcomes.map do |item|
-              { host: item.device.host || item.device.source_ip, name: item.device.name,
-                vendor: item.device.vendor,
-                status: item.status, path: item.backup&.path,
-                bytes: item.backup.is_a?(Backup) ? item.backup.bytes : nil,
-                sha256: item.backup.is_a?(Backup) ? item.backup.sha256 : nil,
-                change: item.backup.is_a?(Backup) ? item.backup.change : nil,
-                previous_sha256: item.backup.is_a?(Backup) ? item.backup.previous_sha256 : nil,
-                started_at: item.started_at&.iso8601, finished_at: item.finished_at&.iso8601,
-                duration_ms: item.duration_ms,
-                error_code: item.error_code, error_type: item.error_type }
+            devices: outcomes.map do |outcome|
+              { host: outcome.device.host || outcome.device.source_ip, name: outcome.device.name,
+                vendor: outcome.device.vendor,
+                status: outcome.status, path: outcome.backup&.path,
+                bytes: outcome.backup.is_a?(Backup) ? outcome.backup.bytes : nil,
+                sha256: outcome.backup.is_a?(Backup) ? outcome.backup.sha256 : nil,
+                change: outcome.backup.is_a?(Backup) ? outcome.backup.change : nil,
+                previous_sha256: outcome.backup.is_a?(Backup) ? outcome.backup.previous_sha256 : nil,
+                started_at: outcome.started_at&.iso8601, finished_at: outcome.finished_at&.iso8601,
+                duration_ms: outcome.duration_ms,
+                error_code: outcome.error_code, error_type: outcome.error_type }
             end
           }
         end
 
+        def server_verified?(outcome)
+          outcome.backup.is_a?(TftpReceipt) && outcome.backup.verification == :server_verified
+        end
+
+        def tftp_summary(outcome)
+          receipt = outcome.backup if outcome.backup.is_a?(TftpReceipt)
+          { remote_path: receipt&.path, server: receipt&.server,
+            configuration_kind: receipt&.configuration_kind, source_file: receipt&.source_file,
+            format: receipt&.format, verification: receipt&.verification,
+            server_file_verified: server_verified?(outcome), server_sha256: receipt&.server_sha256,
+            local_file: receipt&.local_path, server_archive_file: receipt&.archive_path,
+            bytes: receipt&.server_bytes, sha256: receipt&.server_sha256 }
+        end
+
         def device_summaries(entries)
-          entries.zip(outcomes).map do |entry, item|
-            diagnostic = item.diagnostic || Diagnostic.new(error_code: item.error_code, error_type: item.error_type)
+          entries.zip(outcomes).map do |entry, outcome|
+            diagnostic = outcome.diagnostic || Diagnostic.new(error_code: outcome.error_code, error_type: outcome.error_type)
+            entry = entry.merge(tftp_summary(outcome)) if mode == :tftp
+            entry[:session_log] = File.join(log_directory, "#{outcome.device.host.tr(":", "_")}.log") if log_directory && outcome.device.host && outcome.started_at
             entry.merge(error_code: diagnostic.error_code, error_type: diagnostic.error_type,
                         diagnostic: diagnostic.to_h.except(:error_code, :error_type))
           end

data/lib/net/connector/netdisco/result_store.rb

@@ -10,7 +10,7 @@ module Net
     module Netdisco
       module ResultStore
         # 每批保存一份私有 JSON 报告，通过重命名防止半写文件。
-        class Text
+        class Json
           # 以临时文件和重命名原子写入私有 JSON 报告。
           def write(batch, directory:)
             destination = File.expand_path(directory)
@@ -21,6 +21,8 @@ module Net
           end
         end
 
+        Text = Json # Compatibility with the former name of the JSON writer.
+
         # 数据库仓储由调用方提供，可使用 Active Record 或其他对象。
         # 仓储须实现 create!，本项目不负责数据库表结构。
         class Database