335 lines
13 KiB
Markdown
335 lines
13 KiB
Markdown
# 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 系统的数据接口
|
||
- **图片处理服务**：批量图片处理（裁剪、水印、格式转换）
|