docs: 顶层 README 更新——包清单按类归组 + go-hua 迁移对照表

- 新增 28 个迁入包的分类清单(基础工具/网络协议/系统与硬件)
- go-hua→zogo 包名替换对照表(含不迁入项: log 弃用/qps 空壳/remote 归 remote-core)
- examples 例程约定写入开发约定

README.md

@@ -5,28 +5,92 @@ zeroone Go 通用库（单仓多包，顶层即包）。被各后端服务以 Go
 
 ## 包清单
 
+### 服务开发
+
 | 包 | 用途 | 文档 |
 |---|---|---|
-| `httpx` | Gin 统一出入参：OkJson/ErrorJson（CodeMsg 错误码透传）、Handle/HandleResult、Parse（uri→query→header→json 顺序绑定 + binding 校验收口） | [httpx/README.md](httpx/README.md) |
+| `httpx` | Gin 统一出入参：OkJson/ErrorJson（CodeMsg 错误码透传）、Handle/HandleResult、Parse（uri→query→header→json 顺序绑定 + binding 校验收口）、ParseXML | [httpx/README.md](httpx/README.md) |
 | `logger` | logrus 日志初始化（控制台彩色 + 按天轮转文件 + 历史压缩） | [logger/README.md](logger/README.md) |
 | `wsc` | WebSocket 服务端框架（会话/房间/路由）+ 配套客户端（自动重连），同一 Message 信封 | [wsc/README.md](wsc/README.md) |
 | `jwtx` | 轻量 HMAC-SHA256 令牌签发与校验 | [jwtx/README.md](jwtx/README.md) |
