# 規模別アーキテクチャ判断の目安
def recommend_architecture(dau: int, data_gb: float) -> dict:
    """DAUとデータ量からアーキテクチャを推奨"""
    if dau < 1_000:
        return {
            "architecture": "シンプルモノリス",
            "infra": "単一サーバー (VPS/PaaS)",
            "db": "単一RDB (PostgreSQL)",
            "cache": "不要（またはアプリ内キャッシュ）",
            "deployment": "手動 or 簡易CI/CD",
            "cost": "~$50/月",
            "team_size": "1-2人",
        }
    elif dau < 100_000:
        return {
            "architecture": "モノリス + 一部分離",
            "infra": "Web(2台) + DB(Primary/Replica)",
            "db": "RDB + Read Replica",
            "cache": "Redis (単一ノード)",
            "deployment": "CI/CD + Blue/Green",
            "cost": "~$500-2,000/月",
            "team_size": "3-10人",
        }
    elif dau < 10_000_000:
        return {
            "architecture": "サービス分割 (Modular Monolith or Microservices)",
            "infra": "Kubernetes or ECS + Auto Scaling",
            "db": "RDB (シャーディング) + NoSQL",
            "cache": "Redis Cluster + CDN",
            "deployment": "Canary/Rolling + Feature Flags",
            "cost": "~$10,000-100,000/月",
            "team_size": "20-100人",
        }
    else:
        return {
            "architecture": "マイクロサービス + イベント駆動",
            "infra": "マルチリージョン + マルチクラウド",
            "db": "分散DB + Data Lake + CQRS",
            "cache": "多層キャッシュ (L1/L2/CDN)",
            "deployment": "カスタムデプロイパイプライン",
            "cost": "$100,000+/月",
            "team_size": "100人+",
        }
 
# 出力例
for dau in [500, 50_000, 5_000_000, 50_000_000]:
    result = recommend_architecture(dau, dau * 0.001)
    print(f"\n=== DAU: {dau:>12,} ===")
    for k, v in result.items():
        print(f"  {k:20s}: {v}")
 
# 出力:
# === DAU:          500 ===
#   architecture        : シンプルモノリス
#   infra               : 単一サーバー (VPS/PaaS)
#   db                  : 単一RDB (PostgreSQL)
#   cache               : 不要（またはアプリ内キャッシュ）
#   deployment          : 手動 or 簡易CI/CD
#   cost                : ~$50/月
#   team_size           : 1-2人
# ...以下略

# 要件明確化のフレームワーク
class RequirementAnalyzer:
    """要件を体系的に整理するフレームワーク"""
 
    def __init__(self, system_name: str):
        self.system_name = system_name
        self.functional_requirements = []
        self.non_functional_requirements = {}
        self.constraints = []
        self.assumptions = []
        self.out_of_scope = []
 
    def add_functional(self, requirement: str, priority: str = "must"):
        """機能要件を追加（must/should/could/won't で分類）"""
        self.functional_requirements.append({
            "requirement": requirement,
            "priority": priority,  # MoSCoW法
        })
 
    def set_nfr(self, category: str, target: str, rationale: str):
        """非機能要件を設定"""
        self.non_functional_requirements[category] = {
            "target": target,
            "rationale": rationale,
        }
 
    def add_constraint(self, constraint: str):
        """制約条件を追加"""
        self.constraints.append(constraint)
 
    def add_assumption(self, assumption: str):
        """前提条件（仮定）を追加"""
        self.assumptions.append(assumption)
 
    def add_out_of_scope(self, item: str):
        """スコープ外の機能を明示"""
        self.out_of_scope.append(item)
 
    def summary(self) -> str:
        """要件サマリーを出力"""
        lines = [f"=== {self.system_name} 要件サマリー ===\n"]
 
        # 機能要件（MoSCoW法で分類）
        lines.append("【機能要件】")
        for priority in ["must", "should", "could", "won't"]:
            items = [r for r in self.functional_requirements
                     if r["priority"] == priority]
            if items:
                label = {"must": "Must Have", "should": "Should Have",
                         "could": "Could Have", "won't": "Won't Have"}[priority]
                lines.append(f"  [{label}]")
                for item in items:
                    lines.append(f"    - {item['requirement']}")
 
        # 非機能要件
        lines.append("\n【非機能要件】")
        for category, detail in self.non_functional_requirements.items():
            lines.append(f"  {category}: {detail['target']}")
            lines.append(f"    理由: {detail['rationale']}")
 
        # 制約条件
        lines.append("\n【制約条件】")
        for c in self.constraints:
            lines.append(f"  - {c}")
 
        # 仮定
        lines.append("\n【仮定】")
        for a in self.assumptions:
            lines.append(f"  - {a}")
 
        # スコープ外
        lines.append("\n【スコープ外】")
        for o in self.out_of_scope:
            lines.append(f"  - {o}")
 
        return "\n".join(lines)
 
 
# 使用例: Twitter風SNSの設計
analyzer = RequirementAnalyzer("Twitter風SNS")
 
# 機能要件（MoSCoW法）
analyzer.add_functional("ツイートの投稿（テキスト、280文字以内）", "must")
analyzer.add_functional("ホームタイムラインの表示", "must")
analyzer.add_functional("ユーザーフォロー/アンフォロー", "must")
analyzer.add_functional("ツイートの「いいね」", "should")
analyzer.add_functional("リツイート機能", "should")
analyzer.add_functional("画像/動画の添付", "could")
analyzer.add_functional("ダイレクトメッセージ", "won't")  # 今回のスコープ外
analyzer.add_functional("広告表示", "won't")
 
