# 商品定价服务（kfz-goods-pricing）项目交接文档

> 生成时间：2026-05-27
> 项目路径：D:\work\newProject\kfz-goods-pricing

---

## 一、项目概述

**项目名称**：商品定价服务（kfz-goods-pricing）
**技术栈**：Go 1.25 + SQLite + HTTP API + 原生 GUI（无 Vue/Wails，纯 Go）
**输出可执行文件**：kfz-goods-pricing.exe
**核心功能**：接收商品 ISBN 查询请求，通过孔网搜索 API 获取市场定价，计算最优价格并回调通知下游系统

> ⚠️ **重要区别**：本项目与之前生成的 kfz-move-kfz / xy-verify-price / kfz-verify-price 项目完全不同——不是 Wails 桌面应用，而是纯 Go HTTP 服务 + 原生 GUI 窗口，没有前端框架，没有子进程 B 程序。

### 目录结构

`
kfz-goods-pricing/
├── cmd/
│   ├── server/
│   │   ├── main.go         # 程序入口（HTTP服务 + GUI窗口 + 定时器）
│   │   └── gui_windows.go  # GUI 窗口实现
├── internal/
│   ├── config/             # 配置加载（YAML + 全局单例）
│   │   └── config.go
│   ├── database/           # SQLite 数据库初始化
│   │   └── db.go
│   ├── handler/            # HTTP 处理器（4个文件）
│   │   ├── goods_handler.go     # /api/goods/query — 商品查询
│   │   ├── token_handler.go     # /api/token/* — Token 管理（增删改查/启用）
│   │   ├── kfz_handler.go       # /api/kfz/login — 孔网登录
│   │   └── config_handler.go    # /api/config/price/* — 价格配置
│   ├── model/
│   │   └── book.go             # BookInfo 图书信息结构体
│   ├── repository/          # 数据访问层
│   │   ├── token_repository.go   # Token CRUD + 启用状态
│   │   ├── goods_repository.go  # 商品记录 CRUD + 失败计数
│   │   └── config_repository.go  # kfz_config 表（永远只有 ID=1 一条）
│   └── service/
│       └── goods_service.go     # 核心业务逻辑（定时器/限速/爬虫/回调）
├── pkg/                     # 公共库目录（当前为空）
├── config/
│   └── config.yaml          # 程序配置文件
├── data/
│   └── goods_pricing.db     # SQLite 数据库文件
├── go.mod / go.sum
├── kfz-goods-pricing.exe   # 编译后的可执行文件
└── README.md
`

---

## 二、技术栈

| 组件 | 依赖 | 版本 | 说明 |
|------|------|------|------|
| HTTP 服务 | Go 标准库 | 内置 | 
et/http，无框架，裸serveMux路由 |
| 数据库 | modernc.org/sqlite | v1.50.0 | 纯 Go SQLite，无 CGO |
| HTTP 客户端 | github.com/parnurzeal/gorequest | v0.3.0 | 孔网 API 调用 |
| 配置解析 | gopkg.in/yaml.v3 | v3.0.1 | config.yaml 读取 |
| 日志 | log | 内置 | 输出到 GUI 窗口（guiLogWriter） |
| GUI | 原生实现 | — | gui_windows.go 中的 GUI 窗口（GTK/原生混合） |

---

## 三、架构设计

`
┌─────────────────────────────────────────────────────────────────┐
│                     kfz-goods-pricing.exe                        │
│                                                                  │
│  ┌────────────┐     ┌──────────────┐     ┌─────────────────┐    │
│  │ GUI 窗口   │     │ HTTP 服务    │     │ 定时器 (Timer)   │    │
│  │(gui_windows)│    │(net/http)   │     │ 每 N 秒执行一次   │    │
│  └────────────┘     └──────┬───────┘     └────────┬────────┘    │
│                            │                      │              │
│         ┌──────────────────┬┴─────────────────────┘              │
│         ▼                  ▼                                      │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────────┐  │
│  │ TokenHandler │  │GoodsHandler  │  │   GoodsService         │  │
│  │ /api/token/* │  │/api/goods/...│  │  (核心业务逻辑)         │  │
│  └──────┬───────┘  └──────┬───────┘  └─────────┬──────────────┘  │
│         │                │                    │                  │
│  ┌──────▼────────────────▼────────────────────▼──────────────┐  │
│  │                   Repository 层                          │  │
│  │  TokenRepo  │  GoodsRepo  │  ConfigRepo                    │  │
│  └────────────────────────┬───────────────────────────────────┘  │
│                           ▼                                       │
│  ┌─────────────────────────────────────────────────────────────────┐
│  │                     SQLite (goods_pricing.db)                   │
│  │  kfz_token (Token管理) │ kfz_goods (商品记录) │ kfz_config     │
│  └─────────────────────────────────────────────────────────────────┘
│                                                                  │
│  外部调用：                                                    │
│    ① 上游系统 → POST /api/goods/query → 写入 kfz_goods         │
│    ② 定时器 → 查询 kfz_goods（按失败次数/更新时间排序）        │
│       → 爬孔网搜索API → 计算价格 → POST callbackURL             │
│    ③ 回调 URL: http://192.168.101.213:9090/api/product/updatePrice│
└─────────────────────────────────────────────────────────────────┘
`

