feat(开发任务): 状态流转接入单条工作流

apps/web/lib/dev-task-transitions.ts

@@ -1,62 +1,6 @@
 import type { DevTask } from './dev-task';
 
-/**
- * 是否可以"手动"切到 in_progress
- * - 仅当 todo 且未到 expectedStartAt 时返回 true
- * - 已到点：自动机制接管，UI 不应再显示手动按钮
- * - 已超期：返回 false，UI 应要求填 delayReason
- */
-export function canManualStart(task: DevTask, now: Date = new Date()): boolean {
-  if (task.status !== 'todo') return false;
-  if (!task.expectedStartAt) return true;
-  return now.getTime() < new Date(task.expectedStartAt).getTime();
-}
-
-/**
- * 自动切换扫描：返回所有需要从 todo 切到 in_progress 的任务
- * - status === 'todo'
- * - now >= expectedStartAt（且未超期超过 0 秒就自动切——超期未切的可单独走 needsDelayReason 流程）
- *
- * 注意：超期任务也包含在内，由调用方决定要不要扫；当前策略是 fetchTasks 调用时只扫"刚好到点"，
- * 超期任务保留在 todo 等用户填 delayReason。所以这里加 maxOverdueMs 参数，默认 24h 内的算到点。
- */
-export function findTasksToAutoStart(
-  tasks: DevTask[],
-  now: Date = new Date(),
-  maxOverdueMs: number = 24 * 60 * 60 * 1000,
-): Array<{ taskId: string; actualStartAt: string }> {
-  const result: Array<{ taskId: string; actualStartAt: string }> = [];
-  for (const t of tasks) {
-    if (t.status !== 'todo' || !t.expectedStartAt || t.actualStartAt) continue;
-    const expected = new Date(t.expectedStartAt).getTime();
-    if (isNaN(expected)) continue;
-    const diff = now.getTime() - expected;
-    if (diff >= 0 && diff <= maxOverdueMs) {
-      result.push({ taskId: t.id, actualStartAt: t.expectedStartAt });
-    }
-  }
-  return result;
-}
-
-/**
- * 是否处于"超期手动开干需填延后原因"状态
- * - todo 且 now > expectedStartAt
- */
 export function needsDelayReason(task: DevTask, now: Date = new Date()): boolean {
   if (task.status !== 'todo' || !task.expectedStartAt) return false;
   return now.getTime() > new Date(task.expectedStartAt).getTime();
 }
-
-/**
- * 进入 in_progress 时计算 actualStartAt
- * - auto: 等于 expectedStartAt
- * - manual: 等于 now
- */
-export function deriveActualStartAt(
-  task: DevTask,
-  trigger: 'auto' | 'manual',
-  now: Date = new Date(),
-): string {
-  if (trigger === 'auto' && task.expectedStartAt) return task.expectedStartAt;
-  return now.toISOString();
-}

apps/web/lib/dev-task-workflow.test.ts

@@ -0,0 +1,81 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import type { DevTask } from './dev-task';
+import { applyDevTaskTransition, normalizeDevTaskOnCreate } from './dev-task-workflow';
+
+function task(patch: Partial<DevTask> = {}): DevTask {
+  return {
+    id: 'task-1',
+    taskNo: 'DEV-001',
+    requirementId: 'req-1',
+    title: '实现拖拽排序',
+    categoryId: 'cat-frontend-interaction',
+    assigneeId: 'Alice',
+    priority: 'P2',
+    expectedStartAt: '2026-06-25T01:00:00.000Z',
+    expectedEndAt: '2026-06-25T02:00:00.000Z',
+    status: 'todo',
+    isBlocked: false,
+    createdBy: 'PM',
+    createdAt: '2026-06-25T00:00:00.000Z',
+    updatedAt: '2026-06-25T00:00:00.000Z',
+    ...patch,
+  };
+}
+
+test('normalizeDevTaskOnCreate forces todo and clears actual timestamps for AI drafts', () => {
+  const normalized = normalizeDevTaskOnCreate(task({
+    status: 'in_progress',
+    actualStartAt: '2026-06-25T01:00:00.000Z',
+    actualEndAt: '2026-06-25T02:00:00.000Z',
+    aiDraft: true,
+  }));
+
+  assert.equal(normalized.status, 'todo');
+  assert.equal(normalized.actualStartAt, undefined);
+  assert.equal(normalized.actualEndAt, undefined);
+});
+
+test('todo to in_progress writes actualStartAt from manual click time', () => {
+  const result = applyDevTaskTransition(task(), 'in_progress', {
+    now: new Date('2026-06-25T03:30:00.000Z'),
+  });
+
+  assert.equal(result.ok, true);
+  assert.equal(result.patch?.status, 'in_progress');
+  assert.equal(result.patch?.actualStartAt, '2026-06-25T03:30:00.000Z');
+});
+
+test('in_progress to testing does not write actualEndAt', () => {
+  const result = applyDevTaskTransition(task({
+    status: 'in_progress',
+    actualStartAt: '2026-06-25T03:30:00.000Z',
+  }), 'testing', {
+    now: new Date('2026-06-25T04:00:00.000Z'),
+  });
+
+  assert.equal(result.ok, true);
+  assert.equal(result.patch?.actualEndAt, undefined);
+});
+
+test('testing to submitted writes actualEndAt', () => {
+  const result = applyDevTaskTransition(task({
+    status: 'testing',
+    actualStartAt: '2026-06-25T03:30:00.000Z',
+  }), 'submitted', {
+    now: new Date('2026-06-25T05:00:00.000Z'),
+  });
+
+  assert.equal(result.ok, true);
+  assert.equal(result.patch?.actualEndAt, '2026-06-25T05:00:00.000Z');
+});
+
+test('invalid transition is rejected', () => {
+  const result = applyDevTaskTransition(task(), 'submitted', {
+    now: new Date('2026-06-25T05:00:00.000Z'),
+  });
+
+  assert.equal(result.ok, false);
+  assert.match(result.message || '', /不允许/);
+});

