ewoooc/docs/work_log_20260112.md

# 工作日誌 - 2026年01月12日

## 📅 日期
2026-01-12 (週日)

## 👤 執行者
Claude Code (AI Assistant)

---

## 📋 工作概要

今日主要完成兩大任務：
1. **MOMO 商品圖片修復與驗證** - 修復錯誤的商品圖片 URL，提升正確率從 86% 到 92%
2. **每日業績儀表板需求規劃** - 完整規劃新功能的需求、設計與實作計畫

---

## 🎯 任務一：商品圖片修復專案

### 背景說明
從上次會話延續，系統中有大量商品的圖片 URL 不正確，主要問題是：
- 圖片 URL 格式錯誤（使用舊的 img2.momoshop.com.tw 格式）
- 圖片 URL 不包含對應的 i_code，導致圖片與商品不匹配
- 之前的全量更新已完成 4,526 個商品，但仍有許多錯誤

### 執行步驟

#### 1. 初始狀態確認
**時間**: 上午
**動作**: 檢查圖片更新任務完成狀態

```
✅ 完成狀態：
- 全量更新已完成（4,526/4,529 商品）
- 成功更新: 2,834 個
- 跳過（已正確）: 332 個
- 失敗: 1,360 個（主要為已下架商品）
```

#### 2. 驗證圖片覆蓋率
**檔案**: `check_missing_images.py`
**結果**:
```
一般商品: 4,529 總數
- 有圖片: 4,151 (91.7%)
- 缺圖片: 378 (8.3%)

EDM 促銷: 4,931 (100%)
購物節: 662 (100%)
```

#### 3. 驗證圖片正確性
**檔案**: `verify_image_urls.py`
**方法**: 抽樣 200 個商品檢查
**結果**:
```
✅ 正確: 198/200 (99.0%)
❌ 錯誤: 2/200 (1.0%)
```

#### 4. 用戶反饋 - 第一批錯誤商品
**商品編號**: 9 個
```
14672839, 9216349, 13261678, 6676895, 13240823,
13240822, 10911080, 3876337, 8863611
```

**處理**:
- 建立 `fix_specific_products.py`
- 逐一獲取正確圖片 URL
- ✅ 9/9 全部修復成功

**修復範例**:
```
❌ 舊: https://img4.momoshop.com.tw/ecm/img/online/341/2025/12/30/162906531/...
✅ 新: https://og.momoshop.com.tw/1767837323/goodsimg/0014/672/839/14672839_L.jpg
```

#### 5. 用戶反饋 - 第二批錯誤商品
**商品編號**: 13 個
```
5939587, 14713987, 14237189, 13759520, 13330513, 13731019,
14049583, 14695038, 14373672, 13646926, 4633943, 6271461, 13559833
```

**處理**:
- 建立 `fix_batch2_products.py`
- ✅ 13/13 全部修復成功
- 所有圖片 URL 已包含正確 i_code

#### 6. 用戶反饋 - 第三批錯誤商品
**商品編號**: 31 個
```
6323590, 7904362, 5954422, 6009343, 4248163, 3331634, 7351198,
12589232, 11118441, 10755887, 9009264, 9562474, 11038732, 10901361,
9250857, 5477268, 9600967, 10440331, 10080994, 9900915, 3821684,
10567236, 13351736, 13351734, 12777975, 11640264, 5894654, 10050962,
8318051, 11593427, 9857434
```

**處理**:
- 建立 `fix_batch3_products.py`
- ✅ 31/31 全部修復成功
- 驗證通過率 100%

#### 7. 全面檢查與批量修復
**用戶要求**: "你再去檢查全部商品，再重新修復一次"

**執行流程**:

**步驟 1**: 全面檢查所有商品
```bash
python3 check_all_products.py
```

**檢查結果**:
```
總商品數（有圖片）: 4,151
✅ 正確: 3,596 (86%)
❌ 錯誤: 555 (13%)

錯誤清單保存: incorrect_images.txt
```

**步驟 2**: 批量修復
```bash
python3 fix_all_incorrect.py
```

