feat/sdlc-report-timesheet/main #34

2026-09-17T06:51:22Z

jiantw83 commented

2026-09-17 06:51:22 +00:00

摘要

以 /sdlc-report 產出可以直接在週會上使用的工時報表：本週、指定月份、指定年份三種期間，
附上估算與實際的落差。報表只印在終端，不對任何管道張貼。

需求議題

#1 — tea-sdlc：以 tea 驅動 SDLC 全流程的跨平台指令組

工作包議題

#16 — 以 sdlc-report 產出工時報表

變更內容

檔案	做什麼
`scripts/report.js`	新增。期間切分、工時彙總、估算落差，單行 JSON 輸出
`scripts/issue-body.js`	新增 `labelledNumber`，讀「標籤：數字」那一行
`templates/report.md`	新增。報表輸出格式，四段：總計／分段小計／逐議題／附註
`prompts/sdlc-report.md`	新增。流程正本
`test/report.test.js`	新增，38 則
`test/sdlc-report-assets.test.js`	新增，16 則

flag 介面：--repo 必填，--week（預設）／--month YYYY-MM／--year YYYY 三選一，
另有 --today、--day-hours、--host、--dry-run。

設計重點

期間以週五當錨點。 一週為週一至週日；跨月那一週依該週週五所屬月份歸屬；W1–W5 指該週五是
當月第幾個週五。錨在週五，一筆工時就只會落在一個月裡，跨月週不會被前後兩個月各算一次。

工時取自 /user/times。 它永遠只回傳自己的工時，不需要 issue manager 權限，也就不會把
別人的工時混進自己的報表；repo 的篩選因此在本地做。

估算讀議題 body，不讀 time_estimate。 該欄位的 API 寫不進去（見 issue-update.js 的
說明），議題上唯一可信的估算是「關聯」段落裡的 估算人天：N。又因為 /user/times 內嵌的
議題不保證帶 body，缺 body 時補查一次議題——少了這一步，整欄估算會靜靜變成 null 而報表
仍回報成功。

總計的落差只涵蓋有估算的議題。 拿全部實際去比只有部分議題的估算，會讓沒估算的工時整批
變成「超出估算」。輸出把 實際秒 與 已估實際秒 並排，兩者的差就是沒估算的部分有多大。

時區。 週界以執行者所在時區切，日期算術一律走 UTC 的 Date 當中間格式，不被日光節約搬動。

解決的問題

工時原本靠記憶補登、週會前臨時湊數字；估算做完就沒有回頭比對，下次估算也就不會變準。這一段
把「哪一筆工時算在哪一週、哪一週算在哪個月」固定成不會因人而異的規則，並把估算與實際擺在一起。

影響的功能

新增一支唯讀腳本，不改動任何既有腳本的行為。
scripts/issue-body.js 只新增一支匯出函式，既有匯出未更動。
唯讀：整趟只有四層前置檢查那支寫入權探針（PATCH 不存在的議題 0）不是 GET，它不改動任何東西。

測試結果

在本分支的確切內容上執行 npm test（node --test）：

ℹ tests 328
ℹ pass 328
ℹ fail 0

新增的 54 則涵蓋六條驗收標準，包含三種週次歸屬的邊界案例：跨月（2026-02-01 歸 2026-01 的 W5）、
跨年（2025-12-29 歸 2026 年）、當月五個週五（2026-01 排到 W5）。時區在測試中固定為
Asia/Taipei——週界是以人在的時區切的，不釘住時區就等於沒釘住答案。

對真實 Gitea 驗過 --dry-run 與錯誤路徑；plugins/tea-sdlc 本身尚未開啟時間追蹤，
因此會停在 TIME_TRACKER_OFF，報表尚未對真實工時跑過。

🤖 Generated with Claude Code

