摩托车零部件采购管理系统

项目介绍

这是一个基于Spring Boot的摩托车零部件采购管理系统，用于管理供应商、产品/零部件、采购订单、库存、客户和物流等业务。本项目为纯后端API服务，不包含可交互的前端页面，所有功能通过 RESTful 接口对外提供，但为了方便查看，作者在ecommerce-demo中写入了数据库对应的静态页面可供参考。

主要功能

• 供应商管理：管理供应商信息，包括信用评级、合作状态等
• 产品管理：管理摩托车零部件信息，包括分类、采购价格等
• 采购订单：管理采购订单的全流程，包括创建、审核、入库等
• 库存管理：管理库存，包括入库、出库、预警等功能
• 客户管理：管理客户信息，包括客户类型、折扣等级等
• 物流管理：管理物流信息，跟踪货物运输状态
• 统计分析：提供采购统计、库存预警等分析报表

技术栈

技术	版本	说明
Java	17+	项目要求 17，实测 JDK 25 可编译运行
Spring Boot	3.1.10
MyBatis Plus	3.5.3.1	ORM 框架
MySQL	8.0	mysql-connector-j 8.0.33
Lombok	1.18.46	需 ≥1.18.42 以支持 JDK 25 编译
springdoc-openapi	2.0.2	Swagger UI 接口文档

快速开始

环境要求

• JDK 17 或更高版本（JDK 25 已验证可用）
• MySQL 8.0+（本地服务已启动）
• Maven 3.6+

数据库配置

1. 数据库可自动创建：JDBC 连接已配置 createDatabaseIfNotExist=true，数据库不存在时 MySQL 驱动会自动创建（需要连接账号有建库权限，如 root）。也可以手动创建：

CREATE DATABASE motorparts_db CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;

2. 从示例创建本地配置文件：

# Windows PowerShell
Copy-Item src/main/resources/application.example.yml src/main/resources/application.yml

Linux 或 macOS：

cp src/main/resources/application.example.yml src/main/resources/application.yml

3. 打开 src/main/resources/application.yml，填写本机的 MySQL 地址、用户名和密码。真实的 application.yml 已被 .gitignore 忽略，请勿强制提交；需要共享配置结构时，只修改 application.example.yml。

构建与运行

# 方式一：Maven 直接运行（开发调试用）
mvn spring-boot:run

# 方式二：打包后运行
mvn clean package
java -jar target/MotorcyclePartsProcurementSystem-1.0.0.jar

首次启动会自动创建 8 张数据表并插入模拟数据，启动完成后控制台会打印：

==========================================
摩托车零部件采购管理系统启动成功！
系统访问地址: http://localhost:8080
API文档地址: http://localhost:8080/swagger-ui.html
==========================================

访问地址

• API 基础路径：http://localhost:8080/api
• Swagger 接口文档：http://localhost:8080/swagger-ui.html（自动跳转到 /swagger-ui/index.html）
• OpenAPI 描述文件：http://localhost:8080/v3/api-docs

注意：本项目是纯 API 服务，http://localhost:8080/ 无页面返回 404，接口文档以 Swagger UI 为准。

项目结构

src/main/java/com/motorparts/
├── MotorpartsApplication.java          # 启动类
├── config/                              # 配置类
│   ├── MyBatisPlusConfig.java           # MyBatis Plus（SqlSessionFactory、自动填充、事务）
│   ├── WebMvcConfig.java                # Web MVC（CORS 跨域已全放开）
│   ├── SwaggerConfig.java               # OpenAPI 文档配置
│   └── DdlApplicationRunnerConfig.java
├── controller/                          # 控制器层
│   ├── SupplierController.java          # /api/suppliers
│   ├── PartController.java              # /api/parts
│   ├── PurchaseOrderController.java     # /api/orders
│   ├── InventoryController.java         # /api/inventory
│   ├── CustomerController.java          # /api/customers
│   ├── LogisticsController.java         # /api/logistics
│   └── StatisticsController.java        # /api/statistics
├── service/                              # 服务层
│   └── impl/                             # 实现类
├── mapper/                               # Mapper接口
├── entity/                               # 实体类
├── dto/                                  # 数据传输对象
├── common/                               # 通用类（Result、PageResult、枚举、异常）
└── init/                                 # 数据初始化
    ├── DatabaseInitializer.java         # 启动时自动建表 + 插入模拟数据
    └── SparkPlugDataInitializer.java    # 独立工具：通过 API 批量创建火花塞数据（需手动运行 main 方法）

