# 用途：CI workflow 的 command-file 草稿，保留原始流程並補上逐行說明。
# 更新時間：2026/07/11 19:00:45
# workflow 名稱，對應 Gitea UI 中的顯示標題。
name: CI
# 定義此 workflow 的觸發事件。
on:
  # 在 pull request 事件時執行。
  pull_request:
    # 只在建立與同步更新 PR 時觸發。
    types: [opened, synchronize]
# workflow 內的工作列表。
jobs:
  # 第一個 job：負責版本計算與 release 發佈。
  build:
    # job 顯示名稱，用來區分執行階段。
    name: 1. BUILD
    # 使用 Ubuntu runner 執行。
    runs-on: ubuntu
    # job 層級環境變數。
    env:
      # 目標分支為 develop 時視為 beta。
      IS_BETA: ${{ gitea.base_ref == 'develop' }}
    # 對外輸出供後續 job 使用。
    outputs:
      # 輸出版本字串。
      version: ${{ steps.calculate-version.outputs.version }}
      # 輸出是否為 beta。
      is_beta: ${{ env.IS_BETA }}
    # build job 的執行步驟。
    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 的環境變數。
      env:
        # 取前一步算出的版本號。
        VERSION: ${{ steps.calculate-version.outputs.version }}
      # release action 的參數。
      with:
        # release 名稱。
        name: "${{ gitea.event.repository.name }} v${{ env.VERSION }}"
        # release tag 名稱。
        tag_name: "v${{ env.VERSION }}"
        # 指向目前提交。
        target_commitish: ${{ gitea.sha }}
        # beta 情境時標記為 prerelease。
        prerelease: ${{ env.IS_BETA }}
  # 第二個 job：在 beta 情境執行 AI Code Review。
  test:
    # job 顯示名稱。
    name: 2. TEST
    # 使用 Ubuntu runner。
    runs-on: ubuntu
    # 必須等 build job 完成。
    needs: [build]
    # 只有 beta 情境才執行。
    if: ${{ needs.build.outputs.is_beta == 'true' }}
    # job 層級環境變數。
    env:
      # 使用 build job 輸出的版本號。
      VERSION: ${{ needs.build.outputs.version }}
    # test job 的步驟。
    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@v${{ env.VERSION }}
      # action 參數。
      with:
        # 存取 Gitea API 的 token。
        token: ${{ secrets.TOKEN }}
        # 指定 LLM 模型名稱。
        model: ${{ vars.LLM_NAME }}
  # 第三個 job：輸出最終版本資訊。
  result:
    # job 顯示名稱。
    name: 3. RESULT
    # 使用 Ubuntu runner。
    runs-on: ubuntu
    # 需等待前兩個 job。
    needs: [build,test]
    # job 層級環境變數。
    env:
      # 延續 build 的版本號。
      VERSION: ${{ needs.build.outputs.version }}
    # result job 的步驟。
    steps:
    # 顯示版本號。
    - name: Show Version
      # 將版本輸出到 log。
      run: echo "$VERSION"