# 非機能要件
analyzer.set_nfr("レイテンシ", "タイムライン表示 < 200ms (P99)",
                 "ユーザー体験の閾値。Googleの研究で200ms以上は体感遅延")
analyzer.set_nfr("可用性", "99.99% (年間ダウンタイム < 52分)",
                 "SNSは常時利用が前提。99.9%では年間8.7時間のダウン")
analyzer.set_nfr("スケーラビリティ", "DAU 3億、ピーク200万QPS",
                 "Twitterの実績ベース。成長を見込んで余裕を持つ")
analyzer.set_nfr("データ耐久性", "99.9999999% (9 nines)",
                 "ユーザーの投稿データは絶対に失えない")
analyzer.set_nfr("一貫性", "結果整合性（5秒以内）",
                 "強い一貫性は不要。タイムラインは多少の遅延が許容される")
 
# 制約条件
analyzer.add_constraint("予算: 初年度 $5M 以内")
analyzer.add_constraint("チーム: バックエンドエンジニア 20名")
analyzer.add_constraint("既存インフラ: AWS (移行不可)")
 
# 仮定
analyzer.add_assumption("DAU 3億のうち、1日あたり投稿するのは20%（6000万人）")
analyzer.add_assumption("1ユーザーあたりフォロー平均200人")
analyzer.add_assumption("読み:書き比率 = 100:1")
 
# スコープ外
analyzer.add_out_of_scope("ダイレクトメッセージ機能")
analyzer.add_out_of_scope("広告配信システム")
analyzer.add_out_of_scope("画像/動画のトランスコーディング")
 
print(analyzer.summary())
 
# 出力:
# === Twitter風SNS 要件サマリー ===
#
# 【機能要件】
#   [Must Have]
#     - ツイートの投稿（テキスト、280文字以内）
#     - ホームタイムラインの表示
#     - ユーザーフォロー/アンフォロー
#   [Should Have]
#     - ツイートの「いいね」
#     - リツイート機能
#   [Could Have]
#     - 画像/動画の添付
#   [Won't Have]
#     - ダイレクトメッセージ
#     - 広告表示
#
# 【非機能要件】
#   レイテンシ: タイムライン表示 < 200ms (P99)
#     理由: ユーザー体験の閾値。Googleの研究で200ms以上は体感遅延
#   可用性: 99.99% (年間ダウンタイム < 52分)
#     理由: SNSは常時利用が前提。99.9%では年間8.7時間のダウン
#   ...以下略

class SystemEstimator:
    """システム設計の見積もりツール"""
 
    # よく使う定数
    SECONDS_PER_DAY = 86_400
    SECONDS_PER_MONTH = 2_592_000  # 30日
    SECONDS_PER_YEAR = 31_536_000  # 365日
 
    def __init__(self, service_name: str, dau: int):
        self.service_name = service_name
        self.dau = dau
 
    def estimate_qps(self, actions_per_user_per_day: float,
                     read_write_ratio: int = 100,
                     peak_multiplier: float = 3.0) -> dict:
        """QPS（Queries Per Second）の見積もり"""
        write_qps = self.dau * actions_per_user_per_day / self.SECONDS_PER_DAY
        read_qps = write_qps * read_write_ratio
        return {
            "avg_write_qps": write_qps,
            "avg_read_qps": read_qps,
            "peak_write_qps": write_qps * peak_multiplier,
            "peak_read_qps": read_qps * peak_multiplier,
        }
 
    def estimate_storage(self, object_size_bytes: int,
                         objects_per_user_per_day: float,
                         retention_years: int = 5) -> dict:
        """ストレージ見積もり"""
        daily_objects = self.dau * objects_per_user_per_day
        daily_storage = daily_objects * object_size_bytes
        yearly_storage = daily_storage * 365
        total_storage = yearly_storage * retention_years
        return {
            "daily_new_objects": daily_objects,
            "daily_storage_tb": daily_storage / 1e12,
            "yearly_storage_tb": yearly_storage / 1e12,
            "total_storage_tb": total_storage / 1e12,
            "total_storage_pb": total_storage / 1e15,
        }
 
    def estimate_bandwidth(self, avg_response_size_bytes: int,
                           peak_read_qps: float) -> dict:
        """帯域幅見積もり"""
        bandwidth_bytes = peak_read_qps * avg_response_size_bytes
        return {
            "peak_bandwidth_gbps": bandwidth_bytes * 8 / 1e9,
            "peak_bandwidth_mbps": bandwidth_bytes * 8 / 1e6,
            "monthly_transfer_tb": (bandwidth_bytes * self.SECONDS_PER_MONTH) / 1e12,
        }
 
    def estimate_memory_for_cache(self, hot_data_percentage: float,
                                  daily_storage_bytes: float) -> dict:
        """キャッシュに必要なメモリ量の見積もり（80/20ルール）"""
        # 通常、20%のデータが80%のアクセスを占める
        cache_size = daily_storage_bytes * hot_data_percentage
        # Redis等のオーバーヘッド（約2倍）
        actual_memory = cache_size * 2
        return {
            "cache_data_gb": cache_size / 1e9,
            "actual_memory_gb": actual_memory / 1e9,
            "redis_nodes_64gb": max(1, int(actual_memory / (64 * 1e9)) + 1),
        }
 
    def full_report(self) -> str:
        """全見積もりのレポートを生成"""
        lines = [f"=== {self.service_name} 見積もりレポート ==="]
        lines.append(f"DAU: {self.dau:,}")
 
        # QPS
        qps = self.estimate_qps(2, 100, 3)
        lines.append(f"\n【QPS見積もり】")
        lines.append(f"  平均書き込み: {qps['avg_write_qps']:,.0f} QPS")
        lines.append(f"  平均読み込み: {qps['avg_read_qps']:,.0f} QPS")
        lines.append(f"  ピーク書き込み: {qps['peak_write_qps']:,.0f} QPS")
        lines.append(f"  ピーク読み込み: {qps['peak_read_qps']:,.0f} QPS")
 
        # ストレージ
        storage = self.estimate_storage(560, 2, 5)
        lines.append(f"\n【ストレージ見積もり】")
        lines.append(f"  1日の新規データ: {storage['daily_storage_tb']:.2f} TB")
        lines.append(f"  1年の新規データ: {storage['yearly_storage_tb']:.1f} TB")
        lines.append(f"  5年間の総データ: {storage['total_storage_tb']:.1f} TB "
                     f"({storage['total_storage_pb']:.2f} PB)")
 
        # 帯域幅
        bw = self.estimate_bandwidth(10_000, qps['peak_read_qps'])
        lines.append(f"\n【帯域幅見積もり】")
        lines.append(f"  ピーク帯域: {bw['peak_bandwidth_gbps']:.1f} Gbps")
        lines.append(f"  月間転送量: {bw['monthly_transfer_tb']:.0f} TB")
 
        # キャッシュ
        cache = self.estimate_memory_for_cache(
            0.2, storage['daily_storage_tb'] * 1e12)
        lines.append(f"\n【キャッシュ見積もり（ホットデータ20%）】")
        lines.append(f"  キャッシュデータ量: {cache['cache_data_gb']:.1f} GB")
        lines.append(f"  実メモリ必要量: {cache['actual_memory_gb']:.1f} GB")
        lines.append(f"  Redisノード数(64GB): {cache['redis_nodes_64gb']}")
 
        return "\n".join(lines)
 
 
