Claude Code 实战指南（三）：Opus 4.6 规划与遗留代码重构

我们需重构遗留支付模块，将基于旧版 stripe.Charge 的逻辑迁移至最新的 stripe.PaymentIntent API。请完成以下任务：
1. 深度分析迁移过程中的数据兼容性、接口兼容性风险；
2. 输出一份结构化的 Markdown 实施计划（命名为 SPEC.md）；
3. 规范必须包含：目标文件列表、核心迁移伪代码（Python）、分步验证步骤。

# 支付模块 Stripe PaymentIntent 迁移规范（SPEC.md）
## 1. 目标文件列表
- 待重构：src/billing/legacy_charge.py（核心支付逻辑文件）
- 新增：src/billing/intent_service.py（封装 PaymentIntent 核心逻辑）
- 待修改测试：tests/billing/test_payments.py（适配新接口的测试用例）

## 2. 核心迁移伪代码（Python）
旧版逻辑（stripe.Charge）：仅作对比，无需修改
charge = stripe.Charge.create(amount=amount_cents, currency="usd", customer=customer_id)

新版逻辑（PaymentIntent）：向后兼容设计
import stripe
from stripe.error import CardError, StripeError

def process_payment(customer_id: str, amount_cents: int) -> str:
    """
    重构核心：替换 Charge 为 PaymentIntent，保留入参兼容，优化异常类型
    :param customer_id: 客户唯一标识
    :param amount_cents: 支付金额（美分）
    :return: PaymentIntent 客户端密钥
    """
    try:
        intent = stripe.PaymentIntent.create(
            amount=amount_cents,
            currency="usd",
            customer=customer_id,
            payment_method_types=["card"],
            setup_future_usage="off_session"
        )
        return intent.client_secret
    except CardError as e:
        # 细化支付卡异常，便于前端精准处理
        raise CardError(message=e.message, param=e.param, code=e.code)
    except StripeError as e:
        # 保留基础 Stripe 异常兼容
        raise StripeError(message=f"支付创建失败：{e.message}")

## 3. 验证步骤（必须逐行执行）
1. 隔离测试：pytest tests/billing/test_payments.py -v（仅执行支付模块测试）
2. 异常验证：模拟卡失效场景，确认 CardError 正常抛出且结构符合预期
3. 兼容性验证：确保旧调用方传入相同参数时，返回值格式无破坏性变更
4. 必须检查 legacy_charge.py 中是否存在未记录的数据库写操作或第三方日志上报，确保在 intent_service.py 中完成平替。

1. 读取项目根目录的 SPEC.md 文件；
2. 严格按照规范完成以下操作：
   - 重构 src/billing/legacy_charge.py（仅修改 PaymentIntent 相关逻辑）；
   - 新增 src/billing/intent_service.py；
   - 修改 tests/billing/test_payments.py 适配新接口；
3. 执行 pytest tests/billing/ -v 并返回测试结果；
4. 禁止修改规范外的任何文件，禁止调整整体架构。

# 架构概览与硬性红线（Hard Rules）
## 禁止修改目录
- apps/auth/core/**：核心鉴权逻辑（无明确授权绝不触碰）
- migrations/**：数据库迁移文件（修改可能导致数据不一致）
## 强制执行命令
- 测试命令：python manage.py test --parallel（每次重构后必须运行）
- 代码格式化：black src/legacy/（修改后自动格式化，保证风格统一）

为 src/legacy/billing.py 中的 calc_tax 函数生成特征测试，要求：
1. 使用 pytest-snapshot 库；
2. 覆盖标准输入、边界值（如负数金额）、异常输入场景；
3. 不仅要记录成功路径，还要通过特征测试锁定旧代码在输入特殊字符、超长字符串时的报错行为，确保重构后报错信息的一致性。
4. 生成的测试文件路径：tests/test_legacy_billing.py；
5. 生成后执行 pytest --snapshot-update 生成快照文件。

运行
# tests/test_legacy_billing.py
import pytest
from src.legacy.billing import calc_tax

# 配置快照存储目录（与测试文件同层级）
@pytest.fixture(scope="module")
def snapshot(snapshot):
    snapshot.snapshot_dir = "tests/snapshots/legacy_billing"
    return snapshot

def test_calc_tax_snapshot(snapshot):
    """特征测试：锁定 calc_tax 函数的实际输出（无论逻辑是否正确）"""
    # 标准输入场景
    result_standard = calc_tax(user_id="user_123", amount=100)
    # 边界值场景（即使是 bug，也先记录）
    result_edge_negative = calc_tax(user_id="user_999", amount=-50)
    # 异常输入场景
    result_invalid = calc_tax(user_id="", amount=0)

    # 保存快照（生成后不可随意修改）
    snapshot.assert_match(str(result_standard), "tax_standard_output.txt")
    snapshot.assert_match(str(result_edge_negative), "tax_edge_negative_output.txt")
    snapshot.assert_match(str(result_invalid), "tax_invalid_output.txt")

基于已生成的特征测试保护，分析 src/legacy/billing.py 中 calc_tax 函数的冗长 if-else 逻辑，输出“策略模式重构计划”，包含：
1. 拆分后的函数/类结构；
2. 重构前后的逻辑对比；
3. 验证要点（确保快照测试通过）。

name: code-reviewer
description: 专注于代码安全与性能审查，不修改任何代码
tools: Read, Glob, Grep, Pytest
model: sonnet-4.5
isolation: worktree  # 核心：启用 Git Worktree 隔离
# Code Reviewer 智能体规则
1. 仅分析代码中的 SQL 注入、N+1 查询、未授权访问风险；
2. 基于隔离的 Git Worktree 目录执行审查，不影响主工作区；
3. 输出结构化的审查报告（Markdown 格式）。
主会话中调用：@code-reviewer 分析 src/auth/ 目录下的鉴权逻辑漏洞
子智能体会在临时 Git Worktree 目录中完成审查，全程不污染主代码库。

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1",
    "CLAUDE_CODE_TEAM_COMMUNICATION_MODE": "tmux"
  }
}

运行
tmux new -s claude-team  # 创建 tmux 会话
claude --teammate-mode tmux  # 以团队模式启动 Claude

重构整站鉴权链路，创建协作团队：
- 队员 A：负责拆分 apps/auth/core 中的旧版 Cookie 逻辑，抽离为独立模块；
- 队员 B：基于拆分后的模块引入 JWT 鉴权，保证接口兼容；
- 队员 C：作为安全审查员，实时审查 A/B 的代码，识别权限漏洞；
要求：
1. 引入队员 D（Sync Agent），负责每 10 分钟汇总 A、B、C 的进展，并自动更新根目录的 PROGRESS.md，防止多个 Agent 在并行开发中出现逻辑冲突。"
2. 队员间通过 SendMessage 工具同步接口定义，达成一致后再提交；
3. 每完成一个子模块，运行 python manage.py test apps/auth/；
4. 最终输出统一的重构报告和测试结果。