# context_builder.py
# 一个用于构建AI上下文的工具脚本

import os
from pathlib import Path
from typing import List, Dict

# 定义文件优先级权重：越核心的文件权重越高
FILE_PRIORITY = {
    "pyproject.toml": 10,
    "requirements.txt": 10,
    "README.md": 9,
    ".cursorrules": 9,
    "conftest.py": 8,
    "models.py": 8,
    "schemas.py": 8,
    "config.py": 7,
}


def collect_context(
    project_root: str,
    max_tokens: int = 12000,
    include_patterns: List[str] = None,
    exclude_dirs: List[str] = None,
) -> str:
    """
    智能收集项目上下文，按优先级排序并截断。

    使用方式：
    >>> context = collect_context("./my-project", max_tokens=12000)
    >>> print(context)
    """
    if include_patterns is None:
        include_patterns = [".py", ".md", ".toml", ".yaml", ".yml", ".json"]
    if exclude_dirs is None:
        exclude_dirs = [".git", "__pycache__", "node_modules", ".venv", "venv"]

    files: List[Dict] = []
    root_path = Path(project_root)

    for file_path in root_path.rglob("*"):
        if not file_path.is_file():
            continue
        if any(d in file_path.parts for d in exclude_dirs):
            continue
        if file_path.suffix not in include_patterns:
            continue

        priority = FILE_PRIORITY.get(file_path.name, 5)
        try:
            content = file_path.read_text(encoding="utf-8")
        except UnicodeDecodeError:
            continue

        # 估算token数（粗略按 1 token ~ 4 chars）
        estimated_tokens = len(content) // 4
        files.append({
            "path": str(file_path.relative_to(root_path)),
            "priority": priority,
            "tokens": estimated_tokens,
            "content": content,
        })

    # 按优先级降序排列
    files.sort(key=lambda x: (-x["priority"], x["path"]))

    # 贪心填充上下文
    collected = []
    total_tokens = 0
    header = f"# Project Context: {root_path.name}\n\n"
    total_tokens += len(header) // 4

    for f in files:
        if total_tokens + f["tokens"] > max_tokens:
            break
        chunk = f"## File: {f['path']}\n```{f['path'].split('.')[-1]}\n{f['content']}\n```\n\n"
        collected.append(chunk)
        total_tokens += len(chunk) // 4

    return header + "".join(collected)


if __name__ == "__main__":
    import sys
    if len(sys.argv) < 2:
        print("Usage: python context_builder.py <project_root>")
        sys.exit(1)

    ctx = collect_context(sys.argv[1])
    print(ctx)

@models.py @schemas.py
帮我实现一个订单状态的幂等转换函数，要求：
1. 状态机只允许 forward 转换（PENDING -> PAID -> SHIPPED）
2. 写入前检查乐观锁版本号
3. 如果已经是目标状态，直接返回成功（幂等）

# .cursorrules - Cursor IDE 团队规范配置

## 代码风格
- Python 遵循 PEP 8，最大行宽 100 字符
- 使用类型注解，不允许 bare `def func(x)`
- 异步函数统一使用 `async def`，禁止混用 sync/async 调用链
- 导入顺序：标准库 > 第三方库 > 本地模块，每组之间空一行

## 架构约束
- 所有数据库操作必须经过 repository 层，禁止在 service 层直接调用 ORM
- API 返回统一使用 `ApiResponse[T]` 包装，禁止直接返回裸模型
- 异常处理：业务异常使用自定义 DomainException，HTTP 异常在 middleware 统一转换

## 测试要求
- 每个新函数必须附带单元测试，覆盖率不低于 80%
- 使用 pytest + pytest-asyncio，fixture 命名采用 `fx_` 前缀
- 外部依赖必须 mock，禁止在单元测试中调用真实数据库或 HTTP 服务

## 注释规范
- 公共 API 必须包含 Google Style Docstring
- 复杂业务逻辑添加 inline 注释说明"为什么"而非"做什么"
- TODO 必须包含创建者姓名和预计处理日期，格式：`# TODO(zhangsan@2026-07-15): xxx`

## 禁止事项
- 禁止使用 `eval()`、`exec()` 或动态代码执行
- 禁止在日志中打印密码、Token、银行卡号等敏感信息
- 禁止直接捕获裸 `Exception`，必须指定具体异常类型

# CLAUDE.md - Claude Code 项目指令

## 项目技术栈
- 后端：Python 3.12 + FastAPI + SQLAlchemy 2.0 + PostgreSQL 15
- 测试：pytest + factory-boy + pytest-asyncio
- 部署：Docker + GitHub Actions

