feat(time-log): 對既有議題重跑時補到當下,每一輪各記一筆

原本的終點一律是議題的建立時間,所以對既有議題重跑時相減為負,補登直接 no-op——
那一輪的規劃時間就這樣掉了,而那正是這顆議題要修的毛病,只是換個位置出現。

終點改成看議題是不是這一輪建立的:是就補到議題建立那一刻(第一次跑),不是就補到
補登的當下(重跑)。回報多出 `迄` 與 `依據` 兩個欄位,讓人一眼看出這一筆補的是哪一段。

「這顆議題上已經有工時就跳過」這條規則拿掉了,它與累計互斥。防重複只剩一條:錶已經
跑在這顆議題上——那一段已經有錶在記,補下去會與錶涵蓋的區間重疊。連帶把 lib 的
listIssueTimes 一起移除,沒有人再用它。

實跑驗過(議題 #57):補登 121 秒、起錶、停錶 7 秒,兩筆都進得了週報,驗完刪除。
議題 #57 的規格同步更正,另外兩處過期的敘述也一併改掉。

議題 #57

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-09-18 08:46:27 +08:00
co-authored by Claude Opus 5
parent 7ee050de2f
commit 46c6db8c70
4 changed files with 66 additions and 79 deletions
-27
View File
@@ -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<object[]>}
*/
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}`) ?? [];
}
// ── 標籤 ───────────────────────────────────────────────────────────
/**
+24 -17
View File
@@ -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;
}