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>

scripts/lib.js

@@ -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;
+}
+
 // ── 標籤 ───────────────────────────────────────────────────────────
 
 /**

scripts/pr-create.js

@@ -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;
-}

scripts/time-log.js

@@ -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;
+}

scripts/timer.js

@@ -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, 已在計時 };
 });