# kfzgw-info 项目技术文档

## 项目概述

**kfzgw-info** 是一个基于 Go 语言开发的桌面应用程序，主要功能是作为 **"核价软件更新器"**，自动检测、下载和更新 "核价软件"（VerifyPriceApp）及相关 DLL 组件。项目同时包含了与 **孔夫子旧书网（kongfz.com）**、**拼多多（PDD）**、**ERP 系统**等平台的 API 集成模块。

> 项目名称中的 "kfzgw" 推测为 "孔夫子旧书网" 的缩写（KongFuZi - 古玩/旧书网）。

---

## 技术栈

| 技术 | 用途 |
|------|------|
| **Go 1.26** | 主要开发语言 |
| **Gio UI (gioui.org)** | 桌面图形界面框架 |
| **Gin** | HTTP Web 框架 |
| **Elasticsearch** | 搜索引擎客户端 |
| **Redis** | 缓存/消息队列 |
| **MySQL (go-sql-driver)** | 关系型数据库 |
| **SQLite (modernc.org/sqlite)** | 嵌入式数据库 |
| **Excelize** | Excel 文件读写 |
| **chromedp** | Chrome DevTools Protocol（无头浏览器） |
| **goquery** | HTML 解析（类 jQuery） |
| **gorequest** | HTTP 请求库 |
| **gozxing / qrcode / barcode** | 二维码/条码生成与识别 |
| **imaging / gg / freetype** | 图像处理与文字渲染 |
| **fasthttp** | 高性能 HTTP 客户端 |
| **YAML / INI** | 配置文件解析 |

---

## 项目结构

```
kfzgw-info/
│
├── walkingWithBooks.go    # ▶ 主入口文件（GUI + 控制台更新器）
├── main.go                # 旧版入口（已全部注释）
├── main_so.go             # SO/DLL 导出封装（已注释）
├── newWalkingWithBooks.go # 新版入口（已注释，未使用）
├── dyso.go                # 动态加载 SO 的 HTTP 服务（已注释）
├── go.mod / go.sum        # Go 模块依赖
├── version.yaml           # 本地版本配置文件
├── config.ini             # 应用配置文件
├── test.db                # SQLite 测试数据库
│
├── config/                # 配置管理模块
│   ├── config.go          #   - 配置文件读取器（支持 JSON/YAML/INI）
│   ├── configDll.go       #   - DLL 导出函数
│   └── config.json        #   - 配置文件示例
│
├── csv/                   # CSV 文件处理模块
│   ├── csv.go             #   - CSV 读写（带句柄管理、自动关闭）
│   ├── newcsv.go          #   - 新版 CSV 处理
│   ├── csvDll.go          #   - DLL 导出函数
│   └── taskLog.csv        #   - 任务日志 CSV
│
├── erp/                   # ERP 接口转发模块
│   └── erp.go             #   - API 转发（GET/POST/PUT）
│
├── es/                    # Elasticsearch 模块
│   ├── es.go              #   - ES 客户端封装（索引管理、CRUD）
│   ├── esDll.go           #   - DLL 导出函数
│   └── test.go            #   - 测试文件
│
├── excel/                 # Excel 处理模块
│   ├── excel_so.go        #   - Excel 合并/拆分（SO 导出）
│   └── main.go            #   - 示例/测试
│
├── expressDeliveryOrder/  # 快递单号处理模块
│   └── expressDeliveryOrder.go
│
├── gin/                   # Gin Web 框架示例
│   └── gin.go             #   - 简单的 HTTP 服务示例
│
├── goroutine-pool/        # 协程池
│   ├── goroutine_pool.go  #   - 通用协程池实现
│   └── goroutine_pool_test.go
│
├── image/                 # 图片处理模块
│   ├── image.go           #   - 图片裁剪、缩放、水印、格式转换、二维码生成
│   ├── imageDllTest.go    #   - DLL 测试
│   └── imageTest.go       #   - 测试文件
│
├── kongfz/                # 孔夫子旧书网 API 模块
│   ├── kongfz.go          #   - 图书/商品搜索、登录、发货等 API
│   ├── kongfzDll.go       #   - DLL 导出函数
│   └── kongfzLao.go       #   - 旧版实现
│
├── listener/              # 文件监听器
│   ├── listener.go        #   - 文件系统监听
│   └── ceshi.go           #   - 测试
│
├── logger/                # 日志模块
│   ├── logger.go          #   - 分级日志（支持分片、滚动）
│   └── loggerDll.go       #   - DLL 导出函数
│
├── monitor/               # 监控模块
│   └── main.go            #   - 系统监控
│
├── pdd/                   # 拼多多 API 模块
│   ├── pdd.go             #   - 拼多多开放平台 API 封装（签名、商品管理）
│   └── pddDll.go          #   - DLL 导出函数
│
├── pddTask/               # 拼多多任务模块
│   ├── pdd-task.go        #   - 拼多多定时任务
│   └── common/pddDll.go   #   - DLL 调用公共组件
│
├── proxy/                 # 代理管理模块
│   ├── proxy.go           #   - 小象/尾巴代理动态切换
│   ├── proxyLao.go        #   - 旧版代理实现
│   └── proxy_so.go        #   - SO 导出函数
│
├── redis/                 # Redis 客户端模块
│   ├── redis.go           #   - Redis 客户端封装
│   └── redisDll.go        #   - DLL 导出函数
│
├── sqlite/                # SQLite 模块
│   └── sqLite.go          #   - SQLite CRUD 示例
│
├── timer/                 # 定时器模块
│   └── timer.go           #   - 时间轮定时器实现
│
├── xy/                    # XY 模块（用途未知）
│   └── xy.go
│
├── dll/                   # Windows DLL 文件目录
│   ├── csv.dll
│   ├── kongfz.dll
│   ├── logger.dll
│   ├── module-centerBook.dll
│   ├── module-erp.dll
│   ├── module-kongfz.dll
│   ├── module-login.dll
│   ├── module-taskPool.dll
│   ├── module-verifyPrice.dll
│   ├── picTool.dll
│   ├── proxy.dll
│   └── config/config.dll
│
├── so/                    # Linux .so 文件目录
│   ├── erp.so
│   ├── kongfz.so
│   ├── pdd.so
│   └── xy.so
│
└── md/                    # 各模块文档目录
    ├── config.md
    ├── csv.md
    ├── es.md
    ├── image.md
    ├── kongfz.md
    ├── logger.md
    └── ...
```

