物料入库 / 出库系统 (MaterialWMS)

本地 Web 物料管理系统，对标桌面 物料明细表.xlsx 的台账 + BOM 核算能力。 Flask + SQLite，免外部数据库，即开即用。库存由 SQL 实时聚合（在库 = 入库 − 出库）， 彻底规避原 Excel 的 [1]物料入库!D_ 外部链接断链风险。

配套文档：物料入库出库系统_使用教程.md（完整功能教程）、物料入库出库系统_用户使用说明.md（面向操作员的使用手册）。

---

一、运行方式

方式一 · 单文件 EXE（推荐车间用） dist/MaterialWMS.exe 双击即开，自动弹出浏览器到 http://127.0.0.1:8080。 库文件 app.db 自动生成在 exe 同目录，换机器直接拷贝 exe 即可。

方式二 · 源码（双击 bat） 双击 启动.bat 启动；或命令行 python app.py（库文件生成在 instance/app.db）。

方式三 · 指定库位置 set WMS_DB=D:/path/app.db 后再启动，可把数据放到任意位置。

默认账号：admin / admin123（首次启动自动建；可在「用户」页加 operator / manager）。

---

二、角色权限

角色	权限
admin	全部，含用户管理、工厂管理、替代料管理
manager	物料/BOM/订单/报表/日志/Excel 导入导出/调拨/替代料
operator	库存看板 / 物料查看 / 入库 / 出库

---

三、核心库存口径

• 在库 = Σ入库 − Σ出库，全部实时聚合，不在库里冗余存储。
• 厂间调拨：从源厂出库减 + 目标厂入库加，系统总库存不变（只搬库，不消耗）。
• 只有「出库 / 生产领料」会减少库存；入库、调入（调拨）只做加项或库间转移。
• 多工厂：factory 表区分归属（SELF=自厂/总部为默认厂）。顶栏「工厂」下拉切换后， 看板 / 物料 / 收发 / 流水全部按所选厂过滤；全部 显示跨厂汇总。

---

四、功能清单

模块	说明
库存看板	实时核算在库；低于安全库存标黄、库存为负标红，顶部统计负数/预警数。BOM 标签页可按 BOM 型号查看「单套用量 × 接单量」的需求与齐套情况，并提供「模拟齐套」试算
物料	主数据 CRUD（编号/型号/单位/安全库存）+ 搜索；物料详情页展示各厂在库与流水
入库	流水登记（批次/数量/经手人/来源/送货日期），写入即更新库存
出库	流水登记，库存不足自动拦截；支持按 BOM 领料、物料编码扫码/输入自动定位；选物料后实时提示可替代料及库存
批量导入窗口	入库/出库/物料/BOM 页「批量导入窗口」按钮弹出模态框：粘贴多行清单或上传 Excel/CSV，实时预览解析与校验，一键批量生成
BOM	BOM 型号 + 组成物料单套用量；支持上传真实 Altium / 嘉立创 BOM 模板（每个 worksheet 视为一个 BOM，sheet 名即 BOM 型号），或中文「组装」sheet；物料不存在的项导入时自动新建
生产订单	选 BOM + 接单量 → 自动展开「需求 = 单套用量 × 接单量」。支持编辑 / 删除（删除级联清除关联的领料出库与调入入库）；订单详情页可填写每个物料的「调入数量」并确认调入（厂间调拨）
厂间调拨	在厂之间转移物料：源厂出库减 + 目标厂入库加，总库存不变；调拨单双向流水自动对账，可在流水台账按「调拨」类型筛选
替代料关系	维护「主料 ↔ 替代料」对照（可 Excel 导入）；出库、BOM 领料、生产订单领料时，主料库存不足自动提示可用替代料及其库存
流水台账	入库 + 出库 按日期合并、折叠展示（默认展开最新一天，可全部展开/折叠）；支持业务类型筛选、单号搜索、按日期导出为同一个 Excel 文件
报表	库存报表页，支持浏览器打印与导出 Excel
操作日志	每次收发/BOM/订单/导入/用户操作全记录（谁/何时/做了什么）
工厂管理	admin/manager 增厂、停用/启用；SELF 为默认自厂
用户管理	admin 增删改角色、启停账号

---

五、Excel 模板字段速查

导入项	标准列（首行表头）
物料	物料编号、型号/规格、单位、安全库存（可选）、期初库存（可选）
入库	物料编号、数量、日期（可选）、批次（可选）、来源（可选）、经手人（可选）
出库	物料编号、数量、日期（可选）、用途（可选）、经手人（可选）
BOM	支持 Altium/嘉立创模板（Item / Part Number / Manufacture Part Number / Quantity / Reference / Part / Package），或中文「物料代码 + 数量」
替代料	「替代料」sheet：主料编号、替代料编号（可多行同一主料）

各页均有「下载模板」按钮可获取标准 Excel 模板。

---

六、目录结构

material_wms/
├─ app.py                 # 路由 + 鉴权 + 库存核算 + 冻结路径处理
├─ models.py              # SQLAlchemy 2.0 模型(user/material/inbound/outbound/
│                         #   bom/bom_item/prod_order/prod_order_alloc/factory/
│                         #   transfer/substitute/operation_log)
├─ excel_io.py            # Excel 双向导入导出 + 模板生成
├─ init_db.py             # 建表 + 管理员 + Excel 导入真实物料
├─ build_exe.py           # PyInstaller 单文件打包脚本(--distpath dist_pkg 避开安全删除钩子)
├─ requirements.txt       # flask / flask-sqlalchemy / sqlalchemy / openpyxl / pyinstaller
├─ 启动.bat
├─ templates/             # 登录/看板/物料/收发/BOM/订单/调拨/替代料/流水/报表/日志/用户/导入 共 22 个页面
├─ static/style.css
├─ tools/                 # e2e_test.py(全量冒烟) / check_*.py(各功能校验) / verify_*.py
├─ instance/app.db        # SQLite 库(源码模式自动生成, 已 gitignore)
└─ dist/MaterialWMS.exe   # 打包产物(单文件, 已 gitignore)

---

七、打包 EXE

python build_exe.py

产物在 dist/MaterialWMS.exe。冻结后模板/静态走 sys._MEIPASS，库文件落 exe 同目录。 构建脚本使用 --distpath dist_pkg 以避开某些环境的「安全删除」钩子，构建完成后再复制到 dist/。

---

八、测试

python tools/e2e_test.py

覆盖：登录 / 收发核算 / BOM / 订单展开 / 领料 / 日志 / 报表 / 导入导出 / 入库·物料·BOM 批量导入窗口 / 角色拦截 / 替代料提示 / 厂间调拨对账。

---

九、部署与数据备份

• 数据唯一真源为 dist/app.db（EXE 同目录）；搬 EXE 时务必把 app.db 一起带走。
• 更新 EXE 后务必结束旧进程（Windows：Stop-Process -Name MaterialWMS -Force）再重启， 否则浏览器连的是旧代码，会表现为「新功能点不了 / 没按钮」。
• 重大操作前复制 app.db 为 .bak 备份，可随时覆盖还原。