Tech Debt Didn't Start with AI

# 代码债务的典型例子
def calculate_price(order, customer):
    # 硬编码折扣规则，散落在代码各处
    discount = 0.1  # 基础折扣
    if customer.type == 'vip':
        discount = 0.15
    if customer.age > 60:
        discount = 0.2
    if order.total > 1000:
        discount += 0.05
    if customer.registered_year < 2020:
        discount += 0.03
    # ... 更多硬编码规则

    return order.total * (1 - discount)

# 问题：
# 1. 折扣规则分散在各处，没有统一管理
# 2. 每加一个规则要改这个函数
# 3. 测试困难，无法覆盖所有组合
# 4. 规则之间可能有冲突

# 架构债务的典型例子：越来越难改的订单服务
class OrderService:
    def __init__(self):
        self.db = LegacyDatabaseConnection()
        self.cache = InMemoryCache()
        self.email_sender = EmailService()
        self.sms_sender = SmsService()
        self.payment_gateway = PaymentGateway()
        self.inventory_system = InventorySystem()
        self.accounting_system = AccountingSystem()

    def create_order(self, order_data):
        # 订单创建牵涉 7 个系统的调用
        # 没有事务边界，任何一步失败都不知道回滚到哪里
        # 每个系统有自己的 error handling 逻辑
        # 每次加新需求要在 OrderService 里加 if-else

        self.db.save(order_data)
        self.inventory_system.reserve(order_data['items'])
        self.payment_gateway.charge(order_data['payment'])
        self.accounting_system.record(order_data)
        self.email_sender.send_confirmation(order_data['customer_email'])
        self.sms_sender.send_sms(order_data['customer_phone'], "Order confirmed")
        return order_data

# 问题：
# 1. OrderService 知道太多，违反单一职责原则
# 2. 系统间耦合严重，改一个会影响其他
# 3. 无法独立测试每个系统
# 4. 任何改动都是高风险的

# 测试债务的典型例子：遗留代码的脆弱测试
def test_calculate_price_vip_order():
    """这个测试测的是实现细节，不是业务逻辑"""
    order = MagicMock()
    order.total = 1500

    customer = MagicMock()
    customer.type = 'vip'
    customer.age = 65
    customer.registered_year = 2019

    result = calculate_price(order, customer)

    # 硬编码的期望值，没有业务意义
    assert result == 1125.0  # 这个数字怎么算出来的？

    # 问题：
    # 1. 测试依赖实现细节，重构后测试就废
    # 2. 业务规则变化（折扣调整）要改很多测试
    # 3. 无法表达"真实业务场景"
    # 4. 没有测试边界条件（负数、空订单等）

# 文档债务的典型例子：README 跟代码对不上

## 用户认证流程

> 上次更新：2021-03
> 最近更新代码：2023-08

1. 用户提交表单
2. 后端验证密码
3. 返回 JWT token
4. 前端存储 token

---

实际代码流程（2023-08 更新后）：
1. 用户提交表单
2. 后端调用 SSO 服务（已移除密码验证）
3. 返回 OAuth token（已移除 JWT）
4. 前端存储在 httpOnly cookie（已变更存储方式）

# 典型的时间压力决策
def sprint_planning(stories, velocity):
    """时间压力决策的数学"""
    story_points = sum(s['points'] for s in stories)
    capacity = velocity * 0.8  # 留 20% buffer 是常识

    if story_points > capacity:
        # 决策时刻：砍需求还是欠 tech debt？
        # 实际情况：砍需求阻力大，欠 tech debt 阻力小
        # 因为"我们先上线，功能都有了，以后再优化"
        return stories  # 一个都不砍，直接欠债

    return stories

# 知识断层的典型例子：三年前写的代码，没人敢动
class OldPaymentProcessor:
    """
    警告：这段代码是 2019 年写的，
    @zhangsan 说是支付逻辑，但没人知道为什么这样写
    2019-2022 年期间有 3 个人试图重构，都失败了
    当前状态：能跑，但不理解
    """

    def process(self, payment_data):
        # 为什么要转成字符串再转回来？
        # 为什么要 sleep 3 秒？
        # 为什么这里有个 try except pass？
        try:
            result = self._legacy_api_call(
                str(payment_data).encode('gbk')  # GBK...认真的吗？
            )
            time.sleep(3)  # 3 秒延迟是为什么？
        except:
            pass  # 吞掉所有异常是故意的吗？

        return self._parse_result(result)

# 技术选型失误的典型例子：选了"最先进"的技术栈
# 2019 年：
from exciting_new_framework import GreatFeature  # 当时最火的新框架

# 2021 年：GreatFeature 停止维护
# 2023 年：安全漏洞，无人修复
# 2026 年：升级到新框架需要重写 80% 的代码

# 现在的状态：
# 1. 框架过时，没人了解
# 2. 招聘困难，市场上没有人才
# 3. 升级成本等于重写
# 4. 但业务已经重度依赖，改不动

# 组织结构导致的 tech debt
"""
团队 A（负责用户模块）和团队 B（负责支付模块）
两个团队独立开发，通过 API 集成

问题：
1. 用户地址校验逻辑在用户模块，支付模块需要地址验证时调用用户模块 API
2. 但两个模块有独立的数据模型，地址数据结构不一致
3. 每次"用户修改地址"要同时更新两个地方
4. API 调用的额外延迟和错误处理增加了复杂度

根本原因：
团队边界和业务边界不一致。
如果"地址"是一个独立的领域实体，应该是一个团队负责。
但组织结构决定了它在两个地方被重复定义。
"""