+| `snowid` | 雪花 ID 生成器（进程内单例）+ GORM 模型 ID 钩子模板 | [snowid/README.md](snowid/README.md) |
+
+### 基础工具（自 go-hua 迁入）
+
+| 包 | 用途 | 文档 |
+|---|---|---|
+| `stringx` | 字符串/切片工具：随机串、UUID、通配符匹配、校验规则、中文首字母 | [stringx/README.md](stringx/README.md) |
+| `timex` | 时间日期：NT/UTC 时间戳互转、时间字符串转毫秒时间戳、月份天数 | [timex/README.md](timex/README.md) |
+| `filex` | 文件目录：运行目录定位、路径存在性、进度下载、Zip 压缩解压（GBK 兼容） | [filex/README.md](filex/README.md) |
+| `cryptox` | MD5 摘要：字符串/字节集/文件 | [cryptox/README.md](cryptox/README.md) |
+| `netx` | 本机网络信息：IPv4 与 MAC 地址枚举 | [netx/README.md](netx/README.md) |
+| `numx` | 数值工具：流量格式化、低位取整、多整数取最值 | [numx/README.md](numx/README.md) |
+| `verx` | 版本号：点分版本解析/还原/比较 | [verx/README.md](verx/README.md) |
+| `counter` | 线程安全 string→int64 键值计数器（原 go-hua/single 更名） | [counter/README.md](counter/README.md) |
+| `queue` | 链式先进先出队列（哨兵头结点风格） | [queue/README.md](queue/README.md) |
+
+### 网络协议（自 go-hua 迁入）
+
+| 包 | 用途 | 文档 |
+|---|---|---|
+| `frame` | 应用层帧协议：8 字节头（版本+命令+长度+流 ID）+ 数据，Conn 读写封装 | [frame/README.md](frame/README.md) |
+| `proto` | 长度前缀封包协议编解码（含 CRC32 校验版） | [proto/README.md](proto/README.md) |
+| `bytepacket` | 二进制封包/解包（小端序，兼容易语言协议、GBK、易语言日期） | [bytepacket/README.md](bytepacket/README.md) |
+| `conn` | net.Conn 装饰器：透明叠加带宽限速（rate）与流量统计（flow） | [conn/README.md](conn/README.md) |
+| `listen` | net.Listener 简单封装（Close 解除 Accept 阻塞） | [listen/README.md](listen/README.md) |
+| `flow` | 并发安全流量统计（收发字节累计/取走清零） | [flow/README.md](flow/README.md) |
+| `rate` | 按秒配额的带宽限速器 | [rate/README.md](rate/README.md) |
+| `httpprobe` | 按首部字节探测 HTTP/HTTPS 流量（原 go-hua/http 更名） | [httpprobe/README.md](httpprobe/README.md) |
+| `httpc` | HTTP 客户端：GET/POST/PUT/DELETE/代理/Digest 认证（原 go-hua/httpurl 更名） | [httpc/README.md](httpc/README.md) |
+| `nettest` | 网络连通性探测：TCP 端口 + 原始 ICMP Ping，统计成功率与延迟 | [nettest/README.md](nettest/README.md) |
+| `spmux` | 单端口多路复用：按报文特征分发到 HTTP/HTTPS/TCP 三个 Listener | [spmux/README.md](spmux/README.md) |
+| `ipratelimiter` | 按 IP 维度的令牌桶限流器 | [ipratelimiter/README.md](ipratelimiter/README.md) |
+
+### 系统与硬件（自 go-hua 迁入）
+
+| 包 | 用途 | 文档 |
+|---|---|---|
+| `arp` | 系统 ARP 表读取与 IP→MAC 查询（定时刷新缓存） | [arp/README.md](arp/README.md) |
+| `dll` | Windows API 封装：互斥体防多开、ShellExecute、窗口操作 | [dll/README.md](dll/README.md) |
+| `hardware` | 硬件信息采集（WMI）与硬件变更检测 | [hardware/README.md](hardware/README.md) |
+| `monitor` | 系统资源监控：CPU/内存/磁盘/网络/进程/连接/主机，后台采集 | [monitor/README.md](monitor/README.md) |
+| `dotnet` | .NET Framework 安装信息（Windows 注册表，原 go-hua/netFramework 更名） | [dotnet/README.md](dotnet/README.md) |
+| `ipquery` | IP/域名归属地查询（ip2region xdb 全内存加载） | [ipquery/README.md](ipquery/README.md) |
+| `mail` | SMTP 邮件发送（收/抄/密送、HTML 正文） | [mail/README.md](mail/README.md) |
+| `certx` | x509 证书解析校验与自签生成（原 go-hua/ssl 更名） | [certx/README.md](certx/README.md) |
+| `gormtypes` | GORM/JSON 双向转换类型：八种 Slice/Map 类型（原 go-hua/datatypes 更名） | [gormtypes/README.md](gormtypes/README.md) |
+| `cafegame` | 网咖游戏识别与运行记录上报（网吧业务专用） | [cafegame/README.md](cafegame/README.md) |
 
 > 历史说明：v0.1.0 曾存在独立包 `wscclient`，v0.2.0 起并入 `wsc`（`wsc.Client`）——
 > 客户端与服务端共用信封定义，协议单一来源防两端漂移。
 
