feat(版本详情): 完善流程日志与需求覆盖

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

@@ -1,7 +1,7 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 
-import type { DevTask } from './dev-task';
+import { canStartDevTask, hasDevTaskPlan, needsDevTaskClaim, type DevTask } from './dev-task';
 import { applyDevTaskTransition, normalizeDevTaskOnCreate } from './dev-task-workflow';
 
 function task(patch: Partial<DevTask> = {}): DevTask {
@@ -47,6 +47,44 @@ test('todo to in_progress writes actualStartAt from manual click time', () => {
   assert.equal(result.patch?.actualStartAt, '2026-06-25T03:30:00.000Z');
 });
 
+test('AI dev task without an assignee must be claimed with a plan before starting', () => {
+  const draft = task({
+    assigneeId: '',
+    expectedStartAt: '',
+    expectedEndAt: '',
+    aiDraft: true,
+  });
+
+  assert.equal(needsDevTaskClaim(draft), true);
+  assert.equal(hasDevTaskPlan(draft), false);
+  assert.equal(canStartDevTask(draft), false);
+
+  const result = applyDevTaskTransition(draft, 'in_progress', {
+    now: new Date('2026-06-25T03:30:00.000Z'),
+  });
+
+  assert.equal(result.ok, false);
+});
+
+test('recommended assignee dev task still needs a plan before starting', () => {
+  const draft = task({
+    assigneeId: 'Alice',
+    expectedStartAt: '',
+    expectedEndAt: '',
+    aiDraft: true,
+  });
+
+  assert.equal(needsDevTaskClaim(draft), false);
+  assert.equal(hasDevTaskPlan(draft), false);
+  assert.equal(canStartDevTask(draft), false);
+
+  const result = applyDevTaskTransition(draft, 'in_progress', {
+    now: new Date('2026-06-25T03:30:00.000Z'),
+  });
+
+  assert.equal(result.ok, false);
+});
+
 test('in_progress to testing does not write actualEndAt', () => {
   const result = applyDevTaskTransition(task({
     status: 'in_progress',
@@ -71,6 +109,21 @@ test('testing to submitted writes actualEndAt', () => {
   assert.equal(result.patch?.actualEndAt, '2026-06-25T05:00:00.000Z');
 });
 
+test('blocked task cannot be submitted to test until unblocked', () => {
+  const result = applyDevTaskTransition(task({
+    status: 'testing',
+    actualStartAt: '2026-06-25T03:30:00.000Z',
+    isBlocked: true,
+    blockReason: '等待接口联调',
+  }), 'submitted', {
+    now: new Date('2026-06-25T05:00:00.000Z'),
+  });
+
+  assert.equal(result.ok, false);
+  assert.equal(result.patch, undefined);
+  assert.match(result.message || '', /\u963b\u585e/);
+});
+
 test('invalid transition is rejected', () => {
   const result = applyDevTaskTransition(task(), 'submitted', {
     now: new Date('2026-06-25T05:00:00.000Z'),

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

@@ -1,5 +1,5 @@
 import type { DevTask, DevTaskStatus } from './dev-task';
-import { canTransition } from './dev-task';
+import { canStartDevTask, canTransition } from './dev-task';
 
 export interface DevTaskWorkflowResult {
   ok: boolean;
@@ -30,7 +30,15 @@ export function applyDevTaskTransition(
     return { ok: false, message: `不允许从「${task.status}」流转到「${to}」` };
   }
 
+  if (to === 'submitted' && task.isBlocked) {
+    return { ok: false, message: '任务仍处于阻塞中，请先解除阻塞后再提测' };
+  }
+
   const nowIso = (options.now ?? new Date()).toISOString();
+  if (to === 'in_progress' && !canStartDevTask(task)) {
+    return { ok: false, message: '开始开发前需要先领取并填写预计开始和预计截止时间' };
+  }
+
   const patch: Partial<DevTask> = {
     status: to,
     aiDraft: false,

apps/web/lib/dev-task.ts

@@ -112,6 +112,21 @@ function roundEffortHours(hours: number): number {
   return Number(hours.toFixed(2));
 }
 
+export function needsDevTaskClaim(task: Pick<DevTask, 'assigneeId'>): boolean {
+  return !task.assigneeId?.trim();
+}
+
+export function hasDevTaskPlan(task: Pick<DevTask, 'expectedStartAt' | 'expectedEndAt'>): boolean {
+  if (!task.expectedStartAt || !task.expectedEndAt) return false;
+  const start = new Date(task.expectedStartAt).getTime();
+  const end = new Date(task.expectedEndAt).getTime();
+  return Number.isFinite(start) && Number.isFinite(end) && end > start;
+}
+
+export function canStartDevTask(task: Pick<DevTask, 'assigneeId' | 'expectedStartAt' | 'expectedEndAt'>): boolean {
+  return !needsDevTaskClaim(task) && hasDevTaskPlan(task);
+}
+
 export function getActualHours(task: DevTask, now: Date = new Date()): number {
   if (!task.actualStartAt) return 0;
   const end = task.actualEndAt ?? (task.status === 'submitted' ? task.updatedAt : now.toISOString());

apps/web/lib/entity-activity-log.test.ts

@@ -0,0 +1,48 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import type { WorkActivity } from './work-activity';
+import { getEntityActivityLogEntries } from './entity-activity-log';
+
+function activity(patch: Partial<WorkActivity>): WorkActivity {
+  return {
+    id: 'act-1',
+    actorId: '张三',
+    date: '2026-06-29',
+    occurredAt: '2026-06-29T01:00:00.000Z',
+    sourceType: 'dev_task',
+    sourceId: 'dev-1',
+    action: 'dev_task_started',
+    category: 'progress',
+    title: '开发任务',
+    summary: '开始开发：开发任务',
+    ...patch,
+  };
+}
+
+test('getEntityActivityLogEntries filters by source and sorts newest first', () => {
+  const entries = getEntityActivityLogEntries([
+    activity({ id: 'old', occurredAt: '2026-06-29T01:00:00.000Z' }),
+    activity({ id: 'other-source', sourceType: 'test_case', sourceId: 'tc-1' }),
+    activity({ id: 'new', occurredAt: '2026-06-29T03:00:00.000Z', action: 'dev_task_submitted' }),
+  ], 'dev_task', 'dev-1');
+
+  assert.deepEqual(entries.map((entry) => entry.id), ['new', 'old']);
+  assert.equal(entries[0].label, '已提测');
+});
+
+test('getEntityActivityLogEntries merges legacy logs with activity entries', () => {
+  const entries = getEntityActivityLogEntries([
+    activity({ id: 'activity-log', occurredAt: '2026-06-29T02:00:00.000Z' }),
+  ], 'dev_task', 'dev-1', [
+    {
+      id: 'legacy-log',
+      actorId: '李四',
+      occurredAt: '2026-06-29T04:00:00.000Z',
+      label: '旧日志',
+      summary: '历史操作记录',
+    },
+  ]);
+
+  assert.deepEqual(entries.map((entry) => entry.id), ['legacy-log', 'activity-log']);
+});

apps/web/lib/entity-activity-log.ts

@@ -0,0 +1,54 @@
+import type { WorkActivity, WorkActivityAction, WorkActivitySourceType } from './work-activity';
+
+export interface EntityActivityLogEntry {
+  id: string;
+  occurredAt: string;
+  actorId: string;
+  label: string;
+  summary: string;
+}
+
+export const WORK_ACTIVITY_ACTION_LABEL: Record<WorkActivityAction, string> = {
+  version_plan_created: '新建计划',
+  version_plan_started: '开始计划',
+  version_plan_completed: '完成计划',
+  dev_task_created: '新建开发任务',
+  dev_task_started: '开始开发',
+  dev_task_self_testing: '进入自测',
+  dev_task_submitted: '已提测',
+  dev_task_blocked: '标记阻塞',
+  dev_task_unblocked: '解除阻塞',
+  dev_task_transferred: '转交开发任务',
+  test_case_created: '新建测试用例',
+  test_case_started: '开始测试',
+  test_case_passed: '测试通过',
+  test_case_failed: '测试不通过',
+  test_case_blocked: '测试阻塞',
+  bug_created: '新建 Bug',
+  bug_fixing: '开始修复',
+  bug_fixed: '已修复',
+  bug_closed: '已关闭',
+  bug_blocked: 'Bug 阻塞',
+  bug_transferred: '转交 Bug',
+  progress_note_added: '补充进展',
+};
+
+export function getEntityActivityLogEntries(
+  activities: WorkActivity[],
+  sourceType: WorkActivitySourceType,
+  sourceId: string,
+  legacyEntries: EntityActivityLogEntry[] = [],
+): EntityActivityLogEntry[] {
+  const activityEntries = activities
+    .filter((activity) => activity.sourceType === sourceType && activity.sourceId === sourceId)
+    .map((activity) => ({
+      id: activity.id,
+      occurredAt: activity.occurredAt,
+      actorId: activity.actorId,
+      label: WORK_ACTIVITY_ACTION_LABEL[activity.action] || activity.action,
+      summary: activity.summary,
+    }));
+
+  return [...activityEntries, ...legacyEntries]
+    .sort((a, b) => b.occurredAt.localeCompare(a.occurredAt));
+}

apps/web/lib/test-case-workflow.test.ts

@@ -2,6 +2,7 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 
 import type { TestCase } from './test-case';
+import { canStartTestCase, hasTestCasePlan, needsTestCaseClaim } from './test-case';
 import { applyTestCaseTransition, normalizeTestCaseOnCreate } from './test-case-workflow';
 
 function tc(patch: Partial<TestCase> = {}): TestCase {
@@ -14,6 +15,9 @@ function tc(patch: Partial<TestCase> = {}): TestCase {
     categoryId: 'cat-test-functional',
     priority: 'P2',
     status: 'pending',
+    assigneeId: 'QA',
+    plannedTestAt: '2026-06-25T01:00:00.000Z',
+    plannedEndAt: '2026-06-25T02:00:00.000Z',
     createdBy: 'QA',
     createdAt: '2026-06-25T00:00:00.000Z',
     updatedAt: '2026-06-25T00:00:00.000Z',
@@ -48,6 +52,44 @@ test('pending to running writes startedAt', () => {
   assert.equal(result.patch?.startedAt, '2026-06-25T01:00:00.000Z');
 });
 
+test('AI test case without an assignee must be claimed with a plan before running', () => {
+  const draft = tc({
+    assigneeId: undefined,
+    plannedTestAt: undefined,
+    plannedEndAt: undefined,
+    aiDraft: true,
+  });
+
+  assert.equal(needsTestCaseClaim(draft), true);
+  assert.equal(hasTestCasePlan(draft), false);
+  assert.equal(canStartTestCase(draft), false);
+
+  const result = applyTestCaseTransition(draft, 'running', {
+    now: new Date('2026-06-25T01:00:00.000Z'),
+  });
+
+  assert.equal(result.ok, false);
+});
+
+test('recommended assignee test case still needs a plan before running', () => {
+  const draft = tc({
+    assigneeId: 'QA',
+    plannedTestAt: undefined,
+    plannedEndAt: undefined,
+    aiDraft: true,
+  });
+
+  assert.equal(needsTestCaseClaim(draft), false);
+  assert.equal(hasTestCasePlan(draft), false);
+  assert.equal(canStartTestCase(draft), false);
+
+  const result = applyTestCaseTransition(draft, 'running', {
+    now: new Date('2026-06-25T01:00:00.000Z'),
+  });
+
+  assert.equal(result.ok, false);
+});
+
 test('running to passed writes completedAt', () => {
   const result = applyTestCaseTransition(tc({
     status: 'running',

apps/web/lib/test-case-workflow.ts

@@ -1,5 +1,5 @@
 import type { TestCase, TestCaseStatus } from './test-case';
-import { canTcTransition, getTestCaseRoundNo } from './test-case';
+import { canStartTestCase, canTcTransition, getTestCaseRoundNo } from './test-case';
 
 export interface TestCaseWorkflowResult {
   ok: boolean;
@@ -36,6 +36,10 @@ export function applyTestCaseTransition(
   }
 
   const nowIso = (options.now ?? new Date()).toISOString();
+  if (to === 'running' && !canStartTestCase(testCase)) {
+    return { ok: false, message: '开始测试前需要先领取并填写计划开始和计划结束时间' };
+  }
+
   const patch: Partial<TestCase> = {
     status: to,
     aiDraft: false,

apps/web/lib/test-case.ts

@@ -23,6 +23,7 @@ export interface TestCase {
   estimateHours?: number;
   aiEstimateHours?: number;
   plannedTestAt?: string;
+  plannedEndAt?: string;
   startedAt?: string;
   completedAt?: string;
   executedAt?: string;
@@ -98,6 +99,7 @@ export function normalizeTestCase(testCase: Partial<TestCase>, index = 0): TestC
     estimateHours: typeof testCase.estimateHours === 'number' && testCase.estimateHours > 0 ? testCase.estimateHours : undefined,
     aiEstimateHours: typeof testCase.aiEstimateHours === 'number' && testCase.aiEstimateHours > 0 ? testCase.aiEstimateHours : undefined,
     plannedTestAt: testCase.plannedTestAt,
+    plannedEndAt: testCase.plannedEndAt,
     startedAt: testCase.startedAt,
     completedAt: testCase.completedAt,
     executedAt: testCase.executedAt,
@@ -172,6 +174,7 @@ export function copyTestCaseToRound(source: TestCase, roundNo: number, createdBy
     estimateHours: source.estimateHours,
     aiEstimateHours: source.aiEstimateHours,
     plannedTestAt: source.plannedTestAt,
+    plannedEndAt: source.plannedEndAt,
     assigneeId: source.assigneeId,
     startedAt: undefined,
     completedAt: undefined,
@@ -224,6 +227,23 @@ export function getTestCaseEstimateHours(tc: TestCase): number {
   return 0;
 }
 
+export function needsTestCaseClaim(testCase: Pick<TestCase, 'assigneeId'>): boolean {
+  return !testCase.assigneeId?.trim();
+}
+
+export function hasTestCasePlan(testCase: Pick<TestCase, 'plannedTestAt' | 'plannedEndAt'>): boolean {
+  if (!testCase.plannedTestAt || !testCase.plannedEndAt) return false;
+  const start = new Date(testCase.plannedTestAt).getTime();
+  const end = new Date(testCase.plannedEndAt).getTime();
+  return Number.isFinite(start) && Number.isFinite(end) && end > start;
+}
+
+export function canStartTestCase(
+  testCase: Pick<TestCase, 'assigneeId' | 'plannedTestAt' | 'plannedEndAt'>,
+): boolean {
+  return !needsTestCaseClaim(testCase) && hasTestCasePlan(testCase);
+}
+
 export function getTestCaseActualHours(tc: TestCase, now: Date = new Date()): number {
   if (!tc.startedAt) return 0;
   const isTerminal = tc.status === 'passed' || tc.status === 'failed' || tc.status === 'blocked';

apps/web/lib/version-plan-workflow.test.ts

@@ -38,6 +38,40 @@ test('requires product requirement coverage when linked requirements exist', ()
   assert.ok(state.missingReasons.includes('关联需求未全部覆盖'));
 });
 
+test('does not treat partial requirement coverage as complete', () => {
+  const state = getPlanCompletionState(plan({
+    requirementCoverage: [{
+      requirementId: 'r1',
+      status: 'partial',
+      completedContent: '完成列表主路径',
+      remainingContent: '剩余筛选联动和空状态',
+      updatedAt: '2026-06-29T09:00:00.000Z',
+      updatedBy: 'PM',
+    }],
+  } as Partial<VersionPlan>));
+
+  assert.equal(state.requirementCompleted, 0);
+  assert.equal(state.canSubmitResult, false);
+  assert.ok(state.missingReasons.includes('关联需求未全部覆盖'));
+});
+
+test('uses requirement coverage before legacy completed ids when both exist', () => {
+  const state = getPlanCompletionState(plan({
+    completedRequirementIds: ['r1'],
+    requirementCoverage: [{
+      requirementId: 'r1',
+      status: 'partial',
+      completedContent: '完成移动端',
+      remainingContent: 'PC 端未完成',
+      updatedAt: '2026-06-29T09:00:00.000Z',
+      updatedBy: 'PM',
+    }],
+  } as Partial<VersionPlan>));
+
+  assert.equal(state.requirementCompleted, 0);
+  assert.equal(state.canSubmitResult, false);
+});
+
 test('allows product result submission after coverage is complete without task checklist', () => {
   const state = getPlanCompletionState(plan({
     completedRequirementIds: ['r1'],

apps/web/lib/version-plan-workflow.ts

@@ -1,3 +1,4 @@
+import { getRequirementCoverageSummary } from './version-plan';
 import type { ProductPlanKind, ProductPlanReviewFailureType, ProductPlanReviewResult, VersionPlan } from './version-plan';
 
 export interface PlanResultPayload {
@@ -67,10 +68,9 @@ export function getPlanCompletionState(plan: VersionPlan): PlanCompletionState {
   const checklistTotal = tasks.length;
   const checklistCompleted = tasks.filter((task) => task.status === 'completed').length;
 
-  const linked = plan.linkedRequirementIds ?? [];
-  const completed = new Set(plan.completedRequirementIds ?? []);
-  const requirementTotal = linked.length;
-  const requirementCompleted = linked.filter((id) => completed.has(id)).length;
+  const requirementSummary = getRequirementCoverageSummary(plan);
+  const requirementTotal = requirementSummary.total;
+  const requirementCompleted = requirementSummary.completed;
 
   const missingReasons: string[] = [];
   if (requiresChecklist(plan) && checklistTotal === 0) missingReasons.push('缺少子任务');

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

@@ -35,3 +35,84 @@ test('sortPlansNewestFirst places newly created plans before older plans', () =>
   assert.deepEqual(sorted.map((item) => item.id), ['plan-300', 'plan-100', 'manual-old']);
   assert.deepEqual(plans.map((item) => item.id), ['plan-100', 'manual-old', 'plan-300']);
 });
+
+test('derives requirement coverage from new records and legacy completed ids', () => {
+  const getRequirementCoverageStatus = (versionPlan as any).getRequirementCoverageStatus as undefined | ((item: VersionPlan, requirementId: string) => string);
+  const getRequirementCoverageSummary = (versionPlan as any).getRequirementCoverageSummary as undefined | ((item: VersionPlan) => {
+    total: number;
+    completed: number;
+    partial: number;
+    notStarted: number;
+    percent: number;
+  });
+  assert.equal(typeof getRequirementCoverageStatus, 'function');
+  assert.equal(typeof getRequirementCoverageSummary, 'function');
+
+  const item = plan({
+    linkedRequirementIds: ['r1', 'r2', 'r3', 'r4'],
+    completedRequirementIds: ['r2'],
+    requirementCoverage: [
+      {
+        requirementId: 'r1',
+        status: 'partial',
+        completedContent: '完成主流程原型',
+        remainingContent: '补充异常状态',
+        updatedAt: '2026-06-29T09:00:00.000Z',
+        updatedBy: 'PM',
+      },
+      {
+        requirementId: 'r3',
+        status: 'completed',
+        completedContent: '已覆盖列表和详情',
+        updatedAt: '2026-06-29T10:00:00.000Z',
+        updatedBy: 'PM',
+      },
+    ],
+  } as Partial<VersionPlan>);
+
+  assert.equal(getRequirementCoverageStatus!(item, 'r1'), 'partial');
+  assert.equal(getRequirementCoverageStatus!(item, 'r2'), 'completed');
+  assert.equal(getRequirementCoverageStatus!(item, 'r4'), 'not_started');
+  assert.deepEqual(getRequirementCoverageSummary!(item), {
+    total: 4,
+    completed: 2,
+    partial: 1,
+    notStarted: 1,
+    percent: 50,
+  });
+});
+
+test('updates requirement coverage, syncs legacy completed ids, and creates a plan log', () => {
+  const updateRequirementCoverage = (versionPlan as any).updateRequirementCoverage as undefined | ((item: VersionPlan, input: {
+    requirementId: string;
+    status: string;
+    completedContent?: string;
+    remainingContent?: string;
+    updatedBy: string;
+    updatedAt: string;
+    requirementCode?: string;
+    requirementTitle?: string;
+  }) => any);
+  assert.equal(typeof updateRequirementCoverage, 'function');
+
+  const next = updateRequirementCoverage!(plan({
+    linkedRequirementIds: ['r1'],
+    completedRequirementIds: ['r1'],
+  }), {
+    requirementId: 'r1',
+    status: 'partial',
+    completedContent: '完成移动端主流程',
+    remainingContent: 'PC 端筛选规则未完成',
+    updatedBy: 'PM',
+    updatedAt: '2026-06-29T12:00:00.000Z',
+    requirementCode: 'QY0001',
+    requirementTitle: '需求池筛选',
+  });
+
+  assert.deepEqual(next.completedRequirementIds, []);
+  assert.equal(next.requirementCoverage?.[0]?.status, 'partial');
+  assert.equal(next.logs?.length, 1);
+  assert.equal(next.logs?.[0]?.type, 'requirement_progress');
+  assert.equal(next.logs?.[0]?.actor, 'PM');
+  assert.equal(next.logs?.[0]?.requirementCode, 'QY0001');
+});

apps/web/lib/version-plan.ts

@@ -3,6 +3,9 @@ import type { AgentDecomposeTarget } from '@ftb/shared';
 export type PlanTaskStatus = 'pending' | 'in_progress' | 'completed';
 export type ProductPlanKind = 'design' | 'review';
 export type ProductPlanReviewResult = 'passed' | 'failed';
+export type RequirementCoverageStatus = 'not_started' | 'partial' | 'completed';
+export type VersionPlanLogType = 'requirement_progress' | 'ai_decompose' | 'system';
+export type AiDecomposeLogStatus = 'started' | 'completed' | 'error';
 export type ProductPlanReviewFailureType =
   | 'requirement_mismatch'
   | 'information_architecture'
@@ -44,6 +47,52 @@ export interface PlanTask {
   status: PlanTaskStatus;
 }
 
+export interface VersionPlanRequirementCoverage {
+  requirementId: string;
+  status: RequirementCoverageStatus;
+  completedContent?: string;
+  remainingContent?: string;
+  updatedAt: string;
+  updatedBy: string;
+}
+
+export interface VersionPlanLog {
+  id: string;
+  type: VersionPlanLogType;
+  createdAt: string;
+  actor: string;
+  title: string;
+  detail?: string;
+  requirementId?: string;
+  requirementCode?: string;
+  requirementTitle?: string;
+  coverageStatus?: RequirementCoverageStatus;
+  aiTarget?: AgentDecomposeTarget;
+  aiStatus?: AiDecomposeLogStatus;
+}
+
+export interface RequirementCoverageUpdateInput {
+  requirementId: string;
+  status: RequirementCoverageStatus;
+  completedContent?: string;
+  remainingContent?: string;
+  updatedAt?: string;
+  updatedBy: string;
+  requirementCode?: string;
+  requirementTitle?: string;
+}
+
+export type PlanLogDraft = Omit<VersionPlanLog, 'id' | 'createdAt'> & {
+  id?: string;
+  createdAt?: string;
+};
+
+export const REQUIREMENT_COVERAGE_LABEL: Record<RequirementCoverageStatus, string> = {
+  not_started: '未开始',
+  partial: '部分完成',
+  completed: '完全完成',
+};
+
 export interface VersionPlan {
   id: string;
   versionId: string;
@@ -56,6 +105,8 @@ export interface VersionPlan {
   tasks?: PlanTask[];
   completedRequirementIds?: string[];
   linkedRequirementIds?: string[];
+  requirementCoverage?: VersionPlanRequirementCoverage[];
+  logs?: VersionPlanLog[];
   productPlanKind?: ProductPlanKind;
   resultType?: 'link' | 'file';
   resultTitle?: string;
@@ -81,6 +132,106 @@ export interface VersionPlan {
 
 export type PlanType = VersionPlan['type'];
 
+function makePlanLogId(createdAt: string): string {
+  const time = new Date(createdAt).getTime();
+  const suffix = Math.random().toString(36).slice(2, 8);
+  return `plan-log-${Number.isFinite(time) ? time : Date.now()}-${suffix}`;
+}
+
+export function getRequirementCoverage(plan: VersionPlan, requirementId: string): VersionPlanRequirementCoverage | undefined {
+  const explicit = plan.requirementCoverage?.find((item) => item.requirementId === requirementId);
+  if (explicit) return explicit;
+  if ((plan.completedRequirementIds ?? []).includes(requirementId)) {
+    return {
+      requirementId,
+      status: 'completed',
+      updatedAt: plan.completedAt ?? plan.createdAt,
+      updatedBy: plan.owner,
+    };
+  }
+  return undefined;
+}
+
+export function getRequirementCoverageStatus(plan: VersionPlan, requirementId: string): RequirementCoverageStatus {
+  return getRequirementCoverage(plan, requirementId)?.status ?? 'not_started';
+}
+
+export function getRequirementCoverageSummary(plan: VersionPlan): {
+  total: number;
+  completed: number;
+  partial: number;
+  notStarted: number;
+  percent: number;
+} {
+  const linkedIds = plan.linkedRequirementIds ?? [];
+  const total = linkedIds.length;
+  const completed = linkedIds.filter((id) => getRequirementCoverageStatus(plan, id) === 'completed').length;
+  const partial = linkedIds.filter((id) => getRequirementCoverageStatus(plan, id) === 'partial').length;
+  const notStarted = Math.max(total - completed - partial, 0);
+  return {
+    total,
+    completed,
+    partial,
+    notStarted,
+    percent: total === 0 ? 0 : Math.round((completed / total) * 100),
+  };
+}
+
+export function appendPlanLog(plan: VersionPlan, draft: PlanLogDraft): VersionPlanLog[] {
+  const createdAt = draft.createdAt ?? new Date().toISOString();
+  const log: VersionPlanLog = {
+    ...draft,
+    id: draft.id ?? makePlanLogId(createdAt),
+    createdAt,
+  };
+  return [log, ...(plan.logs ?? [])];
+}
+
+export function updateRequirementCoverage(
+  plan: VersionPlan,
+  input: RequirementCoverageUpdateInput,
+): Pick<VersionPlan, 'requirementCoverage' | 'completedRequirementIds' | 'logs'> {
+  const updatedAt = input.updatedAt ?? new Date().toISOString();
+  const nextCoverage: VersionPlanRequirementCoverage = {
+    requirementId: input.requirementId,
+    status: input.status,
+    completedContent: input.completedContent?.trim() || undefined,
+    remainingContent: input.remainingContent?.trim() || undefined,
+    updatedAt,
+    updatedBy: input.updatedBy,
+  };
+  const requirementCoverage = [
+    nextCoverage,
+    ...(plan.requirementCoverage ?? []).filter((item) => item.requirementId !== input.requirementId),
+  ];
+
+  const completedSet = new Set(plan.completedRequirementIds ?? []);
+  if (input.status === 'completed') completedSet.add(input.requirementId);
+  else completedSet.delete(input.requirementId);
+
+  const detail = [
+    nextCoverage.completedContent ? `已完成：${nextCoverage.completedContent}` : '',
+    nextCoverage.remainingContent ? `剩余：${nextCoverage.remainingContent}` : '',
+  ].filter(Boolean).join('\n');
+  const reqLabel = [input.requirementCode, input.requirementTitle].filter(Boolean).join(' ');
+
+  return {
+    requirementCoverage,
+    completedRequirementIds: Array.from(completedSet),
+    logs: appendPlanLog(plan, {
+      type: 'requirement_progress',
+      createdAt: updatedAt,
+      actor: input.updatedBy,
+      title: `${reqLabel || '需求'}更新为${REQUIREMENT_COVERAGE_LABEL[input.status]}`,
+      detail: detail || undefined,
+      requirementId: input.requirementId,
+      requirementCode: input.requirementCode,
+      requirementTitle: input.requirementTitle,
+      coverageStatus: input.status,
+    }),
+  };
+}
+
 function getPlanCreatedAtTime(plan: VersionPlan): number {
   const time = new Date(plan.createdAt).getTime();
   return Number.isFinite(time) ? time : 0;

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

@@ -0,0 +1,66 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { calcVersionProgress } from './version-progress';
+import type { Requirement } from './requirement';
+import type { VersionPlan } from './version-plan';
+
+function requirement(id: string): Requirement {
+  return {
+    id,
+    code: 'QY0001',
+    title: '需求',
+    description: '需求描述',
+    productId: 'product-1',
+    projectId: 'project-1',
+    versionId: 'version-1',
+    sourceType: 'internal',
+    sourceTarget: '产品部',
+    platforms: ['web'],
+    typeId: 'type-1',
+    status: 'planned',
+    priority: 'P1',
+    effort: 'M',
+    creator: 'PM',
+    createdAt: '2026-06-29',
+  };
+}
+
+function plan(patch: Partial<VersionPlan>): VersionPlan {
+  return {
+    id: 'plan-1',
+    versionId: 'version-1',
+    type: 'product',
+    title: '产品方案',
+    owner: 'PM',
+    startTime: '2026-06-29T09:00',
+    endTime: '2026-06-29T18:00',
+    status: 'in_progress',
+    linkedRequirementIds: ['r1'],
+    completedRequirementIds: ['r1'],
+    createdAt: '2026-06-29',
+    addedBy: 'PM',
+    ...patch,
+  };
+}
+
+test('version progress uses explicit requirement coverage before legacy completed ids', () => {
+  const progress = calcVersionProgress(
+    'version-1',
+    [plan({
+      requirementCoverage: [{
+        requirementId: 'r1',
+        status: 'partial',
+        completedContent: '完成主流程',
+        remainingContent: '剩余异常状态',
+        updatedAt: '2026-06-29T09:00:00.000Z',
+        updatedBy: 'PM',
+      }],
+    } as Partial<VersionPlan>)],
+    [requirement('r1')],
+    [],
+    [],
+  );
+
+  assert.equal(progress, 0);
+});

apps/web/lib/version-progress.ts

@@ -1,3 +1,4 @@
+import { getRequirementCoverageSummary } from './version-plan';
 import type { VersionPlan } from './version-plan';
 import type { Requirement } from './requirement';
 import type { DevTask } from './dev-task';
@@ -38,10 +39,9 @@ export function calcVersionProgress(
   const productPlans = vPlans.filter((p) => p.type === 'product');
   if (productPlans.length > 0) {
     const totals = productPlans.reduce((acc, p) => {
-      const linked = p.linkedRequirementIds || [];
-      const completed = p.completedRequirementIds || [];
-      acc.total += linked.length;
-      acc.done += completed.filter((id) => linked.includes(id)).length;
+      const summary = getRequirementCoverageSummary(p);
+      acc.total += summary.total;
+      acc.done += summary.completed;
       return acc;
     }, { total: 0, done: 0 });
     segments.push(totals.total > 0 ? (totals.done / totals.total) * 100 : 0);
@@ -50,10 +50,9 @@ export function calcVersionProgress(
   const uiPlans = vPlans.filter((p) => p.type === 'ui');
   if (uiPlans.length > 0) {
     const totals = uiPlans.reduce((acc, p) => {
-      const linked = p.linkedRequirementIds || [];
-      const completed = p.completedRequirementIds || [];
-      acc.total += linked.length;
-      acc.done += completed.filter((id) => linked.includes(id)).length;
+      const summary = getRequirementCoverageSummary(p);
+      acc.total += summary.total;
+      acc.done += summary.completed;
       return acc;
     }, { total: 0, done: 0 });
     segments.push(totals.total > 0 ? (totals.done / totals.total) * 100 : 0);