G.5 模組化與函式設計:def 函式封裝、參數契約與 CIF 報價模組

學完本節,你能夠:

  1. 用 def 把一段商業計算封裝成函式,並分辨 return(交回結果)與 print(只顯示)。
  2. 判斷哪些參數適合給預設值、哪些必須由呼叫者提供,並用型別提示與說明文字(docstring)寫清楚函式的「契約」。
  3. 把 E.4 的 CIF 公式寫成函式,在輸入不合理時停止,並用同一個函式批次產生多個目的港的報價。

壹、開場情境:同一個公式,三個版本

📌 以下為教學情境(依實務改編)。

E.4 的 cif_quotation.py 在公司裡傳開了。一個月後,小安發現同一個 CIF 公式出現在三個地方:

誰複製的 改了什麼 結果
業務 A 原封不動 正確
業務 B 嫌移項公式難懂,改成 (FOB + 運費) × 1.1 × 費率 每張報價的保險費都少算
報價系統 保險費率改成 0.5%,但只改了其中一處 同一張報價單前後數字不一致

公式本身沒錯,錯在它被複製貼上了三次。之後只要規則一改(例如投保加成從 110% 改成 120%),就得找出每一份複本逐一修改,漏掉一份就出錯。

本節要解決的問題: 怎麼把公式寫成「只有一份、大家都呼叫它」的標準模組?


貳、為什麼要用函式:把計算寫成一份標準作業程序

