# --------------------------------------------------
# 用途：定義 CI 工作流程，處理 pull request 的版本發佈與測試。
# 更新日期：2026/07/11 21:08:44（Asia/Taipei）
# --------------------------------------------------

# 工作流程名稱。
name: CI

# 定義觸發條件。
on:
  # 只在 pull_request 事件上執行，避免其他事件重複觸發。
  pull_request:
    # 限定 PR 目標分支為 master 與 develop。
    branches:
      # 正式分支。
      - master
      # 開發分支。
      - develop
    # 只在 PR 建立與同步更新時執行。
    types: [opened, synchronize]

# 定義各個 job。
jobs:
  # build job 先建立 release，並計算基礎版本資訊。
  build:
    # 顯示名稱。
    name: 1. BUILD
    # 使用 Ubuntu runner。
    runs-on: ubuntu
    # 供此 job 與後續輸出共用的環境變數。
    env:
      # 預設 beta 版版本字串，使用 run_number 保持唯一。
      VERSION: "0.0.0-beta.${{ gitea.run_number }}"
      # 只要 PR 的 base branch 是 develop，就視為 beta 流程。
      IS_BETA: ${{ gitea.base_ref == 'develop' }}
    # 將環境變數輸出到下游 job。
    outputs:
      # 提供 test job 使用的版本號。
      version: ${{ env.VERSION }}
      # 提供 test 與 result job 使用的 beta 判斷結果。
      is_beta: ${{ env.IS_BETA }}
    # 定義 build job 的步驟。
    steps:
    # 在 Gitea 上建立 release，並讓 tag 與版本對齊。
    - name: Publishing Release
      # 使用外部 release action，版本由倉庫變數控制。
      uses: akkuman/gitea-release-action@${{ vars.ACTION_GITEA_RELEASE_VERSION }}
      with:
        # release 名稱包含倉庫名稱與版本號。
        name: "${{ gitea.event.repository.name }} v${{ env.VERSION }}"
        # tag 名稱固定使用 v 前綴。
        tag_name: "v${{ env.VERSION }}"
        # 對應到目前提交。
        target_commitish: ${{ gitea.sha }}
        # beta 分支建立 prerelease，正式分支則不是。
        prerelease: ${{ env.IS_BETA }}

  # test job 以 build 輸出為基礎執行版本計算與 beta 專屬檢查。
  test:
    # 顯示名稱。
    name: 2. TEST
    # 使用 Ubuntu runner。
    runs-on: ubuntu
    # 必須等 build 完成，才能取得版本資訊。
    needs: [build]
    # 將 build 的輸出轉成此 job 的環境變數。
    env:
      # 取用 build job 輸出的版本。
      VERSION: ${{ needs.build.outputs.version }}
      # 取用 build job 輸出的 beta 狀態。
      IS_BETA: ${{ needs.build.outputs.is_beta }}
    # 將 calculate-version 的結果往下輸出。
    outputs:
      # 最終版本號由 calculate-version step 產生。
      version: ${{ steps.calculate-version.outputs.version }}
    # 定義 test job 的步驟。
    steps:
    # 執行 calculate-version action 取得版本號。
    - name: Run Calculate Version
      # 用 commit 對應版本的動態 action 版本。
      id: calculate-version
      uses: https://gitea.jsc.idv.tw/actions/calculate-version@v${{ env.VERSION }}
      with:
        # 將 beta 狀態轉成布林值傳入 action。
        is_beta: ${{ env.IS_BETA == "true" }}
    # beta 流程才需要安裝 LLM CLI。
    - name: Setup LLM CLI
      # 動態指定 setup action 版本。
      uses: https://gitea.jsc.idv.tw/actions/setup-${{ vars.ACTION_SETUP_LLM_CLI }}
      # 只有 beta 分支才執行。
      if: ${{ env.IS_BETA == 'true' }}
      with:
        # 提供 OAuth 憑證給 CLI 安裝流程。
        oauth: ${{ secrets.LLM_OAUTH }}
    # beta 流程才執行 AI Code Review。
    - name: Run AI Code Review
      # 用倉庫變數指定 action 版本。
      uses: https://gitea.jsc.idv.tw/actions/ai-code-review@${{ vars.ACTION_AI_CODE_REVIEW_VERSION }}
      # 步驟 id 供必要時引用輸出。
      id: ai-code-review
      # 只有 beta 分支才執行。
      if: ${{ env.IS_BETA == 'true' }}
      with:
        # 提供 token 給 AI review 流程。
        token: ${{ secrets.TOKEN }}
        # 指定模型名稱。
        model: ${{ vars.LLM_NAME }}

  # result job 只在非 beta 流程時，根據 test 的結果再發佈一次 release。
  result:
    # 顯示名稱。
    name: 3. RESULT
    # 使用 Ubuntu runner。
    runs-on: ubuntu
    # 必須等待 build 與 test 都完成。
    needs: [build, test]
    # 只有正式版才會進到這個 job。
    if: ${{ needs.build.outputs.is_beta == 'false' }}
    # 重新帶入版本與 beta 狀態，供 release 步驟使用。
    env:
      # 取用 test job 算出的版本號。
      VERSION: ${{ needs.test.outputs.version }}
      # 取用 build job 的 beta 狀態。
      IS_BETA: ${{ needs.build.outputs.is_beta }}
    # 定義 result job 的步驟。
    steps:
    # 再次發佈 release，作為正式結果。
    - name: Publishing Release
      # 與 build job 使用相同的 release action 與版本來源。
      uses: akkuman/gitea-release-action@${{ vars.ACTION_GITEA_RELEASE_VERSION }}
      with:
        # release 名稱包含倉庫名稱與最終版本號。
        name: "${{ gitea.event.repository.name }} v${{ env.VERSION }}"
        # 使用與 build 相同的 tag 命名方式。
        tag_name: "v${{ env.VERSION }}"
        # 指向目前提交。
        target_commitish: ${{ gitea.sha }}
        # 這裡再次判斷是否為 beta，正式版時會是 false。
        prerelease: ${{ env.IS_BETA == "true" }}