AI编程进入约束式开发时代：从代码生成到工程化落地的范式转移

# project_template.py
# ============================================================
# 项目架构约束文件
# 所有AI生成的代码必须遵循以下规范
# ============================================================

"""
【API层约束】
- 所有路由必须使用依赖注入获取数据库会话
- 请求体必须使用Pydantic模型进行严格校验
- 响应必须统一使用标准化的APIResponse包装
- 异常必须抛出自定义HTTPException，禁止直接返回JSON

【服务层约束】
- 业务逻辑必须封装在Service类中，禁止在路由函数中直接操作数据库
- 数据库查询必须使用SQLAlchemy 2.0的select语法
- 涉及多张表的操作必须使用显式事务
- 所有外部调用必须实现超时和重试机制

【数据层约束】
- 所有模型必须继承自BaseORM，包含created_at和updated_at字段
- 字符串字段必须指定长度限制
- 外键关系必须配置级联行为
- 敏感字段（密码、Token）必须加密存储
"""

from datetime import datetime
from typing import Generic, TypeVar, Optional, List
from pydantic import BaseModel, Field, ConfigDict
from sqlalchemy import select, update, delete
from sqlalchemy.ext.asyncio import AsyncSession

# 统一响应模型
T = TypeVar('T')

class APIResponse(BaseModel, Generic[T]):
    code: int = Field(default=200, description="业务状态码")
    message: str = Field(default="success", description="状态描述")
    data: Optional[T] = Field(default=None, description="响应数据")
    timestamp: datetime = Field(default_factory=datetime.utcnow)

# ORM基类约束
class BaseORM:
    created_at: datetime
    updated_at: datetime
    
    @classmethod
    def get_select(cls):
        return select(cls)

// 使用TypeScript的严格类型约束AI生成代码
// interfaces/api-contracts.ts

interface CreateOrderRequest {
  /** 用户ID，必须是UUID格式 */
  userId: string;
  /** 商品列表，至少包含一项 */
  items: Array<{
    /** 商品SKU，大写字母+数字组合 */
    sku: string;
    /** 购买数量，1-99 */
    quantity: number;
    /** 单价，单位分，必须≥1 */
    unitPrice: number;
  }>;
  /** 收货地址 */
  shippingAddress: Address;
  /** 优惠券码，可选 */
  couponCode?: string;
}

interface OrderResponse {
  orderId: string;
  status: 'pending' | 'paid' | 'shipped' | 'delivered' | 'cancelled';
  totalAmount: number;
  createdAt: string;
  /** 支付截止时间 */
  payDeadline: string;
}

// 明确声明AI必须实现的函数签名
declare function createOrder(
  request: CreateOrderRequest
): Promise<APIResponse<OrderResponse>>;

# test_order_service.py
# 人类编写的测试用例，作为AI的行为约束

import pytest
from datetime import datetime, timedelta
from app.services.order_service import OrderService
from app.exceptions import InsufficientStockError, InvalidCouponError

class TestOrderService:
    async def test_create_order_success(self, db_session):
        """正常下单流程"""
        service = OrderService(db_session)
        result = await service.create_order(
            user_id="550e8400-e29b-41d4-a716-446655440000",
            items=[{"sku": "PHONE-15-128", "quantity": 1, "unit_price": 599900}],
            shipping_address={...},
            coupon_code=None
        )
        assert result.status == "pending"
        assert result.total_amount == 599900
        assert result.pay_deadline > datetime.utcnow() + timedelta(hours=23)
    
    async def test_create_order_insufficient_stock(self, db_session):
        """库存不足时必须抛出异常，且不能创建订单"""
        service = OrderService(db_session)
        with pytest.raises(InsufficientStockError) as exc_info:
            await service.create_order(
                user_id="...",
                items=[{"sku": "LIMITED-EDITION-1", "quantity": 999, "unit_price": 100}],
                shipping_address={...}
            )
        assert exc_info.value.sku == "LIMITED-EDITION-1"
        assert exc_info.value.available == 5
        # 验证数据库中没有残留数据
        orders = await db_session.execute(select(Order))
        assert len(orders.scalars().all()) == 0
    
    async def test_create_order_invalid_coupon(self, db_session):
        """无效优惠券必须使用原价，且记录优惠券错误日志"""
        ...
    
    async def test_create_order_idempotent(self, db_session):
        """相同幂等键的重复请求必须返回相同结果，不重复创建"""
        ...

# .ai-rules.yaml
# 针对AI生成代码的自定义约束规则

rules:
  security:
    - forbid-raw-sql: 禁止在业务代码中拼接SQL语句，必须使用ORM参数化查询
    - require-input-validation: 所有用户输入必须经过Pydantic模型或等价校验层
    - no-hardcoded-secrets: 禁止在代码中硬编码密钥、密码、Token
  
  performance:
    - require-query-optimization: 涉及数据库查询的循环必须预加载关联数据
    - no-n-plus-one: 禁止出现N+1查询问题
    - require-caching-strategy: 高频读取的数据必须实现缓存机制
  
  maintainability:
    - max-function-lines: 单个函数不超过50行
    - require-docstring: 所有公共函数必须包含Google风格的文档字符串
    - type-hint-required: 所有函数参数和返回值必须添加类型注解

# .cursorrules

## 技术栈约束
- 后端：Python 3.12 + FastAPI + SQLAlchemy 2.0 + PostgreSQL
- 前端：Next.js 14 + TypeScript + Tailwind CSS + shadcn/ui
- 部署：Docker + Kubernetes

## 代码规范
- 所有API端点必须使用依赖注入
- 数据库查询必须异步
- 禁止使用any类型，必须显式定义接口

## 安全要求
- 所有用户输入必须经过校验
- 密码必须使用bcrypt哈希
- JWT Token必须设置过期时间