# 程式 repo 狀態同步設定

## 目的

文件網站需要顯示程式 repo 的最新開發狀態，讓主管、工程人員與 Codex 可以快速確認目前程式版本、分支、commit 訊息與下一步。

目前採用 GitHub Actions 串接：

```text
程式 repo push
  -> 程式 repo workflow 送出 repository_dispatch
  -> 文件 repo workflow 接收 code-status-updated
  -> 寫入 status.json 與 public/status.json
  -> 文件 repo 自動 commit
  -> Cloudflare Pages 重新部署
```

## 相關 repo

| repo | 用途 |
|---|---|
| `hs-device-control-template` | 程式碼、測試與 ConsoleHost 開發 |
| `hs-device-control-template-docs` | 文件網站、進度總覽與狀態顯示 |

## 需要的 GitHub Secret

程式 repo 需要設定：

```text
DOCS_REPO_DISPATCH_TOKEN
```

此 token 需要能對 `Hongsen-tw/hs-device-control-template-docs` 送出 `repository_dispatch`，並能讀取必要的 repository metadata。

## 自動更新的檔案

文件 repo workflow 會更新：

```text
status.json
public/status.json
```

這兩個檔案代表「最新程式狀態」，不代表完整開發進度百分比。

## status.json 欄位

| 欄位 | 說明 |
|---|---|
| `repo` | 程式 repo 名稱 |
| `repoUrl` | 程式 repo URL |
| `branch` | 程式 repo 分支 |
| `commit` | 完整 commit SHA |
| `shortCommit` | 短 commit SHA |
| `commitMessage` | commit 訊息 |
| `commitUrl` | commit URL |
| `updatedAt` | 程式 repo commit 時間 |
| `stage` | 目前階段摘要 |
| `nextStep` | 建議下一步 |
| `source` | 狀態來源 |

## 與 progress.json 的分工

| 檔案 | 更新方式 | 責任 |
|---|---|---|
| `status.json` | GitHub Actions 自動更新 | 最新 commit、分支、commit 訊息與下一步 |
| `progress.json` | 人工整理後更新 | 第一階段完成度、第二階段進度、長期進度、測試數、摘要與剩餘缺口 |

進度百分比涉及工程判斷，不建議由 commit 次數或測試數自動推算。

## 編碼注意事項

- workflow 與文件一律使用 UTF-8。
- GitHub Actions 內的中文 `name`、`description`、commit 訊息與 `stage` / `nextStep` 需保持可讀繁體中文。
- 若 `status.json` 出現亂碼，需優先檢查程式 repo 的通知 workflow 是否已經送出亂碼 payload。

## 檢查方式

1. 程式 repo push 後，檢查 `通知文件 repo 更新開發狀態` workflow 是否成功。
2. 文件 repo 檢查 `同步程式 repo 開發狀態` workflow 是否成功。
3. 檢查 `status.json` 與 `public/status.json` 是否更新到最新 commit。
4. 檢查文件首頁是否能顯示最新 commit。
5. 若進度百分比未變動，需確認是否尚未人工更新 `progress.json`。