fix(工时): 按中国工作日历统计正常耗时

apps/web/lib/version-overview.test.ts

@@ -120,9 +120,9 @@ test('calcStageEffortMetrics returns actual hours and AI estimates per stage', (
     ],
   });
 
-  assert.equal(metrics.requirement.actualHours, 9);
+  assert.equal(metrics.requirement.actualHours, 8);
   assert.equal(metrics.product_design.actualHours, 3);
-  assert.equal(metrics.dev.actualHours, 5);
+  assert.equal(metrics.dev.actualHours, 4);
   assert.equal(metrics.dev.estimateHours, 4.5);
   assert.equal(metrics.dev.aiEstimateHours, 3.25);
   assert.equal(metrics.testing.actualHours, 2);
@@ -184,7 +184,7 @@ test('calcVersionOverviewEffortTotals sums actual hours and overtime records sep
     overtimeRecords,
   });
 
-  assert.equal(totals.actualHours, 11);
+  assert.equal(totals.actualHours, 10);
   assert.equal(totals.overtimeHours, 3.3);
 });
 
@@ -222,9 +222,9 @@ test('calcPersonalEffortRanking includes bug work and sorts by total hours', ()
   });
 
   assert.equal(ranking[0].name, 'Alice');
-  assert.equal(ranking[0].actualHours, 11);
+  assert.equal(ranking[0].actualHours, 10);
   assert.equal(ranking[0].overtimeHours, 1.5);
-  assert.equal(ranking[0].total, 12.5);
+  assert.equal(ranking[0].total, 11.5);
   assert.equal(ranking[1].name, 'Bob');
   assert.equal(ranking[1].actualHours, 4);
   assert.equal(ranking[1].overtimeHours, 2);

apps/web/lib/work-hours.test.ts

@@ -1,14 +1,26 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 
-import { calcActualElapsedHours, formatActualDuration } from './work-hours';
+import { calcActualElapsedHours, calcWorkHours, formatActualDuration } from './work-hours';
+import { calcDuration } from './overtime';
 
