network-infra-utility 0.5.0 → 0.8.3

data/network-infra-utility.gemspec

@@ -18,16 +18,18 @@ Gem::Specification.new do |spec|
   spec.metadata["source_code_uri"] = "https://github.com/ChenMeng1365/network-infra-utility"
   spec.metadata["changelog_uri"]   = "https://github.com/ChenMeng1365/network-infra-utility/blob/main/CHANGELOG.md"
 
+  # example 用例随目录重组移至 document/example/, 排除规则同步覆盖新旧路径
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features|example)/}) }
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features|example|document/example)/}) }
   end
   # bin/ 既放对外命令 (geo-api) 也放开发脚本 (console/setup)，
   # executables 显式声明，避免把开发脚本当作系统命令安装到用户 PATH。
   spec.bindir       = "bin"
-  spec.executables  = %w[geo-api geo-get geo-load geo-doc]
-  spec.require_paths = ["document", "service", "service/ssh/lib", "support", "tool", "."]
+  spec.executables  = %w[geo-api geo-get geo-load geo-doc geo-update gen-get ngeo-get dns-query packbit probe]
+  spec.require_paths = ["document", "service", "service/ssh/lib", "service/simlab/lib", "support", "tool", "tool/probe/lib", "."]
 
-  # geo-api 命令行服务依赖的运行时 gem
+  # 仿真场景 DSL 需要的运行时 gem
+  spec.add_runtime_dependency "yaml", "~> 0.1"
   spec.add_runtime_dependency "roda", "~> 3.0"
   spec.add_runtime_dependency "rackup", "~> 2.0"
   spec.add_runtime_dependency "puma", "~> 6.0"

data/network.rb

@@ -15,12 +15,30 @@ module NetworkInfraUtility
   require_relative "support/basic/ip"
   require_relative "support/basic/as_num"
   require_relative "support/basic/mac_address"
+  require_relative "support/basic/packet"
+
+  # 路由原理层：依赖 support/basic
+  require_relative "support/routing/prefix"
+  require_relative "support/routing/lpm_trie"
+  require_relative "support/routing/rib"
+  require_relative "support/routing/static_route"
+  require_relative "support/routing/rip"
+  require_relative "support/routing/ospf"
+  require_relative "support/routing/bgp"
+
+  # 交换原理层：依赖 support/basic
+  require_relative "support/switching/mac_table"
+  require_relative "support/switching/frame_forward"
+  require_relative "support/switching/vlan"
+  require_relative "support/switching/stp"
 
   # 工具层：依赖 support
-  # require_relative "tool/xxx"
+  require_relative "tool/probe/lib/probe"
 
   # 服务层：依赖 tool / support
+  require_relative "service/simlab/lib/simlab"
   require_relative "service/ssh/lib/network_infra_utility/ssh"
+  require_relative "service/geoquery/geoquery"
 
   # 文档层：依赖 service / tool，最后加载
   # require_relative "document/xxx"

data/service/geodb/GeoAPI.md

@@ -1,3 +1,13 @@
+---
+AIGC:
+  ContentProducer: '001191110102MAD55U9H0F10002'
+  ContentPropagator: '001191110102MAD55U9H0F10002'
+  Label: '1'
+  ProduceID: 'f8a5515f-8063-4c0f-82de-6f5d3921a8d0'
+  PropagateID: 'f8a5515f-8063-4c0f-82de-6f5d3921a8d0'
+  ReservedCode1: 'e9dc29f2-2c00-4f09-a5c5-2d487e36268f'
+  ReservedCode2: 'e9dc29f2-2c00-4f09-a5c5-2d487e36268f'
+---
 
 # GeoAPI 测试用例
 
@@ -219,6 +229,54 @@ IP 合法性说明：含 `:` 按 IPv6 解析，否则按 IPv4 解析；非法地
 
 ---
 
