net-connector 0.4.1 → 0.4.2

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Net
+  module Connector
+    module Netdisco
+      # 报告是新的诊断通道：只接受固定词表，不展开异常消息、调用栈、命令、source 或 line。
+      Diagnostic = Data.define(:error_code, :error_type, :phase, :underlying_type,
+                               :artifact_state, :artifact_phase, :verification)
+
+      class Diagnostic
+        CONNECTOR_TYPES = %w[Error ConnectionError AuthenticationError LoginTimeout CommandTimeout WriteTimeout
+                             PromptError ConnectionClosed TransportError DeviceError ScriptError InternalError
+                             OutputLimitExceeded ScriptOutputLimitExceeded SessionBusy UnsupportedOperation LogError ParsingError BackupBusy
+                             BackupPersistenceError TftpCompletionError SavedConfigChanged].freeze
+        TYPES = (CONNECTOR_TYPES.map { |name| "Net::Connector::#{name}" } +
+          %w[StandardError RuntimeError ArgumentError TypeError IOError EOFError SystemCallError ThreadError
+             RangeError KeyError IndexError NoMethodError NameError FrozenError NotImplementedError
+             Timeout::Error IO::TimeoutError Errno::EIO Errno::EACCES Errno::EPERM Errno::ENOSPC Errno::EROFS
+             Errno::ENOENT Errno::ENOTDIR Errno::EISDIR Errno::ELOOP Errno::EINVAL Errno::ENOSYS
+             Errno::ENOTSUP Errno::EOPNOTSUPP Errno::ETIMEDOUT Errno::ECONNREFUSED Errno::ECONNRESET
+             Net::Connector::Operations::PrivateFile::WriteError
+             Net::Connector::Operations::PrivateFile::PersistenceError
+             Net::Connector::Operations::PrivateFile::DirectorySyncUnsupported]).freeze
+        CODES = (CONNECTOR_TYPES.map { |name| name.gsub(/([a-z])([A-Z])/, '\1_\2').downcase.to_sym } +
+          %i[authentication_failed connection_failed connection_refused no_route connection_reset
+             connection_timeout host_key_changed host_key_untrusted rsa_too_small unsupported_cipher
+             ambiguous_description ambiguous_neighbor confirmation_required description_stages_unsupported
+             description_unconfirmed description_unsupported incomplete_configuration interface_missing
+             neighbor_discovery_unsupported parse_failed invalid_output_encoding persistence_unconfirmed stale_plan startup_config_missing
+             template_invalid template_missing template_unreadable transfer_failed transfer_finalize_failed
+             transfer_path_mismatch transfer_path_unconfirmed transfer_unconfirmed uncommitted_configuration
+             unrecognized_output unsupported_configuration_format verification_plan_changed candidate_isolation_unavailable
+             backup_durability_unsupported backup_finalize_failed backup_persistence_unconfirmed
+             file_finalize_failed file_persistence_unconfirmed file_write_failed directory_sync_unsupported]).freeze
+        PHASES = %i[connect login enable command script read write close logging backup collect discover parse
+                    plan apply verify persist tftp_backup report callback].freeze
+        ARTIFACT_STATES = %i[not_committed committed durable reported_uploaded].freeze
+        ARTIFACT_PHASES = %i[resolve_parent temporary_file write file_sync rename directory_open directory_sync
+                            cleanup complete path finalize].freeze
+        private_constant :CONNECTOR_TYPES, :TYPES, :CODES, :PHASES, :ARTIFACT_STATES, :ARTIFACT_PHASES
+
+        # 包括手工构造的结果在内，v2 都不能携带自由文本诊断值。
+        def initialize(error_code: nil, error_type: nil, phase: nil, underlying_type: nil,
+                       artifact_state: nil, artifact_phase: nil, verification: nil)
+          super(error_code: CODES.include?(error_code) ? error_code : nil,
+                error_type: self.class.type(error_type), phase: PHASES.include?(phase) ? phase : nil,
+                underlying_type: self.class.type(underlying_type),
+                artifact_state: ARTIFACT_STATES.include?(artifact_state) ? artifact_state : nil,
+                artifact_phase: ARTIFACT_PHASES.include?(artifact_phase) ? artifact_phase : nil,
+                verification: verification == :device_reported ? verification : nil)
+        end
+
+        def self.type(name)
+          return if name.nil?
+
+          name.instance_of?(String) && TYPES.include?(name) ? name.dup.freeze : "StandardError"
+        end
+
+        # 读取已知错误的白名单属性后立即丢弃异常引用，不把回调对象保留进批次。
+        def self.from(error, backup: nil, phase: nil)
+          return unless error
+
+          fields = { error_type: type(error.class.name) || "StandardError", phase: phase }
+          if error.is_a?(Net::Connector::Error)
+            fields.merge!(error_code: error.code, phase: phase || error.phase)
+            fields[:underlying_type] = error.underlying.type if error.underlying.instance_of?(UnderlyingError)
+          end
+          new(**fields.merge(completion_fields(error, backup, phase)))
+        rescue StandardError
+          new(error_type: "StandardError", phase: phase)
+        end
+
+        def self.completion_fields(error, backup, phase)
+          if error.instance_of?(BackupPersistenceError) && backup.instance_of?(Backup) && error.backup.equal?(backup)
+            { artifact_state: error.receipt.state, artifact_phase: error.receipt.phase,
+              underlying_type: error.underlying_type }
+          elsif error.instance_of?(TftpCompletionError) && backup.instance_of?(TftpBackup) && error.transfer.equal?(backup)
+            { artifact_state: :reported_uploaded, artifact_phase: error.code == :transfer_finalize_failed ? :finalize : :path,
+              verification: :device_reported, underlying_type: error.underlying_type }
+          elsif phase == :report && Operations::PrivateFile.receipt_error?(error)
+            { error_code: error.code, artifact_state: error.receipt.state, artifact_phase: error.receipt.phase,
+              underlying_type: error.underlying_type }
+          else
+            {}
+          end
+        end
+        private_class_method :completion_fields
+      end
+    end
+  end
+end

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

