zabbix_manager 5.1.6 → 6.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37c70888e6fd6b0e27a4945f2672d460243584724c67eed4eadc4d69b88d6ad7
-  data.tar.gz: 6975d3b02322a81fe8923503e58b91f1888de4ec324f30846552305931fe6a59
+  metadata.gz: b40a4744edcbba667b1c548c576b6451e637dee80bce28755a151f58e02a553b
+  data.tar.gz: 5d5ee350721f10da7ea9f93582bf06fc6c5b6ac4e5a9bbaa445058f43c205a45
 SHA512:
-  metadata.gz: 875b98496cffef36b128f8038f007c8d9a0a9bdb6635c14df0380545ef495903970c73ffca1cb26105a3e382d14e88517308edd81b11b57d5be64e30e0b6f486
-  data.tar.gz: 9d2d60aa041e3e993b4c8aaf9c900570824a997537dca1f0fc34a88dbc7f2dd7286d86adc2ecda40e04b2ac0393fa9279cbbb2a29b65c92dab1a92463984d833
+  metadata.gz: db558e058564904b417225b8f59df28a741b7f73d787f104180dd878e017899fadfe077d4194b2e2f2b2995639cf9c42ab585abf25f0d06308af9f8a6549eeba
+  data.tar.gz: 5c6a2e519171dec793941f13ba766aad04679a008196dad090b784614fa59882c851c810554c0c8ee479ba8aa7493779c5c2f770bfc1d24c0efb8da4a730da7d

data/CHANGELOG.md

@@ -1,6 +1,36 @@
 # CHANGELOG
 
-## Unreleased
+## 6.0.0 (2026-10-01)
+
+* Fix role ID queries and host-scoped value map identities, keeping immutable host fields out of updates.
+* Reject incomplete interface creation and duplicate resolved interface targets before remote writes.
+* Preserve distinct interface names, validate standard 32-bit octet conversion, and check effective numeric item configuration before writing monitoring updates.
+* Bound network request duration and decompressed response size, close failed connections, and never replay uncertain mutations.
+* Complete Chinese module comments and correct public return-type documentation.
+
+* Extract reusable Motor monitoring scenarios through native Zabbix APIs only, without SQL or application persistence.
+* Add `traffic.series` and `traffic.for_interface` for precise history/trend reads with missing-data and truncation states.
+* Add device name resolution, proxy groups, SNMP secret macros and caller-owned membership receipts; preserve unrelated configuration.
+* Add line previews, low-traffic/status/ICMP checks, dependencies, scoped problem reads and managed trigger retirement.
+* Return device receipts and per-kind line `triggerids`; expand public method contracts and executable workflow examples.
+
+* Validate mutation receipts against requested IDs; empty, malformed or mismatched receipts remain unconfirmed outcomes.
+* Require desired trigger state during lost-response recovery and serialize dependency replacement with appends.
+* Replace obsolete template-side host-link helpers with `hosts.link_templates`, `replace_templates`, and `unlink_templates` using current host APIs.
+* Use explicit `user_groups.replace_users` and `replace_host_group_permissions` operations with version-correct server fields.
+* Verify packaged source inventory and isolated authenticated requests, then publish the exact verified artifact; declare IRB for Ruby 4 development consoles.
+
+* Normalize multiword resource classes, files and accessors to Ruby CamelCase/snake_case without compatibility aliases.
+
+* Require Ruby 3.4 or newer; refresh the dependency lockfile and remove development-tool version pins and duplicate declarations.
+* Replace the split `Basic` hierarchy with `Resource`, remove compatibility aliases and parameter logging, and use keyword connection/request options.
+* Use ActiveSupport logger/tagging/parameter filtering; make logging failure independent of API results.
+* Add explicit `from_env` loading for `ZABBIX_URL`, `ZABBIX_API_TOKEN`, `ZABBIX_USERNAME`, and `ZABBIX_PASSWORD` only.
+* Remove `current`, `user`, `debug`, `manager_request`, low-level client request helpers and legacy inventory field aliases; use explicit managers, `username`, `logger`/`log_level` and canonical monitoring fields.
+* Validate JSON-RPC response shapes and IDs, report unconfirmed responses as `ProtocolError`, and prevent server text or exception causes from leaking secrets.
+* Delegate proxy discovery and exclusions to Ruby, validate finite timeouts, and avoid closing an inherited parent TLS session after fork.
+* Validate complete interface/item batches before writes, refuse ambiguous macro ownership, and distinguish missing values from empty strings during updates.
+* Separate monitoring input, threshold and traffic-item rules, reject invalid units/expressions, and retain unknown write outcomes in batch results.
 
 * Add Zabbix 7.x API-token authentication through the Bearer header while retaining the legacy 4.x-6.x authentication body.
 * Reuse a thread-safe persistent `Net::HTTP` session and add explicit `close` lifecycle handling.