**修復結果**:
```
處理商品: 555 個
✅ 成功修復: 263 個 (47%)
❌ 修復失敗: 292 個 (53%)

失敗原因: 商品已下架或頁面無法訪問
```

**步驟 3**: 再次驗證
```
修復前: 3,596/4,151 正確 (86%)
修復後: 3,858/4,151 正確 (92%)

改善: +262 個商品 (+6%)
```

#### 8. 完整備份
**用戶要求**: "全部處理完，請幫我完整備份起來，備份檔案名稱要加上日期和版本號"

**備份執行**:
```bash
備份名稱: momo_backup_20260112_v2.0
備份位置: backups/momo_backup_20260112_v2.0.tar.gz
備份大小: 41M (原 186M，壓縮率 78%)
```

**備份內容**:
- ✅ 資料庫 (momo_database.db)
- ✅ 修復報告 (repair_report_20260112.md)
- ✅ 檢查腳本 (check_all_products.py)
- ✅ 修復腳本 (fix_all_incorrect.py)
- ✅ 驗證腳本 (verify_image_urls.py)
- ✅ 工具模組 (utils/image_url_builder.py)
- ✅ 錯誤商品清單 (incorrect_images_20260112.txt)
- ✅ 說明文件 (README.md)

### 最終成果

#### 數據統計
| 指標 | 修復前 | 修復後 | 改善 |
|------|--------|--------|------|
| 正確圖片 | 3,596 (86%) | 3,858 (92%) | +262 |
| 錯誤圖片 | 555 (13%) | 293 (7%) | -262 |
| 總商品數 | 4,151 | 4,151 | - |

#### 手動修復統計
- 第一批: 9 個 ✅ 100% 成功
- 第二批: 13 個 ✅ 100% 成功
- 第三批: 31 個 ✅ 100% 成功
- **小計**: 53 個全部成功

#### 自動修復統計
- 檢測錯誤: 555 個
- 成功修復: 263 個 (47%)
- 修復失敗: 292 個 (53% - 主要為已下架商品)

#### 剩餘問題分析
剩餘 293 個錯誤商品：
- 99% 使用舊格式 URL (img2.momoshop.com.tw)
- 主要原因: 商品已下架或頁面無法訪問
- 建議: 標記為「已下架」狀態

### 技術要點

#### 核心解決方案
使用 `utils/image_url_builder.py` 中的 `get_product_image_url()` 函數：

```python
def get_product_image_url(i_code: str) -> Optional[str]:
    """
    從商品詳情頁的 og:image meta 標籤獲取正確圖片 URL
    這確保圖片 URL 包含對應的 i_code
    """
    detail_url = f"https://www.momoshop.com.tw/goods/GoodsDetail.jsp?i_code={i_code}"
    response = requests.get(detail_url, headers=headers, timeout=10)
    pattern = r'<meta property="og:image" content="([^"]+)"'
    match = re.search(pattern, response.text)
    if match:
        return match.group(1)
    return None
```

#### 圖片 URL 格式

**錯誤格式（舊）**:
```
https://img2.momoshop.com.tw/ecm/img/online/341/2025/12/18/115728399/...
```
特徵: 不包含 i_code，無法確保圖片正確性

**正確格式（新）**:
```
https://og.momoshop.com.tw/1767837323/goodsimg/0014/672/839/14672839_L.jpg
```
特徵: URL 路徑包含 i_code，確保圖片對應正確

#### 驗證邏輯

```python
def check_image_url_match(i_code: str, image_url: str) -> bool:
    """檢查圖片 URL 是否包含對應的 i_code"""
    # TP 開頭商品: 檢查完整 i_code
    if i_code.startswith('TP'):
        return i_code in image_url

    # 數字商品: 檢查路徑格式
    # 格式1: /14672839_L.jpg
    # 格式2: /0014/672/839/
    code_num = str(int(i_code))
    if f"/{code_num}_" in image_url or f"/{code_num}." in image_url:
        return True

    # 分段格式檢查
    code_str = code_num.zfill(8)
    part3 = code_str[-3:]
    part2 = code_str[-6:-3]
    part1 = code_str[:-6].zfill(4)
    path_pattern = f"/{part1}/{part2}/{part3}/"
    return path_pattern in image_url
```

