Skip to content

README.md

Latest commit

 

History

History
213 lines (173 loc) · 6.89 KB

README.md

File metadata and controls

213 lines (173 loc) · 6.89 KB
Raw

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