feat(v2.4): 切换需求池领域主写

apps/server/src/modules/requirement/dto/create-requirement.dto.ts

@@ -1,4 +1,5 @@
-import { IsString, IsNotEmpty, IsOptional, IsInt, Min, Max } from 'class-validator';
+import { RequirementStatus } from '@ftb/shared';
+import { IsArray, IsIn, IsNotEmpty, IsOptional, IsString } from 'class-validator';
 
 export class CreateRequirementDto {
   @IsString()
@@ -13,13 +14,46 @@ export class CreateRequirementDto {
   @IsOptional()
   description?: string;
 
-  @IsInt()
-  @Min(0)
-  @Max(4)
   @IsOptional()
-  priority?: number;
+  priority?: string | number;
 
   @IsString()
-  @IsNotEmpty()
+  @IsOptional()
-  creatorId!: string;
+  projectId?: string;
+
+  @IsString()
+  @IsOptional()
+  versionId?: string;
+
+  @IsString()
+  @IsOptional()
+  type?: string;
+
+  @IsString()
+  @IsOptional()
+  typeId?: string;
+
+  @IsString()
+  @IsOptional()
+  sourceType?: string;
+
+  @IsString()
+  @IsOptional()
+  sourceTarget?: string;
+
+  @IsString()
+  @IsOptional()
+  platform?: string;
+
+  @IsArray()
+  @IsOptional()
+  platforms?: string[];
+
+  @IsIn(Object.values(RequirementStatus))
+  @IsOptional()
+  status?: RequirementStatus;
+
+  @IsString()
+  @IsOptional()
+  creatorId?: string;
 }

apps/server/src/modules/requirement/requirement.controller.ts

@@ -20,8 +20,26 @@ export class RequirementController {
   findAll(
     @Param('productId') productId: string,
     @Query('status') status?: string,
+    @Query('projectId') projectId?: string,
+    @Query('versionId') versionId?: string,
+    @Query('priority') priority?: string,
+    @Query('type') type?: string,
+    @Query('q') q?: string,
+    @Query('sort') sort?: string,
+    @Query('cursor') cursor?: string,
+    @Query('limit') limit?: string,
   ) {
-    return this.requirementService.findAll(productId, status);
+    return this.requirementService.findAll(productId, {
+      projectId,
+      versionId,
+      status,
+      priority,
+      type,
+      q,
+      sort,
+      cursor,
+      limit,
+    });
   }
 
   @Get(':id')

apps/server/src/modules/requirement/requirement.service.spec.ts

@@ -37,6 +37,84 @@ describe('RequirementService with V2.2 composite requirement key', () => {
     });
   });
 
