DaShangDao/daShangDao_psiWebApp

Fork 0

97694731 44ba8a631c

CI / build (20.x) (push) Waiting to run

Details

CI / lint (push) Waiting to run

Details

CI / test (push) Waiting to run

Details

CI / deploy-preview (push) Blocked by required conditions

Details

CI / security (push) Waiting to run

Details

CI / build (18.x) (push) Has been cancelled

Details

2026-06-15 18:09:39 +08:00

16 KiB

Raw Blame History

🛠 维护文档

📅 文档更新：2026-06-15 📂 项目路径：D:\project\psi_web

一、项目概览

属性	详情
项目名称	cards（图书进销存管理后台）
版本	1.0.0
技术栈	Vue 3 + Vite 2 + Element Plus + Pinia + Vue Router 4
源码规模	31 个 API 文件，33 个页面目录，24 个组件文件
路由模式	History 模式（createWebHistory）

核心业务模块

波次管理（wave） — 核心流程：相机拍照 → 条码识别 → 书籍信息编辑 → 波次创建/释放
出库管理（outbound） — 出库单 CRUD、审核、导出、改库位（基于 shipping_order 表结构）
盘库管理（stock-check） — 全盘/抽盘、逐条/批量提交、库存调整
采购 / 销售 / 发货单 — 订单全链路可追溯
商品、库存、供应商、仓库、库位 — 基础数据管理
分账管理 — 分账规则配置 + 扣款日志查询/导出
快递/物流 — 物流模板、运费模板、快递面单打印、单号回填
店铺管理 — 多店铺平台（拼多多、孔夫子、闲鱼）、授权管理

二、技术架构

2.1 依赖版本

{
  "vue": "^3.2.8",
  "vue-router": "^4.1.6",
  "pinia": "^2.1.7",
  "element-plus": "^2.13.7",
  "axios": "^1.7.9",
  "crypto-js": "^4.2.0",
  "@zxing/library": "^0.21.3",
  "jsbarcode": "^3.12.3",
  "json-bigint": "^1.0.0",
  "qrcode": "^1.5.4",
  "sass-embedded": "^1.99.0",
  "vite": "^2.5.2",
  "@vitejs/plugin-vue": "^1.6.0",
  "typescript": "^5.5.4"
}

2.2 项目配置

文件	作用
`vite.config.js`	Vite 构建配置（dev server 代理、中间件、别名）
`.env`	环境变量（API 密钥配置）
`tsconfig.json`	TypeScript 配置（项目以 JS 为主，部分 .ts 文件）
`package.json`	依赖管理与脚本

2.3 环境变量（`.env`）

VITE_APP_API_KEY=psi
VITE_APP_CLIENT_ID=psi
VITE_APP_API_SECRET=psi_api_sign_secret

2.4 Vite 配置代理

代理规则	目标	说明
`/api`	`https://psi.api.buzhiyushu.cn`	主业务 API（changeOrigin）
`/api/print`	`https://print.buzhiyushu.cn`	打印服务（changeOrigin）

2.5 开发服务器

端口：5174
Host：0.0.0.0
History API Fallback：true
自定义中间件：/kongfz-login（孔夫子旧书网登录代理）

三、API 架构

3.1 后端服务地址

服务	地址	用途
主业务 API	`https://psi.api.buzhiyushu.cn`	所有业务接口（通过 Vite 代理 `/api`）
打印服务	`https://print.buzhiyushu.cn`	打印面单（通过 Vite 代理 `/api/print`）
店铺列表	`https://api.buzhiyushu.cn`	外部店铺列表/快递回填
店铺详情	`https://new.taskpool.buzhiyushu.cn:3500`	外部店铺详情
核价器	`http://{用户配置的 IP}:{Port}`	价格查询/配置（直连，不经过代理）

⚠️ 历史：/api/es 代理（192.168.101.162:9009）已于 2026-04-27 移除。

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

baseURL：开发环境 /api，生产环境 https://psi.api.buzhiyushu.cn/api
超时：10 秒
签名机制：所有非 mock 请求默认走签名（signUtil.generateSign），跳过需设 X-Need-Sign: false
鉴权 Token：从 localStorage.admin_token 读取，通过 Bearer 头部传递
请求转换：自动将普通对象转为 FormData（objectToFormData，支持嵌套/数组）
大整数：使用 json-bigint 替代 JSON.parse
响应处理：统一错误提示 + 按 HTTP 状态码跳转登录页
Mock 模式：USE_MOCK = false（默认关闭），支持商品/卡密/代理/订单/积分的模拟数据
额外导出：fetchCurrentUser() 获取当前用户信息

3.3 API 模块索引（31 个 API 文件）

