題材を掴む ＋ Claude Code の3操作

この演習の前に、講師と一緒に「システムの歩き方」で受注ステータスの遷移図と層構造を見て、ブラウザに出る生の JSON を一度眺めます。Eclipse からターミナルに移った初日にいちばん引っかかるのは、指示が届いているのか分からない状態です。ここで起動と応答を先に確かめておくと、あとの演習では提案の中身を読むことに時間を使えます。

ターミナルは2枚使います。1枚目はアプリを動かしっぱなしにする窓、2枚目は claude と話す窓です。1枚で兼ねると、アプリを止めるつもりで押した Ctrl+C で Claude Code のほうが終わります。2枚目はターミナル右上の＋（新しいターミナル）で開きます。Ctrl+@ が効かないときは、表示メニューのターミナルからでも開けます。アプリの初回起動は依存関係の取得に時間がかかるので、D1-1 の頭で先に走らせておくと後が楽です。

claude を初めて起動すると、配色の選択とフォルダを信頼するかの確認が出ます。どちらも Enter で進めて構いません。入力欄が出れば起動できています。

handson フォルダの直下には CLAUDE.md が置いてあり、技術スタック、コーディング規約、受注の業務ルールが書かれています。claude を起動するとこの内容が読み込まれるので、前提を毎回打ち直す必要はありません。遷移ルールを聞いて正しく返ってくれば、読み込まれている証拠になります。

層の説明は毎回同じ形では返りません。4つの層の名前が一度でそろわなくても、聞き直せれば十分です。応答が返らない、そもそも claude というコマンドが見つからないというときは、ターミナルの現在地が handson になっているかを最初に確かめてください。

この演習ではファイルを作りません。コードにも手を入れないので、終わったらそのまま D1-2 に進めます。入力欄で @ を打つとファイル参照の候補が出ます。D1-2 以降で使うので、時間が余ったら一度眺めておいてください。/ の一覧にはこのプロジェクト用の /review も並んでいます。コードを直したあとに打つと、規約と業務ルールに照らして見てくれます。

findByDateRange は、受注日が from から to の間に入る受注だけを取り出す検索です。配布時点では本体が例外を投げる一行だけになっていて、呼ぶと必ず止まります。

手がかりは2つあります。取り出す側はリポジトリにもう用意されていること、詰め替えのお手本が同じファイルの中にあることです。手順1で自分の答えを決めてから、OrderRepository と、すぐ上の findByStatus を開いて確かめてください。リポジトリのメソッドはメソッド名から SQL が組み立てられる仕組みなので、こちらで SQL を書く必要はありません。範囲の指定は両端を含むため、from と to に同じ日を入れてもその日の受注が取れます。

実装前に /api/orders/date-range を叩くと HTTP 400 が返ります。エンドポイントを足すと解消するので、400 が出ても手順どおり進めてください。

触るのは OrderServiceImpl の findByDateRange の本体と、OrderController に足す /date-range の2か所だけで、新しいファイルは作りません。Java の変更は動いているアプリには届かないので、確認の前に起動し直します。実装後に OrderController.java へ赤い波線が残ったら、java.time.LocalDate と org.springframework.format.annotation.DateTimeFormat の import を補ってください。OrderServiceImpl 側は LocalDate を最初から import しています。Claude Code に「足りない import を補って」と続けて頼んでも構いません。

動くところまで来たら、入力欄で /review と打ってみてください。このプロジェクト用のレビュー観点で、直したところを見てくれます。

src/main/resources/static は空です。フォルダごと見当たらないときは、Claude Code が作ってくれます。Spring Boot はこのフォルダに置いたファイルを http://localhost:8080/ファイル名 で配るので、dashboard.html を1枚置くだけで画面ができます。Java には触らない演習です。Planモードは計画を出すところで一度止まるので、Yes を選んで承認するまで dashboard.html は作られません。

アプリは起動したままで構いません。この配布物は動いているアプリが src/main/resources を直接読むので、dashboard.html を新しく置いてもブラウザを再読み込みするだけで出ます。中身を直したときも同じで、再読み込みだけで変わります。起動し直しが要るのは Java を直したときだけです。頼む、見る、直すを止めずに回してください。

