討論 #1460
是由 陳國瑋 於 17 天 前更新
> **閱讀基準：** [主需求 #1422](https://redmine.sylksoft.com/issues/1422) 與 [HTML Mock v0.3／附件 #1117](https://redmine.sylksoft.com/attachments/1117)。以下沿用主票區塊編號，依畫面由上到下、由左到右說明。Mock 數字皆為假資料；功能適用所有案場，A17 不是固定規則。 **現行 REST 更新規則（#1424 DEC-032）**：四步驟結算流程與上月電費共用 Overview 的頁面首載、每 5 分鐘及手動刷新；不建立帳務專用 timer，也不另送 Billing request。帳務資料與其他 REST-owned sections 由同一份 `generatedAt` snapshot 更新；不新增帳務 WebSocket 或任何結算 mutation。
## 08｜結算流程：本票要完成什麼 討論目的
**讓使用者知道：最近有結算資料的那一期，四個步驟完成到哪裡。** 這是 確認 Dashboard 底部右側的唯讀面板，不是「本月帳務摘要」，也不在這裡執行結算。 mockup 既有「結算流程」區塊在正式 V1 的顯示與資料需求。本票只定義 Dashboard 的唯讀呈現，不修改既有結算、帳單或請款作業。
Mock v0.3 顯示「8 月結算流程」；正式版標題為「{資料年份} ## 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 回傳，不能固定成 Mock 月份。 回傳。
- 四列顯示內容：
1. **Connector 結算**：設備電量與費率計算的完成數／總數。
2. **門牌結算**：完成歸戶的門牌結算筆數。
3. **帳務覆核**：既有 Billing status 數量，例如 paid／pending。
4. **發票結算**：既有 Invoice status，例如 draft／pending／settled。
- 假月份、假數字及假狀態全部改由正式 Dashboard API 提供。
- 提供前往既有帳務功能的導覽；每列的實際連結目標另案逐題確認。
```text ### Backend 要開發的內容
- 在 Dashboard overview read model 提供四列所需的唯讀彙整結果。
底部左側：07 30 日充電用量 底部右側：08 結算流程
│
├─ - 優先重用既有 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 狀態。
## 1. 依畫面由上到下看欄位 ### Frontend 要開發的內容
| 位置 | 使用者看到什麼 | 正式資料含意 | v0.3 假資料 | - 依 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 月結算流程 | 月結算流程」。
| 第 1 列 | Connector 結算 | 設備電量與費率計算的完成數／總數 | 11 / 12 | - 這個月份代表畫面中四步驟資料所屬的結算期間，不等於使用者開啟 Dashboard 當下的日曆月份。
| 第 2 列 | 門牌結算 | 完成歸戶的門牌結算筆數與總數 | 10 / 11 | - 若 Backend 已有較新一期資料，即使該期仍為待處理、資料不完整或錯誤，仍顯示該期並照實呈現狀態；不得自動退回前一期來隱藏問題。
| 第 3 列 | 帳務覆核 | 既有 Billing 狀態分布，例如 paid／pending | 7 paid、4 pending；進行中 | - 若新一期資料尚未建立，則顯示目前資料庫中最近一個已存在的結算期間。
| 第 4 列 | 發票結算 | 既有 Invoice 狀態，例如 draft／pending／settled | draft；未完成 | - 若該案場完全沒有任何結算期間資料，整個區塊顯示 Empty state，不猜測月份，也不把未知值顯示為 0。
### Backend 要開發的內容
- 在四步驟結算流程 DTO 回傳 periodYear、periodMonth 與 timezone。
| Footer | 查看帳單、查看請款／發票 | 前往既有管理頁 | **本版 Mock 尚未畫出，見第 3 節。** |
四類資料各自保留欄位與原始 - Backend 依 current-building resolver 所解析之 Building 的實際結算資料決定最近期間；Dashboard request 不傳 `buildingId`，也不得由 A17 特例、伺服器目前月份或 Frontend 日期推算。
- 最近期間即使為 pending／partial／error 仍是回傳期間；狀態與缺漏資料另外透過既有 status、source status code，不能合併成新業務狀態，也不能把 Billing 與 及 updatedAt 表達。
- 完全沒有結算期間資料時，回傳明確 Empty 語意；periodYear／periodMonth 可為 null，不得虛構一個月份。
- 本規則只新增 Dashboard read model 的查詢與回傳欄位，不改變既有月結排程、重算、補償、Billing 或 Invoice 的數值互相替代。（BIL-DEC-001） lifecycle。
## 2. 標題月份怎麼決定 ### Frontend 要開發的內容
- Frontend 只負責把 Backend 只查目前案場，從已存在的結算資料中找最近期間，再回傳 periodYear、periodMonth、timezone。FE 只格式化，不用瀏覽器日期或「目前月份減一」推算。（BIL-DEC-002）
| 例子 | 應顯示 | 不可做 | 回傳的 periodYear／periodMonth 格式化為標題。
|---|---|---| - Frontend 不使用 Date、LocalDate 或「目前月份減一」等規則自行計算結算月份。
| - 收到 Empty 語意或 null 期間時顯示無資料說明，不顯示推測月份。
- 收到 pending／partial／error 時保留 Backend 回傳的同一期間，並以文字狀態清楚呈現，不切回舊月份。
### 驗收例子
1. 9 月開啟，資料庫最新只有 月開啟 Dashboard，資料庫最新只有 8 月資料 | 2026 月結算資料：顯示「2026 年 8 月結算流程 | 為配合今天而虛構 9 月資料。 | 月結算流程」。
| 2. 最新 9 月資料已建立但為 pending／partial／error | 2026 月資料已建立但狀態為 error：顯示「2026 年 9 月結算流程，照實顯示狀態 | 退回 月結算流程」及錯誤狀態，不退回 8 月來隱藏問題。 | 月。
| 案場從未產生任何結算期間 | 明確無資料（Empty），期間可為 null | 猜成「本月／上月」，或把未知筆數顯示成 0。 | 3. 該案場從未產生結算期間資料：顯示 Empty state，不顯示「本月」或「上月」。
案場由 Backend 的唯一 enabled Building resolver 決定；Dashboard request 不傳 buildingId，不使用 A17 特例。本查詢不建立新一期資料、不啟動月結、不重算或補償。
## 3. 四列不可點擊，操作只留在 Footer BIL-DEC-003：四列維持純資訊，區塊底部提供兩個明確導覽
四列只有狀態與數量，**不可點擊**，不顯示箭頭、可點擊 hover 或可展開暗示。使用者需要查看明細時，由 Footer 前往既有頁面。（BIL-DEC-003） **狀態：已確認（2026-09-03，Ken）**
| 連結文字 | 固定目的地 | 開發要求 | ### 使用者會看到什麼
- Connector 結算、門牌結算、帳務覆核、發票結算四列只用來閱讀狀態與數量，不把整列做成可點擊元件。
|---|---|---| - 區塊底部固定提供兩個文字明確的導覽：
1. 「查看帳單」前往既有 /bill/list。
2. 「查看請款／發票」前往既有 /invoice/list。
| 查看帳單 | /bill/list | 原生 Link／anchor，可用 Tab、Enter，有清楚焦點。 | - 四列不顯示箭頭、hover click 樣式或其他會讓使用者誤以為可展開／可操作的提示。
| 查看請款／發票 | /invoice/list | 同上；目的頁沿用原有權限。 | - 使用者進入既有頁面後，才使用原頁面既有的查詢、篩選與操作能力；Dashboard 不承擔這些功能。
FE 維護固定路徑，不從 ### Frontend 要開發的內容
- 在四步驟面板 footer 使用語意正確的 Link／anchor 元件實作兩個導覽。
- 兩個連結須支援鍵盤操作、可見的 focus 狀態與可理解的文字，不使用只有圖示的按鈕。
- route 由 Frontend 使用既有固定路徑；不從 Dashboard API payload 讀取 URL、route URL。
- 若使用者沒有目標頁既有權限，連結顯示方式須配合後續 Dashboard role／permission 決策；不得藉由 Dashboard 繞過既有授權。
### Backend 要開發的內容
- 不需要為這兩個連結增加 URL、route、label 或 label；Backend 不新增導覽 DTO、逐列 navigation DTO 欄位。
- 不新增 row-specific drill-down API、專用頁面、帳務 Drawer 或自訂列表篩選契約。 endpoint，也不為四列建立新的明細查詢。
- Overview API 僅回傳 BIL-DEC-001／002 所需的唯讀結算資料與期間。
**Mock 差異：** 兩個 Footer 入口已在 BIL-DEC-003 確認，但附件 #1117 尚未畫出。工程實作仍須依這項既有需求提供入口；不可誤稱它已出現在 Mock，也不是本次新增範圍。四列不因補 Footer 而變成可操作元件。 ### V1 明確不包含
- 不讓四列各自連往意義不明或重複的頁面。
- 不新增 Connector 結算或門牌結算專用頁面。
- 不新增 Dashboard 專用帳單／發票 Drawer。
- 不為這兩個連結新增自訂 deep-link filter contract。
## 4. 別與「上月電費」KPI 混淆 與「上月電費」KPI 的關係（KPI-DEC-001）
上方第 03-6 張 **狀態：已確認（2026-09-04，Ken；完整公式詳見 #1486）**
- 本區塊與 KPI 的規則由 #1486 KPI-DEC-001 定義：
| 比較 | 本票：08 結算流程 | #1486：03-6 上月電費 | 使用相同帳務來源，但回答不同問題：四步驟區塊顯示 Backend 找到的最近結算資料期間與流程狀態；KPI 固定顯示 building timezone 的上一個完整日曆月。
|---|---|---|
| 要回答 | 各步驟完成到哪裡？ | 上月門牌帳單應收電費共多少？ |
| 期間 | 最近已存在的結算期間 | 案場時區的上一完整日曆月 |
| 金額來源 | 四列依各自結算／Billing／Invoice 資料呈現 | e_bill_settlement.cost_predict；paid／pending 均納入 |
| 不完整時 | 保留該期，分列顯示狀態 | 任一帳單未 COMPLETE，金額為 null，顯示「—」與完成筆數 |
| 點擊 | 四列不可點；由 Footer 去列表 | 整張 - KPI 定位同頁 #billing |
兩區期間可能不同。KPI 不用 金額只加總該案場、該月份的 `e_bill_settlement.cost_predict`，代表所有門牌帳單應收總額；paid／pending 均納入，不使用 Connector fee 或 Invoice totalFee 代算、不顯示部分合計、不退回前期；點進本區不代表兩者月份必須相同。
## 5. 更新與異常狀態
本區與上月電費均隨**共用 Overview：首載、每 5 分鐘、手動刷新**更新；每輪只取一次 GET /api/dashboard/overview，不另設 Billing request／timer，也不新增帳務 WebSocket。（#1424 DEC-032）
| 情況 | FE 呈現 | Backend 責任 | totalFee。
|---|---|---| - 上月任一門牌帳單尚未 COMPLETE 時，KPI 顯示 `—` 與完成筆數，不顯示部分合計、也不退回前一期。
| 載入中 | Loading，不先填 0 或完成圖示 | 回應前不提供假成功狀態。 | - KPI card 導向同頁 `#billing`；四列仍維持純資訊，不因新增此導覽而變成可操作元件。
| 成功、沒有任何期間 | Empty，說明沒有結算資料 | 明確 Empty 語意，年月可為 null。 |
| 成功、真實數字為 0 | 顯示 0 | 0 與 null 分開。 |
| 部分子來源失敗 | 保留可確認內容，標示不完整 | 分來源 status／updatedAt；不要使其他 - 本關聯只新增 Dashboard 區塊失敗。 |
| 無法取得／未知 | Error 或「—」，不顯示已完成 | 未知值為 null，保留來源狀態。 |
| 後續刷新失敗 | 依 #1424 共用規則保留同案場最後成功資料與時間，清楚標示失敗／過期 | 不把舊資料標為本次成功資料。 | read model 與顯示規則，不改變四步驟結算期間選擇、結算排程或帳務 lifecycle。
狀態同時用文字與視覺樣式表達，不能只靠顏色。正式版 API 失敗不退回 fixture。
## 6. 工程分工 V1 不開發
| 負責範圍 | 交付內容 | - 不新增「本月帳務摘要」版型。
|---|---| - 不新增帳務趨勢圖或歷史月份比較。
| Backend／API | 四步驟 read-only aggregation／DTO、最近資料期間查詢、原始狀態、source status／updatedAt；重用既有 repository／service 查詢概念，不複製結算公式。 | - 不在 Dashboard 顯示住戶或逐筆帳單清單。
| FE | 四列 responsive 面板、API 綁定、年月格式、Loading／Empty／Partial／Error／null、兩個 Footer 連結與鍵盤可用性。 | - 不在 Dashboard 提供付款、覆核、重算或修改 Invoice status。
| 權限 | 沿用 #1424 DEC-030 的 dashboard function；列表入口與目的頁不繞過既有授權。 |
| QA | 驗證期間選擇、四類資料不混用、部分失敗隔離、導覽與無 mutation。 | - 不新增 Dashboard 專用帳務資料表、排程或 WebSocket。
**V1 不做：** 本月帳務摘要、帳務趨勢／歷史比較、住戶／逐筆帳單清單、付款／覆核／重算／修改發票狀態、Dashboard 專用帳務表或排程。
## 7. 驗收清單 Acceptance Criteria
- [ ] 標題與四列名稱、順序符合第 1 節，年月／數字／狀態來自 API。 畫面保留四列及既定順序：Connector 結算、門牌結算、帳務覆核、發票結算。
- [ ] 第 2 節三個期間例子正確；新一期 error 不退回前期，無資料不猜月份。 展示年份、月份、數字與狀態均由正式 API 提供，不殘留 A17 fixture，也不由 Frontend 推算期間。
- [ ] 四類資料分欄位，null 不當 0／已完成；單一來源失敗不拖垮其他區塊。 最新期間即使為 pending／partial／error 仍照實顯示；完全無期間資料時顯示 Empty。
- [ ] 四列沒有可點擊暗示；兩個 Footer 連結可用滑鼠／鍵盤，且沿用既有權限。 四種資料語意不互相替代或混用。
- [ ] API 不新增導覽 URL、逐列明細 API 或任何帳務 mutation。 `null`／無資料與數值 0 有不同呈現。
- [ ] 單一帳務來源失敗時可顯示 partial，其他 Dashboard 區塊仍可使用。
- [ ] 上月電費 KPI 與流程期間可不同；上月金額未全數 與四步驟區塊的期間語意可不同：KPI 固定上一完整日曆月，流程區塊使用最近已存在的結算期間。
- [ ] 上月帳單未全數 COMPLETE 時不顯示部分合計或舊月份。 時 KPI 顯示 `—` 與完成筆數，不顯示部分合計或前期金額。
- [ ] 共用首載／5 分鐘／手動 Overview，無帳務專用 timer／WebSocket／fixture fallback。 Dashboard 不送出任何帳務 mutation request。
- [ ] 四列不具 click affordance，區塊底部可分別導向既有 /bill/list 與 /invoice/list。
- [ ] Dashboard API 不回傳導覽 URL，亦不新增 row-specific drill-down endpoint。
## 8. 決策與更正索引 更正紀錄
| 決策 | 已確認日期 | 本文位置 |
|---|---|---|
| BIL-DEC-001 四步驟面板 | 2026-09-03 | 第 1、5、6 節 |
| BIL-DEC-002 最近結算資料期間 | 2026-09-03 | 第 2 節 |
| BIL-DEC-003 純資訊列與 Footer | 2026-09-03 | 第 3 節 |
| KPI-DEC-001 上月電費關聯 | 2026-09-04 | 第 4 節；公式由 #1486 負責 |
2026-09-03 曾把「本月帳務摘要」誤述成 Mock 既有內容，該提案及 曾將 Agent 新提出的「本月帳務摘要」誤述為 mockup 內容；該版提案及 cancelled 顯示問題已撤回。初始依據為附件 顯示問題均已撤回。本決策以 attachment #1110 的四步驟面板；目前視覺對照改用 #1117，舊版不刪除。早期「每列連結待確認」已由 BIL-DEC-003 定案，不再是待決事項。 的四步驟面板重新確認並取代前一版。
## 需求管理與本次編輯 待確認事項
- 本票仍是已確認需求的追蹤票，不代表已完成開發或通過測試；指派、狀態、進度、附件與父子關係均維持原狀。 [x] 標題與資料使用 Backend 回傳的最近結算資料期間；Frontend 不依日曆月份自行推算（BIL-DEC-002）。
- 全 [x] 四列維持純資訊；區塊底部以「查看帳單」及「查看請款／發票」分別導向 /bill/list 與 /invoice/list（BIL-DEC-003）。
## 需求管理狀態
- Parent：#1422
- Requirement status：**本區塊需求已確認，待其他 Dashboard 完成一致性 review 後，才依 區塊完成後整併**
- Confirmed decision：BIL-DEC-001、BIL-DEC-002、BIL-DEC-003
- Final specification：所有 Dashboard 區塊確認後再整併至 #1422 DOC-DEC-001 發布同版號 PDF／Markdown／HTML 套件；現有 v0.3 Draft 不覆寫，本次不發布新版附件。 v1.0 文件
- 2026-09-14：僅重整 Description、說明與排版，將已確認決策併入對應畫面／工程工作；決策編號保留供追溯。E2E impact：No catalog change（沒有修改產品行為、公式或 API 契約）；功能實作時仍須遵循主票與本票驗收。
Implementation tickets：需求鎖定後才建立 FE／BE／QA child issues
返回