QR 庫存管理系統 v2（模組化版本）

基於 v13 的模組化重構版本，將單一 app13.py 拆分為多個獨立模組，提升程式碼的可維護性與擴展性。

功能特色

• QR Code 掃描：支援明碼格式、HMAC 簽章格式、捲級別格式
• 庫存操作：查詢、入庫、出庫、調撥、盤點
• 捲ID管理：布疋捲級別追蹤（v13 新增）
• Session 式盤點：支援鎖倉機制、快照審計、掃描累加模式
• 交易記錄：完整的操作歷史追蹤

---

模組化結構

qr-inventory-system-v2/
│
├── app.py                      # 主程式入口
├── config.py                   # 配置常數
├── core.py                     # 核心功能模組
│
├── query_api.py                # 查詢 API 模組
├── stock_in_api.py             # 入庫 API 模組
├── stock_out_api.py            # 出庫 API 模組
├── transfer_api.py             # 調撥 API 模組
├── inventory_check_api.py      # 簡易盤點 API 模組
│
├── stocktaking_api_v13.py      # Session 式盤點模組（沿用）
├── transaction_log_api.py      # 交易記錄查詢模組（沿用）
│
├── generate_qr_v13.py          # QR Code 生成工具
├── batch_qr_generator_v13.py   # 批次 QR Code 生成工具
│
├── static/                     # 前端靜態檔案
│   ├── index13.html            # 主頁面
│   ├── stocktaking13.html      # 盤點管理頁面
│   ├── transaction-log.html    # 交易記錄頁面
│   └── style.css               # 樣式表
│
├── stocktaking/                # 盤點資料目錄
│   └── snapshots/              # 盤點快照
│
├── inventory.xlsx              # 庫存資料
├── transaction_log.xlsx        # 交易記錄
├── users.json                  # 使用者清單
├── cert.pem                    # SSL 憑證
└── key.pem                     # SSL 金鑰

---

模組說明

config.py - 配置模組

集中管理所有配置常數：

• 檔案路徑（Excel、使用者清單）
• 系統常數（重載間隔、HMAC 密鑰）
• Excel 欄位名稱定義

core.py - 核心功能模組

提供共用的核心功能：

• load_excel() / save_excel() - Excel 讀寫
• log_transaction() - 交易記錄寫入
• parse_payload() - QR Code 解析（支援多種格式）
• check_lock_and_reject() - 鎖倉檢查
• reload_watcher() - 背景自動重載機制
• 快取管理函式

query_api.py - 查詢模組

端點	方法	說明
/api/users	GET	查詢使用者列表
/api/query	GET	貨品查詢（支援 QR Code）
/api/query-roll	GET	捲ID 查詢
/api/inventory/list	GET	庫存清單

stock_in_api.py - 入庫模組

端點	方法	說明
/api/stock-in	POST	入庫操作

stock_out_api.py - 出庫模組

端點	方法	說明
/api/stock-out	POST	出庫操作

transfer_api.py - 調撥模組

端點	方法	說明
/api/transfer	POST	調撥操作

inventory_check_api.py - 簡易盤點模組

端點	方法	說明
/api/inventory-check	POST	簡易盤點（即時更新）

stocktaking_api_v13.py - Session 式盤點模組（沿用）

端點	方法	說明
/api/stocktaking/sessions	GET	取得所有盤點 Session
/api/stocktaking/session	POST	建立新盤點 Session
/api/stocktaking/session/<id>	GET	取得 Session 詳情
/api/stocktaking/session/<id>/start	POST	開始盤點（建立快照）
/api/stocktaking/session/<id>/items	GET	取得盤點項目
/api/stocktaking/session/<id>/check	POST	更新盤點數量
/api/stocktaking/session/<id>/scan-roll	POST	掃描累加模式
/api/stocktaking/session/<id>/close	POST	關閉盤點
/api/stocktaking/session/<id>/apply	POST	套用盤點結果
/api/stocktaking/session/<id>/cancel	POST	取消盤點
/api/stocktaking/warehouses	GET	取得倉庫列表

transaction_log_api.py - 交易記錄模組（沿用）

端點	方法	說明
/api/transaction-log	GET	查詢交易記錄
/api/transaction-log/types	GET	取得操作類型列表
/api/transaction-log/operators	GET	取得操作人員列表

---

快速開始

環境需求

• Python 3.8+
• Flask
• pandas
• openpyxl

啟動伺服器

cd C:/Python/myvenv01/qr-inventory-system-v2
../Scripts/python.exe app.py

存取位址

• 主頁面：https://localhost:5002/
• 盤點管理：https://localhost:5002/stocktaking
• 交易記錄：https://localhost:5002/transaction-log

---

API 使用範例

查詢貨品

curl -k "https://localhost:5002/api/query?code=02001-0001-64A-V1"

入庫

curl -k -X POST "https://localhost:5002/api/stock-in" \
  -H "Content-Type: application/json" \
  -d '{"barcode":"A001","batch_no":"b1","qty":100,"location":"R1-1","operator":"王小明"}'

出庫

curl -k -X POST "https://localhost:5002/api/stock-out" \
  -H "Content-Type: application/json" \
  -d '{"barcode":"A001","batch_no":"b1","qty":50,"operator":"王小明"}'

調撥

curl -k -X POST "https://localhost:5002/api/transfer" \
  -H "Content-Type: application/json" \
  -d '{"barcode":"A001","batch_no":"b1","qty":30,"from_location":"R1-1","to_location":"R2-1","operator":"王小明"}'

---

與原版 app13.py 的對應

原 app13.py 功能	v2 模組
配置常數	config.py
Excel 操作、HMAC 驗證、快取管理	core.py
/api/users, /api/query, /api/query-roll, /api/inventory/list	query_api.py
/api/stock-in	stock_in_api.py
/api/stock-out	stock_out_api.py
/api/transfer	transfer_api.py
/api/inventory-check	inventory_check_api.py
Session 式盤點	stocktaking_api_v13.py（沿用）
交易記錄查詢	transaction_log_api.py（沿用）

---

模組化優點

1. 可維護性：各功能獨立成模組，修改單一功能不影響其他模組
2. 可讀性：程式碼結構清晰，易於理解
3. 可測試性：可針對個別模組進行單元測試
4. 可擴展性：新增功能只需建立新模組並註冊
5. 團隊協作：不同開發者可同時修改不同模組

---

注意事項

• 所有 API 端點與原版 v13 完全相容
• 前端頁面無需修改，直接沿用
• stocktaking_api_v13.py 和 transaction_log_api.py 幾乎不需更動
• 鎖倉機制跨模組共享，由 core.py 統一管理

---

版本資訊

• 基於版本：v13（支援捲ID、掃描累加模式）
• 模組化版本：v2
• 建立日期：2024-12-22