Merge pull request 'feat/plan-analyze-timing/main' (#63) from feat/plan-analyze-timing/main into master
Reviewed-on: #63 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>
This commit was merged in pull request #63.
This commit is contained in:
+56
-15
@@ -5,9 +5,9 @@ description: 僅由 /sdlc-analyze 指令叫用。對一顆需求議題執行可
|
||||
|
||||
對一顆需求議題執行可行性檢查，把疑點一題一題問到雙方有共識，再把共識變成一批工作包議題。
|
||||
|
||||
分成三段：**可行性分析**到共識摘要為止，完全不寫入 Gitea；使用者看過摘要點頭之後，
|
||||
才進入**產生工作包**建立議題；最後**排上時程與看板**，把相依、截止日、Milestone、
|
||||
看板與人天估算補上。
|
||||
分成三段：**可行性分析**到共識摘要為止，除了起錶之外完全不寫入 Gitea；使用者看過摘要
|
||||
點頭之後，才進入**產生工作包**建立議題；最後**排上時程與看板**，把相依、截止日、
|
||||
Milestone、看板與人天估算補上。
|
||||
|
||||
這份檔案是流程正本。各平台的轉接檔只是指回這裡，不要把規則抄過去。
|
||||
|
||||
@@ -15,6 +15,17 @@ description: 僅由 /sdlc-analyze 指令叫用。對一顆需求議題執行可
|
||||
|
||||
一個需求議題編號。
|
||||
|
||||
## 計時範圍
|
||||
|
||||
錶起在**它分析的那顆需求議題**上：在「起錶」那一步起，在「停錶並回報」那一步停，
|
||||
涵蓋整道 /sdlc-analyze。
|
||||
|
||||
起點放在第一段開頭，因為分析最耗時的正是共識之前那一段——四類疑點逐題問到收斂。
|
||||
從第二段才起錶的話，那段時間永遠是零，而報表上「分析不花時間」會直接餵給下一次估算。
|
||||
|
||||
錶已經跑在同一顆議題上時起錶什麼都不做，所以 plan 接著跑 analyze 不會把累積的時間
|
||||
切成兩段。**錶不跨階段跑**，也**不碰別顆議題上的錶**。
|
||||
|
||||
## 第一段：可行性分析
|
||||
|
||||
### 1. 讀議題
|
||||
@@ -33,7 +44,22 @@ node scripts/issue-extract.js --repo <owner/name> --index <編號>
|
||||
|
||||
使用者選擇不整併就繼續，但要記下這件事，並在共識摘要裡註明「分析基於未整併留言前的描述」。
|
||||
|
||||
### 2. 對四份清單列出疑點
|
||||
### 2. 起錶
|
||||
|
||||
議題確認存在之後，在**這顆需求議題**上起錶：
|
||||
|
||||
```
|
||||
node scripts/timer.js --repo <owner/name> --index <需求議題編號> --dry-run
|
||||
```
|
||||
|
||||
確認無誤後拿掉 `--dry-run` 再跑一次。錶已經跑在同一顆上時它什麼都不做，重跑不會把
|
||||
已經累積的時間切成兩段。
|
||||
|
||||
錶跑在別顆議題上時會被擋下（`STOPWATCH_ON_OTHER_ISSUE`）。**照實告訴使用者是哪一顆，
|
||||
請他自己去停**，不要代勞：那一段時間該記在哪顆議題上只有他知道。順帶說明停錶不會動到
|
||||
任何既有的工作樹——碼錶只管時間、工作樹只管檔案。
|
||||
|
||||
### 3. 對四份清單列出疑點
|
||||
|
||||
依序讀這四份規則正本，逐條對照議題內容：
|
||||
|
||||
@@ -45,7 +71,7 @@ node scripts/issue-extract.js --repo <owner/name> --index <編號>
|
||||
每一條檢查若在議題裡找不到答案，就轉成一個問題。**能在程式碼裡查證的就自己去查，
|
||||
不要拿去問使用者**——把問題留給只有人能回答的事。
|
||||
|
||||
### 3. 逐題問到共識
|
||||
### 4. 逐題問到共識
|
||||
|
||||
**一次問一題。** 問完等使用者回答，再問下一題，讓他能看著前一題的答案回答下一題。
|
||||
不要一次丟出五個問題，也不要把多個問題包成一題的多個選項。
|
||||
@@ -60,7 +86,7 @@ node scripts/issue-extract.js --repo <owner/name> --index <編號>
|
||||
|
||||
問題本身要具體到能用一句話回答。問不出收斂答案的問題，多半是問題本身太大，拆開再問。
|
||||
|
||||
### 4. 輸出共識摘要
|
||||
### 5. 輸出共識摘要
|
||||
|
||||
全部問完後，輸出一份摘要讓使用者做最後確認，內容包含：
|
||||
|
||||
@@ -75,7 +101,7 @@ node scripts/issue-extract.js --repo <owner/name> --index <編號>
|
||||
|
||||
**使用者對共識摘要點頭之後才開始。** 摘要沒有經過確認就不要往下走。
|
||||
|
||||
### 5. 切出工作包
|
||||
### 6. 切出工作包
|
||||
|
||||
把需求切成幾顆工作包。一顆工作包是**開發者拿了就能動手、做完有明確結果**的單位：
|
||||
它有自己的驗收標準，做完能單獨被檢視，不必等別的工作包一起才看得出成果。
|
||||
@@ -86,7 +112,7 @@ node scripts/issue-extract.js --repo <owner/name> --index <編號>
|
||||
**禁止流水編號與任何無意義代號**（`WP-01`、`任務三`、`第一階段`）：命名本身就要說明用途，
|
||||
看標題就知道這顆在做什麼，不必點進去。
|
||||
|
||||
### 6. 組出每顆工作包的內容
|
||||
### 7. 組出每顆工作包的內容
|
||||
|
||||
套用 `templates/work-package-issue.md`，依序填滿九個段落：
|
||||
|
||||
@@ -111,7 +137,7 @@ node scripts/issue-extract.js --repo <owner/name> --index <編號>
|
||||
8. **repo 列表** — 這顆會動到哪些 repo。
|
||||
9. **關聯** — 至少要有一行 `需求議題：#<編號>` 指回來源。阻擋、先決與人天估算由後續流程補上。
|
||||
|
||||
### 7. 先試跑，再寫入
|
||||
### 8. 先試跑，再寫入
|
||||
|
||||
每顆工作包各寫一個暫存檔，然後逐顆：
|
||||
|
||||
@@ -128,16 +154,18 @@ no-op」。確認無誤後拿掉該旗標再跑一次。
|
||||
中斷後重跑不會產生重複工作包：`issue-create` 以標題查重，發現同名議題就回傳既有那一顆
|
||||
並把 `created` 設為 `false`。
|
||||
|
||||
### 8. 回報
|
||||
### 9. 回報
|
||||
|
||||
列出每顆工作包的編號、標題與網址。不要把議題內容再貼一次。
|
||||
|
||||
**這裡不停錶**——指令還沒跑完，第三段還要排時程。停錶在最後的「停錶並回報」那一步。
|
||||
|
||||
## 第三段：排上時程與看板
|
||||
|
||||
工作包建好之後，把它們之間的關係與時程補上。做完這一段，看板上呈現的才是真實的
|
||||
開發順序，而不是一堆平鋪的議題。
|
||||
|
||||
### 9. 算出截止日
|
||||
### 10. 算出截止日
|
||||
|
||||
把每顆工作包的編號、人天估算與先決關係寫成一份計畫檔：
|
||||
|
||||
@@ -161,7 +189,7 @@ node scripts/schedule.js --plan-file <計畫檔>
|
||||
|
||||
日期以日曆日累加，不跳週末也不扣假日。要跳的話自己把 `startDate` 或人天調整過再算。
|
||||
|
||||
### 10. 逐顆補上關係與時程
|
||||
### 11. 逐顆補上關係與時程
|
||||
|
||||
對每一顆工作包，依序：
|
||||
|
||||
@@ -179,7 +207,7 @@ node scripts/project-add.js --repo <owner/name> --index <編號> --project "<看
|
||||
看板名稱靠掃最近 50 筆議題反查 id，反查不到就會請你直接貼專案網址（結尾即 id）。
|
||||
本流程不建立 Milestone，也不建立專案。
|
||||
|
||||
### 11. 產生分析版的圖解總覽
|
||||
### 12. 產生分析版的圖解總覽
|
||||
|
||||
用同一份 `templates/overview-artifact.html` 再產一份，但這一份要多出**工作包全景**：
|
||||
把工作包之間的相依與截止日畫成一張圖，讓開發者看得出自己這一項在整體中的位置。
|
||||
@@ -205,7 +233,16 @@ node scripts/issue-update.js --repo <owner/name> --index <需求議題編號> --
|
||||
**重跑會就地更新同一行**，不會在議題上留下兩個連結。規劃階段產生的那一份會被這一份取代，
|
||||
這是預期行為——同一顆需求議題只掛一個總覽網址。
|
||||
|
||||
### 12. 回報
|
||||
### 13. 停錶並回報
|
||||
|
||||
回報之前先停錶，這一段計時到此為止：
|
||||
|
||||
```
|
||||
node scripts/timer.js --repo <owner/name> --index <需求議題編號> --stop
|
||||
```
|
||||
|
||||
它**只停這一顆**上的錶，與「起錶」那一步起的是同一顆。錶本來就沒在跑不算失敗
|
||||
（`碼錶已停` 會是 `false` 並附一句說明），回報照樣做完。
|
||||
|
||||
列出每顆工作包的編號、標題、截止日與所屬 Milestone，並指出**相依鏈最長路徑**上的那幾顆
|
||||
——那條路徑決定整體交期。
|
||||
@@ -236,9 +273,13 @@ Gitea 1.27 的 API 沒有任何請求定義接受 `time_estimate`，該欄位只
|
||||
|
||||
## 邊界
|
||||
|
||||
- **共識摘要之前不對 Gitea 產生任何寫入**：不建議題、不改描述、不貼標籤、不留留言。
|
||||
- **共識摘要之前不對 Gitea 寫入任何內容**：不建議題、不改描述、不貼標籤、不留留言。
|
||||
**碼錶除外**——它記的是工時，不是內容；而分析最耗時的正是共識之前那一段，不從那裡
|
||||
起錶，那段時間就永遠是零。
|
||||
- 第二段只建立工作包議題。不建相依、不掛 Milestone、不加看板、不寫人天估算——那是第三段的事。
|
||||
- 第三段只掛既有的 Milestone 與看板。不自行建立標籤、Milestone 或專案看板。
|
||||
- 不修改使用者的專案檔案。查證既有功能時只讀不寫。
|
||||
- 不替使用者決定他沒回答的事。問不到答案就進「仍然未決的事」。
|
||||
- 計時只動這顆需求議題：在它上面起錶、在它上面停錶。**不停別顆議題上的錶**，
|
||||
被別顆的錶擋下時交還給使用者決定，不繞過去。
|
||||
- 不關閉或刪除任何既有議題。
|
||||
|
||||
@@ -66,7 +66,8 @@ node scripts/claim.js --repo <owner/name> --index <編號> --dry-run
|
||||
不講清楚，使用者會以為停錶等於放棄那顆工作包，於是寧可不停——工時就記到別顆去了。
|
||||
| 沒有鎖 | —— | 放行。自己已認領但沒起錶也算沒有鎖，那正是中斷後重跑的情形 |
|
||||
|
||||
碼錶一律由使用者自己停。哪一段時間該記在哪顆議題上只有他知道，代勞會把工時記錯地方。
|
||||
**別顆議題上的錶一律由使用者自己停。** 哪一段時間該記在哪顆議題上只有他知道，代勞會把
|
||||
工時記錯地方。每道指令停掉的只有自己起的那一支——這一道停在「開 PR 並停錶」那一步。
|
||||
|
||||
鎖以外還有一個前置條件：repo 上要有「進行中」標籤。缺了會得到 `LABEL_NOT_FOUND`，
|
||||
請使用者自己去建立——**不要自己建**，標籤體系不該在多個 repo 之間長出雜草。
|
||||
|
||||
+74
-7
@@ -19,13 +19,36 @@ description: 僅由 /sdlc-plan 指令叫用。把一段口語需求轉成結構
|
||||
`scripts/issue-extract.js` 取（若該腳本尚未可用，改用 `scripts/issue-create.js` 以外的
|
||||
既有讀取途徑，並在摘要中註明資料來源）。
|
||||
|
||||
## 計時範圍
|
||||
|
||||
這份正本把整個 /sdlc-plan 的耗時記成兩段，合起來就是這道指令實際花掉的時間：
|
||||
|
||||
- **議題建立之前** — 在「記下開始時間」記下起點，在「補登規劃時間，然後起錶」補上去。
|
||||
議題還不存在，沒有標的可起錶。
|
||||
- **議題建立之後** — 在「補登規劃時間，然後起錶」起錶，在「停錶並回報」停錶。
|
||||
|
||||
起與停都寫在這一份裡，**錶不跨階段跑**：跑完就去開會而錶跑一整天，報表當場失真。
|
||||
反過來，別顆議題上的錶一律不碰——那一段時間該記在哪顆議題上只有使用者知道。
|
||||
|
||||
## 步驟
|
||||
|
||||
### 1. 讀齊輸入，列出還缺什麼
|
||||
### 1. 記下開始時間
|
||||
|
||||
讀齊輸入、逐項詢問、組出議題內容，往往是整個 plan 最耗時的一段，而它發生在議題建立
|
||||
**之前**——那時候沒有標的可起錶。所以先把此刻的時間記下來，等議題建立之後補登上去：
|
||||
|
||||
```
|
||||
node -e "console.log(new Date().toISOString())"
|
||||
```
|
||||
|
||||
記下它，一路帶到「補登規劃時間，然後起錶」那一步。**不要憑印象回推**：補登的長度就是
|
||||
報表上規劃階段的數字。
|
||||
|
||||
### 2. 讀齊輸入，列出還缺什麼
|
||||
|
||||
把九個段落逐一對照使用者給的材料，列出哪些段落已經有依據、哪些沒有。
|
||||
|
||||
### 2. 逐項詢問
|
||||
### 3. 逐項詢問
|
||||
|
||||
**一次問一題**，等使用者回答完再問下一題，讓他能看著前一題的答案回答下一題。
|
||||
|
||||
@@ -34,7 +57,7 @@ description: 僅由 /sdlc-plan 指令叫用。把一段口語需求轉成結構
|
||||
**未獲得答覆的欄位不得自行編造。** 使用者沒說過的目標、沒提過的驗收標準，一個字都不能自己
|
||||
填。問不到就放進「未決事項」，那一段本來就是給未決的東西用的。
|
||||
|
||||
### 3. 組出議題內容
|
||||
### 4. 組出議題內容
|
||||
|
||||
套用 `templates/requirement-issue.md`，依序填滿九個段落：
|
||||
|
||||
@@ -49,13 +72,13 @@ description: 僅由 /sdlc-plan 指令叫用。把一段口語需求轉成結構
|
||||
8. **影響範圍** — 會動到哪些 repo、哪些既有功能。
|
||||
9. **未決事項** — 問不到答案、或需要他人拍板的事。
|
||||
|
||||
### 4. 挑標籤
|
||||
### 5. 挑標籤
|
||||
|
||||
先用 `scripts/labels-list.js --repo <owner/name>` 取得該 repo 的既有標籤，**只能從這份清單裡
|
||||
挑**。找不到合適的就不貼。**不得自行建立新標籤** —— 標籤體系由專案維護者決定，不該在多個
|
||||
repo 之間長出雜草。
|
||||
|
||||
### 5. 先試跑，再寫入
|
||||
### 6. 先試跑，再寫入
|
||||
|
||||
把組好的內容寫到一個暫存檔，然後：
|
||||
|
||||
@@ -69,7 +92,40 @@ node scripts/issue-create.js --repo <owner/name> --title "<標題>" --body-file
|
||||
同一段需求重跑不會產生第二顆議題：`issue-create` 以標題查重，發現同名議題就回傳既有那一顆
|
||||
並把 `created` 設為 `false`。
|
||||
|
||||
### 6. 產生圖解版總覽
|
||||
### 7. 補登規劃時間，然後起錶
|
||||
|
||||
議題有了，計時才有標的。**先補登、再起錶**，兩步指向同一顆議題。
|
||||
|
||||
先把「記下開始時間」到議題建立那一段補上去：
|
||||
|
||||
```
|
||||
node scripts/time-log.js --repo <owner/name> --index <編號> --since <記下的開始時間> --dry-run
|
||||
```
|
||||
|
||||
長度由腳本自己算，不必自己做減法，也不會讓兩邊的時鐘各算一次。終點看議題是不是這一輪
|
||||
建立的：是就補到**議題建立那一刻**，不是（對既有議題重跑）就補到**現在**——那一輪的
|
||||
規劃時間照樣要進報表。確認無誤後拿掉 `--dry-run` 再跑一次。
|
||||
|
||||
**不設時間上限，照實補登。** 中途去開會的那兩個小時會一起被算進去，這是刻意的：換來
|
||||
這個流程不必為此多長一題出來問使用者。時間記多了看得出來，記不到就永遠找不回來。
|
||||
|
||||
補登完才起錶：
|
||||
|
||||
```
|
||||
node scripts/timer.js --repo <owner/name> --index <編號> --dry-run
|
||||
```
|
||||
|
||||
一樣先試跑，確認無誤後拿掉 `--dry-run` 再跑一次。
|
||||
|
||||
順序不能反過來：錶一旦跑在這顆議題上，`time-log` 就會跳過不補——那一段已經有錶在記了，
|
||||
再補一次會與錶涵蓋的區間重疊。**重跑是累計不是覆蓋**，每一輪各記一筆，報表上加總起來
|
||||
才是這顆議題真正花掉的規劃時間。
|
||||
|
||||
錶已經跑在別顆議題上時起錶會被擋下（`STOPWATCH_ON_OTHER_ISSUE`）。**照實告訴使用者
|
||||
是哪一顆，請他自己去停**，不要代勞：那一段時間該記在哪顆議題上只有他知道。順帶說明
|
||||
停錶不會動到任何既有的工作樹——碼錶只管時間、工作樹只管檔案。
|
||||
|
||||
### 8. 產生圖解版總覽
|
||||
|
||||
套用 `templates/overview-artifact.html`，把議題的總覽、目標與流程圖填成一份可以直接投影的
|
||||
網頁。這一份是給**非技術的利害關係人**看的：他們不必讀完技術細節就知道這件事在做什麼。
|
||||
@@ -96,7 +152,16 @@ node scripts/issue-update.js --repo <owner/name> --index <編號> --overview-url
|
||||
議題原本的 markdown 白話總覽一字不動——網頁是補充，不是取代。連結旁會自動附上
|
||||
「此連結預設為私有，組織外無法開啟」，因為讀到的人多半會想轉寄給組織外的人。
|
||||
|
||||
### 7. 回報
|
||||
### 9. 停錶並回報
|
||||
|
||||
回報之前先停錶，這一段計時到此為止：
|
||||
|
||||
```
|
||||
node scripts/timer.js --repo <owner/name> --index <編號> --stop
|
||||
```
|
||||
|
||||
它**只停這一顆**上的錶。錶本來就沒在跑不算失敗（`碼錶已停` 會是 `false` 並附一句
|
||||
說明），回報照樣做完。
|
||||
|
||||
把議題編號與網址告訴使用者。不要把整份議題內容再貼一次 —— 連結點進去就看得到。
|
||||
|
||||
@@ -122,3 +187,5 @@ node scripts/issue-update.js --repo <owner/name> --index <編號> --overview-url
|
||||
- 不建立標籤、不建立 Milestone、不建立專案看板。
|
||||
- 不關閉或刪除任何既有議題。
|
||||
- 規劃階段本身已含問題釐清，因此寫入 Gitea 前不再設額外的確認點；`--dry-run` 就是那道關卡。
|
||||
- 計時只動這顆需求議題：在它上面起錶、在它上面停錶、把規劃時間補登在它上面。
|
||||
**不停別顆議題上的錶**，被別顆的錶擋下時交還給使用者決定，不繞過去。
|
||||
|
||||
@@ -1036,6 +1036,40 @@ export function stopwatchOnIssue(watches, repo, index) {
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* 「這顆議題上沒有碼錶在跑」的回法不只一種：看過 500，也看過 409。
|
||||
* 狀態碼隨站台版本而異，所以認的是「狀態碼在這一組裡 **且** 訊息說的是碼錶」——
|
||||
* 只看訊息會把真的伺服器錯誤一起吞掉，只看狀態碼會把別的衝突也當成沒錶。
|
||||
*/
|
||||
const NO_STOPWATCH_STATUS = [409, 500];
|
||||
|
||||
/**
|
||||
* 停錶。停在指定議題上，只停那一顆——端點本身就是議題範圍的，
|
||||
* 停錶不會波及別顆議題上的錶，那正是領取鎖那條規則要守住的事。
|
||||
*
|
||||
* 錶沒在跑不算失敗：停錶多半排在別的事情做完之後（開完 PR、回報完），
|
||||
* 把「本來就沒在跑」報成失敗，只會讓人以為前面那件事沒做成而重跑一次。
|
||||
*
|
||||
* @param {{base: string, token: string}} login
|
||||
* @param {string} repo owner/name
|
||||
* @param {number} index
|
||||
* @returns {Promise<boolean>} 這次真的停了一支錶才是 true
|
||||
*/
|
||||
export async function stopStopwatch(login, repo, index) {
|
||||
const path = `/repos/${repo}/issues/${index}/stopwatch/stop`;
|
||||
const response = await giteaRequest(login, 'POST', path, { body: {} });
|
||||
if (response.status >= 200 && response.status < 300) return true;
|
||||
|
||||
if (
|
||||
NO_STOPWATCH_STATUS.includes(response.status) &&
|
||||
/stopwatch/i.test(response.body?.message ?? '')
|
||||
) {
|
||||
return false;
|
||||
}
|
||||
expectOk(response, `POST ${path}`);
|
||||
return false;
|
||||
}
|
||||
|
||||
// ── 標籤 ───────────────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
|
||||
+2
-26
@@ -36,6 +36,7 @@ import {
|
||||
preflight,
|
||||
readTextFile,
|
||||
resolveLogin,
|
||||
stopStopwatch,
|
||||
} from './lib.js';
|
||||
|
||||
/** 描述的固定段落，順序即 reviewer 閱讀的順序 */
|
||||
@@ -126,7 +127,7 @@ main(async () => {
|
||||
);
|
||||
|
||||
// 錶只在 PR 確實存在之後才停。既有的 PR 也要停——那一步可能正是上次中斷的地方。
|
||||
const stopped = await stopStopwatch(login, stopPath);
|
||||
const stopped = await stopStopwatch(login, issueRepo, index);
|
||||
|
||||
return {
|
||||
repo,
|
||||
@@ -211,28 +212,3 @@ function checkTestResult(body) {
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 「這顆議題上沒有碼錶在跑」的回法不只一種：看過 500，也看過 409。
|
||||
* 狀態碼隨站台版本而異，所以認的是「狀態碼在這一組裡 **且** 訊息說的是碼錶」——
|
||||
* 只看訊息會把真的伺服器錯誤一起吞掉，只看狀態碼會把別的衝突也當成沒錶。
|
||||
*/
|
||||
const NO_STOPWATCH_STATUS = [409, 500];
|
||||
|
||||
/**
|
||||
* 停錶。錶沒在跑時不算失敗——PR 已經開出去了，把整件事報成失敗只會讓人以為
|
||||
* PR 沒開成而重跑一次。
|
||||
*/
|
||||
async function stopStopwatch(login, path) {
|
||||
const response = await giteaRequest(login, 'POST', path, { body: {} });
|
||||
if (response.status >= 200 && response.status < 300) return true;
|
||||
|
||||
if (
|
||||
NO_STOPWATCH_STATUS.includes(response.status) &&
|
||||
/stopwatch/i.test(response.body?.message ?? '')
|
||||
) {
|
||||
return false;
|
||||
}
|
||||
expectOk(response, `POST ${path}`);
|
||||
return false;
|
||||
}
|
||||
|
||||
@@ -0,0 +1,132 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* 補登一段沒有錶記到的工時。
|
||||
*
|
||||
* 規劃階段最耗時的那一段——讀齊輸入、逐項詢問、組出議題內容——發生在議題建立**之前**，
|
||||
* 那時候沒有標的可起錶（議題還不存在）。這段時間只能事後補登，否則報表上的規劃永遠是零，
|
||||
* 久了會讓人以為規劃不花時間，而那正是估算失準最常見的來源。
|
||||
*
|
||||
* **長度由這支腳本自己算**：終點減掉 `--since`。交給 agent 做減法，等於讓兩邊的時鐘與
|
||||
* 時區各算一次，而算錯了報表上看不出來。
|
||||
*
|
||||
* 終點取哪一刻，看議題是不是這一輪建立的：
|
||||
* - 議題建立於 `--since` 之後 → 終點是**議題的建立時間**。這是第一次跑，補的正是
|
||||
* 「指令開始到議題建立」那一段。
|
||||
* - 議題比 `--since` 還早 → 終點是**補登的當下**。這是對既有議題重跑，那一輪的規劃
|
||||
* 時間照樣要進報表；拿舊的建立時間當終點會算出負數，等於把這一輪的工夫丟掉。
|
||||
*
|
||||
* **不設時間上限，照實補登。** 中途去開會的那兩個小時會一起被算進去——換來這個流程
|
||||
* 不必為此多長一題出來問使用者。時間記多了看得出來，記不到就永遠找不回來。
|
||||
*
|
||||
* **重跑會累計，不會覆蓋**：每一輪各記一筆，報表上加總起來才是這顆議題真正花掉的規劃
|
||||
* 時間。唯一跳過的情形是自己的錶已經跑在這顆議題上——補登排在起錶之前，錶在跑就代表
|
||||
* 這一輪已經走到起錶那一步了，再補一次會與錶涵蓋的區間重疊。
|
||||
*
|
||||
* 只寫工時，不動任何錶——別顆議題上有錶在跑也照補，那兩件事互不相干。
|
||||
*
|
||||
* 用法：
|
||||
* node scripts/time-log.js --repo owner/name --index 42 --since <ISO 8601 時間>
|
||||
* [--host <網址>] [--dry-run]
|
||||
*/
|
||||
import {
|
||||
ScriptError,
|
||||
expectOk,
|
||||
fetchIssue,
|
||||
giteaRequest,
|
||||
listStopwatches,
|
||||
main,
|
||||
parseFlags,
|
||||
parseIndex,
|
||||
parseRepo,
|
||||
preflight,
|
||||
resolveLogin,
|
||||
stopwatchOnIssue,
|
||||
} from './lib.js';
|
||||
|
||||
main(async () => {
|
||||
const flags = parseFlags(process.argv.slice(2), {
|
||||
required: ['repo', 'index', 'since'],
|
||||
optional: ['host'],
|
||||
booleans: ['dry-run'],
|
||||
});
|
||||
const repo = parseRepo(flags.repo);
|
||||
const index = parseIndex(flags.index);
|
||||
const since = parseSince(flags.since);
|
||||
const dryRun = flags['dry-run'] === true;
|
||||
const timesPath = `/repos/${repo}/issues/${index}/times`;
|
||||
|
||||
const login = resolveLogin({ host: flags.host });
|
||||
// 試跑照樣讀現況：手寫一份固定的清單會跟實作走鐘，也說不出「錶已經在跑了」
|
||||
if (!dryRun) await preflight(login, repo);
|
||||
const issue = await fetchIssue(login, repo, index);
|
||||
|
||||
const 建立時間 = Date.parse(issue.created_at);
|
||||
if (Number.isNaN(建立時間)) {
|
||||
throw new ScriptError(
|
||||
'NO_CREATED_AT',
|
||||
`${repo} 的議題 ${index} 沒有可解讀的建立時間，補登的終點判斷不出來`,
|
||||
);
|
||||
}
|
||||
|
||||
// 這一輪建立的議題就補到建立那一刻；既有的議題則補到現在，那一輪的工夫一樣要進報表
|
||||
const 這輪建立 = 建立時間 > since;
|
||||
const 迄 = 這輪建立 ? 建立時間 : Date.now();
|
||||
const 秒數 = Math.round((迄 - since) / 1000);
|
||||
|
||||
const 略過 = await skipReason(login, repo, index, 秒數);
|
||||
const planned = 略過 === null ? [{ method: 'POST', path: timesPath, body: { time: 秒數 } }] : [];
|
||||
const 報告 = {
|
||||
repo,
|
||||
index: issue.number,
|
||||
title: issue.title,
|
||||
url: issue.html_url,
|
||||
since: new Date(since).toISOString(),
|
||||
迄: new Date(迄).toISOString(),
|
||||
依據: 這輪建立 ? '議題建立' : '補登當下',
|
||||
秒數,
|
||||
補登: 略過 === null,
|
||||
...(略過 ? { note: 略過 } : {}),
|
||||
};
|
||||
|
||||
if (dryRun) {
|
||||
return { dryRun: true, ...報告, requests: planned };
|
||||
}
|
||||
|
||||
for (const { method, path, body } of planned) {
|
||||
expectOk(await giteaRequest(login, method, path, { body }), `${method} ${path}`);
|
||||
}
|
||||
|
||||
return 報告;
|
||||
});
|
||||
|
||||
/**
|
||||
* 不該補的理由，沒有就回 null。
|
||||
*
|
||||
* 只有兩種：長度非正的那一段根本不存在；錶已經跑在這顆議題上，代表這一輪已經走到起錶
|
||||
* 那一步，再補就與錶涵蓋的區間重疊。重跑本身不是理由——每一輪的規劃時間都要記上去。
|
||||
*/
|
||||
async function skipReason(login, repo, index, 秒數) {
|
||||
if (秒數 <= 0) {
|
||||
return '指令開始時間不早於現在，沒有可補登的區間；兩邊時鐘差幾秒是常事，這不算失敗。';
|
||||
}
|
||||
if (stopwatchOnIssue(await listStopwatches(login), repo, index)) {
|
||||
return '碼錶已經跑在這顆議題上。補登排在起錶之前，錶在跑就代表這一輪補過了，補下去會與錶重疊。';
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* 解析 `--since`。擋在打 Gitea 之前：值打錯是最常見的輸入錯誤，
|
||||
* 而它在補登之前唯一的症狀就是長度不對，事後從報表上看不出來。
|
||||
* @returns {number} epoch 毫秒
|
||||
*/
|
||||
function parseSince(value) {
|
||||
const at = Date.parse(value);
|
||||
if (Number.isNaN(at)) {
|
||||
throw new ScriptError(
|
||||
'BAD_SINCE',
|
||||
`--since 需為可解析的 ISO 8601 時間（例如 2026-09-17T10:05:00Z），收到的是 ${value}`,
|
||||
);
|
||||
}
|
||||
return at;
|
||||
}
|
||||
+44
-19
@@ -1,18 +1,28 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* 起錶。
|
||||
* 起錶與停錶。
|
||||
*
|
||||
* 錶與領取鎖是兩件事：鎖用 assignee 加標籤（見 claim.js），錶只管工時。分開的理由是
|
||||
* 時機不同——鎖要在開工之前就上好，錶則要等到**工作樹真的建好之後**才起。工作樹建立
|
||||
* 失敗會中止整個領取，錶要是先起了，使用者就被計了一段什麼都沒做的時間，
|
||||
* 而工時要準正是工時報表的立足點。
|
||||
* 錶與領取鎖是兩件事：鎖用 assignee 加標籤（見 claim.js），錶只管工時。
|
||||
*
|
||||
* **領取工作包時**（sdlc-feat）兩者的時機不同：鎖要在開工之前就上好，錶則要等到
|
||||
* **工作樹真的建好之後**才起。工作樹建立失敗會中止整個領取，錶要是先起了，使用者就被
|
||||
* 計了一段什麼都沒做的時間，而工時要準正是工時報表的立足點。規劃與分析沒有工作樹，
|
||||
* 那條規則對它們不適用——它們的標的是需求議題本身，議題存在就起得了錶。
|
||||
*
|
||||
* 自己的錶跑在別顆議題上時擋下，不代勞停錶：那一段時間該記在哪顆議題上只有人知道，
|
||||
* 腳本自作主張會把工時記錯地方。錶已經跑在本議題上則什麼都不做——重新起錶會把已經
|
||||
* 累積的時間切成兩段，而中斷後重跑正是這支腳本最常見的處境。
|
||||
*
|
||||
* `--stop` 停錶，而且**只停 `--index` 指的那一顆**。每個階段停掉自己起的那支錶，
|
||||
* 錶就不會跨階段跑——跑完就去開會而錶跑一整天，報表當場失真。反過來，別顆議題上的錶
|
||||
* 一律不碰：Gitea 在別顆議題上起新錶會靜默地停掉並記錄前一顆，那種靜默結算正是
|
||||
* 領取鎖那條規則當初要擋的，這裡不能反過來製造它。
|
||||
*
|
||||
* 停錶時錶本來就沒在跑不算失敗：這一步多半排在別的事情做完之後（開完 PR、回報之前），
|
||||
* 把「本來就沒在跑」報成失敗，只會讓人以為前面那件事沒做成而重跑一次。
|
||||
*
|
||||
* 用法：
|
||||
* node scripts/timer.js --repo owner/name --index 40 [--host <網址>] [--dry-run]
|
||||
* node scripts/timer.js --repo owner/name --index 40 [--stop] [--host <網址>] [--dry-run]
|
||||
*/
|
||||
import {
|
||||
expectOk,
|
||||
@@ -25,6 +35,7 @@ import {
|
||||
parseRepo,
|
||||
preflight,
|
||||
resolveLogin,
|
||||
stopStopwatch,
|
||||
stopwatchElsewhere,
|
||||
stopwatchOnIssue,
|
||||
} from './lib.js';
|
||||
@@ -33,12 +44,13 @@ main(async () => {
|
||||
const flags = parseFlags(process.argv.slice(2), {
|
||||
required: ['repo', 'index'],
|
||||
optional: ['host'],
|
||||
booleans: ['dry-run'],
|
||||
booleans: ['stop', 'dry-run'],
|
||||
});
|
||||
const repo = parseRepo(flags.repo);
|
||||
const index = parseIndex(flags.index);
|
||||
const issuePath = `/repos/${repo}/issues/${index}`;
|
||||
const dryRun = flags['dry-run'] === true;
|
||||
const 要停錶 = flags.stop === true;
|
||||
|
||||
const login = resolveLogin({ host: flags.host });
|
||||
// 試跑照樣讀現況：手寫一份固定的清單會跟實作走鐘，也說不出「這顆已經在計時了」
|
||||
@@ -47,25 +59,38 @@ main(async () => {
|
||||
|
||||
const watches = await listStopwatches(login);
|
||||
const 已在計時 = stopwatchOnIssue(watches, repo, index) !== null;
|
||||
if (!已在計時 && watches.length > 0) throw stopwatchElsewhere(watches[0], '起錶');
|
||||
// 起錶才要擋：別顆議題上的錶會讓工時記錯地方。停錶只動這一顆，擋不擋都影響不到它
|
||||
if (!要停錶 && !已在計時 && watches.length > 0) throw stopwatchElsewhere(watches[0], '起錶');
|
||||
|
||||
// 已經在跑就不重起：重新起錶會把已經累積的時間切成兩段
|
||||
const planned = 已在計時 ? [] : [{ method: 'POST', path: `${issuePath}/stopwatch/start`, body: {} }];
|
||||
// 起錶：已經在跑就不重起，重新起錶會把已經累積的時間切成兩段
|
||||
// 停錶：沒在這顆上跑就沒得停，別顆議題上的錶不碰
|
||||
const 動作 = 要停錶
|
||||
? { 端點: 'stop', 要發請求: 已在計時 }
|
||||
: { 端點: 'start', 要發請求: !已在計時 };
|
||||
const planned = 動作.要發請求
|
||||
? [{ method: 'POST', path: `${issuePath}/stopwatch/${動作.端點}`, body: {} }]
|
||||
: [];
|
||||
|
||||
const 報告 = { repo, index: issue.number, title: issue.title, url: issue.html_url };
|
||||
|
||||
if (dryRun) {
|
||||
return { dryRun: true, repo, index, title: issue.title, requests: planned, 已在計時 };
|
||||
return { dryRun: true, ...報告, requests: planned, 已在計時 };
|
||||
}
|
||||
|
||||
if (要停錶) {
|
||||
// 端點回「沒有錶在跑」的狀態碼隨站台版本而異，所以停錶走 lib 那條容錯路徑；
|
||||
// 讀到的現況與實際狀態差一步（錶剛被別處停掉）也不該把整件事報成失敗
|
||||
const stopped = planned.length > 0 && (await stopStopwatch(login, repo, index));
|
||||
return {
|
||||
...報告,
|
||||
碼錶已停: stopped,
|
||||
...(stopped ? {} : { note: '碼錶本來就沒在這顆議題上運轉，這一步略過；別顆議題上的錶不由這裡代停。' }),
|
||||
};
|
||||
}
|
||||
|
||||
for (const { method, path, body } of planned) {
|
||||
expectOk(await giteaRequest(login, method, path, { body }), `${method} ${path}`);
|
||||
}
|
||||
|
||||
return {
|
||||
repo,
|
||||
index: issue.number,
|
||||
title: issue.title,
|
||||
url: issue.html_url,
|
||||
碼錶中: true,
|
||||
已在計時,
|
||||
};
|
||||
return { ...報告, 碼錶中: true, 已在計時 };
|
||||
});
|
||||
|
||||
@@ -66,6 +66,22 @@ export function assertNeutralPrompt(prompt, command) {
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 取出正本裡某一個編號步驟的內容，**以名字取而不是以編號取**。
|
||||
* 步驟會增刪、編號會整批位移，名字不會；用編號寫的測試會在別人插一步時無聲地
|
||||
* 框到另一段內容上，而那種失敗看起來像是正本掉了東西。
|
||||
* @param {string} prompt 正本內容
|
||||
* @param {string} name 步驟名，例如 '產生圖解版總覽'
|
||||
* @returns {string} 該步驟的標題與內文，到下一個 `### ` 為止
|
||||
*/
|
||||
export function promptStep(prompt, name) {
|
||||
const start = prompt.search(new RegExp(`^### \\d+\\. ${name}$`, 'm'));
|
||||
assert.ok(start >= 0, `正本裡找不到「${name}」這一步`);
|
||||
const rest = prompt.slice(start);
|
||||
const end = rest.slice(1).search(/^### /m);
|
||||
return end === -1 ? rest : rest.slice(0, end + 1);
|
||||
}
|
||||
|
||||
/**
|
||||
* 斷言模板的 `## 標題` 就是這組段落，順序一致。
|
||||
* 段落順序即下游抽取契約的解析依據，兩邊必須一起改。
|
||||
|
||||
@@ -3,13 +3,15 @@
|
||||
*/
|
||||
import test from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { readPrompt, readTemplateFile } from './helpers/prompt-doc.js';
|
||||
import { promptStep, readPrompt, readTemplateFile } from './helpers/prompt-doc.js';
|
||||
|
||||
const template = readTemplateFile('overview-artifact.html');
|
||||
const planPrompt = readPrompt('sdlc-plan');
|
||||
const analyzePrompt = readPrompt('sdlc-analyze');
|
||||
/** 只看產生總覽那一步，避免拿整份正本的任何一處來充數 */
|
||||
const planStep = planPrompt.slice(planPrompt.indexOf('### 6.'), planPrompt.indexOf('### 7.'));
|
||||
const planStep = promptStep(planPrompt, '產生圖解版總覽');
|
||||
/** 分析版的那一步，同樣只看它自己 */
|
||||
const analyzeStep = promptStep(analyzePrompt, '產生分析版的圖解總覽');
|
||||
|
||||
/** 模板要填的欄位 */
|
||||
const PLACEHOLDERS = ['標題', '來源議題', '總覽', '目標', '流程圖', '工作包全景', '頁尾'];
|
||||
@@ -86,7 +88,7 @@ test('正本說明這份網頁是給非技術的人看的', () => {
|
||||
// ── sdlc-analyze 的步驟 ────────────────────────────────────────────
|
||||
|
||||
test('分析正本的全景圖用 graph TD，並畫出相依與時程', () => {
|
||||
const step = analyzePrompt.slice(analyzePrompt.indexOf('### 11.'));
|
||||
const step = analyzeStep;
|
||||
assert.match(step, /graph TD/);
|
||||
assert.match(step, /相依/);
|
||||
assert.match(step, /截止日/);
|
||||
@@ -97,13 +99,13 @@ test('分析正本沿用同一份模板，不另立一份', () => {
|
||||
});
|
||||
|
||||
test('全景圖一樣有節點上限，超過時的做法有交代', () => {
|
||||
const step = analyzePrompt.slice(analyzePrompt.indexOf('### 11.'));
|
||||
const step = analyzeStep;
|
||||
assert.match(step, /12/);
|
||||
assert.match(step, /最長路徑/);
|
||||
});
|
||||
|
||||
test('分析正本說明重跑會就地更新，不會留下兩個連結', () => {
|
||||
const step = analyzePrompt.slice(analyzePrompt.indexOf('### 11.'));
|
||||
const step = analyzeStep;
|
||||
assert.match(step, /就地更新/);
|
||||
assert.match(step, /只掛一個總覽網址/);
|
||||
});
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
*/
|
||||
import test from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { assertNeutralPrompt, readPrompt, readReference } from './helpers/prompt-doc.js';
|
||||
import { assertNeutralPrompt, promptStep, readPrompt, readReference } from './helpers/prompt-doc.js';
|
||||
|
||||
const prompt = readPrompt('sdlc-analyze');
|
||||
|
||||
@@ -78,16 +78,54 @@ test('正本規定最後輸出共識摘要，且摘要只印不寫', () => {
|
||||
|
||||
test('正本把「共識摘要之前不寫入」寫成明確邊界', () => {
|
||||
const boundary = prompt.slice(prompt.indexOf('## 邊界'));
|
||||
assert.match(boundary, /共識摘要之前不對 Gitea 產生任何寫入/);
|
||||
assert.match(boundary, /共識摘要之前不對 Gitea 寫入任何內容/);
|
||||
assert.match(boundary, /不建議題/);
|
||||
assert.match(boundary, /不留留言/);
|
||||
});
|
||||
|
||||
test('第一段在共識摘要之前不叫用任何寫入型腳本', () => {
|
||||
test('第一段在共識摘要之前不寫入任何內容，碼錶是唯一的例外', () => {
|
||||
const analysis = prompt.slice(prompt.indexOf('## 第一段'), prompt.indexOf('## 第二段'));
|
||||
for (const writer of ['issue-create', 'issue-update', 'issue-link', 'project-add', 'timer']) {
|
||||
for (const writer of ['issue-create', 'issue-update', 'issue-link', 'project-add']) {
|
||||
assert.equal(analysis.includes(writer), false, `第一段不該出現寫入型腳本 ${writer}`);
|
||||
}
|
||||
assert.match(analysis, /timer\.js/, '錶要起在第一段開頭，分析最耗時的正是共識之前那一段');
|
||||
});
|
||||
|
||||
// ── 計時 ───────────────────────────────────────────────────────────
|
||||
|
||||
test('起錶排在第一段開頭，停錶排在最後的回報，兩者成對出現', () => {
|
||||
const 起 = prompt.indexOf(promptStep(prompt, '起錶'));
|
||||
assert.ok(起 > prompt.indexOf(promptStep(prompt, '讀議題')), '讀完議題確認它存在之後才起');
|
||||
assert.ok(起 < prompt.indexOf('## 第二段'), '起錶要在第一段之內：分析最耗時的是共識之前那一段');
|
||||
assert.match(promptStep(prompt, '停錶並回報'), /--stop/, '停錶與最後的回報寫在同一步');
|
||||
});
|
||||
|
||||
test('起錶與停錶指的都是同一顆需求議題', () => {
|
||||
const 計時段 = [...prompt.matchAll(/node scripts\/timer\.js[^\n]*/g)].map((m) => m[0]);
|
||||
assert.ok(計時段.length >= 2, '起錶與停錶都要寫在正本裡');
|
||||
for (const line of 計時段) {
|
||||
assert.match(line, /--index <需求議題編號>/, `錶要起停在需求議題上：${line}`);
|
||||
}
|
||||
});
|
||||
|
||||
test('正本寫出這段計時涵蓋到哪，讀的人不必自己推', () => {
|
||||
assert.match(prompt, /## 計時範圍/);
|
||||
assert.match(prompt, /錶不跨階段跑/);
|
||||
});
|
||||
|
||||
test('正本交代錶已經跑在同一顆上時不重起，不把累積時間切成兩段', () => {
|
||||
assert.match(prompt, /切成兩段/);
|
||||
});
|
||||
|
||||
test('正本明令不代停別顆議題上的錶', () => {
|
||||
assert.match(prompt, /請他自己去停/);
|
||||
assert.match(prompt, /不停別顆議題上的錶/);
|
||||
});
|
||||
|
||||
test('邊界把碼錶從「不寫入」裡明文除外，並寫出理由', () => {
|
||||
const boundary = prompt.slice(prompt.indexOf('## 邊界'));
|
||||
assert.match(boundary, /碼錶除外/);
|
||||
assert.match(boundary, /工時/, '要說清楚碼錶記的是工時不是內容，否則下一個人會把它刪掉');
|
||||
});
|
||||
|
||||
test('正本要求先看未處理留言數，不是 0 就提示先整併', () => {
|
||||
|
||||
@@ -74,7 +74,7 @@ test('領取鎖的四種狀態各自交代了下一步，含放行那一種', ()
|
||||
});
|
||||
|
||||
test('缺標籤是前置條件，不混進領取鎖的四種狀態裡', () => {
|
||||
const table = phase1.slice(phase1.indexOf('| 狀態'), phase1.indexOf('碼錶一律由使用者自己停'));
|
||||
const table = phase1.slice(phase1.indexOf('| 狀態'), phase1.indexOf('鎖以外還有一個前置條件'));
|
||||
assert.equal(table.includes('LABEL_NOT_FOUND'), false, '它不是鎖的狀態，別讓四種變五種');
|
||||
assert.match(phase1, /LABEL_NOT_FOUND/, '但仍要交代它，否則使用者不知道怎麼辦');
|
||||
});
|
||||
@@ -96,9 +96,11 @@ test('被碼錶擋下時要說明停錶不會動到工作樹', () => {
|
||||
assert.match(phase1, /以為停錶等於放棄那顆工作包/, '要說明不講清楚的後果');
|
||||
});
|
||||
|
||||
test('碼錶只由使用者自己停，並說明為什麼不代勞', () => {
|
||||
assert.match(phase1, /由使用者自己停/);
|
||||
test('別顆議題上的錶只由使用者自己停，並說明為什麼不代勞', () => {
|
||||
assert.match(phase1, /別顆議題上的錶一律由使用者自己停/);
|
||||
assert.match(phase1, /工時記錯地方/);
|
||||
// 這一道自己起的那一支要自己停，否則錶會跨階段跑；兩件事不能混成一句「一律不停」
|
||||
assert.match(phase1, /停掉的只有自己起的那一支/);
|
||||
});
|
||||
|
||||
test('來源分支要問過使用者，且一次一題、附理由與手動輸入', () => {
|
||||
|
||||
@@ -12,6 +12,7 @@ import {
|
||||
assertNeutralPrompt,
|
||||
assertPromptListsSections,
|
||||
assertTemplateSections,
|
||||
promptStep,
|
||||
readPrompt,
|
||||
readTemplate,
|
||||
} from './helpers/prompt-doc.js';
|
||||
@@ -19,6 +20,9 @@ import {
|
||||
const template = readTemplate('requirement-issue');
|
||||
const prompt = readPrompt('sdlc-plan');
|
||||
|
||||
/** 某一步在正本裡的位置；以名字取而不是以編號取，插一步不會讓這些測試框錯段落 */
|
||||
const at = (name) => prompt.indexOf(promptStep(prompt, name));
|
||||
|
||||
/** 需求議題的九個段落，順序即議題裡的順序 */
|
||||
const SECTIONS = [
|
||||
'總覽',
|
||||
@@ -99,3 +103,46 @@ test('正本交代了畫與不畫兩種情況各該填什麼', () => {
|
||||
assert.match(prompt, /```mermaid/);
|
||||
assert.match(prompt, /不要加圍欄|不加圍欄/);
|
||||
});
|
||||
|
||||
// ── 計時 ───────────────────────────────────────────────────────────
|
||||
|
||||
test('正本寫出這段計時涵蓋到哪，讀的人不必自己推', () => {
|
||||
assert.match(prompt, /## 計時範圍/);
|
||||
assert.match(prompt, /錶不跨階段跑/);
|
||||
});
|
||||
|
||||
test('議題建立之前先記下開始時間：那時候還沒有標的可起錶', () => {
|
||||
assert.ok(at('記下開始時間') < at('先試跑，再寫入'), '要在議題建立之前就記下');
|
||||
assert.match(promptStep(prompt, '記下開始時間'), /不要憑印象回推/);
|
||||
});
|
||||
|
||||
test('補登排在議題建立之後、起錶之前，三者指向同一顆議題', () => {
|
||||
const 補登 = prompt.indexOf('time-log.js');
|
||||
const 起錶 = prompt.indexOf('timer.js');
|
||||
assert.ok(at('先試跑，再寫入') < 補登, '議題還不存在時無處可補');
|
||||
assert.ok(補登 < 起錶, '順序反過來的話補登會被當成做過了而跳過');
|
||||
for (const line of [...prompt.matchAll(/node scripts\/(?:time-log|timer)\.js[^\n]*/g)]) {
|
||||
assert.match(line[0], /--index <編號>/, `補登與起錶要指向同一顆議題：${line[0]}`);
|
||||
}
|
||||
});
|
||||
|
||||
test('補登的長度由腳本算，不要 agent 自己做減法', () => {
|
||||
assert.match(prompt, /--since <記下的開始時間>/);
|
||||
assert.match(prompt, /不必自己做減法/);
|
||||
});
|
||||
|
||||
test('補登不設時間上限，也不因為時間長就改口問使用者', () => {
|
||||
assert.match(prompt, /不設時間上限/);
|
||||
assert.match(prompt, /不必為此多長一題出來問使用者/);
|
||||
});
|
||||
|
||||
test('停錶排在最後的回報那一步，與起錶成對', () => {
|
||||
assert.match(promptStep(prompt, '停錶並回報'), /--stop/, '停錶與回報寫在同一步');
|
||||
assert.ok(at('補登規劃時間，然後起錶') < at('停錶並回報'), '先起才有得停');
|
||||
});
|
||||
|
||||
test('正本明令不代停別顆議題上的錶', () => {
|
||||
assert.match(prompt, /請他自己去停/);
|
||||
const boundary = prompt.slice(prompt.indexOf('## 邊界'));
|
||||
assert.match(boundary, /不停別顆議題上的錶/);
|
||||
});
|
||||
|
||||
@@ -0,0 +1,196 @@
|
||||
/**
|
||||
* 補登工時。
|
||||
*
|
||||
* 規劃階段最耗時的那一段發生在議題建立之前——那時候沒有標的可起錶，時間只能事後補登。
|
||||
* 這一支的價值全在「補多少」：長度由腳本自己算，不由 agent 做減法。終點看議題是不是
|
||||
* 這一輪建立的——是就補到建立那一刻，不是就補到現在，那一輪的規劃時間照樣要進報表。
|
||||
* 唯一不補的情形是錶已經在這顆議題上跑著，那一段已經有錶在記了。
|
||||
*/
|
||||
import test from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { runScript } from './helpers/run-script.js';
|
||||
import { healthyRoutes, stubEnv as envFor, withStubGitea } from './helpers/stub-gitea.js';
|
||||
|
||||
const REPO = 'plugins/tea-sdlc';
|
||||
const INDEX = 42;
|
||||
|
||||
/** 議題建立於此刻；每支測試的 --since 都相對它往前推 */
|
||||
const CREATED = '2026-09-17T10:30:00Z';
|
||||
|
||||
/** CREATED 往前推 n 秒的 ISO 時間 */
|
||||
const 早於建立 = (seconds) => new Date(Date.parse(CREATED) - seconds * 1000).toISOString();
|
||||
|
||||
/** 議題上跑著的碼錶長什麼樣 */
|
||||
const stopwatchOn = (index, repo = REPO) => ({
|
||||
issue_index: index,
|
||||
repo_owner_name: repo.split('/')[0],
|
||||
repo_name: repo.split('/')[1],
|
||||
});
|
||||
|
||||
function routes(overrides = {}, { stopwatches = [] } = {}) {
|
||||
return healthyRoutes(REPO, {
|
||||
[`GET /api/v1/repos/${REPO}/issues/${INDEX}`]: {
|
||||
status: 200,
|
||||
body: {
|
||||
number: INDEX,
|
||||
title: '為規劃與分析階段計時並補登規劃時間',
|
||||
created_at: CREATED,
|
||||
html_url: `https://gitea.jsc.idv.tw/${REPO}/issues/${INDEX}`,
|
||||
},
|
||||
},
|
||||
'GET /api/v1/user/stopwatches': { status: 200, body: stopwatches },
|
||||
[`POST /api/v1/repos/${REPO}/issues/${INDEX}/times`]: { status: 200, body: { id: 1 } },
|
||||
...overrides,
|
||||
});
|
||||
}
|
||||
|
||||
const withStub = (t, overrides = {}, options) => withStubGitea(t, routes(overrides, options));
|
||||
|
||||
const run = (since, args, stub) =>
|
||||
runScript('time-log.js', ['--repo', REPO, '--index', String(INDEX), '--since', since, ...args], {
|
||||
env: envFor(stub),
|
||||
});
|
||||
|
||||
/** 會改動 Gitea 的請求；前置檢查打在 issues/0 的探針不算（見 lib 的 checkIssueWrite） */
|
||||
const writes = (stub) =>
|
||||
stub.requests.filter((r) => r.method !== 'GET').filter((r) => !r.path.endsWith('/issues/0'));
|
||||
|
||||
test('補登時長等於指令開始到議題建立的差值', async (t) => {
|
||||
const stub = await withStub(t);
|
||||
|
||||
const { code, json } = await run(早於建立(25 * 60), [], stub);
|
||||
|
||||
assert.equal(code, 0, json.error?.message);
|
||||
assert.equal(json.data.補登, true);
|
||||
assert.equal(json.data.秒數, 25 * 60);
|
||||
const [write] = writes(stub);
|
||||
assert.equal(write.path, `/api/v1/repos/${REPO}/issues/${INDEX}/times`);
|
||||
assert.deepEqual(write.body, { time: 25 * 60 });
|
||||
});
|
||||
|
||||
test('長度由腳本自己算：議題的建立時間減掉 --since，agent 不必做減法', async (t) => {
|
||||
const stub = await withStub(t);
|
||||
|
||||
const { json } = await run(早於建立(90), [], stub);
|
||||
|
||||
assert.equal(json.data.秒數, 90);
|
||||
assert.equal(Date.parse(json.data.迄), Date.parse(CREATED), '終點就是議題建立那一刻');
|
||||
assert.equal(json.data.依據, '議題建立');
|
||||
});
|
||||
|
||||
test('不設時間上限：中間去開會的那幾個小時照實補登，不改口問使用者', async (t) => {
|
||||
const stub = await withStub(t);
|
||||
const 十小時 = 10 * 60 * 60;
|
||||
|
||||
const { code, json } = await run(早於建立(十小時), [], stub);
|
||||
|
||||
assert.equal(code, 0, '時間長不是失敗；記多了看得出來，記不到就永遠找不回來');
|
||||
assert.equal(json.data.秒數, 十小時);
|
||||
assert.deepEqual(writes(stub).at(0).body, { time: 十小時 });
|
||||
});
|
||||
|
||||
test('錶已經跑在這顆議題上時跳過：補下去會與錶涵蓋的區間重疊', async (t) => {
|
||||
const stub = await withStub(t, {}, { stopwatches: [stopwatchOn(INDEX)] });
|
||||
|
||||
const { code, json } = await run(早於建立(600), [], stub);
|
||||
|
||||
assert.equal(code, 0, json.error?.message);
|
||||
assert.equal(json.data.補登, false);
|
||||
assert.match(json.data.note, /起錶/);
|
||||
assert.deepEqual(writes(stub), [], '那一段已經有錶在記，補下去就記了兩遍');
|
||||
});
|
||||
|
||||
test('對既有議題重跑時補到現在，那一輪的規劃時間照樣進報表', async (t) => {
|
||||
// 議題比 --since 還早，代表這不是這一輪建立的；拿舊的建立時間當終點會算出負數，
|
||||
// 等於把這一輪的工夫丟掉
|
||||
const stub = await withStub(t);
|
||||
const 起 = new Date(Date.now() - 20 * 60 * 1000).toISOString();
|
||||
|
||||
const { code, json } = await run(起, [], stub);
|
||||
|
||||
assert.equal(code, 0, json.error?.message);
|
||||
assert.equal(json.data.補登, true);
|
||||
assert.equal(json.data.依據, '補登當下');
|
||||
assert.ok(Math.abs(json.data.秒數 - 20 * 60) <= 5, `補的應是這一輪的長度，實際 ${json.data.秒數}`);
|
||||
assert.equal(writes(stub).at(0).body.time, json.data.秒數);
|
||||
});
|
||||
|
||||
test('重跑是累計不是覆蓋：每一輪各記一筆，加總才是這顆議題真正的規劃時間', async (t) => {
|
||||
const stub = await withStub(t);
|
||||
const 起 = new Date(Date.now() - 10 * 60 * 1000).toISOString();
|
||||
|
||||
const 第一輪 = await run(起, [], stub);
|
||||
const 第二輪 = await run(起, [], stub);
|
||||
|
||||
assert.equal(第一輪.json.data.補登, true);
|
||||
assert.equal(第二輪.json.data.補登, true, '前一輪記過了不是跳過的理由');
|
||||
assert.equal(writes(stub).length, 2, '兩輪各記一筆');
|
||||
});
|
||||
|
||||
test('錶跑在別顆議題上不影響補登：補登只寫工時，不動任何錶', async (t) => {
|
||||
const stub = await withStub(t, {}, { stopwatches: [stopwatchOn(7)] });
|
||||
|
||||
const { code, json } = await run(早於建立(600), [], stub);
|
||||
|
||||
assert.equal(code, 0, json.error?.message);
|
||||
assert.equal(json.data.補登, true);
|
||||
assert.deepEqual(
|
||||
writes(stub).map((r) => r.path),
|
||||
[`/api/v1/repos/${REPO}/issues/${INDEX}/times`],
|
||||
'不得順手停掉別顆議題上的錶',
|
||||
);
|
||||
});
|
||||
|
||||
test('指令開始時間落在未來時什麼都不補，也不算失敗', async (t) => {
|
||||
const stub = await withStub(t);
|
||||
|
||||
const { code, json } = await run(new Date(Date.now() + 60 * 1000).toISOString(), [], stub);
|
||||
|
||||
assert.equal(code, 0, '兩邊時鐘差幾秒是常事，不該讓整個流程停在這裡');
|
||||
assert.equal(json.data.補登, false);
|
||||
assert.deepEqual(writes(stub), []);
|
||||
});
|
||||
|
||||
test('--since 不是可解析的時間時擋在打 Gitea 之前', async (t) => {
|
||||
const stub = await withStub(t);
|
||||
|
||||
const { code, json } = await run('剛剛', [], stub);
|
||||
|
||||
assert.equal(code, 1);
|
||||
assert.equal(json.error.code, 'BAD_SINCE');
|
||||
assert.equal(stub.requests.length, 0);
|
||||
});
|
||||
|
||||
test('議題不存在時回可區分的錯誤碼', async (t) => {
|
||||
const stub = await withStub(t, {
|
||||
[`GET /api/v1/repos/${REPO}/issues/${INDEX}`]: { status: 404, body: { message: 'not found' } },
|
||||
});
|
||||
|
||||
const { json } = await run(早於建立(600), [], stub);
|
||||
|
||||
assert.equal(json.error.code, 'ISSUE_NOT_FOUND');
|
||||
assert.deepEqual(writes(stub), []);
|
||||
});
|
||||
|
||||
test('--dry-run 印出將發出的補登，但一個字都不寫進去', async (t) => {
|
||||
const stub = await withStub(t);
|
||||
|
||||
const { code, json } = await run(早於建立(1800), ['--dry-run'], stub);
|
||||
|
||||
assert.equal(code, 0);
|
||||
assert.equal(json.data.dryRun, true);
|
||||
assert.equal(json.data.秒數, 1800);
|
||||
assert.deepEqual(json.data.requests, [
|
||||
{ method: 'POST', path: `/repos/${REPO}/issues/${INDEX}/times`, body: { time: 1800 } },
|
||||
]);
|
||||
assert.deepEqual(writes(stub), [], '預覽不得真的寫入');
|
||||
});
|
||||
|
||||
test('--dry-run 會先讀現況：錶已經在跑時預覽出來就是什麼都不做', async (t) => {
|
||||
const stub = await withStub(t, {}, { stopwatches: [stopwatchOn(INDEX)] });
|
||||
|
||||
const { json } = await run(早於建立(1800), ['--dry-run'], stub);
|
||||
|
||||
assert.deepEqual(json.data.requests, [], '手寫一份固定的清單會跟實作走鐘');
|
||||
assert.equal(json.data.補登, false);
|
||||
});
|
||||
+98
-3
@@ -1,9 +1,13 @@
|
||||
/**
|
||||
* 起錶。
|
||||
* 起錶與停錶。
|
||||
*
|
||||
* 錶是工時報表的唯一來源，所以這一支的價值全在「什麼時候不該起」：工作樹還沒建好
|
||||
* 錶是工時報表的唯一來源，所以起錶那一半的價值全在「什麼時候不該起」：工作樹還沒建好
|
||||
* 不該起（那由流程的順序保證），自己的錶已經跑在別顆議題上更不該起——那會把兩顆
|
||||
* 工作包的時間攪在一起。停錶一律由使用者自己來，這裡不提供。
|
||||
* 工作包的時間攪在一起。
|
||||
*
|
||||
* `--stop` 只停 `--index` 指的那一顆。每個階段停掉自己起的那支錶，錶就不會跨階段跑；
|
||||
* 但別顆議題上的錶一律不碰——那一段時間該記在哪顆議題上只有人知道，而靜默替人結算
|
||||
* 正是領取鎖那條規則當初要擋的事。
|
||||
*/
|
||||
import test from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
@@ -32,6 +36,7 @@ function routes(overrides = {}, { stopwatches = [] } = {}) {
|
||||
},
|
||||
'GET /api/v1/user/stopwatches': { status: 200, body: stopwatches },
|
||||
[`POST /api/v1/repos/${REPO}/issues/${INDEX}/stopwatch/start`]: { status: 201, body: {} },
|
||||
[`POST /api/v1/repos/${REPO}/issues/${INDEX}/stopwatch/stop`]: { status: 200, body: {} },
|
||||
...overrides,
|
||||
});
|
||||
}
|
||||
@@ -147,3 +152,93 @@ test('--dry-run 會先讀現況：已經在計時時預覽出來就是什麼都
|
||||
assert.deepEqual(json.data.requests, [], '手寫一份固定的清單會跟實作走鐘');
|
||||
assert.equal(json.data.已在計時, true);
|
||||
});
|
||||
|
||||
// ── 停錶 ───────────────────────────────────────────────────────────
|
||||
|
||||
test('--stop 停掉跑在這顆議題上的錶', async (t) => {
|
||||
const stub = await withStub(t, {}, { stopwatches: [stopwatchOn(INDEX)] });
|
||||
|
||||
const { code, json } = await run(['--stop'], stub);
|
||||
|
||||
assert.equal(code, 0, json.error?.message);
|
||||
assert.equal(json.data.碼錶已停, true);
|
||||
assert.deepEqual(
|
||||
writes(stub).map((r) => `${r.method} ${r.path}`),
|
||||
[`POST /api/v1/repos/${REPO}/issues/${INDEX}/stopwatch/stop`],
|
||||
);
|
||||
});
|
||||
|
||||
test('--stop 在錶本來就沒在跑時不算失敗，並說明這一步略過了', async (t) => {
|
||||
const stub = await withStub(t);
|
||||
|
||||
const { code, json } = await run(['--stop'], stub);
|
||||
|
||||
assert.equal(code, 0, '這一步多半排在回報之前，報成失敗會讓人以為前面那件事沒做成');
|
||||
assert.equal(json.data.碼錶已停, false);
|
||||
assert.match(json.data.note, /沒在/);
|
||||
assert.deepEqual(writes(stub), []);
|
||||
});
|
||||
|
||||
test('--stop 不碰別顆議題上的錶：錶在別顆時什麼都不停', async (t) => {
|
||||
const stub = await withStub(t, {}, { stopwatches: [stopwatchOn(7)] });
|
||||
|
||||
const { code, json } = await run(['--stop'], stub);
|
||||
|
||||
assert.equal(code, 0);
|
||||
assert.equal(json.data.碼錶已停, false);
|
||||
assert.deepEqual(writes(stub), [], '靜默替人結算別顆議題，正是領取鎖那條規則要擋的事');
|
||||
});
|
||||
|
||||
test('--stop 的 --dry-run 印出將發出的停錶，且不真的停', async (t) => {
|
||||
const stub = await withStub(t, {}, { stopwatches: [stopwatchOn(INDEX)] });
|
||||
|
||||
const { code, json } = await run(['--stop', '--dry-run'], stub);
|
||||
|
||||
assert.equal(code, 0);
|
||||
assert.equal(json.data.dryRun, true);
|
||||
assert.deepEqual(
|
||||
json.data.requests.map((r) => `${r.method} ${r.path}`),
|
||||
[`POST /repos/${REPO}/issues/${INDEX}/stopwatch/stop`],
|
||||
);
|
||||
assert.deepEqual(writes(stub), []);
|
||||
});
|
||||
|
||||
test('--stop 認得站台把「沒有錶在跑」回成 409 或 500 的兩種寫法', async (t) => {
|
||||
for (const status of [409, 500]) {
|
||||
const stub = await withStubGitea(
|
||||
t,
|
||||
routes(
|
||||
{
|
||||
[`POST /api/v1/repos/${REPO}/issues/${INDEX}/stopwatch/stop`]: {
|
||||
status,
|
||||
body: { message: 'cannot stop non existent stopwatch' },
|
||||
},
|
||||
},
|
||||
{ stopwatches: [stopwatchOn(INDEX)] },
|
||||
),
|
||||
);
|
||||
|
||||
const { code, json } = await run(['--stop'], stub);
|
||||
|
||||
assert.equal(code, 0, `${status} 若說的是碼錶，就不是真的伺服器錯誤`);
|
||||
assert.equal(json.data.碼錶已停, false);
|
||||
}
|
||||
});
|
||||
|
||||
test('--stop 遇到真的伺服器錯誤時照樣失敗，不吞掉', async (t) => {
|
||||
const stub = await withStub(
|
||||
t,
|
||||
{
|
||||
[`POST /api/v1/repos/${REPO}/issues/${INDEX}/stopwatch/stop`]: {
|
||||
status: 500,
|
||||
body: { message: 'database is on fire' },
|
||||
},
|
||||
},
|
||||
{ stopwatches: [stopwatchOn(INDEX)] },
|
||||
);
|
||||
|
||||
const { code, json } = await run(['--stop'], stub);
|
||||
|
||||
assert.equal(code, 1);
|
||||
assert.equal(json.error.code, 'HTTP_ERROR');
|
||||
});
|
||||
|
||||
@@ -62,7 +62,7 @@ test('人天估算的 API 限制寫成獨立一節，不是藏在行文裡', ()
|
||||
|
||||
test('邊界把三段各自不做的事分開列', () => {
|
||||
const boundary = prompt.slice(prompt.indexOf('## 邊界'));
|
||||
assert.match(boundary, /共識摘要之前不對 Gitea 產生任何寫入/);
|
||||
assert.match(boundary, /共識摘要之前不對 Gitea 寫入任何內容/);
|
||||
assert.match(boundary, /第二段只建立工作包議題/);
|
||||
assert.match(boundary, /第三段只掛既有的 Milestone 與看板/);
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user