feat(timer,time-log): 起錶配上停錶，並補登議題建立之前的時間

碼錶只在領取工作包時起動，所以工時報表上規劃與分析永遠是零。久了會讓人以為規劃不花時間，而那正是估算失準最常見的來源。 timer 加上 --stop，而且**只停 --index 指的那一顆**。每個階段停掉自己起的那一支，錶就不會跨階段跑——跑完就去開會而錶跑一整天，報表當場失真。反過來，別顆議題上的錶一律不碰：Gitea 在別顆議題上起新錶會靜默地停掉並記錄前一顆，那種靜默結算正是領取鎖那條規則當初要擋的，不能在這裡反過來製造它。錶本來就沒在跑不算失敗，這一步多半排在回報之前，報成失敗只會讓人以為前面那件事沒做成而重跑一次。 time-log 補登議題建立之前那一段——讀齊輸入、逐項詢問、組出議題內容，往往是整個 plan 最耗時的部分，而那時候議題還不存在，沒有標的可起錶。長度由腳本自己算（議題的建立時間減掉 --since），交給 agent 做減法等於讓兩邊的時鐘各算一次，而算錯了報表上看不出來。 **不設時間上限、照實補登**：中途去開會的兩小時會一起算進去，換來這個流程不必為此多長一題出來問使用者。補登不是冪等的動作，所以兩種情況跳過不補：錶已經跑在這顆議題上（補登排在起錶之前，錶在跑就代表這一段補過了），以及這顆議題上已經有工時（整個流程跑完過一次）。工時記重複比記不到更難在報表上被發現，所以判斷偏向不補。時間追蹤在現有環境下可能是關著的，真實路徑跑不起來；兩支都靠 --dry-run 與 stub server 測，共 27 條。議題 #57 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-17 19:32:20 +08:00
parent 5638593c4c
commit 81d02bffcf
4 changed files with 460 additions and 22 deletions
@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/**
+ * 補登一段沒有錶記到的工時。
+ *
+ * 規劃階段最耗時的那一段——讀齊輸入、逐項詢問、組出議題內容——發生在議題建立**之前**，
+ * 那時候沒有標的可起錶（議題還不存在）。這段時間只能事後補登，否則報表上的規劃永遠是零，
+ * 久了會讓人以為規劃不花時間，而那正是估算失準最常見的來源。
+ *
+ * **長度由這支腳本自己算**：議題的建立時間減掉 `--since`。交給 agent 做減法，等於讓
+ * 兩邊的時鐘與時區各算一次，而算錯了報表上看不出來。
+ *
+ * **不設時間上限，照實補登。** 中途去開會的那兩個小時會一起被算進去——換來這個流程
+ * 不必為此多長一題出來問使用者。時間記多了看得出來，記不到就永遠找不回來。
+ *
+ * 兩種情況跳過不補，因為補登一旦記兩遍，報表看不出來哪一筆是重複的：
+ *   - 自己的錶已經跑在這顆議題上：補登排在起錶之前，錶在跑就代表這一步做過了。
+ *   - 這顆議題上已經有自己的工時：整個流程跑完過一次了。
+ *
+ * 只寫工時，不動任何錶——別顆議題上有錶在跑也照補，那兩件事互不相干。
+ *
+ * 用法：
+ *   node scripts/time-log.js --repo owner/name --index 42 --since <ISO 8601 時間>
+ *                            [--host <網址>] [--dry-run]
+ */
+import {
+  ScriptError,
+  expectOk,
+  fetchIssue,
+  giteaRequest,
+  listIssueTimes,
+  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 秒數 = 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(),
+    議題建立時間: issue.created_at,
+    秒數,
+    補登: 略過 === 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 '碼錶已經跑在這顆議題上。補登排在起錶之前，錶在跑就代表這一段補過了，不再記第二遍。';
+  }
+  if ((await listIssueTimes(login, repo, index)).length > 0) {
+    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;
+}