From 52833d81ac81fdef51d71b66bb7e5f4db722bef4 Mon Sep 17 00:00:00 2001
From: Script Generator <dev@scriptgen.local>
Date: Thu, 25 Jun 2026 14:04:45 +0800
Subject: [PATCH] =?UTF-8?q?feat(=E5=BC=80=E5=8F=91=E4=BB=BB=E5=8A=A1):=20?=
 =?UTF-8?q?=E7=8A=B6=E6=80=81=E6=B5=81=E8=BD=AC=E6=8E=A5=E5=85=A5=E5=8D=95?=
 =?UTF-8?q?=E6=9D=A1=E5=B7=A5=E4=BD=9C=E6=B5=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../dev-task/DevTaskCreateModal.tsx           | 17 ++++
 apps/web/lib/dev-task-transitions.ts          | 56 -------------
 apps/web/lib/dev-task-workflow.test.ts        | 81 +++++++++++++++++++
 apps/web/lib/dev-task-workflow.ts             | 49 +++++++++++
 apps/web/lib/dev-task.ts                      | 17 +++-
 apps/web/stores/useDevTaskStore.ts            | 76 ++++++-----------
 6 files changed, 187 insertions(+), 109 deletions(-)
 create mode 100644 apps/web/lib/dev-task-workflow.test.ts
 create mode 100644 apps/web/lib/dev-task-workflow.ts

