# 图书进销存系统 — 技术文档

> **项目名称**：Cards（图书进销存管理后台）  
> **版本**：1.0.0  
> **最后更新**：2026-06-15  
> **项目路径**：`D:\project\psi_web`

---

## 目录

1. [项目概述](#1-项目概述)
2. [技术栈](#2-技术栈)
3. [项目结构](#3-项目结构)
4. [构建与部署](#4-构建与部署)
5. [路由与权限](#5-路由与权限)
6. [API 架构](#6-api-架构)
7. [API 接口详表](#7-api-接口详表)
8. [状态管理](#8-状态管理)
9. [工具函数](#9-工具函数)
10. [外部服务集成](#10-外部服务集成)
11. [核心业务流程](#11-核心业务流程)
12. [打印服务](#12-打印服务)
13. [数据模型](#13-数据模型)
14. [已知问题与维护](#14-已知问题与维护)

---

## 1. 项目概述

本项目是一个面向图书行业的**进销存管理后台系统**，覆盖图书采购入库、库存管理、商品发布、销售出库、发货打单、盘库盘点等全链路业务流程。系统支持多角色（管理员/代理）权限控制，并集成了核价器、快递打印、OCR 识别、孔夫子旧书网登录等外部服务。

### 核心业务范围

| 模块 | 说明 |
|------|------|
| **波次管理** | 相机扫码 → 条码识别 → 书籍信息编辑 → 波次创建/释放 |
| **订单管理** | 采购订单 → 销售订单 → 出库单 → 发货单，全链路可追溯 |
| **库存管理** | 库存查询（商品维度/仓库维度）、变动记录、盘库盘点 |
| **商品管理** | 商品 CRUD、实拍图片管理、多店铺发布/重试、Excel 导入 |
| **店铺管理** | 多客户店铺（拼多多、孔夫子、闲鱼等）管理、授权状态 |
| **分账管理** | 分账规则配置、扣款日志查询与导出 |
| **快递管理** | 快递配置、物流模板、面单打印（拼多多/通用）、单号回填 |
| **小车管理** | 拣货小车 CRUD、小车-店铺关联 |
| **系统管理** | 代理账号、员工类型、核价器配置、物流模板、打印机管理、PDA 管理 |

---

## 2. 技术栈

### 2.1 前端框架与依赖

| 依赖 | 版本 | 用途 |
|------|------|------|
| `vue` | ^3.2.8 | 前端框架（Composition API + `<script setup>`） |
| `vue-router` | ^4.1.6 | 前端路由（History 模式） |
| `pinia` | ^2.1.7 | 状态管理 |
| `element-plus` | ^2.13.7 | UI 组件库（中文 locale，small 尺寸，zIndex 3000） |
| `@element-plus/icons-vue` | ^2.1.0 | 图标库（全局注册所有图标） |
| `axios` | ^1.7.9 | HTTP 客户端 |
| `crypto-js` | ^4.2.0 | 签名算法（MD5/SHA256） |
| `json-bigint` | ^1.0.0 | 大整数精度处理（替换默认 JSON.parse） |
| `@zxing/library` | ^0.21.3 | 条形码/二维码扫描 |
| `jsbarcode` | ^3.12.3 | 条码生成 |
| `qrcode` | ^1.5.4 | QR 码生成 |
| `@vue/compiler-sfc` | ^3.2.8 | SFC 编译器 |
| `sass-embedded` | ^1.99.0 | CSS 预处理器（嵌入版） |

### 2.2 工程化工具

| 工具 | 版本 | 用途 |
|------|------|------|
| `vite` | ^2.5.2 | 构建工具与开发服务器 |
| `@vitejs/plugin-vue` | ^1.6.0 | Vite Vue 插件 |
| `typescript` | ^5.5.4 | 类型检查（项目以 JS 为主，仅部分 .ts 文件） |
| `sass` | ^1.99.0 | CSS 预处理器（dart-sass） |

### 2.3 环境变量（`.env`）

| 变量 | 值 | 说明 |
|------|-----|------|
| `VITE_APP_API_KEY` | `psi` | API 签名密钥 |
| `VITE_APP_CLIENT_ID` | `psi` | 客户端 ID |
| `VITE_APP_API_SECRET` | `psi_api_sign_secret` | 签名密钥 |

### 2.4 脚本命令

| 命令 | 说明 |
|------|------|
| `npm run dev` | 启动开发服务器，端口 5174 |
| `npm run build` | 生产构建，输出到 `dist/` |
| `npm run serve` | 预览生产构建（`vite preview`） |

---

## 3. 项目结构

```
src/
├── api/                              # API 层：所有后端接口调用集中于此（31 个文件）
│   ├── barcode.js                    # 条码生成
│   ├── book.js                       # 书籍信息查询/同步
│   ├── car.js                        # 小车管理（CRUD + 小车-店铺关联）
│   ├── config.js                     # 核价器配置（直连外部 IP:Port，非 request 封装）
│   ├── courierConfig.js              # 快递配置（createConfig 等，仅部分实现）
│   ├── dashboard.js                  # 仪表盘统计
│   ├── district.js                   # 行政区划（省/市/区）及运费模板
│   ├── employee.js                   # 员工/代理管理
│   ├── employeeType.js               # 员工类型管理
│   ├── goodsInfo.js                  # 提交异常书目（product_log/save）
│   ├── submIllegalBook.js            # 异常书目审核/审批（product_log/audit）
│   ├── reviewIllegalBook.js          # 异常书目查询/删除（product_log/list + delete）
│   ├── inventory.js                  # 库存记录（汇总/明细/变动日志）
│   ├── location.js                   # 库位管理（CRUD、批量生成、Excel 导入）
│   ├── login.js                      # 登录（管理员/代理）
│   ├── logistics.js                  # 物流模板 CRUD
│   ├── outbound.js                   # 出库管理（CRUD、审核、导出、改库位）
│   ├── print.js                      # 打印服务（重导出 Lodop 方法）
│   ├── product.js                    # 商品管理（CRUD、图片、OCR、Excel 导入）
│   ├── purchase-order.js             # 采购订单（CRUD、带波次创建、波次释放）
│   ├── releaseRecord.js              # 发布记录（全 Mock 数据）
│   ├── sales-order.js                # 销售订单（CRUD、确认、取消、退货）
│   ├── shop.js                       # 店铺管理（内部 API + 外部 API 双路径）
│   ├── shipping-order.js             # 发货单（内部 CRUD + 外部快递接口）
│   ├── split.js                      # 分账配置（旧版，不完整，部分 stub）
│   ├── splitAccount.js               # 分账配置（完整版，JSON 请求体）
│   ├── splitDeductionLog.js          # 分账扣款日志（查询/导出）
│   ├── stock-check.js                # 盘库管理（CRUD、盘点、调整、退货）
│   ├── supplier.js                   # 供应商 CRUD
│   ├── warehouse.js                  # 仓库 CRUD
│   └── wave-task.js                  # 波次任务（任务列表、波次管理、波次释放）
│
├── components/                       # 公共组件（24 个文件）
│   ├── AdminLayout.vue               # 主布局（侧边栏 + 顶部栏 + 内容区）
│   ├── goodsPop/index.vue            # ISBN 悬停浮窗（书品信息预览）
│   ├── locationSelect/index.vue      # 库位选择器组件
│   ├── dialog/submIllegalBook/       # 异常书目提交弹窗
│   ├── inventory/byGoods/            # 库存视图-按商品分组
│   ├── inventory/byLocation/         # 库存视图-按库位分组
│   ├── product/byGoods/              # 商品视图-按商品分组
│   ├── product/byLocation/           # 商品视图-按库位分组
│   ├── wareHouse/warehouseList.vue   # 仓库列表组件
│   ├── wareHouse/locationManager.vue # 库位管理组件（有独立路由）
│   ├── wareHouse/regionData.js       # 行政区划常量数据
│   └── wave/                         # 波次相关子组件
│       ├── camera.vue                # 相机扫码
│       ├── car.vue                   # 小车选择（含打印调试按钮）
│       ├── bookInfo.vue              # 书籍信息展示
│       ├── goodsInfo.vue             # 商品信息展示
│       ├── goosList.vue              # 商品列表（注意文件名拼写 "goos"）
│       ├── imageCut.vue              # 图片裁剪工具
│       ├── ocrDialog.vue             # OCR 识别对话框
│       ├── ocrResultDialog.vue       # OCR 结果展示对话框
│       └── suitBookDialog.vue        # 套装书对话框（含首次打印调试）
│
├── views/                            # 页面级组件（33 个页面目录）
│   ├── login/Login.vue               # 登录页
│   ├── admin/                        # 管理员页面
│   │   ├── Dashboard.vue             # 仪表盘
│   │   ├── EmployeeList.vue          # 代理管理
│   │   ├── EmployeeAdd.vue           # 添加代理
│   │   └── employeeType.vue          # 员工类型管理
│   ├── wave/Wave.vue                 # 波次管理主页面
│   ├── waveTask/WaveTask.vue         # 波次任务列表
│   ├── warehouse/                    # 仓库管理
│   │   ├── wareHouse.vue             # 仓库列表
│   │   └── template.vue              # 运费模板管理
│   ├── supplier/Supplier.vue         # 供应商列表
│   ├── product/Product.vue           # 商品列表
│   ├── purchase-order/               # 采购订单
│   │   └── PurchaseOrder.vue
│   ├── sales-order/                  # 销售订单
│   │   ├── SalesOrder.vue            # 销售订单
│   │   └── salesInfoList.vue         # 销售单详情列表
│   ├── shipping-order/               # 发货单
│   │   ├── ShippingOrder.vue         # 发货单管理
│   │   ├── orderList.vue             # 发货单详情列表
│   │   └── unshippedOrderList.vue    # 未发货订单列表
│   ├── outbound/Outbound.vue         # 出库管理
│   ├── inventory/Inventory.vue       # 库存记录
│   ├── stock-check/                  # 盘库管理
│   │   └── StockCheck.vue
│   ├── shop/Shop.vue                 # 店铺管理
│   ├── car/Car.vue                   # 小车管理
│   ├── location/Location.vue         # 库位列表
│   ├── config/config.vue             # 核价器配置
│   ├── logistics/index.vue           # 物流模板
│   ├── releaseRecord/                # 发布记录
│   ├── reviewIllegalBook/            # 异常书目审核
│   ├── printer-manager/              # 打印机管理
│   ├── shop-settings/                # 店铺设置
│   ├── sorting-settings/             # 分拣设置
│   ├── scanner/Scanner.vue           # 扫码页
│   ├── pdaManage/                    # PDA 管理
│   ├── courier/config.vue            # 快递配置
│   └── split/                        # 分账管理
│       ├── config/splitConfig.vue    # 分账配置
│       └── log/splitLog.vue          # 分账扣款日志
│
├── router/index.js                   # 路由配置（History 模式 + 完整路由守卫）
├── store/                            # 状态管理
│   ├── index.js                      # 旧版 store（reactive 方式，逐步废弃）
│   └── user.js                       # Pinia 用户 store
├── utils/                            # 工具函数
│   ├── request.js                    # Axios 封装（拦截器、签名、Mock 系统）
│   ├── auth.js                       # Token/UserInfo 的 localStorage 读写
│   ├── sign.js                       # 签名工具（MD5/SHA256，参数排序展平）
│   ├── mock.js                       # Mock 数据（商品、卡密、代理、订单）
│   ├── daYin/print.ts                # Lodop/Clodop 打印服务封装（TypeScript）
│   ├── daYinPdd/index.ts             # 拼多多打印服务
│   ├── pddUpload.ts                  # 拼多多图片上传
│   ├── clipboard.js                  # 剪贴板工具
│   └── ServiceManager.js             # 服务管理器
├── App.vue                           # 根组件（router-view + SEO footer）
└── main.js                           # 入口文件（注册 Element Plus / Pinia / Router / Icons）
```

---

## 4. 构建与部署

### 4.1 开发服务器

```bash
npm run dev
# → http://localhost:5174 （host: 0.0.0.0）
```

### 4.2 生产构建

```bash
npm run build
# → 输出到 dist/
```

### 4.3 Vite 配置要点（`vite.config.js`）

| 配置项 | 值 | 说明 |
|--------|-----|------|
| **插件** | `@vitejs/plugin-vue` | Vue SFC 编译 |
| **代理** | `/api` → `https://psi.api.buzhiyushu.cn` | 主业务 API（changeOrigin） |
| **代理** | `/api/print` → `https://print.buzhiyushu.cn` | 打印服务（changeOrigin） |
| **别名** | `@` → `./src` | 模块路径别名 |
| **端口** | `5174` | 开发服务器端口 |
| **host** | `0.0.0.0` | 监听所有网络接口 |
| **historyApiFallback** | `true` | History 模式 fallback |
| **自定义中间件** | `/kongfz-login` | 孔夫子登录代理（避免跨域） |
| **SCSS** | `api: 'modern-compiler'` | SCSS 编译模式 |
| **Define** | `__VUE_PROD_HYDRATION_MISMATCH_DETAILS__: 'false'` | 关闭水合警告 |

### 4.4 孔夫子登录代理中间件

Vite 开发服务器注册了 `/kongfz-login` 自定义中间件：
- **方法**：仅 POST
- **流程**：接收 `loginName` + `loginPass` → POST 到 `login.kongfz.com/Pc/Login/account` → 跟随重定向 → 提取 `PHPSESSID` → GET `user.kongfz.com/User/Index/getUserInfo/` 获取昵称
- **返回**：`{ code: 200, data: { token, username, nickname } }`
- **错误处理**：HTTP 405（非 POST）→ `{ code: 405 }`；400（空参数）→ `{ code: 400 }`；500（登录失败）→ `{ code: 500, message }`
- **超时**：15 秒
- **重定向限制**：最多跟随 5 次重定向
- **User-Agent**：`Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36`

### 4.5 生产环境 API 地址

- **基础 URL**：`https://psi.api.buzhiyushu.cn/api`
- 通过环境变量 `VITE_API_BASE` 可覆盖

---

## 5. 路由与权限

### 5.1 路由模式

`createWebHistory()` — History 模式，URL 格式为 `http://host:port/path`

> ⚠️ 注意：本项目的 router 使用 History 模式，而非 Hash 模式。不支持 IE 等旧浏览器。

### 5.2 路由守卫逻辑

`router.beforeEach` 守卫依次执行：

1. **URL 参数登录（嵌入模式）**：检测 `window.location.search` 中的 `token` 参数
   - 自动写入 `localStorage.admin_token`
   - 设置 `localStorage.embed_mode = 'true'`（隐藏导航栏）
   - 解析 JWT Payload（base64）提取 `id`、`username`、`role`、`about_id`
   - 用于跨系统嵌入（如从其他系统以 iframe 嵌入本系统）
2. **标题设置**：`document.title = "{meta.title} - 进销存系统"`
3. **登录页处理**：已登录用户自动跳转 `/dashboard`
4. **仪表盘鉴权**：无 `adminUserInfo` 跳转 `/login`
5. **黑名单模式鉴权**：
   - 所有非公开页面（未标记 `meta.isPublic`）均需登录
   - `requiresAdmin: true` 且 `role !== 255` 跳转 `/dashboard`
   - 未登录跳转 `/login`（携带 `redirect` 参数可回跳）

### 5.3 完整路由表

| 路径 | Name | 组件 | 标题 | 权限 | 隐藏 |
|------|------|------|------|------|------|
| `/login` | `Login` | `login.vue` | 登录 | 公开 | — |
| `/` | — | `AdminLayout.vue`（布局） | — | — | 重定向到 `/dashboard` |
| `/dashboard` | `Dashboard` | `dashboard.vue` | 仪表盘 | 需认证 | — |
| `/admin/employees` | `EmployeeList` | `employeeList.vue` | 代理管理 | 管理员 | — |
| `/admin/employees/add` | `EmployeeAdd` | `employeeAdd.vue` | 添加代理 | 管理员 | — |
| `/admin/employee-type` | `EmployeeType` | `employeeType.vue` | 员工类型管理 | 管理员 | — |
| `/wave` | `wave` | `wave.vue` | 波次管理 | 需认证 | — |
| `/wave-task` | `wave-task` | `waveTask.vue` | 波次任务 | 需认证 | — |
| `/warehouse` | `warehouse` | `wareHouse.vue` | 仓库列表 | 需认证 | — |
| `/warehouse/template` | `WarehouseTemplate` | `template.vue` | 运费模板管理 | 需认证 | — |
| `/location-manager` | `location-manager` | `locationManager.vue` | 库位管理 | 需认证 | ✅ 隐藏 |
| `/location` | `location` | `location.vue` | 库位列表 | 需认证 | — |
| `/supplier` | `supplier` | `supplier.vue` | 供应商管理 | 需认证 | — |
| `/product` | `product` | `product.vue` | 商品管理 | 需认证 | — |
| `/purchase-order` | `purchase-order` | `purchaseOrder.vue` | 采购订单 | 需认证 | — |
| `/sales-order` | `sales-order` | `salesOrder.vue` | 销售订单 | 需认证 | — |
| `/sales-order-info-list` | `SalesOrderInfoList` | `salesInfoList.vue` | 销售单详情列表 | 需认证 | — |
| `/outbound` | `outbound` | `outbound.vue` | 出库管理 | 需认证 | — |
| `/shipping-order` | `shipping-order` | `shippingOrder.vue` | 发货单 | 需认证 | — |
| `/shipping-order-list` | `ShippingOrderList` | `orderList.vue` | 发货单详情列表 | 需认证 | — |
| `/inventory` | `inventory` | `inventory.vue` | 库存记录 | 需认证 | — |
| `/stock-check` | `stock-check` | `stockCheck.vue` | 盘库管理 | 需认证 | — |
| `/release-record` | `release-record` | `releaseRecord.vue` | 发布记录 | 需认证 | — |
| `/shop` | `shop` | `shop.vue` | 店铺管理 | 需认证 | — |
| `/shop-settings` | `shop-settings` | `shopSettings.vue` | 店铺设置 | 需认证 | — |
| `/sorting-settings` | `sorting-settings` | `sortingSettings.vue` | 分拣设置 | 需认证 | — |
| `/car` | `car` | `car.vue` | 小车管理 | 需认证 | — |
| `/printer-manager` | `printer-manager` | `printerManager.vue` | 打印机管理 | 需认证 | — |
| `/review-illegal-book` | `reviewIllegalBook` | `reviewIllegalBook.vue` | 异常书目审核 | 管理员 | — |
| `/testUrl` | `testUrl` | `config.vue` | 核价器配置 | 管理员 | — |
| `/split-config` | `split-config` | `splitConfig.vue` | 分账配置 | 需认证 | — |
| `/split-log` | `split-log` | `splitLog.vue` | 分账扣款日志 | 需认证 | — |
| `/courier-config` | `courier-config` | `config.vue`（courier） | 快递配置 | 需认证 | — |
| `/pdaManage` | `pdaManage` | `pdaManage.vue` | PDA 管理 | 需认证 | ✅ 隐藏 |

> **隐藏路由**：`hidden: true` 的路由不会在侧边栏菜单中显示，但可通过 URL 直接访问。

### 5.4 角色权限

| role 值 | 身份 | 说明 |
|---------|------|------|
| `255` | 管理员 | 全部功能可用，包括代理管理、员工类型、核价器配置、异常审核 |
| `128` | 代理 | 仪表盘、波次、仓库、商品等基础功能 |

---

## 6. API 架构

### 6.1 网络拓扑

```
浏览器 ──→ Vite Dev Server (:5174)
              ├── /api/* ──→ Proxy ──→ https://psi.api.buzhiyushu.cn （主业务 API）
              ├── /api/print/* ──→ Proxy ──→ https://print.buzhiyushu.cn （打印服务）
              ├── /kongfz-login  ──→ Node.js 中间件 ──→ login.kongfz.com （孔夫子登录）
              └── axios 直连 ──→ 核价器 http://{ip}:{port} （用户配置）
                         ──→ https://api.buzhiyushu.cn （店铺列表/快递回填）
                         ──→ https://print.buzhiyushu.cn （快递面单打印）
                         ──→ https://new.taskpool.buzhiyushu.cn:3500 （店铺详情）
```

### 6.2 请求封装（`src/utils/request.js`）

**创建 Axios 实例：**
- 开发环境 baseURL：`/api`（通过 Vite 代理）
- 生产环境 baseURL：`https://psi.api.buzhiyushu.cn/api`（可通过 `VITE_API_BASE` 覆盖）
- 超时：10 秒
- 使用 `json-bigint` 替换默认 `JSON.parse`（`transformResponse`），防止后端 19 位大整数精度丢失

**请求拦截器流程：**

```
请求发起
  │
  ├── 注入 Bearer Token（从 localStorage.admin_token 读取）
  │
  ├── 签名处理
  │   ├── 检查 X-Need-Sign 头（'false' 则跳过签名）
  │   ├── GET 请求 → 对 params 签名
  │   ├── POST/PUT/DELETE 请求 → 对 body 签名（先 FormData→Object 再签名）
  │   └── 签名后自动注入 app_key、client_id、timestamp、sign_method
  │
  └── POST/PUT/DELETE 请求 → 自动对象转 FormData（objectToFormData）
      └── 删除 Content-Type 头（让浏览器自动设置为 multipart/form-data）
```

**响应拦截器流程：**

```
响应返回
  │
  ├── Mock 模式（USE_MOCK=true）→ 匹配 mockApiMap 返回模拟数据
  │
  ├── HTTP 204 → "请求无响应数据" 错误提示
  │
  ├── code=200 → 返回 response.data
  │
  ├── code≠200 → 统一 ElMessage 错误提示（code 204 特殊处理）
  │
  ├── HTTP 401 → 清除对应 token（区分 admin/user 端）→ 跳转登录页
  ├── HTTP 400 → 显示后端返回的错误消息
  ├── HTTP 403 → "没有权限访问"
  ├── HTTP 404 → "请求的资源不存在"
  ├── HTTP 500 → "服务器错误"
  │
  └── 网络错误 → "网络错误，请检查网络连接"
```

**objectToFormData 递归转换：**
- 支持嵌套对象 → `parentKey[key]`
- 支持数组 → `parentKey[0]`, `parentKey[1]`
- 支持 File 类型直接附加
- 跳过 `null`/`undefined` 值

**Mock 系统：**
- `USE_MOCK = false`（默认关闭）
- 支持的路由：`/products`、`/admin/cards/*`、`/admin/employee/*`、`/orders`、`/access/*`、`/cards/buy/*`
- 启用后 GET 请求自动匹配 `mockApiMap`，支持路径参数解析

### 6.3 签名机制（`src/utils/sign.js`）

`SignUtil` 类（单例导出），配置来自环境变量：

```javascript
{
  appKey: 'psi',
  clientId: 'psi',
  appSecret: 'psi_api_sign_secret'
}
```

**核心方法：**

| 方法 | 说明 |
|------|------|
| `generateSign(params)` | 完整签名流程：过滤空值 → 注入系统参数 → 展平 → 排序 → 计算 MD5 → 返回含 sign 的 params 对象 |
| `generateSignedUrl(baseUrl, params)` | 生成带签名参数的完整 URL |
| `calculateSign(params)` | 核心哈希：拼接 `appSecret + key=value&... + appSecret`，MD5 签名后转为大写 |
| `buildParamEntries(params, prefix)` | 递归展平嵌套对象/数组为 `key=value` 条目（使用 `[key]` 下标表示法） |
| `sortKeys(a, b)` | 智能键排序：纯数字段数值比较，混合段分段字母+数字排序 |

**系统自动注入参数：**

| 参数 | 值 |
|------|-----|
| `app_key` | `VITE_APP_API_KEY（psi）` |
| `client_id` | `VITE_APP_CLIENT_ID（psi）` |
| `timestamp` | 当前时间戳（毫秒） |
| `sign_method` | `md5` |

**跳过签名：** 在请求头中设置 `X-Need-Sign: false`（如 OCR 图片上传、部分外部服务调用）

### 6.4 列表接口标准化

约 15 个 API 模块实现了 `normalizeListResponse()` 工具函数，将后端可能返回的各种列表格式统一为 `{ list: Array, total: number }`：

```javascript
const normalizeListResponse = (payload) => {
  const data = payload?.data
  if (!data) return { list: [], total: 0 }
  if (Array.isArray(data)) return { list: data, total: data.length }
  return {
    list: Array.isArray(data.list) ? data.list : [],
    total: typeof data.total === 'number' ? data.total : (data.list?.length || 0)
  }
}
```

> ⚠️ 注意：此函数在每个 API 文件中独立定义，存在代码重复，建议未来抽离为公共工具。

### 6.5 大整数精度

使用 `json-bigint` 库替换 `JSON.parse`，在后端返回 JSON 中的 19 位大整数（如订单号、店铺 ID）时保持精度。注意：
- `json-bigint` 返回的是 `BigNumber` 对象，使用 `.toString()` 获取字符串值
- 部分比较操作可能需要特殊处理

---

## 7. API 接口详表

### 7.1 登录与认证

#### `src/api/login.js`

| 函数 | 方法 | 端点 | 参数 | 说明 |
|------|------|------|------|------|
| `login(type, formData)` | POST | `/login/:role` | `type` = `'admin'`（→255）/ `'employee'`（→128）；`formData` = `{ username, password }` | 管理员/代理登录，自动注入 `type: 1` |

#### `src/utils/auth.js`

| 函数 | 说明 |
|------|------|
| `logout()` | 清除 `admin_token` 和 `admin_userInfo` |
| `setAdminToken(token)` / `getAdminToken()` / `removeAdminToken()` | 管理端 Token 存取 |
| `setAdminUserInfo(userInfo)` / `getAdminUserInfo()` / `removeAdminUserInfo()` | 管理端用户信息存取 |

#### `src/utils/request.js`（额外导出）

| 函数 | 说明 |
|------|------|
| `fetchCurrentUser()` | GET `/user/current`，获取当前用户信息并写入 localStorage |

### 7.2 仪表盘

#### `src/api/dashboard.js`

| 函数 | 方法 | 端点 | 参数 | 返回 | 说明 |
|------|------|------|------|------|------|
| `fetchTodayStats()` | GET | `/dashboard/statist` | 无 | `{ today_inbound, today_outbound, today_sales }` | 今日入库/出库/销售统计 |
| `fetchEmployeeStats()` | GET | `/dashboard/statist` | 无 | `[{ employee_id, employee_name, inbound_count, outbound_count }]` | 各员工今日工作量统计 |

### 7.3 书籍与条码

#### `src/api/book.js`

| 函数 | 方法 | 端点 | 参数 | 说明 |
|------|------|------|------|------|
| `getBookInfo(isbn)` | GET | `/getBookInfo` | `isbn`（ISBN 号） | 根据 ISBN 查询书籍信息 |
| `syncBook(params)` | POST | `/syncBook` | `book_name, author, publisher, publication_time, binding_layout, fix_price, isbn, page_count, word_count, book_format, fid, f_isbn, f_book_name, live_image[0], type` | 同步/保存书籍信息（JSON 体） |

#### `src/api/barcode.js`

| 函数 | 方法 | 端点 | 参数 | 返回 | 说明 |
|------|------|------|------|------|------|
| `generateBarcode(content)` | POST | `/barcode/generate` | `content`（条码内容） | `{ data: { image_base64 } }` | 生成条码图片 Base64（FormData） |

### 7.4 商品管理

#### `src/api/product.js`

| 函数 | 方法 | 端点 | 参数 | 说明 |
|------|------|------|------|------|
| `fetchProductList({ keyword, status, shop_id, page, pageSize })` | GET | `/product/list` | 关键词、状态、店铺筛选、分页 | 商品分页列表 |
| `fetchProductListByShop({ shop_id, page, pageSize })` | GET | `/product/list` | 委托 `fetchProductList` | 按店铺筛选商品 |
| `fetchProductDetail(id)` | GET | `/product/detail` | `id` | 商品详情 |
| `createProduct(product)` | POST | `/product/save` | 商品对象 | 创建商品 |
| `saveProduct(product)` | POST | `/product/save` | 含 `name, barcode, price, live_image` | 保存商品（兼容旧接口） |
| `updateProduct(product)` | POST | `/product/save` | 含 `id` | 更新商品（同创建端点） |
| `deleteProduct(product)` | POST | `/product/delete` | 含 `id` | 删除商品 |
| `updateProductLiveImage(id, pictureName, extra)` | POST | `/product/save` | 图片名 + 额外字段 | 更新实拍图（Shxy URL） |
| `updateProductLiveImageAsPddUrl(id, picUrl, extra)` | POST | `/product/save` | 完整 URL | 用 PDD URL 更新实拍图 |
| `updateProductLiveImageForTest(id, pictureName, extra)` | POST | `/product/save` | 测试用 | 硬编码测试 URL 更新实拍图 |
| `getSuitBook(isbn)` | GET | `/getSuitBook` | `isbn` | 查询套装书 |
| `getProCode({ book_name, author, publisher })` | GET | `/getProCode` | 书名/作者/出版社 | 获取产品编码（OCR 模式用） |
| `ocrImage(imageBlob)` | POST | `/ocr` | `imageBlob`（图片 Blob） | OCR 识别（跳过签名） |
| `retryProductPublish(productId, shopId, shopType)` | POST | `/product/retry-out-task` | 商品/店铺/类型 | 重试商品发布 |
| `fetchLatestProducts(limit, start, end)` | GET | `/product/list` | 数量限制、时间范围 | 最新商品（仪表盘用） |
| `fetchShopProducts(shopId, page, pageSize)` | GET | `/product/shop-detail` | 店铺 ID 分页 | 店铺商品列表含发布统计 |
| `getBookDetails(id)` | GET | `/product/detail` | `id` | 书籍详情（`fetchProductDetail` 别名） |
| `importProductsByExcel({ userId, warehouse_id, file })` | POST | `/goods/import-from-excel` | 用户/仓库/Excel 文件 | 从 Excel 导入商品 |

### 7.5 店铺管理

#### `src/api/shop.js`

内部 + 外部双路径。外部 API 使用独立 axios 实例 + JSONbig。

| 函数 | 方法 | 端点 | 说明 |
|------|------|------|------|
| `fetchShopList({ keyword, page, pageSize })` | GET | `https://api.buzhiyushu.cn/zhishu/shop/list`（外部） | 从外部 API 获取店铺列表（小车用） |
| `getShopList({ keyword, shop_type, page, pageSize })` | GET | `/shop/list`（内部代理） | 从本地后端获取店铺列表 |
| `fetchShopDetail(id)` | GET | `https://new.taskpool.buzhiyushu.cn:3500/api/shop/get/:id`（外部） | 从外部 API 获取店铺详情 |
| `createShop(shop)` | POST | `/shop/create` | 创建店铺 |
| `updateShop(shop)` | PUT | `/shop/update` | 更新店铺 |
| `deleteShop(shop)` | POST | `/shop/delete` | 删除店铺 |
| `updateShopAuthorize({ id, shop_authorize })` | POST | `/shop/authorize` | 更新授权状态（0=未授权 1=已授权 2=已过期） |
| `updateShopStatus({ id, status })` | POST | `/shop/status` | 更新状态（0=正常 1=禁用） |
| `getAllShopList()` | GET | `/shop/list` | 获取所有店铺（不分页） |

> 外部 API 使用约 `about_id` 来自 `adminUserInfo`。如果 `about_id == 0` 则替换为 1。

### 7.6 供应商管理

#### `src/api/supplier.js`

| 函数 | 方法 | 端点 | 参数 | 说明 |
|------|------|------|------|------|
| `fetchSupplierList({ keyword, status, page, pageSize })` | GET | `/supplier/list` | 关键词（编码/名称）、状态、分页 | 供应商分页列表 |
| `fetchSupplierDetail(id)` | GET | `/supplier/detail/:id` | ID | 供应商详情 |
| `createSupplier(supplier)` | POST | `/supplier/create` | 供应商对象 | 创建供应商 |
| `updateSupplier(supplier)` | PUT | `/supplier/update` | 含 `id` | 更新供应商 |
| `deleteSupplier(supplier)` | POST | `/supplier/delete` | 含 `id` | 删除供应商 |

### 7.7 仓库管理

#### `src/api/warehouse.js`

| 函数 | 方法 | 端点 | 参数 | 说明 |
|------|------|------|------|------|
| `fetchWarehouseList({ keyword, type, status, page, pageSize })` | GET | `/warehouse/list` | 编码/名称、类型、状态、分页 | 仓库分页列表 |
| `fetchWarehousesByIds({ ids, page, pageSize })` | GET | `/warehouse/list` | `ids[]` 数组 | 按 ID 批量查询 |
| `fetchWarehouseDetail(id)` | GET | `/warehouse/detail/:id` | ID | 仓库详情 |
| `createWarehouse(warehouse)` | POST | `/warehouse/create` | 仓库对象 | 创建仓库 |
| `updateWarehouse(warehouse)` | PUT | `/warehouse/update` | 含 `id` | 更新仓库 |
| `deleteWarehouse(warehouse)` | POST | `/warehouse/delete` | 含 `id` | 删除仓库 |

### 7.8 库位管理

#### `src/api/location.js`

| 函数 | 方法 | 端点 | 参数 | 说明 |
|------|------|------|------|------|
| `fetchLocationList({ keyword, warehouseId, type, status, page, pageSize })` | GET | `/location/list` | 编码（code）、仓库、类型、状态、分页 | 库位分页列表 |
| `fetchLocationDetail(id)` | GET | `/location/detail/:id` | ID | 库位详情 |
| `createLocation(location)` | POST | `/location/create` | 库位对象 | 创建库位 |
| `updateLocation(location)` | PUT | `/location/update` | 含 `id` | 更新库位 |
| `deleteLocation(location)` | POST | `/location/delete` | `ids[]`（FormData） | 批量删除库位 |
| `batchUpdateLocations(payload)` | PUT | `/location/update` | `ids[] + { code, type, capacity, status }`（FormData） | 批量更新库位属性 |
| `batchGenerateLocations(payload)` | POST | `/location/batch-generate` | 仓库/类型/容量/状态/生成规则 | 按规则批量生成库位 |
| `importLocationsFromExcel({ user_id, warehouse_id, file })` | POST | `/location/import-from-excel` | 用户/仓库/Excel 文件（FormData） | 从 Excel 导入库位 |
| `fetchAllLocations({ page, pageSize, keyword })` | GET | `/location/all-list` | 分页、关键词 | 跨仓库全库位列表 |

### 7.9 小车管理

#### `src/api/car.js`

| 函数 | 方法 | 端点 | 参数 | 说明 |
|------|------|------|------|------|
| `fetchCarList({ keyword, page, pageSize })` | GET | `/car/list` | 编码/名称、分页 | 小车分页列表 |
| `fetchCarDetail(id)` | GET | `/car/detail/:id` | ID | 小车详情 |
| `createCar(carData)` | POST | `/car/create` | FormData | 创建小车 |
| `updateCar(carData)` | PUT | `/car/update` | FormData（含 `id`） | 更新小车 |
| `deleteCar(id)` | DELETE | `/car/delete` | FormData（含 `id`） | 删除小车 |
| `createCarShop(carShop)` | POST | `/car/shop/create` | 关联数据 | 创建小车-店铺关联 |
| `deleteCarShop(carShop)` | POST | `/car/shop/delete` | 含 `id` | 删除小车-店铺关联 |

### 7.10 波次管理

#### `src/api/waveTask.js`

| 函数 | 方法 | 端点 | 参数 | 说明 |
|------|------|------|------|------|
| `fetchWaveTaskList(params)` | GET | `/wave/task/list` | `task_no, wave_no, page, page_size` | 波次任务列表 |
| `fetchWaveTaskDetail(id)` | GET | `/wave/task/detail` | `id` | 波次任务详情 |
| `deleteWaveTask(data)` | POST | `/delete` | 含 `id` | 删除波次任务 |
| `fetchWaveById(id)` | GET | `/wave/task/detail` | `id` | 按 ID 查波次信息 |
| `fetchWaveTaskByNo(waveNo)` | GET | （两步）先 `/wave/task/list` 再 `/wave/task/detail` | 波次号 | 按波次号查任务 |
| `fetchWaveList(params)` | GET | `/wave/list` | `keyword, status, warehouse_id, page, page_size` | 波次列表（选择器用） |
| `createWaveOutbound(outboundOrderId)` | POST | `/wave/outbound/create` | FormData | 创建波次出库 |
| `createWaveOutboundRelease(relatedOrderId, waveId)` | POST | `/wave/outbound/release` | FormData | 释放波次出库 |
| `getWaveStatusById(id)` | GET | `/wave/getWaveStatusById` | `id` | 查询波次状态 |

### 7.11 采购订单

#### `src/api/purchaseOrder.js`

| 函数 | 方法 | 端点 | 参数 | 说明 |
|------|------|------|------|------|
| `fetchPurchaseOrderList({ keyword, status, page, pageSize, sort_by, sort_order })` | GET | `/purchase-order/list` | 单号(po_no)、状态、分页、排序 | 采购单列表 |
| `fetchPurchaseOrderDetail(id)` | GET | `/purchase-order/detail` | `id` | 采购单详情 |
| `createPurchaseOrder(data)` | POST | `/purchase-order/save` | 采购单数据 | 创建采购单 |
| `updatePurchaseOrder(data)` | POST | `/purchase-order/save` | 含 `id` | 更新采购单 |
| `deletePurchaseOrder(data)` | POST | `/purchase-order/delete` | 含 `id` | 删除采购单 |
| `createPurchaseOrderWithWave(data)` | POST | `/purchase-order/create-with-wave` | `warehouse_id, supplier_id, expected_arrival_date, remark, items[], direction` | 创建采购单并生成波次（步骤 1/2） |
| `releaseWave(data)` | POST | `/wave/release` | `wave_id, related_order_id, items[], car_id, car_code` | 释放波次（步骤 2/2） |

### 7.12 销售订单

#### `src/api/salesOrder.js`

| 函数 | 方法 | 端点 | 参数 | 说明 |
|------|------|------|------|------|
| `fetchSalesOrderList({ keyword, status, customer_id, warehouse_id, page, pageSize, sort_by, sort_order })` | GET | `/sales-order/list` | 单号(so_no)、状态、平台、仓库、分页、排序 | 销售单列表 |
| `fetchSalesOrderDetail(id)` | GET | `/sales-order/detail` | `id` | 销售单详情（含明细） |
| `createSalesOrder(order)` | POST | `/sales-order/create` | 含 `so_no, customer_id, warehouse_id, order_date, required_delivery_date, items[]` | 创建销售单 |
| `updateSalesOrder(order)` | PUT | `/sales-order/update` | 含 `id` | 更新销售单 |
| `deleteSalesOrder(id)` | POST | `/sales-order/delete` | `id` | 删除销售单 |
| `confirmSalesOrder(id)` | POST | `/sales-order/confirm` | `id` | 确认销售单 |
| `cancelSalesOrder(id, remark)` | POST | `/sales-order/cancel` | `id, remark` | 取消销售单 |
| `returnSalesOrderItem(data)` | POST | `/stock_check/return` | `sales_order_id, sales_order_item_id, remark` | 销售单退货 |
| `fetchSalesOrderDetails({ page, pageSize })` | GET | `/sales-order/detaillist` | 分页 | 销售单明细汇总列表 |

### 7.13 出库管理

#### `src/api/outbound.js`

| 函数 | 方法 | 端点 | 参数 | 说明 |
|------|------|------|------|------|
| `fetchOutboundList({ out_no, status, warehouse_id, customer_id, sales_order_id, start_date, end_date, page, page_size })` | GET | `/outbound-order/list` | 多种筛选条件 | 出库单分页列表 |
| `fetchOutboundDetail(id)` | GET | `/outbound-order/detail` | `id` | 出库单详情（含明细） |
| `createOutbound(outbound)` | POST | `/outbound-order/create` | `warehouse_id, customer_id, shipping_date, items[]` | 创建出库单 |
| `updateOutbound(outbound)` | PUT | `/outbound-order/update` | 含 `id` | 更新出库单 |
| `deleteOutbound(outbound)` | POST | `/outbound-order/delete` | 含 `id` | 删除出库单 |
| `approveOutbound(id, status, remark)` | POST | `/outbound-order/approve` | ID + 审核状态 + 备注 | 审核出库单 |
| `exportOutbound(id)` | GET | `/outbound-order/export/:id` | ID（blob 响应） | 导出出库单 |
| `changeLocation(out_order_item_id, remark)` | POST | `/outbound-order/change-location` | 明细 ID + 备注（FormData） | 改库位 |
| `createOutboundFromSalesOrder(salesOrderIds, total, remark)` | POST | `/outbound-order/create` | 销售单 IDs + 总数（FormData） | 从销售单创建出库单 |

### 7.14 发货单

#### `src/api/shippingOrder.js`

内部 + 外部双路径。

| 函数 | 方法 | 端点 | 参数 | 说明 |
|------|------|------|------|------|
| `fetchShippingOrderList(...)` | GET | `/shipping-order/list` | `check_no, status, customer_id, warehouse_id, sales_order_id, wave_task_id, page, pageSize` | 发货单列表 |
| `fetchShippingOrderDetailList(...)` | GET | `/shipping-order/detaillist` | `status(1=待发货 2=已发货 3=已签收 4=已取消), page, pageSize, customer_id, shipping_no, start_date, end_date` | 发货单明细列表（新接口，支持时间范围） |
| `fetchShippingOrderDetail(id)` | GET | `/shipping-order/detail` | `id` | 发货单详情 |
| `createShippingOrder({ total, outbound_order_ids })` | POST | `/shipping-order/create` | 出库单 IDs（FormData） | 从出库单生成发货单 |
| `updateShippingOrderLogistics(...)` | POST | `/shipping-order/update` | `shipping_order_id, sales_order_item_id, logistics_company, logistics_no`（FormData） | 更新物流信息 |
| `recycleWaybillNo({ user_id, logistics_no })` | POST | `/logistics/cancel` | 用户 ID + 运单号（FormData） | 回收/取消运单 |

**外部快递接口：**

| 函数 | 方法 | 端点 | 说明 |
|------|------|------|------|
| `fetchFastMailList(shopId)` | GET | `https://api.buzhiyushu.cn/zhishu/fastMail/listApi?shopId=` | 获取快递账号列表 |
| `createOrderBatch(params)` | POST | `https://print.buzhiyushu.cn/api/print/createOrderBatch` | 创建快递面单（FormData） |
| `createBmOrderDaYin(params)` | GET | `https://print.buzhiyushu.cn/api/print/createBmOrderDaYin` | 获取打印面单信息 |
| `submitCompanyOrder(params)` | POST | `https://api.buzhiyushu.cn/zhishu/orderExternalGoods/submitCompanyOrder` | 回填快递单号（JSON） |
| `fetchExpressInfo(waybillNo)` | GET | `https://print.buzhiyushu.cn/api/print/printViewByWaybillNo` | 获取快递信息 |

### 7.15 库存管理

#### `src/api/inventory.js`

| 函数 | 方法 | 端点 | 参数 | 说明 |
|------|------|------|------|------|
| `fetchInventoryList(params)` | GET | `/inventory/list` | `page, page_size, product_id, warehouse_id` | 库存汇总（按商品+仓库聚合，含总量/锁定/可用） |
| `fetchInventoryDetailList(params)` | GET | `/inventory/detail` | `product_id`（必填） | 库存明细（按仓库+库位+批次） |
| `fetchInventoryLogList(params)` | GET | `/inventory/log/list` | `page, page_size, isbn, book_name, warehouse_id, change_type, related_order_no, start_date, end_date` | 库存变动记录 |
| `fetchInventoryStats(warehouse_id)` | — | — | — | **桩函数**，返回 null |
| `fetchGoodsListByLocation({ keyword, page, pageSize })` | GET | `/inventory/grouped-list` | 库位编码/商品名/条码 | 按库位分组的库存 |
| `inventorySummary()` | GET | `/inventory/summary` | 无 | 库存汇总统计 |

### 7.16 盘库管理

#### `src/api/stockCheck.js`

| 函数 | 方法 | 端点 | 参数 | 说明 |
|------|------|------|------|------|
| `fetchStockCheckList(...)` | GET | `/inventory/stock-check/list` | `keyword, warehouse_id, status(1=待盘点 2=盘点中 3=已完成 4=已取消), check_type(1=全盘 2=抽盘), page, pageSize, sort_by, sort_order` | 盘库单列表 |
| `fetchStockCheckDetail(id)` | GET | `/inventory/stock-check/:id` | ID | 盘库单详情（含明细） |
| `fetchStockCheckItems(stock_check_id, ...)` | GET | `/:id/items` | 盘库单 ID、关键词、状态(1=待盘点 2=已盘点) | 盘库明细列表 |
| `createStockCheck(data)` | POST | `.../create` | `warehouse_id, check_type, remark, items[]` | 创建盘库单 |
| `startStockCheck(id)` | POST | `.../:id/start` | ID | 开始盘点 |
| `submitCheckItem(stock_check_id, data)` | POST | `.../:id/check` | `item_id, actual_quantity, remark` | 提交单项盘点结果 |
| `batchSubmitCheckItems(stock_check_id, data)` | POST | `.../:id/check/batch` | `items: [{ item_id, actual_quantity, remark }]` | 批量提交盘点结果 |
| `completeStockCheck(id)` | POST | `.../:id/complete` | ID | 完成盘点 |
| `cancelStockCheck(id, reason)` | POST | `.../:id/cancel` | ID + 原因 | 取消盘库单 |
| `deleteStockCheck(id)` | DELETE | `.../:id` | ID | 删除盘库单（仅待盘点状态） |
| `adjustStockCheck(data)` | POST | `/stock-check/adjust` | `warehouse_id, product_id, location_id, batch_no, quantity, adjust_type(1=加 2=减), remark`（FormData） | 库存调整 |
| `returnStockCheck(data)` | POST | `/stock-check/return` | 同上（FormData） | 库存退货 |

### 7.17 物流/运费模板

#### `src/api/logistics.js`

| 函数 | 方法 | 端点 | 参数 | 说明 |
|------|------|------|------|------|
| `fetchLogisticsList(params)` | GET | `/logistics/list` | 查询参数 | 物流模板列表 |
| `fetchLogisticsDetail(id)` | GET | `/logistics/detail/:id` | ID | 模板详情 |
| `createLogistics(data)` | POST | `/logistics/create` | 模板数据（FormData） | 创建物流模板 |
| `updateLogistics(data)` | PUT | `/logistics/update` | 含 `id` | 更新物流模板 |
| `deleteLogistics(ids)` | POST | `/logistics/delete` | 单个 ID 或 ID 数组（FormData） | 删除模板 |

#### `src/api/district.js`

| 函数 | 方法 | 端点 | 说明 |
|------|------|------|------|
| `fetchProvinces()` | GET | `/district/province/list` | 获取省份列表 |
| `fetchCitiesByProvinceId(provinceId)` | GET | `/district/city/list/:id` | 根据省份获取城市 |
| `fetchDistrictsByCityId(cityId)` | GET | `/district/area/list/:id` | 根据城市获取区县 |
| `fetchFreightInfo(id)` | GET | `/district/freight/info/:id` | 获取运费模板信息（含发货地址） |
| `createFreightTemplate(data)` | POST | `/district/freight/create` | 创建运费模板 |
| `updateFreightTemplate(data)` | PUT | `/district/freight/update` | 更新运费模板（FormData） |

### 7.18 代理/员工管理

#### `src/api/employee.js`

| 函数 | 方法 | 端点 | 参数 | 说明 |
|------|------|------|------|------|
| `fetchEmployeeList(params)` | GET | `/admin/employee/list` | `page, page_size, status, keyword` | 代理列表 |
| `addEmployee({ name, password, phone, fid, about_id })` | POST | `/admin/employee/add` | 姓名/密码/电话/上级 ID | 添加代理 |
| `topupEmployee(employeeId, { amount, remark })` | POST | `/admin/employee/topup/:employeeId` | 金额 + 备注 | 代理充值 |
| `deductEmployee(employeeId, { amount, remark })` | POST | `/admin/employee/deduct/:employeeId` | 金额 + 备注 | 代理扣款 |
| `toggleEmployeeStatus(action, employeeId)` | POST | `/admin/employee/:action/:employeeId` | `enable` 或 `disable` | 启用/禁用代理 |

#### `src/api/employeeType.js`

| 函数 | 方法 | 端点 | 说明 |
|------|------|------|------|
| `fetchEmployeeTypeList()` | GET | `/admin/user-type/list` | 员工类型列表 |
| `updataEmployeInfo(formdata)` | PUT | `/api/admin/user-type/update` | ⚠️ 函数名拼写错误（应为 update），更新员工类型信息 |

### 7.19 异常书目管理

#### 提交异常书目：`src/api/goodsInfo.js`

| 函数 | 方法 | 端点 | 说明 |
|------|------|------|------|
| `saveAbnormalBook(data)` | POST | `/product_log/save` | 提交异常书目记录（FormData，multipart/form-data），含新旧字段对比（书名、作者、出版社、出版时间、价格、装帧、页码、字数、是否套装、实拍图） |

#### 异常书目审核：`src/api/submIllegalBook.js`

| 函数 | 方法 | 端点 | 参数 | 说明 |
|------|------|------|------|------|
| `auditProductLog(id, status, newFields)` | POST | `/product_log/audit` | `status`: 1=通过 2=驳回；`newFields`: 通过时更新的字段 | 审核异常书目（FormData） |

#### 异常书目查询/删除：`src/api/reviewIllegalBook.js`

| 函数 | 方法 | 端点 | 参数 | 说明 |
|------|------|------|------|------|
| `fetchProductLogList(params)` | GET | `/product_log/list` | `barcode, status, page, page_size` | 异常书目列表 |
| `deleteProductLog(id)` | POST | `/product_log/delete` | ID（FormData） | 删除异常书目 |

### 7.20 分账管理

#### 分账配置（完整版）：`src/api/splitAccount.js`

| 函数 | 方法 | 端点 | 参数 | 说明 |
|------|------|------|------|------|
| `fetchSplitConfigList({ rule_name, status, page, pageSize })` | GET | `/split-account-config/list` | 规则名、状态、分页 | 分账配置列表 |
| `fetchSplitConfigDetail(id)` | GET | `/split-account-config/detail` | `id` | 配置详情 |
| `createSplitConfig({ rule_name, rule_value, status, description })` | POST | `/split-account-config/create` | 规则名、规则值(JSON)、状态、描述 | 创建分账配置（JSON 体） |
| `updateSplitConfig(data)` | POST | `/split-account-config/update` | 含 `id` | 更新分账配置 |
| `deleteSplitConfig(id)` | POST | `/split-account-config/delete` | `id` | 删除分账配置 |
| `toggleSplitConfigStatus(id, status)` | POST | `/split-account-config/update` | `status`: 0=禁用 1=启用 | 启用/禁用配置 |

#### ⚠️ 旧版分账（不完整）：`src/api/split.js`

仅 `createSplitConfig`（使用 URLSearchParams，非 JSON）+ `updateSplitConfig`（空函数体）。建议使用 `splitAccount.js`。

#### 分账扣款日志：`src/api/splitDeductionLog.js`

| 函数 | 方法 | 端点 | 参数 | 说明 |
|------|------|------|------|------|
| `fetchSplitLogList(...)` | GET | `/split-account-deduction-log/list` | `business_no, config_name, created_by, start_time, end_time, page, pageSize` | 扣款日志列表 |
| `fetchSplitLogDetail(id)` | GET | `/split-account-deduction-log/detail` | `id` | 日志详情 |
| `exportSplitLog(params)` | GET | `/split-account-deduction-log/export` | 同列表筛选参数（blob 响应） | 导出日志 |

### 7.21 快递配置

#### `src/api/courierConfig.js`

⚠️ **不完整**——仅 `createConfig({ key, value })`（POST `/config/create`，FormData）有完整实现，`queryConfigList` 仅为 JSDoc 桩。

### 7.22 核价器（外部服务）

#### `src/api/config.js`

所有请求直连用户配置的 `http://{ip}:{port}`，不经过项目代理或签名。

| 函数 | 方法 | 端点 | 请求格式 | 说明 |
|------|------|------|----------|------|
| `testConnection(ip, port)` | POST | `/api/goods/query` | URLSearchParams | 测试连接（`isbn=0&out_id=0&quality=0&query_index=1&user_id=0`） |
| `saveNewPrice(ip, port, newPrice, placeholderDownPrice, minShippingFee, minPrice, verifyIndex)` | POST | `/api/config/price/set` | URLSearchParams | 保存价格配置 |
| `kongfzLogin(username, password, ip, port)` | POST | `/api/kfz/login` | FormData（15s 超时） | 孔夫子登录（通过核价器） |
| `batchAddTokens(tokens, ip, port)` | POST | `/api/token/add` | JSON Array | 批量提交账号 Token |
| `fetchTokenList(ip, port)` | POST | `/api/token/list` | JSON `{}` | 获取 Token 列表 |
| `fetchConfig(ip, port)` | POST | `/api/config/price/get` | JSON `{}` | 获取价格配置 |
| `queryGoodsPrice({ ip, port, isbn, bookName, author, publisher, isSuit, outId, quality, queryIndex, userId, ... })` | POST | `/api/goods/query` | URLSearchParams | 查询商品价格（套装书传 `book_name+author+publisher` 替代 isbn） |
| `deleteToken(ip, port, id)` | GET | `/api/token/delete` | 查询参数 | 删除 Token |

### 7.23 打印服务（重导出）

#### `src/api/print.js`

重导出自 `src/utils/daYin/print.ts`：

| 函数 | 说明 |
|------|------|
| `initLodop()` | 初始化 Lodop/Clodop 打印控件 |
| `createPrintTask(...)` | 创建打印任务 |
| `getSimplePrinterList()` | 获取已安装的打印机列表 |

### 7.24 发布记录（Mock）

#### `src/api/releaseRecord.js`

**全部为 Mock 数据**，无后端接口。包含 4 个模拟店铺（博知书社/pdd、孔夫子旧书网、闲鱼优选、新知图书/pdd）。

| 函数 | 参数 | 说明 |
|------|------|------|
| `fetchReleaseRecordList({ keyword, shop_type, status, page, pageSize })` | 关键词/店铺类型/发布状态/分页 | Mock 发布记录列表（300ms 延迟） |
| `retryRelease(shopId, productId, shopType)` | 店铺/商品/类型 | Mock 重试发布（500ms 延迟，始终成功） |
| `fetchShopReleaseDetail(shopId)` | 店铺 ID | Mock 店铺发布详情（300ms 延迟） |

---

## 8. 状态管理

### 8.1 Pinia Store（`src/store/user.js`）— 推荐使用

| 状态/方法 | 类型 | 说明 |
|-----------|------|------|
| `adminUserInfo` | `ref` | 管理员用户信息（从 localStorage 初始化） |
| `userInfo` | `computed` | adminUserInfo 的别名 |
| `isAdmin` | `computed` | `role === 255` |
| `points` | `computed` | 当前积分 |
| `setUserInfoAction(info)` | 方法 | 更新用户信息并同步 localStorage |
| `updatePoints(newPoints)` | 方法 | 更新积分 |
| `clearAdminUserInfo()` | 方法 | 清除用户信息（登出） |
| `getAdminInfo()` | 方法 | 返回 `adminUserInfo.value` |

### 8.2 旧版 Store（`src/store/index.js`）

基于 Vue `reactive()` 的简单 store，未使用 Pinia：

| 状态/方法 | 说明 |
|-----------|------|
| `state.user` | 用户信息 |
| `state.token` | Token |
| `setUser(user)` | 设置用户 |
| `setToken(token)` | 设置 Token |
| `clear()` | 清除状态 |

> ⚠️ **逐步废弃中**，建议迁移到 Pinia store。

### 8.3 认证存储（localStorage）

由 `src/utils/auth.js` 统一管理：

| Key | 内容 | 用途 |
|-----|------|------|
| `admin_token` | JWT Token | 管理员 Bearer Token（Authorization 头） |
| `admin_userInfo` | JSON `{ id, username, role, about_id, points }` | 管理员信息 |
| `admin_expire` | 过期时间 | Token 有效期 |
| `embed_mode` | `"true"` | 嵌入模式标志（隐藏导航栏） |
| `user_token` | JWT Token | 用户端 Token（区别于管理端） |
| `user_userInfo` | JSON | 用户端信息 |
| `printFlag` | `"1"` | 打印调试模式标记 |

---

## 9. 工具函数

### 9.1 签名工具（`src/utils/sign.js`）

`SignUtil` 单例类：

| 方法 | 说明 |
|------|------|
| `generateSign(params)` | 生成完整签名参数对象（含 app_key、client_id、timestamp、sign_method、sign） |
| `generateSignedUrl(baseUrl, params)` | 生成带签名的完整 URL |
| `calculateSign(params)` | 核心 MD5 签名计算 |
| `buildParamEntries(params, prefix)` | 递归展平嵌套对象/数组 |
| `sortKeys(a, b)` | 智能键排序 |

### 9.2 Mock 数据（`src/utils/mock.js`）

| 数据集 | 内容 |
|--------|------|
| `mockProducts` | 4 个模拟商品（基础会员卡 100pts 等） |
| `mockCards` | 50 张模拟卡密（随机状态 1/2/3/4） |
| `mockEmployees` | 4 个模拟代理（张三、李四、王五、系统管理员） |
| `mockOrders` | 30 个模拟订单 |
| `mockAccessLogs` | 50 条模拟积分记录（70% 收入 + 30% 支出） |

### 9.3 打印服务

| 文件 | 内容 |
|------|------|
| `src/utils/daYin/print.ts` | Lodop/Clodop 打印封装（TypeScript）：`initLodop`, `createPrintTask`, `getSimplePrinterList` |
| `src/utils/daYinPdd/index.ts` | 拼多多打印服务 |
| `src/utils/pddUpload.ts` | 拼多多图片上传 |

### 9.4 其他

| 文件 | 说明 |
|------|------|
| `src/utils/clipboard.js` | 剪贴板操作工具 |
| `src/utils/ServiceManager.js` | 服务管理器 |

---

## 10. 外部服务集成

### 10.1 核价器（Pricer）

- **方式**：通过 `axios` 直连（不经过项目主 API），访问用户配置的 `{ip}:{port}`
- **功能**：查询商品价格、设置价格、孔夫子登录/Token 管理
- **文件**：`src/api/config.js`
- **特点**：每个请求动态传入 IP:Port，支持 URLSearchParams/JSON/FormData 多种请求格式

### 10.2 快递打印

- **方式**：通过独立 `axios` 实例直连（不经过 request 拦截器签名）
- **服务地址**：
  - `api.buzhiyushu.cn` — 快递账号列表、回填快递单号
  - `print.buzhiyushu.cn` — 创建快递面单、获取打印面单、查询快递信息
- **文件**：`src/api/shipping-order.js`

### 10.3 外部店铺 API

- **服务地址**：`https://api.buzhiyushu.cn/zhishu/shop/list` / `https://new.taskpool.buzhiyushu.cn:3500/api/shop/get/:id`
- **使用独立 axios 实例** + `json-bigint` 处理大整数
- **文件**：`src/api/shop.js`

### 10.4 孔夫子旧书网登录

- **方式**：Vite 开发服务器自定义中间件 `/kongfz-login`
- **流程**：POST `login.kongfz.com` → 跟随重定向 → 提取 PHPSESSID → 获取用户信息
- **绕过**：浏览器跨域限制（CORS）
- **错误码**：400（参数为空）/ 405（非 POST）/ 500（登录失败）

### 10.5 OCR 识别

- **端点**：`/ocr`（经过主 API 代理）
- **特殊处理**：设置 `X-Need-Sign: false` 跳过签名，保持 FormData 中 Blob 数据完整性
- **文件**：`src/api/product.js`（`ocrImage()` 方法）

---

## 11. 核心业务流程

### 11.1 波次管理流程

```
相机扫码 (camera.vue)
  ├── 扫描条码 → 查询书籍信息 (getBookInfo)
  ├── OCR 识别 → 提取书名/作者/出版社 (ocrImage)
  ├── 生成条码图片 (generateBarcode)
  ├── 编辑书籍信息 → 同步到系统 (syncBook)
  └── 添加商品 → 创建波次 (createWaveOutbound)
       └── 释放波次 → 生成采购/出库任务 (releaseWave)
```

### 11.2 采购到出库到发货全流程

```
创建采购订单 (createPurchaseOrder)
  └── 创建带波次采购单 (createPurchaseOrderWithWave)
       ├── 释放波次 (releaseWave) → 生成波次任务
       └── 采购入库 → 库存增加
            └── 创建销售订单 (createSalesOrder)
                 ├── 确认销售订单 (confirmSalesOrder)
                 │   └── 创建出库单 (createOutbound / createOutboundFromSalesOrder)
                 │        ├── 审核出库单 (approveOutbound)
                 │        │   └── 生成发货单 (createShippingOrder)
                 │        │        ├── 填写物流公司/单号 (updateShippingOrderLogistics)
                 │        │        └── 回填快递单号 (submitCompanyOrder)
                 │        └── 导出出库单 (exportOutbound)
                 └── 取消销售订单 (cancelSalesOrder)
```

### 11.3 盘库流程

```
创建盘库单 (createStockCheck) — 全盘/抽盘
  └── 开始盘点 (startStockCheck) → 状态变为"盘点中"
       └── 逐条/批量提交盘点结果 (submitCheckItem / batchSubmitCheckItems)
            └── 完成盘点 (completeStockCheck) → 状态变为"已完成"
                 └── 库存调整 (adjustStockCheck) — 如有差异

也可中途取消盘库单 (cancelStockCheck)
```

### 11.4 商品发布流程

```
商品录入 → 选择店铺 → 发布商品
  └── 查看发布记录（当前为 Mock 数据）
       └── 失败重试 (retryProductPublish)
```

### 11.5 异常书目审核流程

```
员工提交异常书目 (saveAbnormalBook)
  └── 管理员审核 (auditProductLog)
       ├── 通过 → 更新书目信息
       └── 驳回 → 标记异常状态
```

---

## 12. 打印服务

### 12.1 打印架构

前端打印基于 **C-Lodop** / **Lodop** 控件，运行在 `http://localhost:8000`。

| 文件 | 说明 |
|------|------|
| `src/utils/daYin/print.ts` | 核心封装（TypeScript）：`initLodop` 加载 `CLodopfuncs.js`，`createPrintTask` 创建打印任务，`getSimplePrinterList` 获取打印机列表 |
| `src/utils/daYinPdd/index.ts` | 拼多多打印封装 |
| `src/api/print.js` | 重导出上述 TS 文件的方法 |

### 12.2 打印机调试模式

**套装书条码打印**在首次走 `PRINT_SETUP`（弹出打印设置对话框），确认后 `localStorage.printFlag = '1'`，后续走 `PRINT()` 静默打印。

| 状态 | 打印方式 | 说明 |
|------|---------|------|
| `printFlag` 未设置或不为 `'1'` | `PRINT_SETUP()` | 弹出打印设置对话框，用户调整参数后确认 |
| `printFlag === '1'` | `PRINT()` | 直接静默打印 |

**手动入口**：波次页搜索栏的"打印调试"按钮，使用固定测试号 `9787000000000-01` 生成条码，始终弹出调试框。

---

## 13. 数据模型

### 13.1 盘库模块

| 表名 | 用途 |
|------|------|
| `stock_check` | 盘库单主表 |
| `stock_check_item` | 盘库明细表 |

**盘库单状态**：`1`=待盘点 → `2`=盘点中 → `3`=已完成 → `4`=已取消  
**盘点类型**：`1`=全盘，`2`=抽盘  
**明细状态**：`1`=待盘点，`2`=已盘点

### 13.2 出库/发货模块

- 基于 `shipping_order` 表结构（API 层已按表结构调整）
- 状态：`1`=待发货，`2`=已发货，`3`=已签收，`4`=已取消

### 13.3 波次模块

| 端点 | 用途 |
|------|------|
| `/wave/task/list` | 波次任务列表 |
| `/wave/task/detail` | 波次任务详情 |
| `/wave/list` | 波次列表（选择器用） |
| `/wave/getWaveStatusById` | 波次状态查询 |

### 13.4 库存模块

- **汇总级别**：按商品 + 仓库聚合
- **明细级别**：按仓库 + 库位 + 批次
- **关键字段**：总量、锁定数量、可用数量

### 13.5 分账模块

| 表/概念 | 说明 |
|---------|------|
| `split_account_config` | 分账规则配置（rule_name + rule_value JSON） |
| `split_account_deduction_log` | 分账扣款日志 |

---

## 14. 已知问题与维护

### 14.1 遗留问题

| # | 问题 | 说明 | 建议 |
|---|------|------|------|
| 1 | Vite 2 版本较旧 | `^2.5.2` 有已知安全更新 | 建议升级到 Vite 4+ |
| 2 | TypeScript 使用不一致 | `tsconfig.json` 存在但项目以 JS 为主 | 统一规范或移除 TS |
| 3 | 发布记录为 Mock 数据 | `releaseRecord.js` 无后端接口 | 待后端接口对接 |
| 4 | 旧版 Store 冗余 | `store/index.js` 与 Pinia 并存 | 可迁移清理 |
| 5 | 备份文件残留 | 多个 `.bak` 文件 | 确认后可删除 |
| 6 | 函数名 typo | `employeeType.js` 中 `updataEmployeInfo` → 应为 `updateEmployeeInfo` | 后续修复 |
| 7 | 文件名 typo | `submIllegalBook.js` → 应为 `submitIllegalBook.js` | 后续重命名 |
| 8 | 文件名 typo | `goosList.vue`（组件中）→ 应为 `goodsList.vue` | 后续重命名 |
| 9 | 重复 API 文件 | `split.js`（不完整）与 `splitAccount.js`（完整）并存 | 可删除 `split.js` |
| 10 | 重复 normalizeListResponse | 约 15 个文件各自定义该函数 | 应抽离为公共工具 |
| 11 | 仪表盘内容为空 | `Dashboard.vue` 统计内容待完善 | 待与后端对接更多数据 |
| 12 | courierConfig 不完整 | 仅 `createConfig` 有实现 | 需补充完整 |
| 13 | PDF 打印未集成 | 面单打印依赖外部服务 | 后端接入后完善 |

### 14.2 开发规范

| 规范 | 说明 |
|------|------|
| **API 层** | 所有后端接口调用集中在 `src/api/`，视图层不直接调用 `request` |
| **列表接口** | 统一使用 `normalizeListResponse()` 标准化返回格式 |
| **命名** | API 函数使用 `fetchXxx`（查询）、`createXxx`（新增）、`updateXxx`（更新）、`deleteXxx`（删除） |
| **签名** | 默认所有业务接口走签名，需跳过的设置 `X-Need-Sign: false` |
| **大整数** | 涉及 ID 字段使用 `json-bigint`，比较时注意 BigNumber 类型 |
| **组件命名** | Vue 组件使用 PascalCase 文件名 |
| **路由 meta** | 正确设置 `requiresAuth` / `requiresAdmin` / `hidden` |

### 14.3 添加新模块步骤

1. 在 `src/api/` 下新建 `<module>.js`，定义所有接口函数（含 JSDoc 注释）
2. 在 `src/views/` 下新建页面目录及 `.vue` 组件
3. 在 `src/router/index.js` 的 `children` 中添加路由
4. 确保 `meta` 中正确设置 `requiresAuth` / `requiresAdmin`
5. 在 `AdminLayout.vue` 中添加菜单项（如需显示在侧边栏）
6. 实现 `normalizeListResponse()` 标准化列表返回

### 14.4 维护日志

| 日期 | 操作 |
|------|------|
| 2026-06-15 | 更新技术文档，补充完整 API 接口表、路由表、新模块 |
| 2026-06-03 | 初始技术文档创建 |

---
*本文档随项目维护持续更新*