1b4f3a7bbe
Some checks failed
CD Pipeline / deploy (push) Failing after 59s
- 建立 Gitea Actions CD pipeline (.gitea/workflows/cd.yaml) - 部署模式: rsync Python 檔案至 188 → docker restart (volume mount) - Dockerfile/requirements 變動時自動重建 Docker image - 部署通知: Telegram (開始/成功/失敗) - 健康檢查: https://mo.wooo.work/health (最多 5 次重試) - 同步最新 CLAUDE.md / ADR-008 / memory (2026-04-19) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
550 lines
14 KiB
Markdown
550 lines
14 KiB
Markdown
# 每日業績儀表板 - 需求規格書
|
||
|
||
**建立日期**: 2026-01-12
|
||
**狀態**: 待開發
|
||
**優先級**: 高
|
||
|
||
---
|
||
|
||
## 📋 需求概述
|
||
|
||
建立一個每日業績追蹤系統，提供行事曆式的視覺化界面，支援 Excel 匯入、業績對比分析，並與現有業績分析儀表板整合。
|
||
|
||
---
|
||
|
||
## 🎯 核心功能
|
||
|
||
### 1. Excel 匯入功能
|
||
|
||
#### 匯入規格
|
||
- **檔案格式**: .xlsx, .xls
|
||
- **欄位對應**: 完全對應 `realtime_sales_monthly` 表格欄位
|
||
- **必要欄位**:
|
||
- 日期 (DATE)
|
||
- 訂單編號 (TEXT)
|
||
- 商品ID (TEXT)
|
||
- 商品名稱 (TEXT)
|
||
- 數量 (NUMERIC)
|
||
- 總業績 (NUMERIC)
|
||
- 總成本 (NUMERIC)
|
||
|
||
#### 匯入流程
|
||
```
|
||
1. 使用者上傳 Excel 檔案
|
||
2. 系統驗證檔案格式和欄位
|
||
3. 預覽前 10 筆資料
|
||
4. 使用者確認匯入
|
||
5. 批次寫入資料庫 (使用 transaction)
|
||
6. 顯示匯入結果摘要
|
||
```
|
||
|
||
#### 資料驗證規則
|
||
- 日期格式驗證 (YYYY-MM-DD)
|
||
- 數值欄位型別檢查
|
||
- 必填欄位檢查
|
||
- 重複訂單編號檢查（可選：覆蓋/跳過/報錯）
|
||
|
||
---
|
||
|
||
### 2. 行事曆式儀表板
|
||
|
||
#### UI/UX 設計
|
||
|
||
**視覺風格**
|
||
- 延續現有 Bootstrap 5.3 + Font Awesome 設計
|
||
- 卡片式設計，帶陰影和 hover 效果
|
||
- 響應式設計，支援手機/平板/桌面
|
||
|
||
**行事曆樣式**
|
||
```
|
||
┌─────────────────────────────────────────────┐
|
||
│ 2026年 1月 [<] [今天] [>] │
|
||
├─────┬─────┬─────┬─────┬─────┬─────┬─────┤
|
||
│ 日 │ 一 │ 二 │ 三 │ 四 │ 五 │ 六 │
|
||
├─────┼─────┼─────┼─────┼─────┼─────┼─────┤
|
||
│ │ │ │ 01 │ 02 │ 03 │ 04 │
|
||
│ │ │ │$123K│$145K│$167K│$189K│
|
||
│ │ │ │📈5% │📈8% │📈12%│📈15%│
|
||
├─────┼─────┼─────┼─────┼─────┼─────┼─────┤
|
||
│ 05 │ 06 │ 07 │ ... │ │ │ │
|
||
│$198K│$210K│$223K│ │ │ │ │
|
||
│📈10%│📈12%│📈14%│ │ │ │ │
|
||
└─────┴─────┴─────┴─────┴─────┴─────┴─────┘
|
||
```
|
||
|
||
**每日卡片顯示**
|
||
- 日期
|
||
- 總業績（主要指標）
|
||
- 成長率（與前一日/去年同日對比）
|
||
- 訂單數量
|
||
- 平均客單價
|
||
- 狀態顏色（紅/綠/灰）
|
||
- 綠色: 成長 > 5%
|
||
- 紅色: 衰退 > 5%
|
||
- 灰色: 變動 <= 5%
|
||
|
||
**點擊日期展開詳情**
|
||
- 彈出 Modal 顯示當日詳細資料
|
||
- Top 10 熱銷商品
|
||
- 各類別業績佔比
|
||
- 時段業績分佈
|
||
|
||
---
|
||
|
||
### 3. 業績對比分析
|
||
|
||
#### 3.1 日對日對比 (Day-over-Day, DoD)
|
||
|
||
**對比維度**
|
||
- 今日 vs 昨日
|
||
- 任意日期 vs 任意日期
|
||
- 顯示絕對差異和百分比
|
||
|
||
**指標**
|
||
- 總業績變化
|
||
- 訂單量變化
|
||
- 平均客單價變化
|
||
- Top 商品變化
|
||
|
||
**視覺化**
|
||
```
|
||
今日 vs 昨日
|
||
┌─────────────────────┬──────────┬──────────┬─────────┐
|
||
│ 指標 │ 今日 │ 昨日 │ 變化 │
|
||
├─────────────────────┼──────────┼──────────┼─────────┤
|
||
│ 總業績 │ $156,780 │ $145,230 │ +8.0% ↑ │
|
||
│ 訂單數 │ 432 │ 398 │ +8.5% ↑ │
|
||
│ 平均客單價 │ $363 │ $365 │ -0.5% ↓ │
|
||
│ 新客戶訂單 │ 87 │ 76 │ +14.5%↑ │
|
||
└─────────────────────┴──────────┴──────────┴─────────┘
|
||
```
|
||
|
||
#### 3.2 週同日對比 (Week-over-Week same day, WoW)
|
||
|
||
**對比邏輯**
|
||
- 本週一 vs 上週一
|
||
- 本週二 vs 上週二
|
||
- ...以此類推
|
||
|
||
**應用場景**
|
||
- 消除週末/平日差異
|
||
- 發現週期性趨勢
|
||
- 評估行銷活動效果
|
||
|
||
**視覺化**
|
||
```
|
||
週一對比 (過去 4 週)
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
第 1 週 (2025-12-16) ████████░░ $123K
|
||
第 2 週 (2025-12-23) ██████████ $145K (+17.9%)
|
||
第 3 週 (2025-12-30) ████████░░ $134K (-7.6%)
|
||
第 4 週 (2026-01-06) ███████████ $156K (+16.4%)
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
平均成長率: +8.9%
|
||
```
|
||
|
||
#### 3.3 多維度對比建議
|
||
|
||
**時間維度**
|
||
- DoD (日對日)
|
||
- WoW (週對週)
|
||
- MoM (月對月)
|
||
- YoY (年對年)
|
||
- 自訂期間對比
|
||
|
||
**類別維度**
|
||
- 各商品館業績對比
|
||
- 各分類業績對比
|
||
- 出貨方式對比 (宅配/超取)
|
||
- 付款方式對比
|
||
|
||
**成長率計算**
|
||
```python
|
||
成長率 = ((本期 - 前期) / 前期) * 100%
|
||
|
||
移動平均成長率 (7日) = SUM(過去7日成長率) / 7
|
||
```
|
||
|
||
---
|
||
|
||
### 4. 資料庫設計
|
||
|
||
#### 新增表格: `daily_sales`
|
||
|
||
```sql
|
||
CREATE TABLE daily_sales (
|
||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||
-- 基本資訊 (與 realtime_sales_monthly 對應)
|
||
狀態 TEXT,
|
||
日期 TEXT NOT NULL,
|
||
時間 TEXT,
|
||
訂單編號 TEXT UNIQUE NOT NULL,
|
||
序號 TEXT,
|
||
商品館 TEXT,
|
||
小分類 TEXT,
|
||
出貨方式 TEXT,
|
||
商品ID TEXT,
|
||
商品名稱 TEXT,
|
||
數量 TEXT,
|
||
退貨數量 TEXT,
|
||
總業績 TEXT,
|
||
總成本 TEXT,
|
||
付款 TEXT,
|
||
是否超取 TEXT,
|
||
使用P幣 TEXT,
|
||
使用Hami_point TEXT,
|
||
使用儲值 TEXT,
|
||
使用禮券 TEXT,
|
||
|
||
-- 索引和時間戳
|
||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||
|
||
INDEX idx_date (日期),
|
||
INDEX idx_product_id (商品ID),
|
||
INDEX idx_order_number (訂單編號)
|
||
);
|
||
```
|
||
|
||
#### 新增表格: `daily_sales_summary`
|
||
|
||
```sql
|
||
CREATE TABLE daily_sales_summary (
|
||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||
日期 TEXT UNIQUE NOT NULL,
|
||
|
||
-- 業績指標
|
||
總業績 REAL DEFAULT 0,
|
||
總成本 REAL DEFAULT 0,
|
||
毛利 REAL DEFAULT 0,
|
||
毛利率 REAL DEFAULT 0,
|
||
|
||
-- 訂單指標
|
||
訂單數 INTEGER DEFAULT 0,
|
||
商品件數 INTEGER DEFAULT 0,
|
||
平均客單價 REAL DEFAULT 0,
|
||
|
||
-- 對比指標
|
||
日成長率 REAL, -- vs 前一日
|
||
週同日成長率 REAL, -- vs 上週同日
|
||
月成長率 REAL, -- vs 上月同日
|
||
年成長率 REAL, -- vs 去年同日
|
||
|
||
-- 時間戳
|
||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||
|
||
INDEX idx_date (日期)
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
### 5. 後端 API 設計
|
||
|
||
#### 5.1 匯入相關 API
|
||
|
||
**POST** `/api/daily_sales/import`
|
||
- 上傳 Excel 檔案
|
||
- 回傳: 匯入結果摘要
|
||
|
||
**POST** `/api/daily_sales/validate`
|
||
- 驗證 Excel 檔案
|
||
- 回傳: 驗證結果 + 預覽資料
|
||
|
||
#### 5.2 查詢相關 API
|
||
|
||
**GET** `/api/daily_sales/calendar?year=2026&month=1`
|
||
- 取得月度行事曆資料
|
||
- 回傳: 每日業績摘要
|
||
|
||
**GET** `/api/daily_sales/detail?date=2026-01-12`
|
||
- 取得特定日期詳細資料
|
||
- 回傳: 當日所有訂單 + 統計
|
||
|
||
**GET** `/api/daily_sales/compare`
|
||
- 參數: `date1`, `date2`, `type` (dod/wow/mom/yoy)
|
||
- 回傳: 對比分析結果
|
||
|
||
#### 5.3 統計相關 API
|
||
|
||
**GET** `/api/daily_sales/trends?start_date&end_date`
|
||
- 取得期間趨勢資料
|
||
- 回傳: 時間序列資料 (for Chart.js)
|
||
|
||
**GET** `/api/daily_sales/top_products?date=2026-01-12&limit=10`
|
||
- 取得當日熱銷商品
|
||
- 回傳: 商品列表 + 銷售數據
|
||
|
||
---
|
||
|
||
### 6. 與現有儀表板整合
|
||
|
||
#### 6.1 資料累加邏輯
|
||
|
||
**方案 A: 定時累加 (推薦)**
|
||
```python
|
||
# 每日凌晨 00:30 執行
|
||
def accumulate_daily_sales():
|
||
"""將昨日業績累加到月度統計"""
|
||
yesterday = get_yesterday()
|
||
daily_data = fetch_daily_sales(yesterday)
|
||
|
||
# 更新 realtime_sales_monthly
|
||
for record in daily_data:
|
||
upsert_to_monthly(record)
|
||
|
||
# 更新業績分析儀表板快取
|
||
refresh_dashboard_cache()
|
||
```
|
||
|
||
**方案 B: 即時累加**
|
||
- 匯入 daily_sales 時同步寫入 realtime_sales_monthly
|
||
- 優點: 即時性高
|
||
- 缺點: 匯入速度較慢
|
||
|
||
#### 6.2 儀表板顯示邏輯
|
||
|
||
在現有業績分析頁面 (`/sales_analysis`) 新增：
|
||
- "今日業績快覽" 卡片
|
||
- "本週業績趨勢" 圖表
|
||
- "進入每日業績儀表板" 連結
|
||
|
||
---
|
||
|
||
### 7. 技術建議
|
||
|
||
#### 7.1 前端技術
|
||
|
||
**行事曆套件選擇**
|
||
- **FullCalendar.js** (推薦)
|
||
- 功能完整，文件齊全
|
||
- 支援自訂事件渲染
|
||
- 響應式設計
|
||
|
||
- **Toast UI Calendar** (備選)
|
||
- 輕量級
|
||
- 客製化容易
|
||
|
||
**Excel 匯入處理**
|
||
```javascript
|
||
// 使用 SheetJS (xlsx)
|
||
import * as XLSX from 'xlsx';
|
||
|
||
function handleFileUpload(file) {
|
||
const reader = new FileReader();
|
||
reader.onload = (e) => {
|
||
const workbook = XLSX.read(e.target.result);
|
||
const worksheet = workbook.Sheets[workbook.SheetNames[0]];
|
||
const data = XLSX.utils.sheet_to_json(worksheet);
|
||
|
||
// 發送到後端驗證
|
||
validateData(data);
|
||
};
|
||
reader.readAsArrayBuffer(file);
|
||
}
|
||
```
|
||
|
||
#### 7.2 後端技術
|
||
|
||
**Excel 處理**
|
||
```python
|
||
# 使用 pandas + openpyxl
|
||
import pandas as pd
|
||
|
||
def import_excel(file_path):
|
||
# 讀取 Excel
|
||
df = pd.read_excel(file_path)
|
||
|
||
# 資料驗證
|
||
required_columns = ['日期', '訂單編號', '商品ID', ...]
|
||
validate_columns(df, required_columns)
|
||
|
||
# 資料清洗
|
||
df['日期'] = pd.to_datetime(df['日期'])
|
||
df['總業績'] = pd.to_numeric(df['總業績'], errors='coerce')
|
||
|
||
# 批次寫入 (使用 transaction)
|
||
with db.begin():
|
||
df.to_sql('daily_sales', con=db, if_exists='append', index=False)
|
||
|
||
return len(df)
|
||
```
|
||
|
||
**成長率計算**
|
||
```python
|
||
def calculate_growth_rates(date):
|
||
"""計算各維度成長率"""
|
||
current = get_sales_summary(date)
|
||
|
||
# DoD
|
||
prev_day = date - timedelta(days=1)
|
||
dod_growth = calculate_growth(current, get_sales_summary(prev_day))
|
||
|
||
# WoW same day
|
||
prev_week = date - timedelta(days=7)
|
||
wow_growth = calculate_growth(current, get_sales_summary(prev_week))
|
||
|
||
# MoM
|
||
prev_month = date - timedelta(days=30)
|
||
mom_growth = calculate_growth(current, get_sales_summary(prev_month))
|
||
|
||
return {
|
||
'dod': dod_growth,
|
||
'wow': wow_growth,
|
||
'mom': mom_growth
|
||
}
|
||
|
||
def calculate_growth(current, previous):
|
||
"""成長率計算"""
|
||
if previous == 0:
|
||
return None
|
||
return ((current - previous) / previous) * 100
|
||
```
|
||
|
||
---
|
||
|
||
### 8. 開發階段規劃
|
||
|
||
#### Phase 1: 基礎建設 (2-3 天)
|
||
- [ ] 設計並建立資料庫表格
|
||
- [ ] 建立基本 API 架構
|
||
- [ ] 實作 Excel 匯入功能
|
||
- [ ] 單元測試
|
||
|
||
#### Phase 2: 前端開發 (3-4 天)
|
||
- [ ] 建立每日業績儀表板頁面框架
|
||
- [ ] 整合 FullCalendar.js
|
||
- [ ] 實作 Excel 上傳介面
|
||
- [ ] 實作日期詳情 Modal
|
||
|
||
#### Phase 3: 對比分析 (2-3 天)
|
||
- [ ] 實作 DoD 對比邏輯
|
||
- [ ] 實作 WoW 對比邏輯
|
||
- [ ] 視覺化圖表開發
|
||
- [ ] 成長率計算和顯示
|
||
|
||
#### Phase 4: 整合與優化 (2-3 天)
|
||
- [ ] 與現有業績分析整合
|
||
- [ ] 定時累加功能
|
||
- [ ] 效能優化
|
||
- [ ] 完整流程測試
|
||
|
||
**預計總開發時間: 9-13 天**
|
||
|
||
---
|
||
|
||
### 9. 資料呈現建議
|
||
|
||
#### 9.1 關鍵指標 KPI
|
||
|
||
**首頁卡片 (4個)**
|
||
1. 今日業績
|
||
- 金額 + DoD 成長率
|
||
- 與目標的達成率
|
||
|
||
2. 本週業績
|
||
- 累計金額 + WoW 成長率
|
||
- 週目標達成率
|
||
|
||
3. 本月業績
|
||
- 累計金額 + MoM 成長率
|
||
- 月目標達成率
|
||
|
||
4. 熱銷商品
|
||
- Top 1 商品 + 銷售件數
|
||
|
||
#### 9.2 圖表設計
|
||
|
||
**趨勢圖 (折線圖)**
|
||
```
|
||
業績趨勢 (過去 30 天)
|
||
200K ┤ ╭─╮
|
||
│ ╭╯ ╰╮ ╭╮
|
||
150K ┤ ╭──╯ ╰─╮ │╰╮
|
||
│ ╭╯ ╰─╯ ╰╮
|
||
100K ┤╭─╯ ╰─
|
||
└┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─
|
||
1 5 10 15 20 25 30
|
||
```
|
||
|
||
**對比圖 (長條圖)**
|
||
```
|
||
週同日對比
|
||
週一 ████████████ 156K (+16%)
|
||
週二 ██████████░░ 142K (+8%)
|
||
週三 ████████░░░░ 128K (-2%)
|
||
週四 ██████████░░ 145K (+12%)
|
||
週五 ███████████░ 167K (+18%)
|
||
```
|
||
|
||
**商品排行 (水平長條圖)**
|
||
```
|
||
熱銷 Top 5
|
||
商品A ███████████████ 234 件
|
||
商品B ████████████ 198 件
|
||
商品C ██████████ 176 件
|
||
商品D █████████ 154 件
|
||
商品E ████████ 132 件
|
||
```
|
||
|
||
---
|
||
|
||
### 10. 注意事項與風險
|
||
|
||
#### 資料完整性
|
||
- Excel 匯入時可能有髒資料
|
||
- 需要完善的驗證和錯誤處理
|
||
- 建議提供「資料修正」功能
|
||
|
||
#### 效能考量
|
||
- 大量資料匯入時的效能
|
||
- 建議批次處理 (1000 筆/批)
|
||
- 考慮使用背景任務 (Celery/RQ)
|
||
|
||
#### 時區問題
|
||
- 確保日期時間的時區一致性
|
||
- 建議統一使用 UTC+8 (台北時間)
|
||
|
||
#### 資料備份
|
||
- 匯入前自動備份現有資料
|
||
- 提供「復原」功能
|
||
|
||
---
|
||
|
||
## 📝 待討論事項
|
||
|
||
1. **目標設定功能**
|
||
- 是否需要設定每日/週/月業績目標？
|
||
- 目標設定介面如何設計？
|
||
|
||
2. **權限管理**
|
||
- 誰可以匯入 Excel？
|
||
- 誰可以查看業績數據？
|
||
|
||
3. **通知功能**
|
||
- 業績達標/未達標時是否發送通知？
|
||
- 通知方式：Email / LINE / 站內訊息？
|
||
|
||
4. **匯出功能**
|
||
- 是否需要將對比分析結果匯出為 Excel/PDF？
|
||
|
||
5. **行動裝置支援**
|
||
- 行事曆在手機上的呈現方式？
|
||
- 是否需要開發 App？
|
||
|
||
---
|
||
|
||
## 📚 參考資料
|
||
|
||
- 現有業績分析頁面: `/sales_analysis`
|
||
- 資料表結構: `realtime_sales_monthly`
|
||
- UI 風格參考: `dashboard.html`, `edm_dashboard.html`
|
||
- Bootstrap 5.3 文件: https://getbootstrap.com/
|
||
- FullCalendar 文件: https://fullcalendar.io/
|
||
- Chart.js 文件: https://www.chartjs.org/
|
||
|
||
---
|
||
|
||
**下一步**: 與開發團隊確認需求細節，開始 Phase 1 開發
|