# 檔案用途：在 pull request 階段先建立版本、發佈 release，並在 beta 情境下執行後續工具鏈
# 更新日期：2026/07/11 21:02:25

# Workflow 名稱，用來辨識這條 CI 流程
name: CI

# 觸發條件設定
on:
  # 只有在 pull request 時才會執行
  pull_request:
    # 只針對 master 與 develop 分支
    branches:
    - master
    - develop
    # 僅在 PR 開啟或同步更新時觸發
    types: [opened, synchronize]

# 工作流程中的各個 job
jobs:
  # 第一階段：建立版本與發佈 release
  build:
    # Job 名稱，會顯示在 UI 中
    name: 1. BUILD
    # 執行環境為 Ubuntu runner
    runs-on: ubuntu
    # 提供後續 job 使用的環境變數
    env:
      # 若 PR 來源分支是 develop，則標記為 beta
      IS_BETA: ${{ gitea.base_ref == 'develop' }}
    # 對外輸出的 job 結果
    outputs:
      # 輸出版本號，供後續 job 使用
      version: ${{ steps.calculate-version.outputs.version }}
      # 輸出是否為 beta，供後續 job 判斷
      is_beta: ${{ env.IS_BETA }}
    # 具體步驟
    steps:
    # 先依 repo 狀態計算版本號。
    - name: Calculate Version
      # 供後續步驟讀取輸出用的 step id。
      id: calculate-version
      # 使用版本計算 action。
      uses: https://gitea.jsc.idv.tw/actions/calculate-version@${{ vars.ACTION_CALCULATE_VERSION }}
      # 傳入 action 參數。
      with:
        # 告知 action 是否為 beta 分支情境。
        is_beta: ${{ env.IS_BETA }}
    # 發佈 release。
    - name: Publishing Release
      # 使用 release action 發佈版本。
      uses: akkuman/gitea-release-action@${{ vars.ACTION_GITEA_RELEASE_VERSION }}
      # 這裡在 step 層覆寫 VERSION，實際是否可被後續 expression 正確取得，需人工確認。
      env:
        # 取前一步算出的版本號。
        VERSION: ${{ steps.calculate-version.outputs.version }}
      with:
        # release 名稱包含 repository 名稱與版本號。
        name: "${{ gitea.event.repository.name }} v${{ env.VERSION }}"
        # tag 名稱與版本號保持一致。
        tag_name: "v${{ env.VERSION }}"
        # 指定這次 release 對應的 commit。
        target_commitish: ${{ gitea.sha }}
        # beta 分支才標記為 prerelease。
        prerelease: ${{ env.IS_BETA }}
  # 第二階段：在 beta 情況下執行工具鏈與清理動作
  test:
    # Job 名稱，會顯示在 UI 中
    name: 2. TEST
    # 執行環境為 Ubuntu runner
    runs-on: ubuntu
    # 依賴 build job 的輸出
    needs: [build]
    # 只有 build 判定為 beta 時才執行
    if: ${{ needs.build.outputs.is_beta == 'true' }}
    # 由 build job 傳入版本號
    env:
      VERSION: ${{ needs.build.outputs.version }}
    # 對外輸出的 job 結果
    outputs:
      # 目前 workflow 內沒有名為 docker-template 的 step；此輸出是否可取得需人工確認。
      message: ${{ steps.docker-template.outputs.message }}
    # 具體步驟
    steps:
    # 安裝或設定 LLM CLI。
    - name: Setup LLM CLI
      # 使用對應的 setup action。
      uses: https://gitea.jsc.idv.tw/actions/setup-${{ vars.ACTION_SETUP_LLM_CLI }}
      # 傳入設定。
      with:
        # LLM CLI 的 OAuth 憑證。
        oauth: ${{ secrets.LLM_OAUTH }}
    # 執行 AI Code Review action。
    - name: Run AI Code Review
      # step id，方便追蹤。
      id: ai-code-review
      # 使用本 repo 發佈的 action。
      uses: https://gitea.jsc.idv.tw/actions/ai-code-review@${{ vars.ACTION_AI_CODE_REVIEW_VERSION }}
      # action 參數。
      with:
        # 存取 Gitea API 的 token。
        token: ${{ secrets.TOKEN }}
        # 指定 LLM 模型名稱。
        model: ${{ vars.LLM_NAME }}
    # 執行 cleanup-release action。
    - name: Run Cleanup Release
      # 這裡使用 build job 的版本輸出組出 tag；若版本來源不同，需人工確認。
      uses: https://gitea.jsc.idv.tw/actions/cleanup-release@v${{ env.VERSION }}
  # 第三階段：輸出結果
  result:
    # Job 名稱，會顯示在 UI 中
    name: 3. RESULT
    # 執行環境為 Ubuntu runner
    runs-on: ubuntu
    # 依賴 build 與 test job 完成
    needs: [build,test]
    # 取得 build job 輸出的版本
    env:
      VERSION: ${{ needs.build.outputs.version }}
    # 具體步驟
    steps:
    # 顯示版本，讓執行紀錄可直接查看。
    - name: Show Version
      run: echo "$VERSION"