vxlan 0.2.3 → 0.3.1

data/lib/vxlan/config/review.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Vxlan
+  class Config
+    # 配置关联审查独立于语法解析及运行健康检查。
+    class Review
+      # 绑定归一化配置，用于交叉引用一致性检查。
+      def initialize(configuration)
+        @configuration = configuration
+      end
+
+      # 检查完整配置中的关联缺失或引用矛盾。
+      def call(complete: false)
+        raise ArgumentError, "Completeness must be boolean" unless [ true, false ].include?(complete)
+        return [] unless complete
+
+        nve_members_by_vni = @configuration.fetch(:nve).fetch(:members, {})
+        vlan_mappings_by_vni = @configuration.fetch(:vlan_vnis).group_by { |_vlan, vni| vni }
+        vrf_vnis = @configuration.fetch(:vrfs).values.filter_map { |settings| settings[:vni] }.to_set
+        evpn_vnis = @configuration.fetch(:evpn)
+        findings = []
+        vlan_mappings_by_vni.each do |vni, entries|
+          next unless vni && !nve_members_by_vni.key?(vni)
+
+          findings << { code: :vlan_vni_without_nve, vni: vni, vlan_ids: entries.map(&:first).sort }
+        end
+        nve_members_by_vni.each do |vni, settings|
+          if settings[:associate_vrf]
+            findings << { code: :nve_l3_without_vrf, vni: vni } unless vrf_vnis.include?(vni)
+            next
+          end
+
+          findings << { code: :nve_l2_without_vlan, vni: vni } unless vlan_mappings_by_vni.key?(vni)
+          if @configuration[:nv_overlay_evpn] && !evpn_vnis.key?(vni)
+            findings << { code: :nve_l2_without_evpn, vni: vni }
+          end
+        end
+        evpn_vnis.each do |vni, settings|
+          member = nve_members_by_vni[vni]
+          if !member
+            findings << { code: :evpn_vni_without_nve, vni: vni }
+          elsif (settings[:type] == "l3") != member[:associate_vrf]
+            findings << { code: :vni_layer_conflict, vni: vni, evpn_type: settings[:type] }
+          end
+        end
+        @configuration.fetch(:vrfs).each do |name, settings|
+          next unless settings[:vni]
+          member = nve_members_by_vni[settings[:vni]]
+          code = member ? (!member[:associate_vrf] ? :vni_layer_conflict : nil) : :l3_vni_without_nve
+          findings << { code: code, vni: settings[:vni], vrf: name } if code
+        end
+        findings.sort_by { |finding| [ finding[:vni], finding[:code].to_s ] }
+      end
+    end
+  end
+end

data/lib/vxlan/{configuration.rb → config.rb}

@@ -5,7 +5,7 @@ require_relative "observation"
 
 module Vxlan
   # 配置与运行观测使用相同的平台、型号策略。
-  class Configuration
+  class Config
     # 按当前平台和型号选择 VXLAN 配置策略。
     def initialize(platform: :cisco_nxos, model: nil)
       @profile = ParserRegistry.fetch(platform, model: model)

data/lib/vxlan/fabric/review.rb

