# vmi **Repository Path**: 94living/vmi ## Basic Information - **Project Name**: vmi - **Description**: 虚拟仓管理系统是一款专注于库存全生命周期管理的轻量化系统,核心支持自有库存管理、供应商虚拟库存管理、零库存订单处理、出入库单据追溯等功能,适用于电商、仓储、供应链等场景,帮助用户实现库存可视化、操作可追溯、流程规范化。 - **Primary Language**: Python - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2025-10-23 - **Last Updated**: 2026-04-24 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 虚拟仓管理系统 - 帮助文档 ## 一、系统概述 ### 1.1 系统简介 虚拟仓管理系统是一款专注于**库存全生命周期管理**的轻量化系统,核心支持自有库存管理、供应商虚拟库存管理、零库存订单处理、出入库单据追溯等功能,适用于电商、仓储、供应链等场景,帮助用户实现库存可视化、操作可追溯、流程规范化。 ### 1.2 核心功能 - 自有库存管理:入库、出库、库存查询与筛选 - 供应商管理:供应商添加、编辑、删除及状态管理 - 0库存管理:虚拟库存同步、库存预警、零库存订单创建 - 出入库单据:单据生成、详情查询、历史记录筛选 - 库存转移:虚拟库存转自有库存及转移记录追溯 - 操作记录:虚拟库存同步日志、零库存订单状态跟踪 ### 1.3 技术环境 - 运行环境:Python 3.8+ - 依赖框架:Flask 2.3.3 - 数据库:支持SQLite(开发环境)和PostgreSQL(生产环境) - 缓存:Redis 6+ - 部署支持:Docker容器化、Gunicorn、Nginx - 浏览器支持:Chrome、Firefox、Edge(最新版本) - 访问地址:`http://localhost:5000`(本地部署) ### 1.3.1 系统架构优化 本次更新对系统架构进行了全面优化: - **统一日志管理**:实现集中式日志配置,支持多级别日志记录和自定义输出 - **ORM模型重构**:基于抽象基类的ORM实现,简化数据库操作,提高代码复用性 - **错误处理机制**:全局异常捕获和统一响应格式,增强系统稳定性 - **性能优化**:分页查询、Redis缓存、查询优化等,提升大数据量处理能力 - **容器化支持**:提供Docker配置,支持快速部署和环境一致性 ### 1.4 测试账号 - 用户名:`admin` - 密码:`123456` ### 1.5 新增核心能力 本次更新新增 **用户管理、权限鉴权、操作日志** 三大核心能力,强化系统安全性和可审计性: - 用户管理:支持多用户创建、角色分配(管理员/操作员),实现精细化权限控制; - 登录鉴权:基于会话的身份验证,未登录用户禁止访问核心功能,不同角色权限隔离; - 操作日志:记录关键操作(登录、库存变动、用户管理等),支持问题追溯和行为审计。 ### 1.6 部署与开发参考 - **部署指南**:详细的安装、配置和部署步骤请参考 [DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md) - **开发环境**:支持Docker容器化开发和传统本地开发两种方式 - **测试框架**:内置单元测试和集成测试,使用pytest框架 ## 二、快速入门 ### 2.1 系统登录 1. 打开浏览器,输入地址 `http://localhost:5000`,自动跳转至登录页; 2. 输入测试账号(admin/123456),点击「登录」按钮,进入系统主页(自有库存页面); 3. 登录失败提示「账号密码错误」时,检查用户名和密码是否正确(默认账号不可删除)。 ### 2.2 导航栏说明 登录后顶部导航栏包含所有功能入口,点击对应按钮可切换页面: | 导航项 | 功能说明 | |----------------|--------------------------------------------| | 自有库存 | 管理企业自有库存(入库、出库、查询) | | 0库存管理 | 处理供应商虚拟库存(同步、订单创建) | | 供应商管理 | 维护供应商信息(添加、编辑、删除) | | 出入库单据 | 查看所有入库/出库单据及详情 | | 转移记录 | 查询虚拟库存转自有库存的历史记录 | | 同步记录 | 追溯虚拟库存同步的操作日志 | | 零库存订单 | 管理零库存订单(状态更新、筛选查询) | | 退出 | 返回登录页(清除当前登录状态) | ### 2.3 权限与角色说明 登录后系统根据用户角色展示不同功能入口,核心权限差异如下: | 角色 | 权限范围 | 可见导航项 | |--------------|--------------------------------------------------------------------------|----------------------------------------------------------------------------| | 管理员(admin) | 全功能访问,含用户管理、系统所有业务操作及日志查看 | 所有导航项(含「用户管理」入口) | | 操作员(operator) | 仅可执行业务操作(库存管理、供应商管理、订单处理等),无用户管理权限 | 除「用户管理」外的所有导航项 | ### 2.4 会话管理说明 - 登录成功后系统自动创建会话,支持「保持登录状态」(关闭浏览器后重新打开仍可保持登录); - 未登录用户访问任何核心页面(如自有库存、供应商管理)时,自动跳转至登录页; - 点击「退出」按钮可立即清除会话,返回登录页(建议公共设备使用后强制退出)。 ## 三、功能模块详细操作 ### 3.1 自有库存管理 #### 功能介绍 支持自有库存的入库新增、出库扣减、多条件筛选查询,实时展示库存数量、仓库位置及更新时间。 #### 3.1.1 库存查询与筛选 1. 点击导航栏「自有库存」进入页面; 2. 筛选条件: - 商品名称搜索:输入商品名称关键词,点击「搜索」; - 仓库筛选:下拉选择「华东仓」「华南仓」或「所有仓」; 3. 表格展示字段:商品ID、名称、数量、仓库、类型(默认「自有库存」)、更新时间。 #### 3.1.2 商品入库 1. 点击页面右上角「入库」按钮,打开入库弹窗; 2. 填写表单(带「*」为必填项): - 商品ID:输入唯一标识(如 PROD-003); - 商品名称:输入商品全称(如 冰箱); - 数量:输入正整数(最小1); - 仓库:下拉选择入库仓库(华东仓/华南仓); 3. 点击「确认入库」,提示「入库成功」并显示单据编号,自动刷新库存列表; 4. 入库成功后可在「出入库单据」页面查看详情。 #### 3.1.3 商品出库 1. 点击页面右上角「出库」按钮,打开出库弹窗; 2. 填写表单: - 商品ID:输入已存在的商品ID; - 数量:输入需出库的正整数(不可超过当前库存); - 仓库:选择商品所在仓库; 3. 点击「确认出库」,提示「出库成功」并显示单据编号; 4. 若提示「库存不足」,需减少出库数量或先执行入库操作。 ### 3.2 供应商管理 #### 功能介绍 维护供应商基础信息,支持添加、编辑、删除操作,同时管理供应商连接状态(已连接/已断开),删除供应商时会**级联删除关联的虚拟库存**(避免数据残留)。 #### 3.2.1 查看供应商列表 1. 点击导航栏「供应商管理」进入页面; 2. 表格展示字段:供应商ID、名称、联系人、电话、状态(已连接/已断开)、操作按钮。 #### 3.2.2 添加供应商 1. 点击页面右上角「添加供应商」按钮,打开添加弹窗; 2. 填写表单(带「*」为必填项): - 供应商名称:输入唯一名称(不可重复); - 联系人:输入对接人姓名; - 电话:输入联系电话; - 状态:默认「已连接」,可选择「已断开」; 3. 点击「确认添加」,提示「供应商添加成功」,列表自动刷新; 4. 若提示「供应商名称已存在」,需修改名称后重新提交。 #### 3.2.3 编辑供应商 1. 找到目标供应商,点击操作列「编辑」按钮,打开编辑弹窗; 2. 修改表单信息(名称可修改,需避免与其他供应商重复); 3. 点击「确认更新」,提示「供应商更新成功」,列表实时更新。 #### 3.2.4 删除供应商 1. 找到目标供应商,点击操作列「删除」按钮; 2. 弹出确认提示「确定要删除该供应商吗?关联的虚拟库存也会被删除!」,点击「确定」; 3. 提示「供应商删除成功」,列表自动移除该供应商及关联数据。 ### 3.3 0库存管理(核心功能) #### 功能介绍 管理供应商虚拟库存,支持库存同步、库存预警、零库存订单创建,解决「无自有库存但需接单发货」的场景。 #### 3.3.1 虚拟库存查询 1. 点击导航栏「0库存管理」进入页面; 2. 筛选条件: - 供应商筛选:下拉选择特定供应商或「所有供应商」; - 商品名称搜索:输入商品名称关键词,点击「搜索」; 3. 表格展示字段:供应商名称、商品ID、名称、虚拟库存数量、补货阈值、状态(正常/预警)、更新时间; - 状态说明:虚拟库存 < 补货阈值 → 「预警」(红色徽章);反之 → 「正常」(绿色徽章)。 #### 3.3.2 同步虚拟库存 1. 点击页面右上角「同步虚拟库存」按钮,打开同步弹窗; 2. 填写表单: - 供应商:下拉选择目标供应商; - 商品ID:输入商品唯一标识; - 商品名称:输入商品全称; - 虚拟库存数量:输入非负整数(可大于当前库存,支持库存上调/下调); 3. 点击「确认同步」,提示「虚拟库存同步成功」,并显示同步前后数量变化; 4. 同步记录可在「同步记录」页面查看。 #### 3.3.3 创建零库存订单 1. 点击页面右上角「创建零库存订单」按钮,打开订单弹窗; 2. 填写表单: - 供应商:下拉选择目标供应商; - 商品ID:输入已同步虚拟库存的商品ID; - 订单数量:输入正整数(不可超过该商品虚拟库存数量); 3. 点击「创建订单」,提示「零库存订单创建成功」并显示订单号; 4. 订单创建后,虚拟库存自动扣减,可在「零库存订单」页面跟踪状态。 ### 3.4 出入库单据管理 #### 功能介绍 记录所有入库/出库操作的单据,支持单据筛选、详情查看,实现操作可追溯。 #### 3.4.1 单据筛选查询 1. 点击导航栏「出入库单据」进入页面; 2. 筛选条件: - 单据类型:下拉选择「入库单」「出库单」或「所有类型」; - 仓库筛选:下拉选择「华东仓」「华南仓」或「所有仓库」; 3. 点击「查询」,表格展示匹配的单据列表,字段包括:单据编号、类型、仓库、操作人、创建时间、状态(默认「已完成」)。 #### 3.4.2 查看单据详情 1. 找到目标单据,点击操作列「查看详情」按钮,进入单据详情页; 2. 详情页展示: - 单据基本信息:单据编号、类型、仓库、操作人、创建时间、状态; - 商品明细:商品ID、商品名称、数量; 3. 点击「返回列表」可回到单据列表页。 ### 3.5 库存转移管理 #### 功能介绍 支持「供应商虚拟库存 → 自有库存」的转移操作,同时记录转移历史,确保库存流转可追溯。 #### 3.5.1 发起库存转移 1. 点击导航栏「转移记录」进入页面; 2. 点击「发起转移」按钮,打开转移弹窗; 3. 填写表单: - 供应商:下拉选择目标供应商; - 商品ID:输入已同步虚拟库存的商品ID; - 转移数量:输入正整数(不可超过虚拟库存数量); - 转入仓库:下拉选择「华东仓」或「华南仓」; 4. 点击「确认转移」,提示「虚拟库存转移成功」并显示转移单号和对应的入库单据号; 5. 转移成功后,虚拟库存自动扣减,自有库存同步增加,可在「自有库存」和「出入库单据」页面验证。 #### 3.5.2 转移记录查询 1. 筛选条件: - 供应商筛选:下拉选择特定供应商或「所有供应商」; - 商品ID搜索:输入商品ID关键词; 2. 点击「查询」,表格展示转移记录,字段包括:转移单号、供应商、商品ID、名称、数量、时间、状态(默认「已完成」)。 ### 3.6 同步记录管理 #### 功能介绍 追溯所有虚拟库存同步的操作日志,包括同步时间、供应商、商品、同步前后数量等,支持多条件筛选。 1. 点击导航栏「同步记录」进入页面; 2. 筛选条件: - 供应商筛选:下拉选择特定供应商或「所有供应商」; - 商品ID搜索:输入商品ID关键词; 3. 点击「查询」,表格展示同步记录,字段包括:同步时间、供应商、商品ID、名称、同步前数量、同步后数量、操作人。 ### 3.7 零库存订单管理 #### 功能介绍 管理所有零库存订单的全生命周期,支持订单筛选、状态更新(已创建→已发货→已完成/已取消)。 #### 3.7.1 订单筛选查询 1. 点击导航栏「零库存订单」进入页面; 2. 筛选条件: - 供应商筛选:下拉选择特定供应商或「所有供应商」; - 状态筛选:下拉选择「已创建」「已发货」「已完成」「已取消」或「所有状态」; 3. 点击「查询」,表格展示订单列表,字段包括:订单号、供应商、商品ID、名称、数量、创建时间、状态、操作按钮。 #### 3.7.2 更新订单状态 1. 找到目标订单,点击操作列「更新状态」按钮,打开状态弹窗; 2. 下拉选择目标状态(支持切换任意状态); 3. 点击「确认更新」,提示「订单状态更新成功」,列表实时刷新; - 状态说明: - 已创建:订单已生成,待供应商发货; - 已发货:供应商已发货,待入库; - 已完成:商品已转入自有库存,订单闭环; - 已取消:订单作废,虚拟库存自动恢复(需手动同步修正)。 ### 3.8 用户管理(新增模块) #### 功能介绍 用于管理系统用户账号,仅管理员可操作,支持用户创建、角色分配、信息编辑及删除,密码采用加密存储(SHA-256/scrypt算法),确保账号安全。 #### 3.8.1 访问权限 - 仅「管理员」角色可访问,操作员无此功能入口; - 入口:登录后通过导航栏「用户管理」进入(管理员专属导航项)。 #### 3.8.2 核心操作 ##### (1)查看用户列表 1. 进入「用户管理」页面,默认展示系统所有用户信息; 2. 表格展示字段:用户ID、用户名、角色(管理员/操作员)、创建时间、最后登录时间、操作按钮。 ##### (2)添加新用户 1. 点击页面右上角「添加用户」按钮,打开添加弹窗; 2. 填写表单(带「*」为必填项): - 用户名:输入唯一账号(不可重复,如 `operator01`); - 密码:输入至少6位字符(建议包含字母+数字,系统自动加密存储); - 角色:下拉选择「管理员」或「操作员」(谨慎分配管理员角色); 3. 点击「确认添加」,提示「用户添加成功」,列表自动刷新; 4. 若提示「用户名已存在」,需修改用户名后重新提交。 ##### (3)编辑用户信息 1. 找到目标用户,点击操作列「编辑」按钮,打开编辑弹窗; 2. 修改表单信息: - 用户名:可修改(需确保唯一); - 密码:留空则保持原密码,填写则更新为新密码(加密存储); - 角色:可切换「管理员」与「操作员」; 3. 点击「确认更新」,提示「用户更新成功」,列表实时同步修改结果。 ##### (4)删除用户 1. 找到目标用户,点击操作列「删除」按钮; 2. 弹出确认提示「确定要删除该用户吗?」,点击「确定」; 3. 系统限制:**不可删除当前登录的管理员账号**(避免误操作导致无法登录); 4. 提示「用户删除成功」,列表自动移除该用户(关联的操作日志不会删除,仅终止账号使用权限)。 ### 3.9 权限鉴权说明(补充) #### 功能介绍 系统通过「登录校验+角色校验」双重鉴权,确保核心功能仅授权用户可访问,未授权操作将被拦截。 #### 3.9.1 鉴权规则 1. 未登录拦截:所有 `/`、`/supplier`、`/stock/docs` 等核心路由,未登录时自动跳转至 `/login_page`; 2. 角色拦截:「用户管理」页面、用户CRUD接口仅允许管理员访问,操作员访问时提示「无权限访问(需管理员权限)」; 3. 接口鉴权:所有业务API(如 `/api/inventory/in`、`/api/supplier`)均需登录后调用,未登录或权限不足时返回401/403错误。 #### 3.9.2 常见鉴权问题处理 - 问题1:访问页面时提示「请先登录后再访问该页面」→ 解决方案:重新登录系统(会话已过期或未登录); - 问题2:点击「用户管理」提示无权限 → 解决方案:切换为管理员账号登录(当前账号为操作员角色); - 问题3:调用接口时返回「403 Forbidden」→ 解决方案:检查当前用户角色是否具备该操作权限(如操作员无法调用用户删除接口)。 ### 3.10 操作日志管理(新增模块) #### 功能介绍 系统自动记录关键操作行为,生成可追溯的日志记录,支持问题排查、操作审计和安全监控,日志文件按日期分割,保留30天历史数据。 #### 3.10.1 日志类型与内容 | 操作类型 | 记录内容 | 日志级别 | |------------------|--------------------------------------------------------------------------|----------| | 登录/退出 | 登录用户、登录时间、登录结果(成功/失败)、退出时间 | INFO/WARNING | | 用户管理操作 | 操作人、操作类型(添加/编辑/删除)、目标用户ID/用户名、操作结果 | INFO/ERROR | | 库存变动操作 | 操作人、变动类型(入库/出库/转移)、商品信息、数量、仓库、操作结果 | INFO/ERROR | | 订单/同步操作 | 操作人、操作类型(创建订单/同步库存)、关联编号(订单号/同步记录ID)、结果 | INFO/ERROR | | 系统错误 | 错误发生模块、错误信息、堆栈跟踪(便于开发排查) | ERROR | #### 3.10.2 日志查看方式 1. 日志文件位置:项目根目录下的 `logs` 文件夹; 2. 文件命名规则:按日期命名(如 `app_20251024.log`),每天凌晨自动分割新文件; 3. 查看工具:用记事本、VS Code等文本编辑器打开即可,推荐按「时间戳」或「关键字」搜索(如搜索用户名、商品ID); 4. 日志保留期:默认保留30天历史日志,超过30天的旧日志会自动清理(避免占用过多存储空间)。 #### 3.10.3 日志使用场景 - 问题追溯:如库存数量异常时,搜索商品ID可查看所有相关入库/出库/转移操作记录; - 安全审计:如发现非授权操作,可通过日志定位操作人、操作时间和具体行为; - 错误排查:系统报错时,查看ERROR级日志可获取详细堆栈信息,辅助开发修复问题。 ## 四、常见操作流程 ### 流程1:新增供应商→同步虚拟库存→创建零库存订单 1. 进入「供应商管理」→ 添加供应商(填写名称、联系人、电话); 2. 进入「0库存管理」→ 同步虚拟库存(选择新增供应商,填写商品信息和库存数量); 3. 进入「0库存管理」→ 创建零库存订单(选择供应商和商品,输入订单数量); 4. 进入「零库存订单」→ 更新订单状态(根据实际进度切换为「已发货」「已完成」)。 ### 流程2:虚拟库存→转移为自有库存→出库 1. 进入「转移记录」→ 发起转移(选择供应商、商品,输入数量和目标仓库); 2. 进入「自有库存」→ 确认库存已增加; 3. 进入「自有库存」→ 发起出库(选择商品、仓库和出库数量); 4. 进入「出入库单据」→ 查看出库单据详情。 ### 流程3:管理员新增操作员→分配权限→业务操作 1. 管理员登录系统,进入「用户管理」→ 点击「添加用户」; 2. 填写用户名(如 `operator02`)、密码(如 `op123456`),角色选择「操作员」,点击「确认添加」; 3. 用新增的操作员账号登录系统,验证仅显示业务功能入口(无「用户管理」); 4. 操作员执行库存管理、订单处理等业务操作(权限范围内); 5. 管理员可通过日志文件查看该操作员的所有操作记录。 ## 五、常见问题与解决方案 ### 1. 登录失败(提示「账号密码错误」) **解决方案**:检查用户名是否为「admin」,密码是否为「123456」(默认账号不可修改)。 ### 2. 页面无法打开(提示「TemplateNotFound: xxx.html」) **解决方案**: 1. 确认 `templates` 目录下存在对应HTML文件(如 `sync_logs.html`); 2. 检查文件名拼写是否正确(区分大小写,如 `Supplier.html` 与 `supplier.html` 不同)。 ### 3. 数据库表不存在(提示「sqlite3.OperationalError: no such table: xxx」) **解决方案**: 1. 删除项目根目录下的 `database.db` 文件; 2. 重新运行 `python run.py`,系统会自动初始化数据库表。 ### 4. 库存不足无法操作(提示「库存不足」) **解决方案**: - 出库:先执行入库操作增加自有库存; - 零库存订单/转移:先同步虚拟库存(增加虚拟库存数量)。 ### 5. 参数错误(提示「缺少参数」「数量必须是数字」) **解决方案**: 1. 检查表单是否填写完整(带「*」为必填项); 2. 数量字段需输入正整数(不可为负数、小数或文字)。 ### 6. 供应商名称重复(提示「供应商名称已存在」) **解决方案**:修改供应商名称,确保名称唯一(系统不允许重复供应商名称)。 ### 7. 无权限访问用户管理页面 - 问题:点击「用户管理」提示「无权限访问(需管理员权限)」; - 解决方案:确认当前登录账号角色为「admin」,若为操作员账号,切换至管理员账号登录。 ### 8. 无法删除用户 - 问题:点击删除用户时提示「不能删除当前登录用户」; - 解决方案:若需删除该管理员账号,先使用其他管理员账号登录,再执行删除操作(确保系统至少保留一个管理员账号)。 ### 9. 日志文件无内容或无法生成 - 问题:`logs` 文件夹未生成或日志文件为空; - 解决方案: 1. 确认项目根目录具备写入权限(Windows需右键「属性」开启写入权限,Linux需 `chmod 755` 授权); 2. 重启系统服务(`python run.py`),执行登录、库存操作等关键行为后,日志会自动生成; 3. 检查 `app/utils/log_config.py` 文件是否存在,确保日志配置代码未被修改。 ### 10. 登录后会话频繁过期 - 问题:登录后不久提示「会话过期,请重新登录」; - 解决方案: 1. 检查 `app/__init__.py` 中的 `SECRET_KEY` 是否配置(需替换为随机密钥,不可用占位符); 2. 清除浏览器缓存和Cookie后重新登录; 3. 避免同时在多个浏览器/设备登录同一账号(可能导致会话冲突)。 ## 六、注意事项 1. 数据库文件:`database.db` 存储所有系统数据,删除后会丢失所有记录(测试环境可删除重建,生产环境需备份); 2. 操作权限:当前系统仅支持管理员账号(admin),无多角色权限控制; 3. 数据一致性:删除供应商会级联删除关联的虚拟库存,操作前请确认数据无保留需求; 4. 特殊字符:商品名称、仓库名称等字段支持中文,但避免输入 `&` `#` 等特殊字符(可能导致URL解析错误); 5. 系统重启:修改后端代码后需重启 `run.py` 才能生效。 6. 用户密码安全:系统采用加密存储密码,管理员不可查看用户明文密码,仅可通过「编辑用户」功能重置密码; 7. 角色分配谨慎:管理员角色具备全权限,建议仅分配给系统管理员,普通业务人员使用「操作员」角色; 8. 日志隐私保护:日志文件包含用户操作行为和业务数据,需限制 `logs` 文件夹访问权限(避免未授权查看); 9. 敏感信息过滤:日志中自动过滤密码、Token等敏感数据,仅记录必要的操作标识(如用户名、商品ID),确保数据安全。