135 lines
4.8 KiB
Markdown
135 lines
4.8 KiB
Markdown
# 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.
|