### 建立的檔案

#### 腳本檔案
1. `check_specific_products.py` - 檢查特定商品
2. `fix_specific_products.py` - 修復特定商品
3. `fix_batch2_products.py` - 修復第二批商品
4. `fix_batch3_products.py` - 修復第三批商品
5. `check_all_products.py` - 檢查全部商品
6. `fix_all_incorrect.py` - 批量修復錯誤商品
7. `analyze_remaining.py` - 分析剩餘錯誤

#### 報告檔案
1. `final_report.md` - 完整修復報告
2. `incorrect_images.txt` - 錯誤商品清單
3. `backups/momo_backup_20260112_v2.0/README.md` - 備份說明

---

## 🎯 任務二：每日業績儀表板需求規劃

### 背景說明
**時間**: 下午/傍晚
**用戶需求**: 建立新的每日業績追蹤系統

### 需求內容

#### 核心功能需求
1. **Excel 匯入功能**
   - 匯入欄位對應 `realtime_sales_monthly` 所有欄位
   - 支援資料驗證和錯誤處理
   - 顯示匯入進度和結果

2. **行事曆式儀表板**
   - UI/UX 風格延續現有頁面
   - 每日業績卡片顯示
   - 點擊展開詳細資料

3. **業績對比分析**
   - 每日 vs 每日對比
   - 每週同日對比（週一 vs 週一）
   - 計算成長率和趨勢

4. **資料整合**
   - 每日業績累加到現有業績分析儀表板
   - 自動化統計計算

5. **其他考量**
   - 完整流程設計
   - 專業建議和最佳實踐

### 執行成果

#### 1. TODO 任務建立
建立 12 項開發任務：

**需求分析階段**
- [ ] 需求分析：研究現有業績分析頁面和資料結構

**資料庫設計階段**
- [ ] 設計資料庫：新增 daily_sales 表格（欄位參考 realtime_sales_monthly）

**後端開發階段**
- [ ] 後端開發：實作 Excel 匯入功能（支援 realtime_sales_monthly 所有欄位）
- [ ] 後端開發：建立每日業績 API（CRUD + 統計計算）
- [ ] 業績對比邏輯：實作每日 vs 每日對比功能
- [ ] 業績對比邏輯：實作每週同日對比（週一 vs 週一等）
- [ ] 業績對比邏輯：計算成長率、趨勢分析

**前端開發階段**
- [ ] 前端開發：建立每日業績儀表板頁面（行事曆樣式）
- [ ] 前端開發：實作 Excel 匯入上傳介面
- [ ] 前端開發：設計業績對比視覺化圖表（日對比、週對比）

**整合測試階段**
- [ ] 整合功能：每日業績累加到現有業績分析儀表板
- [ ] 測試：完整流程測試（匯入、查看、對比、累加）

#### 2. 完整需求規格書
**檔案**: `docs/daily_sales_dashboard_spec.md`
**內容**: 48 KB，包含 10 大章節

**章節概要**:

1. **需求概述** - 專案背景和目標
2. **核心功能** - Excel 匯入、行事曆儀表板、業績對比
3. **UI/UX 設計** - 視覺風格、行事曆樣式、互動設計
4. **業績對比分析** - DoD, WoW, MoM, YoY 對比邏輯
5. **資料庫設計** - daily_sales 和 daily_sales_summary 表格結構
6. **後端 API 設計** - 7 個 API 端點規格
7. **與現有儀表板整合** - 資料累加邏輯和顯示方式
8. **技術建議** - 前後端技術選型和實作建議
9. **開發階段規劃** - 4 個 Phase，預計 9-13 天
10. **待討論事項** - 目標設定、權限管理、通知功能等

**技術選型建議**:
- 前端：FullCalendar.js + Chart.js + Bootstrap 5.3
- 後端：Flask + pandas + openpyxl
- 資料庫：SQLite（新增 2 張表）
- 排程：APScheduler