data/README.md

@@ -4,8 +4,7 @@
 
 [gem]: https://rubygems.org/gems/zabbix_manager
 
-Most codes borrowed from zabbixapi, but fit for my everyday works well!
-Simple and lightweight ruby module for working with [Zabbix][Zabbix] via the [Zabbix API][Zabbix API]
+A Ruby client for the [Zabbix API][Zabbix API], with reusable device, interface and circuit monitoring workflows.
 
 ## Installation
 ```sh
@@ -41,6 +40,25 @@ zabbix.close
 
 Zabbix 7.x requests use the `Authorization: Bearer` header. Earlier supported servers use the JSON-RPC `auth` property. Supplying `api_token` skips `user.login`, and `logout` only closes the local connection because an API token is not a Zabbix user session. API tokens are rejected on plain HTTP unless `allow_insecure_http: true` is explicitly set.
 
+### Environment configuration
+
+Environment loading is explicit. `connect` uses only its keyword arguments; `from_env` reads exactly four variables:
+
+| Variable | Option |
+| --- | --- |
+| `ZABBIX_URL` | `url` |
+| `ZABBIX_API_TOKEN` | `api_token` |
+| `ZABBIX_USERNAME` | `username` |
+| `ZABBIX_PASSWORD` | `password` |
+
+```ruby
+zabbix = ZabbixManager.from_env(verify_ssl: true)
+```
+
+Explicit keyword arguments override environment values, including `nil` to clear an inherited credential. Set either an API token or a username/password pair. Unknown options and non-boolean flags are rejected before connecting. Timeouts, logging and locking remain ordinary keyword options.
+
+The HTTP transport uses Ruby's standard proxy discovery (`http_proxy`/`HTTP_PROXY`, `no_proxy`/`NO_PROXY`, with CGI protection). `no_proxy: true` disables proxies; `proxy: "http://proxy.example:8080"` selects an explicit HTTP proxy. HTTPS proxy URLs are rejected because this transport does not encrypt the connection to the proxy itself.
+
 ### Username and password
 
 ```ruby
@@ -61,7 +79,7 @@ A client keeps one persistent `Net::HTTP` session and serializes access to it, s
 
 ### Logging and HTTPS
 
-Pass any Ruby Logger-compatible object to receive connection, request completion, duration, and failure events:
+Pass a Ruby Logger or ActiveSupport logger to receive connection, request completion, duration, and failure events:
 
 ```ruby
 zabbix = ZabbixManager.connect(
@@ -71,28 +89,31 @@ zabbix = ZabbixManager.connect(
 )
 ```
 
-Passwords, API tokens, authorization values, cookies, and session IDs are filtered. Request parameters and response bodies are not logged; debug events contain only operation metadata.
+Logging uses `ActiveSupport::Logger` and `ActiveSupport::TaggedLogging`; structured credential filtering uses `ActiveSupport::ParameterFilter`. Pass `log_level: :info` to create a logger on standard error, or inject your application's logger. Logging is disabled unless one of these options is supplied, and logging failures do not change API outcomes.
+
+Passwords, API tokens, authorization values, cookies, and session IDs are filtered. Request parameters and response bodies are not logged. API exceptions expose the server error code and request ID, without remote messages or data that might echo arbitrary secrets. Malformed or mismatched JSON-RPC responses and invalid mutation ID receipts raise `ProtocolError < TransportError`: a write may already have happened, so it must not be blindly replayed.
 
 HTTPS certificate verification is disabled by default as required by this project. Set `verify_ssl: true` (and optionally `ca_file:`) to enable peer verification.
 
 Zabbix 7 API-token requests need the `Authorization` header, so they cannot share that header with HTTP Basic authentication. The client rejects that combination instead of silently overwriting either credential.
 