@@ -0,0 +1,327 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+require "json"
+require "digest"
+require_relative "../change_plan"
+require_relative "../acl_policy"
+require_relative "scope"
+require_relative "../service/catalog"
+require_relative "../service/mapping"
+require_relative "../config/evidence"
+require_relative "../subnet_index"
+
+module Vxlan
+  module Fabric
+    # 显式 Fabric 边界内比较已部署业务；设备角色和部署范围不由多数票推导。
+    class Review
+      # 比较范围由业务策略统一验证，审查器只负责组织规则与建议。
+      def initialize(documents, policy)
+        @documents = documents.to_h { |document| [ document.fetch("device").fetch("host"), document ] }
+        raise ArgumentError, "重复设备身份" unless @documents.size == documents.size
+        @scope = Scope.new(policy)
+      end
+
+      # 缺少任何成员的完整配置时仍报告覆盖，但不据此生成跨设备增量。
+      def call
+        @findings, @items, @coverage, @subnet_indexes = [], Hash.new { |hash, host| hash[host] = [] }, [], {}
+        inventory = @scope.coverage(@documents.keys)
+        finding("未归属", nil, "fabric_scope_unassigned", "已采集设备未纳入 Fabric 策略，跨设备审查未覆盖", inventory[:unassigned]) if inventory[:unassigned].any?
+        @scope.groups.each do |fabric, group|
+          configs = group.values.flatten.to_h { |host| [ host, configuration(host) ] }
+          unknown = configs.select { |_host, config| config.nil? }.keys
+          unless unknown.empty?
+            finding(fabric, nil, "fabric_evidence_incomplete", "成员配置证据不完整，停止该 Fabric 的变更推导", unknown)
+            next
+          end
+          %w[leaves borders].each do |role|
+            @role = role
+            review_group(fabric, configs.slice(*group[role]), all_configs: configs) if group[role].any?
+          end
+          @role = "spines"
+          group["spines"].each { |host| review_spine(fabric, host, configs.fetch(host)) }
+          @role = nil
+          review_subnets(fabric, configs)
+        end
+        { schema_version: 2, scope: "same_role_same_deployed_vni", inventory: inventory, findings: @findings, device_items: @items.to_h, coverage: @coverage }
+      end
+
+      private
+
+      # 配置完整性是关联缺失和规则对比的前提，运行表部分不影响完整配置比较。
+      def configuration(host)
+        Config::Evidence.complete_record(@documents[host])
+      end
+
+      # 每个 VNI 只纳入已映射此业务的 Leaf，未部署的 Leaf 仅记录覆盖范围。
+      def review_group(fabric, configs, all_configs:)
+        services = Service::Catalog.new(configs).services
+        policies = configs.transform_values do |config|
+          config.fetch("acls", {}).transform_values { |entries| AclPolicy.resolve(config, entries) }
+        end
+        services.sort.each do |vni, rows|
+          @coverage << { fabric: fabric, role: @role, vni: vni, deployed: rows.map { |row| row[:host] }.uniq, not_deployed: configs.keys - rows.map { |row| row[:host] }, incomplete: rows.select { |row| row[:missing].any? }.map { |row| row[:host] }.uniq }
+          incomplete = rows.select { |row| row[:missing].any? }
+          if incomplete.any?
+            finding(fabric, vni, "fabric_service_incomplete", "业务已开始部署，但 VLAN/NVE/EVPN 关联不完整", observations(incomplete) { |row| { missing: row[:missing] } })
+            review_missing_mappings(fabric, vni, rows, all_configs)
+          end
+          if rows.map { |row| row[:host] }.uniq.size != rows.size
+            finding(fabric, vni, "fabric_vlan_mapping_ambiguous", "同一 Leaf 将多个 VLAN 映射到相同 VNI", rows.map { |row| row.slice(:host, :vlan) })
+            next
+          end
+          next unless rows.size >= 2
+          constraints = review_transport(fabric, vni, rows)
+          service_blocked = incomplete.any? || constraints
+          # 缺映射行没有可定位 SVI，不能再扩散为网关、MTU 等一串伪差异。
+          rows = rows.select { |row| row[:vlan] }
+          next unless rows.size >= 2
+          compare(fabric, vni, "fabric_vlan_mapping", "相同 VNI 的本地 VLAN 编号不一致", rows) { |row| row[:vlan] }
+          # L2 业务没有网关可以是正常设计，但仍须检查承载与控制平面。
+          next unless rows.any? { |row| row[:svi] && (row[:svi]["anycast"] || row[:svi].fetch("addresses", []).any?) }
+          review_gateway(fabric, vni, rows, all_configs, service_blocked: service_blocked)
+          %w[in out].each { |direction| review_acl(fabric, vni, rows, direction, policies: policies, service_blocked: service_blocked) }
+          %w[vrf anycast mtu shutdown].each do |field|
+            compare(fabric, vni, "fabric_#{field}", "业务 SVI 的 #{field} 不一致", rows) { |row| row[:svi]&.fetch(field, nil) }
+          end
+          compare(fabric, vni, "fabric_anycast_mac", "Anycast 网关 MAC 不一致", rows) { |row| row[:config]["anycast_mac"] }
+        end
+        review_acl_catalog(fabric, configs, policies)
+        review_address_groups(fabric, configs)
+      end
+
+      # 已有 NVE/EVPN 的缺映射业务单独推导，不把不完整关联当作从未部署。
+      def review_missing_mappings(fabric, vni, rows, configs)
+        rows.select { |row| row[:missing] == [ "VLAN" ] }.each do |row|
+          evidence = observations(rows) { |peer| { missing: peer[:missing], gateway: peer[:svi]&.fetch("addresses", []), vrf: peer[:svi]&.dig("vrf") } }
+          item = recommendation(fabric, vni, "fabric_vlan_mapping_missing", "补齐已有业务的 VLAN/VNI 关联", evidence)
+          plan = Service::Mapping.infer(vni, row, rows)
+          change = plan&.to_h
+          conflicts = change ? gateway_conflicts(configs, change, except: [ row[:host], "Vlan#{change['vlan']}" ]) : []
+          if conflicts.any?
+            item[:evidence].concat(conflicts)
+            item[:blockers] << "同 VRF 存在跨 SVI/跨 VNI 网段重叠，不能通过新增映射扩大冲突：#{conflicts.map { |entry| "#{entry[:name]} #{entry[:interface]}" }.join('、')}"
+            plan = nil
+          end
+          if plan
+            local_svi = row[:config].fetch("interfaces").fetch("Vlan#{change['vlan']}")
+            item[:evidence] = evidence.map do |entry|
+              entry[:host] == row[:host] ? entry.merge(vlan: change["vlan"].to_s, value: { missing: [ "VLAN/VNI 映射" ], gateway: local_svi["addresses"], vrf: local_svi["vrf"] }) : entry
+            end
+            item[:impact] = "将已有 VLAN 接入既有 VXLAN 业务，可能立即扩展广播域；不创建 VLAN，不更改网关或 ACL。"
+            item[:prerequisites] << "本机未映射 VLAN 的网关、VRF、Anycast 身份及 ACL 与完整对端一致，NVE/EVPN 也已匹配；确认该业务确应在本机接入。"
+            item[:expected] = "本机 VLAN/VNI 关联完整、VNI 状态符合预期，既有网关及 ACL 保持不变；接入业务验收通过。"
+            item[:resolves] = [ { code: "nve_l2_without_vlan", vni: vni } ]
+            propose(item, plan, service_blocked: false)
+          else
+            item[:blockers] << "没有唯一且完整的业务对应关系；需核对本机未映射 VLAN、网关、VRF、ACL 与对端配置，禁止按 VNI 数值猜测 VLAN。"
+          end
+          @items[row[:host]] << item
+        end
+      end
+
+      # 一致性约束先于增量生成；承载/路由声明冲突时停止叠加网关和 ACL 变更。
+      def review_transport(fabric, vni, rows)
+        before = @findings.size
+        compare(fabric, vni, "fabric_replication", "NVE 复制方式或组播组声明不一致", rows) { |row| Service::Catalog.nve_member(row[:config], row[:nve])&.slice("replication", "multicast_group") }
+        compare(fabric, vni, "fabric_arp_suppression", "ARP 抑制的显式配置不一致", rows) { |row| row[:nve]&.fetch("suppress_arp", nil) }
+        compare(fabric, vni, "fabric_route_targets", "EVPN 导入/导出 RT 声明不一致，需核对路由互通与隔离", rows) do |row|
+          row[:evpn] && Service::Catalog.route_targets(row[:evpn]["route_targets"], asn: row[:config].dig("bgp", "asn"), vni: vni)
+        end
+        tenant_rows = rows.select { |row| row[:svi] && row[:svi]["vrf"] }
+        compare(fabric, vni, "fabric_tenant_routing", "共同业务的租户 VNI 或路由导入/导出声明不一致", tenant_rows) do |row|
+          Service::Catalog.tenant(row[:config], row[:svi]["vrf"])
+        end if tenant_rows.size >= 2
+        @findings.size > before
+      end
+
+      # Spine 角色的业务承载配置保留为待决项，不能自动补齐或删除疑似残留。
+      def review_spine(fabric, host, config)
+        services = Service::Catalog.new(host => config).services
+        return if services.empty?
+        evidence = [ { host: host, value: { role: "spines", l2_vnis: services.keys.sort } } ]
+        finding(fabric, nil, "fabric_role_conflict", "声明为 Spine，但存在 L2 业务承载配置", evidence)
+        item = recommendation(fabric, nil, "fabric_role_conflict", "核对 Spine 是否应承担业务 VTEP 职责", evidence)
+        item[:blockers] << "先确认角色或迁移残留；不能因为出现 NVE 就自动把 Spine 当作 Leaf，不能自动补业务配置或删除 NVE。"
+        @items[host] << item
+      end
+
+      # 网关不一致与地址迁移分开；未知目标不做替换，仅允许无冲突的缺失地址补齐。
+      def review_gateway(fabric, vni, rows, configs, service_blocked:)
+        values = rows.map { |row| row[:svi]&.fetch("addresses", [])&.sort }
+        return if values.uniq.one?
+        finding(fabric, vni, "fabric_gateway", "同业务网关地址不一致", observations(rows) { |row| row[:svi]&.fetch("addresses", []) })
+        expected = values.compact.reject(&:empty?).uniq
+        rows.each do |row|
+          next if expected.one? && row[:svi]&.fetch("addresses", [])&.sort == expected.first
+          item = recommendation(fabric, vni, "fabric_gateway", "网关地址需要一致", observations(rows) { |entry| entry[:svi]&.fetch("addresses", []) })
+          change = { "kind" => "svi_gateway_add", "vlan" => row[:vlan].to_i, "vni" => vni, "vrf" => row[:svi]&.dig("vrf"), "address" => expected.one? && expected.first.one? ? expected.first.first : nil }
+          context = rows.map { |entry| [ entry[:svi]&.dig("vrf"), entry[:svi]&.dig("anycast"), entry[:config]["anycast_mac"] ] }.uniq
+          conflicts = change["address"] ? gateway_conflicts(configs, change) : []
+          item[:evidence].concat(conflicts)
+          if conflicts.empty? && context.one? && context.first.all? && expected.one? && expected.first.one? &&
+              (plan = ChangePlan.candidate(change, config: row[:config]))
+            propose(item, plan, service_blocked: service_blocked)
+          else
+            item[:blockers] << "存在已有地址、跨 SVI/跨 VNI 网段冲突，或 VRF/Anycast 模式/MAC 不一致、缺少唯一网关；需先确认迁移设计，禁止重复添加网关。"
+            item[:blockers] << "Fabric 内冲突接口：#{conflicts.map { |conflict| "#{conflict[:name]} #{conflict[:interface]}" }.join('、')}" if conflicts.any?
+          end
+          @items[row[:host]] << item
+        end
+      end
+
+      # 目标机没有重复地址还不够；其他 Leaf 的跨 VNI 重叠同样阻止扩散网关。
+      def gateway_conflicts(configs, change, except: nil)
+        configs.flat_map do |host, config|
+          index = (@subnet_indexes[host] ||= SubnetIndex.new(config))
+          excluded = except&.first == host ? except.last : nil
+          index.conflicts(address: change["address"], vrf: change["vrf"], vni: change["vni"], except_interface: excluded).map do |entry|
+            { host: host, name: @documents[host]["device"]["name"], **entry }
+          end
+        end
+      end
+
+      # 无 ACL 不构成删除保护的基线；只从一致且已实际挂载的访问控制提出补齐。
+      def review_acl(fabric, vni, rows, direction, policies:, service_blocked:)
+        bindings = rows.map { |row| row[:svi]&.dig("acl_bindings", direction) }
+        definitions = rows.map { |row| name = row[:svi]&.dig("acl_bindings", direction); name && policies.dig(row[:host], name) }
+        different_binding = bindings.uniq.size > 1
+        different_content = definitions.uniq.size > 1 || bindings.zip(definitions).any? { |name, content| name && content.nil? }
+        return unless different_binding || different_content
+        evidence = observations(rows) do |row|
+          name = row[:svi]&.dig("acl_bindings", direction)
+          entries = name && row[:config].fetch("acls", {})[name]
+          policy = policies.dig(row[:host], name)
+          { acl: name, defined: !entries.nil?, entries: entries, policy_verified: !policy.nil?, address_groups: policy&.address_groups, digest: policy && ChangePlan.fingerprint(policy.to_h) }
+        end
+        code = different_binding ? "fabric_acl_binding" : "fabric_acl_content"
+        finding(fabric, vni, code, "#{direction} 方向 ACL 挂载/有序规则不一致", evidence)
+        undefined = evidence.select { |row| row[:value][:acl] && !row[:value][:defined] }
+        finding(fabric, vni, "fabric_acl_undefined", "#{direction} 方向已挂载 ACL，但本机没有对应定义", undefined) if undefined.any?
+        unresolved = evidence.select { |row| row[:value][:defined] && !row[:value][:policy_verified] }
+        finding(fabric, vni, "fabric_acl_dependency", "#{direction} 方向 ACL 依赖对象缺失、为空或尚未解析，不能证明策略一致", unresolved) if unresolved.any?
+        names = bindings.compact.uniq
+        sources = rows.select { |row| row[:config].fetch("acls", {})[names.first] }
+        originals = sources.map { |row| row[:config]["acls"][names.first] }
+        unique = sources.map { |row| policies.dig(row[:host], names.first) }.uniq
+        rows.each do |row|
+          current_name = row[:svi]&.dig("acl_bindings", direction)
+          current_entries = names.one? && row[:config].fetch("acls", {})[names.first]
+          next if names.one? && unique.one? && unique.first && current_name == names.first && policies.dig(row[:host], names.first) == unique.first
+          item = recommendation(fabric, vni, code, "统一 #{direction} 方向访问控制", evidence)
+          change = { "kind" => "svi_acl", "vlan" => row[:vlan].to_i, "vni" => vni, "direction" => direction,
+            "acl" => names.first, "entries" => originals.first, "create_acl" => current_entries.nil?, "previous_binding" => current_name }
+          change["address_groups"] = unique.first.address_groups if unique.one? && unique.first
+          context_matches = rows.map { |entry| entry[:svi]&.dig("vrf") }.uniq.one?
+          if names.one? && unique.one? && unique.first && context_matches &&
+              (plan = ChangePlan.candidate(change, config: row[:config]))
+            item[:prerequisites] << "依据是本业务已挂载且有序内容一致的 ACL；即使挂载节点较少，也不以无 ACL 的多数节点为删除依据。确认此业务应统一受该 ACL 保护。"
+            propose(item, plan, service_blocked: service_blocked)
+          else
+            item[:blockers] << "ACL 名称、有序规则、地址组成员、VRF 或当前绑定不能证明一致；需选择权威规则及完整依赖，不自动覆盖或撤销访问控制。"
+            shared = change["create_acl"] ? AclPolicy.bindings(row[:config], names.first) - [ { "interface" => "Vlan#{row[:vlan]}", "direction" => direction } ] : []
+            if shared.any?
+              references = shared.map { |binding| "#{binding['interface']} #{binding['direction']}" }.join("、")
+              item[:blockers] << "创建 #{names.first} 还会激活既有引用：#{references}。需合并所有受影响接口核对策略和回退，禁止作为单个 SVI 的补齐执行。"
+            end
+          end
+          @items[row[:host]] << item
+        end
+      end
+
+      # 同名 ACL 即使暂未挂载也报告规则债务，避免未来补挂时激活不同策略。
+      def review_acl_catalog(fabric, configs, policies)
+        names = configs.values.flat_map { |config| config.fetch("acls", {}).keys }.uniq.sort
+        names.each do |name|
+          rows = configs.filter_map do |host, config|
+            entries = config.fetch("acls", {})[name]
+            { host: host, entries: entries, semantics: policies.dig(host, name)&.rules || AclPolicy.rules(entries), policy: policies.dig(host, name)&.to_h } if entries
+          end
+          if rows.map { |row| row[:semantics] }.uniq.size > 1 || rows.map { |row| row[:policy] }.uniq.size > 1
+            finding(fabric, nil, "fabric_acl_content", "同名 ACL #{name} 的有序规则或依赖对象不同（包括尚未挂载的定义）", rows)
+          end
+          unknown = rows.select { |row| row[:policy].nil? }
+          finding(fabric, nil, "fabric_acl_dependency", "ACL #{name} 的依赖对象未验证，不能证明策略一致（包括尚未挂载的定义）", unknown) if unknown.any?
+        end
+      end
+
+      # 展开引用对象的成员差异，避免只展示相同的 ACL 文本而隐藏实际匹配范围。
+      def review_address_groups(fabric, configs)
+        # 每台设备的引用去重后直接归入对象索引，避免每个对象再扫描所有引用。
+        references = {}
+        configs.each do |host, config|
+          names = config.fetch("acls", {}).values.flatten.flat_map { |entry| entry["expression"].scan(/\baddrgroup\s+(\S+)/).flatten }.uniq
+          names.each { |name| (references[name] ||= []) << { host: host, value: config.fetch("address_groups", {})[name] } }
+        end
+        references.sort.each do |name, rows|
+          next unless rows.map { |row| row[:value] }.uniq.size > 1
+          finding(fabric, nil, "fabric_address_group", "ACL 地址组 #{name} 成员不同或缺失；仅比较引用此对象的业务，不自动复制", rows)
+        end
+      end
+
+      # 同 VRF 内按规范网段区间扫描，保留跨 VNI 的包含关系；同网段多台证据先合并。
+      def review_subnets(fabric, configs)
+        subnets = Hash.new { |hash, key| hash[key] = [] }
+        configs.each do |host, config|
+          config.fetch("interfaces", {}).each do |name, svi|
+            next unless name.match?(/\AVlan\d+\z/) && svi["anycast"]
+            vni = config.fetch("vlan_vnis", {})[name.delete_prefix("Vlan")]
+            next unless vni
+            svi.fetch("addresses", []).each do |address|
+              network = IPAddr.new(address)
+              subnets[[ svi["vrf"], network.ipv4?, network.to_i, network.to_range.last.to_i ]] << { host: host, interface: name, vni: vni, address: address }
+            end
+          end
+        end
+        subnets.group_by { |(vrf, ipv4, _start, _finish), _rows| [ vrf, ipv4 ] }.each do |(vrf, _ipv4), networks|
+          active = []
+          networks.sort_by { |(key, _rows)| key[2] }.each do |key, rows|
+            active.reject! { |other_key, _other_rows| other_key[3] < key[2] }
+            conflicts = active.filter_map do |_other_key, other_rows|
+              combined = other_rows + rows
+              combined if combined.map { |row| row[:vni] }.uniq.size > 1
+            end
+            conflicts << rows if rows.map { |row| row[:vni] }.uniq.size > 1
+            conflicts.each do |evidence|
+              finding(fabric, nil, "fabric_subnet_vni_conflict", "VRF #{vrf} 的网段在不同 VNI 上重叠，需核对迁移或隔离设计", evidence)
+            end
+            active << [ key, rows ]
+          end
+        end
+      end
+
+      # 属性比较保留各叶节点值；显式缺失与 nil 不静默套用设备默认值。
+      def compare(fabric, vni, code, title, rows, &value)
+        evidence = observations(rows, &value)
+        finding(fabric, vni, code, title, evidence) if evidence.map { |row| row[:value] }.uniq.size > 1
+      end
+
+      # 观察附带设备名、地址及本地 VLAN，报告可直接定位配置入口。
+      def observations(rows)
+        rows.map { |row| { host: row[:host], name: @documents[row[:host]]["device"]["name"], vlan: row[:vlan], value: yield(row) } }
+      end
+
+      # 按业务问题计数，不把证据行数当作问题数量。
+      def finding(fabric, vni, code, title, evidence)
+        @findings << { fabric: fabric, role: @role, vni: vni, code: code, title: title, evidence: evidence }
+      end
+
+      # 与单设备报告共享建议字段，跨设备来源完整保留。
+      def recommendation(fabric, vni, code, title, evidence)
+        { code: code, category: "fabric", scope: "#{fabric} / #{@role} / #{vni ? "VNI #{vni}" : '角色核查'}", title: title, status: "blocked", evidence: evidence,
+          prerequisites: [ "仅在本 Fabric、相同已部署业务范围内适用；核对业务访问策略与维护窗口。", "下发前重新读取配置，任何变化均使计划过期；逐设备逐项确认，不批量重放。" ], blockers: [],
+          commands: [], rollback: [], verify: [ "show running-config", "show nve vni", "show ip interface brief vrf all" ],
+          impact: "改变网关或 ACL 可能改变可达性及业务隔离；配置回读通过后仍需业务验收。", expected: "共同业务的网关和访问控制一致，允许/拒绝流量均符合设计。", references: [] }
+      end
+
+      # 类型化增量才可导出可交互执行的计划，冲突项只有证据和待确认信息。
+      def propose(item, plan, service_blocked:)
+        if service_blocked
+          item[:blockers] << "共同业务的承载关联或复制/路由声明存在冲突，先解决这些前置问题，再生成网关或 ACL 增量。"
+          return
+        end
+        item.merge!(status: "candidate", change: plan.to_h, commands: plan.commands, rollback: plan.rollback)
+      end
+    end
+  end
+end