**資料庫設計亮點**:

**daily_sales 表格**
```sql
CREATE TABLE daily_sales (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    狀態, 日期, 時間, 訂單編號, 序號, 商品館, 小分類,
    出貨方式, 商品ID, 商品名稱, 數量, 退貨數量,
    總業績, 總成本, 付款, 是否超取,
    使用P幣, 使用Hami_point, 使用儲值, 使用禮券,
    created_at, updated_at,
    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,
    總業績, 總成本, 毛利, 毛利率,
    訂單數, 商品件數, 平均客單價,
    日成長率, 週同日成長率, 月成長率, 年成長率,
    created_at, updated_at
);
```

**API 設計**:
```
POST   /api/daily_sales/import        - 匯入 Excel
POST   /api/daily_sales/validate      - 驗證檔案
GET    /api/daily_sales/calendar      - 月度資料
GET    /api/daily_sales/detail        - 單日詳情
GET    /api/daily_sales/compare       - 業績對比
GET    /api/daily_sales/trends        - 趨勢資料
GET    /api/daily_sales/top_products  - 熱銷商品
```

#### 3. 實作檢查清單
**檔案**: `docs/daily_sales_implementation_checklist.md`
**內容**: 完整的開發檢查清單

**檢查項目統計**:
- Phase 1 (後端基礎): 23 個檢查點
- Phase 2 (前端開發): 22 個檢查點
- Phase 3 (對比分析): 17 個檢查點
- Phase 4 (整合優化): 17 個檢查點
- 上線前檢查: 15 個檢查點
- **總計**: 94 個檢查點

**開發時程規劃**:
```
Phase 1: 資料庫與後端基礎 - 2-3 天
Phase 2: 前端開發 - 3-4 天
Phase 3: 對比分析與視覺化 - 2-3 天
Phase 4: 整合與優化 - 2-3 天
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
總計: 9-13 天
```

**建議開始時間**: 2026-01-13（明天）
**預計完成時間**: 2026-01-24

### 專業建議重點

#### 1. UI/UX 設計
**行事曆樣式範例**:
```
┌─────────────────────────────────────────────┐
│  2026年 1月                    [<] [今天] [>] │
├─────┬─────┬─────┬─────┬─────┬─────┬─────┤
│ 日  │ 一  │ 二  │ 三  │ 四  │ 五  │ 六  │
├─────┼─────┼─────┼─────┼─────┼─────┼─────┤
│     │     │     │ 01  │ 02  │ 03  │ 04  │
│     │     │     │$123K│$145K│$167K│$189K│
│     │     │     │📈5% │📈8% │📈12%│📈15%│
└─────┴─────┴─────┴─────┴─────┴─────┴─────┘
```

**狀態顏色規則**:
- 🟢 綠色: 成長 > 5%
- 🔴 紅色: 衰退 > 5%
- ⚪ 灰色: 變動 <= 5%

#### 2. 業績對比邏輯

**DoD (Day-over-Day) 日對日**:
- 今日 vs 昨日
- 用於短期趨勢追蹤

**WoW (Week-over-Week) 週同日**:
- 本週一 vs 上週一
- 消除週末/平日差異
- 發現週期性趨勢

**MoM (Month-over-Month) 月對月**:
- 本月 vs 上月
- 中期趨勢分析

**YoY (Year-over-Year) 年對年**:
- 今年 vs 去年
- 長期趨勢和季節性分析

**成長率計算公式**:
```python
成長率 = ((本期 - 前期) / 前期) * 100%
移動平均成長率 (7日) = SUM(過去7日成長率) / 7
```

#### 3. 資料整合方案

**方案 A: 定時累加（推薦）**
```python
# 每日凌晨 00:30 執行
def accumulate_daily_sales():
    yesterday = get_yesterday()
    daily_data = fetch_daily_sales(yesterday)

    for record in daily_data:
        upsert_to_monthly(record)

    refresh_dashboard_cache()
```

優點:
- 不影響匯入速度
- 可以批次驗證
- 易於除錯