-Timeouts can be set together with `timeout:` or independently with `open_timeout:`, `read_timeout:`, and `write_timeout:`. `keep_alive_timeout:` controls persistent connection reuse.
+Timeouts can be set together with `timeout:` or independently with `open_timeout:`, `read_timeout:`, and `write_timeout:`. `keep_alive_timeout:` controls persistent connection reuse. `request_timeout:` bounds the complete network operation, including a continuously progressing response, and defaults to `timeout:`. Waiting for another request on the same client is outside that budget. `max_response_bytes:` limits the decompressed response body (64 MiB by default). Exceeding either limit closes the connection and raises `TransportError`; mutations are never automatically replayed.
 
 ### Device and interface monitoring
 
-`monitoring` provides idempotent workflows for frequent device and line updates. Item identity is the stable pair `hostid + key_`; managed triggers use a dedicated `zabbix_manager_id` tag. Missing remote objects are created and existing ones are updated. Omitted objects are never deleted.
+`monitoring` provides device and line workflows using native Zabbix APIs only. There are no SQL operations, Rails models or persistence dependencies. Item identity is the stable pair `hostid + key_`; managed triggers use a dedicated `zabbix_manager_id` tag. Missing objects are created and existing ones are updated. Optional line checks removed from a definition are disabled after the remaining desired checks succeed; objects are never automatically deleted.
 
-For a line inventory that already has interface traffic items discovered by Zabbix, use `reconcile_line`. It accepts the field names from the historical `add_line_monitors.rb` importer, locates the host and the unique inbound/outbound items, then creates or updates one combined trigger. Use a stable, non-secret `line_id` so interface renames update the same trigger.
+For a line inventory that already has interface traffic items discovered by Zabbix, use `reconcile_line`. It locates the host and unique inbound/outbound items, then creates or updates the selected checks. Use canonical fields `host` (or `host_candidates`), `interface_name`, `capacity_mbps`, and a stable, non-secret endpoint `line_id`. Convert external inventory column names before calling the library.
+
+The complete workflows and return values are documented in [device monitoring](examples/device_monitoring.md), [line monitoring](examples/line_monitoring.md), and [traffic queries](examples/traffic.md). Public method comments document input, output, failures and remote side effects.
 
 ```ruby
 zabbix.monitoring.reconcile_line(
   line_id: "line-42",
   description: "Example upstream circuit",
-  capacity: 200, # Mbps
-  device1: "edge-switch-01",
-  ipaddr1: "192.0.2.10",
-  iface1: "Ten-GigabitEthernet1/0/49",
+  capacity_mbps: 200,
+  host_candidates: ["edge-switch-01", "192.0.2.10"],
+  interface_name: "Ten-GigabitEthernet1/0/49",
   isp: "Example ISP",
   high_water: 0.90,
   recovery_water: 0.80,
@@ -102,11 +123,11 @@ zabbix.monitoring.reconcile_line(
 )
 ```
 
-The lookup accepts full and abbreviated interface names such as `Ten-GigabitEthernet1/0/49` and `Te1/0/49`. It refuses zero or multiple direction matches instead of selecting an item by response order. Existing triggers from the importer can be adopted when their description and `category=line_bandwidth` tag match.
+The lookup accepts full and abbreviated interface names such as `Ten-GigabitEthernet1/0/49` and `Te1/0/49`. It refuses zero or multiple direction matches instead of selecting an item by response order. Trigger ownership comes from the managed identity tag; matching descriptions alone never adopt unrelated triggers.
 
 Use `reconcile_lines(lines)` for imports. It reuses host and item discovery results within the batch, avoiding a full `item.get` scan for every line.
 
