tea-sdlc/prompts/sdlc-report.md

name: sdlc-report description: 僅由 /sdlc-report 指令叫用。產出本週、指定月份或指定年份的工時報表，只印在終端。

sdlc-report

把 Gitea 上的碼錶紀錄整理成一份可以直接在週會上使用的工時報表。

這份檔案是流程正本。各平台的轉接檔只是指回這裡，不要把規則抄過去。

輸入

• repo — owner/name。沒給就問，不要猜。
• 期間 — 三選一，沒給就是本週：
  • --week 本週一至今日（預設）
  • --month YYYY-MM 指定月份，含 W1–W5 分段小計
  • --year YYYY 指定年份，以月份分段小計

步驟

1. 取數字

node scripts/report.js --repo <owner/name> [--week | --month YYYY-MM | --year YYYY]

腳本回傳一行 JSON，裡面已經算好總計、分段小計與逐議題明細，時分格式也一併算好了 （實際工時、落差工時）。直接取用那些字串，不要自己再乘一次三千六百 —— 報表上的數字 自己算錯，比沒有報表更糟。

要回頭補印過去的某一週，加 --today YYYY-MM-DD 指定「今天」是哪一天。

2. 套模板印出

套用 templates/report.md，佔位對應如下：

• {{期間}} 期間標籤（期間.標籤）
• {{範圍}} 一行說明這份報表涵蓋哪個 repo、哪段日期、以幾小時當一人天
• {{實際工時}}、{{估算人天}}、{{已估實際}}、{{落差}} 取自 總計
• {{分段}} 每個分段一列表格列；週報沒有分段，連同「分段小計」標題整段不印—— markdown 表格只留表頭不留資料列，在終端上看起來像壞掉，不像「本來就沒有」
• {{議題}} 每顆議題一列表格列，議題欄寫成指回該議題的連結
• {{附註}} 見下方「怎麼讀落差」；沒有要提醒的就填「無」

報表只印在終端。不要張貼到議題、PR、聊天室或任何其他管道——這份要給誰看，是使用者的 決定，不是這個流程的。

3. 回報

印完就結束。不要順手去改議題、不要替使用者補登漏掉的工時。

期間怎麼切

三句話，沒有例外：

1. 一週為週一至週日。
2. 跨月的那一週依「該週週五所屬月份」歸屬。 一筆工時因此只會落在一個月裡， 不會被前後兩個月各算一次。
3. W1–W5 指該週五是當月第幾個週五。 當月有幾個週五就有幾段，有五個就排到 W5。

舉例：2026-01 的第一個週五是 01-02，所以 2025-12-29（週一）那天的工時算在 2026 年 1 月的 W1；2026-02-01（週日）那天的工時，它那一週的週五是 01-30，所以算在 2026 年 1 月的 W5， 而不是 2 月。

年報同理：跨年的那一週也依週五歸屬，2025-12-29 的工時會出現在 2026 年的報表裡。

怎麼讀落差

落差 = 實際工時 − 估算。正數代表超出估算，負數代表還有餘裕。

總計的落差只涵蓋有估算的議題。 分子是 已估實際秒（那些議題的實際工時）而不是 實際秒 （全部）——拿全部實際去比只有部分議題的估算，沒估算的工時會整批變成「超出估算」，落差就永遠 是灌水的正數。報表上把 實際工時 與 已估實際 並排印出來，兩者差多少就是沒估算的部分有多大。

估算讀的是議題「關聯」段落裡的「估算人天」那一行。換算時一人天預設為 8 小時，團隊若不是 這樣算，用 --day-hours 換掉。

有三件事要在 {{附註}} 裡講清楚，否則落差會被讀錯：

• 沒寫估算的議題，落差是空的，不是零。 輸出裡是 null；一顆估算都沒有時，總計的落差也是 null，不要印成 0。
• 工作包還沒做完時，落差本來就會是負的。 估算是整顆工作包的，實際卻只是這段期間內的 那一部分；只有工作包在這段期間內收掉，兩者才真的可以比。
• 略過 不為零時要說出來。 那是查不到議題資訊的工時筆數，它們沒有被算進任何數字裡。

邊界

• 不張貼。報表只印在終端。
• 不寫入 Gitea：不改議題、不補登工時、不動碼錶。腳本唯一的非 GET，是四層前置檢查打在不存在的 議題 0 上那支寫入權探針，它不改動任何東西。
• 不替使用者決定跳過哪些日子。腳本只算實際記錄到的工時，不扣假日、不補上沒按碼錶的時間。
• 不跨 repo 彙總。一次一個 repo，要看別的就再跑一次。