@@ -8,90 +8,117 @@ module Net
     module Netdisco
       # 基于已验证的清单快照组织有上限的并发备份。
       class Fleet
+        DEFAULT_SETTING = Object.new.freeze
+        private_constant :DEFAULT_SETTING
+
         # 组装清单客户端、规则、凭据与结果存储。
         def initialize(client: nil, settings: Settings.new, rules: nil, credentials: nil, connector_factory: nil,
                        result_store: ResultStore::Text.new)
           @settings = settings
-          @client = client || settings.client
-          @rules = rules || settings.rules
-          @credentials = credentials || settings.method(:credentials_for)
+          @client = client
+          @rules = rules
+          @credentials = credentials
           @connector_factory = connector_factory || ->(device, connection_settings) { device.connector(**connection_settings) }
           @result_store = result_store
-          raise ArgumentError, "credentials must respond to call" unless @credentials.respond_to?(:call)
+          raise ArgumentError, "credentials must respond to call" if @credentials && !@credentials.respond_to?(:call)
           raise ArgumentError, "result_store must respond to write" if result_store && !result_store.respond_to?(:write)
         end
 
         # 拉取并标记重复管理地址的设备清单。
         def devices
-          rows = @client.devices
-          raise Client::Error, "Netdisco returned an invalid device inventory" unless rows.is_a?(Array)
-
-          devices = rows.map { |row| Device.from_row(row, rules: @rules) }
-          duplicates = devices.group_by(&:host).reject { |host, entries| host.nil? || entries.size == 1 }
-          devices.map do |device|
-            duplicates.key?(device.host) ? device.with(issue: :duplicate_host) : device
-          end.freeze
+          inventory(@settings.snapshot(mode: :inventory))
         end
 
         # 规划本地配置备份的设备集合。
         def plan_backup(limit_per_vendor: nil)
-          Planner.new(devices).call(mode: :backup, limit_per_vendor: limit_per_vendor)
+          build_plan(:backup, limit_per_vendor, @settings.snapshot(mode: :backup))
         end
 
         # 规划 TFTP 配置备份的设备集合。
         def plan_tftp_backup(limit_per_vendor: 5)
