根节点：效用（Utility）/ 业务目标
  ↓
第一层：质量属性（Performance, Availability, Security, ...）
  ↓
第二层：质量属性细化（Latency, Throughput, Fault Tolerance, ...）
  ↓
第三层：具体场景（带优先级的质量属性场景）

效用
├── 性能
│   ├── 响应时间
│   │   ├── [H] 首页加载时间 < 2 秒（正常负载）
│   │   ├── [H] 搜索响应时间 < 1 秒
│   │   └── [M] 报表生成时间 < 30 秒
│   └── 吞吐量
│       ├── [H] 支持 1000 QPS
│       └── [L] 批量处理 10 万条/小时
├── 可用性
│   ├── 故障恢复
│   │   ├── [H] 数据库故障恢复时间 < 30 秒
│   │   └── [M] 服务重启时间 < 5 分钟
│   └── 容错
│       ├── [H] 单点故障不影响整体服务
│       └── [L] 计划内维护无需停机
├── 安全性
│   ├── 数据保护
│   │   ├── [H] 用户密码加密存储
│   │   └── [M] 敏感数据传输加密
│   └── 访问控制
│       ├── [H] 未授权访问被阻止
│       └── [M] 操作审计日志完整
└── 可修改性
    ├── 代码变更
    │   ├── [M] 添加新支付方式 < 5 人天
    │   └── [L] 修改 UI 布局 < 1 人天
    └── 配置变更
        └── [M] 调整业务规则无需重新部署

准备：
- 架构师准备架构文档和效用树草案
- 邀请开发、测试、运维代表参与

执行：
- 架构师展示设计
- 团队一起完善效用树
- 针对高优先级场景分析架构
- 识别风险和权衡点

结果：
- 发现 3 个高风险项
- 识别 5 个需要进一步验证的技术点
- 制定原型验证计划

方案 A：关系型数据库
方案 B：NoSQL 数据库

效用树分析：
- 性能：B 在高并发写入上更好
- 一致性：A 更强
- 可维护性：A 更成熟，人才更多
- 成本：B 可能需要更多服务器

权衡点：
- 一致性 vs 性能
- 成熟度 vs 扩展性

决策：根据业务优先级选择

步骤：
1. 梳理当前架构
2. 构建效用树（基于当前业务需求）
3. 分析架构对关键场景的支持
4. 识别技术债务和风险
5. 制定重构优先级

发现：
- 单体架构导致部署困难
- 缺乏自动化测试
- 数据库耦合严重

行动：
- 引入 CI/CD
- 补充关键路径测试
- 逐步剥离独立模块

"""
效用树工具
用于构建、分析和可视化 ATAM 效用树
"""

from dataclasses import dataclass, field
from typing import List, Optional, Dict
from enum import Enum


class Priority(Enum):
    """场景优先级"""
    HIGH = "H"
    MEDIUM = "M"
    LOW = "L"


class QualityAttribute(Enum):
    """质量属性"""
    PERFORMANCE = "性能"
    AVAILABILITY = "可用性"
    SECURITY = "安全性"
    MODIFIABILITY = "可修改性"
    TESTABILITY = "可测试性"
    DEPLOYABILITY = "可部署性"


@dataclass
class Scenario:
    """质量属性场景"""
    description: str
    quality_attribute: QualityAttribute
    sub_attribute: str
    priority: Priority
    source: str = ""
    stimulus: str = ""
    environment: str = ""
    artifact: str = ""
    response: str = ""
    response_measure: str = ""
    
    def __str__(self):
        return f"[{self.priority.value}] {self.description}"


