# 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` 代理

---

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