385 lines
16 KiB
Markdown
385 lines
16 KiB
Markdown
# 🛠 维护文档
|
||
|
||
> 📅 文档更新：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 依赖版本
|
||
|
||
```json
|
||
{
|
||
"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`）
|
||
|
||
```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 启动开发服务器
|
||
|
||
```bash
|
||
cd D:\project\psi_web
|
||
npm run dev
|
||
# 访问 http://localhost:5174
|
||
```
|
||
|
||
### 7.2 生产构建
|
||
|
||
```bash
|
||
npm run build
|
||
# 输出到 dist/
|
||
npm run serve
|
||
# 预览构建结果
|
||
```
|
||
|
||
### 7.3 添加新业务模块
|
||
|
||
1. **API 层**：在 `src/api/` 下新建 `xxx.js`，定义所有接口函数（含 JSDoc）
|
||
2. **视图层**：在 `src/views/` 下新建目录和 `.vue` 组件
|
||
3. **路由注册**：在 `src/router/index.js` 的 `children` 中添加路由对象
|
||
4. **权限控制**：确保 `meta` 中正确设置 `requiresAuth` / `requiresAdmin`
|
||
5. **菜单配置**：在 `AdminLayout.vue` 的侧边栏添加菜单项（如需显示）
|
||
6. **列表标准化**：实现 `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 数据进行离线开发：
|
||
|
||
```javascript
|
||
// 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`
|
||
|
||
---
|
||
|
||
*本文档随项目维护持续更新*
|