メインコンテンツまでスキップ

腐敗防止層（ACL）教育コンテンツ：20章 詳細アウトライン 🧼🧱✨

1章：ACLってなに？“翻訳係”のイメージをつかもう 🗣️🌍​

  • ACL（Anti-Corruption Layer）とは何か（超やさしく）
  • 「外部のクセ」が内側に入ると起きる事故例😱
  • 今日のゴール：ACLの役割を言葉で説明できるようにする🎯

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

  • 何を作る？：外部APIを2つ使う小さなアプリ題材🎓
  • どこにACLが入る？（内側／外側／境界の図）📦🚪
  • 最終成果物：外部DTOが内側に漏れない構造✅

3章：Windows＋VS Code＋TypeScript(2026)の最小セットアップ 🧰🪟​

  • Node.js（LTS想定）＋ TypeScript最新安定版
  • VS Code拡張（ESLint/Prettier/テスト/Git/AI）🧩
  • “生成AIを使う前提”の進め方（ルール）🤖🧠

4章：設計が超入門でもOKな「境界」と「関心の分離」🚪🧱​

  • SoC（関心の分離）を超シンプルに
  • 「内側＝自分のルール」「外側＝相手の都合」✨
  • ACLは境界に置く“通訳＋防波堤”🌊🛡️

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

  • 例：学食ポイント（ドメイン）🍱

  • 外部API例：

    • 学生情報：古い命名＋コード値が謎👻
    • 決済：エラー仕様が厳しい🏦

  • “クセの種類”をリスト化（命名/コード/欠損/単位/時刻…）📝

6章：まず失敗例を見る（外部DTOが侵食する地獄）🕳️😵​

  • 外部DTOをそのまま内部で使う例（あえてやる）

  • 起きる問題：

    • 命名が汚染される😇
    • 変更で内側が壊れる💥
    • テストがつらい🧪💦

  • ここで「ACLの必要性」を体感する章🔥

7章：最低限のドメインモデリング（Entity/ValueObject超入門）🧩📌​

  • Entity：IDで同一性（StudentIdなど）🪪
  • ValueObject：値に意味（Money/Pointなど）💴✨
  • “ドメインに入っていい言葉”を決める（辞書づくり）📚

8章：不変条件（Invariants）を“入口で守る”ってどういうこと？🚫🔒​

  • 例：「ポイントは0以上」「金額は正」など
  • ルールが散ると事故る（ifだらけ地獄）🌀
  • 入口（生成・更新）で保証する作り方✅

9章：ACLをどこに置く？配置パターンと責任範囲 🧱🛡️​

  • ACLの仕事は「翻訳」と「防御」✨

  • 置き場所のパターン：

    • 外部Clientの直後
    • Adapter層としてまとめる（Ports & Adapters）🔌

  • 何をACLに含める／含めない（線引き）✍️

10章：Ports & Adapters超入門（interfaceで“外を差し替え”）🔌🧱​

  • DIPをやさしく：内側は抽象に依存する🧠
  • StudentDirectoryPort / PaymentPortみたいな形で
  • テストがラクになる理由も先に理解する🧪✨

11章：ACLの核① マッピングの基本（DTO→ドメイン）🔁📦​

  • DTOは外の都合、ドメイン型は内の都合✨

  • 変換の基本形：

    • DTO受け取る
    • 整形する
    • ドメイン型を作る

  • 「変換関数の置き場所」と命名ルール📝

12章：ACLの核② 命名変換・構造変換（読みやすさ爆上げ）🧾➡️📘​

  • stu_kbn → studentType みたいな翻訳
  • ネスト構造の差を吸収（DTOは深い、ドメインは平ら等）🧱
  • “内側に残る言葉”の品質を上げる✨

13章：ACLの核③ コード値・列挙・区分の変換（謎コード撲滅）🔤🧹​

  • "1"|"2" を意味あるenumへ（例：UNDERGRAD/GRAD）🎓
  • 不明コードが来たらどうする？（方針）🤔
  • 変換テーブルの管理の仕方🗃️

14章：外部データを信用しない① パース（整形）の設計 🧽🔍​

  • “整形”の例：trim、全角半角、文字→数値、日時文字列など
  • パースをACLに置く理由（内側を汚さない）🧼
  • どこまで直す？直しすぎ問題も注意⚠️

15章：外部データを信用しない② バリデーション（検証）の設計 ✅🧪​

  • 何をチェックする？（必須、範囲、形式、長さ）

  • 失敗時の扱い：

    • 落とす（エラー）
    • 代替値
    • 保留（扱えないデータとして隔離）🚦

  • “境界で落とす”の大切さ🧯

16章：エラーモデリング① 外部エラーとドメインエラーの分離 🧊🔥​

  • 外部：HTTP、タイムアウト、レート制限、500…🌩️
  • ドメイン：学生がいない、残高不足、期限切れ…📘
  • 同じ「失敗」でも意味が違うのを理解する🧠

17章：エラーモデリング② 変換（翻訳）とリトライ可否の設計 🔁⏱️​

  • 外部エラー→ドメイン向けの形へ変換（境界の責任）🧱
  • リトライしていい失敗／ダメな失敗
  • “結果の型”を揃えて扱いやすくする📦✨

18章：テスト① マッピングのユニットテスト（最強に効く）🧪🔥​

  • DTO→ドメインのテスト観点
  • 正常系：代表ケースを少数で押さえる✅
  • “内側の不変条件”が守られるか確認🔒

19章：テスト② 異常系・境界値・外部変更検知（壊れない設計へ）🧨🧱​

  • 欠損、未知コード、変な型、桁あふれ、null…😇
  • フィクスチャ（外部レスポンスサンプル）を残す📦
  • 外部が変わったら“テストが先に気づく”仕組み🚨

20章：仕上げ：観測＋AI活用＋ミニプロジェクトで完成 🎓🏁📈🤖​

  • 観測（ログ/相関ID/失敗理由）をACLに入れる📈🔍

  • AI活用の実戦：

    • 変換関数の下書き生成
    • テストケース案の大量生成🧪
    • でもドメインルールは人間が監督🛡️

  • 最終課題：

    • 外部API2つをACLで包む
    • 内側はドメイン型だけで完結✨
    • チェックリストで卒業✅🎉