feat: wscclient 并入 wsc(wsc.Client), 信封/心跳约定单一来源; 客户端 API 改名 NewClient/ClientConfig/BindPayload/PayloadHandler; 补各包 README

wsc/README.md

@@ -0,0 +1,44 @@
+# wsc
+
+WebSocket 服务端框架 + 配套客户端，**同一 Message 信封、同一处协议定义**。
+
+信封格式：`{"action":"...","payload":...}`（`Message` 结构体，payload 为 `json.RawMessage`）。
+心跳约定：双方默认 60s 读超时 + 周期 ping（客户端 `PongTimeout` 需 ≥ 服务端 ping 周期 54s，默认值即满足）。
+
+## 服务端
+
+```go
+import "git.zeroonesoft.cn/golib/zogo/wsc"
+
+wsc.HandleWS(r, "/ws/chat", wsc.QuickServer(onConnect, onDisconnect), func(router *wsc.Router) {
+    // 带响应：fn 返回 (resp, error)，resp 序列化后以同名 action+".resp" 语义回包
+    router.On("ping", wsc.Bind(func(ctx *wsc.Context, req *PingReq) (*PingResp, error) {
+        return &PingResp{Pong: true}, nil
+    }))
+    // 无响应 / 客户端约定固定回包类型时
+    router.On("register", wsc.BindNoResp(func(ctx *wsc.Context, req *RegisterReq) error { ... }))
+})
+```
+
+- `Server`：连接池与房间管理（`GetOrCreateRoom`/`ActiveCount`…），`OnConnect/OnDisconnect/OnUpgrade` 钩子
+- `Router`：action 分发，反射校验 handler 签名；`Use` 挂中间件
+- `Context`：单会话上下文，实现 `context.Context`；`WriteMessage`/`WriteError`/`JoinRoom`/`Set`…，`WriteError` 使用 `WsActionError` action
+- gin 耦合仅在 `HandleWS`/`newContext`/`OnUpgrade` 三处入口，核心零 gin
+
+## 客户端
+
+```go
+cli := wsc.NewClient(wsc.DefaultClientConfig("wss://cloud/ws/gateway?token=xxx"))
+cli.On("kick", wsc.BindPayload(func(req *KickReq) { ... }))
+cli.OnConnected = func() { cli.Send("register", &RegisterReq{...}) }
+cli.SetURL("wss://cloud/ws/gateway?token=新token") // 重连时生效
+_ = cli.Connect() // AutoReconnect=true 时阻塞到连上（指数退避，稳定 10s 后重置）
+defer cli.Close()
+```
+
+- 自动重连：指数退避（1s→30s 封顶），连接稳定满 10s 才重置退避，防抖动时"永远 1s 一连"
+- 断线期间 `Send` 返回错误；重连成功重建读写泵，`OnConnected` 重新触发（在此做重注册/重订阅）
+
+## 线程安全
+
+`Client` 与 `Session` 的公开方法均可并发调用；发送走带缓冲通道 + 单写泵。