-For a device-and-line batch, use `reconcile_network`. The whole input is structurally validated before the first device write. Devices are reconciled first, then lines, and the return value contains per-entry results plus a summary. Template linking and low-level discovery are asynchronous in Zabbix: if a new device's traffic items are not available yet, its line result is an error and the same batch can be safely rerun later.
+For a device-and-line batch, use `reconcile_network`. The whole input is structurally validated before the first device write. Devices are reconciled first, then lines, and the return value contains per-entry results plus a summary. Template linking and low-level discovery are asynchronous in Zabbix: retry discovery after the required items become available. Inspect any `:unknown` write outcome before repeating that entry.
 
 ```ruby
 result = zabbix.monitoring.reconcile_network(
@@ -114,16 +135,13 @@ result = zabbix.monitoring.reconcile_network(
     {
       host: "edge-router-01",
       name: "Example edge router",
-      groups: [{ groupid: 20 }],
-      interfaces: [{
-        type: 2, main: 1, useip: 1, ip: "192.0.2.10", dns: "", port: "161",
-        details: { version: 2, community: ENV.fetch("SNMP_COMMUNITY") }
-      }]
+      groups: ["Network devices"],
+      snmp: { ip: "192.0.2.10", community: ENV.fetch("SNMP_COMMUNITY") }
     }
   ],
   lines: [
     {
-      line_id: "line-42", device: "edge-router-01",
+      line_id: "line-42", host: "edge-router-01",
       interface_name: "Ten-GigabitEthernet1/0/49", capacity_mbps: 200,
       high_water: 0.90, recovery_water: 0.80
     }
@@ -134,7 +152,7 @@ result.fetch(:summary)
 ```
 
 ```ruby
-hostid = zabbix.monitoring.reconcile_device(
+receipt = zabbix.monitoring.reconcile_device(
   host: "router-01",
   name: "Core router 01",
   groups: [{ groupid: 20 }],
@@ -148,10 +166,14 @@ hostid = zabbix.monitoring.reconcile_device(
     details: { version: 2, community: ENV.fetch("SNMP_COMMUNITY") }
   }]
 )
+hostid = receipt.fetch(:hostid)
+snmp_interface = zabbix.host_interfaces.for_host(hostid).find do |interface|
+  interface["type"] == "2" && interface["main"] == "1"
+end
 
 zabbix.monitoring.reconcile_interface(
   host: { hostid: hostid, host: "router-01" },
-  interface: { name: "GigabitEthernet1/0/1", interfaceid: 12 },
+  interface: { name: "GigabitEthernet1/0/1", interfaceid: snmp_interface.fetch("interfaceid") },
   items: {
     inbound_bps: {
       key_: "if.hc.in.bps[1]", name: "WAN inbound", type: 20, value_type: 0,
@@ -192,9 +214,9 @@ zabbix.monitoring.reconcile_interface(
 )
 ```
 
-The library does not guess that SNMP discard/error counters equal packet-loss percentage. Supply an actual packet-loss item key (for example an ICMP loss item) and its item definition. Raw HC-octet traffic items must expose `bps` units and include change-per-second plus multiplier-8 preprocessing; otherwise line reconciliation refuses to build a dimensionally incorrect trigger. Thresholds use separate high and recovery values to avoid alert flapping.
+The library does not guess that SNMP discard/error counters equal packet-loss percentage. Supply an actual packet-loss item key (for example an ICMP loss item) and its item definition. Raw HC-octet traffic items must expose `bps` units and include change-per-second plus multiplier-8 preprocessing; otherwise line reconciliation refuses to build a dimensionally incorrect trigger. Thresholds use separate high and recovery values to avoid alert flapping. Line `high_water` and `recovery_water` are ratios greater than zero and at most one; percentages such as `90` are rejected. Interface threshold recovery is inclusive (`<=`), so a zero recovery threshold remains attainable.
 
