docs(v2.3): 记录关系表写入闭环方案

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

@@ -0,0 +1,79 @@
+# 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): 完成关系表写入闭环`.
+