第5章：題材紹介：学内アプリ（例）と外部APIの“クセ”を確認 🎓🧾✨

5.0 この章でやること（今日のゴール）🎯💕

この章は「ACLを作る前の下準備」だよ〜！😺✨ 外部APIって、だいたい“クセ強”です😂💦 そのクセを 先に見える化 しておくと、ACL（翻訳＋防波堤🛡️🌊）が作りやすくなるの💡

題材（学内アプリ）をサクッと理解🍱🎓
外部APIが持ってる「クセ」を 種類ごとに分類 📝🔍
後の章で使うために「クセ台帳（クセの一覧表）」を作る📚✨

5.1 題材：学食ポイントアプリ（ミニ）🍱📱✨

何をするアプリ？🤔

「学生が学食を買うときに、ポイントを使ったり貯めたりできる」アプリだよ〜！🧡 （小さく作るから安心してね☺️）

**このアプリの“内側のルール”（ドメイン）**は、ざっくりこんな感じ👇

学生（Student）は学生IDを持つ🪪✨
ポイント（Point）は 0以上📌🔒
支払い（Payment）は「成功/失敗」がはっきりしてる💳✅❌
“学内の言葉”で統一したい（学生区分とか、表示名とか）📘✨

5.2 外部APIは2つ：学生情報と決済 🧑‍🎓🔍 + 💳🏦

この教材では「外側（外部API）」が2つある想定で進めるよ😺✨ **大事なのは、外側の都合を内側へ持ち込まないこと！**🧼🧱

A) 学生情報API（Student Directory）🧑‍🎓📚

学生の基本情報を取れる（所属、区分、表示名など）
でも古いシステムで、命名が独特…👻

B) 決済API（Payment）💳🏦

チャージ/支払いの実行（成功・失敗）
エラー仕様が細かい＆厳しめ…😇💦

なお、HTTP取得は fetch() を使うよ（WebでもNodeでも同じ感覚で書けるやつ！）🕸️✨ Fetch API自体の考え方はMDNがわかりやすいよ📘 (MDNウェブドキュメント) Node側でも fetch を使える流れになってる（仕組みは Undici が支えてる）🚀 (Node.js)

5.3 “クセ”ってなに？（外部APIあるある）😈🌀

外部APIのデータって、だいたいこういう“クセ”があるよ〜😂

イメージ：外部APIのクセたち（データモンスター）

よくあるクセ一覧（チェック項目）✅📝

命名が独特：stu_kbn とか pt_bal とか…何それ!?😵
コード値が謎："1"|"2"|"9" みたいな「意味不明な数字」🔢👻
欠損（null/空文字/省略）：あると思ってた項目が無い😇
型がゆらぐ：数値のはずが文字列 "100" で来る😵‍💫
単位が違う：円なの？銭なの？ポイントは整数？小数？💴🧮
日時がクセ強："2026/01/29 09:10" みたいな形式バラバラ⏰🌀
仕様が変わる：項目追加・名称変更・意味変更が突然来る💥
エラーが独自：HTTP 200なのに本文が {"ok":false} とか😇

この章では、この“クセ”を実データで確認して、台帳にまとめるよ🗃️✨

5.4 サンプルで“クセ”を体感しよう（外部レスポンス例）👀📦

ここからは「外部がこういう形で返してくる（例）」を見て、クセを洗い出すよ〜！🔍✨ （※例だから、気楽に読んでね☺️）

A) 学生情報API：レスポンス例 🧑‍🎓📦

{
  "stu_id": "A0123456",
  "stu_kbn": "2",
  "dept_cd": "04",
  "disp_nm": "ｺﾐﾔﾏ ﾏｻﾋﾛ",
  "birth": "2004/7/3",
  "enroll_ymd": "2020-04-01",
  "email": "",
  "flags": {
    "pay_lock": "0",
    "vip": null
  }
}

この時点で見えるクセ👇😂

stu_kbn / dept_cd：コード値っぽい🔢👻
disp_nm：半角カナ混じり（表示名としてそのまま使いたくない）😵
birth：日付形式が統一されてない（2004/7/3）🗓️🌀
email：空文字（nullじゃない）📭😇
vip：null（型がゆらぐ可能性）🌀

B) 決済API：成功レスポンス例 💳✅

{
  "result": "OK",
  "auth_id": "P-9f8a1d",
  "amount": 550,
  "currency": "JPY",
  "processed_at": "2026-01-29T09:10:12+09:00"
}

クセ候補👇

result が "OK"（enum化したくなる）✅🔤
processed_at はISOっぽい（これは比較的良い子）😺✨

C) 決済API：失敗レスポンス例 💳❌

{
  "result": "NG",
  "error": {
    "code": "E102",
    "message": "INSUFFICIENT_BALANCE",
    "retryable": false
  }
}

クセ候補👇

E102 と INSUFFICIENT_BALANCE：外部の言葉（内側に入れたくない）🧼🧱
retryable：便利だけど、そのまま信じていい？🤔⚠️（後の章で扱うよ）

5.5 「クセ台帳」を作る 🗃️📝✨（ACL設計の宝物💎）

外部APIのクセは、頭で覚えるより「表にして残す」が最強だよ🔥 ここでは “クセ台帳” を作ろう！

イメージ：外部APIのクセを可視化する

クセ台帳テンプレ（例）📋✨

