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

2026-06-25 14:04:45 +08:00
parent 168c748835
commit 52833d81ac
6 changed files with 187 additions and 109 deletions
--- 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>
--- 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();
-}
--- a/apps/web/lib/dev-task-workflow.test.ts
+++ 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 || '', /不允许/);
+});
--- a/apps/web/lib/dev-task-workflow.ts
+++ 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 };
+}
--- 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
  );
--- 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 };
  },