docs(calculate-version): 重建 README 並補齊 ci.yaml／action.yaml 指令檔註解與 logger JSDoc

.gitea/workflows/ci.yaml

@@ -1,36 +1,58 @@
 # =============================================================================
 # 用途: calculate-version 專案的 CI workflow。
-#       在 Pull Request 開啟或更新時,觸發 OpenCode AI 程式碼審查。
-# 更新日期: 2026/06/30 12:12:59
+#       在 Pull Request 開啟或更新 (且目標分支非 master) 時,先以 composite
+#       action 釋出並標註 beta 成品版本,再用剛標註出的版本呼叫
+#       calculate-version action 計算版本號。
+# 更新日期: 2026/06/30 16:31:09
 # =============================================================================
 
 # workflow 名稱,顯示於 Gitea Actions 介面。
 name: CI
-# 觸發條件設定。
+# 觸發條件設定,定義此 workflow 在哪些事件下被啟動。
 on:
   # 於 Pull Request 事件觸發。
   pull_request:
-    # 忽略目標分支為 master 的 PR (master 走 CD 流程,不在此審查)。
+    # 忽略目標分支為 master 的 PR (master 走 CD 流程,不在此 CI 審查)。
     branches-ignore:
+    # 排除清單的單一項目: master 分支。
     - master
-    # 僅在 PR 開啟 (opened) 或有新 commit 推送 (synchronize) 時觸發。
+    # 僅在 PR 開啟 (opened) 或有新 commit 推送 (synchronize) 時觸發,避免其他 PR 事件 (如關閉) 重複觸發。
     types: [opened, synchronize]
+# 定義此 workflow 要執行的所有 job。
 jobs:
+  # 第一個 job: 釋出並標註成品版本,並將版本號往外拋給後續 job 使用。
   release-tag-version:
+    # job 顯示名稱。
     name: Release Tag Version
+    # 指定執行環境 (runner) 標籤為 ubuntu。
     runs-on: ubuntu
+    # 宣告此 job 的輸出,供後續 needs 此 job 的其他 job 取用。
     outputs:
+      # 將下方 id 為 release-tag-version 的 step 所輸出的 version,設為此 job 的對外 version 輸出 (關鍵點: 透過 outputs 把標註出的版本往外拋)。
       version: ${{ steps.release-tag-version.outputs.version }}
+    # 此 job 依序執行的步驟。
     steps:
+    # 步驟: 呼叫 composite action 進行釋出並標註成品版本。
     - name: 釋出並標註成品版本
+      # 設定此 step 的 id,讓上方 outputs 可用 steps.release-tag-version.outputs.version 取得其輸出。
       id: release-tag-version
+      # 引用 release-tag-version composite action,版本以變數 vars.ACTION_RELEASE_TAG_VERSION 釘選 (集中於 repo/org 變數管理,便於統一升版)。
       uses: https://gitea.jsc.idv.tw/composite-actions/release-tag-version@${{ vars.ACTION_RELEASE_TAG_VERSION }}
+      # 傳遞給該 action 的輸入參數。
       with:
+        # is_beta 設為 true 表示走 beta 標版流程 (標註的是 beta 成品版本,而非正式版)。
         is_beta: true
+  # 第二個 job: 以前一個 job 標註出的版本來計算版本號。
   calculate-version:
+    # job 顯示名稱。
     name: Calculate Version
+    # 指定執行環境 (runner) 標籤為 ubuntu。
     runs-on: ubuntu
+    # 宣告相依於 release-tag-version job: 需等其成功後才執行,並可透過 needs 取得其 outputs (關鍵點: 以此取得剛標註出的版本)。
     needs: release-tag-version
+    # 此 job 依序執行的步驟。
     steps:
+    # 步驟: 呼叫 calculate-version action 計算版本號。
     - name: 計算版本號
+      # 引用本專案的 calculate-version action,並以 @v<version> 釘選自身 action 版本; 其中 version 來自上一個 job 透過 needs 取得的 outputs.version (關鍵點: 用剛標註的版本釘選自身)。
       uses: https://gitea.jsc.idv.tw/docker-actions/calculate-version@v${{ needs.release-tag-version.outputs.version }}