程式 repo 狀態同步設定

目的

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

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

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

需要的 GitHub Secret

程式 repo 需要設定 DOCS_REPO_DISPATCH_TOKEN。此 token 需要能對 Hongsen-tw/hs-device-control-template-docs 送出 repository_dispatch，並能讀取必要的 repository metadata。

自動更新的檔案

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。

檢查方式

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