# 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:

```ts
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:

```ts
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:

```powershell
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**

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

Do not push unless the user explicitly asks.
