討論 #1460
是由 陳國瑋 於 28 天 前更新
## 討論目的 目的
確認 定義 Dashboard mockup 既有「結算流程」區塊在正式 V1 的顯示規則。本票目前只做需求釐清，不代表已確認要改版。 首頁的「當月帳務摘要」顯示內容。此區塊只協助管理者快速看出本月是否有待處理帳務，並導向既有帳務頁；不在 Dashboard 重做結算、帳單或請款功能。
## Mockup 原始內容（Source of Truth） BIL-DEC-001：V1 使用單張唯讀帳務摘要卡
Redmine attachment #1110 `a17-operations-dashboard.html` 實際包含一個標題為「6 月結算流程」的四步驟面板： **狀態：已確認（2026-09-03，Ken）**
### 使用者會看到什麼
首頁只顯示一張「本月帳務摘要」卡，內容分成三個既有資料維度：
1. Connector 結算：設備電量與費率計算，範例 `11 / 11`。 **結算計算狀態（Settlement calculation status）**
- 顯示既有 `COMPLETE`、`PENDING_DATA`、`ERROR` 數量或摘要。
- 用途是判斷結算資料是否完整，不代表帳單是否已付款。
2. 門牌結算：私人與公用費用歸戶，範例 `11 筆`。 **帳單狀態（Billing status）**
- 顯示既有 `paid`、`pending`、`overdue` 數量。
- 三種狀態必須分開，不能只顯示一個含糊的「待處理總數」。
3. 帳務覆核：範例 `7 paid・4 pending`，顯示「進行中」。 **請款／發票結算狀態（Invoice status）**
- 顯示既有 `draft`、`pending`、`settled` 狀態。
- 此狀態不得與 Billing status 或 calculation status 混為同一套流程狀態。
畫面提供前往既有帳務頁的連結。既有路由為：
- 帳單清單：`/bill/list`
4. 發票結算：範例狀態 `draft`，顯示「未完成」。 - 請款／發票結算：`/invoice/list`
Mockup 另在 Needs Attention 區顯示「結算待確認／6 月帳務流程未完成」。附件中沒有名為「本月帳務摘要」的三行摘要卡。 ### 顯示範例
```text
本月帳務摘要｜2026 年 9 月
結算資料：Complete 11、Pending data 0、Error 0
住戶帳單：Paid 7、Pending 4、Overdue 0
請款狀態：Draft
[查看帳務]
```
範例只說明資訊層級，不代表正式文案或固定筆數。
## 更正紀錄 Backend 要開發的內容
2026-09-03 的前一版需求誤把 Agent 新提出的「本月帳務摘要」方案描述成 mockup 既有內容，造成 Ken 在錯誤前提下回覆同意。因此：
- 前一版 `BIL-DEC-001` 不視為已確認，亦不得交付 FE／BE 實作。 在 Dashboard overview read model 中彙整當月結算計算狀態、Billing status counts 與 Invoice status。
- `cancelled` 顯示問題一併撤回，目前不需要回答。 優先重用既有 `/api/bills/statistics` 查詢概念及既有 settlement／invoice repository；不得複製另一套帳務計算公式。
- Parent #1422 與架構票 #1424 已恢復為「帳務區塊待本票確認」。 三種 status enum 分開回傳，不建立新的共同 enum，也不把未知值轉成正常或 0。
- 本票維持 `New／0%`。 任一帳務來源讀取失敗時，該區塊回傳 partial／error source status，不影響 Dashboard 其他區塊。
- 本區塊為 read-only，不更新 settlement、billing、invoice 或 payment 資料。
- 金額若未來納入，必須使用 BigDecimal／decimal string；但 BIL-DEC-001 目前只確認狀態與數量。
## 目前尚未定案 Frontend 要開發的內容
以下三個方向尚未選擇：
1. 完全沿用 attachment #1110 的四步驟「結算流程」。 - 顯示單張 responsive 摘要卡，清楚分隔三種狀態，不使用四階段 pipeline 圖。
2. 經 Ken 明確同意後，才簡化或修改該區塊。 - 顯示 loading、empty、partial、error 及無資料狀態；`null` 不得顯示為 0。
3. 從 - 狀態同時使用文字與樣式，不可只用顏色表示。
- 提供前往既有 `/bill/list`／`/invoice/list` 的導覽，不在 Dashboard 直接改變任何帳務狀態。
## V1 移除此區塊。 不開發
- 不顯示四階段流程圖。
- 不顯示帳務趨勢圖或歷史月份比較。
- 不在 Dashboard 顯示住戶／逐筆帳單清單。
- 不在 Dashboard 提供付款、覆核、重算或修改 Invoice status 等操作。
- 不新增 Dashboard 專用帳務資料表或帳務排程。
## Backend／Frontend 狀態 Acceptance Criteria
在本票定案前：
- Backend 不固定新的 Billing Summary DTO 或 aggregation contract。 [ ] 顯示月份與案場 timezone 一致。
- Frontend 不新增「本月帳務摘要」元件。 [ ] Calculation、Billing、Invoice 三套狀態不混用。
- 既有帳務、結算、請款作業與 route 不變。 [ ] paid／pending／overdue 數量可對回既有帳務資料。
- 最終需求文件與 mockup 暫不修改。 [ ] `PENDING_DATA`／`ERROR` 不得被顯示為 COMPLETE。
- [ ] `null`／無資料與數值 0 有不同呈現。
- [ ] 點擊連結可進入既有帳單或請款頁。
- [ ] Dashboard 不會送出任何帳務 mutation request。
## 待確認事項
- [ ] Dashboard V1 是否依 attachment #1110 保留四步驟「結算流程」面板，只將假月份／假數字替換為正式 API 資料？ `cancelled` 帳單數量是否需要顯示在首頁摘要卡？
## 需求管理狀態
- Parent：#1422
- Requirement status：**待重新確認** status：**待確認**
- Final specification：所有 Dashboard 區塊確認後再整併至 #1422 v1.0 文件
- Implementation tickets：需求鎖定後才建立 FE／BE／QA child issues
返回