# 使用例
estimator = SystemEstimator("Twitter風SNS", 300_000_000)
print(estimator.full_report())
 
# 出力:
# === Twitter風SNS 見積もりレポート ===
# DAU: 300,000,000
#
# 【QPS見積もり】
#   平均書き込み: 6,944 QPS
#   平均読み込み: 694,444 QPS
#   ピーク書き込み: 20,833 QPS
#   ピーク読み込み: 2,083,333 QPS
#
# 【ストレージ見積もり】
#   1日の新規データ: 0.34 TB
#   1年の新規データ: 122.6 TB
#   5年間の総データ: 613.2 TB (0.61 PB)
#
# 【帯域幅見積もり】
#   ピーク帯域: 166.7 Gbps
#   月間転送量: 54000 TB
#
# 【キャッシュ見積もり（ホットデータ20%）】
#   キャッシュデータ量: 67.2 GB
#   実メモリ必要量: 134.4 GB
#   Redisノード数(64GB): 3

# 非機能要件の体系的整理
class NFRFramework:
    """非機能要件を網羅的にチェックするフレームワーク"""
 
    CATEGORIES = {
        "性能 (Performance)": {
            "レイテンシ": "応答時間の上限 (P50, P95, P99)",
            "スループット": "単位時間あたりの処理能力 (QPS/TPS)",
            "リソース効率": "CPU/メモリ/ディスク使用率の目標",
        },
        "信頼性 (Reliability)": {
            "可用性": "稼働率の目標 (99.9%, 99.99%等)",
            "耐障害性": "障害時の動作保証",
            "データ耐久性": "データ損失に対する保証",
            "災害復旧": "RPO (Recovery Point Objective) / RTO (Recovery Time Objective)",
        },
        "スケーラビリティ (Scalability)": {
            "負荷対応": "想定する最大負荷",
            "データ増大": "想定するデータ増加率",
            "地理的拡張": "マルチリージョン対応の必要性",
        },
        "セキュリティ (Security)": {
            "認証/認可": "認証方式、権限モデル",
            "データ保護": "暗号化要件 (at-rest, in-transit)",
            "コンプライアンス": "GDPR, HIPAA, PCI DSS等",
            "監査": "操作ログの保存要件",
        },
        "運用性 (Operability)": {
            "監視": "メトリクス、ログ、トレーシング",
            "デプロイ": "デプロイ頻度、ダウンタイム許容度",
            "保守性": "コードの理解しやすさ、変更容易性",
        },
    }
 
    @classmethod
    def generate_checklist(cls) -> str:
        """NFRチェックリストを生成"""
        lines = ["=== 非機能要件チェックリスト ===\n"]
        for category, items in cls.CATEGORIES.items():
            lines.append(f"[ ] {category}")
            for name, description in items.items():
                lines.append(f"    [ ] {name}: {description}")
            lines.append("")
        return "\n".join(lines)
 