-Reconciliation is a sequence of remote API calls, not a transaction. Single-object methods raise immediately; batch methods return a sanitized error for each failed entry unless `fail_fast: true` is passed. A retry safely converges already-created items by stable keys. If a trigger create loses its response and cannot be confirmed by readback, `ResultUnknown` is raised and must not be automatically retried. The readback schedule can be set with `uncertain_write_delays:` (up to 60 seconds total). The trigger upsert is serialized within one client process. For multiple workers, inject a callable `upsert_lock` adapter that runs the block under an application-level distributed lock.
+Reconciliation is a sequence of remote API calls, not a transaction. Single-object methods raise immediately; batch methods return a sanitized error for each failed entry unless `fail_fast: true` is passed. Batch results distinguish `ok`, `error`, and `unknown`; summaries count each status. Transport failures during device reconciliation are conservatively `unknown`, since that workflow includes both lookup and write calls. Successful earlier remote writes are not rolled back if a later operation fails. After an uncertain outcome has been resolved, a retry can converge already-created items by stable keys. If a trigger create loses its response, readback must confirm both its managed identity and requested attributes. If that cannot be confirmed, `ResultUnknown` is raised and must not be automatically retried. A definite API rejection is propagated. The readback schedule can be set with `uncertain_write_delays:` (up to 60 seconds total). Trigger upserts and dependency read/modify/write operations are serialized within one client process. For multiple workers, inject a callable `upsert_lock` adapter that runs the block under an application-level distributed lock.
 
 ```ruby
 ZabbixManager.connect(
@@ -204,40 +226,32 @@ ZabbixManager.connect(
 )
 ```
 
-Invalid caller input raises `ZabbixManager::Invalid`, ambiguous remote ownership raises `ZabbixManager::Conflict`, Zabbix JSON-RPC failures raise `ZabbixManager::ApiError`, HTTP/network failures raise `ZabbixManager::TransportError`, and uncertain remote writes raise `ZabbixManager::ResultUnknown`. Destructive/status/dependency methods require `hostid:` and verify ownership before writing. Dependencies default to the same host; cross-host dependencies require `allow_cross_host_dependencies: true`. Do not pass untrusted page parameters directly to raw `query` calls.
+Invalid caller input raises `ZabbixManager::Invalid`, ambiguous remote ownership raises `ZabbixManager::Conflict`, Zabbix JSON-RPC failures raise `ZabbixManager::ApiError`, HTTP/network failures raise `ZabbixManager::TransportError`, and uncertain remote writes raise `ZabbixManager::ResultUnknown`. The focused item/interface/trigger deletion, status and dependency helpers require `hostid:` and verify existing ownership before writing. Custom trigger expressions and raw resource methods accept trusted Zabbix definitions; the host lookup context does not replace application authorization. Dependencies default to the same host; cross-host dependencies require `allow_cross_host_dependencies: true`. Do not pass untrusted page parameters directly to `query`, raw resource methods, or custom expressions.
 
 ### High-frequency API modules
 
-The focused modules expose explicit current operations instead of compatibility aliases:
+`traffic.series` reads explicit item IDs; `traffic.for_interface` discovers both interface directions. Both expose missing data and query truncation, preserve numeric precision, and keep raw history separate from hourly trends. They never substitute zero or a stale last value for missing samples.
 
-* `hosts.reconcile`, `hosts.find_by_id`, `hosts.find_by_candidates`, `hosts.set_status`
-* `hostinterfaces.for_host`, `hostinterfaces.reconcile_for_host`, `hostinterfaces.delete_many`
+Multiword resource accessors use Ruby snake_case: `host_groups`, `host_interfaces`, `http_tests`, `media_types`, `proxy_groups`, `user_groups`, `user_macros`, `value_maps`, and `discovery_rules`.
+
+The focused modules expose explicit operations:
+
+* `hosts.reconcile`, `hosts.resolve`, `hosts.find_by_id`, `hosts.find_by_candidates`, `hosts.set_status`
+* `monitoring.reconcile_device`, `monitoring.reconcile_devices`, `monitoring.reconcile_network`
+* `monitoring.plan_line`, `monitoring.reconcile_line`, `monitoring.line_triggers`, `monitoring.line_problems`, `monitoring.disable_line`
+* `hosts.link_templates`, `hosts.replace_templates`, `hosts.unlink_templates`
+* `user_groups.replace_users`, `user_groups.replace_host_group_permissions`
+* `host_interfaces.for_host`, `host_interfaces.reconcile_for_host`, `host_interfaces.delete_many`
 * `items.for_host`, `items.upsert_by_key`, `items.upsert_many`, `items.set_status`, `items.delete_many`
 * `triggers.for_host`, `triggers.upsert_for_host`, `triggers.add_dependencies`, `triggers.replace_dependencies`, `triggers.set_status`, `triggers.delete_many`
 
 
 ## Supported Ruby Versions
