docs(AI Code Review): 補齊 action 與 workflow 註解說明

.gitea/workflows/readme.md

@@ -1,9 +1,49 @@
-# GITEA NODE ACTION 的工作流列表
+# GITEA NODE ACTION 工作流說明草稿
 
-- CI
-  - BUILD
-  - TEST
-  - RESULT
-- CD
-  - BUILD
-  - DEPLOY
+更新時間：2026/07/11 18:54:51
+
+## 總覽
+
+此專案目前包含兩個 workflow：
+
+- `CI`：處理 pull request 期間的版本計算、釋出與 AI 程式碼審查。
+- `CD`：處理推送到 `master` 分支後的部署相關檢查與資訊輸出。
+
+## Workflow 明細
+
+### CI
+
+- 檔案位置：`.gitea/workflows/ci.yaml`
+- 用途：在 pull request 事件中計算版本，必要時建立 release，並在 beta 情境下執行 AI 程式碼審查。
+- 觸發條件：`pull_request`，事件類型為 `opened` 與 `synchronize`。
+- 主要輸入 / 環境參數：
+  - `gitea.base_ref`：用來判斷是否為 `develop`，進而決定 `IS_BETA`。
+  - `vars.ACTION_CALCULATE_VERSION`：提供 `calculate-version` action 的版本。
+  - `vars.ACTION_GITEA_RELEASE_VERSION`：提供 release action 的版本。
+  - `secrets.LLM_OAUTH`：設定 LLM CLI 的 OAuth。
+  - `secrets.TOKEN`：提供 AI 程式碼審查 action 存取 Gitea API。
+  - `vars.LLM_NAME`：指定審查使用的模型名稱。
+- 重要注意事項：
+  - `test` job 只會在 `IS_BETA == true` 時執行，也就是 pull request 目標分支為 `develop` 時。
+  - `Publishing Release` 會使用 `VERSION` 與 `gitea.sha` 建立 release 與 tag。
+  - 若變數或 secret 未設定，對應步驟會失敗，需人工確認部署前置條件。
+
+### CD
+
+- 檔案位置：`.gitea/workflows/master.yaml`
+- 用途：在 `master` 分支推送後輸出 Gitea context、檢查提交標籤，作為後續部署流程的基礎。
+- 觸發條件：`push` 到 `master` 分支。
+- 主要輸入 / 環境參數：
+  - `gitea` 事件內容：轉成 `GITEA_CONTEXT` 後交給 `jq` 顯示。
+  - `gitea.event.commits[1].id`：作為 `COMMIT_SHA`，用來查詢 commit tag。
+  - `vars.ACTION_CHECKOUT_VERSION`：提供 `actions/checkout` 的版本。
+  - `GITEA_OUTPUT`：寫入 `git describe --contains` 的結果。
+- 重要注意事項：
+  - `COMMIT_SHA` 取用 commits 陣列的第 2 筆資料，若 push 事件實際只有 1 筆 commit，需人工確認是否會發生索引風險。
+  - `Get Commit Tag` 依賴完整的 git 歷史與 tags，因此 checkout 已設定 `fetch-depth: 0` 與 `fetch-tags: true`。
+  - `Show Gitea Context` 會輸出完整事件內容，若包含敏感資訊，需注意執行環境的日誌保存策略。
+
+## 備註
+
+- 本檔為草稿版本，僅整理 workflow 行為與設定重點，不修改任何 workflow 實際邏輯。
+- 若後續要覆蓋正式檔，請先確認 `ci.yaml` 與 `master.yaml` 的變數與 secret 已在目標環境中正確配置。