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
@@ -1,9 +1,13 @@
 /**
- * 起錶。
+ * 起錶與停錶。
 *
- * 錶是工時報表的唯一來源，所以這一支的價值全在「什麼時候不該起」：工作樹還沒建好
+ * 錶是工時報表的唯一來源，所以起錶那一半的價值全在「什麼時候不該起」：工作樹還沒建好
 * 不該起（那由流程的順序保證），自己的錶已經跑在別顆議題上更不該起——那會把兩顆
- * 工作包的時間攪在一起。停錶一律由使用者自己來，這裡不提供。
+ * 工作包的時間攪在一起。
+ *
+ * `--stop` 只停 `--index` 指的那一顆。每個階段停掉自己起的那支錶，錶就不會跨階段跑；
+ * 但別顆議題上的錶一律不碰——那一段時間該記在哪顆議題上只有人知道，而靜默替人結算
+ * 正是領取鎖那條規則當初要擋的事。
 */
 import test from 'node:test';
 import assert from 'node:assert/strict';
@@ -32,6 +36,7 @@ function routes(overrides = {}, { stopwatches = [] } = {}) {
    },
    'GET /api/v1/user/stopwatches': { status: 200, body: stopwatches },
    [`POST /api/v1/repos/${REPO}/issues/${INDEX}/stopwatch/start`]: { status: 201, body: {} },
+    [`POST /api/v1/repos/${REPO}/issues/${INDEX}/stopwatch/stop`]: { status: 200, body: {} },
    ...overrides,
  });
 }
@@ -147,3 +152,93 @@ test('--dry-run 會先讀現況：已經在計時時預覽出來就是什麼都
  assert.deepEqual(json.data.requests, [], '手寫一份固定的清單會跟實作走鐘');
  assert.equal(json.data.已在計時, true);
 });
+
+// ── 停錶 ───────────────────────────────────────────────────────────
+
+test('--stop 停掉跑在這顆議題上的錶', async (t) => {
+  const stub = await withStub(t, {}, { stopwatches: [stopwatchOn(INDEX)] });
+
+  const { code, json } = await run(['--stop'], stub);
+
+  assert.equal(code, 0, json.error?.message);
+  assert.equal(json.data.碼錶已停, true);
+  assert.deepEqual(
+    writes(stub).map((r) => `${r.method} ${r.path}`),
+    [`POST /api/v1/repos/${REPO}/issues/${INDEX}/stopwatch/stop`],
+  );
+});
+
+test('--stop 在錶本來就沒在跑時不算失敗，並說明這一步略過了', async (t) => {
+  const stub = await withStub(t);
+
+  const { code, json } = await run(['--stop'], stub);
+
+  assert.equal(code, 0, '這一步多半排在回報之前，報成失敗會讓人以為前面那件事沒做成');
+  assert.equal(json.data.碼錶已停, false);
+  assert.match(json.data.note, /沒在/);
+  assert.deepEqual(writes(stub), []);
+});
+
+test('--stop 不碰別顆議題上的錶：錶在別顆時什麼都不停', async (t) => {
+  const stub = await withStub(t, {}, { stopwatches: [stopwatchOn(7)] });
+
+  const { code, json } = await run(['--stop'], stub);
+
+  assert.equal(code, 0);
+  assert.equal(json.data.碼錶已停, false);
+  assert.deepEqual(writes(stub), [], '靜默替人結算別顆議題，正是領取鎖那條規則要擋的事');
+});
+
+test('--stop 的 --dry-run 印出將發出的停錶，且不真的停', async (t) => {
+  const stub = await withStub(t, {}, { stopwatches: [stopwatchOn(INDEX)] });
+
+  const { code, json } = await run(['--stop', '--dry-run'], stub);
+
+  assert.equal(code, 0);
+  assert.equal(json.data.dryRun, true);
+  assert.deepEqual(
+    json.data.requests.map((r) => `${r.method} ${r.path}`),
+    [`POST /repos/${REPO}/issues/${INDEX}/stopwatch/stop`],
+  );
+  assert.deepEqual(writes(stub), []);
+});
+
+test('--stop 認得站台把「沒有錶在跑」回成 409 或 500 的兩種寫法', async (t) => {
+  for (const status of [409, 500]) {
+    const stub = await withStubGitea(
+      t,
+      routes(
+        {
+          [`POST /api/v1/repos/${REPO}/issues/${INDEX}/stopwatch/stop`]: {
+            status,
+            body: { message: 'cannot stop non existent stopwatch' },
+          },
+        },
+        { stopwatches: [stopwatchOn(INDEX)] },
+      ),
+    );
+
+    const { code, json } = await run(['--stop'], stub);
+
+    assert.equal(code, 0, `${status} 若說的是碼錶，就不是真的伺服器錯誤`);
+    assert.equal(json.data.碼錶已停, false);
+  }
+});
+
+test('--stop 遇到真的伺服器錯誤時照樣失敗，不吞掉', async (t) => {
+  const stub = await withStub(
+    t,
+    {
+      [`POST /api/v1/repos/${REPO}/issues/${INDEX}/stopwatch/stop`]: {
+        status: 500,
+        body: { message: 'database is on fire' },
+      },
+    },
+    { stopwatches: [stopwatchOn(INDEX)] },
+  );
+
+  const { code, json } = await run(['--stop'], stub);
+
+  assert.equal(code, 1);
+  assert.equal(json.error.code, 'HTTP_ERROR');
+});