第2章：この教材のゴールと“全体の地図”を先に見よう 🗺️✨

この章のゴール 🎯💡

この章が終わったら、次の3つが言えるようになります😊✨

何を作る教材なのか（題材）🎓🧩
どこにACL（腐敗防止層）が入るのか（地図）🧼🛡️
最終的に「できあがる形」がどんな状態か（ゴールの定義）✅🏁

1) 何を作るの？：外部APIを2つ使う“学内ミニアプリ” 🎓📲✨

題材は 「学食ポイント」アプリ（小さなバックエンドAPI）」 にします🍱💳 やることはシンプル！

学生の現在ポイントを表示する 👀✨
チャージ（支払い）してポイントを増やす ➕💰
そのために 外部APIを2つ 呼ぶ 🌍🔌

2) 外部APIは2つ：それぞれ“クセが強い”想定 😇🌀

外部API①：学生情報API（Student Directory）🧑‍🎓📘

返ってくるJSONの名前が独特（古い命名とか略語とか）🧾💦
型がふわっとしてる（数字なのに文字列とか）🔢➡️🔤
区分コードが謎（"1" が何か分からん…）👻

例（外部DTOのイメージ）👇

{
  "stu_id": "A001234",
  "stu_kbn": "1",
  "nm_kanji": "山田 花子",
  "pt": "1200"
}

外部API②：決済API（Payment）🏦⚡

エラー仕様が細かい（コード値が多い）🧨
「成功したけど注意」みたいな返し方をすることもある💦
タイムアウトやリトライの判断が必要になる🌩️🔁

例（外部DTOのイメージ）👇

{
  "result": "NG",
  "err_cd": "P402",
  "message": "Limit exceeded"
}

3) いちばん大事な最終ゴール：外部DTOが内側に漏れない ✅🧼🧱

この教材の“卒業条件”はこれ！🎓✨

アプリの中心（ドメイン＆ユースケース側）は、自分たちの言葉（型）だけで動く📘✨
外部のクセ（変な命名・謎コード・null・文字列数値…）は、境界で吸収して終わり🧽🚪
外部が仕様変更しても、壊れる範囲が ACLの周辺に閉じる🛡️🔒

4) どこにACLが入る？：内側／外側／境界の“地図” 🧭📦🚪

イメージはこんな感じです👇 （※ACLは「通訳＋防波堤」だよ🗣️🛡️）

イメージ：内側・外側・境界の地図

┌───────────────────────────────┐
│            内側（自分の世界）📘✨            │
│  Domain（ルール） + UseCase（やりたい事）   │
│     ↑ ここは「自分の言葉」だけを使う！       │
└───────────────┬───────────────┘
                │（境界）🚪
                ▼
┌───────────────────────────────┐
│     ACL（腐敗防止層）🧼🛡️                    │
│  - 外部DTO → ドメイン型に変換（翻訳）🔁       │
│  - パース/検証（信用しない）🧽✅              │
│  - 外部エラー → 内側向けに翻訳 🧊🔥           │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│            外側（相手の世界）🌍🌀            │
│   学生情報API（クセ強） / 決済API（クセ強）  │
└───────────────────────────────┘

5) 最終成果物の“完成形”はこれ！📦✨

出来上がるプロジェクトは、ざっくりこういう分かれ方になります👇🧩

domain/：ポイントや学生の「ルールと言葉」だけ💎
application/：ユースケース（例：ポイント照会、チャージ処理）🧠
infrastructure/external/：外部APIクライアント（HTTP呼ぶだけ）🌍
infrastructure/acl/：DTO→ドメイン変換、検証、エラー翻訳🧼🛡️
tests/：変換と境界のテストが強い！🧪🔥

6) 20章の“地図”を、先にざっくり4つの旅に分けるよ 🧳✨

細かい章立てはあるけど、進み方はこの4ステップが超わかりやすいです😊🌈

土台づくり（環境・題材・境界の考え方）🧰🚪
内側の言葉づくり（Entity/VO・不変条件）📘🔒
ACLづくり（変換・パース・検証・エラー翻訳）🧼🔁✅
テストで守る（変換テスト・異常系・外部変更検知）🧪🚨

7) 生成AIの使い方も、最初に“役割分担”しておく 🤖🧠✨

VS CodeのCopilot Chatは「質問する」「編集させる」みたいに使い分けできるよ💬✍️ （VS Codeのチャット機能や、会話しながら編集するEditモードの説明は公式にもあるよ） (Visual Studio Code)

この教材でのおすすめ使い分け👇✨

理解の補助：知らない用語をやさしく言い換えてもらう📚🙂
下書き生成：変換関数やテストケースのたたき台を作る🧪📝
レビュー相棒：境界を破ってないかチェック観点を出す🔍✅

さらに、VS Code側には「コーディングエージェント」に作業を委任する導線も用意されてるよ（機能修正を任せてPRで受け取る、みたいな） (Visual Studio Code) ※ただし、最終判断は人間が必ずレビューね👀🛡️✨

8) “外部DTOが内側に漏れてない”セルフチェック ✅🔒

最後に、ゴールの判定基準をチェックリスト化しとくよ📋✨

内側（domain/application）で 外部DTOの型名が一切出てこない ✅
外部APIのレスポンス形式が変わったら、ACLのテストが先に落ちる ✅
変換時に、未知コード／欠損／型ズレを握りつぶさず扱える ✅
ドメインの不変条件（例：ポイントは0以上）を 入口で守れてる ✅

ちょい最新メモ（教材に関係する“今どき事情”）🆕✨

Node.jsは v24がActive LTSとして扱われていて、安定運用の基準にしやすいよ🟢 (nodejs.org)
TypeScriptは 5.9系が安定版ラインとして確認できるよ（公式リリース一覧）🟦 (GitHub)
TypeScriptは6.0/7.0（ネイティブ化含む）の話も進んでるけど、教材ではまず「今すぐ使える安定ライン」で設計力を身につけるのが安全👌✨ (Microsoft for Developers)
VS Codeは月次で更新されていて、直近の更新情報も公式ノートで追えるよ📝✨ (Visual Studio Code)

この章のゴール 🎯💡​