この演習の軸になる API は、GET /api/orders と GET /api/orders/{id}、D1-2 で足した GET /api/orders/date-range の3本です。ほかに顧客名検索の /api/orders/search?customerName= とステータス検索の /api/orders/status/{status} も動いているので、余力があれば使ってください。D1-5 でステータス変更ボタンを足すときは、PATCH /api/orders/{id}/status を使います。

何が見たいかを決めずに「いい感じの画面を作って」と頼むと、返ってきたものを評価できません。評価できないものは直せないので、先に見たい形を決めておきます。この画面は D1-4 以降でも手を入れ続ける前提です。明細を返せるようにしたら明細欄、ステータス遷移を実装したら変更ボタンを、自分で足していってください。

完成度は問いません。表が出れば達成です。手が止まる人はプロンプトが長すぎることが多いので、短く言い直してください。ファイル名を変えると URL も変わるため、dashboard.html の名前のまま以降の演習でも使います。

GET /api/orders/1 を叩くと、受注番号も顧客名も合計金額も返るのに、明細の配列だけが返りません。データベースの order_items には13件の明細が入っていて、エンティティの Order も items を持っています。足りないのは外に出る側です。OrderDTO に明細のフィールドが無く、変換メソッドの fromEntity が明細に触れていません。

DTO は、返したい項目だけを詰め替えて外に出すための入れ物です。エンティティの OrderItem をそのまま返すと、データベースの持ち方がそのまま API の形になります。いまは親参照の order に @JsonIgnore が付いているので JSON の循環こそ止まりますが、LAZY の親参照や内部項目に外向きの形が引きずられます。だから明細専用の OrderItemDTO を新しく起こします。

D1-2 は既存メソッドの穴を埋める作業でした。ここはクラスを一枚まるごと新設して、関連ファイルも一緒に直す場面です。Planモードで計画を先に見てから承認してください。承認せずに直したい点を伝える操作も、ここで一度やっておきます。

作るのは src/main/java/com/example/order/dto/OrderItemDTO.java の1本、直すのは同じフォルダの OrderDTO.java です。どちらも Java なので、確認の前にアプリを起動し直します。返すフィールドは productCode、productName、quantity、unitPrice、subtotal の5つが目安になります。id=2 は L3スイッチと L2スイッチの明細を2件持つので、複数明細も合わせて確かめておくと安心です。

時間が余ったら、@src/main/resources/static/dashboard.html を対象に「行を開いたら明細を表示してください」と1行で頼み、自分の画面にも明細を出してください。こちらは HTML だけの変更なので、ブラウザの再読み込みだけで反映されます。

OrderServiceImpl の validateStatusTransition は、受注ステータスをある値から別の値へ変えてよいかを判定するメソッドです。配布時点では case Order.STATUS_CONFIRMED が SHIPPED への遷移しか許していないため、確定済みの受注をキャンセルできません。業務ルールでは PENDING と CONFIRMED からのキャンセルを認めます。出荷済み以降は認めません。モノが動いたのに帳簿だけ消える状態になるためです。

確認は PATCH /api/orders/{id}/status で行います。内部で validateStatusTransition が呼ばれるからです。PATCH /api/orders/{id}/cancel は cancelOrder という別のメソッドを呼ぶので、遷移ルールの確認には使いません。手順3で作るボタンも、押したときに叩くのは /status のほうです。

ステータス値は文字列の直書きではなく Order の定数を使います。綴り間違いをコンパイルの時点で見つけられるからです。

画面のボタンがうまく動かないときは、ターミナルから直接叩いても確かめられます。PowerShell なら Invoke-RestMethod -Method Patch -Uri http://localhost:8080/api/orders/2/status -ContentType "application/json" -Body (@{status="CANCELLED"} | ConvertTo-Json) の1行です。返ってきた status が CANCELLED になっていれば通っています。

配布データでは id=2 と id=3 が CONFIRMED、id=4 が SHIPPED で入っています。id=2 を一度 CANCELLED にすると遷移元が変わるので、やり直すときはアプリを起動し直してください。H2 はメモリ上で動くので、起動のたびに配布時の10件へ戻ります。

新しいファイルは作りません。編集は OrderServiceImpl.java の中と、自分のダッシュボードだけです。手順4で起動し直すのは OrderServiceImpl を直したためで、ボタンを足した HTML のほうは再読み込みだけで反映されます。ボタンの見た目や文言をあとから直すときは、起動したまま再読み込みで確かめてください。