-          Planner.new(devices).call(mode: :tftp, limit_per_vendor: limit_per_vendor)
+          build_plan(:tftp, limit_per_vendor, @settings.snapshot(mode: :tftp))
         end
 
         # 先拉取完整清单，再并发采集并保存设备配置。
-        def backup_all(directory: @settings.backup_directory, concurrency: @settings.concurrency,
-                       limit_per_vendor: nil, plan: nil, on_start: nil, on_result: nil, on_change: nil)
+        def backup_all(directory: DEFAULT_SETTING, concurrency: DEFAULT_SETTING,
+                       limit_per_vendor: nil, plan: nil, on_start: nil, on_result: nil, on_change: nil,
+                       success_policy: :strict, report_schema: nil)
+          reporting = Report.options(policy: success_policy, schema: report_schema)
+          policy = @settings.snapshot(mode: :backup)
+          directory = policy.backup_directory if directory.equal?(DEFAULT_SETTING)
+          concurrency = policy.concurrency if concurrency.equal?(DEFAULT_SETTING)
           raise ArgumentError, "directory must be a nonempty String" unless directory.is_a?(String) && !directory.empty?
+          Worker.new(concurrency: concurrency)
           Planner.validate_limit!(limit_per_vendor)
           validate_callback!(on_result, :on_result)
           validate_callback!(on_start, :on_start)
           validate_callback!(on_change, :on_change)
 
-          plan ||= plan_backup(limit_per_vendor: limit_per_vendor)
+          plan ||= build_plan(:backup, limit_per_vendor, policy)
           validate_plan!(plan, :backup)
           callbacks = [on_result]
           callbacks << ->(item) { on_change.call(item) if item.backup.is_a?(Backup) && item.backup.changed? } if on_change
           target_directory = File.expand_path(directory)
+          saved_config = Operations::SavedConfig.new(directory: target_directory, indexed: true)
           run_batch(:backup, plan, concurrency: concurrency, report_directory: directory,
-                   output_directory: target_directory, on_start: on_start, on_result: callbacks.compact) do |device, log_directory|
-            backup_one(device, target_directory, log_directory)
+                    output_directory: target_directory, policy: policy, reporting: reporting,
+                    on_start: on_start, on_result: callbacks.compact) do |device, log_directory|
+            backup_one(device, target_directory, log_directory, policy, saved_config)
           end
         end
 
         # 让设备主动导出配置，在执行前检查同批目标文件名冲突。
-        def tftp_backup_all(server:, source_files: {}, concurrency: @settings.concurrency,
+        def tftp_backup_all(server:, source_files: {}, concurrency: DEFAULT_SETTING,
                             limit_per_vendor: 5, vrfs: {}, on_start: nil, on_result: nil, plan: nil,
-                            report_directory: @settings.backup_directory)
-          TftpTarget.new(host: server, path: "preflight.cfg")
+                            report_directory: DEFAULT_SETTING, success_policy: :strict, report_schema: nil)
+          reporting = Report.options(policy: success_policy, schema: report_schema)
+          policy = @settings.snapshot(mode: :tftp)
+          concurrency = policy.concurrency if concurrency.equal?(DEFAULT_SETTING)
+          report_directory = policy.backup_directory if report_directory.equal?(DEFAULT_SETTING)
+          Worker.new(concurrency: concurrency)
+          server = TftpTarget.new(host: server, path: "preflight.cfg").host
           raise ArgumentError, "source_files must be a Hash" unless source_files.is_a?(Hash)
           source_files.each_value { |source_file| TftpTarget.validate_source_file!(source_file) }
-          validate_vrfs!(vrfs)
+          source_files = source_files.transform_values { |value| value.dup.freeze }.freeze
+          vrfs = Settings.validate_vrfs!(vrfs).transform_values { |value| value.dup.freeze }.freeze
           Planner.validate_limit!(limit_per_vendor)
           validate_callback!(on_result, :on_result)
           validate_callback!(on_start, :on_start)
 
