# product-manager

**Repository Path**: yichench/product-manager

## Basic Information

- **Project Name**: product-manager
- **Description**: 商品管理系统
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-30
- **Last Updated**: 2026-06-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 商品库存管理系统 (Product Inventory Manager)

基于 Spring Boot + Vue 3 的进销存管理系统，提供商品管理、供应商管理、入库管理、出库管理核心功能，支持库存自动更新与预警。

## 技术栈

| 层次 | 技术 |
|------|------|
| 后端框架 | Spring Boot 2.7.18 / Java 17 |
| ORM | MyBatis 2.3.0 (注解式 SQL) |
| 数据库 | MySQL 8.0 |
| 前端框架 | Vue 3.4 (Composition API + `<script setup>`) |
| 构建工具 | Vite 5 / Maven |
| UI 组件库 | Element Plus 2.7 |
| 路由/状态 | Vue Router 4 (History 模式) / Pinia |
| HTTP | Axios (响应拦截器解包 Result 结构) |
| Excel 导出 | Alibaba EasyExcel 3.3.4 (注解驱动，流式写入) |

## 快速启动

### 前置条件

- JDK 17+, Maven 3.6+
- Node.js 18+, npm 9+
- MySQL 8.0+

### 1. 初始化数据库

```sql
CREATE DATABASE IF NOT EXISTS product_db DEFAULT CHARSET utf8mb4;
```

表结构由 MyBatis Mapper 中的注解 SQL 定义，首次启动前需手动建表（参见下方 DDL）。

### 2. 启动后端

```bash
cd product-manager
mvn clean package -DskipTests
java -jar target/product-manager-1.0.0.jar
```

后端默认运行在 `http://localhost:8080`。

### 3. 启动前端

```bash
cd product-manager-web
npm install
npm run dev
```

前端默认运行在 `http://localhost:5173`，`/api` 请求自动代理到后端 8080 端口。

## 功能模块

### 商品管理

| 功能 | 说明 |
|------|------|
| 商品列表 | 表格展示全部商品，含名称/分类/价格/库存 |
| 新增商品 | 填写名称、分类、价格、库存 |
| 编辑商品 | 修改已有商品信息 |
| 删除商品 | 有关联入库/出库记录时禁止删除并提示 |
| 导出 Excel | 一键导出全部商品数据为 `.xlsx` |

### 入库管理

| 功能 | 说明 |
|------|------|
| 入库列表 | 表格展示全部入库记录，支持日期范围筛选 |
| 新增入库 | 选择商品 → 自动填入单价 → 填写数量 → 自动计算总金额 |
| 删除入库 | 删除记录同时自动回滚库存 |
| 导出 Excel | 导出当前筛选条件下的入库记录，或导出全部 |

### 出库/销售管理

| 功能 | 说明 |
|------|------|
| 出库列表 | 表格展示全部出库记录，支持日期范围筛选 |
| 新增出库 | 选择商品（库存为 0 的置灰禁用）→ 校验库存充足 → 扣减库存 |
| 删除出库 | 删除记录同时自动回滚库存 |
| 导出 Excel | 导出当前筛选条件下的出库记录，或导出全部 |

### 供应商管理

| 功能 | 说明 |
|------|------|
| 供应商列表 | 表格展示全部供应商，含名称/联系人/电话/地址 |
| 新增供应商 | 填写名称、联系人、电话、地址等信息 |
| 编辑供应商 | 修改已有供应商信息 |
| 删除供应商 | 有关联入库记录时禁止删除并提示 |
| 导出 Excel | 一键导出全部供应商数据为 `.xlsx` |

### 仪表盘

| 功能 | 说明 |
|------|------|
| 统计卡片 | 商品总数、库存总量、低库存商品数、入库/出库次数、销售总收入 |
| 库存预警 | 列出库存 < 10 的商品，支持「快速入库」跳转 |
| 导出预警 | 一键导出低库存商品列表为 Excel |

## 用例说明

