wanzi/ftb-project-management
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
。
2026-07-08 12:18:15 +08:00
parent 142800f75b
commit 5f5a211c99
11 changed files with 602 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
apps/server/src/modules/requirement/dto/create-requirement.dto.ts
View File

@@ -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()
creatorId!: string;
@IsOptional()
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;
}

20
apps/server/src/modules/requirement/requirement.controller.ts
View File

@@ -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')

111
apps/server/src/modules/requirement/requirement.service.spec.ts
View File

@@ -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'],

146
apps/server/src/modules/requirement/requirement.service.ts
View File

@@ -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.PLANNED]: [RequirementStatus.DEVELOPING],
[RequirementStatus.ADOPTED]: [RequirementStatus.PLANNED, RequirementStatus.CLOSED],
[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 || '',
status: RequirementStatus.PENDING_REVIEW,
priority: dto.priority ?? 0,
creatorId: dto.creatorId,
description: dto.description ?? '',
status: dto.status ?? RequirementStatus.PENDING_REVIEW,
priority: parsePriorityValue(dto.priority) ?? 0,
},
});
}
findAll(productId: string, status?: string) {
return this.prisma.requirement.findMany({
async findAll(productId: string, query: RequirementListQuery = {}) {
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,
...(status ? { status } : {}),
productId: normalizedProductId,
...(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: {
...(dto.code !== undefined && { code: dto.code }),
...(dto.title !== undefined && { title: dto.title }),
...(dto.description !== undefined && { description: dto.description }),
...(dto.priority !== undefined && { priority: dto.priority }),
},
data: this.toRequirementData(dto),
});
}
@@ -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 };
}
}

19
apps/web/app/requirements/page.tsx
View File

@@ -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}
onDelete={canMutateRequirement(viewingReq) ? () => { deleteRequirement(viewingReq.id); 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, 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()}

29
apps/web/app/versions/[id]/page.tsx
View File

@@ -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) => {

4
apps/web/app/versions/page.tsx
View File

@@ -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;
}

129
apps/web/lib/domain-api.ts
View File

@@ -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();
}

67
apps/web/lib/requirement-domain-write-source.test.ts Normal file
View File

@@ -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\)/);
});

69
apps/web/stores/useRequirementStore.ts
View File

@@ -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);
}

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

@@ -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.
- [ ] 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.
- [ ] Implement service-side query parsing and safe order fields.
- [ ] Switch `useRequirementStore` create/update/delete/status/link writes to Requirement APIs.
- [ ] Keep AppData read fallback only when relation API is unavailable.
- [ ] Run targeted tests and full gates.
- [ ] Commit: `feat(v2.4): 切换需求池领域主写`.
- [x] Add failing backend tests for server pagination, search, filters, sort, cursor, and partition-key validation.
- [x] Add failing tests for create/update fields currently present in frontend requirements: `projectId`, `versionId`, `type`, `sourceType`, `sourceTarget`, and `platform`.
- [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.
- [x] Implement service-side query parsing and safe order fields.
- [x] Switch `useRequirementStore` create/update/delete/status/link writes to Requirement APIs.
- [x] Keep AppData read fallback only when relation API is unavailable.
- [x] Run targeted tests and full gates.
- [x] Commit: `feat(v2.4): 切换需求池领域主写`.
### Task 4: V2.4.3 VersionPlan / DevTask Main Writes