---

## 四、HTTP API 接口

### 4.1 商品查询（上游系统调用入口）

**POST** /api/goods/query

**请求参数**（form-data 或 x-www-form-urlencoded）：

| 参数                 | 类型 | 必填 | 说明                |
|--------------------|------|--|-------------------|
| isbn               | string |  | 商品 ISBN           |
| book_name          | string |  | 商品 名称             |
| author             | string |  | 商品 作者             |
| publishing         | string |  | 商品 出版社            |
| out_id             | string | | 输出 ID（回调时透传）      |
| quality            | string | | 品相（100=全新，90=九品等） |
| query_index        | int | | 想排第几位（默认取最后一条）    |
| user_id            | string | | 用户 ID（回调时透传）      |
| placeholder_down_price | float | | 占位降价              |
| min_shipping_fee   | float | | 最低运费              |
| min_price          | float | | 最低书价              |

**响应**：
`json
{"code":200,"message":"success","id":123}
`

> 说明：只写入数据库，返回插入记录的 ID。实际核价由定时器异步完成。

### 4.2 Token 管理

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /api/token/add | 批量添加 Token（JSON数组） |
| GET | /api/token/list | 查询所有 Token |
| POST | /api/token/delete | 删除 Token（id 参数） |
| POST | /api/token/update | 修改 Token（id/username/token/is_enable） |
| GET | /api/token/enabled | 获取所有启用的 Token |

**批量添加请求体**：
`json
[{"username":"孔网账号1","token":"PHPSESSID_xxx"},{"username":"孔网账号2","token":"PHPSESSID_yyy"}]
`

### 4.3 孔网登录

**POST** /api/kfz/login

| 参数 | 说明 |
|------|------|
| username | 孔网用户名 |
| password | 孔网密码 |

**响应**：
`json
{"code":200,"message":"success","data":{"userId":123456,"nickname":"xxx","mobile":"138xxxx","token":"PHPSESSID_xxx"}}
`

### 4.4 价格配置

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/config/price/get | 获取完整配置（yaml + DB 覆盖层合并） |
| POST | /api/config/price/set | 修改价格配置（只更新入参字段） |

**配置合并逻辑**（GetConfigPrice）：
`
yaml配置（Port / TimerInterval / APIRateLimit / CallbackURL）
  + DB配置（NewPrice / PlaceholderDownPrice / MinShippingFee / MinPrice / QueryIndex）
= 最终配置（DB 优先覆盖 yaml 的价格字段）
`

---

## 五、定时器核心逻辑（GoodsService.syncGoodsPricing）

`
每 N 秒（默认 5 秒）触发一次：

1. 从 kfz_config 表读取价格参数
2. 从 kfz_goods 表取一条记录（按 fail_count ASC, updated_at DESC）
   └→ 优先处理失败次数少的记录
3. 调用 outGetAllGoods(isbn, quality, queryIndex) 爬孔网搜索 API
   ├→ 使用轮询方式从 kfz_token 表选一个启用 Token
   └→ URL: https://search.kongfz.com/pc-gw/search-web/client/pc/product/keyword/list
4. 计算最终价格：
   finalPrice = totalPrice - placeholderDownPrice - minShippingFee
   if (finalPrice < minPrice) → finalPrice = minPrice
5. 更新 kfz_goods 表（price / shipping_fee / final_price / updated_at）
6. 调用 sendCallback(outID, userID, finalPrice, minShippingFee)
   └→ POST 
      product_id=xxx&user_id=xxx&sale_price=xxx&cost=xxx
      （sale_price 和 cost 均为整数，单位：分 = 原价 × 100）
7. 失败处理：MarkFailed → fail_count++，下次优先重试
`

---

## 六、数据库设计

### 6.1 kfz_token 表

`sql
CREATE TABLE kfz_token (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  username TEXT NOT NULL,
  token TEXT NOT NULL,
  is_enable INTEGER DEFAULT 1
);
`

**用途**：存储多个孔网账号 Token，支持轮询切换，防止单个 Token 请求过快被限

### 6.2 kfz_goods 表

`sql
CREATE TABLE kfz_goods (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  isbn TEXT NOT NULL,
  out_id TEXT,
  quality TEXT,
  user_id TEXT,
  query_index INTEGER DEFAULT 1,
  placeholder_down_price REAL DEFAULT 0.01,
  min_shipping_fee REAL DEFAULT 5.0,
  min_price REAL DEFAULT 1.0,
  price REAL DEFAULT 0,
  shipping_fee REAL DEFAULT 0,
  final_price REAL DEFAULT 0,
  fail_count INTEGER DEFAULT 0,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
`

**用途**：上游调用 QueryGoods 时写入记录，定时器按 fail_count ASC 排序依次处理

### 6.3 kfz_config 表

