软件架构师

# ADR-001: [决策标题]

## 状态
提议中 | 已接受 | 已弃用 | 被 ADR-XXX 取代

## 背景
是什么问题促使我们做这个决策？

## 决策
我们提出或实施的变更是什么？

## 备选方案
我们考虑了哪些方案？各自的优缺点？

## 影响
这个变更使什么变得更容易或更难？

# 快速估算系统容量需求
class CapacityEstimate:
    def __init__(self, dau: int, actions_per_user: int):
        self.dau = dau
        self.actions_per_user = actions_per_user

    @property
    def daily_requests(self) -> int:
        return self.dau * self.actions_per_user

    @property
    def peak_qps(self) -> float:
        """假设高峰期流量是平均值的 3 倍，集中在 4 小时内"""
        avg_qps = self.daily_requests / 86400
        return avg_qps * 3

    @property
    def storage_per_year_gb(self) -> float:
        """假设每个请求产生 2KB 数据"""
        return (self.daily_requests * 2 * 1024 * 365) / (1024**3)

    def summary(self) -> str:
        return (
            f"DAU: {self.dau:,}\n"
            f"日请求量: {self.daily_requests:,}\n"
            f"峰值 QPS: {self.peak_qps:.0f}\n"
            f"年存储: {self.storage_per_year_gb:.1f} GB"
        )

# 示例：电商系统
estimate = CapacityEstimate(dau=500_000, actions_per_user=20)
print(estimate.summary())
# DAU: 500,000 | 日请求量: 10,000,000 | 峰值 QPS: 347 | 年存储: 6.8 TB

✅ 正确的依赖方向：
UI层 → 应用层 → 领域层 → 基础设施层
         ↓              ↑（依赖倒置）
       端口接口  ←  适配器实现

❌ 危险信号：
- 领域层引用了框架包（Spring、Django 等）
- 基础设施细节泄漏到 API 响应（数据库 ID 格式、内部错误栈）
- 两个服务互相直接调用（循环依赖）

| 维度         | 权重 | 方案 A（PostgreSQL）| 方案 B（MongoDB）| 方案 C（DynamoDB）|
|-------------|------|--------------------|--------------------|---------------------|
| 查询灵活性   | 30%  | 9                  | 7                  | 4                   |
| 水平扩展能力 | 25%  | 5                  | 7                  | 9                   |
| 运维复杂度   | 20%  | 7                  | 5                  | 9                   |
| 团队熟悉度   | 15%  | 8                  | 6                  | 3                   |
| 成本         | 10%  | 7                  | 6                  | 5                   |
| 加权得分     |      | 7.25               | 6.40               | 6.10                |

阶段 1: 大泥球 → 识别边界，建立模块
阶段 2: 模块化单体 → 模块通过接口通信，可独立测试
阶段 3: 按需拆分 → 只把需要独立扩展/部署的模块拆成服务
阶段 4: 持续演进 → 保持架构适应度函数，防止退化

# 示例：检测模块间的循环依赖
# 在 CI 中运行，失败则阻塞合并
jdeps --module-path target/modules -dotoutput deps.dot
python check_circular_deps.py deps.dot --fail-on-cycle

# 示例：检测领域层对基础设施的非法依赖
grep -r "import.*infrastructure" src/domain/ && echo "领域层不应依赖基础设施层" && exit 1