wireless-rb 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e202198d7c272a5d1463d5bfd91fb56057d440783d3e11f2316187673d296be3
-  data.tar.gz: 2ce8943f91535c5950cc3ae0bec031edf5a5564debbfaaae1770938b2ebf9962
+  metadata.gz: 4da8d6c74654151d449ed7c71366f5ad2335b84a59caee076a1bc07ca49497b3
+  data.tar.gz: 6c2601cb0b091843987c26e68bfa4eea4f978ab457b99902ed4a04e4adf7cc24
 SHA512:
-  metadata.gz: d4eacfd2e94f6228d10e230f4ad2b44bf103c835cc89463cbee4734db266589f8767f4a01cbafddf39b510c51e7b84cd841b5ea26818ba39278372630b42e4fe
-  data.tar.gz: 7bb9649c07bb3b7d580ba47779ac10183a5df6d112500391db9853749b8a156b24ccce8e422836d4b677e0f85e70356b6908afdc02289f66c8f9d75d734f33ce
+  metadata.gz: 1992172ce7c985fb4afc713a956b69ea84c902edd58e576be928384ec346e136bbc6b978de677323d651514103ee3cbc4c6113edbbe710dafa404b6a9bc6f772
+  data.tar.gz: fe4ac1f5ed1b1a9084409167f7aeae5953cfbbf321c8d7226d0a9a4be96c50731cfff96858d086c42854b2d244c74ea50fc92f9c81e6e4b3c9b2a27dad8323dc

data/CHANGELOG.md

@@ -2,6 +2,55 @@
 
 Changes to the public contract are recorded here. Versions follow Semantic Versioning.
 
+## 0.2.0 (2026-10-17)
+
+- Route Huawei commands through Profile and standard Parser contracts, and validate caller arguments before reading output. Keep malformed device bodies as failed observations.
+- Share terminal rejection detection across platforms.
+
+- Keep AP login, queries, return verification, and failure close within one borrowed controller operation; never quit from the controller or an unexpected prompt.
+- Leave busy controllers untouched, propagate cancellation, preserve independent cleanup/close failures, and require net-connector 0.11.1 for the optional AP adapter.
+- Skip AP credential and adapter setup for empty inventories; keep AP setup errors separate from controller connection failures.
+
+- Snapshot controller identity and AP selection before external session callbacks can mutate caller-owned inputs.
+- Remove the mandatory net-connector dependency and default AP adapter loading; inject AP readers through `Collector.new(ap_session:)` and load `wireless/ap_session` explicitly when needed.
+- Use the current shared parser and driver APIs without version constraints in the gemspec; applications own their deployment lockfiles.
+- Reject pagination and editing controls before parsing H3C/Huawei runtime facts; retain damaged configuration source lines and mark their enclosing captures incomplete.
+
+- Use the shared `CtxParser::Configuration`, `Results`, and `Commands` names and dimension indexes where applicable.
+
+- Simplify H3C parsing to `Parser` and `RecordParser`, with shared `Authentication` field definitions; retain device-command parser names.
+- Name H3C source documents `H3c::Document`, group Huawei parsing under `Huawei::Profile` and command-mapped `Huawei::Parsers`, and use `RuntimeParser` directly for H3C observations.
+- Reject numeric overflow in measurements and rate conversions while retaining unrelated client facts.
+
+- Rename domain APIs directly; callers must use the new names (no compatibility aliases).
+
+- Expose seconds, Mbps, and MHz in measurement conversion names; keep ambiguous channel-only band evidence unknown.
+
+- Name private collection operations by their scope: controller commands, AP neighbor batches, and individual AP neighbor reads.
+- Breaking: map H3C AP/client online duration to `online_seconds`, and reserve AP `uptime_seconds` for the separate system uptime field.
+- Preserve explicit composite authentication modes and opaque LLDP chassis identities instead of reducing their meaning.
+
+### Fixed
+
+- Keep repeated Radio capability labels within their VHT, HT, HE MCS, or operational-rate subsection; accept documented BSSID and bandwidth aliases.
+- Keep Radio coverage incomplete when an AP has no reported Radio evidence; AP counts only establish the AP inventory.
+- Validate compound channel settings before assignment, and clear all related flags when channel or MAC username-format declarations conflict.
+- Bind AP LLDP captures and evidence to the requested command and AP identity, rejecting contradictory skipped-success receipts.
+
+- Reject conflicting or malformed totals and conflicting converted runtime fields; ambiguous fields cannot be restored by later declarations.
+- Reject contradictory singleton settings within a configuration block, retain invalid source locations, and stop ambiguous authentication derivation.
+- Preserve wireless declarations under unknown parent scopes as incomplete evidence instead of claiming an empty configuration.
+- Validate authentication modes, explicit IP address families, and VLAN membership ranges; keep domain references separate from authentication activation.
+- Index configuration entities, template bindings, and AP name selection; append LLDP descriptions without repeated whole-string copies.
+- Traverse unsupported configuration trees iteratively instead of consuming the Ruby call stack.
+- Keep observation, snapshot, and projection display strings metadata-only; validate observation identities and detach snapshot hash defaults.
+- Keep empty coverage scopes unknown and reject non-finite freshness windows.
+- Snapshot platform/model before callbacks and prevent AP credentials from replacing the borrowed controller session.
+
+- Recognize unsupported command responses at line boundaries without interpreting SSIDs or banner text as errors.
+- Keep paginated or damaged configurations and their source captures incomplete.
+- Copy validated AP credentials so later caller mutation cannot alter login interactions.
+
 ## 0.1.0 (2026-10-16)
 
 ### Added