+## (7) GEO_CACHE 外带缓存兜底 — `geo-api -a`
+
+服务端以 `geo-api -d GEODB_PATH -a GEO_CACHE [--priority local,cache]` 启动后，
+`addr` 类查询按顺位编排：先查本地 GeoLite2 库，本地查不到（404）时用 GEO_CACHE
+目录内 `geocacheYYYYMMDD.json`（`ngeo-get -c` 产出）的缓存定位信息兜底，统一
+schema 转换为各接口的 GeoLite2 风格响应，并附加 `"cached": true` 标记。
+`id` / `num` 类查询不适用缓存（非 IP 键）。目录内文件增删改自动感知，无需重启。
+
+### 7.1 启动与根路由
+
+| # | 命令 | 预期结果 |
+|---|------|----------|
+| 7.1.1 | `geo-api -d ./geodb -a ./GEO_CACHE` | 启动横幅显示缓存目录与文件数、兑底顺位 `local,cache` |
+| 7.1.2 | `curl -s "localhost:9292/"` | 200，含 `cache_dir` 与 `cache_order:"local,cache"` |
+| 7.1.3 | `geo-api -a ./不存在的目录` | 警告但继续启动（目录后续创建自动感知） |
+| 7.1.4 | `geo-api --priority cache,local` | 兑底顺位改为缓存优先 |
+
+### 7.2 缓存兜底查询
+
+预置 `GEO_CACHE/geocache20260101.json`：
+
+```json
+{ "203.0.113.7": { "state": "local", "country": "中国", "province": "浙江",
+  "city": "杭州", "asn": "4134", "asn_org": "Chinanet",
+  "network": "203.0.113.0/24", "ts": 100 } }
+```
+
+| # | curl 命令 | 预期结果 |
+|---|-----------|----------|
+| 7.2.1 | `curl -s "localhost:9292/geo/city?addr=203.0.113.7"` | 200，`geoname.subdivision_1_name:"浙江"`、`geoname.city_namezh:"杭州"`、`cached:true`（本地库无此 TEST-NET-3 地址，走缓存兜底）|
+| 7.2.2 | `curl -s "localhost:9292/geo/asn?addr=203.0.113.7"` | 200，`autonomous_system_number:"4134"`、`cached:true` |
+| 7.2.3 | `curl -s "localhost:9292/geo/country?addr=203.0.113.7"` | 200，`geoname.country_name:"中国"`、`cached:true` |
+| 7.2.4 | `curl -s "localhost:9292/geo/asn?addr=8.8.8.8"` | 200，Google LLC，**无** `cached` 字段（本地库命中，不走缓存，local 优先）|
+| 7.2.5 | 缓存记录 `state:"empty"` 的 IP 查 city | 404（缓存确认无归属，无兜底数据）|
+| 7.2.6 | 缓存记录无 `asn` 字段的 IP 查 asn | 404（对应字段缺失，该接口无数据）|
+
+### 7.3 兜底响应结构（缓存命中）
+
+```json
+{
+  "network": "203.0.113.0/24",
+  "geoname": { "country_name": "中国", "subdivision_1_name": "浙江", "city_namezh": "杭州" },
+  "cached": true
+}
+```
+
+---
+
 ## 备注
 
 1. **ASN 的 `num` 非数字**：需求第(1)点只要求 city/country 的 id 做数字校验，未规定 asn 的 num。当前实现在 `num=abc` 时返回 `count:0`（空结果，状态 200）。如需返回 `400 ASN编号不合法`，可在 `api.rb` 中加一行校验。
@@ -226,3 +284,9 @@ IP 合法性说明：含 `:` 按 IPv6 解析，否则按 IPv4 解析；非法地
 2. **city-IPv6.json**：当前 `geodb/` 目录下已生成此文件，IPv6 city 查询可正常命中。文件缺失时服务端会容错返回 `无结果`（404），不影响其他接口。
 
 3. **加载耗时（首次，含 JSON 解析）**：asn 约 3.5s / country-IPv4 约 2.9s / country-IPv6 约 3.6s / city-IPv4 约 22.8s，之后常驻内存走缓存，查询耗时约 0ms。
+
+4. **GEO_CACHE 与服务端缓存（`@store`）的区别**：`@store` 是数据文件加载内存缓存（进程内常驻）；GEO_CACHE 是外带定位信息缓存目录（ngeo-get 产出的查询结果），用于 addr 查询兜底，两者互不影响。
+
+5. **geo-api 的顺位参数是 `--priority`**（不是 `-p`）：`-p` 已被监听端口占用。服务端仅支持 `local,cache` 排列（无互联网源）；客户端 `ngeo-get -p` 支持 `cache,local,internet` 三源排列。
+
+> AI生成

data/service/geodb/api.rb

@@ -6,7 +6,14 @@
 #
 # 数据文件目录通过环境变量 GEODB_DATA_DIR 指定，默认 ./geodb/
 # 用 -d/--data-dir 参数 (命令行) 或设置该环境变量可指向任意位置。
+#
+# GEO_CACHE 外带缓存 (bin/geo-api -a 或环境变量 GEODB_CACHE_DIR 指定目录):
+#   目录内 geocacheYYYYMMDD.json (ngeo-get -c 产出) 作为缓存定位信息。
+#   addr 查询按 GEODB_CACHE_ORDER 顺位 (默认 local,cache) 编排:
+#   先查本地 GeoLite2 库, 查不到时用缓存记录兑底 (统一 schema 转为
+#   各接口的 GeoLite2 风格响应, 对客户端透明)。目录内文件增删改自动感知。
 ['cc','CasetDown/casetdown','network','roda'].each{|mod| require mod}