print(NFRFramework.generate_checklist())
 
# 出力:
# === 非機能要件チェックリスト ===
#
# [ ] 性能 (Performance)
#     [ ] レイテンシ: 応答時間の上限 (P50, P95, P99)
#     [ ] スループット: 単位時間あたりの処理能力 (QPS/TPS)
#     [ ] リソース効率: CPU/メモリ/ディスク使用率の目標
#
# [ ] 信頼性 (Reliability)
#     [ ] 可用性: 稼働率の目標 (99.9%, 99.99%等)
#     [ ] 耐障害性: 障害時の動作保証
#     [ ] データ耐久性: データ損失に対する保証
#     [ ] 災害復旧: RPO / RTO
# ...以下略

# 可用性とダウンタイムの関係
def availability_table():
    """可用性レベルごとのダウンタイムを計算"""
    print(f"{'可用性':>10s}  {'年間DT':>12s}  {'月間DT':>10s}  {'週間DT':>8s}  {'用途例'}")
    print("-" * 80)
 
    levels = [
        (99.0,    "内部ツール、開発環境"),
        (99.9,    "一般的なSaaS"),
        (99.95,   "ECサイト"),
        (99.99,   "金融、医療"),
        (99.999,  "通信インフラ"),
        (99.9999, "航空管制、原子力"),
    ]
 
    minutes_per_year = 365.25 * 24 * 60
 
    for avail, use_case in levels:
        downtime_pct = 100 - avail
        dt_year = minutes_per_year * downtime_pct / 100
        dt_month = dt_year / 12
        dt_week = dt_year / 52
 
        if dt_year >= 60:
            year_str = f"{dt_year / 60:.1f}時間"
        else:
            year_str = f"{dt_year:.1f}分"
 
        if dt_month >= 60:
            month_str = f"{dt_month / 60:.1f}時間"
        else:
            month_str = f"{dt_month:.1f}分"
 
        week_str = f"{dt_week:.1f}分"
 
        print(f"{avail:>9.4f}%  {year_str:>12s}  {month_str:>10s}  "
              f"{week_str:>8s}  {use_case}")
 
availability_table()
 
# 出力:
#    可用性        年間DT      月間DT    週間DT  用途例
# ----------------------------------------------------------
#  99.0000%      87.7時間     7.3時間   101.2分  内部ツール、開発環境
#  99.9000%       8.8時間      43.8分    10.1分  一般的なSaaS
#  99.9500%       4.4時間      21.9分     5.1分  ECサイト
#  99.9900%      52.6分        4.4分     1.0分  金融、医療
#  99.9990%       5.3分        0.4分     0.1分  通信インフラ
#  99.9999%       0.5分        0.0分     0.0分  航空管制、原子力

# Jeff Deanのレイテンシ数値（現代版概算）
latency_numbers = {
    # メモリ操作（ナノ秒オーダー）
    "L1 cache reference":                  ("0.5 ns",   0.5),
    "Branch mispredict":                   ("5 ns",     5),
    "L2 cache reference":                  ("7 ns",     7),
    "Mutex lock/unlock":                   ("25 ns",    25),
    "Main memory reference":               ("100 ns",   100),
 
    # ストレージ操作（マイクロ秒〜ミリ秒オーダー）
    "SSD random read (4KB)":               ("150 us",   150_000),
    "Read 1 MB sequentially from memory":  ("250 us",   250_000),
    "Read 1 MB sequentially from SSD":     ("1 ms",     1_000_000),
    "Read 1 MB sequentially from HDD":     ("20 ms",    20_000_000),
    "HDD disk seek":                       ("10 ms",    10_000_000),
 
    # ネットワーク操作（ミリ秒オーダー）
    "Send packet CA → Netherlands → CA":   ("150 ms",   150_000_000),
    "Same datacenter round trip":          ("0.5 ms",   500_000),
    "TCP handshake (same DC)":             ("1.5 ms",   1_500_000),
    "TLS handshake":                       ("10 ms",    10_000_000),
}
 
# ビジュアル比較（対数スケール）
print("=== レイテンシ比較（対数スケール） ===\n")
for operation, (label, ns) in latency_numbers.items():
    import math
    bar_length = int(math.log10(max(ns, 1)) * 4)
    bar = "#" * bar_length
    print(f"  {operation:45s} {label:>10s}  {bar}")
 
# 出力:
# === レイテンシ比較（対数スケール） ===
#
#   L1 cache reference                          0.5 ns
#   Branch mispredict                             5 ns  ##
#   L2 cache reference                            7 ns  ###
#   Mutex lock/unlock                            25 ns  #####
#   Main memory reference                       100 ns  ########
#   SSD random read (4KB)                       150 us  ####################
#   Read 1 MB sequentially from memory          250 us  #####################
#   Read 1 MB sequentially from SSD               1 ms  ########################
#   Read 1 MB sequentially from HDD              20 ms  #############################
#   HDD disk seek                                10 ms  ############################
#   Send packet CA → Netherlands → CA           150 ms  ################################
#   Same datacenter round trip                  0.5 ms  ######################
#   TCP handshake (same DC)                     1.5 ms  ########################
#   TLS handshake                                10 ms  ############################