**方案 B: 即時累加**
- 匯入時同步寫入 realtime_sales_monthly
- 優點: 即時性高
- 缺點: 匯入速度較慢

#### 4. 效能優化建議

**大量資料匯入**:
```python
# 使用批次處理
batch_size = 1000
for i in range(0, len(data), batch_size):
    batch = data[i:i+batch_size]
    with db.begin():
        batch.to_sql('daily_sales', con=db,
                     if_exists='append', index=False)
```

**資料庫索引**:
- 日期欄位：加速日期範圍查詢
- 商品ID：加速商品分析
- 訂單編號：加速去重檢查

**API 快取**:
```python
# 使用 Redis 快取月度資料
@cache.cached(timeout=300)  # 5 分鐘
def get_calendar_data(year, month):
    return query_monthly_summary(year, month)
```

#### 5. 安全性考量

**檔案上傳驗證**:
- 限制檔案大小（10MB）
- 限制檔案類型（.xlsx, .xls）
- 檔案內容掃描（防毒）

**SQL Injection 防護**:
```python
# 使用參數化查詢
cursor.execute(
    "SELECT * FROM daily_sales WHERE 日期 = ?",
    (date,)
)
```

**權限控制**:
- 匯入功能需要管理員權限
- 查看功能可開放給一般用戶

### 待討論事項

用戶需要後續確認的問題：

1. **目標設定功能**
   - 是否需要設定每日/週/月業績目標？
   - 目標設定介面如何設計？

2. **權限管理**
   - 誰可以匯入 Excel？
   - 誰可以查看業績數據？

3. **通知功能**
   - 業績達標/未達標時是否發送通知？
   - 通知方式：Email / LINE / 站內訊息？

4. **匯出功能**
   - 是否需要將對比分析結果匯出為 Excel/PDF？

5. **行動裝置支援**
   - 行事曆在手機上的呈現方式？
   - 是否需要開發 App？

---

## 📊 今日工作統計

### 時間分配
```
商品圖片修復: ~6-7 小時
  - 用戶反饋修復: 2 小時
  - 全面檢查修復: 3 小時
  - 備份與報告: 1-2 小時

業績儀表板規劃: ~3-4 小時
  - 需求理解: 0.5 小時
  - 規格書撰寫: 2 小時
  - 檢查清單建立: 1 小時
  - TODO 記錄: 0.5 小時

總計: ~9-11 小時
```

### 建立檔案統計
```
腳本檔案: 7 個
  - check_specific_products.py
  - fix_specific_products.py
  - fix_batch2_products.py
  - fix_batch3_products.py
  - check_all_products.py
  - fix_all_incorrect.py
  - analyze_remaining.py

報告文件: 3 個
  - final_report.md
  - incorrect_images.txt
  - backups/.../README.md

規劃文件: 2 個
  - docs/daily_sales_dashboard_spec.md (48KB)
  - docs/daily_sales_implementation_checklist.md

備份檔案: 1 個
  - backups/momo_backup_20260112_v2.0.tar.gz (41MB)

總計: 13 個檔案
```

### 程式碼執行統計
```
Python 腳本執行: 15+ 次
資料庫查詢: 4,151+ 商品
修復商品數: 315 個（手動53 + 自動262）
備份資料: 186 MB → 41 MB
```

### 文件撰寫統計
```
需求規格書: ~8,000 字
實作清單: ~3,000 字
修復報告: ~2,000 字
工作日誌: ~4,000 字（本文件）

總計: ~17,000 字
```

---

## 🎯 成果交付

### 任務一交付物
1. ✅ 修復後資料庫（正確率 92%）
2. ✅ 完整備份檔案（momo_backup_20260112_v2.0.tar.gz）
3. ✅ 修復報告（final_report.md）
4. ✅ 錯誤商品清單（incorrect_images_20260112.txt, 293個）
5. ✅ 7 個修復/檢查腳本
6. ✅ 工具模組（utils/image_url_builder.py）