diff --git a/apps/web/components/dev-task/DevTaskCreateModal.tsx b/apps/web/components/dev-task/DevTaskCreateModal.tsx
index b1fbd85..3b7ae01 100644
--- a/apps/web/components/dev-task/DevTaskCreateModal.tsx
+++ b/apps/web/components/dev-task/DevTaskCreateModal.tsx
@@ -57,6 +57,7 @@ export function DevTaskCreateModal({ versionId, requirementIds, versionDeadline,
   const [predecessorIds, setPredecessorIds] = useState<string[]>([]);
   const [description, setDescription] = useState('');
   const [overdueVersionReason, setOverdueVersionReason] = useState('');
+  const [prototypeNotes, setPrototypeNotes] = useState('');
 
   useEffect(() => {
     if (categories[0] && !categoryId) setCategoryId(categories[0].id);
@@ -95,6 +96,15 @@ export function DevTaskCreateModal({ versionId, requirementIds, versionDeadline,
 
   const handleSubmit = () => {
     if (!canSubmit) return;
+    const reqRef = versionReqs.find((r) => r.id === requirementId);
+    const references = [
+      ...(reqRef ? [{ type: 'requirement' as const, id: reqRef.code, label: `${reqRef.code} ${reqRef.title}` }] : []),
+      ...prototypeNotes.split(/[,，\s]+/).map((s) => s.trim()).filter(Boolean).map((note) => ({
+        type: 'prototype_note' as const,
+        id: note,
+        label: note,
+      })),
+    ];
     createTask({
       requirementId,
       title: title.trim(),
@@ -105,6 +115,7 @@ export function DevTaskCreateModal({ versionId, requirementIds, versionDeadline,
       priority: effectivePriority,
       expectedStartAt: expectedStartISO,
       expectedEndAt: expectedEndISO,
+      estimateHours,
       actualStartAt: undefined,
       actualEndAt: undefined,
       status: 'todo',
@@ -114,6 +125,7 @@ export function DevTaskCreateModal({ versionId, requirementIds, versionDeadline,
       riskLevel: undefined,
       delayReason: undefined,
       overdueVersionReason: isOverdueVersion ? overdueVersionReason.trim() : undefined,
+      references: references.length > 0 ? references : undefined,
       createdBy: user?.name || '系统',
     });
     onCreated?.();
@@ -212,6 +224,11 @@ export function DevTaskCreateModal({ versionId, requirementIds, versionDeadline,
             <label className="block text-[12px] text-[var(--ink-soft)] mb-1">描述</label>
             <textarea rows={3} value={description} onChange={(e) => setDescription(e.target.value)} className="w-full rounded-lg border border-[var(--line)] bg-[var(--bg)] px-3 py-2 text-[13px] focus:border-[var(--accent)] focus:outline-none resize-none" placeholder="任务描述（可选）" />
           </div>
+          <div>
+            <label className="block text-[12px] text-[var(--ink-soft)] mb-1">原型批注</label>
+            <input value={prototypeNotes} onChange={(e) => setPrototypeNotes(e.target.value)} className="h-8 w-full rounded-lg border border-[var(--line)] bg-[var(--bg)] px-3 text-[13px] focus:border-[var(--accent)] focus:outline-none" placeholder="如 QY0007, QY0023" />
+            <p className="mt-1 text-[11px] text-[var(--ink-muted)]">原型批注编号，逗号分隔（任务来自原型上的哪些标记）</p>
+          </div>
         </div>
         <div className="flex justify-end gap-2 pt-4 border-t border-[var(--line)] mt-4">
           <button onClick={onClose} className="h-8 px-3 rounded-lg text-[12px] font-medium border border-[var(--line)] text-[var(--ink-soft)] hover:bg-[var(--bg-subtle)]">取消</button>
diff --git a/apps/web/lib/dev-task-transitions.ts b/apps/web/lib/dev-task-transitions.ts
index b0d8874..81d149d 100644
--- a/apps/web/lib/dev-task-transitions.ts
+++ b/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();
-}
diff --git a/apps/web/lib/dev-task-workflow.test.ts b/apps/web/lib/dev-task-workflow.test.ts
new file mode 100644
index 0000000..4b9a6d0
--- /dev/null
+++ b/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 || '', /不允许/);
+});
diff --git a/apps/web/lib/dev-task-workflow.ts b/apps/web/lib/dev-task-workflow.ts
new file mode 100644
index 0000000..78d2519
--- /dev/null
+++ b/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 };
+}
diff --git a/apps/web/lib/dev-task.ts b/apps/web/lib/dev-task.ts
index a9e4895..fbd0abe 100644
--- a/apps/web/lib/dev-task.ts
+++ b/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
   );
diff --git a/apps/web/stores/useDevTaskStore.ts b/apps/web/stores/useDevTaskStore.ts
index 5479112..3a20535 100644
--- a/apps/web/stores/useDevTaskStore.ts
+++ b/apps/web/stores/useDevTaskStore.ts
@@ -1,37 +1,30 @@
 'use client';
 import { create } from 'zustand';
 import type { DevTask, DevTaskStatus } from '@/lib/dev-task';
-import { canTransition, generateTaskNo, isLegacyTask } from '@/lib/dev-task';
-import { findTasksToAutoStart, deriveActualStartAt } from '@/lib/dev-task-transitions';
+import { generateTaskNo, isLegacyTask } from '@/lib/dev-task';
+import { applyDevTaskTransition, normalizeDevTaskOnCreate } from '@/lib/dev-task-workflow';
+import { loadServerData, saveServerData } from '@/lib/server-data';
 
-const STORAGE_KEY = 'ftb_dev_tasks_v2';
-const LEGACY_KEY = 'ftb_dev_tasks_v1';
-
-function saveLocal(items: DevTask[]) {
-  try { localStorage.setItem(STORAGE_KEY, JSON.stringify(items)); } catch {}
+function saveStored(items: DevTask[]) {
+  saveServerData('dev-tasks', items).catch(() => {});
 }
 
-function loadLocal(): DevTask[] | null {
+async function loadStored(): Promise<DevTask[] | null> {
   try {
-    const raw = localStorage.getItem(STORAGE_KEY);
-    if (raw) {
-      const parsed = JSON.parse(raw);
+    const parsed = await loadServerData<DevTask[]>('dev-tasks');
+    if (parsed) {
       if (Array.isArray(parsed) && parsed.some(isLegacyTask)) {
-        localStorage.removeItem(STORAGE_KEY);
         return null;
       }
       return parsed;
     }
-    if (localStorage.getItem(LEGACY_KEY)) {
-      localStorage.removeItem(LEGACY_KEY);
-    }
   } catch {}
   return null;
 }
 
 interface DevTaskState {
   tasks: DevTask[];
-  fetchTasks: () => void;
+  fetchTasks: () => Promise<void>;
   createTask: (data: Omit<DevTask, 'id' | 'taskNo' | 'createdAt' | 'updatedAt' | 'isBlocked'>) => DevTask;
   updateTask: (id: string, data: Partial<DevTask>) => void;
   deleteTask: (id: string) => void;
@@ -45,72 +38,51 @@ interface DevTaskState {
 export const useDevTaskStore = create<DevTaskState>((set, get) => ({
   tasks: [],
 
-  fetchTasks: () => {
-    const cached = loadLocal();
-    const list = cached ?? [];
-    const now = new Date();
-    const autoStarts = findTasksToAutoStart(list, now);
-    if (autoStarts.length > 0) {
-      const map = new Map(autoStarts.map((a) => [a.taskId, a.actualStartAt]));
-      const updated = list.map((t) =>
-        map.has(t.id)
-          ? { ...t, status: 'in_progress' as DevTaskStatus, actualStartAt: map.get(t.id)!, updatedAt: now.toISOString() }
-          : t,
-      );
-      set({ tasks: updated });
-      saveLocal(updated);
-    } else {
-      set({ tasks: list });
-    }
+  fetchTasks: async () => {
+    const cached = await loadStored();
+    set({ tasks: cached ?? [] });
   },
 
   createTask: (data) => {
     const list = get().tasks;
     const now = new Date().toISOString();
-    const task: DevTask = {
+    const task: DevTask = normalizeDevTaskOnCreate({
       ...data,
       id: `task-${Date.now()}`,
       taskNo: generateTaskNo(list),
       isBlocked: false,
       createdAt: now,
       updatedAt: now,
-    };
+    } as DevTask);
     const updated = [...list, task];
     set({ tasks: updated });
-    saveLocal(updated);
+    saveStored(updated);
     return task;
   },
 
   updateTask: (id, data) => {
     const updated = get().tasks.map((t) =>
-      t.id === id ? { ...t, ...data, updatedAt: new Date().toISOString() } : t,
+      t.id === id ? { ...t, ...data, aiDraft: false, updatedAt: new Date().toISOString() } : t,
     );
     set({ tasks: updated });
-    saveLocal(updated);
+    saveStored(updated);
   },
 
   deleteTask: (id) => {
     const updated = get().tasks.filter((t) => t.id !== id);
     set({ tasks: updated });
-    saveLocal(updated);
+    saveStored(updated);
   },
 
   changeStatus: (id, to, opts) => {
     const task = get().tasks.find((t) => t.id === id);
     if (!task) return { ok: false, message: '任务不存在' };
-    if (!canTransition(task.status, to)) {
-      return { ok: false, message: `不允许从「${task.status}」流转到「${to}」` };
-    }
-    const now = new Date();
-    const patch: Partial<DevTask> = { status: to };
-    if (to === 'in_progress' && !task.actualStartAt) {
-      patch.actualStartAt = deriveActualStartAt(task, 'manual', now);
-      if (opts?.delayReason) patch.delayReason = opts.delayReason;
-    }
-    if (to === 'submitted') {
-      patch.actualEndAt = now.toISOString();
-    }
-    get().updateTask(id, patch);
+    const result = applyDevTaskTransition(task, to, {
+      now: new Date(),
+      delayReason: opts?.delayReason,
+    });
+    if (!result.ok || !result.patch) return { ok: false, message: result.message };
+    get().updateTask(id, result.patch);
     return { ok: true };
   },