# 設計面接でよく使う2の冪乗とデータサイズの対応表
print("=== 2の冪乗テーブル ===\n")
print(f"{'冪乗':>6s}  {'値':>20s}  {'バイト単位':>10s}  {'実用例'}")
print("-" * 75)
 
examples = {
    7:  ("128 B",     "HTTPヘッダー1つ分"),
    8:  ("256 B",     "小さなJSON応答"),
    10: ("1 KB",      "短いテキスト"),
    14: ("16 KB",     "典型的なHTML1ページ"),
    16: ("64 KB",     "TCPウィンドウサイズ"),
    20: ("1 MB",      "高画質写真1枚"),
    23: ("8 MB",      "一般的なキャッシュエントリ上限"),
    25: ("32 MB",     "短い動画クリップ"),
    30: ("1 GB",      "映画1本 (圧縮済み)"),
    33: ("8 GB",      "一般的なサーバーメモリ"),
    36: ("64 GB",     "Redisノード1台の推奨上限"),
    40: ("1 TB",      "大規模DBのデータファイル"),
    50: ("1 PB",      "大企業のデータウェアハウス"),
}
 
for power, (size, example) in examples.items():
    print(f"  2^{power:2d}  {2**power:>20,}  {size:>10s}  {example}")
 
# 出力:
#  冪乗                    値    バイト単位  実用例
# -----------------------------------------------------------------------
#   2^ 7                   128       128 B  HTTPヘッダー1つ分
#   2^ 8                   256       256 B  小さなJSON応答
#   2^10                 1,024        1 KB  短いテキスト
#   2^14                16,384       16 KB  典型的なHTML1ページ
#   2^16                65,536       64 KB  TCPウィンドウサイズ
#   2^20             1,048,576        1 MB  高画質写真1枚
#   ...以下略

# 主要Webサービスの見積もりを瞬時に出す練習
services = {
    "URL短縮サービス": {
        "dau": 100_000_000,
        "writes_per_user_day": 0.1,  # 10人に1人が短縮
        "reads_per_write": 100,      # 1つのURLが100回クリック
        "data_per_record_bytes": 500, # URL + メタデータ
        "retention_years": 10,
    },
    "Instagram風画像共有": {
        "dau": 500_000_000,
        "writes_per_user_day": 0.5,
        "reads_per_write": 200,
        "data_per_record_bytes": 2_000_000,  # 平均2MB/画像
        "retention_years": 99,  # 永久保存
    },
    "チャットアプリ": {
        "dau": 200_000_000,
        "writes_per_user_day": 50,   # 1日50メッセージ
        "reads_per_write": 5,        # グループチャット平均
        "data_per_record_bytes": 200, # テキストメッセージ
        "retention_years": 5,
    },
}
 
for name, params in services.items():
    dau = params["dau"]
    write_qps = dau * params["writes_per_user_day"] / 86400
    read_qps = write_qps * params["reads_per_write"]
    daily_storage = dau * params["writes_per_user_day"] * params["data_per_record_bytes"]
    yearly_storage_tb = daily_storage * 365 / 1e12
 
    print(f"\n=== {name} ===")
    print(f"  DAU: {dau/1e6:.0f}M")
    print(f"  書き込みQPS: {write_qps:,.0f} (ピーク: {write_qps*3:,.0f})")
    print(f"  読み込みQPS: {read_qps:,.0f} (ピーク: {read_qps*3:,.0f})")
    print(f"  年間ストレージ: {yearly_storage_tb:.1f} TB")
 
# 出力:
# === URL短縮サービス ===
#   DAU: 100M
#   書き込みQPS: 116 (ピーク: 347)
#   読み込みQPS: 11,574 (ピーク: 34,722)
#   年間ストレージ: 1.8 TB
#
# === Instagram風画像共有 ===
#   DAU: 500M
#   書き込みQPS: 2,894 (ピーク: 8,681)
#   読み込みQPS: 578,704 (ピーク: 1,736,111)
#   年間ストレージ: 182,500.0 TB
#
# === チャットアプリ ===
#   DAU: 200M
#   書き込みQPS: 115,741 (ピーク: 347,222)
#   読み込みQPS: 578,704 (ピーク: 1,736,111)
#   年間ストレージ: 730.0 TB

# REST API設計の体系的アプローチ
from dataclasses import dataclass, field
from typing import Optional
from enum import Enum
 
class HttpMethod(Enum):
    GET = "GET"
    POST = "POST"
    PUT = "PUT"
    PATCH = "PATCH"
    DELETE = "DELETE"
 
@dataclass
class APIEndpoint:
    """REST APIエンドポイントの定義"""
    method: HttpMethod
    path: str
    description: str
    request_body: Optional[dict] = None
    query_params: Optional[dict] = None
    response: Optional[dict] = None
    rate_limit: str = "100 req/min"
    auth_required: bool = True
 
@dataclass
class APIDesign:
    """API設計文書"""
    service_name: str
    base_url: str
    version: str = "v1"
    endpoints: list = field(default_factory=list)
 
    def add_endpoint(self, endpoint: APIEndpoint):
        self.endpoints.append(endpoint)
 
    def generate_doc(self) -> str:
        lines = [f"=== {self.service_name} API設計 ==="]
        lines.append(f"Base URL: {self.base_url}/api/{self.version}\n")
 
        for ep in self.endpoints:
            lines.append(f"  {ep.method.value:6s} {ep.path}")
            lines.append(f"    説明: {ep.description}")
            lines.append(f"    認証: {'必要' if ep.auth_required else '不要'}")
            lines.append(f"    レート制限: {ep.rate_limit}")
            if ep.request_body:
                lines.append(f"    リクエスト: {ep.request_body}")
            if ep.query_params:
                lines.append(f"    クエリパラメータ: {ep.query_params}")
            if ep.response:
                lines.append(f"    レスポンス: {ep.response}")
            lines.append("")
 
        return "\n".join(lines)
 
 