+## go-hua 迁移对照
+
+2026-09 自 `github.com/4566704/go-hua` 迁入并整理，消费方替换对照：
+
+| go-hua 包 | zogo 去处 | 说明 |
+|---|---|---|
+| `common` | 拆分为 `stringx` / `timex` / `filex` / `cryptox` / `netx` / `numx` / `verx`；`frame.go` 独立为 `frame` | 拆大杂烩，按职责归位 |
+| `http` | `httpprobe` | 实为协议探测，与 net/http 混淆故更名 |
+| `httpurl` | `httpc` | 实为 HTTP 客户端 |
+| `single` | `counter` | 实为键值计数器 |
+| `netFramework` | `dotnet` | 实为 .NET Framework 信息查询 |
+| `ssl` | `certx` | 实为 x509 证书操作 |
+| `datatypes` | `gormtypes` | 避免与 gorm.io/datatypes 混淆 |
+| `log` | **不迁入**（已弃用） | 消费方用 `logger`（logrus）；spmux 已改为 `spmux.Logger` 接口 |
+| `snowid` / `gormhook` | 已被 `snowid` 覆盖（v0.2.0 吸收），不再迁入 | |
+| `httpx` | 已存在，仅并入 `ParseXML` 与全套单元测试 | |
+| `remote` | 并入 [remote-core](../remote-core) 仓库（被控端远程能力归位） | |
+| `qps` | 不迁入 | 空壳包（无代码） |
+
+迁移中修复的缺陷见各包 README：`frame`（SetData 未返回错误、ReadFrame 短读/吞帧）、
+`ipratelimiter`（包子句大写不规范）、`httpx`（README 笔误）等。
+
 ## 约定
 
 - 通用性准入：被 ≥2 个服务复制使用过的包才进入本仓库；仅单服务使用的留在服务内。
 - 改动流程：在本仓库修复/演进 → 打 tag（如 v0.2.0）→ 各服务 `go get git.zeroonesoft.cn/golib/zogo@v0.2.0`。
 - 本地联动开发：在 `D:\zomaintain\backend\go.work` 中 `use D:/golib/zogo`（go.work 不提交）。
-- go.mod 声明 go 1.24（不高于最低版本消费方），不要随意上调。
+- go.mod 声明 go 版本不高于最低版本消费方，不要随意上调。
 - 依赖版本声明「最低可用」而非 latest（如 gorm 锁消费方在用的版本），避免把消费方依赖图顶出新版本引发不兼容。
-- 每个包自带 README.md（定位/用法/注意事项），改 API 先改文档。
+- 每个包自带 README.md（定位/用法/注意事项），改 API 先改文档；可运行例程统一放 `examples/<包名>/main.go`。
-
-## 私有模块拉取配置（每台开发机/CI 一次）
-
-```
-go env -w GOPRIVATE=git.zeroonesoft.cn/*
-```
-git 凭据需能访问 git.zeroonesoft.cn（Git Credential Manager 存 PAT）。

go.mod

@@ -9,10 +9,16 @@ require (
 	github.com/google/uuid v1.6.0
 	github.com/gorilla/websocket v1.5.3
 	github.com/lestrrat-go/file-rotatelogs v2.4.0+incompatible
+	github.com/lionsoul2014/ip2region/binding/golang v0.0.0-20250508043914-ed57fa5c5274
+	github.com/lxn/win v0.0.0-20210218163916-a377121e959e
 	github.com/mattn/go-colorable v0.1.15
 	github.com/mozillazg/go-pinyin v0.21.0
+	github.com/shirou/gopsutil/v3 v3.24.3
 	github.com/sirupsen/logrus v1.10.2
+	github.com/yusufpapurcu/wmi v1.2.4
+	golang.org/x/sys v0.47.0
 	golang.org/x/text v0.41.0
+	golang.org/x/time v0.5.0
 	gorm.io/gorm v1.25.12
 )
 
