# 物料入库 / 出库系统 (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

```bat
python build_exe.py
```

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

---

## 八、测试

```bat
python tools/e2e_test.py
```

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

---

## 九、部署与数据备份

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