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