-test('calcActualElapsedHours uses real elapsed time with a half-hour minimum', () => {
+test('calcWorkHours skips official holidays and counts makeup workdays', () => {
+  assert.equal(calcWorkHours('2026-10-01T09:00:00', '2026-10-01T18:00:00'), 0);
+  assert.equal(calcWorkHours('2026-10-10T09:00:00', '2026-10-10T18:00:00'), 8);
+});
+
+test('calcActualElapsedHours uses work calendar time with a half-hour minimum', () => {
   assert.equal(calcActualElapsedHours('2026-06-22T09:00:00', '2026-06-22T09:10:00'), 0.5);
   assert.equal(calcActualElapsedHours('2026-06-22T09:00:00', '2026-06-22T10:15:00'), 1.5);
+  assert.equal(calcActualElapsedHours('2026-10-01T09:00:00', '2026-10-01T18:00:00'), 0);
+  assert.equal(calcActualElapsedHours('2026-10-10T09:00:00', '2026-10-10T10:00:00'), 1);
   assert.equal(calcActualElapsedHours('2026-06-22T10:00:00', '2026-06-22T09:00:00'), 0);
 });
 
+test('overtime duration still counts holiday time directly', () => {
+  assert.equal(calcDuration('2026-10-01T09:00:00', '2026-10-01T18:00:00'), 9);
+});
+
 test('formatActualDuration converts hours to natural days', () => {
   assert.equal(formatActualDuration(60.5), '60.5h（2.5天）');
   assert.equal(formatActualDuration(0.5), '0.5h（0.02天）');

apps/web/lib/work-hours.ts

@@ -1,3 +1,5 @@
+import { isChinaWorkday } from './china-workday-calendar';
+
 export const WORK_HOURS = {
   morningStart: 9,
   morningEnd: 12,
@@ -27,7 +29,7 @@ function dayBound(d: Date, hourFloat: number): Date {
 }
 
 function dayOverlapHours(start: Date, end: Date, day: Date): number {
-  if (WORK_HOURS.skipWeekends && isWeekend(day)) return 0;
+  if (WORK_HOURS.skipWeekends && !isChinaWorkday(day)) return 0;
   const morningStart = dayBound(day, WORK_HOURS.morningStart);
   const morningEnd = dayBound(day, WORK_HOURS.morningEnd);
   const afternoonStart = dayBound(day, WORK_HOURS.afternoonStart);
@@ -55,7 +57,7 @@ function dayOverlapHours(start: Date, end: Date, day: Date): number {
  * - 全在周末 周六全天 = 0h
  * - 负区间 / 非法 ISO = 0
  */
-export function calcWorkHours(startISO: string, endISO: string): number {
+function calcWorkHoursRaw(startISO: string, endISO: string): number {
   if (!startISO || !endISO) return 0;
   const start = new Date(startISO);
   const end = new Date(endISO);
@@ -73,6 +75,11 @@ export function calcWorkHours(startISO: string, endISO: string): number {
     cursor.setDate(cursor.getDate() + 1);
   }
 
+  return total;
+}
+
+export function calcWorkHours(startISO: string, endISO: string): number {
+  const total = calcWorkHoursRaw(startISO, endISO);
   return Math.round(total * 2) / 2;
 }
 
@@ -100,12 +107,11 @@ export function formatWorkHoursShort(hours: number): string {
  * 用于“实际耗时”口径：按开始/结束时间戳直接相减，精度 0.5h；
  * 只要有正向耗时，最低按 0.5h 计，避免 30 分钟内工作被显示为 0。
  */
+// 实际耗时只统计中国工作日历内的工作时段；加班通过 overtime 记录单独计入。
 export function calcActualElapsedHours(startISO?: string | null, endISO?: string | null): number {
   if (!startISO || !endISO) return 0;
-  const start = new Date(startISO).getTime();
-  const end = new Date(endISO).getTime();
-  if (isNaN(start) || isNaN(end) || end <= start) return 0;
-  const hours = (end - start) / MS_PER_HOUR;
+  const hours = calcWorkHoursRaw(startISO, endISO);
+  if (hours <= 0) return 0;
   return Math.max(0.5, Math.round(hours * 2) / 2);
 }
 
@@ -146,7 +152,7 @@ export function addWorkHours(startISO: string, hours: number): string {
   while (remaining > 0) {
     const day = new Date(cursor);
     day.setHours(0, 0, 0, 0);
-    if (WORK_HOURS.skipWeekends && isWeekend(day)) {
+    if (WORK_HOURS.skipWeekends && !isChinaWorkday(day)) {
       cursor.setDate(cursor.getDate() + 1);
       cursor.setHours(WORK_HOURS.morningStart, 0, 0, 0);
       continue;

docs/decisions.md

@@ -355,3 +355,15 @@
 - TestCase 增加 `plannedTestAt`，Bug 增加 `plannedFixAt`，保存为 ISO 时间戳。
 
 **理由**：项目排期需要贴近中国工作日，但研发和线上 Bug 可能确实安排在非工作日处理，所以系统负责提醒，最终是否保存交给用户判断。
+
+## 30. 正常工时走中国工作日历，加班单独计入
+
+**问题**：接入中国节假日后，如果任务从节假日前开始、节假日后结束，直接按自然时间差会把休息日误算为实际耗时。
+
+**决策**：
+- `calcWorkHours` 和正常任务的 `calcActualElapsedHours` 都按中国工作日历和工作时段计算。
+- 法定节假日、周末不计入正常工时；调休上班日计入正常工时。
+- AI 预估工时是工作量建议，不按日期跳过；执行预估只有从计划起止时间自动推导时才走工作日历。
+- 加班记录不受工作日历过滤，按加班单填写的开始/结束时间直接计入额外投入。
+
+**理由**：正常任务耗时回答“工作时间里实际投入了多少”，加班记录回答“非正常工作时间额外投入了多少”，两条口径分开才能避免休息日被重复或误算。

docs/workflow.md

@@ -233,3 +233,10 @@ Implementation convention:
 - 非工作日只提示，不阻止保存；调休工作日按工作日提示。
 - 测试用例计划测试时间字段为 `plannedTestAt`；Bug 计划修复时间字段为 `plannedFixAt`。
 - 测试轮次复制用例时保留计划测试时间、AI 预估和执行预估，清空实际执行记录。
+
+## 工时统计口径
+
+- 正常任务耗时使用 `calcWorkHours` / `calcActualElapsedHours`，按中国工作日历和 9:00-12:00、13:00-18:00 工作时段计算。
+- 法定节假日和周末不计入正常任务耗时；调休上班日计入正常任务耗时。
+- AI 预估工时和手填执行预估工时本身是小时数，不再按日期过滤；只有从计划起止时间自动推导的执行预估会按工作日历计算。
+- 加班记录使用 `overtime.calcDuration`，按加班单开始/结束时间直接计算，不受节假日过滤。