# Tech debt 的来源不是代码，是组织的边界划分

def measure_tech_debt(project_path):
    """
    量化 tech debt 的基础指标
    """

    metrics = {
        # 代码债务指标
        "code_duplication_rate": calculate_duplication(project_path),
        "complexity_per_file": calculate_complexity(project_path),
        "comment_to_code_ratio": calculate_comment_ratio(project_path),
        "naming_violations": count_naming_issues(project_path),

        # 架构债务指标
        "cyclic_dependencies": count_cycles(project_path),
        "module_coupling": calculate_coupling(project_path),
        "architectural_violations": count_arch_violations(project_path),

        # 测试债务指标
        "test_coverage": calculate_coverage(project_path),
        "flaky_tests_rate": calculate_flaky_rate(project_path),
        "test_maintenance_burden": calculate_test_maintenance(project_path),

        # 文档债务指标
        "outdated_docs_rate": calculate_doc_currency(project_path),
        "api_documented_rate": calculate_api_docs(project_path),
    }

    return metrics

# 关键洞察：如果你不测量，就无法管理
# 很多团队不知道 tech debt 有多少，因为从来没有量化过

def create_tech_debt_dashboard(metrics):
    """
    Tech Debt 可视化仪表板
    """

    # 红绿灯系统：让 tech debt 状态一目了然
    dashboard = {
        "code_debt": {
            "status": "red" if metrics["code_duplication_rate"] > 0.15 else "yellow",
            "score": metrics["code_duplication_rate"],
            "trend": "increasing",  # 债务在增长还是减少
            "top_5_files": get_worst_5_files(metrics),
        },
        "architecture_debt": {
            "status": "yellow",
            "critical_violations": metrics["cyclic_dependencies"],
            "refactoring_units": count_refactoring_units(metrics),
        },
        "test_debt": {
            "status": "red",
            "coverage": f"{metrics['test_coverage']}%",
            "flaky_tests": metrics["flaky_tests_rate"],
        }
    }

    return dashboard

# 关键洞察：让 tech debt 可见，让它成为优先级讨论的一部分
# 不要让 tech debt 只存在于开发者的脑海里

def feature_debt_tradeoff(user_story, tech_debt_impact):
    """
    把 tech debt 纳入产品决策
    """

    """
    当产品团队决定做功能 X 时，技术团队应该提供：
    1. 功能价值：做 vs 不做的区别
    2. 开发成本：这个功能需要多少时间
    3. Tech Debt 影响：这个功能会加重多少 tech debt
    4. Future Cost：现在不还债，以后还要额外多少成本

    示例输出：
    功能：实时通知系统
    开发成本：2 周
    Tech Debt 影响：中等（需要引入新的消息队列服务）
    Future Cost：如果 6 个月后再做，同样功能需要 4 周（因为要整合已有代码）
    Net Value：现在做 vs 以后做 = 节省 2 周 + 降低 6 个月的技术风险
    """

    # 技术负责人应该把这种分析带到产品规划会议上
    # 不要让产品团队以为 tech debt 是"免费的"

def allocate_debt_repayment(sprint_capacity, tech_debt_dashboard):
    """
    在 sprint 中分配还债时间
    """

    """
    经验法则：20% 规则
    每个 sprint 预留 20% 的时间用于还 tech debt

    原因：
    - 如果不预留，tech debt 会无限积累
    - 20% 是足够可观的还债时间，又不影响交付
    - 持续的小规模还债比一次性大规模重构风险低

    分配优先级：
    1. 高流量、高变更频率的代码优先
    2. 影响系统稳定性的债务优先
    3. 拖累开发效率的债务优先
    """

    total_capacity = sprint_capacity
    feature_work = total_capacity * 0.8
    debt_repayment = total_capacity * 0.2

    # 债务还清优先级排序
    debt_priority = prioritize_debt(tech_debt_dashboard)

    return {
        "feature_capacity": feature_work,
        "debt_capacity": debt_repayment,
        "top_debt_to_address": debt_priority[:3]  # 这个 sprint 专注解决前 3 个
    }

# AI 辅助的 tech debt 管理
def ai_assisted_debt_management():

    # 1. Tech Debt 检测
    # AI 可以分析代码库，识别潜在的 tech debt
    def detect_debt_patterns(codebase):
        """AI 检测常见的 tech debt 模式"""
        patterns = [
            "magic_numbers",  # 硬编码数字
            "copy_paste_code",  # 重复代码
            "complex_conditionals",  # 复杂条件
            "god_classes",  # 上帝类
            "circular_dependencies",  # 循环依赖
        ]
        return ai_analyze(codebase, patterns)

    # 2. 重构建议
    # AI 可以提供重构建议和代码示例
    def suggest_refactoring(debt_item):
        """AI 生成重构建议"""
        return ai_generate_refactor_plan(debt_item)

    # 3. 测试生成
    # AI 可以帮助补齐测试债务
    def generate_missing_tests(code_coverage):
        """AI 补全测试覆盖"""
        uncovered = find_uncovered_code(code_coverage)
        return ai_generate_tests(uncovered)

    # 4. 文档同步
    # AI 可以帮助更新过时的文档
    def sync_documentation(code_change, docs):
        """AI 同步文档和代码"""
        return ai_update_docs(code_change, docs)