jiantw83andClaude Opus 5
57e45dd63e
正本釘住三件事：期間怎麼切、落差怎麼讀、印到哪裡為止。報表只印在終端， 不張貼到議題、PR 或任何管道——要給誰看是使用者的決定，不是這個流程的。 時分格式由腳本算好，正本明令直接取用：報表上的數字自己算錯，比沒有報表更糟。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
92 lines
4.5 KiB
Markdown
92 lines
4.5 KiB
Markdown
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，要看別的就再跑一次。
|