apps/web/lib/dev-task-workflow.ts

@@ -0,0 +1,49 @@
+import type { DevTask, DevTaskStatus } from './dev-task';
+import { canTransition } from './dev-task';
+
+export interface DevTaskWorkflowResult {
+  ok: boolean;
+  patch?: Partial<DevTask>;
+  message?: string;
+}
+
+export interface DevTaskTransitionOptions {
+  now?: Date;
+  delayReason?: string;
+}
+
+export function normalizeDevTaskOnCreate(task: DevTask): DevTask {
+  return {
+    ...task,
+    status: 'todo',
+    actualStartAt: undefined,
+    actualEndAt: undefined,
+  };
+}
+
+export function applyDevTaskTransition(
+  task: DevTask,
+  to: DevTaskStatus,
+  options: DevTaskTransitionOptions = {},
+): DevTaskWorkflowResult {
+  if (!canTransition(task.status, to)) {
+    return { ok: false, message: `不允许从「${task.status}」流转到「${to}」` };
+  }
+
+  const nowIso = (options.now ?? new Date()).toISOString();
+  const patch: Partial<DevTask> = {
+    status: to,
+    aiDraft: false,
+  };
+
+  if (to === 'in_progress' && !task.actualStartAt) {
+    patch.actualStartAt = nowIso;
+    if (options.delayReason?.trim()) patch.delayReason = options.delayReason.trim();
+  }
+
+  if (to === 'submitted') {
+    patch.actualEndAt = nowIso;
+  }
+
+  return { ok: true, patch };
+}

apps/web/lib/dev-task.ts

@@ -3,6 +3,15 @@ import { calcWorkHours, formatWorkHours, type TimeInterval } from './work-hours'
 
 export type DevTaskStatus = 'todo' | 'in_progress' | 'testing' | 'submitted';
 
+export type ReferenceType = 'requirement' | 'prototype_note' | 'external';
+
+export interface Reference {
+  type: ReferenceType;
+  id: string;
+  label: string;
+  url?: string;
+}
+
 export interface DevTask {
   id: string;
   taskNo: string;
@@ -16,6 +25,7 @@ export interface DevTask {
 
   expectedStartAt: string;
   expectedEndAt: string;
+  estimateHours?: number;
   actualStartAt?: string;
   actualEndAt?: string;
 
@@ -27,6 +37,9 @@ export interface DevTask {
   riskLevel?: 'low' | 'medium' | 'high';
   delayReason?: string;
   overdueVersionReason?: string;
+  references?: Reference[];
+  aiDraft?: boolean;
+  aiDraftAt?: string;
   createdBy: string;
   createdAt: string;
   updatedAt: string;
@@ -84,6 +97,9 @@ export function formatHours(hours: number): string {
 }
 
 export function getEstimateHours(task: DevTask): number {
+  if (typeof task.estimateHours === 'number' && task.estimateHours > 0) {
+    return Math.round(task.estimateHours * 2) / 2;
+  }
   if (!task.expectedStartAt || !task.expectedEndAt) return 0;
   return calcWorkHours(task.expectedStartAt, task.expectedEndAt);
 }
@@ -162,7 +178,6 @@ export function isLegacyTask(t: any): boolean {
     'startDate' in t ||
     'dueDate' in t ||
     'completedAt' in t ||
-    'estimateHours' in t ||
     'actualHours' in t ||
     'overdueReason' in t
   );