✨ feat(highgo-sm3): 增加瀚高SM3专用驱动并解耦PostgreSQL连接链路

- 引入 third_party/highgo-pq 作为 HighGo 专用驱动实现
- 调整驱动注册与连接入口，避免覆盖 postgres 驱动
- 保持 PG 数据源行为不变并补充接入文档

docs/HighGo_SM3_Integration_Guide.md

@@ -17,17 +17,17 @@ HighGo（瀚高）数据库需要使用支持 SM3 国密认证的 PostgreSQL 驱
 
 ### 步骤 2：放置驱动源码
 
-1. 在项目根目录创建 vendor 目录（如果不存在）：
+1. 在项目根目录创建目录（如果不存在）：
    ```bash
-   mkdir -p vendor/highgo-pq
+   mkdir -p third_party/highgo-pq
    ```
 
-2. 解压下载的驱动源码到 `vendor/highgo-pq/` 目录
+2. 解压下载的驱动源码到 `third_party/highgo-pq/` 目录
 
 3. 确保目录结构如下：
    ```
    GoNavi/
-   ├── vendor/
+   ├── third_party/
    │   └── highgo-pq/
    │       ├── go.mod
    │       ├── conn.go
@@ -36,10 +36,11 @@ HighGo（瀚高）数据库需要使用支持 SM3 国密认证的 PostgreSQL 驱
 
 ### 步骤 3：修改 go.mod
 
-在 `go.mod` 文件末尾添加 replace 指令：
+在 `go.mod` 中添加独立的 HighGo 驱动依赖与本地替换：
 
 ```go
-replace github.com/lib/pq => ./vendor/highgo-pq
+require github.com/highgo/pq-sm3 v0.0.0
+replace github.com/highgo/pq-sm3 => ./third_party/highgo-pq
 ```
 
 完整示例：
@@ -51,11 +52,24 @@ go 1.24.3
 require (
     // ... 现有依赖
     github.com/lib/pq v1.11.1
+    github.com/highgo/pq-sm3 v0.0.0
     // ... 其他依赖
 )
 
 // 在文件末尾添加
-replace github.com/lib/pq => ./vendor/highgo-pq
+replace github.com/highgo/pq-sm3 => ./third_party/highgo-pq
+```
+
+并将 `third_party/highgo-pq/go.mod` 的 module 修改为：
+
+```go
+module github.com/highgo/pq-sm3
+```
+
+同时在驱动源码中把注册名改为 `highgo`，确保不覆盖 `postgres`：
+
+```go
+sql.Register("highgo", &Driver{})
 ```
 
 ### 步骤 4：更新 HighGo 连接配置（可选）
@@ -100,10 +114,11 @@ q.Set("sslmode", "require")
 
 ### ⚠️ 影响范围
 
-使用 `go.mod replace` 会**全局替换** `github.com/lib/pq` 驱动，这意味着：
+采用独立驱动名后，影响范围如下：
 
-1. **PostgreSQL 连接也会使用瀚高驱动**
-2. **需要验证瀚高驱动对标准 PostgreSQL 的兼容性**
+1. **PostgreSQL 继续使用原生 `github.com/lib/pq`**
+2. **HighGo 使用 `github.com/highgo/pq-sm3`（本地替换到官方源码）**
+3. 两条连接链路互不覆盖，降低兼容性风险
 
 ### 兼容性验证
 
@@ -112,23 +127,24 @@ q.Set("sslmode", "require")
 1. ✅ HighGo 数据库连接（SM3 认证）
 2. ✅ 标准 PostgreSQL 连接（确保仍然可用）
 
-如果标准 PostgreSQL 连接失败，说明瀚高驱动不完全兼容，需要考虑其他方案。
+若 PostgreSQL 或 HighGo 任一连接异常，优先检查驱动注册名与 `go.mod` replace 是否一致。
 
 ### 回滚方案
 
 如果集成后出现问题，可以快速回滚：
 
 1. 删除 `go.mod` 中的 replace 指令
-2. 删除 `vendor/highgo-pq/` 目录
-3. 运行 `go mod tidy`
-4. 重新编译
+2. 删除 `go.mod` 中 `github.com/highgo/pq-sm3` 的 require
+3. 删除 `third_party/highgo-pq/` 目录
+4. 运行 `go mod tidy`
+5. 重新编译
 
 ## 四、瀚高驱动特性
 
 根据官方文档：
 
-- **包路径**：`github.com/lib/pq`（与标准版相同）
-- **驱动名**：`postgres`（与标准版相同）
+- **项目内包路径**：`github.com/highgo/pq-sm3`（映射到本地 `third_party/highgo-pq`）
+- **驱动名**：`highgo`（项目内独立注册，避免覆盖 `postgres`）
 - **SM3 支持**：自动启用国密认证
 - **默认端口**：5866
 - **默认数据库**：`highgo`
@@ -139,11 +155,11 @@ q.Set("sslmode", "require")
 
 ### 问题 1：编译失败
 
-**现象**：`go build` 报错找不到 `github.com/lib/pq`
+**现象**：`go build` 报错找不到 `github.com/highgo/pq-sm3`
 
 **解决**：
-1. 检查 `vendor/highgo-pq/` 目录是否存在
-2. 检查 `go.mod` 中 replace 路径是否正确
+1. 检查 `third_party/highgo-pq/` 目录是否存在
+2. 检查 `go.mod` 中 `github.com/highgo/pq-sm3` 的 require/replace 是否正确
 3. 运行 `go mod download`
 
 ### 问题 2：HighGo 连接失败
@@ -152,25 +168,26 @@ q.Set("sslmode", "require")
 
 **解决**：
 1. 确认瀚高驱动已正确替换（检查 `go.mod`）
-2. 确认 HighGo 服务器支持 SM3 认证
-3. 检查用户名、密码、端口是否正确
+2. 确认项目内驱动注册名为 `highgo`
+3. 确认 HighGo 服务器支持 SM3 认证
+4. 检查用户名、密码、端口是否正确
 
 ### 问题 3：PostgreSQL 连接失败
 
 **现象**：集成后标准 PostgreSQL 无法连接
 
 **解决**：
-1. 这说明瀚高驱动不完全兼容标准 PostgreSQL
-2. 需要考虑条件编译或其他隔离方案
-3. 临时回滚：删除 replace 指令
+1. 检查是否误将 `github.com/lib/pq` 全局 replace 到 HighGo 驱动
+2. 确认 PostgreSQL 仍使用 `sql.Open("postgres", dsn)`
+3. 确认 HighGo 使用 `sql.Open("highgo", dsn)`
 
 ## 六、后续优化建议
 
-如果发现瀚高驱动与标准 PostgreSQL 不兼容，可以考虑：
+如果后续需要增强，可考虑：
 
-1. **条件编译**：使用 Go build tags 分别编译两个版本
-2. **动态驱动注册**：如果瀚高驱动支持自定义驱动名
-3. **联系瀚高技术支持**：咨询官方兼容性方案
+1. 将 HighGo `sslmode` 做成可配置项（前后端联动）
+2. 增加 HighGo/PG 驱动链路健康检查项
+3. 联系瀚高技术支持确认 SM3 + SSL 最佳参数组合
 
 ## 七、参考资料