Skip to content

USER_GUIDE.md

Latest commit

 

History

History
456 lines (331 loc) · 13.3 KB

USER_GUIDE.md

File metadata and controls

456 lines (331 loc) · 13.3 KB

React Flow Showcase - 使用者指南

概述

這是一個基於節點的動態價格計算系統，讓使用者可以透過拖放商品節點、額外費用節點和總計節點到畫布上，並將它們連接起來，即時觀看計算結果在圖表中傳播。

系統架構

三種核心節點類型

  1. 🏷️ 商品節點 (Product Info Node)

    • 用於輸入單一商品的詳細資訊
    • 自動計算該商品的小計金額
    • 可以連接到總計節點

  2. 💳 總計節點 (Total Price Node)

    • 匯總所有連接的商品節點金額
    • 接收額外費用節點的計算
    • 顯示最終應付金額

  3. 💲 額外費用計算節點 (Extra Charge Node)

    • 應用服務費、折價券、點數折抵等額外計算
    • 只能連接到總計節點
    • 每個總計節點只能連接一個額外費用節點

如何使用

基本操作

  1. 新增節點

    • 從左側工具列拖曳想要的節點類型到畫布上
    • 可用節點：商品、總計、額外費用

  2. 連接節點

    • 從商品節點底部的藍色連接點拖曳到總計節點頂部的藍色連接點
    • 從額外費用節點左側的綠色連接點拖曳到總計節點右側的綠色連接點

  3. 移動節點

    • 直接點擊並拖曳節點即可移動

  4. 刪除節點或連線

    • 選擇節點或連線後按 Delete 或 Backspace 鍵

  5. 儲存/載入流程

    • 系統會自動將您的節點配置儲存到瀏覽器本地儲存
    • 重新開啟頁面時會自動載入上次的配置

計算邏輯詳解

1️⃣ 商品節點計算 (Product Info Node)

輸入欄位：

  • 活動名稱 - 文字描述（不參與計算）
  • 方案項目 - 文字描述（不參與計算）
  • 市售價 - 原始價格
  • 優惠價 - 促銷價格（如有）
  • 數量 - 購買數量
  • 退款數量 - 需要退款的數量
  • 取消行政費用 - 取消訂單的手續費

計算公式：

有效價格 = (優惠價 > 0) ? 優惠價 : 市售價

金額小計 = (有效價格 × 數量) - (退款數量 × 有效價格) - 取消行政費用

計算範例：

假設：

  • 市售價：NT$ 1,000
  • 優惠價：NT$ 800
  • 數量：5
  • 退款數量：1
  • 取消行政費用：NT$ 100

計算過程：

  1. 有效價格 = NT$ 800（因為有優惠價）
  2. 總金額 = 800 × 5 = NT$ 4,000
  3. 退款金額 = 1 × 800 = NT$ 800
  4. 金額小計 = 4,000 - 800 - 100 = NT$ 3,100

重要規則：

  • 如果有設定優惠價（且 > 0），則使用優惠價計算
  • 如果沒有優惠價，則使用市售價
  • 退款是按「有效價格」計算，不是按固定金額
  • 金額小計不會是負數（最小為 0）

2️⃣ 總計節點計算 (Total Price Node)

輸出欄位：

  • 金額小計 - 所有連接商品的總和
  • 最後金額 - 套用額外費用後的最終金額

計算邏輯：

階段一：商品總計

金額小計 = 商品A小計 + 商品B小計 + 商品C小計 + ...

每當有商品節點連接或斷開時，系統會：

  1. 找出所有連接到此總計節點的商品節點
  2. 讀取每個商品節點的「金額小計」
  3. 加總所有金額
  4. 更新「金額小計」欄位

階段二：額外費用計算

最後金額 = 金額小計
          + (金額小計 × 服務費%)
          - (點數數量 × 點數折抵比例)
          - 折價券金額

計算範例：

假設您有三個商品節點：

  • 商品 1 小計：NT$ 3,100
  • 商品 2 小計：NT$ 2,000
  • 商品 3 小計：NT$ 1,500

金額小計 = 3,100 + 2,000 + 1,500 = NT$ 6,600

如果連接了額外費用節點（服務費 5%，折價券 500，點數 100點，1點折抵10元）：

  1. 基礎金額 = NT$ 6,600
  2. 加服務費 = 6,600 × 1.05 = NT$ 6,930
  3. 扣點數 = 6,930 - (100 × 10) = NT$ 5,930
  4. 扣折價券 = 5,930 - 500 = NT$ 5,430（最後金額）

連接規則：

  • 頂部藍色連接點：只能連接商品節點（可多個）
  • 右側綠色連接點：只能連接額外費用節點（限一個）
  • 如果沒有連接額外費用節點，最後金額 = 金額小計

3️⃣ 額外費用節點計算 (Extra Charge Node)

輸入欄位：

  • 平臺服務費(%) - 百分比形式的服務費（0-100%）
  • 折價券 - 固定折扣金額（NT$）
  • 點數數量 - 使用的點數數量
  • 點數折抵比例 - 每點可折抵的現金金額（1點對多少元）