外部API	外部フィールド	意味（推測でOK）	問題（クセ）😈	内側での表現（案）📘	ACLでの方針🛡️
学生	`stu_kbn`	学生区分	`"1"	"2"` が謎	`StudentType`	変換テーブルでenumへ
学生	`disp_nm`	表示名	半角カナ/空白ゆれ	`DisplayName`	正規化（全角化/トリム等）
学生	`email`	メール	空文字	`Email?`	空は `undefined` 扱い
決済	`result`	成否	`"OK"	"NG"`	`PaymentResult`	enumへ
決済	`error.code`	エラーコード	外部固有	`PaymentError`	外部→内側へ翻訳

ここでのポイントは「正解」を作ることじゃなくて、“クセを見逃さない” ことだよ〜！👀✨

5.6 クセの“種類”でまとめると、ACLの設計が一気にラクになる🧠✨

クセ台帳を作ったら、次は「カテゴリ分け」すると超スッキリするよ😺🧡

クセ分類（おすすめの箱）📦📦📦

命名変換：stu_kbn → studentType 🧾➡️📘
コード変換："2" → UNDERGRAD 🔤✨
パース（整形）："2004/7/3" → Date 🗓️🔧
欠損の扱い：空/省略/nullの統一🧼
単位の統一：円/ポイント/税/小数など💴🧮
エラー翻訳：外部エラー → 内側で意味のある失敗へ🧊🔥

この分類ができたら、ACLでやることが「翻訳メニュー」みたいに見えてくるよ🍽️✨

5.7 TypeScriptで“外部データ観察”をするミニコード（読むだけでOK）🧪👀

まずは「外部レスポンスを受け取って眺める」だけのコード例だよ〜！ Nodeの fetch で取って、unknown で受けるのがコツ🧠✨（最初から信用しない🛡️）

type StudentDirectoryRaw = unknown;

export async function fetchStudentRaw(studentId: string): Promise<StudentDirectoryRaw> {
  const url = `https://example.edu/api/students/${encodeURIComponent(studentId)}`;

  const res = await fetch(url); // fetch の使い方はWebと同じ感覚だよ✨
  if (!res.ok) throw new Error(`HTTP ${res.status}`);

  return res.json() as Promise<unknown>;
}

unknown にしておくと「雑に内側へ流し込む」事故が減るよ🧯✨
NodeのFetchはUndiciベースで提供されてるよ🚀 (Node.js)

5.8 AI拡張（Copilot/Codex）を使って“クセ台帳”作成を爆速にする🤖⚡

① 外部JSONから「クセ候補」を列挙させる📝

プロンプト例👇

「このJSONを見て、命名・コード値・欠損・型ゆれ・日時形式の観点でクセを列挙して」😺🔍
「このレスポンスを内側のドメインに入れないために、ACLで必要な変換を表にして」📋✨

② 変換テーブル（コード→enum案）を作らせる🔤

「stu_kbn の "1"|"2"|"9" に意味がある想定で、enum案と変換方針を出して」🎓✨

③ “危ない匂い”を嗅がせる👃⚠️

「このAPIは将来壊れそう？変更されやすそうな点を挙げて」💥

ただし！AIが言ったことは“提案”だから、台帳には「根拠（実データ）」も一緒に残すのが大事だよ📦🧠✨

5.9 演習（ミニ）✍️🌟：クセ台帳を完成させよう！

やること（15〜30分）⏱️💕

さっきの 学生API/決済APIのサンプルJSON をそれぞれ samples/ に保存📁✨
JSONを見て、クセ台帳に最低10個書く📝😺
クセを「命名/コード/欠損/型/日時/単位/エラー」に分類してラベル付け🏷️✨

チェック（できた？）✅🎀

“外部の言葉”っぽい項目を見つけられた？👻
空文字・null・省略のパターンを把握した？🧼
コード値（数字/文字）を見つけた？🔢
日時・単位・型のゆれを疑えた？🕵️‍♀️✨
「内側でどう表現したいか」を1行でも書けた？📘💕

5.10 この章のまとめ 🧁✨

題材は「学食ポイント」🍱🎓
外部APIは クセがある前提 で観察する👀🛡️
「クセ台帳」を作ると、ACLの設計が超ラクになる🧱✨
fetch で外部取得はできるけど、受け取ったデータは最初から信用しない（unknown）が安心🧯✨ (MDNウェブドキュメント)
2026年1月時点では Node は v24 が Active LTS として案内されているよ🟩✨ (Node.js)
TypeScript は 5.9 系のリリースノートが公開されていて、Node向けの設定（例：--module node20 など）も整備されてきてるよ🧩✨ (typescriptlang.org)

5.0 この章でやること（今日のゴール）🎯💕​

5.1 題材：学食ポイントアプリ（ミニ）🍱📱✨

何をするアプリ？🤔​

5.2 外部APIは2つ：学生情報と決済 🧑‍🎓🔍 + 💳🏦

A) 学生情報API（Student Directory）🧑‍🎓📚​

B) 決済API（Payment）💳🏦​

5.3 “クセ”ってなに？（外部APIあるある）😈🌀

よくあるクセ一覧（チェック項目）✅📝​

5.4 サンプルで“クセ”を体感しよう（外部レスポンス例）👀📦

A) 学生情報API：レスポンス例 🧑‍🎓📦​

B) 決済API：成功レスポンス例 💳✅​

C) 決済API：失敗レスポンス例 💳❌​