Update src/utils/visualizations.py

src/utils/visualizations.py

@@ -834,39 +834,61 @@ def summarize_fixed_assets(df: pd.DataFrame) -> dict:
 # 科目分類設定
 # 格式：(科目代碼前綴或精確碼, 描述, 活動類別, 資產/負債符號)
 # 符號：資產科目 sign=-1（資產增加→現金減少），負債/淨資產 sign=+1
+# 科目分類說明（間接法推估，以平衡表增減替代現金流量）：
+#
+# 一、營業活動：
+#   - 本期賸餘為起點（在 summarize_cashflow 另行傳入）
+#   - 非現金費用加回：折舊/攤銷以資產淨額減少近似
+#   - 準備金提存：屬非現金調整（退休金/補償準備提撥），並非對外投資
+#   - 遞延負債：遞延收入/補助款等日常營運相關，歸營業活動
+#   - 流動資產/負債變動：應收、存貨、預付、應付、預收
+#
+# 二、投資活動：
+#   - 不動產廠房及設備：各項購建（淨額變動含折舊，近似資本支出淨效果）
+#   - 短期貸墊款：對外放款，非日常營運
+#   - 非流動金融資產、長期應收款：長期投資性質
+#
+# 三、籌資活動：
+#   - 什項負債（長期借款/融資性負債）
+#   - 基金及公積：
+#     ‧ 3101 基金：撥入資本，有變動才列籌資，通常穩定
+#     ‧ 3201/3202 公積：由賸餘提撥，屬內部分配非現金流 → 排除
+#     ‧ 3401 累積其他綜合餘絀：評價調整，非現金 → 排除
+
 _CF_ITEMS = [
-    # ── 一、營業活動 ──────────────────────────────────────────────
-    # 非現金調整（固定/無形資產淨額減少≈折舊攤銷，這裡用差額近似）
-    ("13",   "不動產廠房及設備（淨額變動）", "operating",  +1),  # 減少=折舊
-    ("1701", "無形資產攤銷",                "operating",  +1),
-    ("1801", "遞延資產攤銷",                "operating",  +1),
-    # 流動資產（不含現金）—增加=現金流出
-    ("1102", "流動金融資產增減",             "operating",  -1),
-    ("1103", "應收款項增減",                "operating",  -1),
-    ("1104", "存貨增減",                   "operating",  -1),
-    ("1107", "預付款項增減",                "operating",  -1),
-    ("1108", "短期貸墊款增減",              "operating",  -1),
-    ("1807", "什項資產增減",                "operating",  -1),
-    # 流動負債—增加=現金流入
-    ("2102", "應付款項增減",                "operating",  +1),
-    ("2103", "預收款項增減",                "operating",  +1),
-    # ── 二、投資活動 ──────────────────────────────────────────────
-    ("1202", "非流動金融資產增減",           "investing",  -1),
-    ("1204", "長期應收款增減",              "investing",  -1),
-    ("1207", "準備金增減",                 "investing",  -1),
-    ("1301", "土地增減",                   "investing",  -1),
-    ("1302", "土地改良物增減",              "investing",  -1),
-    ("1303", "房屋及建築增減",              "investing",  -1),
-    ("1304", "機械及設備增減",              "investing",  -1),
-    ("1305", "交通運輸設備增減",            "investing",  -1),
-    ("1306", "什項設備增減",               "investing",  -1),
-    ("1309", "購建中固定資產增減",          "investing",  -1),
-    # ── 三、籌資活動 ──────────────────────────────────────────────
-    ("2801", "遞延負債增減",               "financing",  +1),
-    ("2807", "什項負債增減",               "financing",  +1),
-    ("3101", "基金增減",                   "financing",  +1),
-    ("3201", "資本公積增減",               "financing",  +1),
-    ("3202", "特別公積增減",               "financing",  +1),
+    # ── 一、營業活動：非現金費用調整 ──────────────────────────────
+    ("1701", "無形資產攤銷（淨額減少≈攤銷）",    "operating",  +1),
+    ("1801", "遞延資產攤銷（淨額減少≈攤銷）",    "operating",  +1),
+    ("1207", "準備金提存（退休金/補償準備等）",   "operating",  +1),  # ★ 改為營業
+    # ── 一、營業活動：流動資產變動（增加=現金流出）──────────────────
+    ("1102", "流動金融資產增減",                "operating",  -1),
+    ("1103", "應收款項增減",                   "operating",  -1),
+    ("1104", "存貨增減",                       "operating",  -1),
+    ("1107", "預付款項增減",                   "operating",  -1),
+    ("1807", "什項資產增減（含暫付/存出保證金）", "operating",  -1),
+    # ── 一、營業活動：流動負債變動（增加=現金流入）──────────────────
+    ("2102", "應付款項增減",                   "operating",  +1),
+    ("2103", "預收款項增減",                   "operating",  +1),
+    ("2801", "遞延負債增減（遞延收入/補助款）",  "operating",  +1),  # ★ 改為營業
+    # ── 二、投資活動：不動產廠房及設備 ──────────────────────────────
+    ("1301", "土地增減",                       "investing",  -1),
+    ("1302", "土地改良物增減",                 "investing",  -1),
+    ("1303", "房屋及建築增減",                 "investing",  -1),
+    ("1304", "機械及設備增減",                 "investing",  -1),
+    ("1305", "交通及運輸設備增減",             "investing",  -1),
+    ("1306", "什項設備增減",                   "investing",  -1),
+    ("1309", "購建中固定資產增減",             "investing",  -1),  # ★ 13xx 改為投資
+    # ── 二、投資活動：其他長期資產 ──────────────────────────────────
+    ("1108", "短期貸墊款增減",                 "investing",  -1),  # ★ 改為投資
+    ("1202", "非流動金融資產增減",             "investing",  -1),
+    ("1204", "長期應收款增減",                 "investing",  -1),
+    # ── 三、籌資活動 ─────────────────────────────────────────────────
+    ("2807", "什項負債增減（長期融資性負債）",  "financing",  +1),
+    ("3101", "基金增減（政府撥補）",            "financing",  +1),
+    # 排除項（非現金或重複計算）：
+    #   3201 資本公積、3202 特別公積：賸餘內部提撥，非現金流
+    #   3301 累積賸餘：已以本期賸餘為起點，避免重複
+    #   3401 累積其他綜合餘絀：評價調整，非現金
 ]
 
 _ACTIVITY_LABEL = {
@@ -900,6 +922,15 @@ def _get_amount(d: dict, code_or_pfx: str) -> float:
     return sum(v for k, v in d.items() if k.startswith(code_or_pfx))
 
 
+# 刻意排除的科目（非現金或避免重複計算），但需在誤差說明中揭露其增減
+_CF_EXCLUDED = [
+    ("3201", "資本公積",          "由本期賸餘提撥，非現金流，已含於起點"),
+    ("3202", "特別公積",          "由本期賸餘提撥，非現金流，已含於起點"),
+    ("3301", "累積賸餘",          "與本期賸餘重複，已以本期賸餘為起點"),
+    ("3401", "累積其他綜合餘絀",   "金融資產評價調整，屬非現金項目"),
+]
+
+
 def summarize_cashflow(
     df_start: pd.DataFrame,
     df_end:   pd.DataFrame,
@@ -908,16 +939,16 @@ def summarize_cashflow(
     """
     以間接法推估現金流量。
 
-    Parameters
-    ----------
-    df_start : 期初平衡表 DataFrame
-    df_end   : 期末平衡表 DataFrame
-    surplus  : 本期賸餘(短絀)，單位億元（從收支餘絀表取）
-
     Returns
     -------
     list of dict，每筆含：
-        activity, label, amount(億元), is_subtotal, is_total
+        activity       : 'operating' | 'investing' | 'financing' | 'total' | 'unexplained'
+        label          : 顯示名稱
+        amount         : 金額（億元），正=流入，負=流出
+        is_subtotal    : 小計列
+        is_total       : 合計/現金餘額列
+        is_excluded    : 刻意排除的科目（顯示於誤差說明）
+        exclude_reason : 排除原因說明
     """
     start = _bs_to_dict(df_start)
     end   = _bs_to_dict(df_end)
@@ -926,69 +957,94 @@ def summarize_cashflow(
 
     # 本期賸餘作為營業活動起點
     items.append({
-        "activity": "operating",
-        "label":    "本期賸餘(短絀)",
-        "amount":   surplus,
-        "is_subtotal": False, "is_total": False,
+        "activity": "operating", "label": "本期賸餘(短絀)",
+        "amount": surplus, "is_subtotal": False, "is_total": False,
+        "is_excluded": False, "exclude_reason": "",
     })
 
     # 各調整科目
     for code, label, activity, sign in _CF_ITEMS:
         end_val   = _get_amount(end,   code)
         start_val = _get_amount(start, code)
-        delta = (end_val - start_val) * sign   # 正=現金流入，負=現金流出
+        delta = (end_val - start_val) * sign
         if abs(delta) < 0.001:
             continue
         items.append({
-            "activity": activity,
-            "label":    label,
-            "amount":   delta,
-            "is_subtotal": False, "is_total": False,
+            "activity": activity, "label": label,
+            "amount": delta, "is_subtotal": False, "is_total": False,
+            "is_excluded": False, "exclude_reason": "",
         })
 
-    # 加入各活動小計
+    # 各活動小計
     result = []
     for act in ["operating", "investing", "financing"]:
         act_items = [x for x in items if x["activity"] == act]
         subtotal  = sum(x["amount"] for x in act_items)
         result.extend(act_items)
         result.append({
-            "activity": act,
-            "label":    f"{_ACTIVITY_LABEL[act]} 小計",
-            "amount":   subtotal,
-            "is_subtotal": True, "is_total": False,
+            "activity": act, "label": f"{_ACTIVITY_LABEL[act]} 小計",
+            "amount": subtotal, "is_subtotal": True, "is_total": False,
+            "is_excluded": False, "exclude_reason": "",
         })
 
-    # 加入現金變動合計
+    # 現金期初期末（確定值）
     cash_start = _get_amount(start, "1101")
     cash_end   = _get_amount(end,   "1101")
-    net_change = cash_end - cash_start
-    result.append({
-        "activity": "total",
-        "label":    "現金及約當現金淨增減",
-        "amount":   net_change,
-        "is_subtotal": False, "is_total": True,
-    })
-    result.append({
-        "activity": "total",
-        "label":    "期初現金及約當現金",
-        "amount":   cash_start,
-        "is_subtotal": False, "is_total": True,
-    })
-    result.append({
-        "activity": "total",
-        "label":    "期末現金及約當現金",
-        "amount":   cash_end,
-        "is_subtotal": False, "is_total": True,
-    })
+    net_change = cash_end - cash_start        # ← 這是「確定的」現金淨增減
+
+    for label, amount in [
+        ("現金及約當現金淨增減（確定值）", net_change),
+        ("期初現金及約當現金",            cash_start),
+        ("期末現金及約當現金",            cash_end),
+    ]:
+        result.append({
+            "activity": "total", "label": label,
+            "amount": amount, "is_subtotal": False, "is_total": True,
+            "is_excluded": False, "exclude_reason": "",
+        })
+
+    # ── 誤差分析 ──────────────────────────────────────────────────────────────
+    # 三活動合計（推估值）
+    est_net = sum(x["amount"] for x in result if x.get("is_subtotal"))
+
+    # 刻意排除科目的實際增減（揭露用）
+    excluded_items = []
+    excluded_total = 0.0
+    for code, name, reason in _CF_EXCLUDED:
+        end_val   = _get_amount(end,   code)
+        start_val = _get_amount(start, code)
+        # 排除科目通常是淨資產，增加對現金影響為 0（非現金）
+        # 但若有變動仍需揭露，讓使用者知道這部分無法解釋
+        delta = end_val - start_val   # 原始增減，不加 sign（讓使用者自行判斷）
+        if abs(delta) < 0.001:
+            continue
+        excluded_items.append({
+            "activity": "unexplained", "label": f"{name}（{code}）",
+            "amount": delta, "is_subtotal": False, "is_total": False,
+            "is_excluded": True, "exclude_reason": reason,
+        })
+        excluded_total += delta
+
+    # 純粹不明誤差 = 確定現金增減 - 推估三活動合計 - 排除科目影響
+    # 排除科目因屬非現金，理論上不影響現金，純粹誤差應接近 0
+    pure_error = net_change - est_net
+
+    if excluded_items:
+        result.append({
+            "activity": "unexplained",
+            "label": "── 以下為刻意排除科目（非現金或避免重複） ──",
+            "amount": 0.0, "is_subtotal": False, "is_total": False,
+            "is_excluded": True, "exclude_reason": "區隔標題",
+        })
+        result.extend(excluded_items)
 
-    # 算誤差（三活動小計合計 vs 實際現金變動）
-    calc_net = sum(x["amount"] for x in result if x.get("is_subtotal"))
     result.append({
-        "activity": "check",
-        "label":    "推估誤差（三活動合計 − 實際現金增減）",
-        "amount":   calc_net - net_change,
+        "activity": "unexplained",
+        "label":    "推估誤差（確定現金增減 − 三活動合計）",
+        "amount":   pure_error,
         "is_subtotal": False, "is_total": False,
+        "is_excluded": False, "exclude_reason":
+            "接近 0 表示推估合理；偏大表示仍有科目未能分類或分類有誤",
     })
 
     return result