zabbix_manager 5.1.6 → 6.0.0

data/lib/zabbix_manager/monitoring.rb

@@ -1,691 +1,265 @@
 # frozen_string_literal: true
 
+require "zabbix_manager/monitoring/validation"
+require "zabbix_manager/monitoring/traffic_items"
+require "zabbix_manager/monitoring/thresholds"
+require "zabbix_manager/monitoring/line"
+require "zabbix_manager/monitoring/line_items"
+require "zabbix_manager/monitoring/line_plan"
+require "zabbix_manager/monitoring/line_lifecycle"
+require "zabbix_manager/monitoring/device"
+
 class ZabbixManager
-  # 封装网络设备、接口和线路监控的高频幂等业务流程。
+  # 网络设备、接口和线路监控编排。先验证整批输入，再按稳定身份执行远端操作。
   class Monitoring
-    DEFAULT_WINDOW = "5m"
-    DEFAULT_PRIORITY = 3
-    SUPPORTED_FUNCTIONS = %w[avg max min last].freeze
-    EXPRESSION_ITEM_KEY = /\A[A-Za-z0-9_.-]+(?:\[[A-Za-z0-9_.:,\/\-\s{}\#\$"']*\])?\z/.freeze
-
-    # 使用同一个 Manager 复用 API 会话和资源模块。
-    # @return [Monitoring] 监控业务对象
-    # @api public
+    # @param manager [ZabbixManager] 共享认证客户端和资源对象
     def initialize(manager)
       @manager = manager
+      @thresholds = Thresholds.new(manager.client)
+      @workflow_mutex = Mutex.new
     end
 
-    # 创建或更新受监控的网络设备。
-    # @return [Integer] Zabbix 主机 ID
-    # @api public
-    def reconcile_device(data)
-      @manager.hosts.reconcile(data)
+    # 按技术主机名装配设备监控；名称引用在写入前通过 API 解析。
+    # 同一实例内串行执行工作流，远端写入没有数据库事务或跨进程原子性。
+    # @param device [Hash] 原生主机属性及 groups/templates、snmp、proxy_group、managed 等业务选项
+    # @return [Hash] hostid、enabled 和下次更新可传回的 managed 集合归属回执
+    # @raise [Invalid, Conflict] 输入无效、引用不唯一或不支持当前服务端版本
+    # @raise [ApiError, TransportError] 远端操作失败；超时后应先核查远端状态
+    def reconcile_device(device)
+      definition = Device.new(device)
+      @workflow_mutex.synchronize { definition.reconcile(@manager) }
     end
 
-    # 先校验整批设备，再按技术主机名逐台幂等创建或更新。
-    # 默认保留逐台结果；fail_fast 为 true 时遇到首个运行期错误即停止。
-    # @return [Array<Hash>]
-    def reconcile_devices(collection, fail_fast: false)
-      devices = Array(collection).map { |device| @manager.hosts.validate(device) }
-      validate_device_batch!(devices)
-      devices.map do |device|
-        hostid = reconcile_device(device)
-        { status: :ok, device: safe_device_identity(device), hostid: hostid }
-      rescue ApiError, TransportError, ArgumentError => e
-        raise if fail_fast
-
-        failure_result(:device, safe_device_identity(device), e)
-      end
+    # 先校验整批本地定义，再逐台对账；单台失败不掩盖其他设备的结果。
+    # @param devices [Array<Hash>] 设备定义，技术主机名必须唯一
+    # @param fail_fast [Boolean] true 时首个远端错误向上抛出
+    # @return [Array<Hash>] 每台设备的身份、status 和 result，或脱敏 error
+    # @raise [Invalid] 本地定义无效，此时整批尚未写入
+    def reconcile_devices(devices, fail_fast: false)
+      Validation.boolean!(fail_fast, "fail_fast")
+      reconcile_device_definitions(validate_devices!(devices), fail_fast: fail_fast)
     end
 
-    # 分设备和线路两个阶段执行一次网络监控批次，并返回稳定的汇总结果。
-    # 线路依赖模板或自动发现产生的流量项；尚未生成时会记录为线路失败，后续可安全重跑。
-    # @return [Hash]
+    # 线路预检在设备写入之前完成；线路发现依赖设备或模板产生的监控项。
+    # 模板/LLD 异步产生监控项，设备成功不代表对应线路已就绪。
+    # @param devices [Array<Hash>] 设备定义
+    # @param lines [Array<Hash>] 单端点线路定义；双端使用独立 line_id
+    # @param fail_fast [Boolean] true 时首个远端错误向上抛出
+    # @return [Hash] devices、lines 逐项结果和成功/失败/未知数量 summary
     def reconcile_network(devices:, lines:, fail_fast: false)
-      validate_line_collection!(lines)
-      device_results = reconcile_devices(devices, fail_fast: fail_fast)
-      line_results = reconcile_lines(lines, fail_fast: fail_fast)
-      results = { devices: device_results, lines: line_results }
+      Validation.boolean!(fail_fast, "fail_fast")
+      line_definitions = validate_lines!(lines)
+      device_definitions = validate_devices!(devices)
+      results = {
+        devices: reconcile_device_definitions(device_definitions, fail_fast: fail_fast),
+        lines: reconcile_line_definitions(line_definitions, fail_fast: fail_fast)
+      }
       results.merge(summary: batch_summary(results))
     end
 
-    # 使用 Zabbix 已发现的流量项创建或更新线路阈值触发器。
-    # 兼容 add_line_monitors.rb 的历史字段名。
-    # @return [Hash] 主机、接口、监控项和触发器结果
-    # @api public
-    def reconcile_line(data = nil, **attributes)
-      reconcile_line_with_cache(data || attributes, nil)
+    # 只读解析主机和监控项，预览实际触发器属性及按类型引用的依赖。
+    # ICMP 是 Zabbix server/proxy 对目标的检查，不能证明专线两端的转发路径。
+    # @param attributes [Hash] 单端点 line_id、host、interface_name、capacity_mbps 及可选监控配置
+    # @return [Hash] hostid、line_id、itemids、triggers、dependencies 和可选 icmp_item
+    # @raise [Invalid, Conflict] 阈值、量纲、项目选择或管理归属无法确定
+    # @raise [ApiError, TransportError] 远端发现失败，此方法从不写入
+    def plan_line(attributes)
+      prepare_line(Line.new(attributes), {})
     end
 
-    # 批量同步线路并复用主机和监控项查询缓存。
-    # 默认逐条记录成功或失败；fail_fast 为 true 时立即抛出错误。
-    # @return [Array<Hash>] 每条线路的状态和结果
-    # @api public
-    def reconcile_lines(collection, fail_fast: false)
-      lines = validate_line_collection!(collection)
-      cache = { items: {}, hosts: {} }
-      lines.map do |line|
-        { status: :ok, result: reconcile_line_with_cache(line, cache) }
-      rescue ApiError, TransportError, ArgumentError => e
-        raise if fail_fast
-
-        failure_result(:line, safe_line_identity(line), e)
-      end
+    # 对账一个端点，确认所需触发器后停用该线路不再需要的受管类型。
+    # 同一实例串行执行；多步远端写入不具备事务回滚或跨进程原子性。
+    # @param attributes [Hash] 与 plan_line 相同的线路定义
+    # @return [Hash] 主机、接口、line_id、按指标分类的 itemids 和 triggerids
+    # @raise [Invalid, Conflict] 预检失败，此时没有线路写入
+    # @raise [ApiError, TransportError] 远端失败；已确认的步骤保留，传输失败可能已提交
+    def reconcile_line(attributes)
+      line = Line.new(attributes)
+      @workflow_mutex.synchronize { apply_line(prepare_line(line, {})) }
     end
 
-    # 创建或更新一个设备接口的监控项和阈值触发器。
-    #
-    # 必需输入：
-    #   host: { hostid: 10101, host: "router-01" }
-    #   interface: { name: "GigabitEthernet1/0/1", interfaceid: 12 }
-    #   items: { inbound_bps: { key_: "...", name: "...", type: 4, value_type: 3 }, ... }
-    #
-    # 阈值支持 bandwidth、errors 和 packet_loss，只增改不自动删除远端对象。
-    # @return [Hash] 监控项和触发器 ID
-    # @api public
-    def reconcile_interface(data)
-      input = data.deep_symbolize_keys
-      host = resolve_explicit_host(input.fetch(:host))
-      interface = input.fetch(:interface)
-      validate_interface!(interface)
-
-      prepared_items, item_keys = prepare_items(host, interface, input.fetch(:items, {}))
-      thresholds = input.fetch(:thresholds, {})
-      validate_threshold_items!(thresholds, prepared_items)
-      prepared_triggers = prepare_thresholds(
-        host: host,
-        interface: interface,
-        item_keys: item_keys,
-        thresholds: thresholds
-      )
-      itemids = reconcile_items(prepared_items)
-      triggerids = reconcile_thresholds(prepared_triggers)
-
-      {
-        hostid: host[:hostid].to_i,
-        interface: interface[:name],
-        itemids: itemids,
-        triggerids: triggerids
-      }
+    # 先预检整批本地输入和远端发现，再逐端点执行，保留失败与结果未知的区别。
+    # @param lines [Array<Hash>] line_id 唯一的端点定义；双端线路使用两个不同 line_id
+    # @param fail_fast [Boolean] 遇到首个远端失败时向上抛出
+    # @return [Array<Hash>] 每个端点的 status、result 或脱敏 error
+    # @raise [Invalid] 本地定义或解析后的目标重复
+    def reconcile_lines(lines, fail_fast: false)
+      Validation.boolean!(fail_fast, "fail_fast")
+      reconcile_line_definitions(validate_lines!(lines), fail_fast: fail_fast)
     end
 
-    private
-
-      # 解析单条线路、发现流量项并同步阈值触发器。
-      def reconcile_line_with_cache(data, cache)
-        input = data.deep_symbolize_keys
-        host = resolve_line_host(input, cache: cache)
-        interface_name = input[:interface_name] || input[:iface] || input[:iface1]
-        raise Invalid, "line interface_name is required" if interface_name.blank?
-
-        traffic = find_line_traffic_items(host.fetch(:hostid), interface_name, cache: cache)
-        capacity_mbps = numeric!(input[:capacity_mbps] || input[:capacity], "line capacity_mbps")
-        raise Invalid, "line capacity_mbps must be positive" unless capacity_mbps.positive?
+    # 查询端点的受管触发器；人工触发器及其他管理方的同名对象不在结果中。
+    # @param hostid [Integer, String] 目标主机 ID
+    # @param line_id [String, Integer] 端点的稳定身份，或 plan_line 返回的自动身份
+    # @return [Array<Hash>] 原生 trigger.get 对象，包括 tags、items、状态及表达式
+    # @raise [Invalid, Conflict, ProtocolError] 输入无效或远端管理身份不唯一
+    def line_triggers(hostid:, line_id:)
+      LineLifecycle.new(@manager, hostid, line_id).owned
+    end
 
-        high_water = water_ratio!(input.fetch(:high_water, 0.90), "high_water")
-        recovery_water = water_ratio!(input.fetch(:recovery_water, 0.80), "recovery_water")
-        line_identity = input[:line_id].presence || input[:id].presence ||
-                        "#{host.fetch(:hostid)}:#{canonical_interface_identity(interface_name)}"
-        interface = { name: interface_name, line_id: line_identity }
-        item_keys = {
-          inbound_bps: traffic.fetch(:inbound).fetch("key_"),
-          outbound_bps: traffic.fetch(:outbound).fetch("key_")
-        }
-        prepared = line_thresholds(input, host, interface, item_keys, capacity_mbps, high_water, recovery_water)
-        triggerid = reconcile_thresholds(prepared).fetch(:bandwidth)
+    # 停用一个端点的全部受管触发器；不删除触发器或共享 ICMP 监控项。
+    # @param hostid [Integer, String] 目标主机 ID
+    # @param line_id [String, Integer] 端点的稳定身份
+    # @return [Array<Integer>] 已确认停用的触发器 ID；没有受管对象时为空
+    # @raise [ApiError, TransportError] 写入失败或结果尚未确认
+    def disable_line(hostid:, line_id:)
+      lifecycle = LineLifecycle.new(@manager, hostid, line_id)
+      @workflow_mutex.synchronize { lifecycle.disable }
+    end
 
-        {
-          hostid: host.fetch(:hostid).to_i,
-          host: host.fetch(:host),
-          interface: interface_name,
-          itemids: { inbound: traffic[:inbound]["itemid"].to_i, outbound: traffic[:outbound]["itemid"].to_i },
-          triggerid: triggerid
-        }
-      end
+    # 按该端点的触发器 ID 在服务端过滤问题，再应用数量上限。
+    # Zabbix problem.get 的 recent 范围受服务器问题保留配置影响，不代表完整事件归档。
+    # @param hostid [Integer, String] 目标主机 ID
+    # @param line_id [String, Integer] 端点的稳定身份
+    # @param time_from [Integer, Time] 查询起点（Unix 秒或 Time）
+    # @param time_till [Integer, Time] 查询终点，默认为当前时间
+    # @param limit [Integer] 最大记录数，1..1000；多读取一条以判定截断
+    # @return [Hash] problems、truncated、time_from、time_till 和 limit
+    # @raise [Invalid, ProtocolError] 范围无效或响应超出目标线路
+    def line_problems(hostid:, line_id:, time_from:, time_till: Time.now, limit: 100)
+      LineLifecycle.new(@manager, hostid, line_id).problems(time_from: time_from, time_till: time_till, limit: limit)
+    end
 
-      # 根据线路字段组装带宽阈值和历史迁移标签。
-      def line_thresholds(input, host, interface, item_keys, capacity_mbps, high_water, recovery_water)
-        prepared = prepare_thresholds(
-          host: host,
-          interface: interface,
-          item_keys: item_keys,
-          thresholds: {
-            bandwidth: {
-              capacity_bps: capacity_mbps * 1_000_000,
-              high_percent: high_water * 100,
-              recovery_percent: recovery_water * 100,
-              window: input.fetch(:problem_window, DEFAULT_WINDOW),
-              recovery_window: input.fetch(:recovery_window, "15m"),
-              priority: input.fetch(:severity, DEFAULT_PRIORITY),
-              description: line_trigger_description(input, interface[:name]),
-              tags: line_tags(input, interface[:name])
-            }
-          }
+    # 接口更新只增改，不自动删除远端对象；所有本地校验在首个写入之前完成。
+    # @param attributes [Hash] host、interface、按名称分组的原生 items 和 thresholds
+    # @return [Hash] hostid、interface、itemids 和 triggerids
+    # @raise [Invalid, Conflict] 输入、量纲或资源归属无效
+    # @raise [ApiError, TransportError] 远端失败；已经确认的早期步骤不会被回滚
+    def reconcile_interface(attributes)
+      input = Validation.hash!(attributes, "interface monitoring")
+      input.assert_valid_keys(:host, :interface, :items, :thresholds)
+      supplied_host = Validation.hash!(input[:host], "host")
+      Validation.host!(supplied_host)
+      interface = Validation.hash!(input[:interface], "interface")
+      interface.assert_valid_keys(:name, :interfaceid)
+      Validation.text!(interface[:name], "interface.name")
+      Validation.positive_id!(interface[:interfaceid], "interface.interfaceid") if interface.key?(:interfaceid)
+      items = @thresholds.prepare_items(supplied_host, interface, input.fetch(:items, {}))
+      triggers = @thresholds.prepare_triggers(
+        host: supplied_host, interface: interface, items: items, thresholds: input.fetch(:thresholds, {}),
+        validate_items: false
+      )
+      host = resolve_host(supplied_host, {})
+      ids = @manager.items.upsert_many(items.values) do |effective|
+        # 读取已有配置后再次校验最终量纲和数值类型，仍在首个 item 写入之前。
+        triggers = @thresholds.prepare_triggers(
+          host: supplied_host, interface: interface, items: items.keys.zip(effective).to_h,
+          thresholds: input.fetch(:thresholds, {})
         )
-        prepared[:bandwidth][:legacy_identity_tags] = [
-          { tag: "category", value: "line_bandwidth", operator: 1 }
-        ]
-        prepared[:bandwidth][:comments] = line_comments(input, capacity_mbps, high_water, recovery_water)
-        prepared
-      end
-
-      # 补齐监控项的主机、接口和名称，并检查 key 唯一性。
-      def prepare_items(host, interface, items)
-        prepared = items.each_with_object({}) do |(metric, raw_attributes), result|
-          attributes = raw_attributes.deep_symbolize_keys
-          attributes[:hostid] = host[:hostid]
-          attributes[:interfaceid] ||= interface[:interfaceid] if interface[:interfaceid]
-          attributes[:name] ||= "#{interface[:name]} #{metric.to_s.tr("_", " ")}"
-          raise Invalid, "item #{metric} key_ is required" if attributes[:key_].blank?
-          unless attributes[:key_].to_s.match?(EXPRESSION_ITEM_KEY)
-            raise Invalid, "item #{metric} key_ contains unsupported expression characters"
-          end
-
-          result[metric.to_sym] = attributes
-        end
-        keys = prepared.transform_values { |attributes| attributes.fetch(:key_) }
-        if keys.values.uniq.length != keys.length
-          raise Invalid, "item key_ values must be unique within an interface"
-        end
-
-        [prepared, keys]
-      end
-
-      # 把业务阈值转换为 Zabbix 问题和恢复表达式。
-      def prepare_thresholds(host:, interface:, item_keys:, thresholds:)
-        thresholds.each_with_object({}) do |(metric, raw_config), result|
-          config = raw_config.deep_symbolize_keys
-          keys = threshold_item_keys(metric, config, item_keys)
-          high, recovery = threshold_values(metric, config)
-          validate_threshold!(metric, high, recovery)
-          window = validate_window!(config.fetch(:window, DEFAULT_WINDOW))
-          recovery_window = validate_window!(config.fetch(:recovery_window, window))
-          function = validate_function!(config.fetch(:function, "avg"))
-          description = config[:description] || "#{interface[:name]} #{metric.to_s.tr("_", " ")} high"
-          raise Invalid, "threshold #{metric} description is required" if description.blank?
-
-          priority = validate_priority!(config.fetch(:priority, DEFAULT_PRIORITY))
-
-          result[metric.to_sym] = {
-            hostid: host[:hostid],
-            description: description,
-            expression: combine_expressions(host[:host], keys, function, window, ">", high, "or"),
-            recovery_mode: 1,
-            recovery_expression: combine_expressions(
-              host[:host], keys, function, recovery_window, "<", recovery, "and"
-            ),
-            priority: priority,
-            manual_close: 1,
-            tags: managed_tags(interface[:name], metric, config[:tags])
-          }
-          result[metric.to_sym][:managed_key] = managed_key(interface, metric)
-        end
-      end
-
-      # 在远端写入前校验各指标的单位和速率语义。
-      def validate_threshold_items!(thresholds, items)
-        thresholds.each do |metric, raw_config|
-          config = raw_config.deep_symbolize_keys
-          names = Array(config[:metrics] || default_metrics(metric)).map(&:to_sym)
-          selected = names.map do |name|
-            items.fetch(name) { raise Invalid, "threshold #{metric} requires item metric #{name}" }
-          end
-          case metric.to_sym
-          when :bandwidth
-            selected.each { |item| validate_bps_item!(item) }
-          when :errors
-            selected.each { |item| validate_error_rate_item!(item) }
-          when :packet_loss
-            selected.each { |item| validate_packet_loss_item!(item) }
-          end
-        end
-      end
-
-      # 确认误码指标表示每秒速率而不是累计计数器。
-      def validate_error_rate_item!(item)
-        values = item.with_indifferent_access
-        preprocessing = Array(values[:preprocessing])
-        rate_step = preprocessing.any? { |step| (step["type"] || step[:type]).to_i == 10 }
-        explicit_rate = [values[:key_], values[:name]].join(" ").match?(/rate|per[._ -]?second/i)
-        return if rate_step || explicit_rate
-
-        raise Invalid, "error metric #{values[:key_]} must represent a per-second rate"
-      end
-
-      # 确认丢包指标使用百分比单位。
-      def validate_packet_loss_item!(item)
-        values = item.with_indifferent_access
-        return if values[:units].to_s == "%"
-
-        raise Invalid, "packet loss metric #{values[:key_]} must use % units"
-      end
-
-      # 按稳定 key 写入已准备好的监控项。
-      def reconcile_items(prepared_items)
-        prepared_items.transform_values { |attributes| @manager.items.upsert_by_key(attributes) }
-      end
-
-      # 按稳定管理标签写入已准备好的触发器。
-      def reconcile_thresholds(prepared_triggers)
-        prepared_triggers.transform_values { |attributes| @manager.triggers.upsert_for_host(attributes) }
-      end
-
-      # 在批量写入前拒绝重复线路 ID。
-      def validate_line_batch!(lines)
-        identities = lines.filter_map { |line| line[:line_id].presence || line[:id].presence }.map(&:to_s)
-        duplicate = identities.tally.find { |_identity, count| count > 1 }&.first
-        raise Invalid, "duplicate line_id #{duplicate}" if duplicate
-      end
-
-      # 规范化并完整预检线路集合，保证校验阶段不执行远端写入。
-      def validate_line_collection!(collection)
-        lines = Array(collection).map(&:deep_symbolize_keys)
-        validate_line_batch!(lines)
-        lines.each { |line| validate_line_definition!(line) }
-        lines
-      end
-
-      # 在任何远端写入前校验线路必填字段和阈值格式。
-      def validate_line_definition!(line)
-        validate_line_host_reference!(line)
-        interface_name = line[:interface_name] || line[:iface] || line[:iface1]
-        raise Invalid, "line interface_name is required" if interface_name.blank?
-
-        capacity = numeric!(line[:capacity_mbps] || line[:capacity], "line capacity_mbps")
-        raise Invalid, "line capacity_mbps must be positive" unless capacity.positive?
-
-        high_water = water_ratio!(line.fetch(:high_water, 0.90), "high_water")
-        recovery_water = water_ratio!(line.fetch(:recovery_water, 0.80), "recovery_water")
-        raise Invalid, "recovery_water must be lower than high_water" unless recovery_water < high_water
-
-        validate_window!(line.fetch(:problem_window, DEFAULT_WINDOW))
-        validate_window!(line.fetch(:recovery_window, "15m"))
-        validate_priority!(line.fetch(:severity, DEFAULT_PRIORITY))
-      end
-
-      # 校验线路提供显式主机对象或至少一个可解析的设备候选值。
-      def validate_line_host_reference!(line)
-        supplied = line[:host]
-        if supplied.respond_to?(:deep_symbolize_keys)
-          validate_host!(supplied.deep_symbolize_keys)
-          return
-        end
-
-        candidates = Array(line[:host_candidates])
-        candidates.concat([supplied, line[:device], line[:device1], line[:ip], line[:ipaddr1], line[:serial]])
-        candidates = candidates.filter_map { |value| value.to_s.strip.presence }
-        candidates.delete("IP地址")
-        raise Invalid, "line host candidate is required" if candidates.empty?
-      end
-
-      # 在任何远端写入前拒绝同一技术主机名的重复设备定义。
-      def validate_device_batch!(devices)
-        identities = devices.map { |device| device.fetch(:host).to_s }
-        duplicate = identities.tally.find { |_identity, count| count > 1 }&.first
-        raise Invalid, "duplicate device host #{duplicate}" if duplicate
-      end
-
-      # 只返回可安全记录的设备身份字段。
-      def safe_device_identity(device)
-        { host: device[:host], name: device[:name] }.compact
-      end
-
-      # 构造设备或线路的脱敏失败结果。
-      def failure_result(kind, identity, error)
-        {
-          status: :error,
-          kind => identity,
-          error: { class: error.class.name, message: LogSanitizer.sanitize(error.message) }
-        }
-      end
-
-      # 汇总批次两个阶段的成功与失败数量。
-      def batch_summary(results)
-        results.each_with_object({}) do |(kind, entries), summary|
-          summary[kind] = {
-            total: entries.length,
-            succeeded: entries.count { |entry| entry[:status] == :ok },
-            failed: entries.count { |entry| entry[:status] == :error }
-          }
-        end
-      end
-
-      # 只返回可安全记录的线路身份字段。
-      def safe_line_identity(line)
-        {
-          line_id: line[:line_id].presence || line[:id].presence,
-          device: line[:device] || line[:device1],
-          interface: line[:interface_name] || line[:iface] || line[:iface1]
-        }.compact
-      end
-
-      # 解析一个阈值引用的监控项 key 集合。
-      def threshold_item_keys(metric, config, item_keys)
-        metric_names = Array(config[:metrics] || default_metrics(metric))
-        keys = metric_names.map do |name|
-          item_keys.fetch(name.to_sym) do
-            raise Invalid, "threshold #{metric} requires item metric #{name}"
-          end
-        end
-        raise Invalid, "threshold #{metric} requires at least one item" if keys.empty?
-
-        keys
-      end
-
-      # 返回常用指标默认依赖的监控项名称。
-      def default_metrics(metric)
-        case metric.to_sym
-        when :bandwidth then %i[inbound_bps outbound_bps]
-        when :errors then %i[in_errors out_errors]
-        when :packet_loss then [:packet_loss]
-        else [metric.to_sym]
-        end
-      end
-
-      # 计算带宽百分比或普通指标的高低阈值。
-      def threshold_values(metric, config)
-        if metric.to_sym == :bandwidth
-          capacity = numeric!(config[:capacity_bps], "bandwidth capacity_bps")
-          high_percent = numeric!(config[:high_percent], "bandwidth high_percent")
-          recovery_percent = numeric!(config[:recovery_percent], "bandwidth recovery_percent")
-          unless capacity.positive? && high_percent.between?(0, 100) && recovery_percent.between?(0, 100)
-            raise Invalid, "bandwidth capacity must be positive and percentages must be between 0 and 100"
-          end
-
-          [capacity * high_percent / 100.0, capacity * recovery_percent / 100.0]
-        else
-          [numeric!(config[:high], "#{metric} high"), numeric!(config[:recovery], "#{metric} recovery")]
-        end
-      end
-
-      # 校验恢复阈值低于问题阈值，形成滞回区间。
-      def validate_threshold!(metric, high, recovery)
-        return if high.positive? && recovery >= 0 && recovery < high
-
-        raise Invalid, "#{metric} recovery threshold must be non-negative and lower than high threshold"
-      end
-
-      # 组合多个方向的触发器表达式。
-      def combine_expressions(host, keys, function, window, operator, threshold, joiner)
-        keys.map do |key|
-          function_call = expression_function(host, key, function, window)
-          "#{function_call}#{operator}#{format_number(threshold)}"
-        end.join(" #{joiner} ")
-      end
-
-      # 按 Zabbix 版本生成新式或旧式函数表达式。
-      def expression_function(host, key, function, window)
-        if modern_trigger_expression?
-          source = "/#{host}/#{key}"
-          function == "last" ? "last(#{source})" : "#{function}(#{source},#{window})"
-        else
-          parameter = function == "last" ? "" : window
-          "{#{host}:#{key}.#{function}(#{parameter})}"
-        end
-      end
-
-      # 判断服务端是否支持 Zabbix 5.4 起的新表达式语法。
-      def modern_trigger_expression?
-        version = @manager.client.api_version.to_s.split(".").first(2).map(&:to_i)
-        (version <=> [5, 4]) >= 0
-      end
-
-      # 合并系统管理标签和调用方扩展标签。
-      def managed_tags(interface_name, metric, extra_tags)
-        tags = [
-          { tag: "managed_by", value: "zabbix_manager" },
-          { tag: "interface", value: interface_name.to_s },
-          { tag: "metric", value: metric.to_s }
-        ]
-        tags.concat(Array(extra_tags).map do |tag|
-          unless tag.respond_to?(:deep_symbolize_keys)
-            raise Invalid, "threshold tags must contain a non-empty tag name"
-          end
-
-          normalized = tag.deep_symbolize_keys
-          raise Invalid, "threshold tags must contain a non-empty tag name" if normalized[:tag].blank?
-
-          normalized
-        end)
-      end
-
-      # 生成不受描述和数组顺序影响的触发器管理键。
-      def managed_key(interface, metric)
-        identity = interface[:line_id].presence || interface[:interfaceid].presence ||
-                   canonical_interface_identity(interface[:name])
-        "interface:#{identity}:#{metric}"
-      end
-
-      # 从显式主机或历史线路字段中解析唯一主机。
-      def resolve_line_host(input, cache: nil)
-        supplied = input[:host]
-        if supplied.respond_to?(:deep_symbolize_keys)
-          return resolve_explicit_host(supplied)
-        end
-
-        candidates = Array(input[:host_candidates])
-        candidates.concat([supplied, input[:device], input[:device1], input[:ip], input[:ipaddr1], input[:serial]])
-        candidates = candidates.filter_map { |value| value.to_s.strip.presence }
-        candidates.delete("IP地址")
-        raise Invalid, "line host candidate is required" if candidates.empty?
-
-        cache_key = candidates.join("\0")
-        found = if cache
-                  cache.fetch(:hosts)[cache_key] ||= @manager.hosts.find_by_candidates(candidates)
-                else
-                  @manager.hosts.find_by_candidates(candidates)
-                end
-        raise ApiError, "Zabbix host not found for #{candidates.join(", ")}" unless found
-
-        found.deep_symbolize_keys
-      end
-
-      # 查询并精确选择接口的入向和出向流量项。
-      def find_line_traffic_items(hostid, interface_name, cache: nil)
-        aliases = interface_aliases(interface_name)
-        source_items = if cache
-                         cache.fetch(:items)[hostid.to_s] ||= @manager.items.monitored_traffic_candidates(hostid)
-                       else
-                         @manager.items.monitored_traffic_candidates(hostid)
-                       end
-        candidates = source_items.select do |item|
-          traffic_item?(item) && interface_item?(item, aliases)
-        end
-        selected = {
-          inbound: unique_direction_item!(candidates, :inbound, interface_name),
-          outbound: unique_direction_item!(candidates, :outbound, interface_name)
-        }
-        selected.each_value { |item| validate_bps_item!(item) }
-        selected
-      end
-
-      # 把接口名称转换为统一身份集合。
-      def interface_aliases(interface_name)
-        [canonical_interface_identity(interface_name)]
-      end
-
-      # 统一全称、缩写和分隔符，生成稳定接口身份。
-      def canonical_interface_identity(value)
-        value.to_s.downcase.gsub(/\s+|[-_]/, "")
-             .sub(/^tengigabitethernet/, "te")
-             .sub(/^gigabitethernet/, "gi")
-             .sub(/^ethernet/, "eth")
-      end
-
-      # 判断监控项字段是否包含目标接口的精确 token。
-      def interface_item?(item, aliases)
-        fields = [item["name"], item["key_"], item["snmp_oid"]].compact.map(&:to_s)
-        discovered = fields.flat_map { |field| interface_tokens(field) }.map do |name|
-          canonical_interface_identity(name)
-        end
-        aliases.any? { |name| discovered.include?(name) }
-      end
-
-      # 从名称、key 和 OID 文本中抽取完整接口 token。
-      def interface_tokens(value)
-        prefix = "(?:Ten-?GigabitEthernet|GigabitEthernet|Ethernet|Te|Gi|Eth)"
-        pattern = /(?:#{prefix})?\d+(?:\/\d+)+(?:[.:]\d+)*(?![A-Za-z0-9\/._-]|:\d)/i
-        value.to_s.scan(pattern)
-      end
-
-      # 排除误码、丢包和状态项，只保留可能的流量项。
-      def traffic_item?(item)
-        oid = item["snmp_oid"].to_s
-        blob = [item["key_"], item["name"]].join(" ").downcase
-        return false if blob.match?(/error|discard|drop|packet|status|utilization|percentage|percent/)
-
-        oid.match?(/1\.3\.6\.1\.2\.1\.31\.1\.1\.1\.(6|10)(\.|$)/) ||
-          blob.match?(/net\.if\.(in|out)(?:\[[^,\]]+\]|\b)|ifhc(in|out)octets|inbound|outbound/)
-      end
-
-      # 确保一个方向只匹配一个监控项。
-      def unique_direction_item!(candidates, direction, interface_name)
-        matches = candidates.select { |item| direction_item?(item, direction) }
-        if matches.length != 1
-          raise Conflict, "expected one #{direction} traffic item for #{interface_name}, found #{matches.length}"
-        end
-
-        matches.first
-      end
-
-      # 根据 OID、key 和名称判断监控项方向。
-      def direction_item?(item, direction)
-        oid = item["snmp_oid"].to_s
-        blob = [item["key_"], item["name"]].join(" ").downcase
-        if direction == :inbound
-          oid.match?(/1\.3\.6\.1\.2\.1\.31\.1\.1\.1\.6(\.|$)/) || blob.match?(/net\.if\.in|ifhcin|inbound/)
-        else
-          oid.match?(/1\.3\.6\.1\.2\.1\.31\.1\.1\.1\.10(\.|$)/) || blob.match?(/net\.if\.out|ifhcout|outbound/)
-        end
-      end
-
-      # 校验流量项单位及原始八位组预处理链。
-      def validate_bps_item!(item)
-        values = item.with_indifferent_access
-        unless values[:units].to_s.casecmp("bps").zero?
-          raise Invalid, "traffic item #{values[:itemid] || values[:key_]} must use bps units"
-        end
-        return unless raw_octet_counter?(values)
-
-        preprocessing = Array(values[:preprocessing])
-        change_per_second = preprocessing.any? { |step| (step["type"] || step[:type]).to_i == 10 }
-        bits_multiplier = preprocessing.any? do |step|
-          type = step["type"] || step[:type]
-          params = step["params"] || step[:params]
-          type.to_i == 1 && numeric!(params, "traffic preprocessing multiplier") == 8
-        end
-        return if change_per_second && bits_multiplier
-
-        identity = values[:itemid] || values[:key_]
-        raise Invalid, "raw octet item #{identity} requires change-per-second and multiplier 8 preprocessing"
-      end
-
-      # 判断监控项是否直接读取 HC Octets 累计计数器。
-      def raw_octet_counter?(item)
-        values = item.with_indifferent_access
-        oid = values[:snmp_oid].to_s
-        key = values[:key_].to_s.downcase
-        oid.match?(/1\.3\.6\.1\.2\.1\.31\.1\.1\.1\.(6|10)(\.|$)/) || key.match?(/ifhc(in|out)octets/)
       end
+      itemids = items.keys.zip(ids).to_h
+      triggerids = triggers.transform_values { |trigger| @manager.triggers.upsert_for_host(trigger) }
+      { hostid: host[:hostid].to_i, interface: interface[:name], itemids: itemids, triggerids: triggerids }
+    end
 
-      # 把百分数或小数形式的水位转换为 0 到 1 的比例。
-      def water_ratio!(value, name)
-        ratio = numeric!(value, name)
-        ratio /= 100.0 if ratio > 1
-        raise Invalid, "#{name} must be greater than 0 and at most 1" unless ratio.positive? && ratio <= 1
+    private
 
-        ratio
-      end
+    def validate_devices!(devices)
+      definitions = Validation.array!(devices, "devices").map { |device| Device.new(device) }
+      validate_unique!(definitions.map(&:identity), "device host")
+      definitions
+    end
 
-      # 组合线路触发器的可读描述。
-      def line_trigger_description(input, interface_name)
-        ["专线流量超阈值", input[:isp], input[:description], input[:device] || input[:device1], interface_name]
-          .compact.map(&:to_s).reject(&:blank?).join(" | ")
-      end
+    def validate_lines!(lines)
+      definitions = Validation.array!(lines, "lines").map { |attributes| Line.new(attributes) }
+      validate_unique!(definitions.map(&:identity), "line_id or host/interface")
+      definitions
+    end
 
-      # 从脱敏的线路业务字段生成触发器标签。
-      def line_tags(input, interface_name)
-        {
-          category: "line_bandwidth",
-          isp: input[:isp],
-          description: input[:description],
-          device: input[:device] || input[:device1],
-          iface: interface_name
-        }.filter_map { |tag, value| { tag: tag.to_s, value: value.to_s } if value.present? }
-      end
+    def validate_unique!(identities, name)
+      duplicate = identities.tally.find { |_identity, count| count > 1 }
+      raise Invalid, "duplicate #{name}" if duplicate
+    end
 
-      # 生成线路阈值参数说明，便于 Zabbix 页面审计。
-      def line_comments(input, capacity_mbps, high_water, recovery_water)
-        "Managed line bandwidth monitor: ISP=#{input[:isp]}, description=#{input[:description]}, " \
-          "capacity_mbps=#{format_number(capacity_mbps)}, high_water=#{high_water}, recovery_water=#{recovery_water}"
-      end
+    def reconcile_device_definitions(devices, fail_fast:)
+      devices.map do |device|
+        identity = device.safe_identity
+        result = @workflow_mutex.synchronize { device.reconcile(@manager) }
+        { status: :ok, device: identity, result: result }
+      rescue ApiError, TransportError, Invalid => error
+        raise if fail_fast
 
-      # 校验主机对象包含 ID 和技术名。
-      def validate_host!(host)
-        raise Invalid, "host.hostid is required" if host[:hostid].blank?
-        raise Invalid, "host.host is required" if host[:host].blank?
-        raise Invalid, "host.host cannot contain /" if host[:host].to_s.include?("/")
+        failure_result(:device, identity, error, writing: true)
       end
+    end
 
-      # 回读主机并核对 hostid 与技术名属于同一对象。
-      def resolve_explicit_host(raw_host)
-        supplied = raw_host.deep_symbolize_keys
-        validate_host!(supplied)
-        remote = @manager.hosts.find_by_id(supplied[:hostid])
-        raise ApiError, "Zabbix host #{supplied[:hostid]} was not found" unless remote
-
-        resolved = remote.deep_symbolize_keys
-        if resolved[:host].to_s != supplied[:host].to_s
-          raise Conflict, "hostid and technical host name do not refer to the same Zabbix host"
-        end
+    # 先完成线路发现，防止两个不同候选主机名解析到同一触发器后互相覆盖。
+    def reconcile_line_definitions(lines, fail_fast:)
+      cache = {}
+      prepared = lines.map do |line|
+        { line: line, plan: prepare_line(line, cache) }
+      rescue ApiError, TransportError, Invalid => error
+        raise if fail_fast
 
-        resolved[:hostid] = supplied[:hostid]
-        resolved
+        { line: line, failure: failure_result(:line, line.safe_identity, error) }
       end
-
-      # 校验接口对象包含可显示名称。
-      def validate_interface!(interface)
-        raise Invalid, "interface.name is required" if interface[:name].blank?
+      identities = prepared.filter_map do |entry|
+        plan = entry[:plan]
+        [plan[:hostid], plan[:line_id]] if plan
       end
+      validate_unique!(identities, "line target")
+      prepared.map do |entry|
+        next entry[:failure] if entry[:failure]
 
-      # 校验 Zabbix 时间窗口格式。
-      def validate_window!(window)
-        value = window.to_s
-        raise Invalid, "window must use a Zabbix duration such as 5m or 1h" unless value.match?(/\A\d+[smhdw]\z/)
+        { status: :ok, result: @workflow_mutex.synchronize { apply_line(entry[:plan]) } }
+      rescue ApiError, TransportError, Invalid => error
+        raise if fail_fast
 
-        value
+        failure_result(:line, entry[:line].safe_identity, error, writing: true)
       end
+    end
 
-      # 限制触发器函数为受支持的安全集合。
-      def validate_function!(function)
-        value = function.to_s
-        unless SUPPORTED_FUNCTIONS.include?(value)
-          raise Invalid, "function must be one of #{SUPPORTED_FUNCTIONS.join(", ")}"
-        end
-
-        value
-      end
+    def prepare_line(line, cache)
+      host = resolve_host(line.host_reference, cache)
+      source_items = cache[[:items, host[:hostid].to_s]] ||=
+        @manager.items.monitored_traffic_candidates(host[:hostid])
+      resolver = LineItems.new(@manager.items)
+      selected = resolver.resolve(line, source_items, hostid: host[:hostid])
+      icmp_item = resolver.icmp_plan(host[:hostid], line.reachability_target) if line.reachability_target
+      plan = LinePlan.new(@manager.client, line, host, selected, icmp_item).to_h
+      lifecycle = LineLifecycle.new(@manager, plan[:hostid], plan[:line_id])
+      lifecycle.validate_ownership!(lifecycle.inventory, plan[:triggers].values.pluck(:managed_key))
+      plan
+    end
 
-      # 校验 Zabbix 严重级别范围。
-      def validate_priority!(priority)
-        value = Integer(priority)
-        raise Invalid unless value.between?(0, 5)
+    def apply_line(plan)
+      lifecycle = LineLifecycle.new(@manager, plan[:hostid], plan[:line_id])
+      existing = lifecycle.inventory
+      desired_keys = plan[:triggers].values.pluck(:managed_key)
+      lifecycle.validate_ownership!(existing, desired_keys)
+      itemids = plan[:itemids].dup
+      if plan[:icmp_item]
+        itemids[:reachability] = LineItems.new(@manager.items).ensure_icmp(plan[:icmp_item])
+      end
+      triggerids = {}
+      plan[:triggers].each do |kind, attributes|
+        dependencies = plan[:dependencies].fetch(kind).map { |dependency| { triggerid: triggerids.fetch(dependency) } }
+        triggerids[kind] = @manager.triggers.upsert_for_host(attributes.merge(dependencies: dependencies))
+      end
+      lifecycle.retire(existing, desired_keys)
+      plan.slice(:hostid, :host, :interface, :line_id).merge(itemids: itemids, triggerids: triggerids)
+    end
 
-        value
-      rescue ArgumentError, TypeError
-        raise Invalid, "priority must be an integer between 0 and 5"
-      end
+    def resolve_host(reference, cache)
+      host = cache[[:host, reference]] ||= @manager.hosts.resolve(reference)
+      reference.is_a?(Hash) ? host.merge(hostid: reference[:hostid]) : host
+    end
 
-      # 把业务输入转换为浮点数并统一错误消息。
-      def numeric!(value, name)
-        Float(value)
-      rescue ArgumentError, TypeError
-        raise Invalid, "#{name} must be numeric"
-      end
+    def failure_result(kind, identity, error, writing: false)
+      unknown = error.is_a?(ResultUnknown) || (writing && error.is_a?(TransportError))
+      {
+        status: unknown ? :unknown : :error,
+        kind => identity,
+        error: { class: error.class.name, message: LogSanitizer.sanitize(error.message) }
+      }
+    end
 
-      # 用稳定精度格式化表达式中的数值。
-      def format_number(number)
-        number.to_i == number ? number.to_i.to_s : number.round(6).to_s
+    def batch_summary(results)
+      results.transform_values do |entries|
+        statuses = entries.map { |entry| entry[:status] }.tally
+        { total: entries.length, succeeded: statuses.fetch(:ok, 0),
+          failed: statuses.fetch(:error, 0), unknown: statuses.fetch(:unknown, 0) }
       end
+    end
   end
 end