数据初始化

项目启动时会自动执行数据初始化（DatabaseInitializer），包括：

• 创建数据库表结构（8 张表：user、supplier、part、purchase_order、order_detail、inventory、customer、logistics）
• 插入模拟数据（12 用户、30 供应商、64 零部件、120 采购订单、40 客户、64 库存、79+ 物流记录）

初始化配置

在 application.yml 中配置：

motorparts:
  init:
    enabled: true            # 是否启用数据初始化
    insert-sample-data: true # 是否插入模拟数据

初始化机制说明

• 幂等性：插入模拟数据前会检查 user 表是否已有数据，已有则跳过（不会重复插入）
• 重新初始化：清空全部表数据（或 DROP 表/库）后重启应用即可，不要只清部分表，否则会跳过插入
• 数据库自动创建：连接参数 createDatabaseIfNotExist=true 会在库不存在时自动建库（需账号有建库权限）

API 接口测试

使用 Swagger UI 测试

1. 启动项目后访问：http://localhost:8080/swagger-ui.html
2. 在页面上可以看到所有 API 接口（7 个模块、54 个接口）
3. 点击任意接口可以查看详情和测试

使用 Postman / curl 测试

基础 URL：http://localhost:8080/api

创建供应商

POST http://localhost:8080/api/suppliers/create
Content-Type: application/json

{
  "supplierCode": "SUP00031",
  "name": "测试供应商",
  "contactPerson": "张三",
  "phone": "13800138000",
  "email": "test@example.com",
  "address": "上海市某区某路1号",
  "creditRating": "A",
  "status": 1
}

分页查询

GET http://localhost:8080/api/suppliers/page?current=1&size=10

搜索供应商（注意：参数名是 name，不是 keyword）

GET http://localhost:8080/api/suppliers/search?name=博世

统一响应格式

{
  "code": 200,
  "message": "操作成功",
  "data": { },
  "timestamp": 1746508800000
}

code 为 200 表示成功；601 数据已存在、602 数据不存在、603 库存不足、604 订单状态异常、605 供应商状态异常。

完整接口说明见 API接口文档。

已知问题与注意事项

以下为从他人处接手本项目的实测记录，对接接口前请先了解：

1. 创建采购订单必须传单价：POST /api/orders/create 的每个明细必须显式传 unitPrice，系统不会自动从零部件表带出采购价；不传时单价和订单总额都会是 0。

2. 统计接口时间参数：GET /api/statistics/monthly-trend 的参数名是 startDateParam / endDateParam（格式 yyyy-MM-dd），默认查询最近 6 个月；由于模拟订单数据都在 2024-2025 年，不传参数会返回空数组。

3. 模拟数据时间范围：订单、库存等模拟数据的时间集中在 2024-2025 年，2026 年（当前年份）的数据需要自行创建。

4. CORS 已全放开：允许任意来源、任意方法（GET/POST/PUT/DELETE/PATCH/OPTIONS）、携带凭证，前端项目可直接跨域调用。

数据库设计

表结构

表名	说明	关联关系
supplier	供应商表	-
part	产品/零部件表	supplier_id -> supplier
purchase_order	采购订单表	supplier_id -> supplier, created_by -> user
order_detail	订单明细表	order_id -> purchase_order, part_id -> part
inventory	库存表	part_id -> part
customer	客户表	-
user	用户表	-
logistics	物流表	order_id -> purchase_order

主要字段

• 所有表都包含 deleted（逻辑删除）、create_time、update_time 字段
• 金额字段使用 DECIMAL 类型确保精度
• 时间字段使用 DATETIME 类型

默认用户

用户名	密码	角色	部门
admin	admin123	管理员	财务部
user1	admin123	采购员	采购部
user2	admin123	仓管员	仓储部
user3	admin123	销售员	销售部

说明：当前版本未实现登录/认证接口，用户数据为初始化预留，密码已加密存储。

文档

• API接口文档
• 数据库表结构
• 数据来源说明

许可证

本项目仅供学习和参考使用。