🧮 New SKU Safety Stock Calculator
新產品安全（補貨）庫存計算器 使用說明書

A開發者筆記（Developer Notes）

本段為開發者與維護者快速參考，列出目前前端程式中的關鍵變數、函式與 UI id，方便對照與修改。

核心資料與函式

• `config.js`：主要業務資料來源（`STORES_CONFIG`, `SAFETY_STOCK_MATRIX`, `WEIGHT_CONFIG`, `WEIGHT_TEMPLATES`）。
• 店鋪資料結構：`{ Site, Shop, Regional, Class, Size, OM, Type }`（Type = T/M/L 客源類型）。
• `getSafetyStockValue(region, category, size, type)`：從 `SAFETY_STOCK_MATRIX` 讀取 Safety Stock 值（含 Type）。
• `calculateSafetyStockWithWeights(region, category, size, type, weights)`：使用權重計算單一 Safety Stock 值（含 Type）。
• `generateMatrixWithWeights(weights)`：根據權重生成整張對照表（以 Type=M 作為基準）。
• `matrixDraft`：對照表草稿（編輯/套用前的暫存）。
• `customStoreStock`：物件，存儲個別店鋪覆寫的 Safety Stock（key = `Site`）。
• `customSafetyStock`：物件，存儲對照表覆寫值（key = `${region}-${category}-${type}-${size}`）。

重要 UI 元素 (id)

• calculateBtn - 執行計算
• exportBtn / exportExcelBtn - 匯出 CSV / Excel
• exportExcelWithFormulasBtn - 匯出 Excel（含公式）
• printBtn - 打印結果
• exportConfigBtn / importFile - 匯出 / 匯入 JSON 設定
• storesCsvFile - 店鋪 CSV 上傳 input
• editMatrixBtn / saveMatrixBtn - 編輯對照表
• themeToggleBtn, themePanel, themeList - 主題切換
• storesContainer - 店鋪列表容器（內含 `.editable-store-stock` 可 inline 編輯）
• qrExportExcel, qrOmFilter, qrTable - 快速報表區域

其他說明

• Inline 編輯：店鋪列表的 `.editable-store-stock` 元素支援點擊編輯，按 Enter 儲存、Esc 取消。
• 本專案為純前端（無後端），所有狀態均保存在 localStorage 或記憶體中。
• 變更業務資料（如對照表或店鋪名單）時，請優先修改 `config.js`。
• 本專案包含 GitHub 模板與貢獻指南：`CONTRIBUTING.md`、`.github/PULL_REQUEST_TEMPLATE.md`、`.github/ISSUE_TEMPLATE/`。
• 安全提醒：不要在任何會上傳到版本控制或公開的檔案中硬編碼密碼或金鑰（例如 `app.js`、`config.js`）。請使用環境變數、CI secrets（GitHub Secrets）或專業秘密管理服務來保存敏感資訊。

1程式簡介

1.1 什麼是 Safety Stock 計算器？

Safety Stock（安全庫存）計算器是一個專為零售業設計的網頁工具， 幫助您根據店鋪的不同特性（區域、舖類、貨場面積）來計算每間店鋪所需的 安全庫存數量。

1.2 主要功能一覽

1.3 程式架構

New SKU Safety Stock Calculator/
├── index.html      # 主頁面與 UI 骨架
├── styles.css      # 樣式表（支援多種主題）
├── app.js          # 應用程式邏輯
├── config.js       # 業務資料與參數配置
└── stores-template.csv  # 店鋪批量匯入模板

2系統需求與安裝

2.1 系統需求

2.2 安裝方式

方法一：直接開啟（最簡單）

# Windows
在檔案總管中找到 index.html，雙擊用瀏覽器開啟

# macOS
open index.html

# Linux
xdg-open index.html

方法二：使用本地伺服器（推薦）

# 使用 Python（需安裝 Python 3）
cd /path/to/calculator
python -m http.server 8000

# 使用 Node.js（需安裝 Node.js）
cd /path/to/calculator
npx http-server -p 8000

# 使用 PHP
cd /path/to/calculator
php -S localhost:8000

3介面導覽

3.1 主介面結構

3.2 店鋪類型代碼說明

店鋪類型代碼由三部分組成：區域 + 舖類 + 面積，客源類型 (Type) 會以獨立欄位顯示。

3.3 店鋪等級說明

3.4 貨場面積說明

3.5 客源類型 (Type) 說明

4基本操作流程

4.1 快速開始指南

系統提供兩種操作模式：