data/lib/vxlan/fabric/scope.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+require "ctx_parser/immutable"
+
+module Vxlan
+  module Fabric
+    # Fabric 与角色是业务边界，名称和地址相似不能替代显式成员声明。
+    class Scope
+      ROLES = %w[leaves borders spines].freeze
+      attr_reader :groups
+
+      # 在入口验证唯一归属；允许单角色为空，但 Fabric 至少有两个成员。
+      def initialize(policy)
+        unless policy.is_a?(Hash) && policy.keys == [ "fabrics" ] && policy["fabrics"].is_a?(Hash) && policy["fabrics"].any?
+          raise ArgumentError, "需要 fabrics 策略"
+        end
+        @groups = policy["fabrics"].to_h do |name, group|
+          unless name.is_a?(String) && !name.empty? && group.is_a?(Hash) && (group.keys - ROLES).empty? && group.any?
+            raise ArgumentError, "Fabric 需要明确的角色成员清单"
+          end
+          roles = ROLES.to_h do |role|
+            hosts = group.fetch(role, [])
+            raise ArgumentError, "角色成员须为地址列表" unless hosts.is_a?(Array)
+            hosts.each { |host| raise ArgumentError, "成员地址无效" unless host.is_a?(String) && !host.include?("/") && IPAddr.new(host).to_s == host }
+            [ role, CtxParser::Immutable.copy(hosts) ]
+          end
+          raise ArgumentError, "Fabric 至少需要两个成员" unless roles.values.flatten.size >= 2
+          [ name, roles.freeze ]
+        end.freeze
+        raise ArgumentError, "成员不能重复、跨角色或跨 Fabric" unless hosts.uniq == hosts
+      end
+
+      # 扁平成员集合用于覆盖核对，不改变角色内的比较范围。
+      def hosts = groups.values.flat_map { |roles| roles.values.flatten }
+
+      # 未采集与未纳入是两种不同缺口，均不能被无发现掩盖。
+      def coverage(observed_hosts)
+        { groups: groups, assigned: hosts & observed_hosts, unassigned: observed_hosts - hosts, missing: hosts - observed_hosts }
+      end
+    end
+  end
+end

