docs(README): 重建專案 README 與工作流說明

.gitea/workflows/readme.md

@@ -1,9 +1,52 @@
-# GITEA COMPOSITE ACTION 的工作流列表
+# GITEA 工作流說明
 
-- CI
-  - BUILD
-  - TEST
-  - RESULT
-- CD
-  - BUILD
-  - DEPLOY
+## 總覽
+
+目前專案內有 2 條 workflow 與 1 份 workflow README 文件：
+
+| Workflow 名稱 | 檔案位置 | 觸發條件 | 用途 |
+| --- | --- | --- | --- |
+| CI | `.gitea/workflows/ci.yaml` | `pull_request` 到 `master`、`develop`，事件類型為 `opened`、`synchronize` | 在 PR 階段建立版本、發佈 release，並在 beta 情境下執行工具鏈與清理動作 |
+| CD | `.gitea/workflows/master.yaml` | `push` 到 `master` | 在主分支推送後取得 commit tag，作為部署或版本追蹤依據 |
+| WORKFLOW README | `.gitea/workflows/readme.md` | 文件檔，無觸發條件 | 整理 workflow 名稱、觸發條件與注意事項，方便維護與查閱 |
+
+## CI
+
+- 檔案位置：`.gitea/workflows/ci.yaml`
+- 用途：在 pull request 階段先建立版本、發佈 release，並在 beta 情境下執行後續工具鏈與清理動作。
+- 觸發條件：PR 指向 `master` 或 `develop`，且事件為 `opened` 或 `synchronize`。
+- 主要參數：
+  - `vars.ACTION_CALCULATE_VERSION`：版本計算 action 版本。
+  - `vars.ACTION_GITEA_RELEASE_VERSION`：release action 版本。
+  - `vars.ACTION_SETUP_LLM_CLI`：LLM CLI 設定 action 名稱或版本識別。
+  - `vars.ACTION_AI_CODE_REVIEW_VERSION`：AI code review action 版本。
+  - `vars.LLM_NAME`：模型名稱。
+  - `secrets.LLM_OAUTH`：LLM CLI OAuth 憑證。
+  - `secrets.TOKEN`：Gitea API token。
+  - `gitea.run_number`、`gitea.base_ref`、`gitea.sha`：版本號、beta 判斷與 release target commit。
+- 重要注意事項：
+  - `build` job 先計算版本，再發佈 release；`Publishing Release` 這個 step 的 `env.VERSION` 是否能被後續表達式正確使用，需人工確認。
+  - `test` job 目前有 `outputs.message` 指向 `steps.docker-template.outputs.message`，但現有 steps 中沒有 `docker-template` step，這一點需人工確認。
+  - `Run Cleanup Release` 目前使用 `env.VERSION` 組 action 版本字串，實際是否與預期發布版本一致，需人工確認。
+  - `result` job 只輸出版本號，不再輸出訊息內容，與舊版流程不同。
+
+## CD
+
+- 檔案位置：`.gitea/workflows/master.yaml`
+- 用途：在 `master` 分支推送後 checkout 原始碼並顯示對應 commit tag。
+- 觸發條件：`push` 到 `master`。
+- 主要參數：
+  - `vars.ACTION_CHECKOUT_VERSION`：checkout action 版本。
+  - `gitea.event.commits[1].id`：用於 `git describe --contains` 的 commit SHA。
+  - `GITEA_OUTPUT`：job step 輸出檔案。
+- 重要注意事項：
+  - `gitea.event.commits[1]` 的索引是否一定存在，需人工確認，避免 push 內容少於兩筆 commit 時出錯。
+  - `fetch-depth: 0` 是為了讓 `git describe` 能讀取完整歷史，不能省略。
+
+## readme
+
+- 檔案位置：`.gitea/workflows/readme.md`
+- 用途：整理 workflow 名稱、觸發條件與注意事項，方便快速查閱。
+- 觸發條件：無，這是文件檔。
+- 主要參數：無。
+- 重要注意事項：此文件不改動任何 workflow 設定，只負責說明與彙整。