文件	API 基路径	说明
`barcode.js`	`/barcode/generate`	条码生成（套装书条码打印/调试用）
`book.js`	`/getBookInfo`, `/syncBook`	书籍信息查询/同步
`car.js`	`/car/*`	小车 CRUD + 小车-店铺关联
`config.js`	直连 `http://{ip}:{port}`	核价器（价格查询、Token 管理、孔夫子登录）
`courierConfig.js`	`/config/*`	⚠️ 快递配置（仅 `createConfig` 完整，其余为桩）
`dashboard.js`	`/dashboard/statist`	仪表盘统计（今日/员工）
`district.js`	`/district/*`	省市区数据 + 运费模板 CRUD
`employee.js`	`/admin/employee/*`	代理 CRUD、积分加减、启用禁用
`employeeType.js`	`/admin/user-type/*`	员工类型管理
`goodsInfo.js`	`/product_log/save`	提交异常书目（新旧字段对比，FormData）
`inventory.js`	`/inventory/*`	库存汇总/明细/变动日志
`location.js`	`/location/*`	库位 CRUD、批量生成、Excel 导入
`logistics.js`	`/logistics/*`	物流模板 CRUD
`login.js`	`/login/:role`	管理员/代理登录
`outbound.js`	`/outbound-order/*`	出库单 CRUD、审核、导出、改库位
`print.js`	—	Lodop 打印方法重导出
`product.js`	`/product/*`, `/getSuitBook`, `/ocr`	商品 CRUD、图片管理、OCR、Excel 导入
`purchase-order.js`	`/purchase-order/*`, `/wave/release`	采购单 CRUD、带波次创建、波次释放
`releaseRecord.js`	—	Mock 数据，无后端接口
`reviewIllegalBook.js`	`/product_log/*`	异常书目查询/删除
`sales-order.js`	`/sales-order/*`	销售单 CRUD、确认、取消、退货
`shipping-order.js`	`/shipping-order/*` + 外部接口	发货单 CRUD + 快递面单/回填
`shop.js`	`/shop/*` + 外部 API	店铺 CRUD + 外部列表/详情
`split.js`	`/split-account-config/*`	⚠️ 旧版分账（不完整），建议用 `splitAccount.js`
`splitAccount.js`	`/split-account-config/*`	分账配置 CRUD + 启用/禁用（完整版）
`splitDeductionLog.js`	`/split-account-deduction-log/*`	分账扣款日志列表/详情/导出
`stock-check.js`	`/inventory/stock-check/*`	盘库单 CRUD、盘点、调整、退货
`submIllegalBook.js`	`/product_log/audit`	⚠️ 文件名 "subm" 应为 "submit"，异常书目审核
`supplier.js`	`/supplier/*`	供应商 CRUD
`warehouse.js`	`/warehouse/*`	仓库 CRUD
`wave-task.js`	`/wave/*`	波次任务列表/详情、波次创建/释放

3.4 外部服务集成一览

服务	集成方式	说明
核价器	axios 直连 `http://{ip}:{port}`	价格查询、孔夫子登录、Token 管理
快递打印	axios 直连	面单创建（print.buzhiyushu.cn）、单号回填（api.buzhiyushu.cn）
店铺列表	外部 axios + JSONbig	api.buzhiyushu.cn 店铺列表
店铺详情	外部 axios	new.taskpool.buzhiyushu.cn:3500
孔夫子登录	Vite 自定义中间件	模拟浏览器 POST → 提取 PHPSESSID → 获取用户信息
OCR 识别	主 API `/ocr`（跳过签名）	图片文字识别、提取书名字段
Lodop 打印	本地 8000 端口	C-Lodop 控件，条码打印/调试

四、路由与权限

4.1 路由模式

History 模式（createWebHistory）
URL 格式：http://host:port/path
需要服务端配置 history API fallback（Vite dev 已配置，生产需 Nginx 配置）

4.2 路由守卫逻辑

步骤	逻辑	说明
1	URL token 注入	检测 `?token=xxx` → 解析 JWT payload → 写入 localStorage（嵌入模式）
2	页面标题	`document.title = "{title} - 进销存系统"`
3	登录页	已登录自动跳转 `/dashboard`
4	仪表盘	无 `adminUserInfo` 跳转 `/login`
5	黑名单鉴权	缺少 `meta.isPublic` 的所有页面需登录
6	管理员校验	`requiresAdmin: true` 且 `role !== 255` 跳转 `/dashboard`

4.3 角色权限

role 值	身份	权限范围
`255`	管理员	所有页面和操作
`128`	代理	基础功能（波次、仓库、商品等），无权访问管理页面

4.4 路由统计

