说明文档 - 库存管理系统 V3.3

1. 项目概述

1.1 项目简介

库存管理系统（Warehouse Management System，简称 WMS）V3.3 是一款基于 Python + PyQt5 开发的桌面端库存管理软件，面向中小型仓库和物料管理场景。系统提供物料信息管理、出入库操作、图片管理、Excel 批量导入导出、操作日志追踪等核心功能，操作简单直观，数据存储于本地 SQLite 数据库，无需联网即可使用。

1.2 开发背景

在日常仓库管理中，许多中小企业仍依赖纸质台账或简单的 Excel 表格进行库存管理，存在数据易丢失、查询不便、操作记录难以追溯等问题。本系统旨在提供一套轻量、可靠、功能完备的数字化库存管理方案，帮助用户高效管理物料信息和出入库流程。

1.3 核心特性

物料全生命周期管理：新增、编辑、删除、详情查看
多图支持：每个物料可关联多张图片，支持剪贴板粘贴快速录入
智能出入库：自动计算库存数量和金额，支持出入库记录编辑
编号级联更新：修改物料编号时自动同步所有关联记录
Excel 批量导入：多线程导入，支持进度展示和冲突处理
操作日志追踪：完整记录所有修改、出入库操作
离线可用：数据存储于本地 SQLite，无需网络连接

2. 环境与依赖

2.1 运行环境

项目	要求
操作系统	Windows 7 及以上
Python 版本	3.8 及以上
磁盘空间	≥ 100 MB（含数据库和图片存储）

2.2 第三方依赖

库名	版本	用途
`PyQt5`	5.15.9	GUI 框架
`pandas`	2.1.4	Excel 数据处理
`openpyxl`	3.1.2	Excel 文件读写
`Pillow`	10.0.0	图片处理与缩放
`sqlite3`	内置	数据库引擎

2.3 打包工具

使用 PyInstaller 将 Python 脚本打包为独立的 Windows 可执行文件（.exe），用户无需安装 Python 环境即可运行。

3. 系统架构设计

3.1 三层架构

系统采用经典的三层架构设计，各层职责明确，耦合度低：

层次	目录	职责
View 层（视图层）	`view/`	用户界面展示与交互，12 个文件
Core 层（业务逻辑层）	`core/`	业务逻辑处理与服务，6 个文件
Database 层（数据访问层）	`database.py`	数据库连接与 CRUD 操作

3.2 模块依赖关系

View 层调用 Core 层提供的 Service 接口，Core 层通过 Database 层操作数据。三层之间的调用关系为单向依赖：View → Core → Database，不存在反向调用或循环依赖。

3.3 信号槽通信

系统大量使用 PyQt5 的信号槽（Signal/Slot）机制实现模块间通信：

数据变更通知：物料增删改后发出信号，主界面自动刷新列表
多线程通信：Excel 导入线程通过信号向主界面报告进度和结果
跨窗口通信：对话框操作完成后通知父窗口更新数据

4. 数据库设计

4.1 概述

系统使用 SQLite3 作为数据库引擎，共包含 5 张数据表。数据库文件默认存储在程序运行目录下，首次启动时自动创建。

4.2 数据表结构

4.2.1 物料主表（materials）

字段名	类型	约束	说明
`id`	INTEGER	PRIMARY KEY AUTOINCREMENT	主键
`material_id`	TEXT	NOT NULL UNIQUE	物料编号（唯一标识）
`name`	TEXT	NOT NULL	物料名称
`type_id`	INTEGER	FOREIGN KEY	物料类型ID，关联 material_types
`spec`	TEXT		规格型号
`unit`	TEXT		计量单位
`quantity`	INTEGER	DEFAULT 0	当前库存数量
`unit_price`	REAL	DEFAULT 0.0	单价
`total_price`	REAL	DEFAULT 0.0	总金额
`location`	TEXT		存放位置
`remark`	TEXT		备注
`image_path`	TEXT		旧版单图路径（兼容字段）
`image_paths`	TEXT		新版多图路径（JSON 数组）
`created_at`	TEXT		创建时间
`updated_at`	TEXT		更新时间

多图兼容设计

