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

action.yaml

@@ -1,18 +1,42 @@
+# =============================================================================
+# 用途：此檔為 calculate-version Gitea Action 的定義，宣告其 inputs（is_beta）、
+#       outputs（version）與以 docker 方式執行時注入給容器的環境變數。
+# 更新日期：2026/06/30 16:31:09
+# =============================================================================
+
+# Action 名稱，會顯示於 Gitea workflow 執行畫面上以利辨識
 name: 'Calculate Version'
+# Action 簡述，說明此 Action 的功能為計算版本號
 description: '計算版本號'
+# Action 作者標示，供維護與聯絡用
 author: 'Jeffery'
+# inputs 區塊：宣告呼叫此 Action 時可傳入的參數
 inputs:
+  # is_beta：控制此次要計算穩定版還是 beta 版本號的旗標
   is_beta:
+    # 參數說明：是否為 beta 版本
     description: '是否為 beta 版本'
+    # 預設值為 false，表示未指定時預設計算穩定版本號
     default: false
+# outputs 區塊：宣告此 Action 執行後對外提供的輸出值
 outputs:
+  # version：容器內主程式計算完成後寫出的版本號，供後續步驟取用
   version:
+    # 輸出說明：計算出的版本號
     description: '計算出的版本號'
+# runs 區塊：定義此 Action 的執行方式與相關設定
 runs:
+  # 以 docker 容器方式執行此 Action
   using: 'docker'
+  # 指定容器映像來源為同目錄的 Dockerfile，會即時建置成映像後執行
   image: 'Dockerfile'
+  # env 區塊：把 Gitea 平台 context 與 inputs 對應成容器內環境變數，供 Node.js 主程式（app/index.js）讀取
   env:
+    # 注入 Gitea 伺服器網址，供主程式組出 release API 端點時使用
     GITEA_SERVER_URL: ${{ gitea.server_url }}
+    # 注入目前 repository（owner/repo），供主程式定位要查詢 release 的儲存庫
     GITEA_REPOSITORY: ${{ gitea.repository }}
+    # 注入 Gitea token，供主程式呼叫 release API 時通過身分驗證（屬敏感憑證，勿外洩）
     GITEA_TOKEN: ${{ gitea.token }}
+    # 將 inputs.is_beta 對應成 IS_BETA 環境變數，供主程式判斷要推算穩定版或 beta 版本號
     IS_BETA: ${{ inputs.is_beta }}