### 商品 CRUD

```
Actor: 管理员
前置: 已登录系统
流程:
  1. 进入「商品管理」查看商品列表
  2. 点击「新增商品」填写表单并保存
  3. 编辑已有商品信息
  4. 删除不用的商品（无关联记录时）
后置: 商品数据持久化
```

### 入库流程

```
Actor: 管理员
前置: 商品已存在
流程:
  1. 进入「入库记录」→ 点击「新增入库」
  2. 选择商品（单价自动填入）
  3. 填写数量、供应商等信息
  4. 保存 → 库存自动增加
后置: 入库记录写入，商品库存 += 入库数量
```

### 出库流程

```
Actor: 管理员
前置: 商品库存充足
流程:
  1. 进入「销售出库」→ 点击「新增出库」
  2. 选择商品（库存不足的商品置灰）
  3. 填写数量（不可超出当前库存）
  4. 保存 → 库存自动扣减
后置: 出库记录写入，商品库存 -= 出库数量
异常: 库存不足时拒绝出库并提示
```

### 库存预警

```
Actor: 管理员
前置: 存在库存 < 10 的商品
流程:
  1. 进入「仪表盘」查看预警表格
  2. 点击「快速入库」跳转到入库表单，商品已预选
  3. 填写数量完成补货
后置: 库存得到补充，预警消失
```

### 供应商管理

```
Actor: 管理员
前置: 无
流程:
  1. 进入「供应商管理」查看供应商列表
  2. 点击「新增供应商」填写名称、联系人等信息并保存
  3. 编辑已有供应商信息
  4. 删除不再合作的供应商（无关联入库记录时）
  5. 新增入库时从供应商下拉列表中选择
后置: 供应商数据持久化，入库时可关联选择
```

### 删除回滚

```
Actor: 管理员
前置: 存在入库/出库记录
流程:
  1. 在列表页删除一条入库/出库记录
  2. 系统弹出确认提示「删除后库存将自动回滚」
  3. 确认后记录删除，库存恢复
后置: 记录删除，库存恢复到操作前的数值
```

### 数据导出

```
Actor: 管理员
前置: 存在数据
流程:
  1. 在任意列表页点击「导出」按钮
  2. 前端发送请求，后端流式生成 Excel 文件
  3. 浏览器自动下载 `.xlsx` 文件
后置: 获得 Excel 文件，数据完整可查阅
分支:
  - 入库/出库列表支持按日期筛选后导出
  - 仪表盘支持单独导出低库存预警列表
```

## 数据库设计 (ER 图)

![](D:\商品库存管理系统\product-manager\assets/product_db_er_photograph.png)

### 表说明

#### product — 商品主表

核心业务实体，`stock` 字段为实时库存，受入库和出库操作的原子 SQL 更新（`UPDATE product SET stock = stock + ? WHERE id = ?`），避免并发丢失更新。

#### supplier — 供应商表

独立管理的供应商实体，与入库记录通过 `supplier_id` 关联。`name` 字段有 UNIQUE 约束防止重复录入。`contact`、`phone`、`address` 为可选联系信息。删除供应商时需确保无关联入库记录。

#### purchase_record — 入库记录表

记录每次向供应商采购的商品明细。`total_amount = unit_price × quantity` 由后端计算。`product_name` 和 `supplier` 均为冗余快照字段，分别保存入库时的商品名称和供应商名称，防止改名后历史记录错乱。`supplier_id` 可选关联 `supplier` 表。`created_at` 由 `DEFAULT CURRENT_TIMESTAMP` 自动填充。

#### sale_record — 出库/销售记录表

与入库记录对称设计，记录每次向客户销售的商品明细。`sold_at` 记录出库时间。出库时强制校验 `product.stock >= quantity`，库存不足时拒绝操作。`product_id` 上建有索引 `idx_product_id` 以加速按商品查询。

#### user — 用户表