image_path 为旧版单图字段，image_paths 为新版 JSON 数组字段。系统读取时优先使用 image_paths，若为空则回退读取 image_path，确保新旧数据兼容。

4.2.2 物料类型表（material_types）

字段名	类型	约束	说明
`id`	INTEGER	PRIMARY KEY AUTOINCREMENT	主键
`name`	TEXT	NOT NULL UNIQUE	类型名称

系统预置 6 种默认物料类型：电子元件、机械零件、原材料、成品、半成品、其他。

4.2.3 入库记录表（inbound_logs）

字段名	类型	约束	说明
`id`	INTEGER	PRIMARY KEY AUTOINCREMENT	主键
`material_id`	TEXT	NOT NULL	物料编号
`material_name`	TEXT		物料名称（冗余存储）
`quantity`	INTEGER		入库数量
`unit_price`	REAL		入库单价
`total_price`	REAL		入库总金额
`operator`	TEXT		操作人
`inbound_date`	TEXT		入库日期
`remark`	TEXT		备注

4.2.4 出库记录表（outbound_logs）

字段名	类型	约束	说明
`id`	INTEGER	PRIMARY KEY AUTOINCREMENT	主键
`material_id`	TEXT	NOT NULL	物料编号
`material_name`	TEXT		物料名称
`quantity`	INTEGER		出库数量
`unit_price`	REAL		出库单价
`total_price`	REAL		出库总金额
`operator`	TEXT		操作人
`outbound_date`	TEXT		出库日期
`remark`	TEXT		备注

4.2.5 修改日志表（modification_logs）

字段名	类型	约束	说明
`id`	INTEGER	PRIMARY KEY AUTOINCREMENT	主键
`material_id`	TEXT	NOT NULL	物料编号
`material_name`	TEXT		物料名称
`field_name`	TEXT		修改字段名
`old_value`	TEXT		修改前的值
`new_value`	TEXT		修改后的值
`modified_at`	TEXT		修改时间
`operator`	TEXT		操作人

5. 核心模块详解

5.1 Database 数据访问层（database.py）

采用单例模式管理数据库连接，确保全局只有一个 SQLite 连接实例。提供统一的 CRUD 操作接口，包括：

数据库初始化：创建表结构、插入默认物料类型、处理旧版数据库兼容迁移
物料 CRUD：增删改查物料记录，支持多条件搜索和分页
出入库 CRUD：出入库记录的增删改查
修改日志：记录物料字段级别的变更
统计查询：库存汇总、出入库统计等

5.2 InventoryService 库存服务（core/inventory_service.py）

核心业务逻辑层，提供以下关键功能：

物料管理：新增物料、编辑物料信息、删除物料
出入库操作：入库（增加库存数量和金额）、出库（扣减库存数量和金额，含库存不足校验）
编号级联更新：修改物料编号时的 5 步事务流程
数据导出：将物料列表导出为 Excel 文件

编号级联更新 5 步流程

更新物料主表中的 material_id
更新入库记录表中所有关联的 material_id
更新出库记录表中所有关联的 material_id
更新修改日志表中所有关联的 material_id
以上步骤在同一个数据库事务中执行，任一步失败则全部回滚

5.3 ExcelService Excel 服务（core/excel_service.py）

负责 Excel 文件的导入导出功能：

多线程导入：使用 QThread 在后台线程执行 Excel 数据导入，避免阻塞主界面
进度报告：通过信号槽实时报告导入进度
冲突处理：检测编号冲突，提供跳过或覆盖策略
数据校验：导入前校验数据格式和必填字段

5.4 ImageService 图片服务（core/image_service.py）

管理物料图片的存储和加载：

多图支持：使用 JSON 数组存储多个图片路径
图片压缩：自动压缩大图，平衡画质与存储空间
格式转换：支持常见图片格式的统一处理
旧数据迁移：自动将旧版单图数据迁移为多图格式

5.5 MaterialTypeService 物料类型服务（core/material_type_service.py）

管理物料类型的增删改查，维护类型列表的展示顺序和默认类型。

5.6 ClipboardImageHandler 剪贴板图片处理（core/clipboard_image_handler.py）

监听系统剪贴板，支持从剪贴板直接粘贴图片到物料详情，提升图片录入效率。

6. 视图模块详解

