daShangDao_psiWebApp/技术文档.md

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

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

---

目录

1. 项目概述
2. 技术栈
3. 项目结构
4. 构建与部署
5. 路由与权限
6. API 架构
7. API 接口详表
8. 状态管理
9. 工具函数
10. 外部服务集成
11. 核心业务流程
12. 打印服务
13. 数据模型
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 开发服务器

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

4.2 生产构建

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 类（单例导出），配置来自环境变量：

{
  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 }：

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	初始技术文档创建

---

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