data/lib/vxlan/observation.rb

@@ -22,5 +22,8 @@ module Vxlan
     # 展示对象身份与状态，避免泄露原始回显或凭据。
     def inspect = "#<#{self.class.name} name=#{name} status=#{status} records=#{records.size}>"
     alias to_s inspect
+
+    # PP 默认展开 Data 成员，显式沿用脱敏展示。
+    def pretty_print(printer) = printer.text(inspect)
   end
 end

data/lib/vxlan/recommendations.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require_relative "cisco_nxos/profile"
+require_relative "config/evidence"
+
+module Vxlan
+  # 对持久化事实生成可审阅建议；不持有连接器，不下发配置，不推断跨设备 Fabric 归属。
+  class Recommendations
+    REFERENCE = "https://www.cisco.com/c/en/us/td/docs/dcn/nx-os/nexus9000/103x/configuration/vxlan/cisco-nexus-9000-series-nx-os-vxlan-configuration-guide-release-103x/m_configuring_vxlan_bgp_evpn.html"
+    TITLES = {
+      "vlan_vni_without_nve" => "VLAN 已映射 VNI，但缺少 NVE 成员",
+      "nve_l2_without_vlan" => "L2 NVE 成员缺少 VLAN 映射",
+      "nve_l2_without_evpn" => "L2 NVE 成员缺少 EVPN 配置",
+      "nve_l3_without_vrf" => "L3 NVE 成员缺少 VRF 关联",
+      "evpn_vni_without_nve" => "EVPN VNI 缺少 NVE 成员",
+      "vni_layer_conflict" => "VNI 的 L2/L3 属性冲突",
+      "l3_vni_without_nve" => "VRF VNI 缺少 NVE 成员"
+    }.freeze
+
+    # 联合证据可以解决本机未知，但角色冲突优先阻断所有草稿；不改变原始发现。
+    def self.combine(local, supplemental)
+      supplemental = Array(supplemental)
+      resolved = supplemental.select { |item| item[:status] == "candidate" }.flat_map { |item| item.fetch(:resolves, []) }
+      items = local[:items].reject { |item| resolved.include?(item.slice(:code, :vni)) } + supplemental
+      conflict = supplemental.find { |item| item[:code] == "fabric_role_conflict" }
+      if conflict
+        items = items.map do |item|
+          next item unless item[:status] == "candidate"
+          item.reject { |key, _| key == :change }.merge(status: "blocked", commands: [], rollback: [], blockers: item.fetch(:blockers, []) + conflict[:blockers])
+        end
+      end
+      local.merge(items: items, counts: items.map { |item| item[:status] }.tally)
+    end
+
+    # 输入为报告 JSON 的字符串键结构，离线与实时报告共用此边界。
+    def initialize(document)
+      @document = document
+      @dimensions = document.dig("snapshot", "dimensions") || {}
+    end
+
+    # 建议与采集完整性分开；没有命中规则并不代表网络健康。
+    def call
+      items = evidence_tasks
+      config = Config::Evidence.complete_record(@document)
+      if config
+        items.concat(config.fetch("review_findings", []).map { |finding| configuration_item(config, finding) })
+        items.concat(undefined_acl_items(config))
+      end
+      items.concat(runtime_tasks)
+      { schema_version: 1, review_only: true, health_assessment: "not_performed", device: @document["device"],
+        observed_at: @document.dig("snapshot", "observed_at"), items: items, counts: items.map { |item| item[:status] }.tally }
+    end
+
+    private
+
+    # 无 VNI、无网关的残留接口也保留悬空引用，不能由共同业务筛选掩盖。
+    def undefined_acl_items(config)
+      config.fetch("interfaces", {}).flat_map do |name, interface|
+        interface.fetch("acl_bindings", {}).filter_map do |direction, acl|
+          next if config.fetch("acls", {}).key?(acl)
+          result = item("acl_reference_undefined", "#{name} / #{direction}", "接口引用 ACL #{acl}，本机缺少定义",
+            evidence: { interface: name, direction: direction, acl: acl, addresses: interface.fetch("addresses", []), vlan_vni: config.fetch("vlan_vnis", {})[name.delete_prefix("Vlan")] },
+            verify: [ "show running-config", "show ip interface brief vrf all" ])
+          result[:blockers] << "先确认接口是否承载业务及 ACL 的权威定义；无地址或无 VNI 可能是残留配置，不能直接推断业务中断，也不能按名称复制其他 Fabric 的 ACL。"
+          result[:impact] = "新增 ACL 定义会作用于本机所有同名引用；须核对全部引用及回退范围。"
+          result[:references] = []
+          result
+        end
+      end
+    end
+
+    # 建议只保存有关事实，不复制整份配置或敏感命令正文。
+    def item(code, scope, title, evidence:, verify:, category: "configuration")
+      { code: code, scope: scope, title: title, category: category, status: "blocked", evidence: evidence,
+        prerequisites: [], blockers: [], commands: [], rollback: [], verify: verify,
+        expected: "重新采集并核对该项事实；业务连通性须另行验收。", references: [ REFERENCE ] }
+    end
+
+    # 仅在完整配置证实关联缺失时讨论增量补齐，不自动删除疑似闲置配置。
+    def configuration_item(config, finding)
+      vni = finding["vni"]
+      result = item(finding["code"], "VNI #{vni}", TITLES.fetch(finding["code"], "配置关联需要核查"),
+        evidence: finding, verify: [ "show running-config", "show nve vni", "show nve peers", "show bgp l2vpn evpn summary" ])
+      result[:vni] = vni
+      result[:prerequisites] = [ "确认该 VNI 应在本机承载业务，而非预配置或退网残留。", "核对当前软件版本、设备角色、同 Fabric 对端的 VLAN/VNI、RD/RT 与复制方式。", "重新采集配置并确认与本报告一致；审批维护窗口后逐台操作，出现异常先回读，勿盲目重放。" ]
+      result[:impact] = "补齐可能开始发布路由或扩展二层广播域；须核对隔离边界、对端配置和回退条件。"
+      result[:expected] = "VLAN、NVE 与 EVPN 关联一致；预期承载业务的 VNI 状态 Up，BGP/对端正常，业务验收通过。"
+      unless vni.is_a?(Integer) && vni.between?(1, 16_777_215)
+        result[:blockers] << "VNI 非有效整数，无法生成命令。"
+        return result
+      end
+      vlans = config.fetch("vlan_vnis", {}).select { |_vlan, mapped| mapped == vni }.keys
+      nve = config.fetch("nve", {})
+      member = nve.fetch("members", {})[vni.to_s]
+      evpn = config.fetch("evpn", {})[vni.to_s]
+      result[:evidence] = finding.merge("vlan_ids" => vlans, "nve_member" => member, "evpn" => evpn)
+      case finding["code"]
+      when "nve_l2_without_evpn"
+        if l2_context?(config, vni, vlans) && member && member["associate_vrf"] == false && member["replication"] == "bgp" && !evpn && auto_policy?(config)
+          candidate(result, evpn_add(vni), evpn_remove(vni), "本机现有 L2 EVPN 均采用 RD auto、RT import/export auto；候选沿用此模式，仍需确认本 VNI 的业务意图。")
+        else
+          result[:blockers] << "需要唯一 VLAN 映射、L2 BGP 复制以及一致的 RD/RT 策略；缺失或冲突时不能套用 auto。"
+        end
+      when "vlan_vni_without_nve", "evpn_vni_without_nve"
+        if l2_context?(config, vni, vlans) && !member && bgp_replication?(nve) && (evpn ? auto_evpn?(evpn) : auto_policy?(config))
+          commands = [ "interface #{nve['interface']}", "  member vni #{vni}", "    ingress-replication protocol bgp", "exit", "exit" ]
+          rollback = [ "interface #{nve['interface']}", "  no member vni #{vni}", "exit" ]
+          commands.concat(evpn_add(vni)) unless evpn
+          rollback.concat(evpn_remove(vni)) unless evpn
+          candidate(result, commands, rollback, "本机既有 L2 成员统一使用 BGP 复制、EVPN auto 策略；仅补齐缺失的 NVE/EVPN，不启用额外 ARP 抑制。")
+        else
+          result[:blockers] << "需确认 VNI 的 L2/L3 角色、VLAN、NVE 接口、复制模式和 RD/RT，当前不能唯一确定增量配置。"
+        end
+      when "nve_l2_without_vlan"
+        result[:blockers] << "请提供本 VNI 对应 VLAN ID，并核对 access/trunk/SVI；不能由 VNI 尾数或其他设备名称猜测。"
+        result[:template] = [ "vlan <VLAN_ID>", "  vn-segment #{vni}" ]
+      else
+        result[:blockers] << "需要明确 VRF/VNI 业务映射和 L2/L3 角色；先核对设计，再补齐或清理残留配置。"
+      end
+      result
+    end
+
+    # 同一 VNI 只能有一个有效 VLAN，且不能同时属于 VRF。
+    def l2_context?(config, vni, vlans)
+      nve = config.fetch("nve", {})
+      config["nv_overlay_evpn"] == true && nve["shutdown"] == false && nve["host_reachability"] == "bgp" &&
+        nve["interface"].to_s.match?(/\Anve[1-9]\d*\z/i) && vlans.size == 1 && vlans.first.match?(/\A\d+\z/) && vlans.first.to_i.between?(1, 4094) &&
+        config.fetch("vrfs", {}).values.none? { |vrf| vrf["vni"] == vni }
+    end
+
+    # 仅识别本机全部 L2 EVPN 都使用显式 auto 的情况，不推断跨 ASN 策略。
+    def auto_policy?(config)
+      policies = config.fetch("evpn", {}).values.select { |settings| settings["type"] == "l2" }
+      policies.any? && policies.all? { |settings| auto_evpn?(settings) }
+    end
+
+    # 正反方向必须同时存在且没有额外定制 RT。
+    def auto_evpn?(settings)
+      targets = settings.fetch("route_targets", [])
+      settings["type"] == "l2" && settings["rd"] == "auto" && targets.size == 2 &&
+        targets.map { |rt| rt["direction"] }.sort == %w[export import] &&
+        targets.all? { |rt| rt["target"] == "auto" && rt["evpn"] == false }
+    end
+
+    # 混合组播或静态复制时不生成 BGP 复制候选。
+    def bgp_replication?(nve)
+      members = nve.fetch("members", {}).values.reject { |settings| settings["associate_vrf"] }
+      members.any? && members.all? { |settings| settings["replication"] == "bgp" && !settings["multicast_group"] }
+    end
+
+    # NX-OS L2 EVPN 子模式增量；不包含保存配置命令。
+    def evpn_add(vni)
+      [ "evpn", "  vni #{vni} l2", "    rd auto", "    route-target import auto", "    route-target export auto", "exit", "exit" ]
+    end
+
+    # 只删除本候选新增的子节点，保留既有全局配置。
+    def evpn_remove(vni) = [ "evpn", "  no vni #{vni} l2", "exit" ]
+
+    # 候选仍需人工确认业务意图，不能作为自动变更许可。
+    def candidate(result, commands, rollback, assumption)
+      result[:status] = "candidate"
+      result[:prerequisites] << assumption
+      result[:commands] = [ "configure terminal", *commands, "end" ]
+      result[:rollback] = [ "configure terminal", *rollback, "end" ]
+    end
+
+    # 空或部分证据只生成重新采集任务，不按缺失配置处理。
+    def evidence_tasks
+      selected = @dimensions.reject { |name, _| name == "collection" }
+      selected = { "configuration" => { "status" => "not_requested" } } if selected.empty?
+      selected.filter_map do |name, observation|
+        next if observation["status"] == "complete" && (name != "configuration" || Config::Evidence.complete_record(@document))
+        evidence = { status: observation["status"], issues: observation.fetch("issues", []).map { |issue| issue["code"] } }
+        if name == "configuration"
+          records = observation.fetch("records", [])
+          evidence.merge!(configuration_records: records.size, review_status: records.map { |record| record["review_status"] })
+        end
+        item("evidence_incomplete", name, "证据不完整，先补采", evidence: evidence,
+          verify: Array(CiscoNxos::Profile::COMMANDS[name.to_sym]), category: "evidence").merge(status: "investigate", expected: "完整回显或明确的零记录证明；空响应不能等同无配置。")
+      end
+    end
+
+    # 运行异常只生成定位建议；Down 也可能是计划停用，不能自动 no shutdown。
+    def runtime_tasks
+      %w[nve_vnis nve_peers bgp_neighbors].filter_map do |dimension|
+        rows = @dimensions.fetch(dimension, {}).fetch("records", []).select { |row| %w[down idle active connect opensent openconfirm].include?(row["state"].to_s.downcase) }
+        next if rows.empty?
+        item("#{dimension}_not_up", dimension, "观测到未建立的运行状态", evidence: rows,
+          verify: [ CiscoNxos::Profile::COMMANDS[dimension.to_sym], "show running-config" ], category: "runtime").merge(status: "investigate", prerequisites: [ "先确认业务预期，再检查对端、底层路由、接口和配置；不自动重启邻居或启用接口。" ])
+      end
+    end
+  end
+end