### 任務二交付物
1. ✅ TODO 任務清單（12 項）
2. ✅ 完整需求規格書（48KB, 10章節）
3. ✅ 實作檢查清單（94 個檢查點）
4. ✅ 開發時程規劃（9-13 天）
5. ✅ 技術選型建議
6. ✅ 資料庫設計方案
7. ✅ API 設計規格

---

## 💡 重要決策記錄

### 圖片修復專案
1. **採用 og:image meta 標籤方案**
   - 理由: 確保圖片 URL 包含正確 i_code
   - 效果: 成功率 47%，正確率提升至 92%

2. **保留 293 個修復失敗的商品**
   - 理由: 主要為已下架商品，無法獲取有效圖片
   - 建議: 標記為 INACTIVE 狀態

3. **定期驗證機制**
   - 建議: 每月執行一次全面檢查
   - 工具: check_all_products.py

### 業績儀表板專案
1. **採用 FullCalendar.js**
   - 理由: 功能完整、文件齊全、社群活躍
   - 替代方案: Toast UI Calendar（輕量級）

2. **採用定時累加方案**
   - 理由: 不影響匯入速度，易於維護
   - 時間: 每日凌晨 00:30 執行

3. **MVP 優先策略**
   - 優先: Excel 匯入 + 行事曆顯示
   - 其次: 業績對比分析
   - 最後: 進階功能（目標設定、通知等）

4. **資料庫設計雙表方案**
   - daily_sales: 存放訂單明細
   - daily_sales_summary: 存放統計摘要
   - 理由: 分離明細和統計，提升查詢效能

---

## 📌 待辦事項（明日）

### 高優先級
- [ ] 與用戶確認業績儀表板需求細節
- [ ] 決定待討論事項（目標設定、權限、通知等）
- [ ] 開始 Phase 1 開發（資料庫設計）

### 中優先級
- [ ] 處理剩餘 293 個錯誤商品（標記狀態）
- [ ] 更新 scheduler.py 使用新的圖片獲取方法

### 低優先級
- [ ] 建立定期圖片驗證排程
- [ ] 優化現有業績分析頁面效能

---

## 📝 學習與心得

### 技術收穫
1. **圖片 URL 驗證邏輯**
   - 學習如何驗證 URL 與 i_code 的對應關係
   - 處理數字和 TP 開頭商品的不同邏輯

2. **批量資料處理**
   - 使用 pandas 進行大量資料的讀取和驗證
   - 交易 (transaction) 確保資料一致性

3. **需求分析與規劃**
   - 完整的需求規格書撰寫
   - 開發時程估算和階段規劃
   - 技術選型的考量因素

### 溝通要點
1. **即時回應用戶反饋**
   - 用戶提供錯誤商品時立即處理
   - 每批處理完畢立即驗證

2. **完整的交付文件**
   - 備份包含完整說明
   - 報告清楚列出成果和剩餘問題

3. **前瞻性規劃**
   - 為新需求提供多種方案
   - 列出待討論事項供用戶決策

---

## 🔗 相關檔案連結

### 圖片修復相關
- 備份檔案: `backups/momo_backup_20260112_v2.0.tar.gz`
- 修復報告: `final_report.md`
- 錯誤清單: `incorrect_images.txt`
- 檢查腳本: `check_all_products.py`
- 修復腳本: `fix_all_incorrect.py`
- 驗證腳本: `verify_image_urls.py`
- 工具模組: `utils/image_url_builder.py`

### 業績儀表板相關
- 需求規格: `docs/daily_sales_dashboard_spec.md`
- 實作清單: `docs/daily_sales_implementation_checklist.md`
- TODO 系統: 已記錄 12 項任務

### 資料庫
- 主資料庫: `data/momo_database.db` (186MB)
- 備份資料庫: `backups/momo_backup_20260112_v2.0/momo_database.db`

---

## ✅ 簽核

**執行者**: Claude Code (AI Assistant)
**日期**: 2026-01-12
**狀態**: ✅ 全部完成
**下次工作**: 2026-01-13（開始每日業績儀表板開發）

---

**文件版本**: 1.0
**最後更新**: 2026-01-12 23:59