## 摘要以 `/sdlc-report` 產出可以直接在週會上使用的工時報表：本週、指定月份、指定年份三種期間，附上估算與實際的落差。報表只印在終端，不對任何管道張貼。 ## 需求議題 #1 — tea-sdlc：以 tea 驅動 SDLC 全流程的跨平台指令組 ## 工作包議題 #16 — 以 sdlc-report 產出工時報表 ## 變更內容 | 檔案 | 做什麼 | | --- | --- | | `scripts/report.js` | 新增。期間切分、工時彙總、估算落差，單行 JSON 輸出 | | `scripts/issue-body.js` | 新增 `labelledNumber`，讀「標籤：數字」那一行 | | `templates/report.md` | 新增。報表輸出格式，四段：總計／分段小計／逐議題／附註 | | `prompts/sdlc-report.md` | 新增。流程正本 | | `test/report.test.js` | 新增，38 則 | | `test/sdlc-report-assets.test.js` | 新增，16 則 | flag 介面：`--repo` 必填，`--week`（預設）／`--month YYYY-MM`／`--year YYYY` 三選一，另有 `--today`、`--day-hours`、`--host`、`--dry-run`。 ## 設計重點 **期間以週五當錨點。** 一週為週一至週日；跨月那一週依該週週五所屬月份歸屬；W1–W5 指該週五是當月第幾個週五。錨在週五，一筆工時就只會落在一個月裡，跨月週不會被前後兩個月各算一次。 **工時取自 `/user/times`。** 它永遠只回傳自己的工時，不需要 issue manager 權限，也就不會把別人的工時混進自己的報表；repo 的篩選因此在本地做。 **估算讀議題 body，不讀 `time_estimate`。** 該欄位的 API 寫不進去（見 `issue-update.js` 的說明），議題上唯一可信的估算是「關聯」段落裡的 `估算人天：N`。又因為 `/user/times` 內嵌的議題不保證帶 `body`，缺 body 時補查一次議題——少了這一步，整欄估算會靜靜變成 `null` 而報表仍回報成功。 **總計的落差只涵蓋有估算的議題。** 拿全部實際去比只有部分議題的估算，會讓沒估算的工時整批變成「超出估算」。輸出把 `實際秒` 與 `已估實際秒` 並排，兩者的差就是沒估算的部分有多大。 **時區。** 週界以執行者所在時區切，日期算術一律走 UTC 的 `Date` 當中間格式，不被日光節約搬動。 ## 解決的問題工時原本靠記憶補登、週會前臨時湊數字；估算做完就沒有回頭比對，下次估算也就不會變準。這一段把「哪一筆工時算在哪一週、哪一週算在哪個月」固定成不會因人而異的規則，並把估算與實際擺在一起。 ## 影響的功能 - 新增一支唯讀腳本，不改動任何既有腳本的行為。 - `scripts/issue-body.js` 只新增一支匯出函式，既有匯出未更動。 - 唯讀：整趟只有四層前置檢查那支寫入權探針（PATCH 不存在的議題 0）不是 GET，它不改動任何東西。 ## 測試結果在本分支的確切內容上執行 `npm test`（node --test）： ``` ℹ tests 328 ℹ pass 328 ℹ fail 0 ``` 新增的 54 則涵蓋六條驗收標準，包含三種週次歸屬的邊界案例：跨月（2026-02-01 歸 2026-01 的 W5）、跨年（2025-12-29 歸 2026 年）、當月五個週五（2026-01 排到 W5）。時區在測試中固定為 `Asia/Taipei`——週界是以人在的時區切的，不釘住時區就等於沒釘住答案。對真實 Gitea 驗過 `--dry-run` 與錯誤路徑；`plugins/tea-sdlc` 本身尚未開啟時間追蹤，因此會停在 `TIME_TRACKER_OFF`，報表尚未對真實工時跑過。 🤖 Generated with [Claude Code](https://claude.com/claude-code)

jiantw83 added 3 commits 2026-09-17 06:51:23 +00:00

feat(工時報表): 以 report.js 產出週／月／年工時報表 fc30df15f2

期間固定以週五當錨點：一週為週一至週日，跨月那一週依該週週五所屬月份歸屬，
一筆工時因此只會落在一個月裡，不會被前後兩個月各算一次。

工時取自 /user/times——它永遠只回傳自己的工時，不必有 issue manager 權限，
repo 的篩選因此在本地做。估算讀的是議題「關聯」段落裡的那一行，不是 Gitea 的
time_estimate 欄位：該欄位的 API 寫不進去，議題上唯一可信的估算就是那一行；
內嵌的議題沒帶 body 時補查一次議題，否則估算會整欄靜靜變成 null。

總計的落差只拿有估算的議題的實際去比。拿全部實際去比只有部分議題的估算，
會讓沒估算的工時全部變成「超出估算」，落差就永遠是灌水的正數。

labelledNumber 放進 issue-body：body 的解析正本在那裡，格式改一次不該動兩個模組。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

feat(流程正本): 新增 sdlc-report 與工時報表模板 57e45dd63e

正本釘住三件事：期間怎麼切、落差怎麼讀、印到哪裡為止。報表只印在終端，
不張貼到議題、PR 或任何管道——要給誰看是使用者的決定，不是這個流程的。

時分格式由腳本算好，正本明令直接取用：報表上的數字自己算錯，比沒有報表更糟。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

test(工時報表): 釘住週次歸屬的跨月、跨年與五個週五 b56216e0f0

時區在測試裡固定為 Asia/Taipei：週界是以人在的時區切的，不釘住時區就等於沒釘住答案。
--today 讓「本週」在 CLI 接縫上釘得住，否則預設期間會跟著系統時鐘漂走。

寫入請求那則斷言誠實列出唯一的非 GET——四層前置檢查的寫入權探針，
而不是先把它濾掉再宣稱整趟沒有寫入。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

admin approved these changes 2026-09-17 06:54:09 +00:00

admin merged commit f736d11049 into master

2026-09-17 06:54:15 +00:00

admin deleted branch feat/sdlc-report-timesheet/main

2026-09-17 06:54:15 +00:00

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: plugins/tea-sdlc#34