jiantw83andClaude Opus 5
46c6db8c70
原本的終點一律是議題的建立時間，所以對既有議題重跑時相減為負，補登直接 no-op—— 那一輪的規劃時間就這樣掉了，而那正是這顆議題要修的毛病，只是換個位置出現。 終點改成看議題是不是這一輪建立的：是就補到議題建立那一刻（第一次跑），不是就補到 補登的當下（重跑）。回報多出 `迄` 與 `依據` 兩個欄位，讓人一眼看出這一筆補的是哪一段。 「這顆議題上已經有工時就跳過」這條規則拿掉了，它與累計互斥。防重複只剩一條：錶已經 跑在這顆議題上——那一段已經有錶在記，補下去會與錶涵蓋的區間重疊。連帶把 lib 的 listIssueTimes 一起移除，沒有人再用它。 實跑驗過（議題 #57）：補登 121 秒、起錶、停錶 7 秒，兩筆都進得了週報，驗完刪除。 議題 #57 的規格同步更正，另外兩處過期的敘述也一併改掉。 議題 #57 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
133 lines
5.2 KiB
JavaScript
133 lines
5.2 KiB
JavaScript
#!/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;
|
|
}
|