-          plan ||= plan_tftp_backup(limit_per_vendor: limit_per_vendor)
+          plan ||= build_plan(:tftp, limit_per_vendor, policy)
           validate_plan!(plan, :tftp)
           run_batch(:tftp, plan, concurrency: concurrency, report_directory: report_directory,
-                    on_start: on_start, on_result: on_result) do |device, log_directory|
-            tftp_backup_one(device, server, source_files, log_directory, vrfs)
+                    policy: policy, reporting: reporting, on_start: on_start, on_result: on_result) do |device, log_directory|
+            tftp_backup_one(device, server, source_files, log_directory, vrfs, policy)
           end
         end
 
         private
 
+        # 策略在清单请求之前固定；注入的清单客户端仍由调用方负责其自身生命周期。
+        def inventory(policy)
+          rows = (@client || @settings.client(policy: policy)).devices
+          raise Client::Error, "Netdisco returned an invalid device inventory" unless rows.is_a?(Array)
+
+          rules = @rules || policy.rules
+          devices = rows.map { |row| Device.from_row(row, rules: rules) }
+          duplicates = devices.group_by(&:host).reject { |host, entries| host.nil? || entries.size == 1 }
+          devices.map { |device| duplicates.key?(device.host) ? device.with(issue: :duplicate_host) : device }.freeze
+        end
+
+        def build_plan(mode, limit, policy)
+          Planner.validate_limit!(limit)
+          Planner.new(inventory(policy)).call(mode: mode, limit_per_vendor: limit)
+        end
+
         # 统一组织设备任务、日志目录与报告；Worker 保证单台设备失败不影响其他设备。
-        def run_batch(mode, plan, concurrency:, report_directory:, on_start:, on_result:, output_directory: nil)
+        def run_batch(mode, plan, concurrency:, report_directory:, policy:, reporting:, on_start:, on_result:, output_directory: nil)
           worker = Worker.new(concurrency: concurrency)
           started_at = Time.now.utc
+          started = monotonic
           outcomes = plan.outcomes.dup
           FileUtils.mkdir_p(output_directory, mode: 0o700) if output_directory && !plan.ready.empty?
-          log_directory = @settings.log_directory
+          log_directory = policy.log_directory
           FileUtils.mkdir_p(log_directory, mode: 0o700) if log_directory && !plan.ready.empty?
           callback_errors = worker.run(plan.ready, outcomes: outcomes, on_start: on_start, on_result: on_result,
                                        on_error: ->(device, error) { outcome(device, :failed, error: error) }) do |device|
@@ -100,9 +127,14 @@ module Net
           batch = Batch.new(mode: mode, outcomes: outcomes.freeze, started_at: started_at,
                             finished_at: Time.now.utc, callback_errors: callback_errors,
                             report_location: nil, report_error: nil)
+          if reporting.fetch(:schema) == 2
+            batch = Report.new(batch, policy: reporting.fetch(:policy), duration_ms: ((monotonic - started) * 1000).round)
+          end
           save_report(batch, directory: report_directory)
         end
 
+        def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
         # 校验批量任务回调接口。
         def validate_callback!(callback, name)
           raise ArgumentError, "#{name} must respond to call" if callback && !callback.respond_to?(:call)
@@ -113,18 +145,16 @@ module Net
           return batch unless @result_store
 
           batch.with(report_location: @result_store.write(batch, directory: directory))
+        rescue Operations::PrivateFile::WriteError => error
+          # 报告也可能已经原子替换；保留已知位置，不将持久性失败误写成完全没有产物。
+          location = error.receipt.path if Operations::PrivateFile.receipt_error?(error) && error.receipt.committed?
+          return batch.with_report_error(error, location: location) if batch.instance_of?(Report)
+
+          batch.with(report_location: location, report_error: error.class.name)
         rescue StandardError => error
-          batch.with(report_error: error.class.name)
-        end
+          return batch.with_report_error(error) if batch.instance_of?(Report)
 
-        # 校验厂商 VRF 映射和名称。
-        def validate_vrfs!(vrfs)
-          unless vrfs.is_a?(Hash) && vrfs.all? { |vendor, value|
-            %i[cisco_nxos hillstone].include?(vendor) && value.is_a?(String) &&
-              value.match?(/\A[A-Za-z0-9_][A-Za-z0-9_.-]*\z/)
-          }
-            raise ArgumentError, "vrfs must map supported vendor names to safe VRF names"
-          end
+          batch.with(report_error: error.class.name)
         end
 
         # 确认传入计划属于当前备份模式。
