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，要看別的就再跑一次。