案例 001：用 Agent 改造电商订单系统的缺陷修复流程

┌─────────────────────────────────────────────────────────────────┐
│                        电商平台订单系统                          │
│                                                                 │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐    │
│  │ 订单服务  │──▶│ 支付服务  │──▶│ 退款服务  │──▶│ 物流服务  │    │
│  │ (order)  │   │ (pay)    │   │ (refund) │   │ (ship)   │    │
│  └────┬─────┘   └────┬─────┘   └────┬─────┘   └────┬─────┘    │
│       │              │              │              │            │
│  ┌────▼──────────────▼──────────────▼──────────────▼─────┐      │
│  │              状态机引擎 (StateMachine)                  │      │
│  └───────────────────────────────────────────────────────┘      │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │              Agent 工作台接入层                           │    │
│  │  ┌─────────┐  ┌──────────┐  ┌─────────┐  ┌──────────┐ │    │
│  │  │Issue 解析│→│上下文包生成│→│Agent 修复│→│质量门禁   │ │    │
│  │  └─────────┘  └──────────┘  └─────────┘  └────┬─────┘ │    │
│  └────────────────────────────────────────────────│────────┘    │
│                                                   │             │
│  ┌────────────────────────────────────────────────▼────────┐    │
│  │  审批门禁：涉及金额/支付/退款的修改 → 必须人工审批       │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘

# 订单金额计算 Bug 的 Agent 上下文包
bugfix_context:
  issue: "#BUG-2341"
  error_log: |
    AssertionError: order.total_amount = -15.00, expected >= 0
    at OrderService.calculate_total (app/order/service.py:287)
  
  # Agent 可以读取的文件
  allowed_files:
    - app/order/service.py        # 订单服务核心逻辑
    - app/order/models.py         # 订单数据模型
    - app/coupon/calculator.py    # 优惠券计算
    - app/order/tests/test_total.py  # 已有测试
  
  # 业务规则（注入到 Prompt）
  business_rules:
    - "订单金额不能小于 0"
    - "满减券抵扣不能超过订单原价的 80%"
    - "运费不参与满减计算"
  
  # 约束
  constraints:
    max_patch_lines: 15
    must_add_test: true
    approval_required: true  # 涉及金额，需审批

# 支付幂等性 Bug 上下文包
bugfix_context:
  issue: "#BUG-2356"
  error_log: |
    OrderStatusError: Cannot transition from 'paid' to 'paid'
    at OrderStateMachine.transition (app/common/state.py:45)
    triggered by PayCallbackHandler.handle (app/pay/callback.py:89)
  
  allowed_files:
    - app/pay/callback.py         # 支付回调处理
    - app/common/state.py         # 状态机
    - app/order/models.py         # 订单模型
    - app/pay/tests/test_callback.py
  
  business_rules:
    - "支付回调必须幂等：相同交易号重复回调不改变状态"
    - "回调处理使用数据库事务 + 行锁"
  
  constraints:
    max_patch_lines: 20
    must_add_test: true
    approval_required: true  # 涉及支付，需审批

# app/pay/callback.py 修复后

class PayCallbackHandler:
    def handle(self, callback_data):
        transaction_id = callback_data["transaction_id"]
        
        # 幂等检查 1：Redis 分布式锁（快速路径）
        lock_key = f"pay_callback:{transaction_id}"
        if not self.redis.set(lock_key, "1", nx=True, ex=3600):
            # 已有处理中的锁，可能是重复回调
            existing_order = self.order_repo.get_by_transaction(transaction_id)
            if existing_order and existing_order.status == "paid":
                return {"status": "already_processed"}  # 幂等返回
        
        # 幂等检查 2：数据库事务 + 行锁
        with db.atomic():
            order = Order.select().where(
                Order.transaction_id == transaction_id
            ).for_update().first()
            
            if order.status == "paid":
                return {"status": "already_processed"}
            
            order.status = "paid"
            order.paid_at = datetime.now()
            order.save()
        
        return {"status": "success"}

bugfix_context:
  issue: "#BUG-2378"
  error_log: |
    InventoryWarning: SKU-001 stock mismatch after partial refund
    Expected: 95, Actual: 97
    at InventoryService.rollback (app/inventory/service.py:112)
  
  allowed_files:
    - app/inventory/service.py    # 库存服务
    - app/refund/service.py       # 退款服务
    - app/order/models.py
    - app/inventory/tests/
    - app/refund/tests/
  
  business_rules:
    - "部分退款只回滚被退商品的库存"
    - "已发货的商品不能退库存（只能退货后入库）"
    - "退款金额 = 商品单价 × 退款数量 - 分摊优惠"
  
  constraints:
    max_patch_lines: 25
    must_add_test: true
    approval_required: true
    run_tests: ["test_inventory", "test_refund", "test_order"]  # 跨模块回归

# approval-policy.yaml
approval_rules:
  - condition: "patch touches files matching 'app/pay/**'"
    action: "require_approval"
    approvers: ["@tech-lead", "@payment-owner"]
    reason: "支付相关修改必须技术负责人和支付模块 owner 双重审批"

  - condition: "patch modifies 'order.total_amount' or 'refund.amount'"
    action: "require_approval"
    approvers: ["@tech-lead"]
    reason: "金额计算修改必须技术负责人审批"

  - condition: "patch.lines_changed > 20"
    action: "require_review"
    reviewers: ["@senior-dev"]
    reason: "修改超过 20 行，需要高级开发者 Review"

  - condition: "all tests pass AND patch.lines_changed <= 10 AND no sensitive files"
    action: "auto_merge"
    reason: "小修改 + 测试通过 = 自动合并"

# quality-gate.yaml
gates:
  - name: "编译检查"
    command: "python -m py_compile app/**/*.py"
    blocking: true

  - name: "单元测试"
    command: "pytest app/{affected_module}/tests/ -v --tb=short"
    blocking: true
    timeout: 120

  - name: "回归测试"
    command: "pytest app/order/tests app/pay/tests app/refund/tests -v"
    blocking: true
    timeout: 300

  - name: "Lint 检查"
    command: "ruff check app/ --fix"
    blocking: false

  - name: "安全扫描"
    command: "semgrep --config=auto app/"
    blocking: true
    fail_on: ["ERROR", "HIGH"]

# 验收：运行全部相关测试
pytest app/order/tests app/pay/tests app/refund/tests app/inventory/tests \
  -v --tb=short --cov=app --cov-report=term-missing

# 验收：检查 Agent 修复的 PR
gh pr list --author "agent-bot" --state open
gh pr checks <pr-number>

# 验收：审计日志
cat .agent-audit/$(date +%Y-%m-%d).json | jq '.[] | select(.action == "patch")'