EMS

Feature #1417

是由 陳國瑋 於 2 天 前更新

## 1. 目的 

 提供一套「帳單人工補正」功能，處理因 MeterValue 缺漏、跨帳務邊界分攤資料不足、Tariff 缺漏、起訖錨點不可信或其他資料異常而無法自動完成的帳單。 缺漏、跨電價邊界資料不足、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. 3. 功能範圍 

 ### 4.1 3.1 異常帳單清單 

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

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

 ### 4.2 3.2 人工補正 

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

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

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

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

 ### 4.3 3.3 試算與確認 

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

 ### 4.4 3.4 狀態與權限 

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

 ### 4.5 3.5 稽核紀錄 

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

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

 ## 5. 4. FE／BE 範圍 

 ### Backend 

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

 ### Frontend 

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

 ## 6. 5. 不在本票範圍 

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

 ## 7. 6. 驗收條件 

 - [ ] 可查出 #1416 標記為資料不完整的 DRAFT 帳單及阻擋原因。 
 - [ ] 可信 `meterStart`／`meterStop` 的交易總量固定等於起訖差，且所有 bucket 分配總和與其一致。 
 - [ ] 單一 billing bucket、終點差距不超過 10 Wh、排除異常點後維持單調且不跨邊界時，可自動以 `meterStop` 調和並完成計算。 
 - [ ] 自動調和不修改原始 MeterValue／Transaction，並留下 warning／issue 稽核。 
 - [ ] 終點差距大於 10 Wh 時不得自動完成，必須進入人工介入。 
 - [ ] 跨 bucket 且無法安全分配時，不得標記計算完整。 
 - [ ] 授權人員可針對單一異常建立可稽核的人工補正項。 
 - [ ] 人工補正不會修改原始 MeterValue／Transaction。 
 - [ ] 儲存前可看到補正前後的總度數、bucket 分配、費用、服務費及月總額差異。 儲存前可看到補正前後的度數、費用、服務費及月總額差異。 
 - [ ] 確認補正後會使用共用計價引擎重新彙總，不會重複計費。 
 - [ ] 尚有未處理的阻擋性異常時，不得標記計算完整或送交財務審核。 
 - [ ] 補正完成後帳單仍維持既有 DRAFT／pending 狀態，必須再走既有財務審核流程。 補正完成後帳單仍為 DRAFT，必須再走既有財務審核流程。 
 - [ ] 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`。 E2E，驗證人工補正、金額重算、權限、狀態保護及冪等。 

 ## 8. 7. 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. 8. 關聯需求 

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

返回