cards_web 维护文档
📅 文档更新：2026-04-27
📂 项目路径：D:\project\cards_web
一、项目概览
| 属性 |
详情 |
| 项目名称 |
cards（图书进销存管理后台） |
| 版本 |
1.0.0 |
| 技术栈 |
Vue 3 + Vite 2 + Element Plus + Pinia + Vue Router 4 |
| 源码规模 |
32 个 JS 文件，21 个 Vue 组件 |
核心业务模块
- 波次管理（wave） — 核心流程：相机拍照 → 条码识别 → 书籍信息编辑
- 出库管理（outbound） — 出库单管理（API 层已按
shipping_order 表结构重写）
- 盘库管理（stock-check） — 基于
stock_check / stock_check_item 表
- 采购 / 销售 / 发货单 — 订单全链路
- 商品、库存、供应商、仓库、库位 — 基础数据管理
二、技术架构
2.1 依赖版本
{
"vue": "^3.2.8",
"vue-router": "^4.0.11",
"pinia": "^3.0.4",
"element-plus": "^2.13.7",
"axios": "^0.21.1",
"crypto-js": "^4.2.0",
"@zxing/library": "^0.21.3",
"qrcode": "^1.5.4",
"vite": "^2.5.2"
}
2.2 项目配置
| 文件 |
作用 |
vite.config.js |
Vite 构建配置，dev server 代理 |
.env |
环境变量（API 密钥配置） |
tsconfig.json |
TypeScript 配置（但项目实际以 JS 为主） |
2.3 环境变量（.env）
VITE_APP_API_KEY=psi
VITE_APP_CLIENT_ID=psi
VITE_APP_API_SECRET=psi_api_sign_secret
三、API 架构
3.1 后端服务地址
| 服务 |
地址 |
用途 |
| 主业务 API |
192.168.101.213:9090 |
所有业务接口（已在 vite.config.js 中配置代理） |
ES 搜索 |
192.168.101.162:9009 |
⚠️ 已废弃，功能已合并到主业务 API |
⚠️ 2026-04-27 更新：/api/es 代理已从 vite.config.js 中移除，现仅保留 /api → 192.168.101.213:9090。
3.2 请求封装（src/utils/request.js）
- baseURL：开发环境
/api，生产环境通过 VITE_API_BASE 或 192.168.101.213:9090/api
- 签名机制：所有非 mock 请求默认走签名（
signUtil.generateSign）
- 鉴权 Token：从
localStorage 的 admin_token 读取，通过 Bearer 头部传递
- 请求转换：自动将普通对象转为 FormData（
objectToFormData）
- 响应处理：统一处理 code≠200 的错误提示，按 HTTP 状态码跳转登录页
- Mock 模式：
USE_MOCK = false（默认关闭），可通过环境变量控制
3.3 API 模块列表（src/api/）
| 文件 |
对应接口前缀 |
备注 |
barcode.js |
/barcode/* |
条码相关 |
inventory.js |
/inventory/* |
库存记录 |
location.js |
/location/* |
库位管理 |
outbound.js |
/outbound/* |
出库管理 |
product.js |
/product/* |
商品管理 |
purchase-order.js |
/purchase-order/* |
采购订单 |
sales-order.js |
/sales-order/* |
销售订单 |
shipping-order.js |
/shipping-order/* |
发货单 |
stock-check.js |
/stock-check/* |
盘库管理 |
supplier.js |
/supplier/* |
供应商管理 |
warehouse.js |
/warehouse/* |
仓库管理 |
wave-task.js |
/wave/* |
波次任务 |
注意：wave-task.js 有 .bak_20260426_172453 备份文件，建议清理。
四、路由与权限
4.1 路由模式
- Hash 模式（
createWebHashHistory）
- URL 格式：
http://host:port/#/path
4.2 路由守卫逻辑
| 路径 |
鉴权要求 |
说明 |
/login |
无 |
登录页，已登录自动跳转 /dashboard |
/dashboard |
admin_token 存在 |
仪表盘，入口页 |
| 其他业务页 |
admin_token + role=255 |
仅管理员可访问 |
4.3 角色权限
| role 值 |
身份 |
权限 |
255 |
管理员 |
所有页面和操作 |
128 |
代理 |
降级为普通用户，仅限基础功能 |
五、业务数据模型（关键表结构）
5.1 盘库模块
| 表名 |
用途 |
stock_check |
盘库单主表 |
stock_check_item |
盘库明细 |
| 状态流程 |
1=待盘点 → 2=盘点中 → 3=已完成 / 4=已取消 |
| 盘点类型 |
1=全盘，2=抽盘 |
5.2 出库模块
- 基于
shipping_order 表结构（API 层已重写，接口路径 /shipping-order/*）
- 目前无后端 API，前端先行开发待对接
5.3 波次模块
- 波次任务：
/wave/task/list、/wave/task/detail
- 波次列表：
/wave/list
- 支持按波次号扫码查询任务
六、已知问题与维护记录
6.1 遗留问题
| # |
问题 |
说明 |
建议 |
| 1 |
Vite 2 较旧 |
^2.5.2，有安全更新 |
建议升级到 Vite 4+ |
| 2 |
Dashboard 为空 |
Dashboard.vue 未实现内容 |
待后端接口接入 |
| 3 |
库位管理路由隐藏 |
location 路由正常注册，但 UI 可能未展示入口 |
检查侧边栏组件 |
| 4 |
.bak 备份文件 |
wave-task.js.bak_20260426_172453 |
确认无问题后可删除 |
| 5 |
出库模块无后端 |
outbound.js API 已写好，后端尚未实现 |
等待后端对接 |
| 6 |
TypeScript 未启用 |
tsconfig.json 存在但项目使用 JS |
统一规范或移除 |
6.2 维护日志
| 日期 |
操作 |
| 2026-04-26 |
首次读取项目，建立基础文档 |
| 2026-04-27 |
移除废弃的 ES 搜索服务代理 192.168.101.162:9009（功能已合并到主业务 API） |
七、开发指南
7.1 启动开发服务器
cd D:\project\cards_web
npm run dev
# 访问 http://localhost:3000
7.2 添加新业务模块
- API 层：在
src/api/ 下新建 xxx.js
- 视图层：在
src/views/ 下新建目录和 .vue 组件
- 路由注册：在
src/router/index.js 的 children 中添加路由对象
- 权限控制：确保
meta 中正确设置 requiresAuth / requiresAdmin
7.3 API 签名机制
所有业务请求通过 signUtil.generateSign 生成签名参数：
- GET 请求：
params 签名
- POST/PUT/DELETE：
body 签名
如需跳过签名，可在请求头添加 X-Need-Sign: false。
7.4 Mock 数据调试
如需启用本地 mock 数据，将 src/utils/request.js 中的 USE_MOCK 改为 true。
八、文件清单
8.1 源码统计
src/
├── api/ 12 个业务 API 模块 + 1 个 .bak 备份
├── assets/ 静态资源
├── components/ 公共组件（AdminLayout 等）
├── router/ 路由配置（hash 模式）
├── store/ Pinia 状态管理
├── utils/ 工具函数（auth、request、sign、mock）
└── views/ 18 个业务页面目录
8.2 需要清理的文件
src/api/wave-task.js.bak_20260426_172453 — 备份文件，可删除
九、联系方式
- 后端接口负责人：
192.168.101.213:9090
- 主业务接口前缀：所有 API 通过
/api 代理
本文档随项目维护持续更新