+  it('creates requirements with frontend pool fields in relation columns', async () => {
+    const { prisma, service } = makeService();
+    prisma.requirement.create.mockResolvedValue({ id: 'req-1', productId: 'product-1', code: 'REQ-001' });
+
+    await service.create('product-1', {
+      code: 'REQ-001',
+      title: 'Payment',
+      projectId: 'project-1',
+      versionId: 'version-1',
+      type: 'feature',
+      sourceType: 'customer',
+      sourceTarget: 'ACME',
+      platform: 'web,ios',
+      priority: 1,
+    } as any);
+
+    expect(prisma.requirement.create).toHaveBeenCalledWith({
+      data: expect.objectContaining({
+        productId: 'product-1',
+        projectId: 'project-1',
+        versionId: 'version-1',
+        type: 'feature',
+        sourceType: 'customer',
+        sourceTarget: 'ACME',
+        platform: 'web,ios',
+      }),
+    });
+  });
+
+  it('paginates requirement pool queries by product partition key and composite cursor', async () => {
+    const { prisma, service } = makeService();
+    prisma.requirement.findMany.mockResolvedValue([{ id: 'req-2' }, { id: 'req-1' }]);
+
+    const result = await service.findAll('product-1', {
+      projectId: 'project-1',
+      versionId: 'version-1',
+      status: 'adopted',
+      priority: 'P1',
+      type: 'feature',
+      q: 'login',
+      sort: 'created_at_asc',
+      cursor: 'req-3',
+      limit: '1',
+    } as any);
+
+    expect(result).toEqual({ items: [{ id: 'req-2' }], nextCursor: 'req-1' });
+    expect(prisma.requirement.findMany).toHaveBeenCalledWith({
+      where: {
+        productId: 'product-1',
+        projectId: 'project-1',
+        versionId: 'version-1',
+        status: 'adopted',
+        priority: 1,
+        type: 'feature',
+        OR: [
+          { code: { contains: 'login', mode: 'insensitive' } },
+          { title: { contains: 'login', mode: 'insensitive' } },
+        ],
+      },
+      include: { creator: { select: { id: true, name: true } } },
+      orderBy: { createdAt: 'asc' },
+      take: 2,
+      cursor: { id_productId: { id: 'req-3', productId: 'product-1' } },
+      skip: 1,
+    });
+  });
+
+  it('uses only approved requirement sort keys', async () => {
+    const { prisma, service } = makeService();
+    prisma.requirement.findMany.mockResolvedValue([]);
+
+    await service.findAll('product-1', { sort: 'unsafe_sql_asc', limit: '20' } as any);
+
+    expect(prisma.requirement.findMany).toHaveBeenCalledWith(expect.objectContaining({
+      orderBy: { createdAt: 'desc' },
+    }));
+  });
+
   it('updates requirements by id plus product id', async () => {
     const { prisma, service } = makeService();
     prisma.requirement.findFirst.mockResolvedValue({
@@ -54,6 +132,37 @@ describe('RequirementService with V2.2 composite requirement key', () => {
     });
   });
 
+  it('updates frontend pool fields by id plus product id', async () => {
+    const { prisma, service } = makeService();
+    prisma.requirement.findFirst.mockResolvedValue({
+      id: 'req-1',
+      productId: 'product-1',
+      status: 'pending_review',
+    });
+    prisma.requirement.update.mockResolvedValue({ id: 'req-1', productId: 'product-1' });
+
+    await service.update('product-1', 'req-1', {
+      projectId: 'project-2',
+      versionId: 'version-2',
+      type: 'optimization',
+      sourceType: 'internal',
+      sourceTarget: 'Product',
+      platform: 'web,h5',
+    } as any);
+
+    expect(prisma.requirement.update).toHaveBeenCalledWith({
+      where: { id_productId: { id: 'req-1', productId: 'product-1' } },
+      data: {
+        projectId: 'project-2',
+        versionId: 'version-2',
+        type: 'optimization',
+        sourceType: 'internal',
+        sourceTarget: 'Product',
+        platform: 'web,h5',
+      },
+    });
+  });
+
   it('deletes requirements by id plus product id', async () => {
     const { prisma, service } = makeService();
     prisma.requirement.findFirst.mockResolvedValue({
@@ -75,7 +184,9 @@ describe('RequirementService with V2.2 composite requirement key', () => {
     ['pending_review', 'rejected'],
     ['rejected', 'pending_review'],
     ['adopted', 'planned'],
+    ['adopted', 'closed'],
     ['planned', 'developing'],
+    ['planned', 'closed'],
     ['developing', 'testing'],
     ['testing', 'released'],
     ['released', 'closed'],

apps/server/src/modules/requirement/requirement.service.ts

@@ -7,14 +7,26 @@ import { UpdateRequirementDto } from './dto/update-requirement.dto';
 const VALID_TRANSITIONS: Record<string, string[]> = {
   [RequirementStatus.PENDING_REVIEW]: [RequirementStatus.ADOPTED, RequirementStatus.REJECTED],
   [RequirementStatus.REJECTED]: [RequirementStatus.PENDING_REVIEW],
-  [RequirementStatus.ADOPTED]: [RequirementStatus.PLANNED],
+  [RequirementStatus.ADOPTED]: [RequirementStatus.PLANNED, RequirementStatus.CLOSED],
-  [RequirementStatus.PLANNED]: [RequirementStatus.DEVELOPING],
+  [RequirementStatus.PLANNED]: [RequirementStatus.DEVELOPING, RequirementStatus.CLOSED],
   [RequirementStatus.DEVELOPING]: [RequirementStatus.TESTING],
   [RequirementStatus.TESTING]: [RequirementStatus.RELEASED],
   [RequirementStatus.RELEASED]: [RequirementStatus.CLOSED],
   [RequirementStatus.CLOSED]: [],
 };
 
+export interface RequirementListQuery {
+  projectId?: string;
+  versionId?: string;
+  status?: string;
+  priority?: string;
+  type?: string;
+  q?: string;
+  sort?: string;
+  cursor?: string;
+  limit?: string | number;
+}
+
 function createFallbackRequirementCode() {
   return `REQ-${Date.now().toString(36).toUpperCase()}-${Math.random()
     .toString(36)
@@ -27,28 +39,62 @@ export class RequirementService {
   constructor(private prisma: PrismaService) {}
 
   create(productId: string, dto: CreateRequirementDto) {
+    const data = this.toRequirementData(dto);
     return this.prisma.requirement.create({
       data: {
+        ...data,
         productId,
         code: dto.code?.trim() || createFallbackRequirementCode(),
         title: dto.title,
-        description: dto.description || '',
+        description: dto.description ?? '',
-        status: RequirementStatus.PENDING_REVIEW,
+        status: dto.status ?? RequirementStatus.PENDING_REVIEW,
-        priority: dto.priority ?? 0,
+        priority: parsePriorityValue(dto.priority) ?? 0,
-        creatorId: dto.creatorId,
       },
     });
   }
 
-  findAll(productId: string, status?: string) {
+  async findAll(productId: string, query: RequirementListQuery = {}) {
-    return this.prisma.requirement.findMany({
+    const normalizedProductId = productId?.trim();
+    if (!normalizedProductId) {
+      throw new BadRequestException('productId is required for requirement pool queries');
+    }
+
+    const limit = parseLimit(query.limit);
+    const priority = parsePriorityValue(query.priority);
+    const search = query.q?.trim();
+    const rows = await this.prisma.requirement.findMany({
       where: {
-        productId,
+        productId: normalizedProductId,
-        ...(status ? { status } : {}),
+        ...(query.projectId?.trim() ? { projectId: query.projectId.trim() } : {}),
+        ...(query.versionId?.trim() ? { versionId: query.versionId.trim() } : {}),
+        ...(query.status?.trim() ? { status: query.status.trim() } : {}),
+        ...(priority !== undefined ? { priority } : {}),
+        ...(query.type?.trim() ? { type: query.type.trim() } : {}),
+        ...(search
+          ? {
+            OR: [
+              { code: { contains: search, mode: 'insensitive' as const } },
+              { title: { contains: search, mode: 'insensitive' as const } },
+            ],
+          }
+          : {}),
       },
-      orderBy: { createdAt: 'desc' },
       include: { creator: { select: { id: true, name: true } } },
+      orderBy: parseRequirementSort(query.sort),
+      take: limit + 1,
+      ...(query.cursor
+        ? {
+          cursor: { id_productId: { id: query.cursor, productId: normalizedProductId } },
+          skip: 1,
+        }
+        : {}),
     });
+
+    const hasNext = rows.length > limit;
+    return {
+      items: hasNext ? rows.slice(0, limit) : rows,
+      nextCursor: hasNext ? rows[limit]?.id : undefined,
+    };
   }
 
   async findOne(productId: string, id: string) {
@@ -64,12 +110,7 @@ export class RequirementService {
     await this.findOne(productId, id);
     return this.prisma.requirement.update({
       where: { id_productId: { id, productId } },
-      data: {
+      data: this.toRequirementData(dto),
-        ...(dto.code !== undefined && { code: dto.code }),
-        ...(dto.title !== undefined && { title: dto.title }),
-        ...(dto.description !== undefined && { description: dto.description }),
-        ...(dto.priority !== undefined && { priority: dto.priority }),
-      },
     });
   }
 
@@ -91,4 +132,75 @@ export class RequirementService {
     await this.findOne(productId, id);
     return this.prisma.requirement.delete({ where: { id_productId: { id, productId } } });
   }
+
+  private toRequirementData(dto: CreateRequirementDto | UpdateRequirementDto) {
+    const type = dto.type ?? dto.typeId;
+    const platform = dto.platform ?? arrayToCsv(dto.platforms);
+    const priority = parsePriorityValue(dto.priority);
+
+    return {
+      ...(dto.code !== undefined && { code: dto.code }),
+      ...(dto.title !== undefined && { title: dto.title }),
+      ...(dto.description !== undefined && { description: dto.description }),
+      ...(dto.projectId !== undefined && { projectId: emptyToNull(dto.projectId) }),
+      ...(dto.versionId !== undefined && { versionId: emptyToNull(dto.versionId) }),
+      ...(type !== undefined && { type: emptyToNull(type) }),
+      ...(dto.sourceType !== undefined && { sourceType: emptyToNull(dto.sourceType) }),
+      ...(dto.sourceTarget !== undefined && { sourceTarget: emptyToNull(dto.sourceTarget) }),
+      ...(platform !== undefined && { platform: emptyToNull(platform) }),
+      ...(dto.creatorId !== undefined && { creatorId: emptyToNull(dto.creatorId) }),
+      ...(priority !== undefined && { priority }),
+    };
+  }
+}
+
+function emptyToNull(value: string | null | undefined): string | null {
+  if (value === null) return null;
+  if (value === undefined) return null;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : null;
+}
+
+function arrayToCsv(value: string[] | undefined): string | undefined {
+  if (!value) return undefined;
+  return value.map((item) => item.trim()).filter(Boolean).join(',');
+}
+
+function parseLimit(raw?: string | number): number {
+  const parsed = raw === undefined ? 50 : Number(raw);
+  if (!Number.isFinite(parsed)) return 50;
+  return Math.max(1, Math.min(200, Math.floor(parsed)));
+}
+
+function parsePriorityValue(raw?: string | number | null): number | undefined {
+  if (raw === null || raw === undefined || raw === '') return undefined;
+  if (typeof raw === 'number') return Number.isFinite(raw) ? Math.max(0, Math.min(4, Math.floor(raw))) : undefined;
+  const normalized = raw.trim().toUpperCase();
+  const prefixed = /^P([0-4])$/.exec(normalized);
+  if (prefixed) return Number(prefixed[1]);
+  const parsed = Number(normalized);
+  if (!Number.isFinite(parsed)) return undefined;
+  return Math.max(0, Math.min(4, Math.floor(parsed)));
+}
+
+function parseRequirementSort(sort?: string) {
+  switch (sort) {
+    case 'created_at_asc':
+      return { createdAt: 'asc' as const };
+    case 'priority_asc':
+      return { priority: 'asc' as const };
+    case 'priority_desc':
+      return { priority: 'desc' as const };
+    case 'code_asc':
+      return { code: 'asc' as const };
+    case 'code_desc':
+      return { code: 'desc' as const };
+    case 'updated_at_asc':
+      return { updatedAt: 'asc' as const };
+    case 'updated_at_desc':
+      return { updatedAt: 'desc' as const };
+    case 'created_at_desc':
+    default:
+      return { createdAt: 'desc' as const };
+  }
 }

apps/web/app/requirements/page.tsx

@@ -432,7 +432,6 @@ function RequirementsPageContent() {
   }, [scopedRequirements, search, statusFilter, priorityFilter, typeFilter, versionFilter, dateSort, requirementDevStatusMap]);
 
   const appDataRequirementById = useMemo(() => new Map(requirements.map((item) => [item.id, item])), [requirements]);
-  const appDataRequirementIds = useMemo(() => new Set(appDataRequirementById.keys()), [appDataRequirementById]);
   const usingV22Requirements = Boolean(v22RequirementQuery) && !v22RequirementsFailed;
   const appTotalPages = Math.max(1, Math.ceil(filtered.length / pageSize));
   const appPage = Math.min(page, appTotalPages);
@@ -450,7 +449,7 @@ function RequirementsPageContent() {
     : filtered.length;
   const displayPage = usingV22Requirements ? page : appPage;
   const displayedScopeCount = usingV22Requirements ? total : scopedRequirements.length;
-  const canMutateRequirement = (req: Requirement) => requirementsLoaded && appDataRequirementIds.has(req.id);
+  const canMutateRequirement = (req: Requirement) => Boolean(req.productId);
   const handlePageChange = (nextPage: number) => {
     if (usingV22Requirements && nextPage > page && !v22CursorByPage[nextPage]) return;
     setPage(nextPage);
@@ -789,7 +788,7 @@ function RequirementsPageContent() {
                             {canMutateRequirement(req) && req.status === 'pending_review' && (
                               <>
                                 <button
-                                  onClick={() => updateRequirement(req.id, { status: 'adopted' })}
+                                  onClick={() => updateRequirement(req.id, { productId: req.productId, status: 'adopted' })}
                                   className={`${REQUIREMENT_ACTION_BUTTON_BASE_CLASS} ${REQUIREMENT_ACTION_BUTTON_TONE_CLASS.success}`}
                                   title="采纳"
                                   aria-label="采纳需求"
@@ -809,7 +808,7 @@ function RequirementsPageContent() {
                             {/* 已采纳/已规划：关闭 */}
                             {canMutateRequirement(req) && (req.status === 'adopted' || req.status === 'planned') && canCloseRequirement(req.id, devTasksByRequirement.get(req.id) ?? []) && (
                               <button
-                                onClick={() => updateRequirement(req.id, { status: 'closed' })}
+                                onClick={() => updateRequirement(req.id, { productId: req.productId, status: 'closed' })}
                                 className={`${REQUIREMENT_ACTION_BUTTON_BASE_CLASS} ${REQUIREMENT_ACTION_BUTTON_TONE_CLASS.warning}`}
                                 title="关闭"
                                 aria-label="关闭需求"
@@ -820,7 +819,7 @@ function RequirementsPageContent() {
                             {/* 删除：待评审/已拒绝/已关闭（已采纳后不能直接删，需走拒绝） */}
                             {canMutateRequirement(req) && (['pending_review', 'rejected', 'closed'] as const).includes(req.status as any) && (
                               <button
-                                onClick={() => deleteRequirement(req.id)}
+                                onClick={() => deleteRequirement(req.id, req.productId)}
                                 className={`${REQUIREMENT_ACTION_BUTTON_BASE_CLASS} ${REQUIREMENT_ACTION_BUTTON_TONE_CLASS.danger}`}
                                 title="删除"
                                 aria-label="删除需求"
@@ -854,10 +853,10 @@ function RequirementsPageContent() {
           resolveVersionName={resolveVersionName}
           onClose={() => setViewingReq(null)}
           onEdit={canMutateRequirement(viewingReq) && canEditRequirement(viewingReq.id, devTasksByRequirement.get(viewingReq.id) ?? []) ? () => handleEdit(viewingReq) : undefined}
-          onAdopt={canMutateRequirement(viewingReq) ? () => { updateRequirement(viewingReq.id, { status: 'adopted' }); setViewingReq(null); } : undefined}
+          onAdopt={canMutateRequirement(viewingReq) ? () => { updateRequirement(viewingReq.id, { productId: viewingReq.productId, status: 'adopted' }); setViewingReq(null); } : undefined}
           onReject={canMutateRequirement(viewingReq) ? () => { setRejectingReq(viewingReq); setRejectReason(''); setViewingReq(null); } : undefined}
-          onCloseReq={canMutateRequirement(viewingReq) && canCloseRequirement(viewingReq.id, devTasksByRequirement.get(viewingReq.id) ?? []) ? () => { updateRequirement(viewingReq.id, { status: 'closed' }); setViewingReq(null); } : undefined}
+          onCloseReq={canMutateRequirement(viewingReq) && canCloseRequirement(viewingReq.id, devTasksByRequirement.get(viewingReq.id) ?? []) ? () => { updateRequirement(viewingReq.id, { productId: viewingReq.productId, status: 'closed' }); setViewingReq(null); } : undefined}
-          onDelete={canMutateRequirement(viewingReq) ? () => { deleteRequirement(viewingReq.id); setViewingReq(null); } : undefined}
+          onDelete={canMutateRequirement(viewingReq) ? () => { deleteRequirement(viewingReq.id, viewingReq.productId); setViewingReq(null); } : undefined}
         />
       )}
 
@@ -882,7 +881,7 @@ function RequirementsPageContent() {
                 data.versionId,
                 data.versionId !== editingReq.versionId ? currentUserName : editingReq.addedToVersionBy,
               );
-              updateRequirement(editingReq.id, { ...data, ...versionPatch });
+              updateRequirement(editingReq.id, { ...data, productId: editingReq.productId, ...versionPatch });
             } else {
               createRequirement(data);
             }
@@ -947,7 +946,7 @@ function RequirementsPageContent() {
               <button
                 onClick={() => {
                   if (!rejectReason.trim()) return;
-                  updateRequirement(rejectingReq.id, { status: 'rejected', description: rejectingReq.description + `\n\n【拒绝原因】${rejectReason.trim()}` });
+                  updateRequirement(rejectingReq.id, { productId: rejectingReq.productId, status: 'rejected', description: rejectingReq.description + `\n\n【拒绝原因】${rejectReason.trim()}` });
                   setRejectingReq(null);
                 }}
                 disabled={!rejectReason.trim()}

apps/web/app/versions/[id]/page.tsx

@@ -358,7 +358,10 @@ export default function VersionDetailPage() {
             alert('版本关联数据正在加载，请稍后再删除。');
             return;
           }
-          scopedVersionData.requirements.forEach((r) => updateRequirement(r.id, getRequirementVersionUnlinkPatch(r)));
+          scopedVersionData.requirements.forEach((r) => updateRequirement(r.id, {
+            productId: r.productId,
+            ...getRequirementVersionUnlinkPatch(r),
+          }));
           // 清理计划任务
           scopedVersionData.plans.forEach((p) => deletePlan(p.id));
           // 清理开发任务
@@ -988,16 +991,22 @@ export default function VersionDetailPage() {
             onLink={(ids, addedBy) => {
               if (versionReadonly || !requirementWriteReady) return;
               ids.forEach((id) => {
-                const requirement = requirements.find((item) => item.id === id);
+                const requirement = displayRequirements.find((item) => item.id === id);
                 if (!requirement) return;
-                updateRequirement(id, getRequirementVersionSelectionPatch(requirement, version.id, addedBy));
+                updateRequirement(id, {
+                  productId: requirement.productId,
+                  ...getRequirementVersionSelectionPatch(requirement, version.id, addedBy),
+                });
               });
             }}
             onUnlink={(id) => {
               if (versionReadonly || !requirementWriteReady) return;
-              const requirement = requirements.find((item) => item.id === id);
+              const requirement = displayRequirements.find((item) => item.id === id);
               if (!requirement) return;
-              updateRequirement(id, getRequirementVersionUnlinkPatch(requirement));
+              updateRequirement(id, {
+                productId: requirement.productId,
+                ...getRequirementVersionUnlinkPatch(requirement),
+              });
             }}
             onCreateChange={(data) => {
               if (versionReadonly || !requirementWriteReady) return;
@@ -1039,7 +1048,10 @@ export default function VersionDetailPage() {
                   if (versionReadonly || !planWriteReady) return;
                   createPlan(data);
                   if ((pt === 'product') && data.linkedRequirementIds?.length) {
-                    data.linkedRequirementIds.forEach((rid) => updateRequirement(rid, { productOwner: data.owner }));
+                    data.linkedRequirementIds.forEach((rid) => {
+                      const requirement = displayRequirements.find((item) => item.id === rid);
+                      if (requirement) updateRequirement(rid, { productId: requirement.productId, productOwner: data.owner });
+                    });
                   }
                   // 同步版本状态：计划开始时间<=今天，版本进入对应阶段
                   const today = new Date().toISOString().slice(0, 10);
@@ -1052,7 +1064,10 @@ export default function VersionDetailPage() {
                   if (versionReadonly || !planWriteReady) return;
                   updatePlan(id, data);
                   if ((pt === 'product') && data.linkedRequirementIds && data.owner) {
-                    data.linkedRequirementIds.forEach((rid) => updateRequirement(rid, { productOwner: data.owner }));
+                    data.linkedRequirementIds.forEach((rid) => {
+                      const requirement = displayRequirements.find((item) => item.id === rid);
+                      if (requirement) updateRequirement(rid, { productId: requirement.productId, productOwner: data.owner });
+                    });
                   }
                 }}
                 onComplete={(id, result) => {

apps/web/app/versions/page.tsx

@@ -159,7 +159,9 @@ function VersionsPageContent() {
     setOpenMenuId(null);
     if (action === 'delete') {
       if (!confirm('确认删除该版本？关联的需求会回到需求池。')) return;
-      requirements.filter((r) => r.versionId === version.id).forEach((r) => updateRequirement(r.id, getRequirementVersionUnlinkPatch(r)));
+      requirements
+        .filter((r) => r.versionId === version.id)
+        .forEach((r) => updateRequirement(r.id, { productId: r.productId, ...getRequirementVersionUnlinkPatch(r) }));
       deleteVersion(version.productId, version.id);
       return;
     }

apps/web/lib/domain-api.ts

@@ -1,4 +1,6 @@
 import { api } from './api';
+import type { Priority } from './derive';
+import type { Requirement, RequirementStatus, SourceType } from './requirement';
 
 export interface RootProject {
   id: string;
@@ -89,6 +91,62 @@ export async function deleteVersionByProductId(productId: string, versionId: str
   await api.delete(`/products/${productId}/versions/${versionId}`);
 }
 
+interface DomainRequirementRow {
+  id: string;
+  productId: string;
+  projectId?: string | null;
+  versionId?: string | null;
+  code: string;
+  title: string;
+  description?: string | null;
+  status?: string | null;
+  priority?: string | number | null;
+  type?: string | null;
+  sourceType?: string | null;
+  sourceTarget?: string | null;
+  platform?: string | null;
+  creatorId?: string | null;
+  creatorName?: string | null;
+  creator?: { id?: string | null; name?: string | null } | null;
+  createdAt?: string | Date | null;
+}
+
+export async function createRequirementByProductId(
+  productId: string,
+  data: Partial<Requirement>,
+): Promise<Requirement> {
+  return normalizeRequirement(await api.post<DomainRequirementRow>(
+    `/products/${productId}/requirements`,
+    toRequirementPayload(data),
+  ));
+}
+
+export async function updateRequirementByProductId(
+  productId: string,
+  requirementId: string,
+  data: Partial<Requirement>,
+): Promise<Requirement> {
+  return normalizeRequirement(await api.patch<DomainRequirementRow>(
+    `/products/${productId}/requirements/${requirementId}`,
+    toRequirementPayload(data),
+  ));
+}
+
+export async function updateRequirementStatusByProductId(
+  productId: string,
+  requirementId: string,
+  status: RequirementStatus,
+): Promise<Requirement> {
+  return normalizeRequirement(await api.patch<DomainRequirementRow>(
+    `/products/${productId}/requirements/${requirementId}/status`,
+    { status },
+  ));
+}
+
+export async function deleteRequirementByProductId(productId: string, requirementId: string): Promise<void> {
+  await api.delete(`/products/${productId}/requirements/${requirementId}`);
+}
+
 function normalizeProductRoot(product: RootProduct): RootProduct {
   return {
     ...product,
@@ -108,3 +166,74 @@ function normalizeVersionRoot(version: RootVersion): RootVersion {
     links: version.links && typeof version.links === 'object' ? version.links : {},
   };
 }
+
+function toRequirementPayload(data: Partial<Requirement>) {
+  return {
+    ...(data.code !== undefined && { code: data.code }),
+    ...(data.title !== undefined && { title: data.title }),
+    ...(data.description !== undefined && { description: data.description }),
+    ...(data.projectId !== undefined && { projectId: data.projectId }),
+    ...(data.versionId !== undefined && { versionId: data.versionId ?? null }),
+    ...(data.typeId !== undefined && { type: data.typeId }),
+    ...(data.sourceType !== undefined && { sourceType: data.sourceType }),
+    ...(data.sourceTarget !== undefined && { sourceTarget: data.sourceTarget }),
+    ...(data.platforms !== undefined && { platform: data.platforms.join(',') }),
+    ...(data.priority !== undefined && { priority: priorityToNumber(data.priority) }),
+  };
+}
+
+function normalizeRequirement(row: DomainRequirementRow): Requirement {
+  return {
+    id: row.id,
+    code: row.code,
+    title: row.title,
+    description: row.description ?? '',
+    productId: row.productId,
+    projectId: row.projectId ?? '',
+    versionId: row.versionId ?? undefined,
+    sourceType: toSourceType(row.sourceType),
+    sourceTarget: row.sourceTarget ?? '',
+    platforms: splitCsv(row.platform),
+    typeId: row.type ?? '',
+    status: toRequirementStatus(row.status),
+    priority: toPriority(row.priority),
+    effort: 'M',
+    creator: row.creator?.name ?? row.creatorName ?? row.creatorId ?? '',
+    createdAt: isoString(row.createdAt),
+  };
+}
+
+function toSourceType(value: string | null | undefined): SourceType {
+  const allowed = new Set<SourceType>(['customer', 'internal', 'operation', 'aftersale', 'market', 'competitor', 'management']);
+  return allowed.has(value as SourceType) ? value as SourceType : 'internal';
+}
+
+function toRequirementStatus(value: string | null | undefined): RequirementStatus {
+  const allowed = new Set<RequirementStatus>(['pending_review', 'adopted', 'rejected', 'planned', 'developing', 'testing', 'released', 'closed']);
+  return allowed.has(value as RequirementStatus) ? value as RequirementStatus : 'pending_review';
+}
+
+function toPriority(value: string | number | null | undefined): Priority {
+  if (typeof value === 'string' && /^P[0-4]$/.test(value)) return value as Priority;
+  const parsed = Number(value ?? 2);
+  const normalized = Number.isFinite(parsed) ? Math.max(0, Math.min(4, Math.floor(parsed))) : 2;
+  return `P${normalized}` as Priority;
+}
+
+function priorityToNumber(value: Priority | undefined): number | undefined {
+  if (!value) return undefined;
+  const match = /^P([0-4])$/.exec(value);
+  return match ? Number(match[1]) : undefined;
+}
+
+function splitCsv(value: string | null | undefined): string[] {
+  if (!value) return [];
+  return value.split(',').map((item) => item.trim()).filter(Boolean);
+}
+
+function isoString(value: string | Date | null | undefined): string {
+  if (!value) return new Date().toISOString();
+  if (value instanceof Date) return value.toISOString();
+  const time = new Date(value).getTime();
+  return Number.isFinite(time) ? new Date(time).toISOString() : new Date().toISOString();
+}

apps/web/lib/requirement-domain-write-source.test.ts

@@ -0,0 +1,67 @@
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import test from 'node:test';
+
+const storeSource = () => readFileSync(join(process.cwd(), 'stores/useRequirementStore.ts'), 'utf8');
+const pageSource = () => readFileSync(join(process.cwd(), 'app/requirements/page.tsx'), 'utf8');
+
+function storeMethodBody(text: string, name: string) {
+  const start = text.indexOf(`    ${name}:`);
+  assert.notEqual(start, -1, `missing store method ${name}`);
+
+  let depth = 0;
+  let sawFirstBrace = false;
+  for (let i = start; i < text.length; i += 1) {
+    const char = text[i];
+    if (char === '{') {
+      depth += 1;
+      sawFirstBrace = true;
+    }
+    if (char === '}') {
+      depth -= 1;
+      if (sawFirstBrace && depth === 0) {
+        return text.slice(start, i + 1);
+      }
+    }
+  }
+
+  throw new Error(`could not extract store method ${name}`);
+}
+
+test('requirement store imports domain requirement write helpers', () => {
+  const text = storeSource();
+
+  assert.match(text, /from '@\/lib\/domain-api'/);
+  assert.match(text, /createRequirementByProductId/);
+  assert.match(text, /updateRequirementByProductId/);
+  assert.match(text, /deleteRequirementByProductId/);
+});
+
+test('requirement mutations use domain APIs instead of AppData requirements saves', () => {
+  const text = storeSource();
+  const createRequirement = storeMethodBody(text, 'createRequirement');
+  const updateRequirement = storeMethodBody(text, 'updateRequirement');
+  const deleteRequirement = storeMethodBody(text, 'deleteRequirement');
+
+  assert.match(createRequirement, /createRequirementByProductId\(newReq\.productId,/);
+  assert.match(updateRequirement, /updateRequirementByProductId\(productId, id,/);
+  assert.match(deleteRequirement, /deleteRequirementByProductId\(productId, id\)/);
+  assert.doesNotMatch(createRequirement, /saveServerData\('requirements'/);
+  assert.doesNotMatch(updateRequirement, /saveServerData\('requirements'/);
+  assert.doesNotMatch(deleteRequirement, /saveServerData\('requirements'/);
+});
+
+test('requirement pool uses server pagination without full AppData load for scoped list queries', () => {
+  const text = pageSource();
+
+  assert.match(text, /loadV22RequirementsPage\(v22RequirementQuery\)/);
+  assert.match(text, /if \(v22RequirementQuery && !v22RequirementsFailed\) return;\s+fetchRequirements\(\);/);
+});
+
+test('relation-backed requirement rows remain mutable without AppData identity', () => {
+  const text = pageSource();
+
+  assert.match(text, /const canMutateRequirement = \(req: Requirement\) => Boolean\(req\.productId\);/);
+  assert.doesNotMatch(text, /appDataRequirementIds\.has\(req\.id\)/);
+});

apps/web/stores/useRequirementStore.ts

@@ -3,6 +3,12 @@
 import { create } from 'zustand';
 import type { Requirement, RequirementStatus, Effort, DictItem, SourceType, SourceTarget } from '@/lib/requirement';
 import type { Priority } from '@/lib/derive';
+import {
+  createRequirementByProductId,
+  deleteRequirementByProductId,
+  updateRequirementByProductId,
+  updateRequirementStatusByProductId,
+} from '@/lib/domain-api';
 import { scheduleSaveWithOptimisticRollback } from '@/lib/optimistic-persistence';
 import { loadServerData, saveServerData, SERVER_DATA_CACHE_MS } from '@/lib/server-data';
 
@@ -16,7 +22,7 @@ interface RequirementState {
   fetchRequirements: (options?: { force?: boolean }) => Promise<void>;
   createRequirement: (data: Omit<Requirement, 'id' | 'code' | 'createdAt'>) => void;
   updateRequirement: (id: string, data: Partial<Requirement>) => void;
-  deleteRequirement: (id: string) => void;
+  deleteRequirement: (id: string, productId?: string) => void;
   addSourceTarget: (name: string, sourceType: SourceType) => void;
   updateSourceTarget: (id: string, name: string) => void;
   deleteSourceTarget: (id: string) => void;
@@ -99,7 +105,19 @@ export const useRequirementStore = create<RequirementState>((set, get) => {
       const updated = [...requirements, newReq];
       set({ requirements: updated, loaded: true });
       scheduleSaveWithOptimisticRollback({
-        save: () => saveServerData('requirements', { requirements: updated, sourceTargets, types, platforms }),
+        save: async () => {
+          try {
+            const created = await createRequirementByProductId(newReq.productId, newReq);
+            set({
+              requirements: get().requirements.map((item) => (
+                item.id === newReq.id ? { ...created, creator: newReq.creator || created.creator } : item
+              )),
+              loaded: true,
+            });
+          } catch {
+            await saveRequirementsFallback({ requirements: updated, sourceTargets, types, platforms });
+          }
+        },
         expected: updated,
         getCurrent: () => get().requirements,
         rollback: () => set({ requirements, loaded: true }),
@@ -108,22 +126,50 @@ export const useRequirementStore = create<RequirementState>((set, get) => {
 
     updateRequirement: (id, data) => {
       const { requirements, sourceTargets, types, platforms } = get();
+      const current = requirements.find((r) => r.id === id);
+      const productId = data.productId ?? current?.productId;
       const updated = requirements.map((r) => (r.id === id ? { ...r, ...data } : r));
       set({ requirements: updated, loaded: true });
       scheduleSaveWithOptimisticRollback({
-        save: () => saveServerData('requirements', { requirements: updated, sourceTargets, types, platforms }),
+        save: async () => {
+          try {
+            if (!productId) throw new Error('missing requirement productId');
+            const domainPatch = { ...data };
+            const status = domainPatch.status;
+            delete domainPatch.status;
+            delete domainPatch.productId;
+            delete domainPatch.productOwner;
+            delete domainPatch.addedToVersionBy;
+            if (hasDomainPatch(domainPatch)) {
+              await updateRequirementByProductId(productId, id, domainPatch);
+            }
+            if (status) {
+              await updateRequirementStatusByProductId(productId, id, status);
+            }
+          } catch {
+            await saveRequirementsFallback({ requirements: updated, sourceTargets, types, platforms });
+          }
+        },
         expected: updated,
         getCurrent: () => get().requirements,
         rollback: () => set({ requirements, loaded: true }),
       });
     },
 
-    deleteRequirement: (id) => {
+    deleteRequirement: (id, scopedProductId) => {
       const { requirements, sourceTargets, types, platforms } = get();
+      const productId = scopedProductId ?? requirements.find((r) => r.id === id)?.productId;
       const updated = requirements.filter((r) => r.id !== id);
       set({ requirements: updated, loaded: true });
       scheduleSaveWithOptimisticRollback({
-        save: () => saveServerData('requirements', { requirements: updated, sourceTargets, types, platforms }),
+        save: async () => {
+          try {
+            if (!productId) throw new Error('missing requirement productId');
+            await deleteRequirementByProductId(productId, id);
+          } catch {
+            await saveRequirementsFallback({ requirements: updated, sourceTargets, types, platforms });
+          }
+        },
         expected: updated,
         getCurrent: () => get().requirements,
         rollback: () => set({ requirements, loaded: true }),
@@ -245,3 +291,16 @@ export const useRequirementStore = create<RequirementState>((set, get) => {
     },
   };
 });
+
+async function saveRequirementsFallback(data: {
+  requirements: Requirement[];
+  sourceTargets: SourceTarget[];
+  types: DictItem[];
+  platforms: DictItem[];
+}) {
+  await saveServerData('requirements', data);
+}
+
+function hasDomainPatch(data: Partial<Requirement>) {
+  return Object.values(data).some((value) => value !== undefined);
+}

docs/superpowers/plans/2026-07-08-v24-domain-crud-migration.md

@@ -102,14 +102,14 @@
 - Produces: requirement create/update/delete/status/link APIs that write `requirements` directly by `(id, productId)`.
 - Produces: server-side list contract with `productId`, `projectId`, `versionId`, `status`, `priority`, `type`, `q`, `sort`, `cursor`, and `limit`.
 
-- [ ] Add failing backend tests for server pagination, search, filters, sort, cursor, and partition-key validation.
+- [x] Add failing backend tests for server pagination, search, filters, sort, cursor, and partition-key validation.
-- [ ] Add failing tests for create/update fields currently present in frontend requirements: `projectId`, `versionId`, `type`, `sourceType`, `sourceTarget`, and `platform`.
+- [x] Add failing tests for create/update fields currently present in frontend requirements: `projectId`, `versionId`, `type`, `sourceType`, `sourceTarget`, and `platform`.
-- [ ] Add failing frontend tests proving requirement pool calls server pagination and does not require loading the full AppData document for list/search/filter/sort.
+- [x] Add failing frontend tests proving requirement pool calls server pagination and does not require loading the full AppData document for list/search/filter/sort.
-- [ ] Implement service-side query parsing and safe order fields.
+- [x] Implement service-side query parsing and safe order fields.
-- [ ] Switch `useRequirementStore` create/update/delete/status/link writes to Requirement APIs.
+- [x] Switch `useRequirementStore` create/update/delete/status/link writes to Requirement APIs.
-- [ ] Keep AppData read fallback only when relation API is unavailable.
+- [x] Keep AppData read fallback only when relation API is unavailable.
-- [ ] Run targeted tests and full gates.
+- [x] Run targeted tests and full gates.
-- [ ] Commit: `feat(v2.4): 切换需求池领域主写`.
+- [x] Commit: `feat(v2.4): 切换需求池领域主写`.
 
 ### Task 4: V2.4.3 VersionPlan / DevTask Main Writes