feat: 多工厂/厂间调拨/替代料/流水台账折叠 + 重写 README

- 多工厂(factory 表) + 顶栏工厂下拉过滤, 库存按厂聚合 - 厂间调拨(transfer): 源厂减+目标厂加, 总库存不变, 双向流水对账 - 替代料关系(substitute): 出库/BOM领料/生产领料缺料时提示可替代料 - 流水台账(ledger): 入出按日期合并折叠, 按日期导出同一 Excel - 生产订单增强: 编辑/删除(级联清关联流水)/调入数量/确认调入=厂间调拨 - 入库新增送货日期字段; 出库物料编码扫码定位 - 重写 README 补全全部模块; .gitignore 排除 dist_pkg/build_pkg/*.db - 停止跟踪 instance/app.db(运行时自动生成)
2026-09-29 11:17:48 +08:00
parent 33efc7c846
commit 5060d027e5
22 changed files with 1961 additions and 149 deletions
@@ -1,76 +1,131 @@
-# 物料入库 / 出库系统 (M1 + M2 + M3 完整版)
+# 物料入库 / 出库系统 (MaterialWMS)

-本地 Web 系统,对标桌面 `物料明细表.xlsx` 的台账 + BOM 核算能力。Flask + SQLite,免外部数据库,即开即用。
-库存由 SQL 实时聚合(在库 = 入库 − 出库),彻底规避原 Excel 的 `[1]物料入库!D_` 外部链接断链风险。
+本地 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`。
+## 一、运行方式
+
+**方式一 · 单文件 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` 后再启动,可把数据放到任意位置。
+`set WMS_DB=D:/path/app.db` 后再启动，可把数据放到任意位置。

-## 默认账号
- 管理员 `admin / admin123`(首次启动自动建;可在「用户」页加 operator / manager)
+默认账号：`admin / admin123`（首次启动自动建；可在「用户」页加 operator / manager）。
+
+---
+
+## 二、角色权限

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

-## 功能清单
+---
+
+## 三、核心库存口径
+
+- **在库 = Σ入库 − Σ出库**，全部实时聚合，不在库里冗余存储。
+- **厂间调拨**：从源厂出库减 + 目标厂入库加，**系统总库存不变**（只搬库，不消耗）。
+- **只有「出库 / 生产领料」会减少库存**；入库、调入（调拨）只做加项或库间转移。
+- **多工厂**：`factory` 表区分归属（`SELF`=自厂/总部为默认厂）。顶栏「工厂」下拉切换后，
+  看板 / 物料 / 收发 / 流水全部按所选厂过滤；`全部` 显示跨厂汇总。
+
+---
+
+## 四、功能清单
+
 | 模块 | 说明 |
 |---|---|
-| 库存看板 | 实时核算在库;低于安全库存标黄、库存为负标红,顶部统计负数/预警数 |
-| 物料 | 主数据 CRUD(编号/型号/单位/安全库存)+ 搜索 |
-| 入库 | 流水登记(批次/数量/经手人/来源),写入即更新库存 |
-| 出库 | 流水登记,**库存不足自动拦截** |
-| **批量导入窗口** | 入库/出库/物料/BOM 页「批量导入窗口」按钮弹出模态框:粘贴多行清单或上传 Excel/CSV,实时预览解析与校验,一键批量生成。各页格式见下 |
-| 入库/出库批量窗口 | 每行 `物料编号 数量 批次(可选) 日期(可选) 备注(可选)`,校验物料存在/数量>0/出库库存充足 |
-| 物料批量窗口 | 每行 `物料编号 型号/规格 单位 安全库存(可选) 期初库存(可选)`,校验重复编号;已存在编号显示「更新」,一键批量 upsert(含期初流水) |
-| BOM 批量窗口 | ① **上传真实 Altium / 嘉立创 BOM 模板**(`Item/Part Number/Manufacture Part Number/Quantity/Reference/Part/Package`):每个 worksheet 视为一个 BOM,sheet 名即 BOM 型号,Part Number 关联物料、Quantity 列即单套用量(若存在两个 Quantity 列,取首列,首列空时回退次列);也支持中文「组装」sheet(物料代码 + 数量)。② 粘贴文本:以 `#BOM <型号> <名称>` 分段、其下 `物料编号 单套用量`。物料不存在的项预览时标「新建」,**导入时自动新建物料**(并写入型号/规格),一键多 BOM 落库 |
-| **BOM(M2)** | BOM 型号 + 组成物料单套用量;支持 Excel 导入 |
-| **生产订单(M2)** | 选 BOM + 接单量 → 自动展开「需求 = 单套用量 × 接单量」,一键「确认领料」生成出库,缺料在看板预警 |
-| **Excel 双向(M2)** | 物料导入/导出、BOM 导入、库存报表导出、导入模板下载 |
-| **报表(M3)** | 库存报表页,支持打印(浏览器打印)与导出 Excel |
-| **操作日志(M3)** | 每次收发/BOM/订单/导入/用户操作全记录(谁/何时/做了什么) |
-| **用户管理(M3)** | admin 增删改角色、启停账号 |
+| **库存看板** | 实时核算在库；低于安全库存标黄、库存为负标红，顶部统计负数/预警数。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 增删改角色、启停账号 |

-## 数据来源
-`init_db.py` 已从桌面 `物料明细表.xlsx` 的「物料入库」表导入 **439 条真实物料**,
-把 Excel 库存数量作为"期初入库"写入,看板开箱即有数。
+---
+
+## 五、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/operation_log)
-├─ excel_io.py       # Excel 双向导入导出 + 模板生成
-├─ init_db.py        # 建表 + 管理员 + Excel 导入真实物料
-├─ build_exe.py      # PyInstaller 单文件打包脚本
-├─ requirements.txt
+├─ 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/订单/报表/日志/用户/导入 共 15 个页面
+├─ templates/             # 登录/看板/物料/收发/BOM/订单/调拨/替代料/流水/报表/日志/用户/导入 共 22 个页面
 ├─ static/style.css
-├─ instance/app.db   # SQLite 库(源码模式自动生成)
-├─ dist/MaterialWMS.exe  # 打包产物(单文件)
-└─ tools/            # e2e_test.py(全量冒烟) / check_server.py
+├─ tools/                 # e2e_test.py(全量冒烟) / check_*.py(各功能校验) / verify_*.py
+├─ instance/app.db        # SQLite 库(源码模式自动生成, 已 gitignore)
+└─ dist/MaterialWMS.exe   # 打包产物(单文件, 已 gitignore)
 ```

-## 打包 EXE
+---
+
+## 七、打包 EXE
+
 ```bat
 python build_exe.py
 ```
-产物在 `dist/MaterialWMS.exe`。冻结后模板/静态走 `sys._MEIPASS`,库文件落 exe 同目录。

-## 测试
+产物在 `dist/MaterialWMS.exe`。冻结后模板/静态走 `sys._MEIPASS`，库文件落 exe 同目录。
+构建脚本使用 `--distpath dist_pkg` 以避开某些环境的「安全删除」钩子，构建完成后再复制到 `dist/`。
+
+---
+
+## 八、测试
+
 ```bat
-python tools/e2e_test.py   # 覆盖 登录/收发核算/BOM/订单展开/领料/日志/报表/导入导出/入库·物料·BOM 批量导入窗口/角色拦截
+python tools/e2e_test.py
 ```
+
+覆盖：登录 / 收发核算 / BOM / 订单展开 / 领料 / 日志 / 报表 / 导入导出 /
+入库·物料·BOM 批量导入窗口 / 角色拦截 / 替代料提示 / 厂间调拨对账。
+
+---
+
+## 九、部署与数据备份
+
+- 数据唯一真源为 `dist/app.db`（EXE 同目录）；搬 EXE 时务必把 `app.db` 一起带走。
+- 更新 EXE 后**务必结束旧进程**（Windows：`Stop-Process -Name MaterialWMS -Force`）再重启，
+  否则浏览器连的是旧代码，会表现为「新功能点不了 / 没按钮」。
+- 重大操作前复制 `app.db` 为 `.bak` 备份，可随时覆盖还原。