@@ -138,12 +168,12 @@ module Net
         def outcome(device, status, backup: nil, error: nil)
           Outcome.new(device: device, status: status, backup: backup,
                       error_code: error.respond_to?(:code) ? error.code : nil,
-                      error_type: error&.class&.name)
+                      error_type: error&.class&.name, diagnostic: Diagnostic.from(error, backup: backup))
         end
 
         # 执行单台设备的 TFTP 导出。
-        def tftp_backup_one(device, server, source_files, log_directory, vrfs)
-          run_one(device, log_directory, success_status: :reported_uploaded,
+        def tftp_backup_one(device, server, source_files, log_directory, vrfs, policy)
+          run_one(device, log_directory, policy, success_status: :reported_uploaded,
                   close_error_status: :reported_with_error, backup_class: TftpBackup) do |connector|
             source_file = source_files.fetch(device.vendor, nil)
             transfer_settings = { host: server, path: device.tftp_filename, source_file: source_file }
@@ -153,25 +183,26 @@ module Net
         end
 
         # 执行单台设备的本地配置采集。
-        def backup_one(device, directory, log_directory)
+        def backup_one(device, directory, log_directory, policy, saved_config)
           destination = File.join(directory, device.backup_filename)
-          previous = Operations::SavedConfig.new(directory: directory).find(device.host, required: false)
-          previous_digest = Digest::SHA256.file(previous).hexdigest if previous && previous != destination
-          run_one(device, log_directory, success_status: :backed_up,
-                  close_error_status: :saved_with_error, backup_class: Backup) do |connector|
-            backup = connector.backup(path: destination)
-            if backup.is_a?(Backup) && backup.change == :created && previous_digest
-              backup.with(previous_sha256: previous_digest,
-                          change: backup.sha256 == previous_digest ? :unchanged : :changed)
-            else
-              backup
+          Operations::BackupLock.synchronize(destination, host: device.host) do |path_lock|
+            previous = saved_config.fingerprint(device.host, required: false)
+            previous_digest = previous.sha256 if previous && previous.path != destination
+            result = run_one(device, log_directory, policy, success_status: :backed_up,
+                             close_error_status: :saved_with_error, backup_class: Backup) do |connector|
+              path_lock.delegate { connector.backup(path: destination) }
             end
+            backup = result.backup
+            next result unless backup.is_a?(Backup) && backup.change == :created && previous_digest
+
+            result.with(backup: backup.with(previous_sha256: previous_digest,
+                                           change: backup.sha256 == previous_digest ? :unchanged : :changed))
           end
         end
 
         # 隔离单台设备的凭据、连接、操作和关闭异常。
-        def run_one(device, log_directory, success_status:, close_error_status:, backup_class:)
-          connection_settings = @credentials.call(device)
+        def run_one(device, log_directory, policy, success_status:, close_error_status:, backup_class:)
+          connection_settings = @credentials ? @credentials.call(device) : @settings.device_credentials_for(device)
           return outcome(device, :missing_credentials) if connection_settings.nil?
           unless connection_settings.is_a?(Hash) && connection_settings.keys.all?(Symbol) &&
                  connection_settings[:username].is_a?(String) && !connection_settings[:username].empty? &&
@@ -179,20 +210,36 @@ module Net
             raise ArgumentError, "credential resolver must return settings with username and without host"
           end
 
+          connection_settings = policy.connection_options(device.vendor).merge(connection_settings)
           log_name = device.host.tr(":", "_")
           if log_directory
             connection_settings = connection_settings.merge(log_file: File.join(log_directory, "#{log_name}.log"))
           end
           connector = @connector_factory.call(device, connection_settings)
+          backup, failure = perform_one(connector, backup_class) { yield connector }
+          return outcome(device, success_status, backup: backup) unless failure
+
+          outcome(device, backup ? close_error_status : :failed, backup: backup, error: failure)
+        rescue StandardError => error
+          outcome(device, :failed, error: error)
+        end
+
+        # 仅信任库定义且产物类型匹配的提交后错误；普通第三方异常上的 backup 字段不代表完成。
+        def perform_one(connector, backup_class)
           backup = nil
           failure = nil
           begin
-            result = yield connector
+            result = yield
             raise TypeError, "backup operation did not return #{backup_class}" unless result.is_a?(backup_class)
 
             backup = result
           rescue StandardError => error
             failure = error
+            if backup_class == Backup && error.instance_of?(BackupPersistenceError) && error.backup.instance_of?(Backup)
+              backup = error.backup
+            elsif backup_class == TftpBackup && error.instance_of?(TftpCompletionError) && error.transfer.instance_of?(TftpBackup)
+              backup = error.transfer
+            end
           ensure
             begin
               connector.close
@@ -200,11 +247,7 @@ module Net
               failure ||= error
             end
           end
-          return outcome(device, success_status, backup: backup) unless failure
-
-          outcome(device, backup ? close_error_status : :failed, backup: backup, error: failure)
-        rescue StandardError => error
-          outcome(device, :failed, error: error)
+          [backup, failure]
         end
       end
     end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Net
+  module Connector
+    module Netdisco
+      # 每次 devices 调用独占一个预算，认证、分页和兼容查询不得重置已用资源或期限。
+      class InventoryBudget
+        def initialize(options, clock:)
+          @options = options
+          @clock = clock
+          @deadline = @clock.call + options.fetch(:inventory_timeout)
+          @bytes = 0
+          @devices = 0
+        end
+
+        def remaining
+          seconds = @deadline - @clock.call
+          raise Client::InventoryTimeout, cause: nil if seconds <= 0
+
+          seconds
+        end
+
+        # 在追加正文前计数；不能靠 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)
+          @bytes += size
+        end
+
+        # 去重前的记录同样占用清单内存；兼容查询也使用这个累计计数。
+        def consume_devices(size)
+          remaining
+          check_limit!(:max_devices, @devices + size)
+          @devices += size
+        end
+
+        private
+
+        def check_limit!(name, value)
+          return if value <= @options.fetch(name)
+
+          raise Client::Error.new("Netdisco inventory exceeded #{name}", code: name), cause: nil
+        end
+      end
+      private_constant :InventoryBudget
+    end
+  end
+end

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

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "forwardable"
+require_relative "batch"
+
+module Net
+  module Connector
+    module Netdisco
+      # v2 显式包装旧 Batch；成功策略与清单覆盖分开，默认 Batch JSON 不增加字段。
+      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
+
+        attr_reader :batch, :policy, :duration_ms, :report_diagnostic
+        def_delegators :@batch, *Batch.members, :success?, :status, :counts
+
+        # selected 必须使用带策略和覆盖信息的 v2；默认 strict 继续使用旧 schema。
+        def self.options(policy: :strict, schema: nil)
+          raise ArgumentError, "success_policy must be strict or selected" unless %i[strict selected].include?(policy)
+
+          schema = policy == :selected ? 2 : 1 if schema.nil?
+          raise ArgumentError, "report_schema must be 1 or 2" unless schema.is_a?(Integer) && [1, 2].include?(schema)
+          raise ArgumentError, "selected success policy requires report schema 2" if policy == :selected && schema != 2
+
+          { policy: policy, schema: schema }.freeze
+        end
+
+        def initialize(batch, policy: :strict, duration_ms: nil, report_diagnostic: nil)
+          self.class.options(policy: policy, schema: 2)
+          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)
+            raise ArgumentError, "duration_ms must be nonnegative and finite"
+          end
+          unless report_diagnostic.nil? || report_diagnostic.instance_of?(Diagnostic)
+            raise ArgumentError, "report_diagnostic must be a Diagnostic"
+          end
+
+          @batch, @policy, @duration_ms, @report_diagnostic = batch, policy, duration_ms, report_diagnostic
+          freeze
+        end
+
+        # 旧 success?/status 委托给 Batch；新策略绝不把未知状态当作可忽略跳过。
+        def policy_success?
+          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) }
+        end
+
+        def with(**attributes)
+          self.class.new(batch.with(**attributes), policy: policy, duration_ms: duration_ms,
+                          report_diagnostic: report_diagnostic)
+        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)
+        end
+
+        # 复用旧业务数据，但重新白名单化所有诊断字段，包括手工构造的旧 Batch。
+        def summary
+          legacy = batch.summary
+          legacy.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(legacy.fetch(:devices)),
+            callback_errors: callback_errors.map { |entry| { host: entry[:host], error_type: Diagnostic.type(entry[:error_type]) } },
+            report_location: report_location, report_error: Diagnostic.type(report_error),
+            report_diagnostic: report_diagnostic&.to_h
+          )
+        end
+
+        def inspect = "#<#{self.class} policy=#{policy} status=#{status} policy_success=#{policy_success?}>"
+
+        private
+
+        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)
+            entry.merge(error_code: diagnostic.error_code, error_type: diagnostic.error_type,
+                        diagnostic: diagnostic.to_h.except(:error_code, :error_type))
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -12,20 +12,33 @@ module Net
                        host_overrides: {}, mappings: [])
           @include_hosts = string_list(include_hosts)
           @exclude_hosts = string_list(exclude_hosts)