• 計算器模式：完整流程（對照表/權重設定 → 選擇店鋪 → 計算 → 匯出）
• 快速報表模式：簡化流程（選擇店鋪 → 直接匯出 Excel）

4.2 選擇店鋪

方法一：手動勾選

1. 在店鋪列表中找到您要選擇的店鋪
2. 點擊店鋪名稱前面的核取方塊
3. 已選擇的店鋪會顯示為藍色背景

方法二：使用快捷按鈕

方法三：使用篩選器

您可以結合多個篩選條件來精準選擇店鋪：

• 區域：HK / MO
• 舖類：A / B / C / D
• 貨場面積：XL / L / M / S / XS
• 客源類型：T / M / L
• 店鋪組別：HA / HB / HC / HD
• 特別店鋪：快速選取指定店鋪代號（如 HA40 / HB87 / HB91）
• 營運經理 (OM)：點擊 OM 按鈕會在右側顯示該 OM 的店鋪清單

4.3 調整 Safety Stock 參數

方式一：直接編輯對照表

1. 點擊 編輯對照表 按鈕
2. 點擊要修改的儲存格（表格內容會依計算模式變化）
3. 輸入新數值
4. 點擊 保存（僅保存到對照表草稿）
5. 點擊 套用到選擇店鋪（才會更新店鋪 Safety Stock）

方式二：使用權重計算

1. 展開 ⚙️ 權重快速設定
2. 調整 Class / Size / Type 權重與基礎值、區域係數
3. （可選）輸入銷售目標與天數，系統自動計算目標總 Safety
4. 點擊 👁️ 預覽結果
5. 點擊 🚀 套用權重計算 更新對照表
6. 最後點擊 套用到選擇店鋪 套用到店鋪

4.4 執行計算

1. 確認已選擇至少一間店鋪
2. 點擊 🔢 計算 Safety Stock
3. 系統會顯示計算結果（可直接點擊彙總表中的 Safety Stock 進行微調）

4.5 查看結果

計算完成後，結果區域會顯示三個表格：

📊 按店鋪類型彙總表

👤 按營運經理 (OM) 彙總表

📋 店鋪詳細清單

顯示所有選擇店鋪的詳細資料（含客源 Type、OM、Carry）。

4.6 快速報表（Quick Report）

1. 切換到 📊 快速報表 分頁
2. 使用上方篩選（區域 / OM）快速縮小範圍
3. 勾選要匯出的店鋪（可使用全選/取消全選）
4. 下方會即時顯示統計與彙總表
5. 點擊 📊 匯出 Excel（只會匯出目前可見且已勾選的店鋪）

5進階功能

5.1 個別店鋪編輯

您可以對單一店鋪的 Safety Stock 值進行獨立編輯：

5.2 彙總表即時調整

在「按店舖類型彙總」表格中，點擊 Safety Stock 欄位即可快速修改該類型數值，系統會即時更新總計。

5.3 重設自訂值

若已對個別店鋪做過編輯，可使用 🔄 重設自訂值 來恢復對照表的預設值（只會重設已選擇的店鋪）。

5.4 主題切換

程式支援多種配色主題，點擊右上角的 🎨 按鈕選擇：

6權重計算系統

6.1 什麼是權重計算？

權重計算系統讓您可以透過調整參數，自動產生符合業務需求的 Safety Stock 對照表， 而不需要手動輸入每個數值。

6.2 計算公式

6.3 權重參數說明

Class 權重（A:B:C:D）

Size 權重（XL:L:M:S:XS）

Type 權重（T:M:L）

區域係數

6.4 快速模板

系統提供多種預設模板：

6.5 使用權重計算的步驟

1. 點擊 ⚙️ 權重快速設定 展開面板
2. 調整各項權重參數
3. （可選）選擇快速模板
4. 點擊 👁️ 預覽結果 查看計算結果
5. 確認後點擊 🚀 套用權重計算
6. 點擊 套用到選擇店鋪 應用到店鋪

6.6 計算範例

6.7 目標總量調整

如果您有特定的 Safety Stock 總量目標：

1. 在 目標總 Safety 輸入目標值（例如：1200）
2. 系統會自動根據店鋪數量和權重比例分配
3. 點擊 預覽結果 查看分配結果

6.8 銷售目標計算功能

銷售目標計算功能讓您可以根據預期的銷售數量，自動計算所需的 Safety Stock 總量。 這對於新產品上市或規劃促銷活動時特別有用。

6.8.1 功能概述

6.8.2 計算公式

6.8.3 使用步驟