# 使用例: Twitter風SNSのAPI設計
api = APIDesign("Twitter風SNS", "https://api.example.com")
 
api.add_endpoint(APIEndpoint(
    method=HttpMethod.POST,
    path="/tweets",
    description="新しいツイートを投稿",
    request_body={"text": "str (max 280)", "media_ids": "list[str] (optional)"},
    response={"tweet_id": "str", "created_at": "datetime"},
    rate_limit="300 req/hour",
))
 
api.add_endpoint(APIEndpoint(
    method=HttpMethod.GET,
    path="/timeline/home",
    description="ホームタイムラインを取得",
    query_params={"cursor": "str", "limit": "int (default=20, max=100)"},
    response={"tweets": "list[Tweet]", "next_cursor": "str"},
    rate_limit="450 req/15min",
))
 
api.add_endpoint(APIEndpoint(
    method=HttpMethod.GET,
    path="/users/{user_id}",
    description="ユーザープロフィールを取得",
    response={"user_id": "str", "name": "str", "followers_count": "int"},
    rate_limit="900 req/15min",
))
 
api.add_endpoint(APIEndpoint(
    method=HttpMethod.POST,
    path="/users/{user_id}/follow",
    description="ユーザーをフォロー",
    response={"success": "bool"},
    rate_limit="400 req/day",
))
 
api.add_endpoint(APIEndpoint(
    method=HttpMethod.DELETE,
    path="/tweets/{tweet_id}",
    description="ツイートを削除",
    response={"success": "bool"},
    rate_limit="300 req/hour",
))
 
print(api.generate_doc())
 
# 出力:
# === Twitter風SNS API設計 ===
# Base URL: https://api.example.com/api/v1
#
#   POST   /tweets
#     説明: 新しいツイートを投稿
#     認証: 必要
#     レート制限: 300 req/hour
#     リクエスト: {'text': 'str (max 280)', 'media_ids': 'list[str] (optional)'}
#     レスポンス: {'tweet_id': 'str', 'created_at': 'datetime'}
# ...以下略

# DBスキーマ設計のフレームワーク
class SchemaDesigner:
    """DBスキーマ設計を構造化するツール"""
 
    def __init__(self, db_type: str = "PostgreSQL"):
        self.db_type = db_type
        self.tables = []
 
    def add_table(self, name: str, columns: list, indexes: list = None,
                  notes: str = ""):
        self.tables.append({
            "name": name,
            "columns": columns,
            "indexes": indexes or [],
            "notes": notes,
        })
 
    def generate_ddl(self) -> str:
        lines = [f"-- {self.db_type} スキーマ定義\n"]
        for table in self.tables:
            lines.append(f"-- {table['notes']}" if table['notes'] else "")
            lines.append(f"CREATE TABLE {table['name']} (")
            col_lines = []
            for col in table['columns']:
                col_lines.append(f"    {col}")
            lines.append(",\n".join(col_lines))
            lines.append(");\n")
 
            for idx in table['indexes']:
                lines.append(f"CREATE INDEX {idx};")
            lines.append("")
        return "\n".join(lines)
 
 
# Twitter風SNSのスキーマ設計
schema = SchemaDesigner()
 
schema.add_table("users", [
    "user_id         BIGINT PRIMARY KEY",
    "username        VARCHAR(15) UNIQUE NOT NULL",
    "email           VARCHAR(255) UNIQUE NOT NULL",
    "display_name    VARCHAR(50) NOT NULL",
    "bio             VARCHAR(160)",
    "followers_count INT DEFAULT 0",
    "following_count INT DEFAULT 0",
    "created_at      TIMESTAMP DEFAULT NOW()",
    "updated_at      TIMESTAMP DEFAULT NOW()",
], indexes=[
    "idx_users_username ON users(username)",
    "idx_users_email ON users(email)",
], notes="ユーザー情報 - DAU 3億 → 約5億行想定")
 
schema.add_table("tweets", [
    "tweet_id    BIGINT PRIMARY KEY",  # Snowflake ID
    "user_id     BIGINT NOT NULL REFERENCES users(user_id)",
    "text        VARCHAR(280) NOT NULL",
    "media_urls  JSONB",
    "like_count  INT DEFAULT 0",
    "rt_count    INT DEFAULT 0",
    "created_at  TIMESTAMP DEFAULT NOW()",
], indexes=[
    "idx_tweets_user_id_created ON tweets(user_id, created_at DESC)",
    "idx_tweets_created ON tweets(created_at DESC)",
], notes="ツイート本体 - 1日6億件 → 年間2190億件。シャーディング必須")
 
schema.add_table("follows", [
    "follower_id   BIGINT NOT NULL REFERENCES users(user_id)",
    "followee_id   BIGINT NOT NULL REFERENCES users(user_id)",
    "created_at    TIMESTAMP DEFAULT NOW()",
    "PRIMARY KEY (follower_id, followee_id)",
], indexes=[
    "idx_follows_followee ON follows(followee_id)",
], notes="フォロー関係 - 双方向インデックスが重要")
 
