ftb-project-management/docs/superpowers/plans/2026-07-03-v23-relational-writes.md

V2.3 Relational Writes 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: Complete the V2.3 write-side bridge so AppData saves keep V2.2 relation-table read paths fresh and observable.

Architecture: Add a focused sync service behind DataService.put() that reuses the V2.2 mapper, syncs only affected relation tables, marks Xiaobao summaries dirty when risk inputs change, and logs sync failures without blocking AppData saves. Add lightweight NestJS and Prisma timing logs with environment-configurable thresholds.

Tech Stack: NestJS, Prisma, PostgreSQL partitioned tables, Jest, TypeScript, existing AppData JSONB compatibility layer.

---

Task 1: AppData Write Hook

Files:

• Modify: apps/server/src/modules/data/data.service.spec.ts

• Modify: apps/server/src/modules/data/data.service.ts

• Modify: apps/server/src/modules/data/data.module.ts

• Modify: apps/server/src/modules/migration/migration.module.ts

• Add tests proving DataService.put() calls the sync service only after successful create/update/upsert.

• Add tests proving stale version conflicts and create races do not trigger sync.

• Add tests proving sync errors are logged and AppData responses still return success.

• Inject AppDataV23SyncService into DataService as an optional dependency for tests.

• Import MigrationModule from DataModule.

Task 2: Relation Sync Service

Files:

• Create: apps/server/src/modules/migration/app-data-v23-sync.service.spec.ts

• Create: apps/server/src/modules/migration/app-data-v23-sync.service.ts

• Modify: apps/server/src/modules/migration/app-data-v22.migration.service.ts

• Modify: apps/server/src/modules/migration/migration.module.ts

• Add tests for requirement sync by productId scope.

• Add tests for version detail tables by versionId scope: plans, dev tasks, test cases, and bugs.

• Add tests for snapshot-driven Xiaobao summary refresh.

• Add tests for risk-input dirty marking.

• Implement syncAfterAppDataPut(key) by loading current AppData snapshot, mapping with mapAppDataToV22Rows(), normalizing date fields, and writing affected delegates in a transaction.

• Export the sync service from MigrationModule.

Task 3: Lightweight Monitoring

Files:

• Create: apps/server/src/common/interceptors/api-timing.interceptor.spec.ts

• Create: apps/server/src/common/interceptors/api-timing.interceptor.ts

• Create: apps/server/src/prisma/prisma-monitoring.ts

• Create: apps/server/src/prisma/prisma-monitoring.spec.ts

• Modify: apps/server/src/prisma/prisma.service.ts

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

• Add tests for timing threshold parsing and slow request logging.

• Add tests for Prisma slow query threshold parsing.

• Register ApiTimingInterceptor globally with APP_INTERCEPTOR.

• Configure PrismaService query event logging without changing connection lifecycle.

Task 4: Documentation

Files:

• Modify: docs/architecture.md

• Modify: docs/decisions.md

• Modify: docs/roadmap.md

• Document V2.3 write-side bridge in architecture.

• Add a decision for non-blocking AppData-to-relation sync and Xiaobao dirty summaries.

• Move roadmap current stage from V2.2 completion to V2.3 completion.

Task 5: Verification And Commit

Commands:

• pnpm --filter server type-check

• pnpm --filter server exec prisma validate --schema prisma/schema.prisma

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

• pnpm --filter web type-check

• pnpm --filter web test

• Run all verification commands.

• Commit with feat(v2.3): 完成关系表写入闭环.