`sql
CREATE TABLE kfz_config (
  id INTEGER PRIMARY KEY CHECK (id = 1),
  new_price REAL DEFAULT 0,
  placeholder_down_price REAL DEFAULT 0.01,
  min_shipping_fee REAL DEFAULT 5.0,
  min_price REAL DEFAULT 1.0,
  query_index INTEGER DEFAULT 1
);
`

**用途**：始终只有一条记录（ID=1），与 config.yaml 共同构成配置体系。yaml 负责基础配置（Port/Timer/APIRateLimit/CallbackURL），DB 负责价格参数

---

## 七、关键设计

### Token 轮询机制

`
tokens = GetEnabledTokens()  // 从 DB 取出所有启用 Token
currentTokenIndex = 0        // 原子操作的轮询索引

每次爬孔网 API 时：
  token = tokens[currentTokenIndex % len(tokens)]
  currentTokenIndex++
`

> 目的：多个孔网账号 Token 轮询使用，防止单个账号请求过快被限

### 价格计算公式

`
totalPrice = price + shippingFee
finalPrice = totalPrice - placeholderDownPrice - minShippingFee
if finalPrice < minPrice → finalPrice = minPrice
`

最终回调中的 sale_price 和 cost 均为整数（单位：分 = float × 100）

### 配置双层机制

| 来源 | 字段 | 说明 |
|------|------|------|
| config/config.yaml | Port, TimerInterval, APIRateLimit, CallbackURL | 基础运行时配置 |
| kfz_config DB | NewPrice, PlaceholderDownPrice, MinShippingFee, MinPrice, QueryIndex | 价格参数 |

yaml 不可动态修改，DB 配置可通过 API 动态修改（实时生效）。

---

## 八、第三方接口

### 孔网登录

| 步骤 | URL | 方法 |
|------|-----|------|
| 登录 | https://login.kongfz.com/Pc/Login/account | POST (form-data) |
| 获取用户信息 | https://user.kongfz.com/User/Index/getUserInfo/ | GET (Cookie: PHPSESSID=xxx) |

### 孔网商品搜索

| 用途 | URL |
|------|-----|
| 搜索商品 | https://search.kongfz.com/pc-gw/search-web/client/pc/product/keyword/list?dataType=0&page=1&sortType=7&quaSelect=2&keyword=ISBN&quality=品相~ |

### 回调

| 回调 URL | 参数 |
|---------|------|
| http://192.168.101.213:9090/api/product/updatePrice | product_id, user_id, sale_price（分）, cost（分） |

---

## 九、运行与构建

`ash
# 运行（开发）
go run cmd/server/main.go

# 编译
go build -o kfz-goods-pricing.exe ./cmd/server
`

**启动后**：
1. 加载 config/config.yaml
2. 初始化 data/goods_pricing.db（SQLite，自动建表）
3. 启动 HTTP 服务（默认端口 8080）
4. 启动 GUI 窗口（阻塞主线程）
5. 启动定时器（5秒间隔，开始首次同步）

**默认配置**（config/config.yaml）：
`yaml
port: "8080"
timer_interval: 5          # 每5秒执行一次定时任务
api_rate_limit: 2          # API 请求间隔2秒
callback_url: "http://192.168.101.213:9090/api/product/updatePrice"
`

---

## 十、交接注意事项

| 文件/目录 | 说明 | 注意点 |
|-----------|------|--------|
| config/config.yaml | 基础配置 | Port/TimerInterval/APIRateLimit/CallbackURL |
| data/goods_pricing.db | SQLite 数据库 | 运行时自动创建，无需手动初始化 |
| internal/handler/kfz_handler.go | 孔网登录逻辑 | HTTP 直接调用孔网官网，无需 kfz.dll（与之前的 Wails 项目不同） |
| internal/service/goods_service.go | 定时器核心 | 异步处理，依赖 Token 池 |
| kfz-goods-pricing.exe | 可执行文件 | 需与 config/、data/ 目录同目录运行 |

### 快速排查

- **上游调用无响应**：检查 HTTP 服务是否正常（默认端口 8080），检查防火墙
- **定时器无动作**：检查 kfz_goods 是否有数据；检查 Token 是否为空或已过期
- **核价结果全为默认值**：孔网搜索 API 无返回，kfzConfig.NewPrice 作为兜底
- **回调失败**：检查 callbackURL 是否可达（192.168.101.213:9090）
- **Token 失效**：上游系统调用 /api/kfz/login 获取新 Token，或手动 /api/token/add 添加

### 与 Wails 桌面项目的核心区别

| 对比项 | 本项目（kfz-goods-pricing） | Wails 项目们 |
|--------|----------------------------|-------------|
| 类型 | **纯 Go HTTP 服务 + GUI 窗口** | Wails 桌面应用 |
| 前端 | **无**（无 Vue/HTML） | Vue 3 + Element Plus |
| 子进程 | **无** | 有（verify-price-b） |
| Token 来源 | HTTP 直接登录孔网 | kfz.dll（Windows DLL） |
| 数据库 | SQLite（本地文件） | SQLite（同） |
| 部署方式 | 后台 HTTP 服务（可远程调用） | 桌面 exe（本地运行） |