討論 #1460
是由 陳國瑋 於 28 天 前更新
## 討論目的
確認 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，不顯示「本月」或「上月」。
## V1 不開發
- 不新增「本月帳務摘要」版型。
- 不新增帳務趨勢圖或歷史月份比較。
- 不在 Dashboard 顯示住戶或逐筆帳單清單。
- 不在 Dashboard 提供付款、覆核、重算或修改 Invoice status。
- 不新增 Dashboard 專用帳務資料表、排程或 WebSocket。
## Acceptance Criteria
- [ ] 畫面保留四列及既定順序：Connector 結算、門牌結算、帳務覆核、發票結算。
- [ ] 展示年份、月份、數字與狀態均由正式 展示月份、數字與狀態均由正式 API 提供，不殘留 A17 fixture，也不由 Frontend 推算期間。 fixture。
- [ ] 最新期間即使為 pending／partial／error 仍照實顯示；完全無期間資料時顯示 Empty。
- [ ] 四種資料語意不互相替代或混用。
- [ ] `null`／無資料與數值 0 有不同呈現。
- [ ] 單一帳務來源失敗時可顯示 partial，其他 Dashboard 區塊仍可使用。
- [ ] Dashboard 不送出任何帳務 mutation request。
- [ ] 可導向既有帳務頁。
## 更正紀錄
2026-09-03 曾將 Agent 新提出的「本月帳務摘要」誤述為 mockup 內容；該版提案及 cancelled 顯示問題均已撤回。本決策以 attachment #1110 的四步驟面板重新確認並取代前一版。
## 待確認事項
- [x] 標題與資料使用 Backend 回傳的最近結算資料期間；Frontend 不依日曆月份自行推算（BIL-DEC-002）。 [ ] 標題與資料應顯示「目前日曆月份」，還是「最近一個可結算月份」？
- [ ] 四列各自應導向哪一個既有頁面？
## 需求管理狀態
- Parent：#1422
- Requirement status：**待確認（剩餘：四列導覽方式）** status：**待確認**
- Confirmed decision：BIL-DEC-001、BIL-DEC-002 decision：BIL-DEC-001
- Final specification：所有 Dashboard 區塊確認後再整併至 #1422 v1.0 文件
- Implementation tickets：需求鎖定後才建立 FE／BE／QA child issues
返回