@dataclass
class QualityNode:
    """质量属性节点"""
    name: str
    sub_attributes: Dict[str, List[Scenario]] = field(default_factory=dict)
    
    def add_scenario(self, sub_attr: str, scenario: Scenario):
        if sub_attr not in self.sub_attributes:
            self.sub_attributes[sub_attr] = []
        self.sub_attributes[sub_attr].append(scenario)
    
    def get_scenarios_by_priority(self, priority: Priority) -> List[Scenario]:
        scenarios = []
        for sub_scenarios in self.sub_attributes.values():
            scenarios.extend([s for s in sub_scenarios if s.priority == priority])
        return scenarios
    
    def get_all_scenarios(self) -> List[Scenario]:
        scenarios = []
        for sub_scenarios in self.sub_attributes.values():
            scenarios.extend(sub_scenarios)
        return scenarios


class UtilityTree:
    """效用树"""
    
    def __init__(self, business_goal: str):
        self.business_goal = business_goal
        self.nodes: Dict[QualityAttribute, QualityNode] = {}
    
    def add_quality_attribute(self, attr: QualityAttribute, name: str = None):
        """添加质量属性节点"""
        node_name = name or attr.value
        self.nodes[attr] = QualityNode(node_name)
    
    def add_scenario(self, attr: QualityAttribute, sub_attr: str, scenario: Scenario):
        """添加场景"""
        if attr not in self.nodes:
            self.add_quality_attribute(attr)
        self.nodes[attr].add_scenario(sub_attr, scenario)
    
    def get_high_priority_scenarios(self) -> List[Scenario]:
        """获取所有高优先级场景"""
        scenarios = []
        for node in self.nodes.values():
            scenarios.extend(node.get_scenarios_by_priority(Priority.HIGH))
        return scenarios
    
    def get_scenarios_by_attribute(self, attr: QualityAttribute) -> List[Scenario]:
        """获取特定质量属性的所有场景"""
        if attr in self.nodes:
            return self.nodes[attr].get_all_scenarios()
        return []
    
    def print_tree(self):
        """打印效用树"""
        print(f"\n{'=' * 60}")
        print(f"效用树: {self.business_goal}")
        print(f"{'=' * 60}")
        
        for attr, node in self.nodes.items():
            print(f"\n├── {attr.value}")
            for sub_attr, scenarios in node.sub_attributes.items():
                print(f"│   ├── {sub_attr}")
                for scenario in sorted(scenarios, key=lambda s: s.priority.value):
                    print(f"│   │   └── {scenario}")
    
    def analyze(self) -> Dict:
        """分析效用树"""
        total_scenarios = sum(
            len(node.get_all_scenarios()) for node in self.nodes.values()
        )
        high_priority = sum(
            len(node.get_scenarios_by_priority(Priority.HIGH)) 
            for node in self.nodes.values()
        )
        medium_priority = sum(
            len(node.get_scenarios_by_priority(Priority.MEDIUM)) 
            for node in self.nodes.values()
        )
        low_priority = sum(
            len(node.get_scenarios_by_priority(Priority.LOW)) 
            for node in self.nodes.values()
        )
        
        return {
            "total": total_scenarios,
            "high": high_priority,
            "medium": medium_priority,
            "low": low_priority,
            "attributes_covered": len(self.nodes)
        }


# ==================== 示例使用 ====================