+          @include_vendors = vendor_list(include_vendors)
+          @vendor_overrides = vendor_mapping(vendor_overrides)
+          @host_overrides = host_mapping(host_overrides)
+          @mappings = device_mappings(mappings)
+        end
+
+        # 校验允许使用的厂商列表。
+        def vendor_list(include_vendors)
           raise ArgumentError, "include_vendors must be an Array" unless include_vendors.is_a?(Array)
 
-          @include_vendors = include_vendors.map do |vendor|
+          vendors = include_vendors.map do |vendor|
             raise ArgumentError, "include_vendors contains an invalid value" unless vendor.is_a?(String) || vendor.is_a?(Symbol)
 
             vendor.to_sym
           end.freeze
-          unless @include_vendors.all? { |vendor| Net::Connector.vendors.include?(vendor) }
+          unless vendors.all? { |vendor| Net::Connector.vendors.include?(vendor) }
             raise ArgumentError, "include_vendors contains an unsupported connector"
           end
+          vendors
+        end
+
+        # 将清单厂商标签映射为受支持的连接器。
+        def vendor_mapping(vendor_overrides)
           unless vendor_overrides.is_a?(Hash)
             raise ArgumentError, "vendor_overrides must be a Hash"
           end
-          @vendor_overrides = vendor_overrides.to_h do |label, vendor|
+          vendor_overrides.to_h do |label, vendor|
             unless label.is_a?(String) && vendor.is_a?(String) && !label.empty?
               raise ArgumentError, "vendor_overrides must map labels to connector names"
             end