計算順序（重要！）：

額外費用的計算順序會影響最終結果，系統按以下順序執行：

步驟 1：先加服務費
  臨時金額 = 商品總計 × (1 + 服務費% / 100)

步驟 2：再扣點數
  臨時金額 = 臨時金額 - (點數數量 × 點數折抵比例)

步驟 3：最後扣折價券
  最後金額 = 臨時金額 - 折價券金額

計算範例：

假設商品總計為 NT$ 10,000

情境A：有服務費 + 折價券

  • 服務費：10%
  • 折價券：NT$ 500

計算：

  1. 加服務費：10,000 × 1.10 = NT$ 11,000
  2. 扣折價券：11,000 - 500 = NT$ 10,500

情境B：完整計算（全部費用）

  • 服務費：5%
  • 點數：200 點
  • 點數折抵比例：1:8（1點 = 8元）
  • 折價券：NT$ 300

計算：

  1. 加服務費：10,000 × 1.05 = NT$ 10,500
  2. 扣點數：10,500 - (200 × 8) = 10,500 - 1,600 = NT$ 8,900
  3. 扣折價券：8,900 - 300 = NT$ 8,600

欄位限制：

  • 服務費：只能輸入 0-100 的整數
  • 點數數量：必須搭配「點數折抵比例」才有效
  • 所有金額：最終結果不會是負數（最小為 0）

邊緣連線（Edges）說明

連線類型

  1. 商品 → 總計連線（藍色）

    • 從商品節點底部連接到總計節點頂部
    • 可以多對一：多個商品可連接到同一個總計節點
    • 觸發條件：當商品節點的「金額小計」改變時，會自動更新總計節點的「金額小計」

  2. 額外費用 → 總計連線（綠色）

    • 從額外費用節點左側連接到總計節點右側
    • 一對一限制：每個總計節點只能連接一個額外費用節點
    • 觸發條件：當額外費用節點的任何欄位改變，或總計節點的「金額小計」改變時，會重新計算「最後金額」

計算觸發機制

系統採用 邊緣驅動計算（Edge-Driven Calculation） 模式：

  • ✅ 連接時計算：當您建立一條新連線時，立即觸發計算
  • ✅ 斷開時重算：當您刪除一條連線時，立即重新計算
  • ✅ 資料改變時：當源節點的資料改變時，透過連線自動更新目標節點
  • ❌ 不是輸入驅動：不是在您輸入資料時計算，而是在連線建立/改變時

範例流程：

步驟 1：新增商品節點 A，輸入資料
  → 商品 A 計算出金額小計 = NT$ 1,000

步驟 2：新增總計節點 T
  → 此時總計 T 顯示：金額小計 = NT$ 0

步驟 3：連接 A → T
  → 立即觸發計算
  → 總計 T 更新為：金額小計 = NT$ 1,000

步驟 4：在商品 A 修改數量
  → 商品 A 重新計算小計 = NT$ 2,000
  → 因為有連線，總計 T 自動更新為：金額小計 = NT$ 2,000

步驟 5：新增商品節點 B，輸入資料
  → 商品 B 計算出金額小計 = NT$ 500

步驟 6：連接 B → T
  → 立即觸發計算
  → 總計 T 更新為：金額小計 = NT$ 2,500（A + B）

步驟 7：新增額外費用節點 E，輸入服務費 10%

步驟 8：連接 E → T
  → 立即觸發計算
  → 總計 T 更新為：最後金額 = 2,500 × 1.10 = NT$ 2,750

使用情境範例

情境一：單一商品結帳

需求：計算一個商品的最終價格，包含服務費

  1. 拖曳一個「商品節點」到畫布
  2. 填寫商品資訊：
    • 市售價：NT$ 1,200
    • 數量：2
    • （其他欄位保持空白或0）
  3. 拖曳一個「總計節點」到畫布
  4. 連接：商品節點 → 總計節點
    • 此時金額小計顯示：NT$ 2,400
  5. 拖曳一個「額外費用節點」到畫布
  6. 填寫：服務費 5%
  7. 連接：額外費用節點 → 總計節點
    • 最後金額顯示：NT$ 2,520

情境二：多商品訂單

需求：購買多個不同商品，套用折價券

  1. 建立商品節點 A：

    • 活動：春季促銷
    • 市售價：NT$ 1,000
    • 優惠價：NT$ 800
    • 數量：3
    • 小計：NT$ 2,400

  2. 建立商品節點 B：

    • 活動：夏日特惠
    • 市售價：NT$ 500
    • 數量：2
    • 小計：NT$ 1,000

  3. 建立商品節點 C：

    • 市售價：NT$ 1,500
    • 數量：1
    • 退款數量：0
    • 小計：NT$ 1,500

  4. 建立總計節點

  5. 連接：A → 總計、B → 總計、C → 總計

    • 金額小計：2,400 + 1,000 + 1,500 = NT$ 4,900

  6. 建立額外費用節點

  7. 填寫：折價券 NT$ 500

  8. 連接：額外費用 → 總計

    • 最後金額：4,900 - 500 = NT$ 4,400