---

## 模块详解

### 1. 主程序 — [walkingWithBooks.go](file:///d:/source/kfzgw-info/walkingWithBooks.go)

这是当前**实际运行的主入口文件**，提供两种运行模式：

#### GUI 模式（默认）
- 使用 **Gio UI** 框架构建桌面图形界面
- 窗口大小 800×600，最小 600×400
- 显示标题、状态信息、进度条、文件信息、日志区域
- 底部控制按钮（暂停/继续/启动软件）
- 日志区域按类型显示不同颜色（信息=蓝、成功=绿、警告=黄、错误=红、下载=紫）

#### 控制台模式（`--console` 参数）
- 使用 ANSI 彩色终端输出
- 与旧版 main.go 相同的更新逻辑

#### 更新流程
```
初始化 → 检查核价软件版本 → 检查主程序并下载
→ 检查 DLL 组件版本 → 更新所有 DLL
→ 完成 → 自动/手动启动核价软件
```

---

### 2. 各模块功能

| 模块 | 包名 | 功能描述 |
|------|------|----------|
| **config** | `main` | 配置文件读取器，支持 JSON/YAML/INI 三种格式；提供 DLL 导出接口 |
| **csv** | `main` | CSV 文件的高效读写，支持句柄管理、自动关闭、线程安全 |
| **erp** | `main` | ERP 系统的 API 请求转发，支持 GET/POST/PUT |
| **es** | `main` | Elasticsearch 客户端封装，索引管理（创建/删除/查询/统计） |
| **excel** | `main` | Excel 文件的合并、拆分操作 |
| **goroutine-pool** | `main` | 通用协程池，管理和复用 goroutine |
| **image** | `main` | 图片处理：裁剪、缩放、旋转、水印、格式转换、二维码/条码生成与识别 |
| **kongfz** | `main` | 孔夫子旧书网接口：商品搜索、商品详情、登录、图片获取、快递费查询 |
| **listener** | `main` | 文件系统事件监听 |
| **logger** | `main` | 分级日志系统，支持按月/日/时/分/秒分片，按大小/数量滚动 |
| **pdd** | `main` | 拼多多开放平台 API：商品管理、订单处理、签名生成 |
| **proxy** | `main` | 动态代理管理，支持小象代理、尾巴代理等多种代理类型 |
| **redis** | `main` | Redis 客户端封装，支持连接池配置 |
| **sqlite** | `main` | SQLite 嵌入式数据库的 CRUD 操作示例 |
| **timer** | `main` | 基于时间轮的定时器实现，支持任务调度 |

---

### 3. 孔夫子旧书网 API 集成（核心业务）

