討論 #1460
是由 陳國瑋 於 27 天 前更新
> **REST 更新週期更新（#1424 DEC-032）**：四步驟結算流程與上月電費改為共用 Overview 的頁面首載、每 5 分鐘及手動刷新；不再使用本票下方較早的 15 分鐘獨立 timer。每個週期不另送 Billing request，帳務資料與其他 REST-owned sections 由同一份 `generatedAt` snapshot 更新；仍不新增帳務 WebSocket或任何結算 mutation。
## 討論目的
確認 Dashboard mockup 既有「結算流程」區塊在正式 V1 的顯示與資料需求。本票只定義 Dashboard 的唯讀呈現，不修改既有結算、帳單或請款作業。
## Source of Truth
Redmine attachment #1110 `a17-operations-dashboard.html` 的既有設計為「6 月結算流程」四步驟面板：
1. Connector 結算。
2. 門牌結算。
3. 帳務覆核。
4. 發票結算。
附件中的月份與數字是展示假資料；正式功能必須由 API 回傳實際資料。
## BIL-DEC-001：V1 沿用 Mockup 四步驟結算流程
**狀態：已確認（2026-09-03，Ken）**
### 使用者會看到什麼
- 保留 attachment #1110 的四列 layout、名稱與順序，不改成另一張「本月帳務摘要」卡。
- 標題格式維持「{資料年份} 年 {資料月份} 月結算流程」；資料期間依 BIL-DEC-002 由 Backend 回傳。
- 四列顯示內容：
1. **Connector 結算**：設備電量與費率計算的完成數／總數。
2. **門牌結算**：完成歸戶的門牌結算筆數。
3. **帳務覆核**：既有 Billing status 數量，例如 paid／pending。
4. **發票結算**：既有 Invoice status，例如 draft／pending／settled。
- 假月份、假數字及假狀態全部改由正式 Dashboard API 提供。
- 提供前往既有帳務功能的導覽；每列的實際連結目標另案逐題確認。
### Backend 要開發的內容
- 在 Dashboard overview read model 提供四列所需的唯讀彙整結果。
- 優先重用既有 settlement、billing、invoice repository／service 查詢概念，不複製帳務計算公式。
- Connector settlement、unit settlement、Billing status、Invoice status 必須分欄位回傳，不合併成新的共同業務狀態。
- 回傳資料月份、各列數值、原始 status code、顯示所需的 source status／updatedAt。
- 任一子來源失敗時，該區塊標示 partial／error，但不得拖垮 Dashboard 其他區塊。
- 所有查詢皆為 read-only；不得更新、重算或改變 settlement、billing、invoice、payment 狀態。
### Frontend 要開發的內容
- 依 attachment #1110 實作同一個四列 responsive 面板。
- 將月份、數字、status 與完成／待處理樣式綁定正式 API，而不是保留 fixture。
- 補齊 loading、empty、partial、error 與 `null` 狀態；未知值不得顯示成 0 或已完成。
- 狀態同時以文字與視覺樣式表達，不只使用顏色。
- 導向既有 `/bill/list`／`/invoice/list`，Dashboard 本身不提供修改操作。
## BIL-DEC-002：標題使用 Backend 回傳的最近結算資料期間
**狀態：已確認（2026-09-03，Ken）**
### 使用者會看到什麼
- 標題顯示 Backend 回傳的結算資料期間，例如「2026 年 8 月結算流程」。
- 這個月份代表畫面中四步驟資料所屬的結算期間，不等於使用者開啟 Dashboard 當下的日曆月份。
- 若 Backend 已有較新一期資料，即使該期仍為待處理、資料不完整或錯誤，仍顯示該期並照實呈現狀態；不得自動退回前一期來隱藏問題。
- 若新一期資料尚未建立，則顯示目前資料庫中最近一個已存在的結算期間。
- 若該案場完全沒有任何結算期間資料，整個區塊顯示 Empty state，不猜測月份，也不把未知值顯示為 0。
### Backend 要開發的內容
- 在四步驟結算流程 DTO 回傳 periodYear、periodMonth 與 timezone。
- Backend 依指定 buildingId 的實際結算資料決定最近期間；不得由 A17 特例、伺服器目前月份或 Frontend 日期推算。
- 最近期間即使為 pending／partial／error 仍是回傳期間；狀態與缺漏資料另外透過既有 status、source status 及 updatedAt 表達。
- 完全沒有結算期間資料時，回傳明確 Empty 語意；periodYear／periodMonth 可為 null，不得虛構一個月份。
- 本規則只新增 Dashboard read model 的查詢與回傳欄位，不改變既有月結排程、重算、補償、Billing 或 Invoice lifecycle。
### Frontend 要開發的內容
- Frontend 只負責把 Backend 回傳的 periodYear／periodMonth 格式化為標題。
- Frontend 不使用 Date、LocalDate 或「目前月份減一」等規則自行計算結算月份。
- 收到 Empty 語意或 null 期間時顯示無資料說明，不顯示推測月份。
- 收到 pending／partial／error 時保留 Backend 回傳的同一期間，並以文字狀態清楚呈現，不切回舊月份。
### 驗收例子
1. 9 月開啟 Dashboard，資料庫最新只有 8 月結算資料：顯示「2026 年 8 月結算流程」。
2. 最新 9 月資料已建立但狀態為 error：顯示「2026 年 9 月結算流程」及錯誤狀態，不退回 8 月。
3. 該案場從未產生結算期間資料：顯示 Empty state，不顯示「本月」或「上月」。
## BIL-DEC-003：四列維持純資訊，區塊底部提供兩個明確導覽
**狀態：已確認（2026-09-03，Ken）**
### 使用者會看到什麼
- Connector 結算、門牌結算、帳務覆核、發票結算四列只用來閱讀狀態與數量，不把整列做成可點擊元件。
- 區塊底部固定提供兩個文字明確的導覽：
1. 「查看帳單」前往既有 /bill/list。
2. 「查看請款／發票」前往既有 /invoice/list。
- 四列不顯示箭頭、hover click 樣式或其他會讓使用者誤以為可展開／可操作的提示。
- 使用者進入既有頁面後，才使用原頁面既有的查詢、篩選與操作能力；Dashboard 不承擔這些功能。
### Frontend 要開發的內容
- 在四步驟面板 footer 使用語意正確的 Link／anchor 元件實作兩個導覽。
- 兩個連結須支援鍵盤操作、可見的 focus 狀態與可理解的文字，不使用只有圖示的按鈕。
- route 由 Frontend 使用既有固定路徑；不從 Dashboard API payload 讀取 URL。
- 若使用者沒有目標頁既有權限，連結顯示方式須配合後續 Dashboard role／permission 決策；不得藉由 Dashboard 繞過既有授權。
### Backend 要開發的內容
- 不需要為這兩個連結增加 URL、route、label 或 navigation DTO 欄位。
- 不新增 row-specific drill-down endpoint，也不為四列建立新的明細查詢。
- Overview API 僅回傳 BIL-DEC-001／002 所需的唯讀結算資料與期間。
### V1 明確不包含
- 不讓四列各自連往意義不明或重複的頁面。
- 不新增 Connector 結算或門牌結算專用頁面。
- 不新增 Dashboard 專用帳單／發票 Drawer。
- 不為這兩個連結新增自訂 deep-link filter contract。
## 與「上月電費」KPI 的關係（KPI-DEC-001）
**狀態：已確認（2026-09-04，Ken；完整公式詳見 #1486）**
- 本區塊與 KPI 使用相同帳務來源，但回答不同問題：四步驟區塊顯示 Backend 找到的最近結算資料期間與流程狀態；KPI 固定顯示 building timezone 的上一個完整日曆月。
- KPI 金額只加總該案場、該月份的 `e_bill_settlement.cost_predict`，代表所有門牌帳單應收總額；paid／pending 均納入，不使用 Connector fee 或 Invoice totalFee。
- 上月任一門牌帳單尚未 COMPLETE 時，KPI 顯示 `—` 與完成筆數，不顯示部分合計、也不退回前一期。
- KPI card 導向同頁 `#billing`；四列仍維持純資訊，不因新增此導覽而變成可操作元件。
- 本關聯只新增 Dashboard read model 與顯示規則，不改變四步驟結算期間選擇、結算排程或帳務 lifecycle。
## V1 不開發
- 不新增「本月帳務摘要」版型。
- 不新增帳務趨勢圖或歷史月份比較。
- 不在 Dashboard 顯示住戶或逐筆帳單清單。
- 不在 Dashboard 提供付款、覆核、重算或修改 Invoice status。
- 不新增 Dashboard 專用帳務資料表、排程或 WebSocket。
## Acceptance Criteria
- [ ] 畫面保留四列及既定順序：Connector 結算、門牌結算、帳務覆核、發票結算。
- [ ] 展示年份、月份、數字與狀態均由正式 API 提供，不殘留 A17 fixture，也不由 Frontend 推算期間。
- [ ] 最新期間即使為 pending／partial／error 仍照實顯示；完全無期間資料時顯示 Empty。
- [ ] 四種資料語意不互相替代或混用。
- [ ] `null`／無資料與數值 0 有不同呈現。
- [ ] 單一帳務來源失敗時可顯示 partial，其他 Dashboard 區塊仍可使用。
- [ ] 上月電費 KPI 與四步驟區塊的期間語意可不同：KPI 固定上一完整日曆月，流程區塊使用最近已存在的結算期間。
- [ ] 上月帳單未全數 COMPLETE 時 KPI 顯示 `—` 與完成筆數，不顯示部分合計或前期金額。
- [ ] Dashboard 不送出任何帳務 mutation request。
- [ ] 四列不具 click affordance，區塊底部可分別導向既有 /bill/list 與 /invoice/list。
- [ ] Dashboard API 不回傳導覽 URL，亦不新增 row-specific drill-down endpoint。
## 更正紀錄
2026-09-03 曾將 Agent 新提出的「本月帳務摘要」誤述為 mockup 內容；該版提案及 cancelled 顯示問題均已撤回。本決策以 attachment #1110 的四步驟面板重新確認並取代前一版。
## 待確認事項
- [x] 標題與資料使用 Backend 回傳的最近結算資料期間；Frontend 不依日曆月份自行推算（BIL-DEC-002）。
- [x] 四列維持純資訊；區塊底部以「查看帳單」及「查看請款／發票」分別導向 /bill/list 與 /invoice/list（BIL-DEC-003）。
## 需求管理狀態
- Parent：#1422
- Requirement status：**本區塊需求已確認，待其他 Dashboard 區塊完成後整併**
- Confirmed decision：BIL-DEC-001、BIL-DEC-002、BIL-DEC-003
- Final specification：所有 Dashboard 區塊確認後再整併至 #1422 v1.0 文件
- Implementation tickets：需求鎖定後才建立 FE／BE／QA child issues
返回