wireless-rb 0.1.0

data/lib/wireless/collector.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require_relative "parser_registry"
+require "ctx_driver"
+require_relative "runtime_parser"
+require_relative "snapshot"
+require_relative "ap_session"
+require_relative "neighbor_parser"
+
+module Wireless
+  # 按单控制器顺序采集，去重共享查询，并区分失败与跳过维度。
+  class Collector
+    H3C_COMMANDS = H3c::Profile::COMMANDS.except(:lldp).freeze
+    HUAWEI_COMMANDS = { access_points: "display ap all", clients: "display station all" }.freeze
+    DEFAULT_DIMENSIONS = H3C_COMMANDS.keys.freeze
+
+    # 注入为顺序命令观测生成时间戳的时钟。
+    def initialize(clock: -> { Time.now.utc })
+      @clock = clock
+    end
+
+    # 通过调用方持有的连接器顺序采集请求维度。
+    def collect(connector:, target:, platform:, model: nil, dimensions: DEFAULT_DIMENSIONS, ap_connection: nil, ap_names: [])
+      platform = platform.to_s
+      raise ArgumentError, "Target must be a hash" unless target.is_a?(Hash)
+
+      unless dimensions.is_a?(Array) && dimensions.any? && dimensions.uniq == dimensions &&
+          (dimensions - (DEFAULT_DIMENSIONS + [ :lldp ])).empty? && ap_names.is_a?(Array) &&
+          ap_names.all? { |name| name.is_a?(String) && !name.strip.empty? && !/[\x00-\x1f\x7f]/.match?(name) }
+        raise ArgumentError, "Invalid wireless dimensions or AP selection"
+      end
+      requested = dimensions.dup
+      # LLDP 需要 AP 清单提供身份；组和服务模板需要配置证据补充关联关系。
+      requested |= [ :access_points ] if requested.include?(:lldp)
+      requested |= [ :configuration ] if (requested & %i[ap_groups service_templates]).any?
+      profile = ParserRegistry.fetch(platform, model: model) unless platform == "huawei"
+      commands = profile ? profile.commands.except(:lldp) : HUAWEI_COMMANDS
+      observations = requested.reject { |name| commands.key?(name) || (name == :lldp && platform != "huawei") }
+        .to_h { |name| [ name, unavailable(name, :unsupported, :unsupported_platform_dimension) ] }
+      queries = if profile
+        profile.queries(requested & commands.keys)
+      else
+        commands.slice(*requested).group_by { |_name, command| command }.transform_values { |entries| entries.map(&:first) }
+      end
+      actual = connector.platform.to_s
+      unless actual == platform || ([ actual, platform ] - %w[h3c h3c_wireless]).empty?
+        raise ArgumentError, "Wireless platform differs from the device connector"
+      end
+      stage = :connect
+      begin
+        connector.open do |session|
+          reader = CtxDriver::Reader.new(session: session, clock: @clock)
+          stage = :prepare
+          preparation = reader.read(platform == "huawei" ? "screen-length 0 temporary" : "screen-length disable")
+          error = preparation.failure&.fetch(:code)
+          queries.each do |command, names|
+            if error
+              names.each { |name| observations[name] = unavailable(name, :failed, error, skipped: true, stage: stage) }
+              next
+            end
+            stage = :collect
+            observations.merge!(read(reader, command, names, platform, model: model))
+          end
+          if requested.include?(:lldp) && platform != "huawei"
+            unavailable_code = error || reader.failure&.fetch(:code)
+            observations[:lldp] = if unavailable_code
+              unavailable(:lldp, :failed, unavailable_code, skipped: true, stage: stage)
+            else
+              # 仅在显式请求 LLDP 且会话准备成功后读取 AP 凭据，避免无关采集访问秘密。
+              credentials = (ap_connection.respond_to?(:call) ? ap_connection.call : ap_connection) || {}
+              neighbors(session, observations[:access_points], credentials, ap_names)
+            end
+          end
+          stage = :close
+        end
+      rescue StandardError => error
+        raise unless CtxDriver::Failure.connection_error?(error, connector)
+
+        code = CtxDriver::Failure.code(error, :connection_failed)
+        requested.each { |name| observations[name] ||= unavailable(name, :failed, code, skipped: true, stage: stage) }
+        observations[:collection] = unavailable(:collection, :failed, stage == :close ? :session_close_failed : code)
+      end
+      status = observations.values.all?(&:complete?) ? :complete : observations.values.any?(&:available?) ? :partial : :failed
+      observations[:collection] ||= Observation.new(name: :collection, status: status, completed_at: @clock.call)
+      Snapshot.new(target: target, dimensions: observations, observed_at: @clock.call)
+    end
+
+    private
+
+    # 单条命令负责自身解析失败；无关查询保留已完成事实。
+    def read(reader, command, names, platform, model:)
+      capture = reader.read(command)
+      metadata = { started_at: capture.started_at, completed_at: capture.completed_at, evidence: capture.evidence }
+      unless capture.success?
+        return failed_observations(names, capture.failure, command: command, skipped: capture.skipped?, **metadata)
+      end
+      begin
+        RuntimeParser.new(model: model).parse_many(names, capture.body, platform: platform, complete: true)
+          .transform_values { |observation| observation.with(**metadata) }
+      rescue StandardError => error
+        details = CtxDriver::Failure.details(error, fallback: :command_processing_failed, stage: :parse)
+        failed_observations(names, details, command: command, **metadata)
+      end
+    end
+
+    # 共享查询的各视图使用相同的安全失败及来源元数据。
+    def failed_observations(names, failure, command:, skipped: false, **metadata)
+      names.to_h do |name|
+        [ name, unavailable(name, :failed, failure.fetch(:code), **failure.except(:code), command: command, skipped: skipped).with(**metadata) ]
+      end
+    end
+
+    # 独立采集 AP 邻居证据，并报告 AP 覆盖不完整的情况。
+    def neighbors(session, aps, credentials, names)
+      return unavailable(:lldp, :failed, :access_points_unavailable) unless aps&.available?
+      return unavailable(:lldp, :failed, :ap_credentials_required) unless credentials[:password].is_a?(String) && !credentials[:password].strip.empty?
+      ap_session = ApSession.new(controller: session, **credentials)
+      started = @clock.call
+      records, issues, evidence = [], [], []
+      selected = aps.records.select { |ap| names.empty? || names.include?(ap[:name]) }
+      # 所选 AP 全部查询成功也不代表覆盖整台控制器，过滤范围和父清单缺失须独立报告。
+      issues << { code: :partial_access_point_coverage } unless aps.complete?
+      issues << { code: :ap_scope_filtered } if selected.size != aps.records.size
+      (names - selected.map { |ap| ap[:name] }).each { |name| issues << { code: :ap_not_found, ap_name: name } }
+      selected.each do |ap|
+        collected = read_neighbor(ap_session, ap)
+        records.concat(collected.fetch(:records))
+        issues.concat(collected.fetch(:issues))
+        evidence << collected.fetch(:evidence)
+      end
+      status = issues.empty? ? :complete : records.any? || evidence.any? { |entry| entry[:status] == :complete } ? :partial : :failed
+      Observation.new(name: :lldp, status: status, records: records, issues: issues, evidence: evidence,
+        started_at: started, completed_at: @clock.call)
+    rescue ArgumentError
+      unavailable(:lldp, :failed, :invalid_ap_credentials)
+    end
+
+    # 单个 AP 脚本或解析失败不能丢弃其他 AP 的邻居观测。
+    def read_neighbor(ap_session, ap)
+      stage = :execute
+      source = { kind: :ap_lldp_result, ap_name: ap[:name], command: ApSession::COMMAND,
+        attempted: true, status: :failed, neighbor_count: 0 }
+      outcome = ap_session.read(access_point: ap)
+      result = outcome[:result]
+      stage = :response
+      source[:attempted] = !outcome[:skipped]
+      source.merge!(result.evidence.first || {}) if result
+      stage = :parse
+      parsed = result&.success? ? NeighborParser.new(model: ap[:model]).parse(result.body, ap_name: ap[:name], complete: true) : nil
+      issues = parsed ? parsed.issues.map { |issue| issue.merge(ap_name: ap[:name]) } : []
+      %i[error cleanup_error].each { |key| issues << { code: outcome[key], ap_name: ap[:name] } if outcome[key] }
+      issues << { code: :ap_collection_failed, ap_name: ap[:name] } if !parsed && issues.empty?
+      source.merge!(
+        status: outcome[:error] || outcome[:cleanup_error] ? :failed : parsed&.status || :failed,
+        neighbor_count: parsed&.records&.size || 0)
+      { records: parsed&.records || [], issues: issues, evidence: source }
+    rescue StandardError => error
+      details = CtxDriver::Failure.details(error,
+        fallback: { execute: :command_execution_failed, response: :invalid_command_result, parse: :command_processing_failed }.fetch(stage), stage: stage)
+      { records: [], issues: [ details.merge(ap_name: ap[:name]) ], evidence: source }
+    end
+
+    # 构建明确不可用的观测，不虚构成功的空结果。
+    def unavailable(name, status, code, **details)
+      Observation.new(name: name, status: status, completed_at: @clock.call, issues: [ { code: code, **details } ])
+    end
+  end
+end