def build_sample_utility_tree():
    """构建示例效用树"""
    tree = UtilityTree("提升电商平台用户体验和运营效率")
    
    # 性能
    tree.add_scenario(
        QualityAttribute.PERFORMANCE,
        "响应时间",
        Scenario(
            description="首页加载时间 < 2 秒（正常负载）",
            quality_attribute=QualityAttribute.PERFORMANCE,
            sub_attribute="响应时间",
            priority=Priority.HIGH,
            source="终端用户",
            stimulus="访问首页",
            environment="正常负载",
            artifact="前端页面",
            response="页面完全渲染",
            response_measure="P95 加载时间 < 2 秒"
        )
    )
    
    tree.add_scenario(
        QualityAttribute.PERFORMANCE,
        "响应时间",
        Scenario(
            description="搜索响应时间 < 1 秒",
            quality_attribute=QualityAttribute.PERFORMANCE,
            sub_attribute="响应时间",
            priority=Priority.HIGH,
            source="终端用户",
            stimulus="执行搜索",
            environment="正常负载",
            artifact="搜索服务",
            response="返回搜索结果",
            response_measure="P95 响应时间 < 1 秒"
        )
    )
    
    tree.add_scenario(
        QualityAttribute.PERFORMANCE,
        "吞吐量",
        Scenario(
            description="支持 1000 QPS",
            quality_attribute=QualityAttribute.PERFORMANCE,
            sub_attribute="吞吐量",
            priority=Priority.HIGH,
            source="系统负载",
            stimulus="并发请求",
            environment="促销活动期间",
            artifact="整个系统",
            response="正常处理请求",
            response_measure="QPS >= 1000, 错误率 < 1%"
        )
    )
    
    # 可用性
    tree.add_scenario(
        QualityAttribute.AVAILABILITY,
        "故障恢复",
        Scenario(
            description="数据库故障恢复时间 < 30 秒",
            quality_attribute=QualityAttribute.AVAILABILITY,
            sub_attribute="故障恢复",
            priority=Priority.HIGH,
            source="数据库服务器",
            stimulus="主数据库故障",
            environment="生产环境",
            artifact="数据访问层",
            response="自动切换到备用数据库",
            response_measure="恢复时间 < 30 秒，无数据丢失"
        )
    )
    
    tree.add_scenario(
        QualityAttribute.AVAILABILITY,
        "容错",
        Scenario(
            description="单点故障不影响整体服务",
            quality_attribute=QualityAttribute.AVAILABILITY,
            sub_attribute="容错",
            priority=Priority.HIGH,
            source="任何服务实例",
            stimulus="单个服务实例故障",
            environment="正常运行",
            artifact="负载均衡器",
            response="流量自动转移到其他实例",
            response_measure="用户无感知，错误率不增加"
        )
    )
    
    # 安全性
    tree.add_scenario(
        QualityAttribute.SECURITY,
        "数据保护",
        Scenario(
            description="用户密码加密存储",
            quality_attribute=QualityAttribute.SECURITY,
            sub_attribute="数据保护",
            priority=Priority.HIGH,
            source="数据库管理员",
            stimulus="直接访问数据库",
            environment="任何时候",
            artifact="用户数据存储",
            response="密码以哈希形式存储",
            response_measure="100% 密码加盐哈希，无法逆向"
        )
    )
    
    tree.add_scenario(
        QualityAttribute.SECURITY,
        "访问控制",
        Scenario(
            description="未授权访问被阻止",
            quality_attribute=QualityAttribute.SECURITY,
            sub_attribute="访问控制",
            priority=Priority.HIGH,
            source="恶意用户",
            stimulus="尝试访问他人订单",
            environment="任何时候",
            artifact="订单服务",
            response="拒绝访问并记录",
            response_measure="100% 未授权访问被阻止"
        )
    )
    
    # 可修改性
    tree.add_scenario(
        QualityAttribute.MODIFIABILITY,
        "代码变更",
        Scenario(
            description="添加新支付方式 < 5 人天",
            quality_attribute=QualityAttribute.MODIFIABILITY,
            sub_attribute="代码变更",
            priority=Priority.MEDIUM,
            source="产品经理",
            stimulus="要求集成新的支付渠道",
            environment="系统已上线",
            artifact="支付模块",
            response="实现新支付适配器并部署",
            response_measure="开发工作量 < 5 人天，不影响现有支付"
        )
    )
    
    return tree


if __name__ == "__main__":
    tree = build_sample_utility_tree()
    
    # 打印效用树
    tree.print_tree()
    
    # 分析
    analysis = tree.analyze()
    print(f"\n{'=' * 60}")
    print("效用树分析")
    print(f"{'=' * 60}")
    print(f"总场景数: {analysis['total']}")
    print(f"高优先级: {analysis['high']}")
    print(f"中优先级: {analysis['medium']}")
    print(f"低优先级: {analysis['low']}")
    print(f"覆盖质量属性: {analysis['attributes_covered']}")
    
    # 获取高优先级场景
    print(f"\n{'=' * 60}")
    print("高优先级场景列表")
    print(f"{'=' * 60}")
    for i, scenario in enumerate(tree.get_high_priority_scenarios(), 1):
        print(f"{i}. {scenario.description}")