1. 展開 ⚙️ 權重快速設定 面板
2. 在 銷售目標數量 輸入框中輸入月銷售目標（例如：36000）
3. 拖動 Safety Stock Days 滑塊調整庫存天數（預設 7 天）
4. 系統會自動計算目標總 Safety Stock
5. 點擊 👁️ 預覽結果 查看計算結果
6. 確認後點擊 🚀 套用權重計算
7. 點擊 套用到選擇店鋪 套用到店鋪

6.8.4 介面示意圖

6.8.5 計算範例

6.8.6 與權重計算的整合

當您點擊 🚀 套用權重計算 時，系統會：

1. 讀取已計算或手動輸入的「目標總 Safety Stock」
2. 根據各類型店鋪的權重比例，自動分配庫存到對照表
3. 使用 scaleMatrixToTarget() 函數將對照表縮放至目標值
4. 完成後請點擊 套用到選擇店鋪 以更新店鋪 Safety Stock

6.8.7 資料持久化

銷售目標計算的參數會自動保存在瀏覽器中：

7匯入與匯出

7.1 匯出計算結果

匯出 CSV

1. 完成計算後，點擊 📥 匯出 CSV
2. 檔案會自動下載到您的電腦
3. 可用 Excel 或其他試算表軟體打開

匯出 Excel

1. 點擊 📊 匯出 Excel
2. 會產生包含多個工作表的 Excel 檔案：

匯出 Excel（含公式）

1. 點擊 📊 匯出 Excel (含公式)
2. 會產生可編輯的對照表工作表，並用公式連動明細與彙總

打印

1. 點擊 🖨️ 打印
2. 會以新視窗開啟列印版面，可輸出為 PDF

快速報表匯出 Excel

1. 切換到 📊 快速報表 分頁
2. 勾選要匯出的店鋪後，點擊 📊 匯出 Excel
3. 會產生「店鋪詳細清單 / 類型彙總 / OM彙總 / 對照表」四個工作表

匯出配置（JSON）

1. 點擊 💾 匯出配置
2. 會保存目前的設定：

• 對照表自訂值
• 已選擇的店鋪
• 店鋪列表

7.2 匯入配置

1. 點擊 📤 匯入配置
2. 選擇之前導出的 .json 檔案
3. 系統會自動載入所有設定

7.3 匯出格式說明

CSV 格式範例：

店鋪詳細清單
生成日期: 2026/02/08 15:30:00

HK/MO,代號,店鋪,類型代碼,舖類,貨場面積,Safety Stock,Carry
HK,HA01,銅鑼灣一號,HKAL,A,L,6,Y
HK,HA02,銅鑼灣二號,HKAM,A,M,5,Y
MO,MA01,澳門廣場,MOBM,B,M,7,Y

8常見問題

Q1：為什麼看不到計算結果？

可能原因：

• 沒有選擇任何店鋪 → 解決：勾選至少一間店鋪
• 參數值不正確 → 解決：檢查所有參數值
• 瀏覽器緩存問題 → 解決：按 F5 刷新頁面

Q2：如何重置為預設值？

1. 點擊 編輯對照表
2. 點擊 重置為預設
3. 確認重置操作

Q3：資料會遺失嗎？

Q4：如何在多台電腦上使用？

1. 手動同步：在一台電腦上匯出配置，在另一台電腦上匯入
2. 雲端同步：將整個專案資料夾放在雲端硬碟（Dropbox、OneDrive）
3. 版本控制：使用 Git 上傳到 GitHub

Q5：如何變更管理員密碼？

為避免在文件中暴露密碼，請不要在公開文件中記錄或張貼任何密碼。如果您需要變更管理員密碼，請透過受控且安全的渠道處理：

1. 聯絡系統管理員或維護人員由其在安全環境下進行修改。
2. 若需在程式碼中設定或更新，請使用受保護的設定管理流程（例如環境變數或受限的設定檔），並避免在版本控制或公開文件中硬編碼密碼。
3. 變更後請立即更新相關憑證管理與備份流程，並通知受影響的管理人員。

Q6：權重計算結果不合理？

1. 檢查各項權重值是否正確
2. 嘗試使用「預設權重」模板
3. 逐步調整參數並預覽結果

9計算公式說明

9.1 Safety Stock 基本概念

Safety Stock（安全庫存）是為防止缺貨而預留的額外庫存， 其計算考量以下因素：

9.2 本程式的權重計算公式

公式說明：

9.3 計算示例表

9.4 Carry 狀態判斷

📎 附錄

鍵盤快速鍵