# 指示書E — `prisma/schema.prisma` を実DDLに一致させる

## 実行状態

| 項目 | 値 |
|---|---|
| **状態** | **実行済み** |
| 実行日 | 2026-09-03（`db pull` 実施日。`prisma/schema.prisma` 冒頭コメントに記載） |
| 実行コミット | **`d20be80`** — 実DDL(clean_watch_20260902.sql)へschema.prismaをdb pullで一致させる(D-050) |
| 取得した決定番号 | **D-058 / D-059** |

### ★実行状態についての注意★

この指示書は「これから実行する手順書」として書き起こしたものですが、
**作成時点（2026-09-03）で確認したところ、下記の手順1〜6の内容はすでに
`prisma/schema.prisma` と `docs/decisions.md` に反映されていました**
（作成中は未コミットの状態で、その後 `d20be80` としてコミットされました）。

確認できた事実:

- `prisma/schema.prisma` が **28モデル → 39モデル**（`git show HEAD:prisma/schema.prisma` は28）
- ファイル冒頭に「db pull 実施日: 2026-09-03 / 元DDL: `clean_watch_20260902.sql`」の注記あり
- `@updatedAt` の付け外しに「実DDL確認済み」コメントが3箇所（付けない）＋1箇所（付ける）
- Laravel 基盤テーブルの直前に区切りコメント（「ビューアーからは参照しない」）あり
- A-1 / A-2 / A-3 の確認待ちコメントが冒頭と各モデルに残っている
- `docs/decisions.md` に D-058 / D-059 が追記済み

**したがって、この指示書を再実行する必要はありません。**
内容を確認したい場合は `git show d20be80` を読んでください。

以下の手順は、**再度 DDL を受領して `db pull` をやり直すときのための手順書**として残しています。
そのときは実行状態の表を新しい実行分に更新してください。

---

## 目的

実DDL（`C:\Users\daich\Downloads\clean_watch_20260902.sql` / TeamWorks提供 / 受領 2026-09-02）
と手書き `prisma/schema.prisma`（28モデル）の間にある **差分49件** を解消します。

差分の全件と根拠は次の2ファイルにあります（**独立した2つの方法による照合結果**）:

- `docs/handoff/analysis/ddl-diff-dbpull.md` — `prisma db pull` による照合
- `docs/handoff/analysis/ddl-diff-parse.md` — DDL文の直接パースによる照合

> ★**1件ずつ手で当てると取りこぼします。**★ 49件のうち3件は定義書の誤記
> （`responsed_at`→`responded_at` / `sireal_number`→`serial_number`）、
> 8件は定義書にあって実DDLには無い廃止済みカラムです。
> **`db pull` の生成結果を採用する方式にしてください**（D-059）。

> ★`docs/handoff/指示書D_実装解析の不整合.md` と**同時に実行しないこと。**★
> 両方が `docs/decisions.md` の決定番号を取るため衝突します。

---

## 前提（ローカル検証環境）

- MySQL 8.4.9 / サービス名 `MySQL84`（自動起動）
- クライアント: `"C:\Program Files\MySQL\MySQL Server 8.4\bin\mysql.exe" -u root`（パスワードなし）
- `dwatch_ddl` … 実DDLを投入済み（**39テーブル**）。**`db pull` の入力元はこちら**
- `dwatch_local` … 手書きスキーマを `db push` したもの（28テーブル・空）。**触らない**
- Prisma 7 では `datasource` に `url` を書けない（`P1012`）。接続先は `prisma7.config.ts` が正。
  `db pull` に接続先を渡すときは **`--url` フラグ**を使う

---

## 手順

### 1. 作業前に `schema.prisma` の控えを取る

**`db pull` は対象ファイルを上書きします。** 先に控えを取ってください
（作業ツリーが clean なら `git stash` / `git show HEAD:prisma/schema.prisma` でも戻せますが、
**未コミットの変更がある状態では戻せません**）。

控えの置き場所は**リポジトリの外**にしてください（`docs/` に置くと成果物と混ざります）。