系统用户，支持多用户登录和角色权限。`password` 使用 BCrypt 编码存储，不保存明文。`display_name` 作为操作人姓名来源，在出入库记录和操作日志中追溯。`role` 分为 ADMIN 和 USER 两级，ADMIN 可访问用户管理和操作日志模块。系统启动时自动创建默认管理员（admin / admin123）。

#### operation_log — 操作日志表

审计日志，记录所有入库/出库操作的创建和删除行为。由 Service 层在业务操作成功后自动写入，对上层透明。`entity_type` + `entity_id` 定位被操作的对象，`operator_id` + `operator_name` 记录操作人，`detail` 记录操作详情摘要。`created_at` 记录操作时间，用于审计追溯。

### 关键约束

| 规则 | 实现 |
|------|------|
| 商品删除保护 | `ProductServiceImpl.deleteById()` 先查 `purchase_record` 和 `sale_record` 中是否存在关联记录 |
| 供应商删除保护 | `SupplierServiceImpl.deleteById()` 先查 `purchase_record` 中是否存在 `supplier_id` 关联 |
| 库存一致性 | 出入库操作与库存更新在同一个 `@Transactional` 事务中 |
| 并发安全 | 库存使用 `SET stock = stock + ?` 原子 SQL，非读取-修改-写入 |
| 库存不回滚为负 | `SaleRecordServiceImpl.addSale()` 出库前校验 `stock >= quantity` |

## API 总览

| 方法 | 路径 | 说明 | 权限 |
|------|------|------|------|
| POST | `/api/auth/login` | 用户登录 | 公开 |
| GET | `/api/products` | 商品列表 | 登录 |
| GET | `/api/products/{id}` | 商品详情 | 登录 |
| POST | `/api/products` | 新增商品 | 登录 |
| PUT | `/api/products/{id}` | 更新商品 | 登录 |
| DELETE | `/api/products/{id}` | 删除商品 | 登录 |
| GET | `/api/purchases` | 入库列表（支持 `start` & `end` 日期筛选） | 登录 |
| POST | `/api/purchases` | 新增入库 | 登录 |
| DELETE | `/api/purchases/{id}` | 删除入库（回滚库存） | 登录 |
| GET | `/api/sales` | 出库列表（支持 `start` & `end` 日期筛选） | 登录 |
| POST | `/api/sales` | 新增出库（校验库存） | 登录 |
| DELETE | `/api/sales/{id}` | 删除出库（回滚库存） | 登录 |
| GET | `/api/suppliers` | 供应商列表 | 登录 |
| GET | `/api/suppliers/{id}` | 供应商详情 | 登录 |
| POST | `/api/suppliers` | 新增供应商 | 登录 |
| PUT | `/api/suppliers/{id}` | 更新供应商 | 登录 |
| DELETE | `/api/suppliers/{id}` | 删除供应商（带关联检查） | 登录 |
| GET | `/api/users` | 用户列表 | ADMIN |
| GET | `/api/operation-logs` | 操作日志列表 | ADMIN |
| GET | `/api/products/export` | 导出商品 Excel | 登录 |
| GET | `/api/purchases/export?start=&end=` | 导出入库 Excel（可选日期筛选） | 登录 |
| GET | `/api/sales/export?start=&end=` | 导出出库 Excel（可选日期筛选） | 登录 |
| GET | `/api/suppliers/export` | 导出供应商 Excel | 登录 |
| GET | `/api/dashboard/export/low-stock` | 导出低库存预警 Excel | 登录 |

统一响应格式 `Result<T>`（导出接口直接返回 Excel 二进制流）：

```json
{
  "code": 200,
  "msg": "success",
  "data": {}
}
```

## 项目结构

