diff --git a/prompts/sdlc-plan.md b/prompts/sdlc-plan.md index 7800743..fc84b5c 100644 --- a/prompts/sdlc-plan.md +++ b/prompts/sdlc-plan.md @@ -102,8 +102,9 @@ node scripts/issue-create.js --repo --title "<標題>" --body-file node scripts/time-log.js --repo --index <編號> --since <記下的開始時間> --dry-run ``` -長度由腳本自己算——它讀議題的建立時間減掉 `--since`，所以不必自己做減法，也不會讓 -兩邊的時鐘各算一次。確認無誤後拿掉 `--dry-run` 再跑一次。 +長度由腳本自己算，不必自己做減法，也不會讓兩邊的時鐘各算一次。終點看議題是不是這一輪 +建立的：是就補到**議題建立那一刻**，不是（對既有議題重跑）就補到**現在**——那一輪的 +規劃時間照樣要進報表。確認無誤後拿掉 `--dry-run` 再跑一次。 **不設時間上限，照實補登。** 中途去開會的那兩個小時會一起被算進去，這是刻意的：換來 這個流程不必為此多長一題出來問使用者。時間記多了看得出來，記不到就永遠找不回來。 @@ -114,8 +115,11 @@ node scripts/time-log.js --repo --index <編號> --since <記下的 node scripts/timer.js --repo --index <編號> --dry-run ``` -一樣先試跑，確認無誤後拿掉 `--dry-run` 再跑一次。順序反過來的話補登會被當成「這一步做過了」而跳過——錶在這顆議題上跑著，正是 -`time-log` 判斷補過了的依據之一，它也因此重跑不會愈補愈多。 +一樣先試跑，確認無誤後拿掉 `--dry-run` 再跑一次。 + +順序不能反過來：錶一旦跑在這顆議題上，`time-log` 就會跳過不補——那一段已經有錶在記了， +再補一次會與錶涵蓋的區間重疊。**重跑是累計不是覆蓋**，每一輪各記一筆，報表上加總起來 +才是這顆議題真正花掉的規劃時間。 錶已經跑在別顆議題上時起錶會被擋下（`STOPWATCH_ON_OTHER_ISSUE`）。**照實告訴使用者 是哪一顆，請他自己去停**，不要代勞：那一段時間該記在哪顆議題上只有他知道。順帶說明 diff --git a/scripts/lib.js b/scripts/lib.js index 8bd2ebf..230635f 100644 --- a/scripts/lib.js +++ b/scripts/lib.js @@ -1041,33 +1041,6 @@ export async function stopStopwatch(login, repo, index) { return false; } -/** - * 這顆議題上已經記到的工時。 - * - * 清單的範圍隨權限而異：不是 repo admin 時 Gitea 只回自己的那幾筆，是 admin 時連別人的 - * 一起回。呼叫端（補登）問的是「這顆議題上已經有工時了嗎」，**兩種範圍都答得了那一問**： - * 剛建好的議題上一筆都不該有，有了就代表這個流程跑過一次。範圍寬一點只會讓它偏向不補， - * 而那是安全的方向——工時記重複比記不到更難在報表上被發現。 - * @param {{base: string, token: string}} login - * @param {string} repo owner/name - * @param {number} index - * @returns {Promise} - */ -export async function listIssueTimes(login, repo, index) { - const path = `/repos/${repo}/issues/${index}/times`; - const response = await giteaRequest(login, 'GET', path); - - // 議題本身讀得到卻在這裡 404，代表的是 repo 的時間追蹤關著。訊息與前置檢查第四層 - // 對齊：同一件事在試跑與實跑上要說同一句話，否則試跑看到的是一句看不懂的 404 - if (response.status === 404) { - throw new ScriptError( - 'TIME_TRACKER_OFF', - 'repo 尚未開啟時間追蹤，工時記不進去；請到 Settings → Advanced Settings → Enable Time Tracker 開啟', - ); - } - return expectOk(response, `GET ${path}`) ?? []; -} - // ── 標籤 ─────────────────────────────────────────────────────────── /** diff --git a/scripts/time-log.js b/scripts/time-log.js index 24032ed..1be2452 100644 --- a/scripts/time-log.js +++ b/scripts/time-log.js @@ -6,15 +6,21 @@ * 那時候沒有標的可起錶（議題還不存在）。這段時間只能事後補登，否則報表上的規劃永遠是零， * 久了會讓人以為規劃不花時間，而那正是估算失準最常見的來源。 * - * **長度由這支腳本自己算**：議題的建立時間減掉 `--since`。交給 agent 做減法，等於讓 - * 兩邊的時鐘與時區各算一次，而算錯了報表上看不出來。 + * **長度由這支腳本自己算**：終點減掉 `--since`。交給 agent 做減法，等於讓兩邊的時鐘與 + * 時區各算一次，而算錯了報表上看不出來。 + * + * 終點取哪一刻，看議題是不是這一輪建立的： + * - 議題建立於 `--since` 之後 → 終點是**議題的建立時間**。這是第一次跑，補的正是 + * 「指令開始到議題建立」那一段。 + * - 議題比 `--since` 還早 → 終點是**補登的當下**。這是對既有議題重跑，那一輪的規劃 + * 時間照樣要進報表；拿舊的建立時間當終點會算出負數，等於把這一輪的工夫丟掉。 * * **不設時間上限，照實補登。** 中途去開會的那兩個小時會一起被算進去——換來這個流程 * 不必為此多長一題出來問使用者。時間記多了看得出來，記不到就永遠找不回來。 * - * 兩種情況跳過不補，因為補登一旦記兩遍，報表看不出來哪一筆是重複的： - * - 自己的錶已經跑在這顆議題上：補登排在起錶之前，錶在跑就代表這一步做過了。 - * - 這顆議題上已經有自己的工時：整個流程跑完過一次了。 + * **重跑會累計，不會覆蓋**：每一輪各記一筆，報表上加總起來才是這顆議題真正花掉的規劃 + * 時間。唯一跳過的情形是自己的錶已經跑在這顆議題上——補登排在起錶之前，錶在跑就代表 + * 這一輪已經走到起錶那一步了，再補一次會與錶涵蓋的區間重疊。 * * 只寫工時，不動任何錶——別顆議題上有錶在跑也照補，那兩件事互不相干。 * @@ -27,7 +33,6 @@ import { expectOk, fetchIssue, giteaRequest, - listIssueTimes, listStopwatches, main, parseFlags, @@ -51,7 +56,7 @@ main(async () => { 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); @@ -59,11 +64,15 @@ main(async () => { if (Number.isNaN(建立時間)) { throw new ScriptError( 'NO_CREATED_AT', - `${repo} 的議題 ${index} 沒有可解讀的建立時間，補登的長度算不出來`, + `${repo} 的議題 ${index} 沒有可解讀的建立時間，補登的終點判斷不出來`, ); } - const 秒數 = Math.round((建立時間 - since) / 1000); + // 這一輪建立的議題就補到建立那一刻；既有的議題則補到現在，那一輪的工夫一樣要進報表 + 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 報告 = { @@ -72,7 +81,8 @@ main(async () => { title: issue.title, url: issue.html_url, since: new Date(since).toISOString(), - 議題建立時間: issue.created_at, + 迄: new Date(迄).toISOString(), + 依據: 這輪建立 ? '議題建立' : '補登當下', 秒數, 補登: 略過 === null, ...(略過 ? { note: 略過 } : {}), @@ -92,18 +102,15 @@ main(async () => { /** * 不該補的理由，沒有就回 null。 * - * 三個理由都是「補了會比不補更錯」：長度非正的那一段根本不存在，另外兩個代表這一步 - * 已經做過，再補一次就是把同一段時間記兩遍。 + * 只有兩種：長度非正的那一段根本不存在；錶已經跑在這顆議題上，代表這一輪已經走到起錶 + * 那一步，再補就與錶涵蓋的區間重疊。重跑本身不是理由——每一輪的規劃時間都要記上去。 */ async function skipReason(login, repo, index, 秒數) { if (秒數 <= 0) { - return '指令開始時間不早於議題建立時間，沒有可補登的區間；兩邊時鐘差幾秒是常事，這不算失敗。'; + return '指令開始時間不早於現在，沒有可補登的區間；兩邊時鐘差幾秒是常事，這不算失敗。'; } if (stopwatchOnIssue(await listStopwatches(login), repo, index)) { - return '碼錶已經跑在這顆議題上。補登排在起錶之前，錶在跑就代表這一段補過了，不再記第二遍。'; - } - if ((await listIssueTimes(login, repo, index)).length > 0) { - return '這顆議題上已經有自己的工時紀錄，代表整個流程跑完過一次，不再補一次。'; + return '碼錶已經跑在這顆議題上。補登排在起錶之前，錶在跑就代表這一輪補過了，補下去會與錶重疊。'; } return null; } diff --git a/test/time-log.test.js b/test/time-log.test.js index 871611f..965351c 100644 --- a/test/time-log.test.js +++ b/test/time-log.test.js @@ -2,9 +2,9 @@ * 補登工時。 * * 規劃階段最耗時的那一段發生在議題建立之前——那時候沒有標的可起錶，時間只能事後補登。 - * 這一支的價值全在「補多少」與「什麼時候不該補」：長度由議題的建立時間減掉指令開始 - * 時間算出來，不由 agent 自己做減法；已經補過的不再補一次，否則重跑會把同一段時間 - * 記兩遍，而報表看不出來那是重複的。 + * 這一支的價值全在「補多少」：長度由腳本自己算，不由 agent 做減法。終點看議題是不是 + * 這一輪建立的——是就補到建立那一刻，不是就補到現在，那一輪的規劃時間照樣要進報表。 + * 唯一不補的情形是錶已經在這顆議題上跑著，那一段已經有錶在記了。 */ import test from 'node:test'; import assert from 'node:assert/strict'; @@ -27,7 +27,7 @@ const stopwatchOn = (index, repo = REPO) => ({ repo_name: repo.split('/')[1], }); -function routes(overrides = {}, { stopwatches = [], times = [] } = {}) { +function routes(overrides = {}, { stopwatches = [] } = {}) { return healthyRoutes(REPO, { [`GET /api/v1/repos/${REPO}/issues/${INDEX}`]: { status: 200, @@ -39,7 +39,6 @@ function routes(overrides = {}, { stopwatches = [], times = [] } = {}) { }, }, 'GET /api/v1/user/stopwatches': { status: 200, body: stopwatches }, - [`GET /api/v1/repos/${REPO}/issues/${INDEX}/times`]: { status: 200, body: times }, [`POST /api/v1/repos/${REPO}/issues/${INDEX}/times`]: { status: 200, body: { id: 1 } }, ...overrides, }); @@ -75,7 +74,8 @@ test('長度由腳本自己算：議題的建立時間減掉 --since，agent 不 const { json } = await run(早於建立(90), [], stub); assert.equal(json.data.秒數, 90); - assert.equal(json.data.議題建立時間, CREATED); + assert.equal(Date.parse(json.data.迄), Date.parse(CREATED), '終點就是議題建立那一刻'); + assert.equal(json.data.依據, '議題建立'); }); test('不設時間上限：中間去開會的那幾個小時照實補登，不改口問使用者', async (t) => { @@ -89,7 +89,7 @@ test('不設時間上限：中間去開會的那幾個小時照實補登，不 assert.deepEqual(writes(stub).at(0).body, { time: 十小時 }); }); -test('錶已經跑在這顆議題上時跳過：補登排在起錶之前，代表這一步做過了', async (t) => { +test('錶已經跑在這顆議題上時跳過：補下去會與錶涵蓋的區間重疊', async (t) => { const stub = await withStub(t, {}, { stopwatches: [stopwatchOn(INDEX)] }); const { code, json } = await run(早於建立(600), [], stub); @@ -97,18 +97,34 @@ test('錶已經跑在這顆議題上時跳過：補登排在起錶之前，代 assert.equal(code, 0, json.error?.message); assert.equal(json.data.補登, false); assert.match(json.data.note, /起錶/); - assert.deepEqual(writes(stub), [], '重跑不該把同一段時間記第二遍'); + assert.deepEqual(writes(stub), [], '那一段已經有錶在記，補下去就記了兩遍'); }); -test('這顆議題上已經有自己的工時時跳過，重跑不會愈補愈多', async (t) => { - const stub = await withStub(t, {}, { times: [{ id: 3, time: 1500 }] }); +test('對既有議題重跑時補到現在，那一輪的規劃時間照樣進報表', async (t) => { + // 議題比 --since 還早，代表這不是這一輪建立的；拿舊的建立時間當終點會算出負數， + // 等於把這一輪的工夫丟掉 + const stub = await withStub(t); + const 起 = new Date(Date.now() - 20 * 60 * 1000).toISOString(); - const { code, json } = await run(早於建立(600), [], stub); + const { code, json } = await run(起, [], stub); assert.equal(code, 0, json.error?.message); - assert.equal(json.data.補登, false); - assert.match(json.data.note, /工時/); - assert.deepEqual(writes(stub), []); + 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) => { @@ -125,10 +141,10 @@ test('錶跑在別顆議題上不影響補登：補登只寫工時，不動任 ); }); -test('指令開始時間不早於議題建立時間時什麼都不補，也不算失敗', async (t) => { +test('指令開始時間落在未來時什麼都不補，也不算失敗', async (t) => { const stub = await withStub(t); - const { code, json } = await run(new Date(Date.parse(CREATED) + 1000).toISOString(), [], stub); + const { code, json } = await run(new Date(Date.now() + 60 * 1000).toISOString(), [], stub); assert.equal(code, 0, '兩邊時鐘差幾秒是常事，不該讓整個流程停在這裡'); assert.equal(json.data.補登, false); @@ -156,19 +172,6 @@ test('議題不存在時回可區分的錯誤碼', async (t) => { assert.deepEqual(writes(stub), []); }); -test('repo 的時間追蹤關著時，訊息與前置檢查第四層說的是同一件事', async (t) => { - // 議題讀得到卻在 times 上 404，代表時間追蹤關著；試跑不跑前置檢查，這句話得由這裡說 - const stub = await withStub(t, { - [`GET /api/v1/repos/${REPO}/issues/${INDEX}/times`]: { status: 404, body: { message: 'not found' } }, - }); - - const { code, json } = await run(早於建立(600), ['--dry-run'], stub); - - assert.equal(code, 1); - assert.equal(json.error.code, 'TIME_TRACKER_OFF'); - assert.match(json.error.message, /Enable Time Tracker/); -}); - test('--dry-run 印出將發出的補登，但一個字都不寫進去', async (t) => { const stub = await withStub(t); @@ -183,8 +186,8 @@ test('--dry-run 印出將發出的補登，但一個字都不寫進去', async ( assert.deepEqual(writes(stub), [], '預覽不得真的寫入'); }); -test('--dry-run 會先讀現況：已經補過的預覽出來就是什麼都不做', async (t) => { - const stub = await withStub(t, {}, { times: [{ id: 3, time: 1500 }] }); +test('--dry-run 會先讀現況：錶已經在跑時預覽出來就是什麼都不做', async (t) => { + const stub = await withStub(t, {}, { stopwatches: [stopwatchOn(INDEX)] }); const { json } = await run(早於建立(1800), ['--dry-run'], stub);