ftb-project-management/docs/superpowers/plans/2026-07-03-v22-performance-hot-path.md

V2.2 Performance Hot Path Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Finish V2.2 by moving high-volume read paths from full AppData document scans to partition-key-scoped relation-table queries, with safe AppData fallback for existing writes.

Architecture: Backend exposes read-optimized V2.2 query endpoints for version detail, requirement pool, workspace, and Xiaobao warning summary data. Frontend adds a single mapping layer that converts Prisma-shaped rows into the existing UI types, then pages consume that layer first and fall back to the existing Zustand/AppData stores when the relation tables are unavailable or empty.

Tech Stack: Next.js 14 App Router, Zustand, NestJS, Prisma, PostgreSQL partitioned tables, node:test, Jest.

---

Task 1: Frontend V2.2 API Mapping

Files:

• Create: apps/web/lib/v22-api.ts

• Create: apps/web/lib/v22-api.test.ts

• Step 1: Write the failing test

Add apps/web/lib/v22-api.test.ts with tests that mock fetch, call loadV22VersionDetailData('version-1'), and assert:

assert.equal(calls[1].url.endsWith('/v2.2/versions/version-1/detail-data'), true);
assert.equal(result.scope.requirements[0].typeId, 'feature');
assert.deepEqual(result.scope.requirements[0].platforms, ['web', 'ios']);
assert.equal(result.scope.devTasks[0].taskNo, 'DEV-001');
assert.equal(result.scope.devTasks[0].actualStartAt, '2026-01-02T09:00:00.000Z');
assert.equal(result.scope.testCases[0].caseNo, 'TC-001');
assert.equal(result.scope.bugs[0].bugNo, 'BUG-001');
assert.equal(result.scope.plans[0].owner, 'member-1');
assert.equal(result.scope.plans[0].startTime, '2026-01-01T00:00:00.000Z');

• Step 2: Run test to verify it fails

Run: pnpm --filter web test

Expected: FAIL because apps/web/lib/v22-api.ts does not exist.

• Step 3: Implement minimal mapping layer

Create apps/web/lib/v22-api.ts exporting:

loadV22VersionDetailData(versionId: string)
loadV22RequirementsPage(query)
loadV22WorkspaceData(userId: string)
loadV22XiaobaoWarnings(query)

The mapper must convert priority: number to P0-style priorities, platform CSV to platforms[], code to taskNo/caseNo/bugNo, ownerId to owner, and date-like values to ISO strings.

• Step 4: Run test to verify it passes

Run: pnpm --filter web test

Expected: PASS.

Task 2: Version Detail Hot Path

Files:

• Modify: apps/web/app/versions/[id]/page.tsx

• Step 1: Write or extend testable helper first

Use Task 1 mapping tests as the behavior guard for the data shape consumed by the page.

• Step 2: Replace full child-data fetches for read-heavy render

In apps/web/app/versions/[id]/page.tsx, load loadV22VersionDetailData(versionId) in an effect. Use its returned scope for overview, requirement, plan, dev-task, test-case, and bug tab props when available. Keep the existing stores loaded for overview, members, categories, overtime, drawers, and mutations.

• Step 3: Keep fallback behavior

If the V2.2 request fails or returns an empty relation scope, keep using buildVersionDataScope(...) from AppData stores.

• Step 4: Verify

Run: pnpm --filter web type-check and pnpm --filter web test.

Expected: both exit 0.

Task 3: Backend And Migration Verification

Files:

• Already modified: apps/server/src/modules/migration/*

• Already created: apps/server/src/modules/v22-query/*

• Modify if needed: apps/server/src/app.module.ts

• Step 1: Verify Prisma schema

Run: pnpm --filter server exec prisma validate --schema prisma/schema.prisma

Expected: schema validates.

• Step 2: Verify backend types and tests

Run: pnpm --filter server type-check

Run from apps/server: $env:NODE_OPTIONS='--max-old-space-size=4096'; .\node_modules\.bin\jest.CMD --runInBand

Expected: both exit 0.

Task 4: Documentation And Commit

Files:

• Modify: docs/architecture.md

• Modify: docs/roadmap.md

• Step 1: Document V2.2 completion boundary

Update docs to say V2.2 relation tables, import execution, read query API, and version-detail frontend hot path are complete. State that writes still go through AppData during the compatibility window.

• Step 2: Final verification

Run:

pnpm --filter web type-check
pnpm --filter web test
pnpm --filter server type-check
pnpm --filter server exec prisma validate --schema prisma/schema.prisma

Run full backend Jest from apps/server.

• Step 3: Commit locally

git add apps/server apps/web docs
git commit -m "feat(v2.2): 完成高频读取热路径"

Do not push unless the user explicitly asks.