# 🔄 Upstream 自動同步機制

本專案實作了完整的 upstream 自動同步、變更追蹤與 smoke test 機制。

## 📋 目錄

- [功能概述](#功能概述)
- [工作流程圖](#工作流程圖)
- [Workflow 說明](#workflow-說明)
- [Smoke Test 內容](#smoke-test-內容)
- [設定說明](#設定說明)
- [手動操作](#手動操作)

---

## 功能概述

### 1️⃣ 自動同步 Upstream

| 功能       | 說明                         |
| ---------- | ---------------------------- |
| 觸發方式   | 每 6 小時自動檢查 / 手動觸發 |
| 同步目標   | `dev` 分支                   |
| Merge 策略 | 自動 merge（無衝突時）       |
| 衝突處理   | 自動建立 GitHub Issue 通知   |

### 2️⃣ 變更摘要

同步完成後自動產生：

- ✅ GitHub Issue（詳細變更記錄）
- ✅ `upstream-changelog.md`（累積變更歷史）
- ✅ GitHub Actions Summary（快速查看）

### 3️⃣ Smoke Test

| 測試項目       | 內容                                   | 時間限制      |
| -------------- | -------------------------------------- | ------------- |
| Container 啟動 | 驗證 image 可正常啟動                  | 60s           |
| 工具檢查       | libreoffice, pandoc, ffmpeg, tesseract | 30s           |
| 最小轉換       | txt → pdf                              | 60s           |
| API 端點       | healthcheck, root                      | 10s           |
| **總計**       |                                        | **< 10 分鐘** |

---

## 工作流程圖

```
┌─────────────────────────────────────────────────────────────────────────┐
│                         Upstream 自動同步流程                              │
└─────────────────────────────────────────────────────────────────────────┘

    ┌──────────────┐
    │   Upstream   │
    │  (C4illin/   │
    │  ConvertX)   │
    └──────┬───────┘
           │
           │ 每 6 小時檢查
           ▼
    ┌──────────────┐     無更新      ┌──────────────┐
    │  檢查是否有   │ ─────────────► │   結束       │
    │  新 commits  │                 └──────────────┘
    └──────┬───────┘
           │ 有更新
           ▼
    ┌──────────────┐     衝突        ┌──────────────┐
    │  自動 Merge  │ ─────────────► │ 建立 Issue   │
    │  到 dev 分支  │                │ 需手動處理    │
    └──────┬───────┘                └──────────────┘
           │ 成功
           ▼
    ┌──────────────┐
    │  產生變更摘要  │
    │  • Issue     │
    │  • Changelog │
    └──────┬───────┘
           │
           ▼
    ┌──────────────┐
    │  Push 到 dev │
    └──────┬───────┘
           │
           │ 觸發 upstream-sync.yml
           ▼
    ┌──────────────┐
    │  Build 測試  │
    │  Image (amd64)│
    └──────┬───────┘
           │
           ▼
    ┌──────────────────────────────────────────────────┐
    │                  Smoke Test                       │
    │  ┌────────────┐ ┌────────────┐ ┌────────────┐   │
    │  │ Container  │ │   工具     │ │   轉換     │   │
    │  │   啟動     │ │   檢查     │ │   測試     │   │
    │  └─────┬──────┘ └─────┬──────┘ └─────┬──────┘   │
    │        │              │              │           │
    │        └──────────────┼──────────────┘           │
    │                       │                          │
    └───────────────────────┼──────────────────────────┘
                            │
              ┌─────────────┴─────────────┐
              │                           │
              ▼                           ▼
       ┌────────────┐              ┌────────────┐
       │  ✅ 通過   │              │  ❌ 失敗   │
       └─────┬──────┘              └─────┬──────┘
             │                           │
             ▼                           ▼
       ┌────────────┐              ┌────────────┐
       │ Build 並   │              │ Workflow   │
       │ Push 到    │              │ 失敗       │
       │ Docker Hub │              │ (不發布)    │
       └─────┬──────┘              └────────────┘
             │
             ▼
       ┌────────────────────────┐
       │ upstream-YYYYMMDD tag  │
       │ ❌ 不更新 latest        │
       │ ❌ 不打 semver tag      │
       └────────────────────────┘
```

---

## Workflow 說明

### `auto-upstream-sync.yml`

**用途：** 自動檢測並同步 upstream 更新

**觸發條件：**

- ⏰ 每 6 小時自動執行
- 🖱️ 手動觸發

**主要步驟：**

1. Fetch upstream 最新程式碼
2. 檢查是否有新 commits
3. 自動 merge 到 `dev` 分支
4. 產生變更摘要（Issue + Changelog）
5. Push 到 `dev`

### `upstream-sync.yml`

**用途：** 當 `dev` 分支有 push 時，執行 build + smoke test

**觸發條件：**

- 📦 `dev` 分支有 push

**主要步驟：**

1. Build 測試用 image（僅 amd64，加速測試）
2. 執行 Smoke Test（10 分鐘內）
3. 測試通過後 build multi-arch image
4. Push 到 Docker Hub（tag: `upstream-YYYYMMDD`）

---

## Smoke Test 內容

### Test 1: Container 啟動測試

```bash
# 啟動 container 並等待 healthcheck 回應
docker run -d --name convertx-test $IMAGE
curl http://localhost:3000/healthcheck
```

### Test 2: 關鍵工具檢查

```bash
# 必須通過（任一失敗則整體失敗）
libreoffice --version
pandoc --version
ffmpeg -version
tesseract --version
```

### Test 3: 最小轉換測試

```bash
# txt → pdf 轉換測試
echo "test" > test.txt
libreoffice --headless --convert-to pdf test.txt
```

### Test 4: API 端點檢查

```bash
# 確認服務正常運作
curl http://localhost:3000/healthcheck
curl http://localhost:3000/
```

---

## 設定說明

### 必要的 GitHub Secrets

在 Repository Settings → Secrets and variables → Actions 中設定：

| Secret 名稱          | 說明                    |
| -------------------- | ----------------------- |
| `DOCKERHUB_USERNAME` | Docker Hub 帳號         |
| `DOCKERHUB_TOKEN`    | Docker Hub Access Token |

### 分支保護規則

建議設定：

**`main` 分支：**

- ✅ Require pull request before merging
- ✅ Require status checks to pass
- ❌ Allow force pushes

**`dev` 分支：**

- ✅ Allow direct pushes (for automation)

---

## 手動操作

### 手動觸發同步

1. 前往 Actions → Auto Upstream Sync
2. 點選 "Run workflow"
3. 可選擇「強制同步」

### 手動處理 Merge 衝突

當自動同步發生衝突時：

```bash
# 1. 切換到 dev 分支
git checkout dev

# 2. 添加 upstream remote（如果還沒有）
git remote add upstream https://github.com/C4illin/ConvertX.git

# 3. Fetch upstream
git fetch upstream main

# 4. Merge upstream
git merge upstream/main

# 5. 解決衝突
# ... 編輯衝突的檔案 ...

# 6. 提交並 push
git add .
git commit -m "Resolve merge conflicts with upstream"
git push origin dev
```

---

## ⚠️ 注意事項

1. **不會自動更新 `latest` tag** - 需要手動發布正式版本
2. **不會自動打 semver tag** - 需要手動建立 release
3. **`main` 分支不會被自動修改** - 只有 `dev` 會自動同步
4. **Smoke test 失敗時不會發布 image** - 確保品質

---

## 📊 Docker Image Tag 規則

| Tag 格式            | 說明                               | 自動/手動 |
| ------------------- | ---------------------------------- | --------- |
| `upstream-YYYYMMDD` | Upstream 同步版（經過 smoke test） | 自動      |
| `vX.Y.Z`            | 正式版本                           | 手動      |
| `latest`            | 最新穩定版                         | 手動      |