EMS

1. 目的¶

提供一套「帳單人工補正」功能，處理因 MeterValue 缺漏、跨帳務邊界分攤資料不足、Tariff 缺漏、起訖錨點不可信或其他資料異常而無法自動完成的帳單。

本功能承接 #1416 的異常處理結果：#1416 負責依下列計價模型自動計算、調和或標記阻擋性異常；本票提供授權人員檢視異常、補上可稽核的計價依據，使帳單恢復完整後再進入既有財務審核流程。

2. 計價模型與自動／人工邊界¶

2.1 交易總用電量¶

• 當 meterStart 與 meterStop 可信時，Transaction 總用電量固定為 meterStop - meterStart。
• 中間 MeterValue 不得改變 Transaction 總用電量；其用途是把總量分配到不同帳務月份、Tariff 版本或尖／離峰等 billing bucket。
• 分段配置後的各 bucket 用電量總和必須等於 Transaction 總用電量；不可因區段捨入、缺點或重複讀值而多算或少算。
• 若整筆 Transaction 全程只落在單一 billing bucket，中間 MeterValue 的細微波動不應改變總度數或金額。

2.2 10 Wh 自動調和上限¶

• 終點 MeterValue 與 meterStop 的差距不超過 10 Wh，且移除最後異常 MeterValue 後序列維持單調、沒有跨帳務月份／Tariff／尖離峰邊界，也沒有其他錨點衝突時，以 meterStop 為權威值自動調和。
• 自動調和後可將計算狀態標記為 COMPLETE，但必須保留原始資料及一筆可查核的 warning／issue 紀錄。
• 10 Wh 必須使用具名設定 ems.branch.billing.meterReconciliationToleranceWh（預設值 10），不得在流程中散落 magic number。
• 差距 大於 10 Wh 一律進入人工介入，不得由系統自行推定讀值。即使整筆交易只屬於單一 bucket，人工人員仍需確認 meterStart／meterStop 是否可信；若可信，可確認使用起訖差作為總量，無須偽造中間 MeterValue。

2.3 必須阻擋並人工處理的情況¶

下列情況維持 PENDING_DATA 或 ERROR，不得自動標記計算完整：

• 終點差距大於 10 Wh。
• meterStart、meterStop 本身缺漏、倒退、互相矛盾或無法證明可信。
• Transaction 跨 billing bucket，但中間 MeterValue 不足以安全決定各 bucket 分配。
• Tariff 版本、時段或帳務邊界不明。
• 排除異常點後仍不單調，或存在其他會改變總量／分攤結果的衝突。

3. 現況核對¶

• 後端已有 POST /api/settlement/calculate，但只能依年月重算整個月份。
• Branch Admin FE 未使用上述重算 API。
• 現有請款頁只能查詢請款資料及切換請款單狀態。
• 目前沒有針對單一異常帳單／Connector／Transaction 補正用電量與計價依據的功能。
• 目前也沒有補正前後差額預覽、異常解除確認及完整人工補正稽核紀錄。

因此，現有功能不能處理「原始 MeterValue 持續無法補齊，但帳單仍需由人工確認完成」的情境。

4. 功能範圍¶

4.1 異常帳單清單¶

Branch Admin 提供「資料不完整帳單」清單，至少顯示：

• 帳務年月、門牌、Connector、idTag、Transaction。
• meterStart、meterStop、起訖差、終點 MeterValue、差距 Wh。
• 自動計算出的總度數、billing bucket 分配與金額。
• 異常類型與說明，例如 MeterValue 缺漏、負增量、衝突讀值、Tariff 缺漏。
• 異常狀態、最後自動重算時間與最後人工處理人。

4.2 人工補正¶

授權人員可針對異常項目建立人工補正資料：

• 確認採用的交易總用電量，並標示依據是可信的起訖錨點、設備紀錄或其他佐證。
• 必要時補正跨 billing bucket 的用電量分配。
• 適用的計價時段／Tariff 版本／單價等計價依據。
• 補正原因、處理說明與必要佐證。
• 金額原則上由系統依補正後總量、bucket 分配及計價依據計算，不直接任意輸入總帳金額。

人工補正不得修改或偽造原始 Transaction、MeterValue；必須以獨立 correction／overlay 紀錄保存。

若沒有足夠資料可證明實際用電量或 bucket 分配，不得憑空建立 MeterValue。應維持帳單阻擋，或另走財務調整／後續補收流程。

4.3 試算與確認¶