"""
ATAM 评估报告生成器
"""

from dataclasses import dataclass, field
from typing import List, Dict
from datetime import datetime


@dataclass
class SensitivityPoint:
    """敏感点"""
    decision: str
    quality_attribute: str
    impact: str


@dataclass
class TradeoffPoint:
    """权衡点"""
    decision: str
    positive_impact: Dict[str, str]  # 质量属性 -> 正面影响
    negative_impact: Dict[str, str]  # 质量属性 -> 负面影响


@dataclass
class Risk:
    """风险"""
    description: str
    category: str  # 技术、实施、演进、运营
    likelihood: str  # 高、中、低
    impact: str  # 高、中、低
    mitigation: str


@dataclass
class Theme:
    """主题"""
    description: str
    related_decisions: List[str]
    recommendation: str


class ATAMReport:
    """ATAM 评估报告"""
    
    def __init__(self, system_name: str, evaluation_date: datetime):
        self.system_name = system_name
        self.evaluation_date = evaluation_date
        self.sensitivity_points: List[SensitivityPoint] = []
        self.tradeoff_points: List[TradeoffPoint] = []
        self.risks: List[Risk] = []
        self.themes: List[Theme] = []
    
    def add_sensitivity_point(self, sp: SensitivityPoint):
        self.sensitivity_points.append(sp)
    
    def add_tradeoff_point(self, tp: TradeoffPoint):
        self.tradeoff_points.append(tp)
    
    def add_risk(self, risk: Risk):
        self.risks.append(risk)
    
    def add_theme(self, theme: Theme):
        self.themes.append(theme)
    
    def generate_report(self) -> str:
        """生成评估报告"""
        lines = [
            "=" * 70,
            f"ATAM 架构评估报告",
            "=" * 70,
            f"系统名称: {self.system_name}",
            f"评估日期: {self.evaluation_date.strftime('%Y-%m-%d')}",
            f"评估团队: [评估团队名称]",
            "",
            "-" * 70,
            "一、敏感点分析",
            "-" * 70,
        ]
        
        for i, sp in enumerate(self.sensitivity_points, 1):
            lines.extend([
                f"\n{i}. 架构决策: {sp.decision}",
                f"   影响质量属性: {sp.quality_attribute}",
                f"   影响说明: {sp.impact}",
            ])
        
        lines.extend([
            "",
            "-" * 70,
            "二、权衡点分析",
            "-" * 70,
        ])
        
        for i, tp in enumerate(self.tradeoff_points, 1):
            lines.extend([
                f"\n{i}. 架构决策: {tp.decision}",
                f"   正面影响:",
            ])
            for attr, impact in tp.positive_impact.items():
                lines.append(f"     + {attr}: {impact}")
            lines.append(f"   负面影响:")
            for attr, impact in tp.negative_impact.items():
                lines.append(f"     - {attr}: {impact}")
        
        lines.extend([
            "",
            "-" * 70,
            "三、风险评估",
            "-" * 70,
        ])
        
        # 按风险等级排序
        sorted_risks = sorted(
            self.risks,
            key=lambda r: ({"高": 3, "中": 2, "低": 1}.get(r.likelihood, 0) * 
                          {"高": 3, "中": 2, "低": 1}.get(r.impact, 0)),
            reverse=True
        )
        
        for i, risk in enumerate(sorted_risks, 1):
            lines.extend([
                f"\n{i}. 风险描述: {risk.description}",
                f"   类别: {risk.category}",
                f"   可能性: {risk.likelihood} | 影响: {risk.impact}",
                f"   缓解措施: {risk.mitigation}",
            ])
        
        lines.extend([
            "",
            "-" * 70,
            "四、主题分析",
            "-" * 70,
        ])
        
        for i, theme in enumerate(self.themes, 1):
            lines.extend([
                f"\n{i}. 主题: {theme.description}",
                f"   相关决策: {', '.join(theme.related_decisions)}",
                f"   建议: {theme.recommendation}",
            ])
        
        lines.extend([
            "",
            "=" * 70,
            "五、总结与建议",
            "=" * 70,
            "",
            f"本次评估共发现:",
            f"- 敏感点: {len(self.sensitivity_points)} 个",
            f"- 权衡点: {len(self.tradeoff_points)} 个",
            f"- 风险: {len(self.risks)} 个",
            f"- 主题: {len(self.themes)} 个",
            "",
            "优先行动项:",
        ])
        
        # 列出高风险项
        high_risks = [r for r in self.risks if r.likelihood == "高" and r.impact == "高"]
        if high_risks:
            for risk in high_risks:
                lines.append(f"- [紧急] {risk.description}")
                lines.append(f"  缓解: {risk.mitigation}")
        
        lines.extend([
            "",
            "=" * 70,
            "报告结束",
            "=" * 70,
        ])
        
        return "\n".join(lines)