-This library aims to support and is [tested against][github-ci] the following Ruby
-versions:
-
-* Ruby 2.7 and newer
-
-If something doesn't work on one of these versions, it's a bug.
-
-This library may inadvertently work (or seem to work) on other Ruby versions,
-however support will only be provided for the versions listed above.
-
-If you would like this library to support another Ruby version or
-implementation, you may volunteer to be a maintainer. Being a maintainer
-entails making sure all tests run and pass on that implementation. When
-something breaks on your implementation, you will be responsible for providing
-patches in a timely fashion. If critical issues for a particular implementation
-exist at the time of a major release, support for that Ruby version may be
-dropped.
+The minimum Ruby version is **3.4**. CI runs Ruby 3.4 and 4.0.
 
 ## Dependencies
 
-* net/http
+* net-http
 * active_support
 * json
 * logger
@@ -247,11 +261,16 @@ dropped.
 * Fork the project.
 * Base your work on the master branch.
 * Make your feature addition or bug fix, write tests, write documentation/examples.
-* Commit, do not mess with rakefile, version.
+* Run `bundle exec rake` and `bundle exec ruby script/verify_package.rb`.
 * Make a pull request.
 
 ## CI and release
 
+`script/verify_package.rb` checks the complete library inventory, installs into an isolated gem directory, exercises authentication and a resource request over a local HTTP socket, then saves that exact verified archive under `pkg/`. It also works when invoked outside the checkout.
+
+Development tools are declared once in `Gemfile`, without historical version pins. `Gemfile.lock` records the versions verified together. Runtime dependencies declare only the minimum API version needed by the library; update the lockfile and run the gates when changing dependencies.
+
+
 Pull requests and pushes to `master` run RSpec, documentation coverage, RuboCop, whitespace checks, and a built-Gem install smoke test. A `v<gem-version>` tag repeats the project gate, validates the tag/version, builds and installs a release candidate, then publishes that exact file through RubyGems Trusted Publishing. Configure the RubyGems trusted publisher for repository `gatework/zabbix_manager`, workflow `release.yml`, and environment `release` before pushing a release tag.
 
 ## Zabbix documentation
@@ -261,3 +280,7 @@ Pull requests and pushes to `master` run RSpec, documentation coverage, RuboCop,
 
 [Zabbix]: https://www.zabbix.com
 [Zabbix API]: https://www.zabbix.com/documentation/current/en/manual/api
+
+### Upgrading to 6.0
+
+Version 6.0 requires Ruby 3.4 or newer. Use keyword connection and query arguments, snake_case resource accessors, the explicit exception classes, and the current monitoring result shapes shown above. Legacy aliases and the former `Basic` API are removed.

data/lib/zabbix_manager/classes/actions.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  class Actions < Basic
+  # 告警动作资源；完整读取包含执行、恢复、确认操作及过滤条件。
+  class Actions < Resource
     # 返回操作对象对应的 Zabbix API 方法前缀。
     #
     # @return [String]
@@ -9,22 +10,13 @@ class ZabbixManager
       "action"
     end
 
-    # 返回操作对象用于业务识别的字段名。
-    #
-    # @return [String]
-    def identify
-      "name"
-    end
-
     # 获取操作及其执行、恢复、确认操作和过滤条件的完整数据。
     #
     # @param data [Hash] 包含识别字段及其值的查询条件
     # @raise [ApiError] Zabbix API 返回业务错误时抛出
     # @raise [TransportError] Zabbix 服务端返回非成功 HTTP 状态时抛出