data/lib/wireless/configuration.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "parser_registry"
+require_relative "observation"
+
+module Wireless
+  # 将平台配置结果封装为领域观测。
+  class Configuration
+    # 按当前平台和型号选择无线配置策略。
+    def initialize(platform: :h3c, model: nil)
+      @profile = ParserRegistry.fetch(platform, model: model)
+    end
+
+    # 解析控制器配置，将事实封装为无线配置观测。
+    def parse(content, complete: false)
+      result = @profile.parse(:configuration, content, complete: complete)
+      Observation.new(name: :configuration, **result.to_h)
+    rescue ArgumentError
+      Observation.new(name: :configuration, status: :failed, issues: [ { code: :invalid_output } ])
+    end
+  end
+end

data/lib/wireless/coverage.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Wireless
+  # 证据新鲜度独立于保留的资产清单及已观察设备故障进行报告。
+  class Coverage
+    # 绑定观测、投影结果及请求的新鲜度时间窗。
+    def initialize(observations:, projection:, dimensions:, now:, stale_after:)
+      @observations, @projection, @dimensions = observations, projection || {}, dimensions
+      @now, @stale_after = now, stale_after
+    end
+
+    # 历史资产清单不声明 CLI 完整性，保持既有纯 Netdisco 视图兼容。
+    def to_h
+      return { "state" => "untracked", "source" => "inventory", "dimensions" => {} } unless @observations
+
+      dimensions = @dimensions.to_h { |name| [ name.to_s, dimension(name.to_s) ] }
+      states = dimensions.values.map { |entry| entry.fetch("state") }
+      state = states.all?("complete") ? "complete" : states.include?("unknown") ? "unknown" : "stale"
+      { "state" => state, "source" => "cli", "dimensions" => dimensions }
+    end
+
+    private
+
+    # 新记录不能刷新旧命令或失败命令的时效；投影受阻不算完整覆盖。
+    def dimension(name)
+      stored = @observations.fetch(name, {})
+      latest = stored.fetch("latest", {})
+      projection = @projection.fetch(name, {})
+      at = timestamp(latest["completed_at"] || latest["observed_at"])
+      projected_at = timestamp(projection["observed_at"])
+      last_complete = latest["status"] == "complete" ? latest : stored.fetch("last_complete", {})
+      state, reason = if latest["status"] != "complete"
+        [ "unknown", latest.empty? ? "not_requested" : "collection_#{latest['status']}" ]
+      elsif !at || at > @now
+        [ "unknown", "observation_time_unknown" ]
+      elsif @now - at > @stale_after
+        [ "stale", "evidence_stale" ]
+      elsif @projection.key?(name) && projected_at != at
+        [ "unknown", "projection_time_unconfirmed" ]
+      elsif @projection.key?(name) && projection["status"] != "complete"
+        [ "unknown", "projection_incomplete" ]
+      else
+        [ "complete", nil ]
+      end
+      { "state" => state, "status" => latest["status"] || "not_requested", "reason" => reason,
+        "observed_at" => at&.iso8601(6),
+        "last_complete_at" => timestamp(last_complete["completed_at"] || last_complete["observed_at"])&.iso8601(6),
+        "projection_status" => projection["status"], "projection_observed_at" => projected_at&.iso8601(6) }.compact
+    end
+
+    # 历史时间戳格式错误时视为证据不可用，不能当作新鲜观测。
+    def timestamp(value)
+      Time.iso8601(value) if value.is_a?(String)
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/wireless/fields.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "ctx_parser/input"
+require "ctx_parser/values"
+require "ctx_parser/result"
+require "ctx_parser/records"
+
+module Wireless
+  # 归一化厂商单位与身份，不将未知测量强制转换为零。
+  module Fields
+    extend self
+
+    # 校验来源文本，仅按请求调整编码或换行形式。
+    def text(content, newlines: :lf)
+      raise ArgumentError, "Invalid wireless output" unless content.is_a?(String)
+      begin
+        CtxParser::Input.text(content, encoding: :utf8, newlines: newlines)
+      rescue ArgumentError, EncodingError
+        raise ArgumentError, "Invalid wireless encoding"
+      end
+    end
+
+    # 归一化 CLI 缺失占位符，不转换为已知的空事实。
+    def value(raw)
+      string = raw.to_s.strip
+      string unless string.empty? || /\A(?:N\/A|--|-|Not configured|Not supported)\z/i.match?(string)
+    end
+
+    # 归一化 MAC 地址，拒绝格式错误的输入。
+    def mac(raw)
+      CtxParser::Values.mac(raw)
+    rescue ArgumentError
+      raise ArgumentError, "Invalid wireless MAC"
+    end
+
+    # 归一化 IP 主机地址，拒绝无效无线身份数据。
+    def ip(raw)
+      CtxParser::Values.host(raw)
+    rescue IPAddr::Error
+      raise
+    rescue ArgumentError
+      raise ArgumentError, "Invalid wireless host address"
+    end
+
+    # 解析十进制整数，并校验声明的边界。
+    def integer(raw, max: nil)
+      CtxParser::Values.integer(raw, max: max)
+    rescue CtxParser::Values::OutOfRange
+      raise ArgumentError, "Wireless integer out of range"
+    rescue ArgumentError
+      raise ArgumentError, "Invalid wireless integer"
+    end
+
+    # 解析数值测量，不将未知文本转换为零。
+    def number(raw, unit: nil)
+      return if raw.nil?
+      match = /\A(-?\d+(?:\.\d+)?)\s*(?:#{Regexp.escape(unit.to_s)})?\z/i.match(raw.to_s)
+      raise ArgumentError, "Invalid wireless number" unless match
+      Float(match[1])
+    end
+
+    # 将支持的时长格式转换为秒，并校验各时间分量。
+    def duration(raw)
+      return if raw.nil?
+      if /\A\d+:\d{2}:\d{2}:\d{2}\z/.match?(raw)
+        days, hours, minutes, seconds = raw.split(":").map(&:to_i)
+        raise ArgumentError, "Invalid wireless duration" unless hours < 24 && minutes < 60 && seconds < 60
+        return days * 86_400 + hours * 3600 + minutes * 60 + seconds
+      end
+      parts = raw.scan(/(\d+)\s*(days?|hours?|minutes?|seconds?|[dhms])\b/i)
+      remainder = raw.gsub(/\d+\s*(?:days?|hours?|minutes?|seconds?|[dhms])\b/i, "").delete(" :,")
+      raise ArgumentError, "Invalid wireless duration" if parts.empty? || !remainder.empty?
+      parts.sum { |amount, unit| amount.to_i * { "d" => 86_400, "h" => 3600, "m" => 60, "s" => 1 }.fetch(unit[0].downcase) }
+    end
+
+    # 将成对收发速率转换为每秒兆比特。
+    def rates(raw)
+      return [ nil, nil ] if raw.nil?
+      match = /\A(\d+(?:\.\d+)?)\s*\/\s*(\d+(?:\.\d+)?)\s*([kmgt]?bps)?\z/i.match(raw)
+      raise ArgumentError, "Invalid wireless rates" unless match
+      multiplier = { "bps" => 0.000001, "kbps" => 0.001, "mbps" => 1, "gbps" => 1000, "tbps" => 1_000_000 }.fetch((match[3] || "Mbps").downcase)
+      [ match[1], match[2] ].map { |value| Float(value) * multiplier }
+    end
+
+    # 解析明确无线信道；自动选择仍保持未知。
+    def channel(raw)
+      return if raw.nil? || /\Aauto\z/i.match?(raw.to_s)
+      match = /\A(\d+)(?:\s*\([^\n]*\))?\z/.match(raw.to_s)
+      raise ArgumentError, "Invalid wireless channel" unless match
+      number = integer(match[1], max: 233)
+      number if number.positive?
+    end
+
+    # 将支持的 MHz 回显归一化为正数信道宽度。
+    def width(raw)
+      match = /\A(\d+)\s*(?:MHz)?\z/i.match(raw.to_s)
+      match[1].to_i if match && match[1].to_i.positive?
+    end
+
+    # 根据明确标签或支持的信道范围确定无线频段。
+    def band(hint, channel: nil)
+      return "6GHz" if /6\s*g(?:hz)?/i.match?(hint.to_s)
+      return "5GHz" if /5\s*g(?:hz)?/i.match?(hint.to_s)
+      return "2.4GHz" if /2\.?4\s*g(?:hz)?|802\.11[bg](?:\b|\/)/i.match?(hint.to_s)
+      return unless channel
+      case channel
+      when 1..14 then "2.4GHz"
+      when 15..199 then "5GHz"
+      when 200..233 then "6GHz"
+      end
+    end
+
+    # 归一化已知在线、离线标签，同时保留未识别状态。
+    def online_status(raw)
+      return "online" if /\A(?:run|running|online|normal|nor|up)\z/i.match?(raw.to_s)
+      return "offline" if /\A(?:idle|fault|offline|down)\z/i.match?(raw.to_s)
+      raw
+    end
+
+    # 身份冲突降低完整性；保留首条记录仅用于部分投影。
+    def result(records, issues:, complete:, total: nil, identity:)
+      issues << { code: :count_mismatch, expected: total, parsed: records.size } if total && total != records.size
+      issues << { code: :missing_completeness_evidence } unless complete && (total || records.any?)
+      identities = CtxParser::Records.new(records, identity: identity)
+      identities.duplicate_row_count.times { issues << { code: :duplicate_identity } }
+      records = identities.first_occurrences.dup
+      status = issues.empty? ? :complete : records.empty? ? :failed : :partial
+      CtxParser::Result.new(status: status, records: records, issues: issues.uniq)
+    end
+  end
+end

data/lib/wireless/h3c/authentication_parser.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "session_parser"
+
+module Wireless
+  module H3c
+    # 认证命令共享字段语法及复合会话身份。
+    class AuthenticationParser < SessionParser
+      MAPPING = COMMON_FIELDS.except("vlan id", "service vlan id").merge(
+        "mac address" => :mac_address, "user mac address" => :mac_address, "username" => :username, "user name" => :username,
+        "access interface" => :interface, "interface" => :interface, "ip address" => :ip_address,
+        "ipv4 address" => :ip_address, "ipv6 address" => :ipv6_address, "authentication domain" => :domain, "domain" => :domain,
+        "authentication method" => :protocol, "authentication protocol" => :protocol, "auth protocol" => :protocol,
+        "access protocol" => :protocol, "protocol" => :protocol, "authentication state" => :state, "state" => :state, "status" => :state,
+        "initial vlan" => :initial_vlan_id, "initial vlan id" => :initial_vlan_id, "authorization vlan" => :authorized_vlan_id,
+        "authorization vlan id" => :authorized_vlan_id, "authorized vlan" => :authorized_vlan_id,
+        "authorized vlan id" => :authorized_vlan_id, "online time" => :online_seconds, "online duration" => :online_seconds).freeze
+      DETAILS = [ "anonymous username", "authorization acl number", "authorization dynamic acl name", "authorization user profile",
+        "authorization car", "authorization url", "authorization ipv6 url", "authorization microsegment id", "termination action",
+        "session timeout last from", "session timeout period", "online from" ].freeze
+      IDENTITY = [ :mac_address, :interface, :bssid ].freeze
+      COUNT = "(?:connections|users|online users)".freeze
+    end
+  end
+end

data/lib/wireless/h3c/command_output.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "../fields"
+
+module Wireless
+  module H3c
+    # 复用 H3C 输入校验；各命令实现 parse_text，配置解析保留原始换行。
+    module CommandOutput
+      UNSUPPORTED = /(?:Unrecognized command|Wrong parameter|Invalid (?:input|command)|Unknown command|Error:[^\r\n]*command)/i
+
+      private
+
+      # 解释当前命令回显，保留不支持或格式错误的证据。
+      def parse_output(text, complete:)
+        text = Fields.text(text, newlines: output_newlines)
+        if UNSUPPORTED.match?(text)
+          return CtxParser::Result.new(status: :unsupported, issues: [ { code: :unsupported_command } ])
+        end
+
+        parse_text(text, complete: complete)
+      rescue ArgumentError, IPAddr::InvalidAddressError
+        CtxParser::Result.new(status: :failed, issues: [ { code: :invalid_output } ])
+      end
+
+      # 声明当前命令解析器所需的换行归一化方式。
+      def output_newlines = :lf
+    end
+  end
+end

data/lib/wireless/h3c/configuration.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Wireless
+  module H3c
+    # 维护实体身份、归属及认证类型，不解析 CLI 文本或管理来源游标。
+    class Configuration
+      Scope = Data.define(:kind, :record, :path) do
+        # 解析当前配置块内的设置。
+        def settings = %i[ap_groups service_templates].include?(kind) ? record[:configuration] : record
+
+        # 解析已配置 AP 型号及其声明能力。
+        def model(name)
+          raise ArgumentError, "AP model outside group" unless kind == :ap_groups
+          descend(:model, [ :model_profiles, name ], radios: {})
+        end
+
+        # 在所属 AP 或型号作用域内解析 Radio 块。
+        def radio(identity)
+          unless %i[access_points ap_groups model global_configuration virtual_ap_group].include?(kind)
+            raise ArgumentError, "Invalid Radio owner"
+          end
+          if kind == :ap_groups && /\A\d+\z/.match?(identity)
+            raise ArgumentError, "Group radio requires a model"
+          end
+
+          collection = identity.end_with?("g") ? :band_defaults : :radios
+          keys = [ collection, identity ]
+          keys.unshift(:configuration) if kind == :ap_groups
+          descend(:radio, keys, service_templates: [])
+        end
+
+        # 在声明的配置作用域内解析 AP 以太网设置。
+        def ethernet(name)
+          raise ArgumentError, "Invalid Ethernet owner" unless %i[access_points model].include?(kind)
+          descend(:ethernet, [ :ethernet_ports, name ])
+        end
+
+        # 汇总已解析记录，并报告未解决或不完整的来源状态。
+        def finish
+          record[:authentication_type] = authentication if kind == :service_templates
+          record
+        end
+
+        private
+
+        # 分析子设置，同时保留父结果路径。
+        def descend(kind, keys, **defaults)
+          parent = keys[0...-1].reduce(record) { |value, key| value[key] ||= {} }
+          child = parent[keys.last] ||= defaults
+          self.class.new(kind: kind, record: child, path: path + keys)
+        end
+
+        # 解析实际生效的认证方法及外部服务器引用。
+        def authentication
+          mode = settings[:client_security_authentication_mode]
+          return "dot1x" if mode == "dot1x" || settings[:akm_modes].include?("dot1x") || settings[:dot1x_domain]
+          return "mab" if mode == "mac" || settings[:mac_authentication_domain]
+          return "psk" if settings[:akm_modes].include?("psk") || settings[:has_preshared_key]
+          return "portal" if settings[:portal]&.key?(:enable_method)
+          nil
+        end
+      end
+
+      attr_reader :data
+
+      # 初始化无线实体集合及配置诊断。
+      def initialize
+        @data = { access_points: {}, ap_groups: [], service_templates: [], global_settings: {}, blacklist: [], whitelist: [] }
+      end
+
+      # 使用实体集合作为身份索引，首条重复记录仅供部分结果保留。
+      def entity(kind, name, model: nil, type: nil)
+        collection = data.fetch(kind)
+        duplicate = kind == :access_points ? collection.key?(name) : collection.any? { |record| record[:name] == name }
+        raise ArgumentError, "Duplicate wireless configuration identity" if duplicate
+
+        record = case kind
+        when :ap_groups
+          { name: name, ap_names: [], serial_ids: [], vlan_ids: [], model_profiles: {}, configuration: type ? { type: type } : {} }
+        when :service_templates
+          { name: name, ssid: nil, vlan_id: nil, enabled: nil, configuration: { akm_modes: [], cipher_suites: [], security_ies: [] } }
+        when :access_points
+          { name: name, model: model, radios: {} }
+        end
+        identity = kind == :access_points ? name : collection.size
+        kind == :access_points ? collection[name] = record : collection << record
+        Scope.new(kind: kind, record: record, path: [ kind, identity ])
+      end
+
+      # 解析支持的控制器全局无线配置。
+      def global(kind = :global, identity: nil)
+        record = data[:global_settings]
+        path = [ :global_settings ]
+        unless %i[global global_configuration].include?(kind)
+          record = record[kind] ||= {}
+          path << kind
+        end
+        if kind == :virtual_ap_group
+          record = record[identity] ||= {}
+          path << identity
+        end
+        Scope.new(kind: kind, record: record, path: path)
+      end
+
+      # 展示对象身份与状态，避免泄露原始回显或凭据。
+      def inspect = "#<#{self.class} aps=#{data[:access_points].size} groups=#{data[:ap_groups].size} templates=#{data[:service_templates].size}>"
+    end
+  end
+end

data/lib/wireless/h3c/parser.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "ctx_parser/parser"
+require_relative "command_output"
+
+module Wireless
+  module H3c
+    # 命令专用解析前，先应用 H3C 响应边界。
+    class Parser < CtxParser::Parser
+      include CommandOutput
+    end
+  end
+end