函式就像公司的 SOP:規定好要給什麼(輸入)、照什麼步驟做(處理)、交出什麼(輸出)。所有人都呼叫同一個函式,規則只需要在一個地方維護,這個原則叫 DRY(Don't Repeat Yourself,不要重複)。

flowchart LR In["輸入(參數)
fob、freight、insurance_rate"] --> F["def cif_quote(...)
檢查輸入 → 計算"] F --> Out["輸出(return)
fob、freight、insurance、cif"] F -.->|"輸入不合理"| Err["raise ValueError
停止,不產生報價"]

1. def 與 return

def calculate_margin(revenue, cost):
    """回傳毛利率(小數)。毛利率 = (收入 − 成本) ÷ 收入"""
    if revenue <= 0:
        raise ValueError("收入必須大於 0,無法計算毛利率")
    return (revenue - cost) / revenue

# 第 1.1 節的 A 款鍵盤:報價 €100
at_quote = calculate_margin(100 * 35.0, 2800)   # 報價當天匯率 35.0
at_settle = calculate_margin(100 * 31.5, 2800)  # 結匯當天匯率 31.5

print(f"報價時毛利率 {at_quote:.1%},結匯時 {at_settle:.1%}")
print(f"少了 {(at_quote - at_settle) * 100:.1f} 個百分點")
報價時毛利率 20.0%,結匯時 11.1%
少了 8.9 個百分點
語法 作用
def 名稱(參數): 定義函式;底下縮排的內容是函式本體
return 值 把結果交回給呼叫的地方,函式到此結束
raise ValueError("訊息") 輸入不合理時停止,並說明原因
名稱(引數) 呼叫函式

raise 比回傳一個假的 0 更安全:如果收入是 0 時回傳毛利率 0,呼叫者可能把它當成真的數字繼續用;raise 則讓錯誤無法被忽略。

常見錯誤:用 print 代替 return

def show_margin(revenue, cost):
    print((revenue - cost) / revenue)    # 只印出來,沒有交回

result = show_margin(3150, 2800)
print(result)
0.1111111111111111
None

⚠️ print 不等於 return print 只是給人看;沒有 return 的函式交回的是 None,其他程式拿不到結果,也就無法再拿去計算或存檔。

2. 預設參數:哪些數字可以「預設」?

def calculate_vat(amount, tax_rate=0.05):
    """回傳營業稅額;不指定稅率時,採台灣營業稅 5%"""
    return amount * tax_rate

print(calculate_vat(1000))         # 用預設 5%
print(calculate_vat(1000, 0.19))   # 德國標準稅率 19%
50.0
190.0

預設值是一種商業決策,不是寫程式的方便:

參數 給預設值? 理由
台灣營業稅率 5% ✅ 法定稅率,很少變動
保險費率 0.3% ✅ 公司與保險公司的常用費率,個案可覆蓋
投保加成 110% ✅ 國際慣例
匯率 🛑 每天變動;預設值等於用過期匯率報價(E.5 的 --rate 必填也是這個理由)
FOB、運費 🛑 每筆交易都不同,沒有合理的預設

3. 型別提示與 docstring:把契約寫在函式上

def convert_to_twd(amount: float, rate: float) -> int:
    """
    把外幣金額換算成新台幣。

    參數:
        amount: 外幣金額
        rate: 當日匯率(必填,不設預設值,避免用到過期匯率)
    回傳:
        新台幣金額,四捨五入到整數
    """
    return round(amount * rate)

print(convert_to_twd(48961.57, 32.2))
1576563

amount: float 表示「這裡應該給小數」,-> int 表示「會交回整數」。Python 不會強制檢查型別提示,但同事、編輯器與 AI 助手都看得懂。三引號 """ 內的說明文字稱為 docstring,在 REPL 輸入 help(convert_to_twd) 就能看到。

4. 區域變數:函式內的東西留在函式內

def apply_discount(price):
    discount = 0.10              # 區域變數:只活在函式裡
    return price * (1 - discount)

print(apply_discount(1000))
print(discount)
900.0
Traceback (most recent call last):
  ...(中間顯示出錯的行號,略)
NameError: name 'discount' is not defined

函式內建立的變數,函式結束就消失,不會汙染外面。反過來,也不要在函式內用 global 去修改外面的變數:那會讓函式的結果取決於「外面剛好是什麼值」,同樣的輸入可能算出不同結果,很難除錯。函式需要什麼,就從參數拿;算出什麼,就用 return 交回。


參、把規則寫下來:CIF 報價函式的契約

項目 規格
函式名稱 cif_quote
必填參數 fob(FOB 貨價)、freight(海運運費),單位美元,都必須 > 0
有預設值的參數 insurance_rate=0.003(0.3%)、insured_markup=1.1(110%)
公式 與 E.4 相同:CIF = (FOB + 運費) ÷ (1 − 投保加成 × 保險費率)
數字一致 CIF 四捨五入到小數兩位;保險費 = CIF − FOB − 運費,確保報價單上三項加總剛好等於 CIF
例外 FOB 或運費 ≤ 0、保險費率不在 0~10% 之間 → raise ValueError,不產生報價
回傳 字典:fob、freight、insurance、cif

為什麼投保金額是 CIF 的 110%?Incoterms 2020 規定,CIF 條件下賣方至少要按契約價金的 110% 投保,且最低承保範圍為協會貨物條款 (C);多出的 10% 一般解釋為保障買方的預期利潤與費用。


肆、寫出來

在 TradeLab 資料夾建立 cif_module.py:

# cif_module.py:把 E.4 的 CIF 公式封裝成函式,批次產生報價

def cif_quote(fob: float, freight: float,
              insurance_rate: float = 0.003,
              insured_markup: float = 1.1) -> dict:
    """
    由 FOB 貨價與運費計算 CIF 報價(單位:美元)。

    投保金額 = CIF × insured_markup(慣例 110%)
    CIF = (FOB + 運費) ÷ (1 − insured_markup × insurance_rate)

    參數:
        fob: FOB 貨價,必須 > 0
        freight: 海運運費,必須 > 0
        insurance_rate: 保險費率,預設 0.3%,須介於 0 與 10% 之間
        insured_markup: 投保加成,預設 1.1
    回傳:
        dict,含 fob、freight、insurance、cif,皆四捨五入到小數兩位
    """
    # 1. 輸入檢查:不合理就停止,不產生報價
    if fob <= 0 or freight <= 0:
        raise ValueError(f"FOB 與運費必須大於 0(收到 fob={fob}, freight={freight})")
    if not 0 < insurance_rate < 0.1:
        raise ValueError(f"保險費率 {insurance_rate} 不合理,請核對保單")

    # 2. 計算(與 E.4 同一個公式)
    cif = round((fob + freight) / (1 - insured_markup * insurance_rate), 2)
    insurance = round(cif - fob - freight, 2)   # 用減的,保證三項加總剛好等於 CIF

    # 3. 回傳結構化結果,交給呼叫者決定怎麼顯示或存檔
    return {"fob": fob, "freight": freight, "insurance": insurance, "cif": cif}


# ===== 使用範例:同一批貨,三個目的港(運費為教學用假設值)=====
FOB = 45000.0
FREIGHT_BY_PORT = {"Hamburg": 3800.0, "Los Angeles": 2600.0, "Tokyo": 1200.0}

print(f"{'Port':<12}{'Freight':>10}{'Insurance':>10}{'CIF':>12}")
for port, freight in FREIGHT_BY_PORT.items():
    q = cif_quote(FOB, freight)
    print(f"{port:<12}{q['freight']:>10,.2f}{q['insurance']:>10,.2f}{q['cif']:>12,.2f}")

執行結果:

Port           Freight Insurance         CIF
Hamburg       3,800.00    161.57   48,961.57
Los Angeles   2,600.00    157.60   47,757.60
Tokyo         1,200.00    152.96   46,352.96

Hamburg 這一列與 E.4 的結果(保險費 161.57、CIF 48,961.57)完全相同:同一個公式,現在只有一份。

🔍 驗收重點 - 公式是否與 E.4 相同,除以 (1 − 1.1 × 費率),而不是用 (FOB + 運費) × 1.1 × 費率 近似? - 匯率、FOB、運費是否都沒有預設值? - 輸入不合理時是 raise,而不是回傳 0 或空字典? - 每一列:運費 + 保險費 + 45,000 是否剛好等於 CIF?


伍、跑跑看、壞給你看

在檔案最後加一行測試,跑完再刪掉。

實驗 操作 預期結果 想想看
① 運費漏填 cif_quote(45000.0, 0) ValueError: FOB 與運費必須大於 0(收到 fob=45000.0, freight=0) 錯誤訊息有沒有告訴你「哪裡錯、收到什麼」?
② 覆蓋預設值 print(cif_quote(45000.0, 3800.0, insurance_rate=0.005)) 保險費 269.88、CIF 49,069.88(與 E.4 實驗 ③ 相同) 預設值讓常見情況少打字,特殊情況仍可指定
③ 參數位置放錯 cif_quote(45000.0, 3800.0, 1.1)(想指定投保加成,卻沒寫參數名稱) ValueError: 保險費率 1.1 不合理,請核對保單 1.1 被當成第 3 個參數 insurance_rate。為什麼用 insured_markup=1.1 這種寫法比較安全?
④ 業務 B 的簡化公式 在 REPL 算 (45000 + 3800) * 1.1 * 0.003 161.04000000000002,比函式的 161.57 少 0.53 這個錯誤只要修函式一處,所有呼叫者就同時修好

陸、回到情境

三份複本換成一個 cif_quote():業務的試算、報價系統、未來的 ERP,都呼叫同一個函式。投保加成若要改成 120%,只要改預設值一處;有人傳入不合理的數字,函式會停下來說明原因,而不是交出一張看似正常的報價單。

限制 後果 在哪一節解決
函式還放在單一檔案裡 其他程式要用,仍得複製 存成模組後用 import 引用(第 4 章起的程式會大量使用)
沒有自動化測試 有人改壞公式,要等客戶發現 可以套用第 5 章的 pytest 寫法,為 cif_quote() 寫測試
CIF 不是買方的總成本 目的港費用、進口關稅等仍由買方負擔 進口成本試算見 E.5 的關稅試算

本節小結

  1. 重複出現的計算寫成函式,規則只在一處維護(DRY)。
  2. return 交回結果,print 只是顯示;輸入不合理用 raise 停止,不回傳假值。
  3. 預設值是商業決策:法定稅率、慣例可以預設;匯率、每筆交易的金額不行。
  4. 型別提示與 docstring 寫清楚函式的契約;呼叫時用參數名稱,避免位置放錯。

柒、練習

  1. 改數字(5 分鐘):Hamburg 的運費漲到 USD 5,200。用 cif_quote() 算出新的保險費與 CIF。(答案:166.21;50,366.21,與 E.4 練習 1 相同)
  2. 加功能(20 分鐘):寫一個 cif_quote_twd(fob, freight, rate),在內部呼叫 cif_quote() 與 convert_to_twd(),回傳 CIF 的台幣金額。先寫契約(參數、哪些必填、例外怎麼處理、回傳什麼),再請 AI 實作,用匯率 32.2 驗算 Hamburg 的結果是否為 NT$ 1,576,563。
  3. 管理反思(討論):開場三份複本中,業務 B 的修改出於好意(想讓公式好懂)。公司應該怎麼規定「誰可以改共用函式、改之前要做什麼」?這和第 1.1 節「誰有權改 MIN_MARGIN」是同一類問題嗎?

國立臺中科技大學 國際貿易系 / 企業管理系 專用教材

《現代軟體工程:商學院的 AI 系統思維與 Agent 實踐》

作者:陳俊智 博士 Dr. Chun-Chih Chen

本書章節架構改編自陳鍾誠教授(金門大學)開源課程《現代軟體工程》(github.com/ccc115a/se,MIT 授權),內容針對商學院全面改寫與擴充。