6.1 主界面（view/inventory_view.py）

系统的核心视图，采用左侧列表 + 右侧详情的经典布局：

顶部工具栏：搜索框、新增/编辑/删除按钮、导入/导出按钮、设置按钮
左侧列表：物料列表，支持按类型筛选和关键词搜索
右侧详情：选中物料的详细信息展示，包含多图轮播

6.2 入库对话框（view/inbound_dialog.py）

入库操作表单，包含物料选择、入库数量、单价、操作人、日期、备注等字段，提交后自动更新库存数量和金额。

6.3 出库对话框（view/outbound_dialog.py）

出库操作表单，类似入库对话框，但提交时会校验库存数量是否充足，不足时给出提示。

6.4 物料详情对话框（view/material_detail_dialog.py）

以多标签页形式展示物料完整信息：

基本信息：编号、名称、类型、规格、单位、库存等
图片：多图展示，支持缩略图点击放大
入库记录：该物料的所有入库历史
出库记录：该物料的所有出库历史
修改日志：该物料的所有变更记录

6.5 编辑物料对话框（view/edit_material_dialog.py）

新增或编辑物料的表单对话框，包含所有物料字段的输入控件，以及图片上传功能。

6.6 编辑入库/出库对话框（view/edit_inbound_dialog.py / edit_outbound_dialog.py）

编辑已有的出入库记录，修改后自动重新计算库存数量和金额。

6.7 Excel 导入对话框（view/excel_import_dialog.py）

Excel 批量导入的工作流界面：

选择 Excel 文件
预览导入数据
配置映射关系和冲突策略
执行导入并显示进度
导入结果汇总

6.8 设置对话框（view/settings_dialog.py）

系统设置界面，可配置数据库路径、图片存储路径、操作人名称等参数。

6.9 修改日志视图（view/modification_logs_view.py）

全局修改日志查看界面，支持按时间范围、物料编号等条件筛选。

6.10 使用指南对话框（view/guide_dialog.py）

首次使用时的引导教程，介绍系统基本操作流程。

6.11 图片查看器（view/image_viewer_dialog.py）

全屏图片查看器，支持缩放和拖拽操作。

6.12 可粘贴图片标签（view/image_label_with_paste.py）

自定义 QLabel 控件，支持 Ctrl+V 粘贴剪贴板图片，快速录入物料图片。

7. 功能操作说明

7.1 物料管理

新增物料：点击工具栏"新增"按钮，填写物料信息并上传图片，保存后自动添加到列表
编辑物料：选中物料后点击"编辑"按钮，修改信息后保存；若修改了编号，系统自动级联更新所有关联记录
删除物料：选中物料后点击"删除"按钮，确认后删除物料及其所有出入库记录
查看详情：双击物料或点击"详情"按钮，打开多标签页详情对话框
搜索筛选：在搜索框输入关键词实时过滤，或通过类型下拉框筛选

7.2 入库操作

点击"入库"按钮打开入库对话框
选择或输入物料编号，填写入库数量和单价
填写操作人、入库日期和备注（可选）
确认提交后，系统自动增加库存数量和金额

7.3 出库操作

点击"出库"按钮打开出库对话框
选择物料，填写出库数量
系统自动校验库存是否充足，不足时弹出提示
确认提交后，系统自动扣减库存数量和金额

7.4 图片管理

上传图片：在编辑物料对话框中点击图片区域，选择本地图片文件
粘贴图片：在支持粘贴的图片区域按 Ctrl+V，直接从剪贴板粘贴
查看大图：点击缩略图打开全屏图片查看器
删除图片：在编辑模式下删除不需要的图片

7.5 Excel 导入导出

导入：点击"导入"按钮，选择 Excel 文件，预览数据后配置映射和冲突策略，执行导入
导出：点击"导出"按钮，将当前物料列表导出为 Excel 文件

7.6 日志查看

通过菜单或工具栏打开修改日志视图，可按时间、物料编号等条件筛选查看所有操作记录。

8. 项目目录结构