@@ -35,9 +48,13 @@ module Net
 
             [key, value]
           end.freeze
+        end
+
+        # 按规范化管理地址覆盖厂商，拒绝网段和无效地址。
+        def host_mapping(host_overrides)
           raise ArgumentError, "host_overrides must be a Hash" unless host_overrides.is_a?(Hash)
 
-          @host_overrides = host_overrides.to_h do |host, vendor|
+          host_overrides.to_h do |host, vendor|
             unless host.is_a?(String) && !host.include?("/") && vendor.is_a?(String)
               raise ArgumentError, "host_overrides must map IP addresses to connector names"
             end
@@ -51,9 +68,13 @@ module Net
 
             [address, connector]
           end.freeze
+        end
+
+        # 型号映射仅接受已声明字段，并冻结每条规则。
+        def device_mappings(mappings)
           raise ArgumentError, "mappings must be an Array" unless mappings.is_a?(Array)
 
-          @mappings = mappings.map do |rule|
+          mappings.map do |rule|
             unless rule.is_a?(Hash) && rule["vendor"].is_a?(String) && !rule["vendor"].empty? &&
                    rule["connector"].is_a?(String) &&
                    (rule.keys - %w[vendor os model_prefix connector]).empty? &&
@@ -68,6 +89,8 @@ module Net
           end.freeze
         end
 
+        private :vendor_list, :vendor_mapping, :host_mapping, :device_mappings
+
         # 根据地址、显式规则和厂商信息识别连接器。
         def resolve(row)
           begin