fix: Double-submit could throw an uncaught unique constraint violation (#943)

Author: KATO-Hiro

.claude/rules/prisma-db.md

@@ -45,3 +45,24 @@ paths:
 
 - Use `prisma.$transaction()` for multi-step operations
 - Handle errors with try-catch and proper rollback
+
+## Idempotent Writes
+
+- Prefer `createMany({ skipDuplicates: true })` over try-catching P2002 when a unique constraint violation is expected (e.g., double-submit race condition). It maps to `INSERT ... ON CONFLICT DO NOTHING` and keeps intent clear.
+- Constraints: top-level `createMany` only (not nested); PostgreSQL, CockroachDB, SQLite only.
+
+## Validate Constraints
+
+Prisma does not support `@@check` in `schema.prisma`. To add a validate constraint:
+
+1. Run `pnpm exec prisma migrate dev --create-only --name <description>` to generate the migration file without applying it
+2. Edit the generated `migration.sql` to add the validate constraint manually
+3. Run `pnpm exec prisma migrate dev` to apply
+
+After adding a validate constraint, add a comment to `docs/erd.md` under the relevant entity:
+
+```
+%% XOR constraint: workbookplacement_xor_grade_category — exactly one of taskGrade or solutionCategory must be non-null
+```
+
+This is the only place validate constraints are visible, since Prisma omits them from `schema.prisma`.

docs/dev-notes/2026-02-28/workbook-order/plan.md

@@ -120,6 +120,7 @@ XOR 制約は `prisma migrate dev --create-only` で migration ファイルを
 
 - バリデーションループに DB 呼び出しが入ったら N+1 を疑い、`findMany({ where: { id: { in: ids } } })` + `Map` パターンに置き換える
 - Prisma enum とアプリ enum は構造が同じでも TypeScript は別型として扱う。キャストが必要な箇所を残すこと
+- ダブルサブミットなどレースコンディションによる unique 制約違反は `try-catch` で P2002 を握りつぶすより `createMany({ skipDuplicates: true })` で冪等な書き込みを DB に委ねる。PostgreSQL/CockroachDB/SQLite のみ対応・nested createMany 不可に注意
 
 ### Svelte 5
 
@@ -150,10 +151,6 @@ XOR 制約は `prisma migrate dev --create-only` で migration ファイルを
 
 | 教訓                                  | 一般化先                             | ステータス |
 | ------------------------------------- | ------------------------------------ | ---------- |
-| `redirect()` vs `error()` の使い分け  | `.claude/rules/auth.md`              | 実装済み   |
-| features テスト配置コロケーション     | `AGENTS.md` Project Structure        | 実装済み   |
-| DB CHECK 制約 → ERD.md コメント       | `.claude/rules/prisma-db.md`         | 実装済み   |
-| スキル CLI コマンドの事前動作確認     | `.claude/rules/skills.md`（新規）    | 実装済み   |
 | `try/finally` クリーンアップ          | `.claude/rules/testing.md`           | 検討中     |
 | `z.number().int()` 整数バリデーション | `.claude/rules/testing.md`           | 検討中     |
 | `onpointerdown` も止める（DnD）       | `.claude/rules/svelte-components.md` | 検討中     |

src/features/workbooks/services/workbook_placements.test.ts

@@ -214,6 +214,17 @@ describe('createInitialPlacements', () => {
     const callArg = vi.mocked(prisma.workBookPlacement.createMany).mock.calls[0][0];
     expect(callArg?.data).toHaveLength(4); // 2 curriculum + 2 solution
   });
+
+  test('calls createMany with skipDuplicates to tolerate concurrent double-submit', async () => {
+    mockWorkBookFindManyOnce(unplacedCurriculumRows);
+    mockWorkBookFindManyOnce(unplacedSolutionWorkbooks);
+    vi.mocked(prisma.workBookPlacement.createMany).mockResolvedValue({ count: 4 });
+
+    await createInitialPlacements();
+
+    const callArg = vi.mocked(prisma.workBookPlacement.createMany).mock.calls[0][0];
+    expect(callArg?.skipDuplicates).toBe(true);
+  });
 });
 
 describe('buildTaskMapFromCurriculumRows', () => {

src/features/workbooks/services/workbook_placements.ts

@@ -89,6 +89,7 @@ export async function createInitialPlacements(): Promise<void> {
 
   await prisma.workBookPlacement.createMany({
     data: [...curriculumPlacements, ...solutionPlacements],
+    skipDuplicates: true,
   });
 }