WarehouseManager/ ├── main.py # 程序入口 ├── run.py # 启动脚本 ├── config.py # 配置管理 ├── database.py # 数据库访问层（单例） ├── build_exe.py # PyInstaller 打包脚本 ├── check_db.py # 数据库检查工具 ├── check_project.py # 项目完整性检查 ├── fix_database.py # 数据库修复工具 ├── migrate_material_types.py # 物料类型迁移脚本 ├── start_fixed.py # 修复启动脚本 ├── test_config.py # 配置测试 ├── core/ │ ├── __init__.py │ ├── constants.py # 全局常量定义 │ ├── inventory_service.py # 库存业务逻辑 │ ├── excel_service.py # Excel 导入导出服务 │ ├── image_service.py # 图片管理服务 │ ├── material_type_service.py # 物料类型服务 │ └── clipboard_image_handler.py # 剪贴板图片处理 └── view/ ├── __init__.py ├── inventory_view.py # 主界面 ├── inbound_dialog.py # 入库对话框 ├── outbound_dialog.py # 出库对话框 ├── material_detail_dialog.py # 物料详情对话框 ├── edit_material_dialog.py # 编辑物料对话框 ├── edit_inbound_dialog.py # 编辑入库记录 ├── edit_outbound_dialog.py # 编辑出库记录 ├── excel_import_dialog.py # Excel 导入对话框 ├── settings_dialog.py # 设置对话框 ├── modification_logs_view.py # 修改日志视图 ├── guide_dialog.py # 使用指南 ├── image_viewer_dialog.py # 图片查看器 └── image_label_with_paste.py # 可粘贴图片标签

9. 版本演进与关键设计

9.1 多图功能演进

系统从单图到多图的演进过程中，采用了新旧字段并存的兼容策略：

阶段	字段	存储方式
旧版（单图）	`image_path`	单个图片文件路径字符串
新版（多图）	`image_paths`	JSON 数组存储多个路径

读取时优先使用 image_paths，为空时回退读取 image_path，确保新旧数据平滑兼容。

9.2 编号级联更新策略

物料编号作为出入库记录和修改日志的关联键，修改编号时必须同步更新所有关联表。系统采用 5 步事务流程，在同一个数据库事务中完成所有更新，任一步失败则全部回滚，保证数据一致性。

9.3 事务保护机制

所有涉及多表操作的业务逻辑（入库、出库、编辑、编号修改等）均使用数据库事务保护：

操作开始时开启事务
所有 SQL 语句执行成功后提交事务
任一步执行失败则回滚整个事务，数据恢复到操作前状态

10. 部署与运行

10.1 源码运行

# 1. 克隆项目
git clone <repository_url>
cd WarehouseManager

# 2. 安装依赖
pip install -r requirements.txt

# 3. 运行程序
python main.py

10.2 打包部署

# 使用 PyInstaller 打包为 exe
python build_exe.py

# 打包产物在 dist/ 目录下
# 双击 exe 即可运行，无需 Python 环境

10.3 数据库初始化

首次启动时，系统自动执行以下初始化操作：

在程序目录下创建 SQLite 数据库文件
创建 5 张数据表（若不存在）
插入 6 种默认物料类型
检测并迁移旧版数据库结构

11. 常见问题与排错

Q1：双击 exe 闪退，无法启动

可能是数据库文件损坏。尝试删除程序目录下的 .db 文件，重新启动程序让系统自动创建新数据库。

Q2：Excel 导入失败

检查 Excel 文件格式是否为 .xlsx，确保表头字段名与系统要求的字段名一致。可先导出一份模板文件作为参考。

Q3：图片无法显示

确认图片文件未被移动或删除。系统存储的是图片的绝对路径，若图片文件位置变化则无法显示。

Q4：编号修改后关联记录未更新

正常情况下级联更新是事务保护的。若出现此问题，可能是数据库文件被外部工具修改导致事务中断。建议使用数据库修复工具检查。

Q5：出库时提示库存不足

检查当前物料的库存数量，确认是否有足够的库存。可查看该物料的出入库记录核实库存变动情况。

Q6：如何备份数据

复制程序目录下的 .db 数据库文件和 images/ 图片文件夹到安全位置即可。恢复时将文件复制回原位。

Q7：如何在多台电脑间同步数据

系统为单机版，不内置网络同步功能。建议使用云同步工具（如坚果云、OneDrive）同步数据库文件和图片文件夹。