## 工作流
1. 修改代码前，先运行 `pytest` 确认当前测试通过
2. 每次修改后，再次运行受影响的测试文件
3. 提交前执行 `ruff check . && ruff format . && mypy .`

## 特殊约定
- 数据库迁移使用 Alembic，命名格式：`{timestamp}_describe_change.py`
- 环境变量通过 `pydantic-settings` 管理，禁止直接读取 `os.environ`
- 缓存统一使用 Redis，Key 前缀为 `app:{module}:`

为以下函数生成 pytest 单元测试：

```python
# src/payment/service.py
async def process_refund(order_id: str, amount: Decimal) -> RefundResult:
    ...

### 4.3 测试驱动AI编程（AI-TDD）

对于复杂业务逻辑，采用"先写测试，再让AI实现"的模式：

```python
# tests/test_discount_engine.py
# 步骤1：人工定义测试用例（明确预期行为）

import pytest
from decimal import Decimal
from src.pricing.discount import DiscountEngine


class TestDiscountEngine:
    @pytest.mark.parametrize(
        "original,rules,expected",
        [
            # 满100减20
            (Decimal("120.00"), [{"type": "fixed_over", "threshold": "100", "amount": "20"}], Decimal("100.00")),
            # 折扣叠加：先满减再打折（顺序敏感）
            (Decimal("200.00"), [
                {"type": "fixed_over", "threshold": "100", "amount": "20"},
                {"type": "percent", "value": "0.9"},
            ], Decimal("162.00")),  # (200-20)*0.9
            # 边界：刚好达到阈值
            (Decimal("100.00"), [{"type": "fixed_over", "threshold": "100", "amount": "20"}], Decimal("80.00")),
        ],
    )
    def test_calculate_final_price(self, original, rules, expected):
        engine = DiscountEngine(rules)
        assert engine.calculate(original) == expected

我已经写好了测试用例，请实现 `DiscountEngine` 使其通过所有测试。
约束：
- 规则按数组顺序依次应用
- 每次计算后价格不能为负数，最小为 0
- 使用 Decimal 避免浮点精度问题

#!/bin/bash
# ai-refactor-guard.sh
# 在允许AI重构前执行的防护脚本

set -e

echo "[1/4] 保存当前测试快照..."
pytest --snapshot-update -q

echo "[2/4] 运行完整测试套件..."
pytest --cov=src --cov-report=term-missing -q

echo "[3/4] 静态检查..."
ruff check src tests
mypy src

echo "[4/4] 基线建立完成，可以开始AI辅助重构"
echo "提示：重构后必须再次运行本脚本验证"

开发者A负责编写核心业务逻辑，使用AI生成单元测试；
开发者B负责评审AI生成的测试，并补充边界用例；
双方共同确认后，AI根据完整测试实现函数体。

## PR Checklist
- [ ] 代码已通过本地测试 (`pytest`)
- [ ] 静态检查无报错 (`ruff` + `mypy`)
- [ ] AI辅助评审：已将diff粘贴到AI工具，确认无架构违规
- [ ] 人工评审：至少1名团队成员Approve

请以下列标准评审这段代码变更：
1. 是否违反单一职责原则？
2. 是否有潜在的空指针/空值异常？
3. 是否引入了循环依赖？
4. 异常处理是否完整？
5. 是否有性能隐患（如N+1查询、内存泄漏）？

请以表格形式输出：问题等级（高/中/低）、位置、建议修改方案。

# .github/workflows/ai-safe-merge.yml
name: AI-Safe-Merge

on:
  pull_request:
    branches: [main]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install dependencies
        run: pip install -r requirements-dev.txt

      - name: Lint & Type Check
        run: |
          ruff check src tests
          ruff format --check src tests
          mypy src

      - name: Unit Tests
        run: pytest --cov=src --cov-fail-under=80 -q

      - name: Detect AI-Generated Code Smells
        run: |
          # 检查常见的AI生成代码模式
          # 1. 过度泛化的异常捕获
          if grep -r "except Exception:" src/; then
            echo "ERROR: Found bare Exception catch (common AI smell)"
            exit 1
          fi
          # 2. 硬编码的占位符值
          if grep -r "TODO\|FIXME\|placeholder\|xxx" src/; then
            echo "ERROR: Found unresolved placeholders"
            exit 1
          fi
          # 3. 缺少类型注解的公共函数
          python scripts/check_type_annotations.py src/