+require_relative '../geoquery/geo_cache'
 
 module GeoDB
   module_function
@@ -26,6 +33,26 @@ module GeoDB
   # asn 反向索引: autonomous_system_number => [record, ...]
   @asn_index = {}
   @lock = Mutex.new
+  # GEO_CACHE 外带缓存实例 (GEODB_CACHE_DIR 设置时启用)
+  @geo_cache = nil
+
+  # ---- GEO_CACHE 外带缓存 -------------------------------------------------
+
+  # 缓存实例 (惰性建立; 目录不存在时仍建立, 后续创建/产出可自动感知)
+  def geo_cache
+    @geo_cache ||= begin
+      d = ENV['GEODB_CACHE_DIR'].to_s
+      d.empty? ? nil : GeoQuery::GeoCache.new(d)
+    end
+  end
+
+  # 查询顺位: local (GeoLite2 库) 与 cache (GEO_CACHE) 的适用顺序。
+  # GEODB_CACHE_ORDER 指定 (bin/geo-api --priority), 默认 local,cache。
+  def cache_order
+    parts = ENV['GEODB_CACHE_ORDER'].to_s.split(/[,\s]+/).map(&:strip).reject(&:empty?)
+    parts = %w[local cache] if parts.empty?
+    parts.select { |p| %w[local cache].include?(p) }.uniq
+  end
 
   # ---- 加载 ---------------------------------------------------------------
 
@@ -112,6 +139,44 @@ module GeoDB
     (number >= s && number <= e) ? r : nil
   end
 
+  # ---- addr 查询编排 (本地库 + GEO_CACHE) ---------------------------------
+
+  # 按 cache_order 顺位查本地库与 GEO_CACHE (kind: :asn/:city/:country)
+  # 返回: :invalid(IP不合法) / nil(无结果) / record
+  def lookup_addr(kind, addr)
+    num = ip_number(addr)
+    return :invalid unless num
+    cache_order.each do |src|
+      r = src == 'cache' ? cache_lookup(kind, addr) : local_lookup(kind, addr, num)
+      return r if r
+    end
+    nil
+  end
+
+  # 本地 GeoLite2 库查询 (原 addr 查询逻辑)
+  def local_lookup(kind, addr, num)
+    case kind
+    when :asn
+      find_range('asn', num)
+    when :city
+      r = find_range(ipv6?(addr) ? 'city-IPv6' : 'city-IPv4', num)
+      r ? enrich(r, 'geo-city') : nil
+    when :country
+      r = find_range(ipv6?(addr) ? 'country-IPv6' : 'country-IPv4', num)
+      r ? enrich(r, 'geo-country') : nil
+    end
+  end
+
+  # GEO_CACHE 兑底: 命中则把统一 schema 转为该接口的 GeoLite2 风格响应
+  # (对应字段缺失时 to_geolite 返回 nil, 继续下一数据源)
+  def cache_lookup(kind, addr)
+    gc = geo_cache
+    return nil unless gc
+    hit = gc.lookup(addr)
+    return nil unless hit
+    GeoQuery::GeoCache.to_geolite(kind, hit)
+  end
+
   # ---- ASN 接口 (1) -------------------------------------------------------
 
   # /geo/asn?num=XXX  查出该 AS 的所有地址段
@@ -120,12 +185,10 @@ module GeoDB
     @asn_index[num.to_s] || []
   end
 
-  # /geo/asn?addr=X.X.X.X  按 IP 查所属 AS
+  # /geo/asn?addr=X.X.X.X  按 IP 查所属 AS (本地库 → GEO_CACHE 兑底)
   # 返回: :invalid(IP不合法) / nil(无结果) / record
   def asn_by_addr(addr)
-    num = ip_number(addr)
-    return :invalid unless num
-    find_range('asn', num)
+    lookup_addr(:asn, addr)
   end
 
   # ---- City 接口 (2)(3) ---------------------------------------------------
@@ -138,15 +201,11 @@ module GeoDB
     g ? g[id.to_s] : nil
   end
 
-  # /geo/city?addr=X.X.X.X  先查 city-IPv4/city-IPv6, 再关联 geo-city
+  # /geo/city?addr=X.X.X.X  先查 city-IPv4/city-IPv6, 再关联 geo-city;
+  # 无结果时 GEO_CACHE 兑底
   # 返回: :invalid / nil / enriched_record
   def city_by_addr(addr)
