架构变更案例：让决策不再只记录"当时怎么想的"

# ADR-007: 使用 Redis 作为会话缓存

## 状态
已采纳

## 背景
当前会话存储在 MySQL 中，读写延迟随用户量上升显著增加。

## 决策
采用 Redis 单节点缓存会话数据，MySQL 作为持久化后备。

## 理由
- Redis 单线程模型满足当前 QPS 预估（峰值 5k）
- 团队已有 Redis 运维经验
- 迁移成本可控，可逐步切换

# change-case-007-a.yaml
adr_ref: "ADR-007"
title: "Redis 单节点无法满足流量增长时切换至 Redis Cluster"

trigger:
  condition: "单节点 QPS 持续超过 20k，或延迟 p99 > 50ms"
  likelihood: "高——业务增长曲线显示 6-9 个月内可能触及"

change_path:
  steps:
    - "将单节点扩展为 3 主 3 从 Cluster"
    - "修改客户端连接配置，启用 cluster-aware 模式"
    - "验证会话 key 的 hash tag 分布是否均匀"
    - "灰度切换：先对新注册用户走 Cluster，老用户逐步迁移"

reversibility:
  level: "中等"
  rationale: "Cluster 可缩回单节点，但需重新 slot 迁移，约 2-4 小时窗口"

cost_estimate:
  effort: "2 人 × 3 天（含测试与灰度观察）"
  data_migration: "Redis slot 迁移工具自动完成，无需离线"
  downstream_impact: "客户端需升级驱动版本；3 个消费会话事件的服务需验证兼容性"

assumptions_exposed:
  - "当前 QPS 峰值 5k 不会短期翻 4 倍——实际增长曲线未建模"
  - "会话 key 无跨 slot 聚合查询需求——若后续引入按用户维度聚合，Cluster 方案需重新设计"

"""
scan_change_cases.py
扫描变更案例 YAML 文件，输出触发条件中 likelihood 为"高"的条目，
提醒团队关注即将逼近的架构变更节点。

依赖：pip install pyyaml
运行：python scan_change_cases.py --dir ./change_cases
"""

import argparse
import glob
import yaml
from pathlib import Path


def load_change_cases(directory: str) -> list[dict]:
    cases = []
    for path in glob.glob(str(Path(directory) / "*.yaml")):
        with open(path, "r", encoding="utf-8") as f:
            doc = yaml.safe_load(f)
            if doc and "adr_ref" in doc:
                doc["_source"] = path
                cases.append(doc)
    return cases


def filter_high_likelihood(cases: list[dict]) -> list[dict]:
    return [
        c for c in cases
        if c.get("trigger", {}).get("likelihood", "").startswith("高")
    ]


def print_report(cases: list[dict]):
    if not cases:
        print("✅ 当前无高概率触发变更案例，架构决策短期稳定。")
        return

    print("⚠️  以下变更案例触发概率为"高"，建议在下次迭代规划中复核：\n")
    for c in cases:
        t = c["trigger"]
        print(f"  ADR: {c['adr_ref']}")
        print(f"  变更案例: {c['title']}")
        print(f"  触发条件: {t.get('condition', '未填写')}")
        print(f"  可逆性: {c.get('reversibility', {}).get('level', '未评估')}")
        print(f"  预估代价: {c.get('cost_estimate', {}).get('effort', '未估算')}")
        print(f"  来源文件: {c['_source']}")
        print()


def main():
    parser = argparse.ArgumentParser(description="扫描架构变更案例")
    parser.add_argument("--dir", default="./change_cases", help="变更案例 YAML 目录")
    args = parser.parse_args()

    cases = load_change_cases(args.dir)
    high = filter_high_likelihood(cases)
    print_report(high)


if __name__ == "__main__":
    main()

$ python scan_change_cases.py --dir ./change_cases

⚠️  以下变更案例触发概率为"高"，建议在下次迭代规划中复核：

  ADR: ADR-007
  变更案例: Redis 单节点无法满足流量增长时切换至 Redis Cluster
  触发条件: 单节点 QPS 持续超过 20k，或延迟 p99 > 50ms
  可逆性: 中等
  预估代价: 2 人 × 3 天（含测试与灰度观察）
  来源文件: change_cases/change-case-007-a.yaml