ADR（アーキテクチャ決定記録）で定義すべきこと
設計判断を記録し続ける技術と Python による ADR 管理 Tips

# ADR-0012: API ゲートウェイに Kong を採用する

## 結果・影響

### ポジティブ
- 認証・レート制限を API ゲートウェイに集約でき、各マイクロサービスの実装が単純化される
- Kong のプラグインエコシステムにより、将来の機能追加がコードなしで可能

### ネガティブ（トレードオフ）
- Kong 自体の運用スキルが必要になる（学習コスト：2週間想定）
- Kong が SPOF（単一障害点）になるため、高可用性構成（Active-Active）が必要

### 将来への影響
- Kong のバージョンアップに追従するメンテナンスコストが発生する
- オンプレからクラウド移行時に Kong Cloud（Konnect）への移行が選択肢になる

docs/
└── adr/
    ├── 0001-use-postgresql-for-primary-db.md
    ├── 0002-adopt-layered-architecture.md
    ├── 0003-use-redis-for-session-cache.md
    └── 0012-adopt-kong-as-api-gateway.md

# ADR-0012: API ゲートウェイに Kong を採用する

## ステータス
Accepted（2026-06-20）

## コンテキスト
マイクロサービス化に伴い、認証・認可・レート制限・ロギングを各サービスが
個別に実装している状態が問題になっている。重複実装の解消と横断的関心事の
集約のため、API ゲートウェイの導入を検討した。

制約：
- オンプレ環境での動作が必須（AWS 専用ソリューションは対象外）
- チームに Nginx の運用経験あり（Kong は未経験）
- 導入まで 3 ヶ月以内

## 決定
API ゲートウェイとして **Kong（オープンソース版）** を採用する。

### 比較した代替案

| 観点 | Kong | AWS API Gateway | Nginx + Lua |
|---|---|---|---|
| オンプレ対応 | ◎ | ✗ | ◎ |
| 認証プラグイン | 豊富 | Cognito 依存 | 自前実装 |
| レート制限 | ネイティブ | ネイティブ | プラグイン要 |
| 学習コスト | 中 | 低 | 高 |

Kong を選定した理由：オンプレ必須という制約を満たしつつ、
プラグインで認証・レート制限を設定のみで実現できるため。

## 結果・影響
### ポジティブ
- 横断的関心事を API ゲートウェイに集約し、各サービスの実装が単純化される
- プラグインによる将来の機能追加がコード変更なしで可能

### ネガティブ（トレードオフ）
- Kong 自体の運用知識が必要（習得コスト 2 週間を見込む）
- 高可用性のための Active-Active 構成が追加インフラコストになる

## 関連 ADR
- ADR-0003: Redis をセッションキャッシュに採用する（セッション管理との連携に影響）

"""
docs/adr/ 配下の Markdown ADR を解析し、
ステータス別の一覧表を標準出力に書き出す。
"""
import re
from pathlib import Path
from collections import defaultdict

ADR_DIR = Path("docs/adr")

STATUS_PATTERN = re.compile(
    r"##\s+ステータス\s*\n(.+?)(?:\n##|\Z)",
    re.DOTALL | re.IGNORECASE
)
TITLE_PATTERN = re.compile(r"^#\s+(.+)", re.MULTILINE)

def parse_adr(path: Path) -> dict:
    text = path.read_text(encoding="utf-8")

    title_m = TITLE_PATTERN.search(text)
    title = title_m.group(1).strip() if title_m else path.stem

    status_m = STATUS_PATTERN.search(text)
    status_raw = status_m.group(1).strip() if status_m else "Unknown"
    # 日付部分を除いてステータス名だけ取り出す
    status = re.split(r"[（(]", status_raw)[0].strip()

    return {
        "file":   path.name,
        "title":  title,
        "status": status,
    }

def main():
    if not ADR_DIR.exists():
        print(f"ディレクトリが見つかりません: {ADR_DIR}")
        return

    adrs = sorted(
        [parse_adr(p) for p in ADR_DIR.glob("*.md")],
        key=lambda x: x["file"]
    )

    by_status = defaultdict(list)
    for adr in adrs:
        by_status[adr["status"]].append(adr)

    print("# ADR 一覧\n")
    for status, items in sorted(by_status.items()):
        print(f"## {status}\n")
        print("| ファイル | タイトル |")
        print("|---|---|")
        for item in items:
            print(f"| `{item['file']}` | {item['title']} |")
        print()

if __name__ == "__main__":
    main()

"""
既存の ADR から次番号を自動採番し、テンプレートファイルを生成する。
使い方: python new_adr.py "API ゲートウェイに Kong を採用する"
"""
import sys
import re
from pathlib import Path
from datetime import date

ADR_DIR = Path("docs/adr")

TEMPLATE = """\
# ADR-{num:04d}: {title}

## ステータス
Proposed（{date}）

## コンテキスト


## 決定


## 結果・影響
### ポジティブ
-

### ネガティブ（トレードオフ）
-

## 関連 ADR
-
"""

def next_number() -> int:
    existing = list(ADR_DIR.glob("*.md"))
    if not existing:
        return 1
    nums = []
    for p in existing:
        m = re.match(r"^(\d+)", p.name)
        if m:
            nums.append(int(m.group(1)))
    return max(nums) + 1 if nums else 1

def main():
    if len(sys.argv) < 2:
        print("使い方: python new_adr.py '決定内容のタイトル'")
        sys.exit(1)

    title = sys.argv[1]
    num = next_number()
    slug = re.sub(r"[^\w\s-]", "", title.lower()).replace(" ", "-")
    filename = f"{num:04d}-{slug}.md"
    path = ADR_DIR / filename

    ADR_DIR.mkdir(parents=True, exist_ok=True)
    path.write_text(
        TEMPLATE.format(num=num, title=title, date=date.today().isoformat()),
        encoding="utf-8"
    )
    print(f"作成しました: {path}")

if __name__ == "__main__":
    main()