@@ -35,26 +41,23 @@ require (
 	github.com/klauspost/cpuid/v2 v2.3.0 // indirect
 	github.com/leodido/go-urn v1.5.0 // indirect
 	github.com/lestrrat-go/strftime v1.2.0 // indirect
-	github.com/lionsoul2014/ip2region/binding/golang v0.0.0-20250508043914-ed57fa5c5274 // indirect
+	github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 // indirect
-	github.com/lxn/win v0.0.0-20210218163916-a377121e959e // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
-	github.com/mitchellh/go-homedir v1.1.0 // indirect
 	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
 	github.com/modern-go/reflect2 v1.0.2 // indirect
-	github.com/mostlygeek/arp v0.0.0-20170424181311-541a2129847a // indirect
 	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
 	github.com/pkg/errors v0.9.1 // indirect
+	github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c // indirect
 	github.com/quic-go/qpack v0.6.0 // indirect
 	github.com/quic-go/quic-go v0.59.0 // indirect
-	github.com/shirou/gopsutil/v3 v3.24.3 // indirect
+	github.com/shoenig/go-m1cpu v0.1.6 // indirect
+	github.com/tklauser/go-sysconf v0.3.12 // indirect
+	github.com/tklauser/numcpus v0.6.1 // indirect
 	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
 	github.com/ugorji/go/codec v1.3.1 // indirect
-	github.com/yusufpapurcu/wmi v1.2.4 // indirect
 	go.mongodb.org/mongo-driver/v2 v2.5.0 // indirect
 	golang.org/x/arch v0.22.0 // indirect
 	golang.org/x/crypto v0.55.0 // indirect
 	golang.org/x/net v0.57.0 // indirect
-	golang.org/x/sys v0.47.0 // indirect
-	golang.org/x/time v0.5.0 // indirect
 	google.golang.org/protobuf v1.36.10 // indirect
 )

go.sum

@@ -61,6 +61,7 @@ github.com/lestrrat-go/strftime v1.2.0 h1:8fAUYOeaJKCuLzNvUWBAo8t6I6hkFfodDTndEz
 github.com/lestrrat-go/strftime v1.2.0/go.mod h1:GtsIA/7ddIGJjEdfadUafEb1sbutvlvpMdPCMglykYo=
 github.com/lionsoul2014/ip2region/binding/golang v0.0.0-20250508043914-ed57fa5c5274 h1:Vslec/nYvO2TdLdhwex8/1x64OZoQNsUzG79WABQaWg=
 github.com/lionsoul2014/ip2region/binding/golang v0.0.0-20250508043914-ed57fa5c5274/go.mod h1:C5LA5UO2ZXJrLaPLYtE1wUJMiyd/nwWaCO5cw/2pSHs=
+github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 h1:6E+4a0GO5zZEnZ81pIr0yLvtUWk2if982qA3F3QD6H4=
 github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0/go.mod h1:zJYVVT2jmtg6P3p1VtQj7WsuWi/y4VnjVBn7F8KPB3I=
 github.com/lxn/win v0.0.0-20210218163916-a377121e959e h1:H+t6A/QJMbhCSEH5rAuRxh+CtW96g0Or0Fxa9IKr4uc=
 github.com/lxn/win v0.0.0-20210218163916-a377121e959e/go.mod h1:KxxjdtRkfNoYDCUP5ryK7XJJNTnpC8atvtmTheChOtk=
@@ -68,15 +69,11 @@ github.com/mattn/go-colorable v0.1.15 h1:+u9SLTRGnXv73cEsnsmoZBom+dMU88B2M0aDcWy
 github.com/mattn/go-colorable v0.1.15/go.mod h1:6LmQG8QLFO4G5z1gPvYEzlUgJ2wF+stgPZH1UqBm1s8=
 github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
 github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
-github.com/mitchellh/go-homedir v1.1.0 h1:lukF9ziXFxDFPkA1vsr5zpc1XuPDn/wFntq5mG+4E0Y=
-github.com/mitchellh/go-homedir v1.1.0/go.mod h1:SfyaCUpYCn1Vlf4IUYiD9fPX4A5wJrkLzIz1N1q0pr0=
 github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
 github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=
 github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
 github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9Gz0M=
 github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
-github.com/mostlygeek/arp v0.0.0-20170424181311-541a2129847a h1:AfneHvfmYgUIcgdUrrDFklLdEzQAvG9AKRTe1x1mx/0=
-github.com/mostlygeek/arp v0.0.0-20170424181311-541a2129847a/go.mod h1:jZxafo9CAqaKFQE4zitrg5QNlA6CXUsjwXPlIppF3tk=
 github.com/mozillazg/go-pinyin v0.21.0 h1:Wo8/NT45z7P3er/9YSLHA3/kjZzbLz5hR7i+jGeIGao=
 github.com/mozillazg/go-pinyin v0.21.0/go.mod h1:iR4EnMMRXkfpFVV5FMi4FNB6wGq9NV6uDWbUuPhP4Yc=
 github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0t5Ec4=