• 儲存前顯示補正前、補正項目及補正後的總度數、bucket 分配、金額與月總額差異。
• 補正資料可在未確認前修改或刪除。
• 確認後重新計算 Connector Settlement、門牌帳單、服務費與月總額。
• 同一補正操作重送不得重複計費。
• 所有阻擋性異常都已處理後，才可將「計算狀態」標記為 COMPLETE。
• 計算完整不等於財務核准；帳單仍維持既有 DRAFT／pending 流程，再依既有流程送交財務審核。

4.4 狀態與權限¶

• 僅具備指定帳務補正權限的 Branch Admin／財務角色可操作。
• 僅 DRAFT 或退回重審的帳單可補正。
• 待財務審核的帳單若需補正，必須先退回 DRAFT。
• SETTLED、PAID、OVERDUE 帳單不得直接修改；應另走調整項或後續補收流程。
• 同一帳單同時被兩人操作時，後提交者不得覆蓋較新的資料。

4.5 稽核紀錄¶

每次自動調和或人工補正需保存：

• 原始異常、自動計算結果與是否命中 10 Wh 規則。
• 原始 meterStart、meterStop、MeterValue 不可變快照／引用。
• 補正前後的總度數、bucket 分配、單價、金額及月總額。
• 操作者、操作時間、原因、佐證與確認者。
• 新增、修改、刪除、確認及退回等完整歷程。

5. FE／BE 範圍¶

Backend¶

• 異常帳單與異常明細查詢 API。
• 人工補正草稿、試算、修改、刪除與確認 API。
• 權限、狀態轉換、併發及冪等保護。
• 補正資料、試算快照與操作稽核資料表。
• 與 #1416 分段計價引擎及月結算彙總整合。
• 共用「起訖總量錨點 + billing bucket 分配」演算法，並驗證分配總和等於起訖差。

Frontend¶

• 資料不完整帳單清單與篩選。
• 異常原因、原始 MeterValue／自動計算結果檢視。
• 人工補正輸入與差額試算。
• 確認補正、退回修改及操作歷程檢視。
• 無權限或帳單狀態不允許時，不顯示可編輯操作。

6. 不在本票範圍¶

• 直接修改原始 MeterValue 或 Transaction。
• 直接改寫已結算、已付款或逾期帳單。
• 在沒有佐證時推測或偽造中間 MeterValue。
• 自動補收 A17 transaction 375 漏列的 5.070 kWh／約 20.18 元；該案仍須由財務另行決定。

7. 驗收條件¶

• 可查出 #1416 標記為資料不完整的 DRAFT 帳單及阻擋原因。
• 可信 meterStart／meterStop 的交易總量固定等於起訖差，且所有 bucket 分配總和與其一致。
• 單一 billing bucket、終點差距不超過 10 Wh、排除異常點後維持單調且不跨邊界時，可自動以 meterStop 調和並完成計算。
• 自動調和不修改原始 MeterValue／Transaction，並留下 warning／issue 稽核。
• 終點差距大於 10 Wh 時不得自動完成，必須進入人工介入。
• 跨 bucket 且無法安全分配時，不得標記計算完整。
• 授權人員可針對單一異常建立可稽核的人工補正項。
• 人工補正不會修改原始 MeterValue／Transaction。
• 儲存前可看到補正前後的總度數、bucket 分配、費用、服務費及月總額差異。
• 確認補正後會使用共用計價引擎重新彙總，不會重複計費。
• 尚有未處理的阻擋性異常時，不得標記計算完整或送交財務審核。
• 補正完成後帳單仍維持既有 DRAFT／pending 狀態，必須再走既有財務審核流程。
• SETTLED、PAID、OVERDUE 帳單無法直接補正。
• 所有補正及狀態操作均留下完整稽核紀錄。
• Backend 與 Branch Admin FE 均完成。
• 新增 production regression E2E，驗證自動調和、人工補正、總量守恆、金額重算、權限、狀態保護及冪等。
• A17 transaction 772 regression：meterStart=480050 Wh、最後 MeterValue 514310 Wh、meterStop=514309 Wh，全程單一 OFF_PEAK bucket；應以起訖差 34259 Wh 計費、保留 1 Wh 自動調和稽核，且計算狀態為 COMPLETE。

8. E2E Impact¶

• Classification：Add
• Domain：Billing／Settlement／Audit／Permission
• Priority：P0
• Status：實作完成前為 Gap
• Trigger：Billing、Settlement、Permission、Release、Hotfix
• 最低案例：
  • 10 Wh 內單一 bucket 自動調和成功。
  • 10 Wh 內但跨 bucket／非單調時維持阻擋。
  • 大於 10 Wh 時進入人工介入。
  • 人工補正後總量守恆、重算與冪等。
  • 原始 Transaction／MeterValue 不可變。

9. 關聯需求¶

• #1416 月結算依帳務月份與 MeterValue 計費區段正確計費