### 2. ★新規ファイルではなく、既存の `prisma/schema.prisma` に対して `db pull` を実行する★

```
npx prisma db pull --schema prisma/schema.prisma --url "<dwatch_ddl への接続URL>"
```

**理由:** 再イントロスペクション（enrich）は、**既存のモデル名と `@@map` を引き継ぎます。**
新規ファイルへ生成すると**モデル名が snake_case になり、PascalCase の命名規約が失われます。**

- `--force` は**付けないこと**（付けると enrich が働かず、既存の命名が捨てられます）
- `--print` で新規ファイルへ出す方式も**取らないこと**（同じ理由）

期待される結果: 既存28モデルは名前と `@@map` が維持されたまま enrich され、
**11モデルが新規に取り込まれる**（`clean_link_schedules` ＋ Laravel 基盤10テーブル）→ 合計39モデル。

### 3. `db pull` が出力しないものを手で戻す

`db pull` は **Prisma 固有の属性とコメントを出力しません。** 次の3つを戻します。

#### 3-1. `@updatedAt`

`@updatedAt` は Prisma 固有の属性なので `db pull` は出しません。
**DDL の `ON UPDATE CURRENT_TIMESTAMP` の有無で判断します。**

> ★**DDL を自分で grep して確認してください。**★ 推測で付けないこと。
>
> ```
> grep -n "ON UPDATE CURRENT_TIMESTAMP" clean_watch_20260902.sql
> ```
>
> テーブル定義のどのブロックに属する行なのかを、`CREATE TABLE` の位置と突き合わせて確認します。

- **3件は付けてはいけません**（`updated_at` に `ON UPDATE CURRENT_TIMESTAMP` が無いテーブル）
- **1件は付け漏れです**（`ON UPDATE CURRENT_TIMESTAMP` があるのに手書き版で付いていなかった）

判断した結果は、**その場にコメントで残してください**（次に `db pull` した人が同じ grep を
やり直さずに済むように）。作業ツリーの現物では次の形で残っています:

```prisma
// 実DDL確認済み: updated_at に ON UPDATE CURRENT_TIMESTAMP が無いため @updatedAt は付けない
```

`@default(now())` も同様に `db pull` の出力と DDL の `DEFAULT CURRENT_TIMESTAMP` を
突き合わせて確認すること（両方無いテーブルは INSERT 時に値を渡す必要があるため、
その旨をコメントに書く）。

#### 3-2. 確定した注記コメント

D-057 で TeamWorks から回答済みの項目（A-1 / A-2 / B-1〜B-6）は、
**「TeamWorks へ確認中」ではなく確定内容に書き換えてください。**
回答が来ていない項目だけを「確認中」として残します（手順5）。

#### 3-3. 冒頭コメント

**D-056 に従い**、ファイル冒頭に次を書きます。

- **`db pull` を実施済みである旨**（以後 DB 由来の事実は `db pull` の生成結果を正とし、手で書き換えない）
- **元DDLのファイル名と日付**（`clean_watch_20260902.sql` / 受領 2026-09-02 / `db pull` 実施 2026-09-03）
- 投入先のローカルDB名（`dwatch_ddl`）
- **`db pull` はコメントを保持しないため、再実行時はこのコミットの diff を見ながらコメントを移植し直す**旨
- 命名の経緯（既存28モデルは enrich で PascalCase + `@@map` を維持。新規11モデルは既定命名）

### 4. ★Laravel 基盤10テーブルを削除しないこと★

`users` / `sessions` / `jobs` / `migrations` / `cache` / `cache_locks` / `failed_jobs` /
`job_batches` / `password_reset_tokens` / `personal_access_tokens`

**削除すると `db pull` のたびに再追加され、本当の変更が差分ノイズに埋もれます。**

**→ 末尾にまとめ、区切りコメントを付けて「参照しない」と明記します。**
作業ツリーの現物では次の形です:

```prisma
// ============================================================================
// 以下は Laravel 基盤のテーブル。ビューアーからは参照しない。
// db pull の差分をきれいに保つために残している（削除すると毎回再追加される）
// ============================================================================
```