schema.add_table("timeline_cache", [
    "user_id     BIGINT NOT NULL",
    "tweet_id    BIGINT NOT NULL",
    "author_id   BIGINT NOT NULL",
    "score       FLOAT NOT NULL",  # ランキングスコア
    "created_at  TIMESTAMP DEFAULT NOW()",
    "PRIMARY KEY (user_id, score DESC, tweet_id)",
], notes="タイムラインキャッシュ（Redisで実装するのが一般的）")
 
print(schema.generate_ddl())
 
# 出力:
# -- PostgreSQL スキーマ定義
#
# -- ユーザー情報 - DAU 3億 → 約5億行想定
# CREATE TABLE users (
#     user_id         BIGINT PRIMARY KEY,
#     username        VARCHAR(15) UNIQUE NOT NULL,
#     ...
# );
# CREATE INDEX idx_users_username ON users(username);
# ...以下略

# トレードオフ分析の構造化フレームワーク
class TradeoffAnalysis:
    """設計トレードオフを体系的に分析するツール"""
 
    def __init__(self, decision: str):
        self.decision = decision
        self.options = []
 
    def add_option(self, name: str, pros: list, cons: list,
                   cost: str, complexity: str, when_to_use: str):
        self.options.append({
            "name": name,
            "pros": pros,
            "cons": cons,
            "cost": cost,
            "complexity": complexity,
            "when_to_use": when_to_use,
        })
 
    def analyze(self) -> str:
        lines = [f"=== トレードオフ分析: {self.decision} ===\n"]
        for i, opt in enumerate(self.options, 1):
            lines.append(f"【選択肢{i}】{opt['name']}")
            lines.append(f"  長所:")
            for p in opt['pros']:
                lines.append(f"    + {p}")
            lines.append(f"  短所:")
            for c in opt['cons']:
                lines.append(f"    - {c}")
            lines.append(f"  コスト: {opt['cost']}")
            lines.append(f"  複雑さ: {opt['complexity']}")
            lines.append(f"  適する場面: {opt['when_to_use']}")
            lines.append("")
        return "\n".join(lines)
 
 
# タイムライン配信のトレードオフ分析
analysis = TradeoffAnalysis("タイムライン配信方式の選択")
 
analysis.add_option(
    "Fan-out on Write (プッシュモデル)",
    pros=[
        "タイムライン読み込みが高速（事前計算済み）",
        "読み込みQPSが高くても対応可能",
        "実装がシンプル（読み側）",
    ],
    cons=[
        "フォロワー数が多いユーザーの投稿時に大量の書き込み発生",
        "有名人（100万フォロワー）の投稿で書き込みQPSが爆発",
        "ストレージコストが高い（各ユーザーのタイムラインを保存）",
    ],
    cost="ストレージ: 高い、計算: 書き込み時に集中",
    complexity="中程度",
    when_to_use="フォロワー数の上限が低いサービス、読み込みが書き込みより圧倒的に多い場合",
)
 
analysis.add_option(
    "Fan-out on Read (プルモデル)",
    pros=[
        "書き込みが軽量（自分のフィードに書くだけ）",
        "有名人のツイートでも負荷が偏らない",
        "ストレージ効率が良い",
    ],
    cons=[
        "タイムライン表示時に全フォロイーの投稿を集約する必要あり",
        "レイテンシが高い（リアルタイム集約）",
        "フォロイーが多いユーザーの読み込みが遅い",
    ],
    cost="ストレージ: 低い、計算: 読み込み時に集中",
    complexity="中程度",
    when_to_use="書き込みQPSが非常に高い場合、フォロイー数が少ない場合",
)
 
analysis.add_option(
    "ハイブリッドアプローチ（Twitterの実方式）",
    pros=[
        "一般ユーザーはプッシュ、有名人はプルで最適化",
        "両方の長所を享受できる",
        "実際にTwitterが採用している実績あり",
    ],
    cons=[
        "実装が複雑（2つのパスを管理）",
        "「有名人」の閾値設定が必要",
        "デバッグが困難",
    ],
    cost="ストレージ: 中程度、計算: 分散",
    complexity="高い",
    when_to_use="大規模SNSで、フォロワー数のばらつきが大きい場合",
)
 
print(analysis.analyze())
 
# 出力:
# === トレードオフ分析: タイムライン配信方式の選択 ===
#
# 【選択肢1】Fan-out on Write (プッシュモデル)
#   長所:
#     + タイムライン読み込みが高速（事前計算済み）
#     + 読み込みQPSが高くても対応可能
#     + 実装がシンプル（読み側）
#   短所:
#     - フォロワー数が多いユーザーの投稿時に大量の書き込み発生
#     ...以下略

