490 lines
20 KiB
Markdown
490 lines
20 KiB
Markdown
# 图书进销存系统 — 技术文档
|
||
|
||
> **项目名称**：Cards（图书进销存管理后台）
|
||
> **版本**：1.0.0
|
||
> **最后更新**：2026-06-03
|
||
> **项目路径**：`D:\project\cards_web`
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [项目概述](#1-项目概述)
|
||
2. [技术栈](#2-技术栈)
|
||
3. [项目结构](#3-项目结构)
|
||
4. [构建与部署](#4-构建与部署)
|
||
5. [路由与权限](#5-路由与权限)
|
||
6. [API 架构](#6-api-架构)
|
||
7. [状态管理](#7-状态管理)
|
||
8. [外部服务集成](#8-外部服务集成)
|
||
9. [核心业务流程](#9-核心业务流程)
|
||
10. [已知问题与维护](#10-已知问题与维护)
|
||
|
||
---
|
||
|
||
## 1. 项目概述
|
||
|
||
本项目是一个面向图书行业的**进销存管理后台系统**，覆盖图书采购入库、库存管理、商品发布、销售出库、发货打单、盘库盘点等全链路业务流程。系统支持多角色（管理员/代理）权限控制，并集成了核价器、快递打印、OCR 识别等外部服务。
|
||
|
||
### 核心业务范围
|
||
|
||
| 模块 | 说明 |
|
||
|------|------|
|
||
| **波次管理** | 相机扫码 → 条码识别 → 书籍信息编辑 → 波次创建/释放 |
|
||
| **订单管理** | 采购订单 → 销售订单 → 出库单 → 发货单，全链路可追溯 |
|
||
| **库存管理** | 库存查询（商品维度/仓库维度）、变动记录、盘库盘点 |
|
||
| **商品管理** | 商品 CRUD、实拍图片管理、多店铺发布/重试 |
|
||
| **店铺管理** | 多平台店铺（拼多多、孔夫子、闲鱼等）管理、授权状态 |
|
||
| **系统管理** | 代理账号、员工类型、核价器配置、物流模板、打印机管理 |
|
||
|
||
---
|
||
|
||
## 2. 技术栈
|
||
|
||
### 2.1 前端框架与依赖
|
||
|
||
| 依赖 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| `vue` | ^3.2.8 | 前端框架（Composition API + `<script setup>`） |
|
||
| `vue-router` | ^4.1.6 | 前端路由（History 模式） |
|
||
| `pinia` | ^2.1.7 | 状态管理 |
|
||
| `element-plus` | ^2.13.7 | UI 组件库（中文 locale，small 尺寸） |
|
||
| `@element-plus/icons-vue` | ^2.1.0 | 图标库 |
|
||
| `axios` | ^1.7.9 | HTTP 客户端 |
|
||
| `crypto-js` | ^4.2.0 | 签名算法（MD5/SHA256） |
|
||
| `json-bigint` | ^1.0.0 | 大整数精度处理 |
|
||
| `@zxing/library` | ^0.21.3 | 条形码/二维码扫描 |
|
||
| `jsbarcode` | ^3.12.3 | 条码生成 |
|
||
| `qrcode` | ^1.5.4 | QR 码生成 |
|
||
|
||
### 2.2 工程化
|
||
|
||
| 工具 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| `vite` | ^2.5.2 | 构建工具与开发服务器 |
|
||
| `typescript` | ^5.5.4 | 类型检查（项目以 JS 为主，部分 .ts 文件） |
|
||
| `sass` | ^1.99.0 | CSS 预处理器 |
|
||
|
||
### 2.3 环境变量（`.env`）
|
||
|
||
| 变量 | 值 | 说明 |
|
||
|------|-----|------|
|
||
| `VITE_APP_API_KEY` | `psi` | API 签名密钥 |
|
||
| `VITE_APP_CLIENT_ID` | `psi` | 客户端 ID |
|
||
| `VITE_APP_API_SECRET` | `psi_api_sign_secret` | 签名密钥 |
|
||
|
||
---
|
||
|
||
## 3. 项目结构
|
||
|
||
```
|
||
src/
|
||
├── api/ # API 层：所有后端接口调用集中于此
|
||
│ ├── barcode.js # 条码生成
|
||
│ ├── book.js # 书籍信息查询/同步
|
||
│ ├── car.js # 小车管理
|
||
│ ├── config.js # 核价器配置（直连外部 IP:Port）
|
||
│ ├── dashboard.js # 仪表盘统计
|
||
│ ├── district.js # 行政区划（省/市/区）及运费模板
|
||
│ ├── employee.js # 员工/代理管理
|
||
│ ├── employeeType.js # 员工类型管理
|
||
│ ├── goodsInfo.js # 商品图像信息
|
||
│ └── submIllegalBook.js # 提交异常书目
|
||
│ ├── inventory.js # 库存记录
|
||
│ ├── location.js # 库位管理
|
||
│ ├── login.js # 登录
|
||
│ ├── logistics.js # 物流模板
|
||
│ ├── outbound.js # 出库管理
|
||
│ ├── print.js # 打印服务（导出 Lodop 方法）
|
||
│ ├── product.js # 商品管理
|
||
│ ├── purchase-order.js # 采购订单
|
||
│ ├── releaseRecord.js # 发布记录（当前为 Mock 数据）
|
||
│ ├── reviewIllegalBook.js # 异常书目审核
|
||
│ ├── sales-order.js # 销售订单
|
||
│ ├── shipping-order.js # 发货单（含外部快递接口）
|
||
│ ├── shop.js # 店铺管理（含外部 API + 内部 API）
|
||
│ ├── stock-check.js # 盘库管理
|
||
│ ├── supplier.js # 供应商管理
|
||
│ ├── warehouse.js # 仓库管理
|
||
│ └── wave-task.js # 波次任务
|
||
│
|
||
├── components/ # 公共组件
|
||
│ ├── AdminLayout.vue # 主布局（侧边栏+顶部栏+内容区）
|
||
│ ├── goodsPop/index.vue # ISBN 悬停浮窗（书品信息预览）
|
||
│ ├── inventory/ # 库存子组件（byGoods, byLocation）
|
||
│ ├── product/ # 商品子组件（byGoods, byLocation）
|
||
│ ├── wave/ # 波次子组件（camera, car, bookInfo 等）
|
||
│ └── wareHouse/ # 仓库子组件（WarehouseList, LocationManager）
|
||
│
|
||
├── views/ # 页面级组件
|
||
│ ├── login/Login.vue # 登录页
|
||
│ ├── admin/ # 管理员页面（Dashboard, EmployeeList, EmployeeAdd, employeeType）
|
||
│ ├── wave/Wave.vue # 波次管理主页面
|
||
│ ├── warehouse/ # 仓库列表
|
||
│ ├── supplier/Supplier.vue # 供应商列表
|
||
│ ├── product/Product.vue # 商品列表
|
||
│ ├── purchase-order/ # 采购订单
|
||
│ ├── sales-order/ # 销售订单
|
||
│ ├── shipping-order/ # 发货单
|
||
│ ├── outbound/Outbound.vue # 出库管理
|
||
│ ├── inventory/Inventory.vue # 库存记录
|
||
│ ├── stock-check/ # 盘库管理
|
||
│ ├── shop/Shop.vue # 店铺管理
|
||
│ ├── car/Car.vue # 小车管理
|
||
│ ├── config/config.vue # 核价器配置
|
||
│ ├── logistics/index.vue # 物流模板
|
||
│ ├── releaseRecord/ # 发布记录
|
||
│ ├── reviewIllegalBook/ # 异常书目审核
|
||
│ ├── printer-manager/ # 打印机管理
|
||
│ ├── shop-settings/ # 店铺设置
|
||
│ ├── sorting-settings/ # 分拣设置
|
||
│ ├── location/Location.vue # 库位列表
|
||
│ ├── scanner/Scanner.vue # 扫码页
|
||
│ ├── pdaManage/ # PDA 管理
|
||
│ └── wave-task/WaveTask.vue # 波次任务列表
|
||
│
|
||
├── router/index.js # 路由配置（History 模式 + 路由守卫）
|
||
├── store/ # 状态管理
|
||
│ ├── index.js # 旧版 store（reactive 方式，逐步废弃）
|
||
│ └── user.js # Pinia 用户 store
|
||
├── utils/ # 工具函数
|
||
│ ├── request.js # Axios 封装（拦截器、签名、Mock）
|
||
│ ├── auth.js # Token/UserInfo 的 localStorage 读写
|
||
│ ├── sign.js # 签名工具（MD5/SHA256，参数排序）
|
||
│ ├── mock.js # Mock 数据
|
||
│ ├── clipboard.js # 剪贴板工具
|
||
│ ├── daYin/print.ts # Lodop 打印服务
|
||
│ ├── daYinPdd/index.ts # 拼多多打印
|
||
│ ├── pddUpload.ts # 拼多多图片上传
|
||
│ └── ServiceManager.js # 服务管理器
|
||
├── App.vue # 根组件
|
||
└── main.js # 入口文件（注册 Element Plus / Pinia / Router）
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 构建与部署
|
||
|
||
### 4.1 开发服务器
|
||
|
||
```bash
|
||
npm run dev
|
||
# → http://localhost:5174 （host: 0.0.0.0）
|
||
```
|
||
|
||
### 4.2 生产构建
|
||
|
||
```bash
|
||
npm run build
|
||
# → 输出到 dist/
|
||
```
|
||
|
||
### 4.3 Vite 配置要点
|
||
|
||
在 `vite.config.js` 中：
|
||
|
||
| 配置项 | 值 | 说明 |
|
||
|--------|-----|------|
|
||
| **代理** | `/api` → `http://192.168.101.213:9090` | 主业务 API |
|
||
| **代理** | `/api/print` → `http://192.168.101.127:8075` | 打印服务 |
|
||
| **别名** | `@` → `./src` | 模块路径别名 |
|
||
| **端口** | `5174` | 开发服务器端口 |
|
||
| **自定义中间件** | `/kongfz-login` | 孔夫子登录代理（避免跨域） |
|
||
|
||
---
|
||
|
||
## 5. 路由与权限
|
||
|
||
### 5.1 路由模式
|
||
|
||
`createWebHistory()` — History 模式，URL 格式为 `http://host:port/path`
|
||
|
||
### 5.2 路由表
|
||
|
||
| 路径 | 组件 | 标题 | 权限 |
|
||
|------|------|------|------|
|
||
| `/login` | Login.vue | 登录 | 无（已登录自动跳转） |
|
||
| `/dashboard` | Dashboard.vue | 仪表盘 | 需认证 |
|
||
| `/admin/employees` | EmployeeList.vue | 代理管理 | 管理员 |
|
||
| `/admin/employees/add` | EmployeeAdd.vue | 添加代理 | 管理员 |
|
||
| `/admin/employee-type` | employeeType.vue | 员工类型管理 | 管理员 |
|
||
| `/wave` | Wave.vue | 波次管理 | 需认证 |
|
||
| `/warehouse` | WareHouse.vue | 仓库列表 | 需认证 |
|
||
| `/supplier` | Supplier.vue | 供应商管理 | 需认证 |
|
||
| `/product` | Product.vue | 商品管理 | 需认证 |
|
||
| `/purchase-order` | PurchaseOrder.vue | 采购订单 | 需认证 |
|
||
| `/sales-order` | SalesOrder.vue | 销售订单 | 需认证 |
|
||
| `/outbound` | Outbound.vue | 出库管理 | 需认证 |
|
||
| `/shipping-order` | ShippingOrder.vue | 发货单 | 需认证 |
|
||
| `/inventory` | Inventory.vue | 库存记录 | 需认证 |
|
||
| `/stock-check` | StockCheck.vue | 盘库管理 | 需认证 |
|
||
| `/release-record` | releaseRecord.vue | 发布记录 | 需认证 |
|
||
| `/shop` | Shop.vue | 店铺管理 | 需认证 |
|
||
| `/car` | Car.vue | 小车管理 | 需认证 |
|
||
| `/location` | Location.vue | 库位列表 | 需认证 |
|
||
| `/review-illegal-book` | ReviewIllegalBook.vue | 异常书目审核 | 管理员 |
|
||
| `/testUrl` | config.vue | 核价器配置 | 管理员 |
|
||
| `/printer-manager` | PrinterManager.vue | 打印机管理 | 需认证 |
|
||
| `/logistics` | logistics/index.vue | 物流模板管理 | 需认证 |
|
||
| ... | 其他 | 隐藏菜单路由 | 需认证 |
|
||
|
||
### 5.3 路由守卫逻辑
|
||
|
||
1. **URL 参数注入**：检测 `?token=xxx` 参数，自动写入 localStorage 并解析 JWT，用于跨系统嵌入
|
||
2. **登录守卫**：未登录用户自动重定向到 `/login`
|
||
3. **管理员守卫**：`requiresAdmin: true` 的路由仅 `role=255` 可访问，否则重定向到 `/dashboard`
|
||
|
||
### 5.4 角色权限
|
||
|
||
| role 值 | 身份 | 说明 |
|
||
|---------|------|------|
|
||
| `255` | 管理员 | 全部功能可用 |
|
||
| `128` | 代理 | 仪表盘、波次、仓库、商品等基础功能 |
|
||
|
||
---
|
||
|
||
## 6. API 架构
|
||
|
||
### 6.1 网络拓扑
|
||
|
||
```
|
||
浏览器 ──→ Vite Dev Server (:5174)
|
||
├── /api/* ──→ Proxy ──→ http://192.168.101.213:9090 （主业务 API）
|
||
├── /api/print/* ──→ Proxy ──→ http://192.168.101.127:8075 （打印服务）
|
||
├── /kongfz-login ──→ Node.js 中间件 ──→ login.kongfz.com （孔夫子登录）
|
||
└── axios 直连 ──→ 核价器 http://{ip}:{port} （用户配置）
|
||
──→ https://api.buzhiyushu.cn （店铺列表/快递回填）
|
||
──→ https://print.buzhiyushu.cn （快递面单打印）
|
||
```
|
||
|
||
### 6.2 请求封装（`src/utils/request.js`）
|
||
|
||
核心流程：
|
||
|
||
```
|
||
请求发起
|
||
│
|
||
├── 请求拦截器
|
||
│ ├── 注入 Bearer Token（从 localStorage.admin_token 读取）
|
||
│ ├── 生成签名参数（params/body → MD5 排序签名，可跳过）
|
||
│ └── 对象自动转 FormData（POST/PUT/DELETE）
|
||
│
|
||
└── 响应拦截器
|
||
├── code=200 → 返回 response.data
|
||
├── code≠200 → 统一 ElMessage 错误提示
|
||
├── HTTP 401 → 清除 token 并跳转登录页
|
||
├── HTTP 403/404/500 → 对应错误提示
|
||
└── 网络错误 → "检查网络连接"
|
||
```
|
||
|
||
**签名机制**（`src/utils/sign.js`）：
|
||
- 参数平铺排序（支持嵌套对象和数组）
|
||
- `app_secret + 参数字符串 + app_secret` 进行 MD5 签名
|
||
- 自动注入 `app_key`、`client_id`、`timestamp`、`sign_method` 等系统参数
|
||
- 通过请求头 `X-Need-Sign: false` 可跳过签名
|
||
|
||
**大整数精度**：
|
||
- 使用 `json-bigint` 替换默认的 JSON.parse，防止后端返回的 19 位大整数丢失精度
|
||
|
||
### 6.3 API 模块总览
|
||
|
||
| 文件 | 接口前缀 | 风格 | 说明 |
|
||
|------|---------|------|------|
|
||
| `login.js` | `/login/{role}` | request | 管理员/代理登录 |
|
||
| `dashboard.js` | `/dashboard/statist` | request | 仪表盘统计 |
|
||
| `barcode.js` | `/barcode/generate` | request+FormData | 条码生成 |
|
||
| `book.js` | `/getBookInfo`, `/syncBook` | request | 书籍查询/同步 |
|
||
| `car.js` | `/car/*` | request | 小车 CRUD |
|
||
| `config.js` | 外部 URL `http://{ip}:{port}` | axios 直连 | 核价器（价格查询/Token管理） |
|
||
| `district.js` | `/district/*` | request | 省市区数据、运费模板 |
|
||
| `employee.js` | `/admin/employee/*` | request | 代理增删改查、积分操作 |
|
||
| `employeeType.js` | `/admin/user-type/*` | request | 员工类型管理 |
|
||
| `goodsInfo.js` | `/product_log/save` | request+FormData | 提交书目异常 |
|
||
| `inventory.js` | `/inventory/*` | request | 库存汇总/明细/变动记录 |
|
||
| `location.js` | `/location/*` | request | 库位 CRUD、批量生成 |
|
||
| `logistics.js` | `/logistics/*` | request | 物流模板 CRUD |
|
||
| `outbound.js` | `/outbound-order/*` | request | 出库单 CRUD、审核、导出 |
|
||
| `print.js` | — | 导出 ts 方法 | 打印服务（Lodop） |
|
||
| `product.js` | `/product/*`, `/getSuitBook`, `/ocr` | request | 商品 CRUD、图片管理、OCR |
|
||
| `purchase-order.js` | `/purchase-order/*`, `/wave/release` | request | 采购单 CRUD、波次释放 |
|
||
| `releaseRecord.js` | — | **Mock** | 发布记录（纯前端模拟数据） |
|
||
| `reviewIllegalBook.js` | `/product_log/*` | request | 异常书目查询/删除 |
|
||
| `sales-order.js` | `/sales-order/*` | request | 销售订单 CRUD、确认、取消 |
|
||
| `shipping-order.js` | `/shipping-order/*` | request | 发货单 CRUD + 外部直连 |
|
||
| `shop.js` | `/shop/*` + 外部 URL | request+axios | 店铺 CRUD + 外部列表查询 |
|
||
| `stock-check.js` | `/inventory/stock-check/*` | request | 盘库单 CRUD、盘点提交 |
|
||
| `submIllegalBook.js` | `/product_log/audit` | request+FormData | 异常书目审核 |
|
||
| `supplier.js` | `/supplier/*` | request | 供应商 CRUD |
|
||
| `warehouse.js` | `/warehouse/*` | request | 仓库 CRUD |
|
||
| `wave-task.js` | `/wave/*` | request | 波次任务/列表 |
|
||
|
||
### 6.4 列表接口标准化
|
||
|
||
大部分 API 模块实现了 `normalizeListResponse()` 工具函数，将后端可能返回的各种列表格式统一为 `{ list: Array, total: number }`：
|
||
|
||
```javascript
|
||
const normalizeListResponse = (payload) => {
|
||
const data = payload?.data
|
||
if (!data) return { list: [], total: 0 }
|
||
if (Array.isArray(data)) return { list: data, total: data.length }
|
||
return {
|
||
list: Array.isArray(data.list) ? data.list : [],
|
||
total: typeof data.total === 'number' ? data.total : (data.list?.length || 0)
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.5 Mock 模式
|
||
|
||
`src/utils/request.js` 中 `USE_MOCK = false`。启用后支持模拟数据（商品、卡密、订单、代理等），用于离线开发调试。
|
||
|
||
---
|
||
|
||
## 7. 状态管理
|
||
|
||
### 7.1 Pinia Store（`src/store/user.js`）
|
||
|
||
| 状态/方法 | 类型 | 说明 |
|
||
|-----------|------|------|
|
||
| `adminUserInfo` | `ref` | 管理员用户信息（从 localStorage 初始化） |
|
||
| `userInfo` | `computed` | adminUserInfo 的别名 |
|
||
| `isAdmin` | `computed` | `role === 255` |
|
||
| `points` | `computed` | 当前积分 |
|
||
| `setUserInfoAction(info)` | 方法 | 更新用户信息（同步到 localStorage） |
|
||
| `updatePoints(newPoints)` | 方法 | 更新积分 |
|
||
| `clearAdminUserInfo()` | 方法 | 清除用户信息（登出） |
|
||
|
||
### 7.2 旧版 Store（`src/store/index.js`）
|
||
|
||
基于 Vue `reactive` 的简单 store，未使用 Pinia，逐步废弃中。
|
||
|
||
### 7.3 认证状态
|
||
|
||
认证信息存储于 `localStorage`，通过 `src/utils/auth.js` 统一管理：
|
||
|
||
| Key | 内容 | 用途 |
|
||
|-----|------|------|
|
||
| `admin_token` | JWT Token | 管理员 Bearer Token |
|
||
| `admin_userInfo` | JSON 用户信息 | 管理员信息（含 role、about_id 等） |
|
||
| `embed_mode` | `"true"` | 嵌入模式标志（隐藏导航栏） |
|
||
|
||
---
|
||
|
||
## 8. 外部服务集成
|
||
|
||
### 8.1 核价器（Pricer）
|
||
|
||
- **方式**：通过 `axios` 直连（不经过项目主 API），连接用户配置的 IP:Port
|
||
- **功能**：查询商品价格、设置价格、管理登录 Token
|
||
- **文件**：`src/api/config.js`，全部为 axios 直连请求
|
||
|
||
### 8.2 快递打印
|
||
|
||
- **方式**：通过 `axios` 直连
|
||
- **接口**：
|
||
- `api.buzhiyushu.cn` — 快递账号列表、回填快递单号
|
||
- `print.buzhiyushu.cn` — 创建快递面单、获取打印面单
|
||
- **特点**：使用独立的 `axios` 实例（不经过 request 拦截器签名）
|
||
- **文件**：`src/api/shipping-order.js`
|
||
|
||
### 8.3 店铺列表
|
||
|
||
- 内部接口（经过代理）和外部接口（`api.buzhiyushu.cn` 直连）两条路径
|
||
- 外部接口使用独立 axios 实例 + JSONbig 处理大整数
|
||
- **文件**：`src/api/shop.js`
|
||
|
||
### 8.4 孔夫子旧书网登录
|
||
|
||
- 通过 Vite 开发服务器自定义中间件 `/kongfz-login` 实现
|
||
- 模拟浏览器登录流程：POST 表单 → 处理重定向 → 提取 PHPSESSID → 获取用户信息
|
||
- 绕过浏览器跨域限制
|
||
|
||
### 8.5 OCR 识别
|
||
|
||
- 图片上传到 `/ocr` 接口进行文字识别
|
||
- 跳过签名（`X-Need-Sign: false`），保持 FormData 中 Blob 数据完整性
|
||
- **文件**：`src/api/product.js` 中的 `ocrImage()`
|
||
|
||
### 8.6 Lodop 打印
|
||
|
||
- `src/utils/daYin/print.ts` — Clodop/Lodop 打印服务封装
|
||
- `src/utils/daYinPdd/index.ts` — 拼多多打印服务
|
||
|
||
---
|
||
|
||
## 9. 核心业务流程
|
||
|
||
### 9.1 波次管理流程
|
||
|
||
```
|
||
相机扫码 (camera.vue)
|
||
├── 扫描条码 → 查询书籍信息 (getBookInfo)
|
||
├── OCR 识别 → 提取书名/作者/出版社 (ocrImage)
|
||
├── 生成条码图片 (generateBarcode)
|
||
├── 编辑书籍信息 → 同步到系统 (syncBook)
|
||
└── 添加商品 → 创建波次 (createWaveOutbound)
|
||
└── 释放波次 → 生成采购/出库任务 (releaseWave)
|
||
```
|
||
|
||
### 9.2 采购到出库流程
|
||
|
||
```
|
||
创建采购订单 (createPurchaseOrder)
|
||
└── 创建波次 → 释放波次 → 生成波次任务
|
||
└── 采购入库 → 库存增加
|
||
└── 创建销售订单 (createSalesOrder)
|
||
└── 确认销售订单 → 创建出库单 (createOutbound)
|
||
└── 审核出库单 → 生成发货单 (createShippingOrder)
|
||
└── 填写物流信息 → 回填快递单号 (submitCompanyOrder)
|
||
```
|
||
|
||
### 9.3 盘库流程
|
||
|
||
```
|
||
创建盘库单 (createStockCheck) — 全盘/抽盘
|
||
└── 开始盘点 (startStockCheck) → 状态变为"盘点中"
|
||
└── 逐条/批量提交盘点结果 (submitCheckItem / batchSubmitCheckItems)
|
||
└── 完成盘点 (completeStockCheck) → 状态变为"已完成"
|
||
```
|
||
|
||
### 9.4 店铺商品发布
|
||
|
||
```
|
||
商品录入 → 选择店铺 → 发布商品
|
||
└── 查看发布记录（当前为 Mock 数据）
|
||
└── 失败重试 (retryRelease)
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 已知问题与维护
|
||
|
||
### 10.1 遗留问题
|
||
|
||
| # | 问题 | 说明 | 建议 |
|
||
|---|------|------|------|
|
||
| 1 | Vite 2 版本较旧 | `^2.5.2` 有已知安全更新 | 建议升级到 Vite 4+ |
|
||
| 2 | TypeScript 使用不一致 | `tsconfig.json` 存在但项目以 JS 为主 | 统一规范或移除 TS |
|
||
| 3 | 发布记录为 Mock 数据 | `releaseRecord.js` 无后端接口 | 待后端接口对接 |
|
||
| 4 | 旧版 Store 冗余 | `store/index.js` 与 Pinia 并存 | 可迁移清理 |
|
||
| 5 | 备份文件残留 | `.bak` 后缀文件 | 确认后可删除 |
|
||
|
||
### 10.2 开发规范
|
||
|
||
- **API 层**：所有后端接口调用集中在 `src/api/`，视图层不直接调用 `request`
|
||
- **列表接口**：统一使用 `normalizeListResponse()` 标准化返回格式
|
||
- **接口文档**：优先用 JSDoc 注释描述参数和返回值
|
||
- **命名**：API 函数使用 `fetchXxx`（查询）、`createXxx`（新增）、`updateXxx`（更新）、`deleteXxx`（删除）
|
||
|
||
### 10.3 添加新模块步骤
|
||
|
||
1. 在 `src/api/` 下新建 `<module>.js`，定义所有接口函数
|
||
2. 在 `src/views/` 下新建页面目录及 `.vue` 组件
|
||
3. 在 `src/router/index.js` 的 `children` 中添加路由
|
||
4. 确保 `meta` 中正确设置 `requiresAuth` / `requiresAdmin`
|
||
5. 在 `AdminLayout.vue` 中添加菜单项
|
||
|
||
---
|
||
|
||
*本文档随项目维护持续更新*
|