-    num = ip_number(addr)
-    return :invalid unless num
-    name = ipv6?(addr) ? 'city-IPv6' : 'city-IPv4'
-    r = find_range(name, num)
-    return nil unless r
-    enrich(r, 'geo-city')
+    lookup_addr(:city, addr)
   end
 
   # ---- Country 接口 (4)(5) ------------------------------------------------
@@ -158,14 +217,10 @@ module GeoDB
     g ? g[id.to_s] : nil
   end
 
-  # /geo/country?addr=X.X.X.X  先查 country-IPv4/country-IPv6, 再关联 geo-country
+  # /geo/country?addr=X.X.X.X  先查 country-IPv4/country-IPv6, 再关联
+  # geo-country; 无结果时 GEO_CACHE 兑底
   def country_by_addr(addr)
-    num = ip_number(addr)
-    return :invalid unless num
-    name = ipv6?(addr) ? 'country-IPv6' : 'country-IPv4'
-    r = find_range(name, num)
-    return nil unless r
-    enrich(r, 'geo-country')
+    lookup_addr(:country, addr)
   end
 
   # ---- 关联聚合 -----------------------------------------------------------
@@ -203,15 +258,18 @@ class GeoAPI < Roda
 
   route do |r|
     r.root do
-      {
+      info = {
         service: 'GeoDB API',
         data_dir: GeoDB.data_dir,
+        cache_order: GeoDB.cache_order.join(','),
         endpoints: {
           'asn'     => '/geo/asn?num=XXX | /geo/asn?addr=X.X.X.X',
           'city'    => '/geo/city?id=XXX | /geo/city?addr=X.X.X.X',
           'country' => '/geo/country?id=XXX | /geo/country?addr=X.X.X.X'
         }
       }
+      info[:cache_dir] = GeoDB.geo_cache.dir if GeoDB.geo_cache
+      info
     end
 
     r.on 'geo' do

data/service/geoquery/GeoQuery.md

@@ -0,0 +1,309 @@
+---
+AIGC:
+  ContentProducer: '001191110102MAD55U9H0F10002'
+  ContentPropagator: '001191110102MAD55U9H0F10002'
+  Label: '1'
+  ProduceID: 'aacf6d8c-3f16-44a6-ad5e-9dec92704459'
+  PropagateID: 'aacf6d8c-3f16-44a6-ad5e-9dec92704459'
+  ReservedCode1: 'c7410cd1-7a15-4cf5-b8f2-5c2ed30d33f1'
+  ReservedCode2: 'c7410cd1-7a15-4cf5-b8f2-5c2ed30d33f1'
+---
+
+# GeoQuery 综合查询接口
+
+> 模块目录：`service/geoquery/`  
+> 命令行入口：`bin/gen-get`（纯互联网）、`bin/ngeo-get`（缓存 + 本地 + 互联网综合）  
+> 设计蓝本：`ip_geo_lookup.py`（多级回退 + 缓存 + 归一化），按"叠加综合"需求重构为 Ruby 实现
+
+## 一、命令总览
+
+| 命令 | 数据源 | 说明 |
+|------|--------|------|
+| `geo-get` | 本地 geo-api (GeoLite2) | 三接口齐查，纯本地；为 `GeoQuery::LocalClient` 的瘦封装（三接口拉取与汇总逻辑收口在 geoquery）|
+| `gen-get` | 互联网 ip-api.com | 免费接口（限 45 req/min，无需 Key） |
+| `ngeo-get` | 缓存 + 本地 + 互联网 | 按 `-p` 顺位逐源查询（默认 cache→local→internet），满意即停，字段级叠加 |
+
+三个查询命令共享同一套客户端实现（`GeoQuery::LocalClient` / `GeoQuery::OnlineClient` /
+`GeoQuery::GeoCache`），无双实现。
+
+## 二、ngeo-get 查询模型（三源顺位）
+
+```
+1. 会话缓存 (ngeo-cache.json) 命中 → 直接返回
+2. 按 -p 顺位逐源查询 (默认 cache → local → internet):
+     cache    GEO_CACHE 外带缓存目录 (geocacheYYYYMMDD.json, -a 指定)
+     local    本地 geo-api 服务 (GeoLite2)
+     internet 互联网 ip-api.com (限速 + 熔断保护)
+3. 每源结果按顺位折叠: 先查的源字段优先, 后查的补空缺
+4. 折叠后归属满意 (省/市/ASN 齐全) → 提前终止, 不再查后续源
+5. 全部源查完仍不满意 → 组装终态 (叠加/部分/空/不可达)
+```
+
+### 结果状态 (state) 可信度排序
+
+**`unreachable` < `local-partial` < `cache-partial` < `empty` < `cache` < `local` < `online` < `merged`**
+
+| state | 含义 | 触发条件 |
+|-------|------|----------|
+| `unreachable` | 各源均无结果且有不联通 (最低) | 本地无结果 + 互联网不可达 + 缓存未命中 |
+| `local-partial` | 本地部分结果 | 本地归属不满意 + 其余源无补充，保留本地字段 |
+| `cache-partial` | 缓存部分结果 | 缓存归属不满意 + 其余源无补充，保留缓存字段 |
+| `empty` | 各源均确认无归属 | 如私有/保留地址 (ip-api 返回 `private range`) |
+| `cache` | 缓存命中且满意 | GEO_CACHE 内记录省市 ASN 齐全 |
+| `local` | 本地结果满意 | 省/市/ASN 齐全，无需互联网 |
+| `online` | 纯互联网结果 | 本地无结果或 geo-api 未启动，互联网查询成功 |
+| `merged` | 多源叠加综合 (最高) | 缓存/本地部分结果 + 互联网或其他源补全，字段级择优 |
+
+### 字段叠加规则 (Merge)
+
+重点准确字段：**省 (Province) / 城市 (City) / 用途 (IDC、云)**，越准确越好。
+按顺位折叠：先查的源为 base，后查的源为 supp。
+
+| 字段 | 择优规则 |
+|------|----------|
+| country / province / city / asn / asn_org | base 优先，base 空取 supp (GeoLite2 网段级数据有值时可信；本地省市缺失率高，由 ip-api.com / GEO_CACHE 补全) |
+| network (网段 CIDR) | base 优先，base 空取 supp (互联网源无网段，实际补给来自本地库与缓存) |
+| isp | 按合并后的 asn_org 重新归一化 (长名 → 电信/联通/移动/腾讯云… 简称) |
+| usage | 两方组织名综合推断: 云 / IDC / CDN / 教育网 / 运营商 / 企业 / 未知 |
+
+## 三、GEO_CACHE 外带缓存
+
+ngeo-get 与 geo-api 均可外带一个缓存目录，目录内的定位信息作为缓存数据源。
+
+### 3.1 格式
+
+```sh
+# 服务器端: GEO_CACHE 内的缓存定位信息作为 addr 查询兑底
+geo-api -d GEODB_PATH -a GEO_CACHE
+
+# 客户端: 查询时缓存目录数据纳入备选
+ngeo-get X.X.X.X -a GEO_CACHE
+```
+
+缓存文件为 `geocacheYYYYMMDD.json`（XXXXXXXX 为 8 位日期时间标签），
+内容与 `ngeo-cache.json` 同构：`{ "ip" => { 统一 schema 结果, "ts" => 时间戳 } }`。
+目录内文件增删改自动感知，无需重启；多文件同 IP 冲突取 `ts` 最新。
+
+### 3.2 顺位 (-p)
+
+`-p` 决定本地库 (local) / 互联网库 (internet) / 缓存库 (cache) 的适用顺序：
+
+```sh
+ngeo-get X.X.X.X -a GEO_CACHE -p local,internet,cache  # 本地优先, 互联网次之, 缓存兑底
+ngeo-get X.X.X.X -a GEO_CACHE                          # 默认 -p cache,local,internet
+```
+
+| 顺位 | 语义 |
+|------|------|
+| `cache,local,internet` (默认) | 优先缓存 → 本地库 → 互联网 |
+| `local,internet,cache` | 本地优先，本地查不到才找互联网，互联网查不到或不通再查缓存 |
+
+顺位即优先级：先查的源字段优先，后查的补空缺；折叠后满意 (省/市/ASN 齐全)
+即停，不再查后续源。源不可用自动跳过（无 `-a` 时 cache 源不存在；
+`--refresh` 跳过全部缓存；`--no-local` 跳过本地）。
+
+服务端 `geo-api` 的顺位参数为 `--priority`（`-p` 已被端口占用），
+仅支持 `local,cache` 排列，默认 `local,cache`。
+
+### 3.3 产出 (-c / -nc)
+
+每次查询的结果默认保存下来用于后续缓存：
+
+```sh
+ngeo-get 1.2.3.4 -a GEO_CACHE     # 查询结果默认保存到 GEO_CACHE/geocacheYYYYMMDD.json
+ngeo-get 1.2.3.4 -a GEO_CACHE -nc # 不保存产出
+```
+
+- 保存位置：`-a` 指定的目录；未指定时为当前目录（可用环境变量 `GEO_CACHE_DIR` 覆盖）
+- 命名：`geocacheYYYYMMDD.json`，同一天多次查询自动归并到同一文件，同 IP 以新结果覆盖
+- 仅保存可缓存状态 (`local` / `merged` / `online` / `empty` / `cache`)；
+  `unreachable` / `local-partial` / `cache-partial` 不落盘（下次重查自动补全）
+- `-c` 为默认行为（显式指定等效），`-nc` 关闭
+
+### 3.4 整理 (-m)
+
+```sh
+ngeo-get -m GEO_CACHE
+# 合并完成: 3 个缓存文件 → 128 条记录
+# 输出文件: /path/GEO_CACHE/geocacheYYYYMMDD.json (生成时间为时间标签)
+```
+
+将 GEO_CACHE 目录下所有 `geocacheYYYYMMDD.json` 格式的数据合并，生成一个新的
+`geocacheYYYYMMDD.json`（新生成时间为合并生成时间），同 IP 冲突取 `ts` 最新。
+源文件保留不删除，重复执行幂等。
+
+## 四、gen-get 接口与参数
+
+默认调用 ip-api.com 免费接口（与 `ip_geo_lookup.py` 的默认配置一致，`message` 字段为诊断扩展）：
+
+```
+http://ip-api.com/json/{ip}?lang=zh-CN&fields=status,message,country,regionName,city,isp,as,query
+```
+
+| gen-get state | 触发条件 | 缓存 |
+|---------------|----------|------|
+| `ok` | `status: success` | 落盘 |
+| `empty` | `status: fail` (如私有地址 `private range`) | 落盘 |
+| `unreachable` | 网络异常 / 超时 / HTTP 429 限速 / 非 200 | 不落盘 (下次重试) |
+| `invalid` | IP 参数不合法 | 不落盘 |
+
+内置限速：两次请求间隔 ≥ 1.4s（对齐 45 req/min 免费限额）；`--timeout` 控制连接/读取超时（默认 10s）。
+
+## 五、命令行用法
+
+```sh
+# gen-get — 互联网查询
+gen-get 8.8.8.8                     # 文字格式
+gen-get 8.8.8.8 -j                  # JSON 格式
+gen-get 1.1.1.1 8.8.8.8            # 多 IP (自动限速)
+cat ips.txt | gen-get -j            # stdin 逐行读 IP
+gen-get 8.8.8.8 --refresh           # 忽略缓存强刷
+gen-get --cache-stats               # 缓存统计
+
+# ngeo-get — 综合查询 (三源顺位)
+ngeo-get 111.8.44.6                 # 默认顺位 cache,local,internet
+ngeo-get 111.8.44.6 -j              # JSON
+ngeo-get 111.8.44.6 -a ./GEO_CACHE  # 外带缓存目录
+ngeo-get 111.8.44.6 -p local,internet,cache -a ./GEO_CACHE   # 本地优先, 缓存兑底
+ngeo-get 111.8.44.6 -nc             # 查询但不产出缓存文件
+ngeo-get -m ./GEO_CACHE             # 合并目录下全部 geocache*.json
+ngeo-get 111.8.44.6 --no-local      # 跳过本地, 仅互联网
+ngeo-get 111.8.44.6 --geoapi http://127.0.0.1:9292   # 覆盖本地服务地址
+ngeo-get 111.8.44.6 --api "http://ip-api.com/json/{ip}?lang=zh-CN&fields=..."  # 覆盖互联网接口
+ngeo-get --cache-stats               # 会话缓存统计 (-a 时附加 GEO_CACHE 统计)
+```
+
+退出码：`0` 查询完成（含 `empty` / `local-partial` / `cache-partial`）；`1` IP 不合法或参数错误；`2` 互联网不可达（且其余源无结果）。
+
+## 六、结果 schema（ngeo-get -j）
+
+```json
+{
+  "ip": "111.8.44.6",
+  "state": "merged",
+  "message": "",
+  "country": "中国",
+  "province": "湖南",
+  "city": "青园",
+  "isp": "移动",
+  "asn": "56047",
+  "asn_org": "China Mobile communications corporation",
+  "network": "111.8.0.0/15",
+  "usage": "运营商",
+  "source": "ngeo(geo-get+gen-get)",
+  "sources": {
+    "cache":  { "state": "miss", "message": "GEO_CACHE 缓存未命中" },
+    "local":  { "state": "ok", "verdict": "不满意" },
+    "online": { "state": "ok" }
+  },
+  "ts": 1789370023
+}
+```
+
+`sources` 键：`cache` / `local` / `online`，未参与查询的源标 `skipped`；
+`source` 字段按参与叠加的源组合，如 `ngeo(geo-cache+geo-get)`。
+
+## 七、测试用例
+
+### 7.1 ngeo-get 状态机
+
+| # | 命令 | 预期结果 |
+|---|------|----------|
+| 7.1.1 | `ngeo-get 219.140.0.1 -j` | `state: local`（本地省市 ASN 齐全，`online: skipped`） |
+| 7.1.2 | `ngeo-get 111.8.44.6 -j` | `state: merged`，省/市来自互联网，`network` 保留本地网段 |
+| 7.1.3 | `ngeo-get 219.140.0.1 --geoapi http://127.0.0.1:9999 -j` | `state: online`（本地不可用，纯互联网） |
+| 7.1.4 | `ngeo-get 111.8.44.6 --api http://192.0.2.1/x/{ip} --timeout 2` | `state: local-partial`，message 含"互联网查询不可达"，本地 ASN/网段保留 |
+| 7.1.5 | `ngeo-get 10.20.30.40 --api http://192.0.2.1/x/{ip} --timeout 2 -j` | `state: unreachable`，全部字段为空，退出码 2 |
+| 7.1.6 | `ngeo-get 10.20.30.40 -j` | `state: empty`（`private range`） |
+| 7.1.7 | `ngeo-get 999.1.1.1 -j` | `state: invalid`，退出码 1 |
+| 7.1.8 | 连续查询同一 IP 两次 | 第二次 `cached: true`（JSON）或"缓存命中"（文字） |
+
+### 7.2 gen-get
+
+| # | 命令 | 预期结果 |
+|---|------|----------|
+| 7.2.1 | `gen-get 8.8.8.8` | `state: ok`，国家/省/市/ASN 齐全，`usage: 云` |
+| 7.2.2 | `gen-get 10.20.30.40 -j` | `state: empty`，message 为 `private range` |
+| 7.2.3 | `gen-get 8.8.8.8 --api http://192.0.2.1/x/{ip} --timeout 2` | `state: unreachable`，退出码 2 |
+| 7.2.4 | `echo 8.8.4.4 \| gen-get -j` | stdin 输入，正常查询 |
+
+### 7.3 GEO_CACHE 外带缓存
+
+预置 `./GEO_CACHE/geocache20260101.json` 含某本地库没有的 IP（如 `203.0.113.7`）的完整定位记录。
+
+| # | 命令 | 预期结果 |
+|---|------|----------|
+| 7.3.1 | `ngeo-get 203.0.113.7 -a ./GEO_CACHE -j` | `state: cache`，`cached: true`，`sources.local/online: skipped`（默认顺位缓存命中） |
+| 7.3.2 | `ngeo-get 203.0.113.7 -p local,internet,cache -a ./GEO_CACHE --api http://192.0.2.1/x/{ip} --timeout 2 -j` | local 空 + internet 不通 + 缓存兑底，`state: cache` |
+| 7.3.3 | `ngeo-get 203.0.113.7 -a ./GEO_CACHE -nc -j` | 查询正常，不修改产出文件（`-nc`） |
+| 7.3.4 | `ngeo-get 1.2.3.4 -a ./GEO_CACHE -j` | 查询后 `./GEO_CACHE/geocacheYYYYMMDD.json` 生成，含本次结果 |
+| 7.3.5 | `ngeo-get -m ./GEO_CACHE` | 合并目录内全部 geocache 文件，输出新文件，退出码 0 |
+| 7.3.6 | `ngeo-get 1.2.3.4 -p bogus -j` | 报"无效顺位"退出码 1 |
+| 7.3.7 | `geo-api -d ./geodb -a ./GEO_CACHE` 后 `curl "localhost:9292/geo/city?addr=203.0.113.7"` | 200，缓存兑底，`cached: true`（详见 GeoAPI.md 第 7 节） |
+
+## 八、缓存与配置
+
+| 项 | 说明 |
+|----|------|
+| 会话缓存目录 | `ENV["NGEO_CACHE_DIR"]`，默认 `~/.network-infra-utility/` |
+| 会话缓存文件 | `gen-cache.json`（gen-get 互联网层）/ `ngeo-cache.json`（ngeo 综合层） |
+| 会话缓存策略 | `local` / `merged` / `online` / `empty` / `cache` 落盘；`unreachable` / `local-partial` / `cache-partial` 不落盘（下次重查，互联网恢复后自动补全）；`--refresh` 强制重查 |
+| GEO_CACHE 外带缓存 | `-a DIR` 指定；产出目录未指定时 `ENV["GEO_CACHE_DIR"]` > 当前目录 |
+| GEO_CACHE 产出 | `-c` 默认开启：结果写入 `geocacheYYYYMMDD.json`；`-nc` 关闭 |
+| GEO_CACHE 整理 | `-m DIR` 合并目录内全部缓存文件为新文件 |
+| 本地服务地址 | `--geoapi` 或 `ENV["GEO_API_BASE"]`，默认 `http://127.0.0.1:9292` |
+| 互联网接口 | `--api`（`{ip}` 占位符），默认 ip-api.com 免费接口 |
+| 熔断 | 连续 3 次互联网不可达后，60s 内跳过在线查询直接返回 unreachable |
+
+## 九、代码级用法
+
+```ruby
+require "geoquery/geoquery"   # gem 安装后 (require_paths 含 service/)
+
+# 纯互联网
+online = GeoQuery::OnlineClient.new(timeout: 10)
+r = online.lookup("8.8.8.8")          # → state: ok/empty/unreachable/invalid
+
+# 本地原始接口查询 (bin/geo-get 底座)
+local = GeoQuery::LocalClient.new     # base 默认 9292 (geo-get 另支持 ENV["GEO_API_BASE"])
+raw = local.fetch_raw("8.8.8.8")      # → { country: body|nil, city: body|nil, asn: body|nil }
+raw = local.fetch_raw("8.8.8.8", endpoints: %i[asn])  # → 单接口子集
+# fetch_raw 返回 :unreachable 表示 geo-api 服务不可达
+
+# 本地归一化查询 (ngeo 内部同款)
+r = local.lookup("8.8.8.8")           # → 统一 schema, state: ok/empty/unavailable/invalid
+
+# 综合 (三源顺位, 默认 cache,local,internet)
+ngeo = GeoQuery::NGeo.new(geo_cache_dir: "./GEO_CACHE")   # -a 外带缓存
+r = ngeo.lookup("111.8.44.6")         # → 统一 schema (见第六节)
+ngeo.lookup("1.2.3.4", refresh: true, no_local: false)
+ngeo.save_cache
+
+# 顺位自定义 (等效 -p)
+ngeo = GeoQuery::NGeo.new(geo_cache_dir: "./GEO_CACHE",
+                          order: "local,internet,cache")
+
+# GEO_CACHE 外带缓存 (service/geoquery/geo_cache.rb)
+gc = GeoQuery::GeoCache.new("./GEO_CACHE")
+gc.lookup("8.8.8.8")                  # → 缓存记录 (附加 cached: true) 或 nil
+gc.put_batch([{ "ip" => "8.8.8.8", "state" => "merged", ... }])  # 产出
+gc.merge!                             # → { "files" =>, "entries" =>, "output" => }
+GeoQuery::GeoCache.parse_order("cache,local,internet")  # → 顺位数组或 nil
+GeoQuery::GeoCache.to_geolite(:city, hit)  # 统一 schema → GeoLite2 风格 (服务端兑底)
+
+# 归一化工具
+GeoQuery::Normalize.isp_from_asn("CHINATELECOM Hubei province 5G network")  # => "电信"
+GeoQuery::Normalize.usage_from_asn("Tencent cloud")                         # => "云"
+GeoQuery::Merge.fields(local_result, online_result)                         # => 字段叠加
+```
+
+## 备注
+
+1. **gen-get 的 `unreachable` 语义**：表示"互联网查询不可达"（网络不通/超时/限速），区别于 `empty`（互联网确认无归属，如私有地址）。不可达结果不缓存，恢复后重查即可。
+2. **`local-partial` / `cache-partial` 的取舍**：互联网不可达时，本地/缓存的部分结果（如 ASN/网段）仍有价值，予以保留并标注；完全无数据时才降级为 `unreachable` 空状态。
+3. **本地 geo-api 未启动**：ngeo-get 不视为错误（`local: unavailable`），自动走纯互联网路径，返回 `state: online`；geo-get 则直接报错并提示启动命令（可用 `GEO_API_BASE` 环境变量覆盖服务地址）。
+4. **ip-api.com 免费接口限制**：45 req/min、仅 HTTP（无 HTTPS）、仅限自用。批量场景已内置 1.4s 最小间隔；更高需求可 `--api` 切换付费批量接口（pro.ip-api.com）。
+5. **GEO_CACHE 与会话缓存的分工**：`ngeo-cache.json` 是进程自动维护的会话缓存（命中直接返回，不参与 `-p` 顺位）；GEO_CACHE 是用户显式外带的缓存目录（作为顺位中的 `cache` 数据源，产出可拷贝/合并/供服务端兑底）。`--refresh` 两者均跳过。
+6. **服务端顺位参数为何是 `--priority`**：`geo-api -p` 已被监听端口占用，故服务端顺位用 `--priority`（仅 `local,cache` 排列）；客户端 `ngeo-get -p` 无冲突，支持三源排列。
+
+> AI生成