共 32 条路由（含 1 个登录页、1 个布局容器、30 个子页面）
管理员专用路由：代理管理、添加代理、员工类型管理、异常书目审核、核价器配置
隐藏路由：库位管理（/location-manager）、PDA 管理（/pdaManage），通过 URL 直接访问但不在侧边栏显示

4.5 新增路由（自上次文档更新以来）

路径	名称	说明
`/sales-order-info-list`	SalesOrderInfoList	销售单详情列表
`/shipping-order-list`	ShippingOrderList	发货单详情列表
`/wave-task`	wave-task	波次任务
`/shop-settings`	shop-settings	店铺设置
`/sorting-settings`	sorting-settings	分拣设置
`/split-config`	split-config	分账配置
`/split-log`	split-log	分账扣款日志
`/courier-config`	courier-config	快递配置
`/pdaManage`	pdaManage	PDA 管理（隐藏）

五、业务数据模型要点

5.1 盘库模块

表名	用途
`stock_check`	盘库单主表（`warehouse_id`、`check_type`、`status`、`remark`）
`stock_check_item`	盘库明细表（`stock_check_id`、`product_id`、`location_id`、`system_quantity`、`actual_quantity`、`status`）

状态流转：1=待盘点 → 2=盘点中 → 3=已完成 / 4=已取消
盘点类型：1=全盘（盘点仓库全部商品），2=抽盘（指定部分商品）

5.2 出库/发货模块

基于 shipping_order 表结构
从销售单 → 出库单 → 发货单，三级流转
发货单状态：1=待发货，2=已发货，3=已签收，4=已取消

5.3 波次模块

波次任务：/wave/task/list、/wave/task/detail
波次列表（选择器）：/wave/list
支持按波次号扫码查询任务
波次出库：先 createWaveOutbound 创建 → 再 createWaveOutboundRelease 释放
采购带波次：先 createPurchaseOrderWithWave 创建 → 再 releaseWave 释放

5.4 库存模块

汇总（按商品+仓库聚合）：/inventory/list → 总量/锁定/可用数量
明细（按仓库+库位+批次）：/inventory/detail
变动日志：/inventory/log/list → 支持时间范围、变动类型筛选

5.5 分账模块

概念	说明
`split-account-config`	分账规则配置（`rule_value` 为 JSON 对象，含分账比例/固定金额等）
`split-account-deduction-log`	扣款执行日志，支持按业务单号/配置名/时间范围查询导出

六、已知问题与维护记录

6.1 遗留问题

#	问题	文件/区域	说明	优先级
1	Vite 2 较旧	`package.json`	`^2.5.2`，有安全更新	中
2	TypeScript 未充分利用	项目范围	`tsconfig.json` 存在，仅 `print.ts` 等少数文件使用 TS	低
3	Dashboard 内容为空	`Dashboard.vue`	仅显示基础统计	低
4	`.bak` 备份文件残留	多处	`camera.vue`（4 个）、`orderList.vue`（3 个）、`shippingOrder.vue` 等	低
5	出库模块待后端对接	`outbound.js`	API 已写好，后端尚未完全实现	中
6	发布记录为 Mock	`releaseRecord.js`	无后端接口，纯前端模拟数据	高
7	`split.js` 不完整	`src/api/split.js`	仅 2 个函数，1 个为桩，应使用 `splitAccount.js`	中
8	`courierConfig.js` 不完整	`src/api/courierConfig.js`	仅 `createConfig` 有实现	中
9	函数名拼写错误	`employeeType.js`	`updataEmployeInfo` → 应为 `updateEmployeeInfo`	低
10	文件名不一致	`submIllegalBook.js`	"subm" → 应为 "submit"	低
11	`normalizeListResponse` 重复	约 15 个 API 文件	各文件独立定义，应抽离公共工具函数	中
12	旧版 Store 冗余	`store/index.js`	与 Pinia store 并存，逐步废弃中	低
13	`goosList.vue` 拼写错误	`components/wave/goosList.vue`	"goos" → 应为 "goods"	低

6.2 维护日志

日期	操作
2026-06-15	全面更新技术文档 + 维护文档，补充完整 API 接口表（31 个文件）、路由表（32 条路由）、新增模块（分账、快递、PDA、扫码等）
2026-06-07	新增打印机调试模式：`car.vue` 添加"打印调试"按钮，`suitBookDialog.vue` 套装书首次打印走 `PRINT_SETUP`，`localStorage.printFlag` 控制是否跳过调试
2026-04-27	移除废弃的 ES 搜索服务代理 `192.168.101.162:9009`（功能已合并到主业务 API）；首次读取项目，建立基础维护文档

七、开发指南

7.1 启动开发服务器

