Fork: 0
develop / client_dwatch
Transfer to URL with SHA Find file
Newer
Older
client_dwatch / docs / handoff / 指示書E_スキーマを実DDLに一致.md
@DFA-takeuchi DFA-takeuchi 20 days ago 12 KB D-Watch ソース一式（GitHub DFARobotics/d-watch の develop f07f7bf 時点のスナップショット。履歴なし）
Raw Blame History

指示書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 を やり直さずに済むように）。作業ツリーの現物では次の形で残っています:

// 実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 のたびに再追加され、本当の変更が差分ノイズに埋もれます。

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

// ============================================================================
// 以下は 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）