docs(calculate-version): 重整 action 與 workflow 文件

.gitea/workflows/ci.yaml

@@ -1,73 +1,139 @@
 # --------------------------------------------------
 # 用途：定義 CI 工作流程，處理 pull request 的版本發佈與測試。
-# 更新日期：2026/07/11 17:44:33（Asia/Taipei）
+# 更新日期：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" }}