# ==================== 示例使用 ====================

if __name__ == "__main__":
    report = ATAMReport("电商订单系统", datetime.now())
    
    # 添加敏感点
    report.add_sensitivity_point(SensitivityPoint(
        decision="使用 Redis 缓存热点数据",
        quality_attribute="性能",
        impact="缓存命中率直接影响响应时间，命中率每提升 10%，P95 延迟降低约 20%"
    ))
    
    report.add_sensitivity_point(SensitivityPoint(
        decision="数据库连接池大小设置为 50",
        quality_attribute="性能",
        impact="连接池大小直接影响并发处理能力，过小会导致等待，过大会增加数据库负担"
    ))
    
    # 添加权衡点
    report.add_tradeoff_point(TradeoffPoint(
        decision="引入二级缓存（本地缓存 + Redis）",
        positive_impact={
            "性能": "减少网络往返，响应时间降低 50%",
            "可用性": "Redis 故障时本地缓存仍可提供部分服务"
        },
        negative_impact={
            "一致性": "本地缓存可能导致数据不一致",
            "可维护性": "缓存失效逻辑复杂，增加维护难度"
        }
    ))
    
    report.add_tradeoff_point(TradeoffPoint(
        decision="采用微服务架构",
        positive_impact={
            "可修改性": "服务独立部署，变更影响范围小",
            "可扩展性": "可以针对不同服务独立扩展"
        },
        negative_impact={
            "性能": "服务间调用增加网络延迟",
            "复杂性": "分布式系统带来一致性、事务等挑战"
        }
    ))
    
    # 添加风险
    report.add_risk(Risk(
        description="团队缺乏微服务运维经验",
        category="实施",
        likelihood="高",
        impact="高",
        mitigation="安排培训，引入有经验的顾问，先从少量服务开始"
    ))
    
    report.add_risk(Risk(
        description="数据库分片策略未经过大流量验证",
        category="技术",
        likelihood="中",
        impact="高",
        mitigation="进行压力测试，准备回滚方案"
    ))
    
    report.add_risk(Risk(
        description="第三方支付接口稳定性未知",
        category="运营",
        likelihood="中",
        impact="中",
        mitigation="实现熔断和降级，准备备用支付渠道"
    ))
    
    # 添加主题
    report.add_theme(Theme(
        description="数据一致性在多个场景中都是挑战",
        related_decisions=["二级缓存", "微服务拆分", "数据库分片"],
        recommendation="制定统一的一致性策略，明确哪些场景需要强一致性，哪些可以接受最终一致性"
    ))
    
    report.add_theme(Theme(
        description="对第三方服务的依赖较多，存在外部风险",
        related_decisions=["支付接口", "短信服务", "物流接口"],
        recommendation="为关键第三方服务实现熔断和降级，准备备用方案"
    ))
    
    # 生成报告
    print(report.generate_report())