cd D:\project\psi_web
npm run dev
# 访问 http://localhost:5174

7.2 生产构建

npm run build
# 输出到 dist/
npm run serve
# 预览构建结果

7.3 添加新业务模块

API 层：在 src/api/ 下新建 xxx.js，定义所有接口函数（含 JSDoc）
视图层：在 src/views/ 下新建目录和 .vue 组件
路由注册：在 src/router/index.js 的 children 中添加路由对象
权限控制：确保 meta 中正确设置 requiresAuth / requiresAdmin
菜单配置：在 AdminLayout.vue 的侧边栏添加菜单项（如需显示）
列表标准化：实现 normalizeListResponse() 标准化返回格式

7.4 API 开发规范

所有业务请求通过 request 封装，自动处理签名和 FormData 转换
GET 请求：参数通过 params 传递，自动签名
POST/PUT/DELETE：对象参数自动转为 FormData（嵌套对象转为 parentKey[childKey] 格式）
如需跳过签名，在请求头添加 X-Need-Sign: false
涉及大整数的字段（ID 类）注意使用 toString() 比较
图片/文件上传使用 multipart/form-data，删除 Content-Type 头让浏览器自动设置

7.5 Mock 数据调试

如需启用本地 mock 数据进行离线开发：

// src/utils/request.js
const USE_MOCK = true // 改为 true

启用的模拟端点：商品列表、卡密管理、代理管理、订单管理、积分记录、卡密购买。

7.6 打印调试

打印基于 C-Lodop 控件（http://localhost:8000/CLodopfuncs.js）：

首次打印套装书条码时弹出打印设置对话框（PRINT_SETUP）
确认后 localStorage.printFlag = '1'，后续直接静默打印（PRINT）
波次页搜索栏有"打印调试"按钮，使用测试号 9787000000000-01

八、文件清单

8.1 源码统计

src/
├── api/            31 个业务 API 模块
├── assets/         静态资源
├── components/     24 个公共组件文件
├── router/         路由配置（history 模式 + 完整路由守卫）
├── store/          1 个 Pinia store + 1 个旧版 reactive store
├── utils/          8 个工具文件/目录（auth、request、sign、mock、打印等）
└── views/          33 个页面目录

8.2 需清理的文件

文件	原因
`src/api/split.js`	被 `splitAccount.js` 替代（仅保留 `createSplitConfig` 且用了不同的请求格式）
`src/store/index.js`	旧版 store，已被 Pinia 替代
`*.bak` 文件（多个）	备份残留，确认后可删除
`src/api/waveTask.js.bak_*`	波次任务备份文件

8.3 关键代码问题

问题	位置	影响
`updataEmployeInfo` 拼写错误	`src/api/employeeType.js`	函数名拼写错误，调用方需使用错误名
`submIllegalBook.js` 文件名	`src/api/`	文件名与内容不符（实际是 audit 功能）
`goosList.vue` 组件名	`src/components/wave/`	拼写错误
`split.js` vs `splitAccount.js`	`src/api/`	重复文件，实现不一致
`normalizeListResponse` 重复定义	约 15 个 API 文件	代码重复，建议抽离

九、联系方式

主业务 API：https://psi.api.buzhiyushu.cn（通过 /api 代理）
打印服务：https://print.buzhiyushu.cn（通过 /api/print 代理）
外部店铺：https://api.buzhiyushu.cn / https://new.taskpool.buzhiyushu.cn:3500
开发服务器：http://localhost:5174

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

16 KiB Raw Blame History Unescape Escape

🛠 维护文档

一、项目概览

核心业务模块

二、技术架构

2.1 依赖版本

2.2 项目配置

2.3 环境变量（.env）

2.4 Vite 配置代理

2.5 开发服务器

三、API 架构

3.1 后端服务地址

3.2 请求封装（src/utils/request.js）

3.3 API 模块索引（31 个 API 文件）

3.4 外部服务集成一览

四、路由与权限

4.1 路由模式

4.2 路由守卫逻辑

4.3 角色权限

4.4 路由统计

4.5 新增路由（自上次文档更新以来）

五、业务数据模型要点

5.1 盘库模块

5.2 出库/发货模块

5.3 波次模块

5.4 库存模块

5.5 分账模块

六、已知问题与维护记录

6.1 遗留问题

6.2 维护日志

七、开发指南

7.1 启动开发服务器

7.2 生产构建

7.3 添加新业务模块

7.4 API 开发规范

7.5 Mock 数据调试

7.6 打印调试

八、文件清单

8.1 源码统计

8.2 需清理的文件

8.3 关键代码问题

九、联系方式

16 KiB

Raw Blame History

2.3 环境变量（`.env`）

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