@@ -84,6 +81,7 @@ github.com/pelletier/go-toml/v2 v2.2.4/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8
 github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
 github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c h1:ncq/mPwQF4JjgDlrVEn3C11VoGHZN7m8qihwgMEtzYw=
 github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c/go.mod h1:OmDBASR4679mdNQnz2pUhc2G8CO2JrUAVFDRBDP/hJE=
 github.com/quic-go/qpack v0.6.0 h1:g7W+BMYynC1LbYLSqRt8PBg5Tgwxn214ZZR34VIOjz8=
 github.com/quic-go/qpack v0.6.0/go.mod h1:lUpLKChi8njB4ty2bFLX2x4gzDqXwUpaO1DP9qMDZII=
@@ -91,7 +89,9 @@ github.com/quic-go/quic-go v0.59.0 h1:OLJkp1Mlm/aS7dpKgTc6cnpynnD2Xg7C1pwL6vy/SA
 github.com/quic-go/quic-go v0.59.0/go.mod h1:upnsH4Ju1YkqpLXC305eW3yDZ4NfnNbmQRCMWS58IKU=
 github.com/shirou/gopsutil/v3 v3.24.3 h1:eoUGJSmdfLzJ3mxIhmOAhgKEKgQkeOwKpz1NbhVnuPE=
 github.com/shirou/gopsutil/v3 v3.24.3/go.mod h1:JpND7O217xa72ewWz9zN2eIIkPWsDN/3pl0H8Qt0uwg=
+github.com/shoenig/go-m1cpu v0.1.6 h1:nxdKQNcEB6vzgA2E2bvzKIYRuNj7XNJ4S/aRSwKzFtM=
 github.com/shoenig/go-m1cpu v0.1.6/go.mod h1:1JJMcUBvfNwpq05QDQVAnx3gUHr9IYF7GNg9SUEw2VQ=
+github.com/shoenig/test v0.6.4 h1:kVTaSd7WLz5WZ2IaoM0RSzRsUD+m8wRR+5qvntpn4LU=
 github.com/shoenig/test v0.6.4/go.mod h1:byHiCGXqrVaflBLAMq/srcZIHynQPQgeyvkvXnjqq0k=
 github.com/sirupsen/logrus v1.10.2 h1:G2SED73/qrAu6YwbdxOD6peLkCBI3z7L+ykJFTXJBBo=
 github.com/sirupsen/logrus v1.10.2/go.mod h1:SLEg8TqYulVKKfIGHldVp2K2aYz2DKSVBq4g/H5bR7Q=
@@ -107,7 +107,9 @@ github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8
 github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
 github.com/stretchr/testify v1.12.1 h1:EuwCh5fleGS7H32xRwO3wRGT7DxrDhLAT6FF8MpWDWE=
 github.com/stretchr/testify v1.12.1/go.mod h1:MDEgiDPPsNp5cuIrHPPCyornHKgEVbtFUmoNlxoYthg=
+github.com/tklauser/go-sysconf v0.3.12 h1:0QaGUFOdQaIVdPgfITYzaTegZvdCjmYO52cSFAEVmqU=
 github.com/tklauser/go-sysconf v0.3.12/go.mod h1:Ho14jnntGE1fpdOqQEEaiKRpvIavV0hSfmBq8nJbHYI=
+github.com/tklauser/numcpus v0.6.1 h1:ng9scYS7az0Bk4OZLvrNXNSAO2Pxr1XXRAPyjhIx+Fk=
 github.com/tklauser/numcpus v0.6.1/go.mod h1:1XfjsgE2zo8GVw7POkMbHENHzVg3GzmoZ9fESEdAacY=
 github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI=
 github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=