`clean_link_schedules` も同様に**削除せず**、モデル直上に不使用の旨をコメントで書きます（D-058）。

### 5. 確認待ち3件にコメントを残す

回答が来ていない項目を、**冒頭の「TeamWorks へ確認中の項目」一覧と、各該当モデルの両方**に
書きます（片方だけだと見落とします）。

| # | 内容 | 止まるもの |
|---|---|---|
| **A-1** | `robot_error_reports` に **PRIMARY KEY が無い**（UNIQUE は `error_id` のみ）。API が返す ID を `id` と `error_id` のどちらにするか | `PATCH /prechecks/{id}/status` の設計 |
| **A-2** | `clean_status_histories` / `clean_timetable_histories` の `id` が **AUTO_INCREMENT でない**。誰が採番するか（元テーブルの id を引き継ぐ設計か） | シードデータ |
| **A-3** | `customer_contacts.contact_type`（bigint unsigned）と `facility_contacts.contact_type`（tinyint unsigned）、`email`（varchar(100) / varchar(255)）の**型・サイズが食い違ったまま**。D-057 の B-6 回答で揃える予定だったが**現行DDLに未反映**。当面は現行DDLに合わせてよいか | スキーマの確定 |

### 6. 決定事項2件を記録する

`docs/decisions.md` に次の2件を追記します。

1. **`clean_link_schedules` は参照しない**（`link_schedules` を使う）
   — 実DDLで `link_schedules` と完全に同一構造であることが判明。`table_options` に
   `AUTO_INCREMENT=` の記載が無く一度も行が挿入されていない。TeamWorks より不要と確認済み
2. **以後 `schema.prisma` は実DDLを正とし、`db pull` の生成結果を採用する**
   — 定義書には誤記・廃止済み項目が含まれることが実証されたため。1件ずつの手当てはしない

> ★**番号を決め打ちしないこと。**★ 追記の直前に `docs/decisions.md` の最終番号を
> 確認してから振ってください（衝突歴あり）。
> 作業ツリーの現物では **D-058 / D-059** になっています。

---

## ★やらないこと★

**次のものはこの指示書の範囲外です。手を付けないでください。**

| 対象 | 理由 |
|---|---|
| **`d-watch-api.yaml` の変更** | API 契約の変更は別作業。スキーマ確定だけを先に済ませる |
| **`lib/types/index.ts` の変更** — 特に **`PrecheckItem.id` を `number` から `string` に変えたくなる**（実DDLは `varchar(50)`） | ★**A-1 の回答待ち。**★ どちらを ID にするかが決まる前に型を動かすと、回答後にもう一度直すことになる |
| **`prismaSource` の実装** | DB 接続層の実装は次の工程。スキーマが固まってから |
| **シードデータ** | ★**A-2 の回答待ち。**★ 履歴テーブルの id を誰が採番するか不明では作れない |
| **`dwatch_local` への `db push`** | 照合が目的なので不要。**`dwatch_local` は空のまま保つ**（シード投入先として使う予定） |
| `docs/handoff/指示書D_実装解析の不整合.md` の範囲 | 決定番号が衝突する。順番に実行する |

---

## 完了条件

1. `prisma/schema.prisma` が39モデルで、既存28モデルの PascalCase + `@@map` が維持されている
2. `npx prisma validate` が通る
3. `@updatedAt` の付け外しが DDL の `ON UPDATE CURRENT_TIMESTAMP` と一致し、
   判断根拠がコメントで残っている
4. 冒頭コメントに `db pull` 実施日・元DDLのファイル名・日付がある
5. Laravel 基盤10テーブルと `clean_link_schedules` が残り、「参照しない」と明記されている
6. 確認待ち3件（A-1 / A-2 / A-3）のコメントがある
7. `docs/decisions.md` に決定2件が記録されている（★番号は追記直前に確認★）
8. `npx tsc --noEmit` がエラー0 / `npm test` のテスト数が**減っていないこと**
9. 検証が通ったら**即コミット**（D-050）