234 lines
7.0 KiB
Markdown
234 lines
7.0 KiB
Markdown
# 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 依赖版本
|
||
|
||
```json
|
||
{
|
||
"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`）
|
||
|
||
```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 启动开发服务器
|
||
|
||
```bash
|
||
cd D:\project\cards_web
|
||
npm run dev
|
||
# 访问 http://localhost:3000
|
||
```
|
||
|
||
### 7.2 添加新业务模块
|
||
|
||
1. **API 层**：在 `src/api/` 下新建 `xxx.js`
|
||
2. **视图层**：在 `src/views/` 下新建目录和 `.vue` 组件
|
||
3. **路由注册**：在 `src/router/index.js` 的 `children` 中添加路由对象
|
||
4. **权限控制**：确保 `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` 代理
|
||
|
||
---
|
||
|
||
*本文档随项目维护持续更新*
|