# [機能名] の理想フロー

given [入力・前提条件]

when [トリガー・操作]

then
  [手順1]: [何をするか]
  [手順2]: [何をするか]
  ...
  return [期待する出力]

# 分岐・エラーケース
when [例外ケース]
then [どう扱うか]

# 注文確定処理 の理想フロー

given 注文内容(商品リスト, ユーザーID)

when 注文確定ボタンが押された

then
  在庫チェック: 全商品が注文可能か確認する
  合計計算:    単価 × 数量を合算する
  決済処理:    合計金額を課金する
  通知送信:    ユーザーに確定メールを送る
  return 注文ID

when 在庫不足
then エラーを返す(どの商品が不足か含める)

when 決済失敗
then 在庫を元に戻す → エラーを返す

疑似コード「在庫チェック」→
  interface StockChecker
    check(items) -> Ok | OutOfStockError

疑似コード「合計計算」→
  interface PriceCalculator
    calculate(items) -> Money

疑似コード「決済処理」→
  interface PaymentGateway
    charge(amount, userId) -> PaymentId | PaymentError

疑似コード「通知送信」→
  interface OrderNotifier
    send(orderId, userId) -> void

class OrderService
  depends-on: StockChecker, PriceCalculator, PaymentGateway, OrderNotifier

  confirm(order):
    stock.check(order.items)    -> error? return it
    amount = price.calculate(order.items)
    paymentId = payment.charge(amount, order.userId) -> error? return it
    notifier.send(paymentId, order.userId)
    return paymentId

BAD:
  interface UserRepository
    findByEmailFromUsersTable(email) -> UserRow   # テーブル名が漏れている
    executeRawQuery(sql) -> unknown               # SQL言語が漏れている

GOOD:
  interface UserRepository
    findByEmail(email) -> User | null

BAD:
  interface ReportService
    fetchAndFormatAndSend(userId) -> void   # andが入ったら要注意

GOOD:
  interface Fetcher
  interface Formatter
  interface Sender

  class ReportFetcher   implements Fetcher   -> fetch(userId) -> RawReport
  class ReportFormatter implements Formatter -> format(raw)   -> FormattedReport
  class ReportSender    implements Sender    -> send(report)  -> void

BAD:
  interface UserService
    find(id)               -> User
    save(user)             -> void
    delete(id)             -> void
    sendWelcomeEmail(user) -> void    # 通知は別責務
    exportToCsv(users)     -> string  # エクスポートも別責務

GOOD: (1 interface = 1メソッド = 1責務)
  interface Reader
  interface Writer
  interface Deleter
  interface Notifier
  interface Exporter

  class UserReader   implements Reader   -> read(id) -> User
  class UserWriter   implements Writer   -> write(user) -> void
  class UserNotifier implements Notifier -> notify(userId, message) -> void

BAD:
  interface ArticleInterface
    get(id) -> array           # "array" はORM都合の型
    paginateAll() -> Paginator # ORMのPaginatorが漏れている

GOOD: 疑似コードから「記事一覧表示」フローを先に描く
  interface Reader
  interface Lister

  class ArticleReader implements Reader -> read(id)     -> Article | null
  class ArticleLister implements Lister -> list(filter) -> Article[]

## [機能名] 設計

### 疑似コード
[Step 1の内容]

### Interface一覧
| Interface名 | メソッド | 引数 | 戻り値 |
|------------|---------|------|--------|
| FooReader  | read()  | id   | Foo \| null |

### クラス一覧
| クラス名    | 実装Interface | 責務 |
|------------|--------------|------|
| FooReader  | Reader       | DBからFooを取得 |

### 上位層の組み立て
[Step 3の内容]

[ ] 疑似コードを書いたか（Step 1を省略していないか）
[ ] 各interfaceのメソッドは1つか（複数なら分割候補）
[ ] interfaceにフレームワーク固有の型が含まれていないか
[ ] 実装を差し替えても利用側が変わらないか
[ ] 組み立て処理は上位層に集約されているか
[ ] エラーケースがinterfaceの戻り値型に反映されているか
[ ] interfaceにメソッドを追加しても既存実装が壊れないか（壊れるなら責務混在）
[ ] 1メソッドが2つ以上の理由で変更されないか
[ ] 禁止事項をすべて確認したか
[ ] TDDスキルへの移行準備ができているか