# 設計ドキュメントのテンプレートを生成
class DesignDocTemplate:
    """Design Doc / RFCのテンプレート"""
 
    SECTIONS = [
        ("1. タイトルとメタデータ", [
            "プロジェクト名",
            "著者",
            "レビュアー",
            "ステータス (Draft / In Review / Approved / Implemented / Deprecated)",
            "最終更新日",
        ]),
        ("2. 概要 (Summary)", [
            "1段落で何を・なぜ・どのように解決するかを記述",
            "非技術者にも理解できるレベルで記載",
        ]),
        ("3. 背景と動機 (Background & Motivation)", [
            "なぜこの設計が必要なのか",
            "現状の問題点は何か",
            "ビジネス上の影響は何か",
        ]),
        ("4. 要件 (Requirements)", [
            "機能要件 (Must/Should/Could/Won't)",
            "非機能要件 (性能、可用性、セキュリティ等)",
            "制約条件",
        ]),
        ("5. 提案する設計 (Proposed Design)", [
            "アーキテクチャ図",
            "コンポーネント説明",
            "API設計",
            "データモデル/スキーマ",
            "主要なシーケンス図",
        ]),
        ("6. 代替案 (Alternatives Considered)", [
            "検討した他のアプローチと不採用の理由",
            "※最低2つの代替案を記載する",
        ]),
        ("7. トレードオフ (Trade-offs)", [
            "今回の設計で受け入れたトレードオフ",
            "将来変更が必要になる可能性のある箇所",
        ]),
        ("8. マイルストーン (Milestones)", [
            "フェーズ分けと各フェーズの成果物",
            "スケジュール概算",
        ]),
        ("9. セキュリティ考慮事項 (Security Considerations)", [
            "認証/認可",
            "データ暗号化",
            "既知のリスクと対策",
        ]),
        ("10. テスト計画 (Test Plan)", [
            "ユニットテスト",
            "統合テスト",
            "負荷テスト",
            "カオスエンジニアリング",
        ]),
        ("11. 監視とアラート (Monitoring & Alerting)", [
            "主要メトリクス（SLI/SLO）",
            "アラート条件",
            "ダッシュボード設計",
        ]),
        ("12. オープンクエスチョン (Open Questions)", [
            "まだ決まっていない事項",
            "レビューで議論が必要な事項",
        ]),
    ]
 
    @classmethod
    def generate(cls) -> str:
        lines = ["# [プロジェクト名] Design Doc\n"]
        for section, items in cls.SECTIONS:
            lines.append(f"## {section}\n")
            for item in items:
                lines.append(f"- {item}")
            lines.append("")
        return "\n".join(lines)
 
print(DesignDocTemplate.generate())

# 演習1のスケルトンコード
 
class URLShortenerRequirements:
    """URL短縮サービスの要件定義"""
 
    def define_requirements(self):
        """ここに要件を記述"""
        # TODO: 機能要件
        functional = [
            # "長いURLを短いURLに変換する",
            # "短いURLにアクセスすると元のURLにリダイレクトする",
            # ...
        ]
 
        # TODO: 非機能要件
        non_functional = {
            # "レイテンシ": "リダイレクト < 100ms (P99)",
            # "可用性": "99.99%",
            # ...
        }
 
        return functional, non_functional
 
    def estimate(self):
        """ここに見積もりを記述"""
        # TODO: DAUの仮定
        dau = 0  # ???
 
        # TODO: QPS計算
        write_qps = 0  # ???
        read_qps = 0   # ???
 
        # TODO: ストレージ計算
        # 1レコードあたりのサイズは？
        # 保存期間は？
 
        return {
            "dau": dau,
            "write_qps": write_qps,
            "read_qps": read_qps,
        }

# 演習2のスケルトンコード
 
class ChatSystemDesign:
    """チャットシステムの設計"""
 
    def requirements(self):
        """要件定義"""
        pass  # TODO
 
    def high_level_design(self):
        """高レベル設計（ASCII図）"""
        diagram = """
        TODO: ここに構成図を描く
 
        ヒント: 以下のコンポーネントを含める
        - WebSocket Gateway（リアルタイム通信）
        - Chat Service（メッセージ処理）
        - Presence Service（オンライン状態管理）
        - Notification Service（プッシュ通知）
        - Message Store（メッセージ永続化）
        - File Storage（ファイル添付）
        """
        return diagram
 
    def data_flow(self):
        """メッセージ送信のデータフロー"""
        pass  # TODO: A → B にメッセージを送る際の全ステップ
 
    def db_schema(self):
        """DBスキーマ設計"""
        pass  # TODO: users, conversations, messages テーブル

# 問題のあるシステム設計
"""
現状のECサイト設計:
- 単一のモノリスアプリケーション (Python/Django)
- 単一のPostgreSQL (16 vCPU, 64GB RAM)
- セッションはDjangoのDB-backedセッション
- 画像はローカルファイルシステムに保存
- 全文検索はPostgreSQLのLIKE検索
- バッチ処理はcronジョブ
- デプロイは手動SSH + git pull
- モニタリングはなし
- DAU: 50万、今後1年で200万に成長予定
 
問題:
1. ピーク時（セール期間）にDBのCPU使用率が95%に達する
2. 商品検索が遅い（2-3秒）
3. 画像の読み込みが遅い（特に海外ユーザー）
4. デプロイ時にダウンタイムが発生
5. 障害発生時に原因特定に時間がかかる
"""
 
# TODO: 上記の各問題に対して、以下の形式で改善提案を行う
# 1. 問題の根本原因分析
# 2. 短期的な改善案（1-2週間で実施可能）
# 3. 中期的な改善案（1-3か月で実施可能）
# 4. 各改善案のトレードオフ