```
product-manager/
├── pom.xml
├── sql/
│   ├── init.sql                          # 数据库初始化 DDL
│   └── backfill_operator.sql             # 历史数据操作人补全脚本
├── src/main/java/com/example/productmanager/
│   ├── ProductManagerApplication.java    # Spring Boot 入口
│   ├── common/
│   │   ├── Result.java                   # 统一响应
│   │   └── GlobalExceptionHandler.java   # 全局异常处理
│   ├── config/
│   │   ├── DataInitializer.java          # 启动时创建默认管理员
│   │   ├── JwtAuthFilter.java            # JWT 认证过滤器
│   │   └── SecurityConfig.java           # Spring Security 配置
│   ├── controller/
│   │   ├── AuthController.java           # 登录认证
│   │   ├── ProductController.java
│   │   ├── PurchaseRecordController.java
│   │   ├── SaleRecordController.java
│   │   ├── SupplierController.java
│   │   ├── UserController.java           # 用户管理
│   │   ├── OperationLogController.java   # 操作日志
│   │   └── ExportController.java         # Excel 导出
│   ├── dto/
│   │   ├── LoginRequest.java             # 登录请求 DTO
│   │   ├── ProductExportDTO.java
│   │   ├── PurchaseExportDTO.java
│   │   ├── SaleExportDTO.java
│   │   └── SupplierExportDTO.java
│   ├── entity/
│   │   ├── Product.java
│   │   ├── PurchaseRecord.java
│   │   ├── SaleRecord.java
│   │   ├── Supplier.java
│   │   ├── User.java                     # 用户实体
│   │   └── OperationLog.java             # 操作日志实体
│   ├── mapper/
│   │   ├── ProductMapper.java
│   │   ├── PurchaseRecordMapper.java
│   │   ├── SaleRecordMapper.java
│   │   ├── SupplierMapper.java
│   │   ├── UserMapper.java
│   │   └── OperationLogMapper.java
│   ├── service/
│   │   ├── ExportService.java
│   │   ├── ProductService.java
│   │   ├── PurchaseRecordService.java
│   │   ├── SaleRecordService.java
│   │   ├── SupplierService.java
│   │   ├── OperationLogService.java
│   │   └── impl/
│   │       ├── ProductServiceImpl.java
│   │       ├── PurchaseRecordServiceImpl.java
│   │       ├── SaleRecordServiceImpl.java
│   │       ├── SupplierServiceImpl.java
│   │       └── OperationLogServiceImpl.java
│   └── util/
│       └── JwtUtil.java                  # JWT 令牌工具
├── src/main/resources/
│   ├── application.yml                   # 数据库 & JWT 配置
│   └── static/
│       ├── index.html                    # API 文档页面
│       └── css/api-docs.css
└── product-manager-web/                  # 前端项目
    ├── index.html
    ├── package.json
    ├── vite.config.js
    └── src/
        ├── main.js
        ├── App.vue
        ├── style.css
        ├── api/
        │   ├── request.js
        │   ├── auth.js                   # 登录 API
        │   ├── product.js
        │   ├── purchase.js
        │   ├── sale.js
        │   ├── supplier.js
        │   ├── user.js                   # 用户管理 API
        │   ├── operationLog.js           # 操作日志 API
        │   └── export.js
        ├── mock/
        │   ├── index.js
        │   ├── product.js
        │   ├── purchase.js
        │   ├── sale.js
        │   ├── supplier.js
        │   └── auth.js                   # 登录 Mock
        ├── router/index.js
        ├── stores/
        │   ├── app.js
        │   └── user.js                   # 用户状态 + token 管理
        ├── utils/format.js
        └── views/
            ├── login/
            │   └── LoginView.vue
            ├── layout/MainLayout.vue
            ├── dashboard/DashboardView.vue
            ├── product/
            │   ├── ProductListView.vue
            │   └── ProductFormView.vue
            ├── purchase/
            │   ├── PurchaseListView.vue
            │   └── PurchaseFormView.vue
            ├── sale/
            │   ├── SaleListView.vue
            │   └── SaleFormView.vue
            ├── supplier/
            │   ├── SupplierListView.vue
            │   └── SupplierFormView.vue
            ├── user/
            │   └── UserListView.vue
            └── operationLog/
                └── OperationLogView.vue
```