Files

CD Pipeline / deploy (push) Failing after 59s

Details

- 建立 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>

2026-04-19 01:21:13 +08:00

14 KiB

Raw Permalink Blame History

每日業績儀表板 - 需求規格書

建立日期: 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 (年對年)
自訂期間對比

類別維度

各商品館業績對比
各分類業績對比
出貨方式對比 (宅配/超取)
付款方式對比

成長率計算

成長率 = ((本期 - 前期) / 前期) * 100%

移動平均成長率 (7日) = SUM(過去7日成長率) / 7

4. 資料庫設計

新增表格: `daily_sales`

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`

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: 定時累加 (推薦)

# 每日凌晨 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 匯入處理

// 使用 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 處理

# 使用 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)

成長率計算

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個)

今日業績
- 金額 + DoD 成長率
- 與目標的達成率
本週業績
- 累計金額 + WoW 成長率
- 週目標達成率
本月業績
- 累計金額 + MoM 成長率
- 月目標達成率
熱銷商品
- 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 (台北時間)

資料備份

匯入前自動備份現有資料
提供「復原」功能

📝 待討論事項

目標設定功能
- 是否需要設定每日/週/月業績目標？
- 目標設定介面如何設計？
權限管理
- 誰可以匯入 Excel？
- 誰可以查看業績數據？
通知功能
- 業績達標/未達標時是否發送通知？
- 通知方式：Email / LINE / 站內訊息？
匯出功能
- 是否需要將對比分析結果匯出為 Excel/PDF？
行動裝置支援
- 行事曆在手機上的呈現方式？
- 是否需要開發 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 開發

14 KiB Raw Permalink Blame History Unescape Escape