[kongfz.go](file:///d:/source/kfzgw-info/kongfz/kongfz.go) 封装了大量孔网 API：

| 函数 | 功能 |
|------|------|
| `outLogin()` | 账号密码登录，获取 PHPSESSID Token |
| `outGetUserMsg()` | 获取用户信息（ID、昵称、手机号） |
| `outGetGoodsTplMsg()` | 获取商品发布模板字段 |
| `outGetGoodsListMsgFromSelfShop()` | 查询自己的商品列表（支持分页/价格筛选） |
| `outDelGoodsFromSelfShop()` | 删除自有店铺中的商品 |
| `outAddGoods()` | 新增商品发布 |
| `outGetImageByIsbn()` | 根据 ISBN 获取图书官图/实拍图 |
| `outGetImageFilterShopId()` | 获取图片时过滤指定店铺 |
| `outGetGoodsListMsgByShopId()` | 按店铺 ID 拉取商品列表 |
| `outGetGoodsMsgByDetailUrl()` | 通过详情页 URL 获取商品信息（含快递费） |
| `outGetTopGoodsListMsg()` | 获取销量榜商品列表 |
| `FetchProductInfoWithChromedp()` | 使用无头浏览器获取店铺页动态内容 |
| `FetchBookDetailsShippingFee()` | 获取商品详情页快递费 |

---

### 4. 配置文件

#### [config.ini](file:///d:/source/kfzgw-info/config.ini)

```ini
[app]
max_retry_times = 3          # HTTP 请求最大重试次数
rate_limit_delay = 500ms      # 请求间隔
size = 5                      # 线程数/并发数

[proxy]
servers = http-dynamic.xiaoxiangdaili.com,...  # 代理服务器列表
username = ...                                 # 代理账号
password = ...                                 # 代理密码

[api]
login_url = https://login.kongfz.com/...       # 孔网登录接口
book_search_url = ...                          # 图书搜索接口
product_search_url = ...                       # 商品搜索接口

[server]
port = 9999                                    # HTTP 服务端口

[image]
target_dir = /file/goods_img/                  # 图片保存路径
domain = book.center.image.buzhiyushu.cn       # 图片 CDN 域名

[database]
host = 146.56.227.42:3306                      # MySQL 数据库
name = newadmin
```

#### [version.yaml](file:///d:/source/kfzgw-info/version.yaml)

```yaml
verifyPriceLatestVersion: v1.0   # 本地核价软件版本号
```

---

### 5. 远程版本服务器

更新器从以下远程服务获取版本信息：

| 地址 | 用途 |
|------|------|
| `https://newverifyprice.buzhiyushu.cn/verify_price_version.json` | 核价软件主程序版本信息 |
| `http://36.212.20.113:53300/version.json` | DLL 组件版本信息 |
| `http://36.212.20.113:53300/api/downLoad` | DLL 组件下载接口 |

---

### 6. 编译与构建

项目主入口 [walkingWithBooks.go](file:///d:/source/kfzgw-info/walkingWithBooks.go) 编译为 Windows 可执行文件：

```bash
# 编译 GUI 版本
go build -o kfzgw-info.exe .

# 可通过 --console 参数切换到控制台模式
kfzgw-info.exe --console
```

部分子模块（如 `pdd`、`kongfz`、`csv`、`es`、`image`、`logger` 等）可编译为 **DLL** 供其他程序调用，通过 `//export` 注释导出 C 接口。

---

### 7. 关键依赖

```
gioui.org                     # GUI 框架
github.com/chromedp/chromedp  # 无头浏览器操作
github.com/PuerkitoBio/goquery # HTML 解析
github.com/elastic/go-elasticsearch/v8 # ES 客户端
github.com/gin-gonic/gin      # Web 框架
github.com/redis/go-redis/v9  # Redis 客户端
github.com/xuri/excelize/v2   # Excel 操作
github.com/parnurzeal/gorequest # HTTP 请求
modernc.org/sqlite            # SQLite 数据库
github.com/valyala/fasthttp   # 高性能 HTTP
gopkg.in/yaml.v3              # YAML 解析
gopkg.in/ini.v1               # INI 解析
```

---

## 架构特点

1. **模块化设计**：每个功能模块独立目录，部分可编译为 DLL 动态库
2. **双模式运行**：支持 GUI 桌面模式和命令行控制台模式
3. **远程版本管理**：自动检测远程版本号，增量更新
4. **安全下载机制**：使用临时文件 + 重命名策略，防止文件损坏
5. **代理支持**：内置小象/尾巴代理切换，支持爬虫场景
6. **多平台兼容**：支持 Windows（DLL）和 Linux（SO）的动态库加载

---

## 使用场景

- **核价软件自动更新**：图书定价系统的基础设施
- **孔夫子旧书网数据采集**：商品搜索、图片获取、价格监控
- **拼多多商品管理**：商品上架/下架/订单处理
- **ERP 系统对接**：与外部 ERP 系统的数据接口
- **图片处理服务**：批量图片处理（裁剪、水印、格式转换）