-    # @return [Hash] 匹配的操作完整数据
+    # @return [Array<Hash>] 匹配的操作完整数据
     def get_full_data(data)
-      log "[DEBUG] Call get_full_data with parameters: #{data.inspect}"
-
       @client.api_request(
         method: "#{method_name}.get",
         params: {

data/lib/zabbix_manager/classes/applications.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  class Applications < Basic
+  # 应用集以 hostid + name 定位；端点是否可用由目标 Zabbix 版本决定。
+  class Applications < Resource
     # 返回应用集对象对应的 Zabbix API 方法前缀。
     #
     # @return [String]
@@ -9,13 +10,6 @@ class ZabbixManager
       "application"
     end
 
-    # 返回应用集对象用于业务识别的字段名。
-    #
-    # @return [String]
-    def identify
-      "name"
-    end
-
     # 生成由应用集名称和所属主机构成的稳定查询条件。
     # @param data [Hash] 包含 name 和 hostid 的应用集属性
     # @return [Hash] 应用集唯一查询条件

data/lib/zabbix_manager/classes/configurations.rb

@@ -1,13 +1,8 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  class Configurations < Basic
-    # 标记配置接口使用数组形式处理 API 返回值。
-    # @return [Boolean] 始终返回 true
-    def array_flag
-      true
-    end
-
+  # 原生配置导入/导出入口；导入可能修改多个远端对象，不提供本地回滚。
+  class Configurations < Resource
     # 返回配置对象对应的 Zabbix API 方法前缀。
     #
     # @return [String]
@@ -27,7 +22,7 @@ class ZabbixManager
     # @param data [Hash] 配置导出参数
     # @raise [ApiError] Zabbix API 返回业务错误时抛出
     # @raise [TransportError] Zabbix 服务端返回非成功 HTTP 状态时抛出
-    # @return [Hash] 配置导出结果
+    # @return [String] 服务端按指定格式序列化的配置内容
     def export(data)
       @client.api_request(method: "configuration.export", params: data)
     end
@@ -37,7 +32,7 @@ class ZabbixManager
     # @param data [Hash] 配置导入参数及内容
     # @raise [ApiError] Zabbix API 返回业务错误时抛出
     # @raise [TransportError] Zabbix 服务端返回非成功 HTTP 状态时抛出
-    # @return [Hash] 配置导入结果
+    # @return [Boolean] 服务端确认的导入结果
     def import(data)
       @client.api_request(method: "configuration.import", params: data)
     end

data/lib/zabbix_manager/classes/{drules.rb → discovery_rules.rb}

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  class Drules < Basic
+  # 网络发现规则（drule），区别于主机内的低级发现（discoveryrule）。
+  class DiscoveryRules < Resource
     # 返回网络发现规则对应的 Zabbix API 方法前缀。
     #
     # @return [String]
@@ -9,13 +10,6 @@ class ZabbixManager
       "drule"
     end
 
-    # 返回网络发现规则用于业务识别的字段名。
-    #
-    # @return [String]
-    def identify
-      "name"
-    end
-
     # 返回创建网络发现规则时使用的默认周期和启用状态。
     #
     # @return [Hash] 网络发现规则默认属性

data/lib/zabbix_manager/classes/errors.rb

@@ -22,6 +22,9 @@ class ZabbixManager
   # 表示 HTTP 状态或传输层失败。
   class TransportError < StandardError; end
 
+  # 响应无法确认远端操作是否已经完成。
+  class ProtocolError < TransportError; end
+
   # 表示远端可能已完成写入，调用方不得自动重放。
   class ResultUnknown < TransportError; end
 end

data/lib/zabbix_manager/classes/events.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  class Events < Basic
+  # 原生事件查询入口；按当前客户端凭据可见范围返回服务端记录。
+  class Events < Resource
     # 返回事件对象对应的 Zabbix API 方法前缀。
     #
     # @return [String]

data/lib/zabbix_manager/classes/graphs.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  class Graphs < Basic
+  # 图形以 hostid + name 查询；写入所有者由 gitems 中的监控项确定。
+  class Graphs < Resource
     # 返回图形对象对应的 Zabbix API 方法前缀。
     #
     # @return [String]
@@ -9,22 +10,13 @@ class ZabbixManager
       "graph"
     end
 
-    # 返回图形对象用于业务识别的字段名。
-    #
-    # @return [String]
-    def identify
-      "name"
-    end
-
     # 按名称搜索并获取图形的完整数据。
     #
     # @param data [Hash] 包含图形识别字段及其值的查询条件
     # @raise [ApiError] Zabbix API 返回业务错误时抛出
     # @raise [TransportError] Zabbix 服务端返回非成功 HTTP 状态时抛出
-    # @return [Hash] 匹配的图形完整数据
+    # @return [Array<Hash>] 匹配的图形完整数据
     def get_full_data(data)
-      log "[DEBUG] Call get_full_data with parameters: #{data.inspect}"
-
       @client.api_request(
         method: "#{method_name}.get",
         params: {
@@ -67,7 +59,7 @@ class ZabbixManager
     # @param data [Hash, String, Integer] 图形 ID
     # @raise [ApiError] Zabbix API 返回业务错误时抛出
     # @raise [TransportError] Zabbix 服务端返回非成功 HTTP 状态时抛出
-    # @return [Hash] 图形监控项数据
+    # @return [Array<Hash>] 图形监控项数据
     def get_items(data)
       @client.api_request(
         method: "graphitem.get",
@@ -78,12 +70,24 @@ class ZabbixManager
       )
     end
 
-    # 生成由图形名称和所属模板构成的稳定查询条件。
-    # @param data [Hash] 包含 name 和 templateid 的图形属性
+    # 生成由图形名称和所属主机或模板构成的稳定查询条件。
+    # graph.templateid 是继承源图形 ID，不是所属模板 ID。
+    # @param data [Hash] 包含 name 和 hostid 的图形属性
     # @return [Hash] 图形唯一查询条件
     def identity_filter(data)
       attributes = data.deep_symbolize_keys
-      { name: attributes.fetch(:name), templateid: attributes.fetch(:templateid) }
+      { name: attributes.fetch(:name), hostid: attributes.fetch(:hostid) }
+    end
+
+    # 图形所有者由 gitems 确定，hostid 仅用于调用方的身份查询。
+    # @return [Integer, nil]
+    def create(data)
+      super(data.deep_symbolize_keys.except(:hostid))
+    end
+
+    # @return [Integer, nil] 更新的图形 ID
+    def update(data)
+      super(data.deep_symbolize_keys.except(:hostid))
     end
   end
 end

data/lib/zabbix_manager/classes/{hostgroups.rb → host_groups.rb}

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  class HostGroups < Basic
+  # 主机群组名称解析与按需创建；批量创建按顺序执行，不是远端事务。
+  class HostGroups < Resource
     # 返回主机群组对应的 Zabbix API 方法前缀。
     #
     # @return [String]
@@ -9,13 +10,6 @@ class ZabbixManager
       "hostgroup"
     end
 
-    # 返回主机群组用于业务识别的字段名。
-    #
-    # @return [String]
-    def identify
-      "name"
-    end
-
     # 返回主机群组的 Zabbix ID 字段名。
     #
     # @return [String]
@@ -44,7 +38,7 @@ class ZabbixManager
     # 批量查询并创建缺失的主机群组，避免逐名称重复查询。
     # @param data [Array<String>, String] 待确保存在的群组名称
     # @return [Array<Hash>] 群组 ID 列表
-    def get_or_create_hostgroups(data)
+    def get_or_create_host_groups(data)
       names = normalized_names(data)
       existing = @client.api_request(
         method: "hostgroup.get",
@@ -53,10 +47,10 @@ class ZabbixManager
 
       names.map do |name|
         group = existing[name]
-        next({ groupid: group.fetch("groupid") }) if group
+        next({ groupid: response_identifier(group["groupid"]).to_s }) if group
 
         result = @client.api_request(method: "hostgroup.create", params: { name: name })
-        { groupid: result.fetch("groupids").first }
+        { groupid: response_id(result).to_s }
       end
     end