data/README-zh.md

@@ -21,7 +21,7 @@ gem "wireless-rb", require: "wireless"
 
 然后执行 `bundle install`；也可直接执行 `gem install wireless-rb`。Ruby 加载入口为 `wireless`，公开命名空间为 `Wireless`；gem 包名与 Ruby 命名空间分别维护。
 
-模块运行依赖：[`ctx_parser`](https://github.com/gatework/ctx_parser), [`ctx_driver`](https://github.com/gatework/ctx_driver), [`net-connector`](https://github.com/gatework/net-connector)。 gemspec 的运行依赖不添加版本约束；应用应提交自己的 `Gemfile.lock`，保持部署可复现。使用本库不需要启动 Rails 或配置兄弟模块的本地路径。
+模块使用 [`ctx_parser`](https://github.com/gatework/ctx_parser) 和 [`ctx_driver`](https://github.com/gatework/ctx_driver)，gemspec 不限定依赖版本。离线解析及注入控制器会话的采集均不安装或加载 `net-connector`。应用应提交自己的 `Gemfile.lock`，保持部署可复现；使用本库不需要启动 Rails 或配置兄弟模块的本地路径。
 
 发布产物和校验值见 [GitHub Releases](https://github.com/gatework/wireless-rb/releases)，已发布版本以 [RubyGems](https://rubygems.org/gems/wireless-rb) 为准。
 
@@ -67,18 +67,51 @@ end
 
 ## 公开契约与限制
 
+非法平台、型号、维度参数及非布尔 `complete` 抛出 `ArgumentError`；设备正文格式错误返回失败观测。
+
 `Configuration.new.parse(text, complete: false)` 解析控制器配置。`RuntimeParser.new(model: nil).parse(name, text, platform: "h3c", complete: false)` 解析单个运行维度；`parse_many` 为同一命令的多个维度共享解析。`NeighborParser` 为邻居观察补充 AP 上下文。
 
 输入完整性由调用方确认。未知语法、身份重复、数量矛盾和截断输出保持部分或失败。配置中的最大发射功率不能当作当前测量功率；PSK、密码、认证 URL 不可进入快照。
 
-`Collector#collect(connector:, target:, platform:, model: nil, dimensions:, ap_connection: nil, ap_names: [])` 使用注入的 connector。内置 `ApSession` 通过显式运行依赖 `net-connector` 处理中转会话；请求 LLDP 时必须通过 `ap_connection` 显式提供 AP 凭据。宿主负责设备身份和连接设置，解析器不会推断 AP console 开启或 AP 凭据。Rails 库存投影、锁、加密、API 和 `Wireless::Sync` 属于宿主，不随本 gem 发布。
+`Collector#collect(connector:, target:, platform:, model: nil, dimensions:, ap_connection: nil, ap_names: [])` 使用宿主注入的 connector，普通采集仅要求会话提供 `connected?` 和 `send_commands`。AP LLDP 通过 `Collector.new(ap_session: factory)` 显式注入；factory 接收 `controller:` 和按需解析的 `ap_connection` 关键字，返回提供 `read(access_point:)` 的对象。需要查询 AP 但未注入工厂时，仅 LLDP 返回 `ap_session_required`，不读取 AP 凭据，也不影响控制器清单。
+
+内置 AP 登录适配器可选使用。宿主须自行声明 `gem "net-connector", "~> 0.11.1", require: false`，并显式加载和注入：
+
+```ruby
+require "wireless"
+require "wireless/ap_session"
+
+collector = Wireless::Collector.new(
+  ap_session: ->(controller:, **credentials) { Wireless::ApSession.new(controller: controller, **credentials) }
+)
+```
+
+适配器要求通过 `ap_connection` 显式提供 AP 密码，可选用户名；自定义适配器可自行管理凭据。`read` 返回包含 `result: CtxDriver::Capture`、可选 `error:` / `cleanup_error:` / `close_error:` 和 `skipped:` 的 Hash。控制器和 AP 凭据、会话生命周期归宿主或适配器管理，解析器不推断 AP console 或凭据。
+
+AP 接入复用已连接的控制器及其操作租约，不另建 AP 传输连接。登录、只读查询、确认返回及失败关闭都在同一租约中；控制器忙碌时不关闭或破坏其他操作。只有仍处于已确认的 AP 提示符时才发送 `quit`，取消继续传播，退出与关闭故障独立保留。空 AP 清单不解析凭据，也不创建适配器。
 
 详细厂商语义、历史验证记录和 Motor 专用集成说明保留在[架构参考](docs/architecture-zh.md)。其中宿主集成代码需要 Motor，不属于独立 gem API。适配层位于 [Motor 仓库](https://github.com/gatework/motor/tree/main/backend/lib) 的 `backend/lib/baseline`、`backend/lib/vxlan` 和 `backend/lib/wireless`。
 
 生命周期 connector 是宿主适配器，提供 `open { |session| }`，VXLAN 和 Wireless 还要求 `platform`；原生 `Net::Connector::Base` 实例并不提供这一宿主生命周期协议。已连接的原生会话可传入 `CtxDriver::Reader` 或 `CtxChecker::Collector#collect_session`，不会隐式连接或重试。
 
+运行字段或同一配置声明块内的单值设置发生冲突时，移除歧义事实，相关来源保持不完整；同块后续声明不能恢复该值。独立的顺序配置块保留各自的来源快照。未知父级下的无线声明不能被当作空配置。观测名称必须为 Symbol，显示字符串只含元数据。空覆盖范围保持未知，新鲜度时间窗必须为有限非负数。
+
+## 领域术语
+
+H3C `Online time` 保存为 `online_seconds`，AP 的 `System uptime` 保存为 `uptime_seconds`，两者对应[不同的设备字段](https://www.h3c.com/cn/d_202606/2850182_30005_0.htm)。显式认证模式优先于域引用；组合和回退模式保留顺序，不归并为单一认证方式，依据 [H3C 认证命令参考](https://www.h3c.com/en/d_202106/1418918_294551_0.htm)。LLDP 的不透明机箱标识保留大小写，明确为 MAC 类型时才归一化。
+
+H3C 命令解析器使用 `H3c::Parser` 校验命令回显，使用 `H3c::RecordParser` 读取带字段标签的记录。`H3c::Authentication` 复用认证字段定义，`H3c::Document` 保留配置来源行；Huawei 使用 `Huawei::Profile` 和 `Huawei::Parsers` 命令解析器，遵循相同参数契约。
+
+AP、射频、BSS 和关联客户端具有不同身份。测量转换方法明确返回单位：`Fields.duration_seconds`、`Fields.rates_mbps`、`Fields.channel_width_mhz`。`Fields.frequency_band` 需要无歧义的频段标签或频段专属 PHY 证据；仅有信道号或通用 `802.11ax` 标签时保持未知。参见 [Cisco 的 6 GHz 信道示例](https://www.cisco.com/c/en/us/support/docs/wireless/catalyst-9166-series-access-points/220526-configure-and-verify-wi-fi-6e-band-opera.html)。
+
+Radio 能力详情按子节保存：`details[:vht_mcs]`、`[:ht_mcs]`、`[:he_mcs]` 和 `[:operational_rates]` 分别拥有 `supported`、`mandatory` 等同名标签。AP 总数只证明 AP 覆盖；缺少 Radio 回显的 AP 会使 Radio 视图保持不完整，AP 视图仍可完整。AP LLDP 适配器须返回对应命令的回执，AP 身份和尝试状态由采集器确定。
+
+`authentication_type` 是已识别认证配置的摘要。PSK 与 Portal 等可叠加机制分别保留在 `configuration[:akm_modes]` 和 `configuration[:portal]`；核查全部启用机制的基线应读取这些字段。
+
 ## 开发与测试
 
+共享类按实际职责命名，平台信息放在命名空间中。直接对应设备命令的解析器保留文件名和类名。
+
 ```sh
 bundle install
 bundle exec rake
@@ -90,6 +123,8 @@ bundle exec rake build
 
 使用声明的最低 Ruby 版本检查兼容性。方法用途统一使用简明中文注释；复杂实现还需说明业务规则、实现思路及关键分支。保持公开返回值与错误契约。真实回显和凭据不可进入示例、fixture、日志或发布包。
 
+运行 `bundle exec ruby -Ilib benchmark/tables.rb`，比较 500、2,000、5,000 条合成模板、绑定及 LLDP 续行的本地开销。每组核对解析结果，报告三次采样中最快的耗时和对象分配数；这些结果不代表设备或网络性能。
+
 ## 发布
 
 本目录可独立维护为 [wireless-rb](https://github.com/gatework/wireless-rb) 仓库。更新 `VERSION` 和 `CHANGELOG.md`，运行上述验证与构建命令，检查包内文件，再创建 `vVERSION` 标签。

data/README.md

@@ -21,7 +21,7 @@ gem "wireless-rb", require: "wireless"
 
 Then run `bundle install`, or install directly with `gem install wireless-rb`. The require path is `wireless` and the public namespace is `Wireless`; package names and Ruby namespaces are intentionally separate.
 
-Internal runtime dependencies: [`ctx_parser`](https://github.com/gatework/ctx_parser), [`ctx_driver`](https://github.com/gatework/ctx_driver), [`net-connector`](https://github.com/gatework/net-connector). The gemspec declares runtime dependencies without version constraints. Applications should commit their own `Gemfile.lock` to make deployments reproducible. No Rails boot or sibling checkout paths are required.
+Runtime dependencies include [`ctx_parser`](https://github.com/gatework/ctx_parser) and [`ctx_driver`](https://github.com/gatework/ctx_driver), without version constraints in the gemspec. Offline parsing and injected controller collection do not install or load `net-connector`. Applications should commit their own `Gemfile.lock` to make deployments reproducible. No Rails boot or sibling checkout paths are required.
 
 Release artifacts and checksums are available from [GitHub Releases](https://github.com/gatework/wireless-rb/releases). Check [RubyGems](https://rubygems.org/gems/wireless-rb) for published versions.
 
@@ -69,16 +69,45 @@ end
 
 `Configuration.new.parse(text, complete: false)` parses controller configuration. `RuntimeParser.new(model: nil).parse(name, text, platform: "h3c", complete: false)` parses one runtime dimension; `parse_many` shares parsing for dimensions from the same command. `NeighborParser` supplies the AP context to neighbor observations.
 
-The caller must establish input completeness. Unknown syntax, duplicate identities, count mismatches, and truncated output remain partial or failed. A configured maximum transmit power is not a current measured transmit power. PSKs, passwords, and authentication URLs must not enter snapshots.
+Invalid platform/model/dimension arguments and non-boolean `complete` raise `ArgumentError`; malformed device text produces a failed observation. The caller must establish input completeness. Unknown syntax, duplicate identities, count mismatches, and truncated output remain partial or failed. A configured maximum transmit power is not a current measured transmit power. PSKs, passwords, and authentication URLs must not enter snapshots.
 
-`Collector#collect(connector:, target:, platform:, model: nil, dimensions:, ap_connection: nil, ap_names: [])` uses an injected connector. `net-connector` is an explicit runtime dependency for the included `ApSession`; an LLDP request needs explicit AP credentials through `ap_connection`. The host owns device identity and connection settings. AP console activation and AP credentials are never inferred by the parser. Rails inventory projection, locking, encryption, APIs, and `Wireless::Sync` belong to the host and are not shipped in this gem.
+Conflicting runtime fields and singleton settings within one configuration block are excluded and keep their source evidence incomplete; later declarations in that block cannot restore the ambiguous value. Separate sequential configuration blocks retain their own source captures. Unknown nested wireless declarations cannot certify an empty configuration. Observation names must be symbols; display strings contain metadata only. An empty coverage scope is unknown, and freshness windows must be finite and nonnegative.
+
+`Collector#collect(connector:, target:, platform:, model: nil, dimensions:, ap_connection: nil, ap_names: [])` uses a host-supplied connector; ordinary collection only requires `connected?` and `send_commands` on its sessions. For AP LLDP, inject `Collector.new(ap_session: factory)`. The factory receives `controller:` plus lazily resolved `ap_connection` keywords and returns an object with `read(access_point:)`. When APs need querying but no factory was supplied, only LLDP reports `ap_session_required`; credentials are not read and controller observations remain available.
+
+The included AP login adapter is optional. Declare `gem "net-connector", "~> 0.11.1", require: false` in the host application, then load and inject it explicitly:
+
+```ruby
+require "wireless"
+require "wireless/ap_session"
+
+collector = Wireless::Collector.new(
+  ap_session: ->(controller:, **credentials) { Wireless::ApSession.new(controller: controller, **credentials) }
+)
+```
+
+This adapter requires an AP password and optional username through `ap_connection`; custom adapters can own their credentials. `read` returns a hash containing `result: CtxDriver::Capture`, optional `error:` / `cleanup_error:` / `close_error:`, and `skipped:`. The host or adapter owns credentials and session lifecycle; parsers never infer AP console activation or credentials.
+
+AP access reuses the connected controller and its operation lease; it does not open a separate AP transport. Login, read-only queries, confirmed return, and any failure close share that lease. A busy controller is left untouched. The adapter sends `quit` only from the confirmed AP prompt, and preserves cancellation and independent cleanup failures. Empty AP inventories do not resolve credentials or construct adapters.
 
 Detailed vendor behavior, historical validation notes, and Motor-only integration are preserved in [the architecture reference](docs/architecture-zh.md). Host integration examples in that reference require Motor; they are not standalone gem APIs. Motor adapters live under `backend/lib/baseline`, `backend/lib/vxlan`, and `backend/lib/wireless` in the [Motor repository](https://github.com/gatework/motor/tree/main/backend/lib).
 
 The lifecycle connector is a host adapter exposing `open { |session| }` (and `platform` for VXLAN and Wireless). It is distinct from a native `Net::Connector::Base` device instance. Borrowed native sessions are accepted by `CtxDriver::Reader` and `CtxChecker::Collector#collect_session`; they are never implicitly connected or retried.
 
+## Domain vocabulary
+
+H3C command parsers share `H3c::Parser` for command-output validation and `H3c::RecordParser` for labeled records. `H3c::Authentication` supplies shared authentication fields; `H3c::Document` preserves configuration source lines. Huawei uses `Huawei::Profile` and command parsers under `Huawei::Parsers`, with the same parameter contract.
+
+APs, radios, BSSs, and associated clients have distinct identities. H3C `Online time` is `online_seconds`; AP `System uptime` is `uptime_seconds`, as shown by the [distinct device fields](https://www.h3c.com/cn/d_202606/2850182_30005_0.htm). Explicit authentication modes take precedence over configured domain references, and combined or fallback modes retain their order instead of becoming a single authentication method; see the [H3C authentication reference](https://www.h3c.com/en/d_202106/1418918_294551_0.htm). Opaque LLDP chassis IDs preserve case, while an explicit MAC subtype is normalized. Measurement conversion names expose output units: `Fields.duration_seconds`, `Fields.rates_mbps`, and `Fields.channel_width_mhz`. `Fields.frequency_band` requires an unambiguous frequency-band label or band-specific PHY evidence. A channel number alone, or a generic `802.11ax` label, does not establish a band; channel numbers are not accepted as band evidence. See the [Cisco 6-GHz channel examples](https://www.cisco.com/c/en/us/support/docs/wireless/catalyst-9166-series-access-points/220526-configure-and-verify-wi-fi-6e-band-opera.html).
+
+Radio capability details preserve their subsection: `details[:vht_mcs]`, `[:ht_mcs]`, `[:he_mcs]`, and `[:operational_rates]` each own labels such as `supported` and `mandatory`. AP totals establish AP coverage; an AP without reported Radio evidence leaves the Radio view incomplete, while the AP view can remain complete. AP LLDP adapters must return a capture for the requested LLDP command; the collector owns AP identity and attempted-status metadata.
+
+`authentication_type` summarizes recognized authentication configuration. Combined deployment layers such as PSK and Portal remain in `configuration[:akm_modes]` and `configuration[:portal]`; a baseline checking all enabled mechanisms must inspect those fields.
+
 ## Development and tests
 
+Name shared classes by their responsibility and use the namespace for platform context. Preserve filenames and class names that directly match device commands.
+
 ```sh
 bundle install
 bundle exec rake
@@ -88,6 +117,8 @@ bundle exec rake build
 
 `bundle exec rake` runs RSpec, RuboCop, and the offline examples. Tests live in `spec/`, following the existing project's RSpec convention; fixtures use synthetic or sanitized evidence. Add regression cases for successful, incomplete, unsupported, and malformed inputs when extending a parser. Offline tests do not certify all device versions or replace live integration checks.
 
+Run `bundle exec ruby -Ilib benchmark/tables.rb` for synthetic 500, 2,000, and 5,000-entry template, binding, and LLDP continuation cases. Each case validates its result and reports the fastest of three local samples plus object allocations; it does not measure device or network performance.
+
 Use the declared minimum Ruby version for compatibility checks. Document source methods and non-obvious business logic in concise Chinese, preserve public return/error contracts, and never add raw device captures or credentials to examples, fixtures, logs, or release archives.
 
 ## Release

data/docs/architecture-zh.md

@@ -10,17 +10,17 @@ Motor 自有的无线业务实现，参考 Netstack 已验证的命令、字段
 
 `Motor::Device → Motor::Devices::Connector → Wireless::Collector / CtxDriver::Reader → Configuration / RuntimeParser / NeighborParser → Snapshot → Sync → AssetInventory / DetailInventory`
 
-- 公共 `Connector` 管理凭据、严格主机密钥校验和会话生命周期；[`CtxDriver::Reader`](https://github.com/gatework/ctx_driver) 通过 net-connector 执行单条查询、验证响应并记录来源摘要。每台控制器使用一个会话顺序采集，共享命令只执行、解析一次；单脚本失败不丢弃其他结果，断线后不自动重连。AP 子会话仍由 `ApSession` 管理，每个 AP 的邻居读取和解析分别隔离失败。
+- 公共 `Connector` 管理凭据、严格主机密钥校验和会话生命周期；[`CtxDriver::Reader`](https://github.com/gatework/ctx_driver) 通过宿主注入的会话执行单条查询、验证响应并记录来源摘要。每台控制器使用一个会话顺序采集，共享命令只执行、解析一次；单脚本失败不丢弃其他结果，断线后不自动重连。AP 子会话由 `Collector.new(ap_session: factory)` 注入，每个 AP 的邻居读取和解析分别隔离失败。内置 `ApSession` 仅在宿主自行安装 net-connector 0.11.1 或同系列后续补丁 并显式 `require "wireless/ap_session"` 后可用；默认加载、配置解析和普通控制器采集均不引入传输库。
 - 解析结果使用与数据库字段对应的 Hash。H3C 覆盖 AP、Radio、BSS、Client、AP 组、服务模板、802.1X，以及快照中的 MAC 认证和阻断客户端。Huawei 保留已验证的 AP、Client 表格格式，其他维度明确标记不支持。
 - 配置事实和运行测量分开保存；配置中的最大功率不能当作当前发射功率。PSK、密码、原始配置及认证 URL 不进入快照或错误信息。
-- AP LLDP 需要显式请求，使用控制器中转和显式 AP 凭据。确认 AP 提示符后才读取，退出时确认原控制器提示符；不自动开启 AP console。
+- AP LLDP 需要显式请求和注入 AP 会话工厂；内置适配器使用控制器中转和显式 AP 凭据。确认 AP 提示符后才读取，退出时确认原控制器提示符；若已返回控制器则不再发送 quit，遇到其他提示符则隔离连接。进入 AP、读取、退出及失败关闭均位于同一次控制器租约中，不建立独立 AP 连接；控制器忙碌时不夺取或关闭其他操作。取消继续传播，原始取消不会被清理阶段的第二次取消覆盖；退出和关闭失败分别保留为 cleanup_error 和 close_error。不自动开启 AP console。
 - 外部 I/O 完成后锁控制器，复核控制器、原快照和资产版本，原子提交资产、配置明细、快照及 revision。采集事实与库存投影分开：缺父 AP/Radio 的合法记录保留在原始快照，库存投影记录 `parent_unavailable`，其他独立实体继续入库；存在依赖未满足的维度禁止清理缺失项。身份歧义、模型校验和数据库异常仍使整个事务回滚。AP 档案只标记缺失，人工管理字段保留。
 - 管理 API、Netdisco 同步和既有 Rake 任务名不变。`Motor::Wireless::CliSync` 委托新实现。虚拟控制器及信道继续查询现有表。
 
 
-H3C 具体策略位于 [`lib/wireless/h3c`](../lib/wireless/h3c/profile.rb)，10 条命令分别实现为 `parsers/display_*.rb`。`H3c::Parser` 管理平台输入边界，`VerboseParser` 与 `SessionParser` 复用标签和会话结构，各命令类维护自己的字段和身份规则。`Profile` 统一声明命令、解析类及型号覆盖，`ParserRegistry` 识别 `h3c` / `h3c_wireless`。公共抽象及型号扩展见 [`../ctx_parser`](https://github.com/gatework/ctx_parser)。
+H3C 具体策略位于 [`lib/wireless/h3c`](../lib/wireless/h3c/profile.rb)，10 条命令分别实现为 `parsers/display_*.rb`。`H3c::Parser` 管理平台输入边界，`H3c::RecordParser` 读取标签字段并划分记录；`H3c::Authentication` 复用认证字段和身份定义，各命令类保留自己的格式规则。`Profile` 统一声明命令、解析类及型号覆盖，`ParserRegistry` 识别 `h3c` / `h3c_wireless`。公共抽象及型号扩展见 [`../ctx_parser`](https://github.com/gatework/ctx_parser)。
 
-配置与运行命令共用 `H3c::CommandOutput` 的编码和命令错误边界；配置保留原始换行，运行表格规范化为 LF。`DisplayCurrentConfiguration` 解释语法，`H3c::Configuration` 维护实体身份、AP 组/型号/Radio 的合法归属及模板认证类型。嵌套记录与来源路径由 `Configuration::Scope` 一起构建，逐行状态和捕获复用 `CtxParser::ConfigurationParser`，不在厂商类内重复实现。
+`H3c::Document` 组织配置来源行、横幅与完整性诊断。配置与运行命令共用 `H3c::CommandOutput` 的编码和命令错误边界；配置保留原始换行，运行表格规范化为 LF。共享 `Wireless::Terminal` 在字段清理前检测分页和编辑控制：运行回显受损时拒绝生成事实，配置文档则逐行标记无效来源，保留其他配置及其捕获；横幅内容仍作为普通文本隔离。`DisplayCurrentConfiguration` 解释语法，`H3c::Configuration` 维护实体身份、AP 组/型号/Radio 的合法归属及模板认证类型。嵌套记录与来源路径由 `Configuration::Scope` 一起构建，逐行状态和捕获复用 `CtxParser::Configuration`，不在厂商类内重复实现。
 
 顶层声明只在配置根节点识别。AP、型号或 Radio 内出现 `sysname`、`wlan ap-group`、`wlan service-template` 等顶层声明时，保留未知诊断，不提升为全局对象；配置及共享的组/模板维度均为部分结果，入库保留已有完整明细。重复实体保留首条并标记为部分结果。
 

data/lib/wireless/ap_session.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# 可选入口单独声明最低连接器版本，核心解析不激活此依赖。
+gem "net-connector", "~> 0.11.1"
 require "net/connector"
 require "ctx_driver"
 require_relative "fields"
@@ -23,79 +25,138 @@ module Wireless
 
     # 校验 AP 凭据，借用控制器会话进行嵌套接入。
     def initialize(controller:, password:, username: nil)
+      unless %i[connected? current_prompt with_operation execute_operation close].all? { |method| controller.respond_to?(method) }
+        raise ArgumentError, "Controller must provide an existing operation-capable session"
+      end
       unless password.is_a?(String) && !password.strip.empty? && !/[\x00-\x1f\x7f]/.match?(password) &&
-          (username.nil? || (username.is_a?(String) && !/[\x00-\x1f\x7f]/.match?(username)))
+          (username.nil? || (username.is_a?(String) && !username.strip.empty? && !/[\x00-\x1f\x7f]/.match?(username)))
         raise ArgumentError, "Invalid AP credentials"
       end
-      @controller, @password, @username = controller, password, username
+      @controller, @password, @username = controller, password.dup.freeze, username&.dup&.freeze
       @usable = true
     end
 
-    # 嵌套登录 AP 读取 LLDP，并确认返回原控制器提示符。
+    # 借用控制器操作租约；进入 AP、查询、退出和失败关闭均不能与其他查询交错。
     def read(access_point:)
-      return { error: :controller_session_lost, skipped: true } unless @usable && @controller.connected?
+      return { error: :controller_session_lost, skipped: true } unless @usable
+      return { error: :ap_address_unavailable, skipped: true } unless access_point.is_a?(Hash)
       return { error: :ap_not_online, skipped: true } unless Fields.online_status(access_point[:operational_status]) == "online"
-      address = Fields.ip(access_point[:management_ip])
-      return { error: :ap_address_unavailable, skipped: true } unless address && IPAddr.new(address).ipv4? && address != "0.0.0.0"
+      address = address_for(access_point)
+      return { error: :ap_address_unavailable, skipped: true } unless address
 
       outcome = {}
+      acquired = false
       @controller.with_operation(:wireless_ap_lldp) do
-        original_prompt = prompt
-        raise Error, :controller_prompt_mismatch unless DEVICE_PROMPT.match?(original_prompt)
-        entered = false
-        returned = false
+        acquired = true
+        unless @usable && @controller.connected?
+          @usable = false
+          next outcome.merge!(error: :controller_session_lost, skipped: true)
+        end
+        collect_neighbors(address, outcome)
+      end
+      outcome
+    rescue StandardError => error
+      # 未取得租约时不改变共享控制器状态，也不能关闭其他操作持有的连接。
+      outcome ||= {}
+      outcome[:error] ||= error_code(error)
+      outcome[:skipped] = true unless acquired
+      outcome
+    end
+
+    # 展示对象身份与状态，避免泄露原始回显或凭据。
+    def inspect = "#<#{self.class.name} usable=#{@usable}>"
+
+    private
+
+    # 地址验证只发生在接入前；后续协议错误不能被误报成未尝试的地址失败。
+    def address_for(access_point)
+      address = Fields.ip_address(access_point[:management_ip])
+      address if address && IPAddr.new(address).ipv4? && address != "0.0.0.0"
+    rescue ArgumentError, IPAddr::Error
+      nil
+    end
+
+    # 同一次控制器租约覆盖完整嵌套操作，未确认返回前始终视为不可复用。
+    def collect_neighbors(address, outcome)
+      original_prompt = prompt
+      raise Error, :controller_prompt_mismatch unless DEVICE_PROMPT.match?(original_prompt)
+
+      ap_prompt = nil
+      returned = false
+      @usable = false
+      begin
+        login = execute("telnet #{address}", DEVICE_PROMPT, timeout: 10, interactions: interactions)
+        confirm(login)
+        current = prompt
+        returned = current == original_prompt
+        ap_prompt = current if !returned && DEVICE_PROMPT.match?(current)
+        raise Error, :ap_authentication_failed if AUTHENTICATION_FAILURE.match?(login.output)
+        raise Error, :ap_connection_failed if CONNECTION_FAILURE.match?(login.output)
+        raise Error, :ap_login_not_confirmed unless ap_prompt
+
+        reader = CtxDriver::Reader.new(session: @controller)
+        preparation = reader.read("screen-length disable")
+        raise Error, preparation.failure.fetch(:code) unless preparation.success?
+        raise Error, :ap_session_lost unless prompt == ap_prompt
+
+        result = reader.read(COMMAND)
+        raise Error, :ap_session_lost if result.success? && prompt != ap_prompt
+        outcome[:result] = result
+        raise Error, result.failure.fetch(:code) unless result.success?
+      rescue StandardError => error
+        outcome[:error] = error_code(error)
+      ensure
+        original_error = $!
         begin
-          interactions = [ Net::Connector::Interaction.new(/password:\s*\z/i, "#{@password}\n", sensitive: true, limit: 1, capture: false) ]
-          interactions.unshift(Net::Connector::Interaction.new(/(?:login|username):\s*\z/i, "#{@username}\n", sensitive: true, limit: 1, capture: false)) if @username
-          login = execute("telnet #{address}", DEVICE_PROMPT, timeout: 10, interactions: interactions)
-          confirm(login)
+          restore(original_prompt, ap_prompt, returned, outcome)
+        rescue Exception # rubocop:disable Lint/RescueException -- 清理期间的二次取消不能覆盖原有取消，所有异常仍向外传播。
+          raise original_error, cause: original_error.cause if original_error
+          raise
+        end
+      end
+    end
+
+    # 登录凭据只进入有次数限制的敏感交互，不构造独立 AP 连接。
+    def interactions
+      values = [ Net::Connector::Interaction.new(/password:\s*\z/i, "#{@password}\n", sensitive: true, limit: 1, capture: false) ]
+      if @username
+        values.unshift(Net::Connector::Interaction.new(/(?:login|username):\s*\z/i, "#{@username}\n", sensitive: true, limit: 1, capture: false))
+      end
+      values
+    end
+
+    # 仅从已确认的 AP 提示符退出；已回控制器时不再发送 quit。
+    def restore(original_prompt, ap_prompt, returned, outcome)
+      if @controller.connected?
+        current = prompt
+        if ap_prompt && current == original_prompt
+          returned = true
+        elsif ap_prompt && current == ap_prompt
+          confirm(execute("quit", exact_prompt(original_prompt)))
           returned = prompt == original_prompt
-          # 只有提示符已切换到 AP 才确认登录，命令成功返回控制器不代表接入成功。
-          entered = prompt != original_prompt && DEVICE_PROMPT.match?(prompt)
-          raise Error, :ap_authentication_failed if AUTHENTICATION_FAILURE.match?(login.output)
-          raise Error, :ap_connection_failed if CONNECTION_FAILURE.match?(login.output)
-          raise Error, :ap_login_not_confirmed unless entered
-          reader = CtxDriver::Reader.new(session: @controller)
-          preparation = reader.read("screen-length disable")
-          raise Error, preparation.failure.fetch(:code) unless preparation.success?
-
-          result = reader.read(COMMAND)
-          outcome[:result] = result
-          raise Error, result.failure.fetch(:code) unless result.success?
-        rescue Error, Net::Connector::Error => error
-          outcome[:error] = error.is_a?(Error) ? error.code : Net::Connector::ErrorMetadata.code(error.code) || :collection_failed
-        ensure
-          begin
-            # 已进入 AP 才发送退出；必须确认返回原提示符后才能继续复用控制器会话。
-            if entered && @controller.connected?
-              confirm(execute("quit", exact_prompt(original_prompt)))
-              returned = prompt == original_prompt
-            end
-            @usable = returned && @controller.connected? && prompt == original_prompt
-          rescue Error, Net::Connector::Error
-            @usable = false
-          end
-          outcome[:cleanup_error] = :ap_exit_failed unless @usable
         end
+        @usable = returned && @controller.connected? && prompt == original_prompt
       end
-      outcome
-    rescue ArgumentError, IPAddr::InvalidAddressError
-      { error: :ap_address_unavailable, skipped: true }
-    rescue Error, Net::Connector::Error => error
+    rescue StandardError
       @usable = false
-      { error: error.is_a?(Error) ? error.code : Net::Connector::ErrorMetadata.code(error.code) || :collection_failed }
     ensure
-      begin
-        @controller.close if !@usable && @controller.connected?
-      rescue Net::Connector::Error
-        outcome[:cleanup_error] = :session_close_failed if outcome
+      unless @usable
+        outcome[:cleanup_error] = :ap_exit_failed
+        close_controller(outcome)
       end
     end
 
-    # 展示对象身份与状态，避免泄露原始回显或凭据。
-    def inspect = "#<#{self.class.name} usable=#{@usable}>"
+    # 关闭仍位于控制器租约中；退出与关闭失败独立保存，不覆盖已取得的观测。
+    def close_controller(outcome)
+      @controller.close
+    rescue StandardError
+      outcome[:close_error] = :session_close_failed
+    end
 
-    private
+    # 所有失败只暴露稳定代码，不把连接器消息或凭据写入领域观测。
+    def error_code(error)
+      error.is_a?(Error) ? error.code : CtxDriver::Failure.code(error, :collection_failed)
+    end
 
     # 渲染当前终端提示符，用于安全核对嵌套会话身份。
     def prompt = Net::Connector::TerminalRenderer.render(@controller.current_prompt.to_s).strip

data/lib/wireless/collector.rb

@@ -4,24 +4,25 @@ 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
+    # 注入时钟和可选 AP 会话工厂；核心采集不加载具体传输。
+    def initialize(clock: -> { Time.now.utc }, ap_session: nil)
+      raise ArgumentError, "AP session factory must be callable" unless ap_session.nil? || ap_session.respond_to?(:call)
+
+      @clock, @ap_session = clock, ap_session
     end
 
     # 通过调用方持有的连接器顺序采集请求维度。
     def collect(connector:, target:, platform:, model: nil, dimensions: DEFAULT_DIMENSIONS, ap_connection: nil, ap_names: [])
-      platform = platform.to_s
+      platform = platform.to_s.dup.freeze
+      model = model.dup.freeze if model.is_a?(String)
       raise ArgumentError, "Target must be a hash" unless target.is_a?(Hash)
 
       unless dimensions.is_a?(Array) && dimensions.any? && dimensions.uniq == dimensions &&
@@ -29,19 +30,18 @@ module Wireless
           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
+      # 外部连接和适配器回调前保存身份与选择范围。
+      target = CtxParser::Immutable.copy(target)
+      ap_names = ap_names.map { |name| name.dup.freeze }.freeze
       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") }
+      profile = ParserRegistry.fetch(platform, model: model)
+      commands = profile.commands.except(:lldp)
+      observations = requested.reject { |name| commands.key?(name) || (name == :lldp && profile.commands.key?(:lldp)) }
         .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
+      queries = profile.queries(requested & commands.keys)
       actual = connector.platform.to_s
       unless actual == platform || ([ actual, platform ] - %w[h3c h3c_wireless]).empty?
         raise ArgumentError, "Wireless platform differs from the device connector"
@@ -51,7 +51,7 @@ module Wireless
         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")
+          preparation = reader.read(profile.preparation_command)
           error = preparation.failure&.fetch(:code)
           queries.each do |command, names|
             if error
@@ -59,16 +59,14 @@ module Wireless
               next
             end
             stage = :collect
-            observations.merge!(read(reader, command, names, platform, model: model))
+            observations.merge!(collect_command(reader, command, names, platform, model: model))
           end
-          if requested.include?(:lldp) && platform != "huawei"
+          if requested.include?(:lldp) && profile.commands.key?(:lldp)
             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)
+              collect_ap_neighbors(session, observations[:access_points], ap_connection, ap_names)
             end
           end
           stage = :close
@@ -88,7 +86,7 @@ module Wireless
     private
 
     # 单条命令负责自身解析失败；无关查询保留已完成事实。
-    def read(reader, command, names, platform, model:)
+    def collect_command(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?
@@ -111,47 +109,62 @@ module Wireless
     end
 
     # 独立采集 AP 邻居证据，并报告 AP 覆盖不完整的情况。
-    def neighbors(session, aps, credentials, names)
+    def collect_ap_neighbors(session, aps, connection, 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 全部查询成功也不代表覆盖整台控制器，过滤范围和父清单缺失须独立报告。
+      selected_names = names.to_h { |name| [ name, true ] }
+      selected = aps.records.select { |ap| selected_names.empty? || selected_names.key?(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)
+      if selected.any?
+        return unavailable(:lldp, :failed, :ap_session_required) unless @ap_session
+        credentials = (connection.respond_to?(:call) ? connection.call : connection) || {}
+        return unavailable(:lldp, :failed, :invalid_ap_connection) unless credentials.is_a?(Hash)
+        ap_session = @ap_session.call(**credentials, controller: session)
+        return unavailable(:lldp, :failed, :invalid_ap_session) unless ap_session.respond_to?(:read)
+        selected.each do |ap|
+          collected = read_ap_neighbors(ap_session, ap)
+          records.concat(collected.fetch(:records))
+          issues.concat(collected.fetch(:issues))
+          evidence << collected.fetch(:evidence)
+        end
       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)
+    rescue StandardError => error
+      details = CtxDriver::Failure.details(error, fallback: :ap_session_setup_failed, stage: :ap_setup)
+      unavailable(:lldp, :failed, details.fetch(:code), **details.except(:code))
     end
 
     # 单个 AP 脚本或解析失败不能丢弃其他 AP 的邻居观测。
-    def read_neighbor(ap_session, ap)
+    def read_ap_neighbors(ap_session, ap)
       stage = :execute
-      source = { kind: :ap_lldp_result, ap_name: ap[:name], command: ApSession::COMMAND,
+      source = { kind: :ap_lldp_result, ap_name: ap[:name], command: H3c::Profile::COMMANDS.fetch(:lldp),
         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
+      if result
+        unless result.is_a?(CtxDriver::Capture) && result.command == source[:command] && !(outcome[:skipped] && result.success?)
+          raise TypeError, "AP capture must match the requested LLDP command"
+        end
+        # 回执补充摘要与时间；AP 身份、命令和尝试状态始终由本次请求确定。
+        source = (result.evidence.first || {}).merge(source)
+      end
       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] }
+      %i[error cleanup_error close_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,
+        status: outcome[:error] || outcome[:cleanup_error] || outcome[:close_error] ? :failed : parsed&.status || :failed,
         neighbor_count: parsed&.records&.size || 0)
       { records: parsed&.records || [], issues: issues, evidence: source }
     rescue StandardError => error