情境三：退款計算

需求：客戶訂購5件商品，後來退款2件，並收取取消費用

  1. 建立商品節點：

    • 市售價：NT$ 600
    • 優惠價：NT$ 500
    • 數量：5
    • 退款數量：2
    • 取消行政費用：NT$ 200

  2. 計算過程：

    • 有效價格 = NT$ 500（優惠價）
    • 總金額 = 500 × 5 = NT$ 2,500
    • 退款金額 = 2 × 500 = NT$ 1,000
    • 小計 = 2,500 - 1,000 - 200 = NT$ 1,300

  3. 連接到總計節點，查看最終應收金額

情境四：會員點數折抵

需求：使用會員點數抵扣部分金額

  1. 建立商品節點，填寫商品資訊，假設小計 NT$ 5,000
  2. 建立總計節點並連接
  3. 建立額外費用節點，填寫：
    • 點數數量：300
    • 點數折抵比例：1:10（1點折抵10元）
  4. 連接額外費用節點到總計節點
  5. 計算：
    • 金額小計：NT$ 5,000
    • 點數折抵：300 × 10 = NT$ 3,000
    • 最後金額：5,000 - 3,000 = NT$ 2,000

進階技巧

1. 多個總計節點的使用

您可以建立多個總計節點來分組計算：

商品 A ──┐
商品 B ──┼─→ 總計 1（活動A總計）
商品 C ──┘

商品 D ──┐
商品 E ──┼─→ 總計 2（活動B總計）
商品 F ──┘

每個總計節點獨立計算，互不影響。

2. 動態調整價格

修改任何商品節點的欄位（如數量、優惠價），所有連接的節點會即時更新，無需重新連接。

3. 比較不同方案

建立相同的商品配置，但連接到不同的總計節點，配合不同的額外費用節點，即可快速比較不同計價方案。

4. 畫布操作

  • 縮放：使用滑鼠滾輪縮放畫布
  • 平移：按住並拖曳空白區域移動畫布
  • 框選：按住 Shift 並拖曳可框選多個節點

常見問題

Q1：為什麼我輸入數字後，總計沒有變化？

A：請確認節點之間已經建立連線。計算是透過連線觸發的，沒有連線時各節點是獨立的。

Q2：額外費用節點的綠色連接點變灰了？

A：每個總計節點只能連接一個額外費用節點。如果該總計節點已經有連接，連接點會被禁用。請先刪除現有連線，或建立新的總計節點。

Q3：可以連接商品節點到額外費用節點嗎？

A：不行。系統會自動驗證連線的有效性：

  • 商品節點只能連接到總計節點
  • 額外費用節點只能連接到總計節點
  • 總計節點不能當作源節點

Q4：如何刪除節點或連線？

A：點選要刪除的節點或連線（會出現高亮），然後按下鍵盤的 Delete 或 Backspace 鍵。

Q5：資料會自動儲存嗎？

A：是的，系統會自動將您的節點配置儲存到瀏覽器的本地儲存（LocalStorage）。下次開啟網頁時會自動載入。

Q6：為什麼金額計算結果是 0？

A：可能的原因：

  • 欄位留空或輸入 0
  • 退款數量等於或大於購買數量
  • 計算結果為負數（系統會自動調整為 0）

Q7：服務費的百分比只能輸入整數嗎？

A：是的，目前服務費欄位限制為 0-100 的整數。如果需要小數（如 5.5%），請聯繫開發團隊。

Q8：點數折抵比例怎麼設定？

A：「點數折抵比例」欄位顯示為 "1:"，您只需要輸入後面的數字。例如，如果 1 點可以折抵 8 元，就輸入 "8"。

技術說明（給開發者）

計算觸發機制

系統使用 React Flow 的 useHandleConnections 和 useStoreApi 實現響應式邊緣更新：

  1. 當連線建立/刪除時，useHandleConnections 偵測變化
  2. 透過 useStoreApi().subscribe() 監聽節點資料變化
  3. 使用 Immer 的 produce() 確保不可變更新
  4. 計算結果透過 setNodes 更新到 React Flow store

資料流向

ProductInfoNode (輸入)
  ↓ calculateSubtotal
金額小計
  ↓ (透過邊緣連線)
TotalPriceNode
  ↓ calculateTotalSubtotal
金額小計
  ↓ (透過邊緣連線)
ExtraChargeNode → calculateFinalAmount
  ↓
最後金額

儲存格式

資料儲存在 LocalStorage 中，包含：

  • 所有節點的完整資料
  • 所有邊緣的連線資訊
  • 畫布的視窗位置（viewport）

總結

這個系統提供了直觀的視覺化介面來處理複雜的價格計算。透過拖放和連接節點，您可以：

✅ 輕鬆管理多商品訂單 ✅ 即時查看價格變動 ✅ 靈活套用各種費用和折扣 ✅ 視覺化理解計算流程 ✅ 快速比較不同方案

記住核心概念：連線驅動計算 - 建立連線時，數字會自動流動和更新！