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

.gitea/workflows/master.yaml

@@ -1,28 +1,48 @@
 # --------------------------------------------------
-# 用途：定義 CD 工作流程，於 master push 後部署並顯示相關 tag。
-# 更新日期：2026/07/11 17:44:33（Asia/Taipei）
+# 用途：定義 CD 工作流程，於 master push 後找出對應 tag 並輸出結果。
+# 更新日期：2026/07/11 21:08:44（Asia/Taipei）
 # --------------------------------------------------
 
+# 工作流程名稱。
 name: CD
+
+# 定義觸發條件。
 on:
+  # 只在 push 事件上執行。
   push:
+    # 限定 master 分支，避免其他分支觸發部署流程。
     branches:
+      # 正式分支。
       - master
+
+# 定義部署工作。
 jobs:
+  # deploy job：檢出原始碼並找出 commit 對應的 tag。
   deploy:
+    # 顯示名稱。
     name: DEPLOY
+    # 使用 Ubuntu runner。
     runs-on: ubuntu
+    # 由 push 事件中的 commits 取出要查找的 commit SHA。
     env:
+      # 目前流程預設取第二筆 commit 的 id；此索引是否永遠存在需人工確認。
       COMMIT_SHA: ${{ gitea.event.commits[1].id }}
+    # 定義 deploy job 的步驟。
     steps:
+      # 先檢出完整原始碼與 tag 歷史，讓後續可以查詢 tag。
       - name: Source Code Checkout
+        # 使用 checkout action，版本由倉庫變數控制。
         uses: actions/checkout@${{ vars.ACTION_CHECKOUT_VERSION }}
         with:
+          # 取得完整歷史，避免 tag 查詢因淺層 clone 而失敗。
           fetch-depth: 0
+      # 根據 COMMIT_SHA 找出包含該提交的最新 tag。
       - name: Get Commit Tag
+        # 將查到的 tag 寫入 Gitea output。
         id: commit
         run: >-
           echo "tag=$(git for-each-ref --sort=-refname --format='%(refname:strip=2)' refs/tags --contains ${{ env.COMMIT_SHA }} | head -n 1)" >> $GITEA_OUTPUT
+      # 將查到的 tag 輸出到日誌，方便人工確認。
       - name: Show Tag
         run: >-
           echo "[DEPLOY][INF][$(TZ='Asia/Taipei' date +'%Y/%m/%d %H:%M:%S')]: ${{ steps.commit.outputs.tag }}"