28f - 后端 Steering 规则与反模式

# CLAUDE.md — 后端项目规则
 
## 项目概述
- 运行时：Node.js 22 LTS + TypeScript 5.x（strict mode）
- 框架：Express 5 / Fastify 5 / NestJS 11
- 数据库：PostgreSQL 17 + Prisma ORM 6 / Drizzle ORM
- 缓存：Redis 8
- 认证：JWT（RS256）+ OAuth 2.0（Authorization Code + PKCE）
- 测试：Vitest + Supertest + Testcontainers
- 构建：tsup / esbuild
- 包管理器：pnpm
 
## 安全强制规则（最高优先级）
 
### SQL 注入防护
- 所有数据库查询必须使用参数化查询或 ORM
- 禁止字符串拼接 SQL：禁止 `SELECT * FROM users WHERE id = '${id}'`
- 禁止使用 Prisma.$queryRawUnsafe() 或 Drizzle sql.raw() 拼接用户输入
- 动态查询（排序字段、筛选条件）必须使用白名单验证
- 原生 SQL 仅在 ORM 无法表达时使用，且必须用参数占位符（$1, $2）
 
### 认证与授权
- 所有 API 端点默认需要认证，公开端点必须显式标注
- JWT 必须使用 RS256（非对称）签名，禁止 HS256 + 硬编码密钥
- JWT 过期时间：access token ≤ 15 分钟，refresh token ≤ 7 天
- 每个端点必须检查用户权限（RBAC/ABAC），不仅仅是认证
- 禁止在 URL query 参数中传递 token
- 密码哈希使用 bcrypt（cost ≥ 12）或 argon2id
- 登录失败必须实现账户锁定（5 次失败后锁定 15 分钟）
 
### 密钥管理
- 所有密钥、密码、API key 必须通过环境变量注入
- 禁止在代码中硬编码任何密钥（包括测试代码中的真实密钥）
- .env 文件必须在 .gitignore 中
- 生产环境使用 Vault、AWS Secrets Manager 或类似密钥管理服务
- 数据库连接字符串禁止出现在日志或错误响应中
 
### 输入验证
- 所有外部输入（body、query、params、headers）必须在控制器层验证
- 使用 Zod / class-validator 进行 schema 验证
- 验证规则：类型检查 + 长度限制 + 格式校验 + 范围约束
- 文件上传必须验证：类型白名单、大小限制（≤ 10MB）、文件名清洗
- 禁止直接将 req.body 传递给数据库操作（必须经过验证和字段筛选）
 
### 错误处理
- 使用统一的错误处理中间件
- 生产环境禁止返回堆栈跟踪、SQL 错误详情、内部路径
- 错误响应格式统一：{ error: { code, message, requestId } }
- 区分客户端错误（4xx）和服务端错误（5xx）
- 未捕获异常必须记录完整堆栈但只返回通用错误消息
- 禁止空 catch 块：catch (e) {} 必须至少记录日志
 
### 限流与防护
- 所有公开 API 必须配置速率限制
- 默认限制：100 请求/分钟/IP（可按端点调整）
- 登录端点：10 请求/分钟/IP
- 注册端点：5 请求/分钟/IP
- 文件上传端点：20 请求/分钟/用户
- 使用 express-rate-limit 或 @nestjs/throttler
- 返回标准限流头：X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After
 
## 性能规则
 
### 数据库
- 禁止在循环中执行数据库查询（N+1 问题）
- 使用 Prisma include/select 或 Drizzle with 进行关联查询
- 列表查询必须分页（默认 20 条，最大 100 条）
- 频繁查询的字段必须建立索引
- 大批量操作使用 createMany/updateMany 批量 API
- 数据库连接使用连接池（Prisma 默认，pg-pool 手动配置）
 
### 并发
- 涉及余额、库存等关键数据的更新必须使用数据库事务 + 行锁
- 使用乐观锁（version 字段）或悲观锁（SELECT FOR UPDATE）防止竞态
- 分布式锁使用 Redis（Redlock 算法）
- 幂等性：支付、订单创建等操作必须实现幂等键
 
### 缓存
- 热点数据使用 Redis 缓存，设置合理的 TTL
- 缓存键命名规范：{service}:{entity}:{id}，如 user-service:user:123
- 数据变更时主动失效缓存（Cache-Aside 模式）
- 禁止缓存敏感数据（密码、token、个人身份信息）
 
## 代码风格
 
### TypeScript
- 严格模式：所有文件必须通过 strict TypeScript 检查
- 禁止 any：使用 unknown + 类型守卫
- 接口优先：请求/响应 DTO 使用 interface，工具类型使用 type
- 错误类型：自定义错误类继承 Error，包含 statusCode 和 errorCode
 
### API 设计
- RESTful 命名：复数名词（/users, /orders），HTTP 动词表达操作
- 版本化：URL 前缀 /api/v1/
- 响应格式统一：{ data, meta, error }
- 分页格式：{ data: [], meta: { total, page, pageSize, totalPages } }
- 日期格式：ISO 8601（UTC）
- ID 格式：UUID v7（时间有序）或 CUID2
 
### 文件组织
- 控制器：src/modules/{module}/controller.ts
- 服务层：src/modules/{module}/service.ts
- 数据访问：src/modules/{module}/repository.ts
- DTO/验证：src/modules/{module}/dto.ts
- 路由：src/modules/{module}/routes.ts
- 中间件：src/middleware/
- 工具函数：src/lib/ 或 src/utils/
- 类型定义：src/types/
 
## 日志与审计
- 使用结构化日志（pino / winston），JSON 格式
- 日志级别：error > warn > info > debug
- 必须记录：认证事件、权限变更、数据修改、API 错误
- 禁止在日志中记录：密码、token、信用卡号、身份证号
- 每个请求必须有唯一 requestId（通过中间件注入）
- 生产环境日志级别：info
 
## 禁止行为
- 禁止使用 eval()、new Function()、child_process.exec() 处理用户输入
- 禁止在响应中返回数据库内部 ID（使用 UUID）
- 禁止 SELECT *（必须显式指定需要的字段）
- 禁止在 GET 请求中执行写操作
- 禁止信任 X-Forwarded-For 头（除非在可信代理后）
- 禁止使用 cors({ origin: '*' }) 在生产环境
- 禁止将用户上传文件存储在应用服务器本地（使用 S3/R2）

.kiro/
└── steering/
    ├── backend-general.md       # 通用后端规则（inclusion: always）
    ├── security-rules.md        # 安全规则（inclusion: always）
    ├── database-rules.md        # 数据库规则（inclusion: auto）
    ├── api-design.md            # API 设计规范（inclusion: auto）
    └── error-handling.md        # 错误处理规则（inclusion: auto）

---
inclusion: always
description: 后端项目通用规则，适用于所有后端代码交互
globs: "src/**/*.ts"
---
 
# 后端通用规则
 
## 技术栈
- Node.js 22 LTS + TypeScript strict mode
- Express 5 / Fastify 5 / NestJS 11
- PostgreSQL 17 + Prisma ORM 6
- Redis 8 缓存
- Vitest 测试框架
 
## 核心约束
1. 所有外部输入必须验证（Zod schema）
2. 所有数据库查询必须使用参数化查询或 ORM
3. 所有密钥通过环境变量注入，禁止硬编码
4. 所有 API 端点默认需要认证
5. 所有公开端点必须配置速率限制
6. 错误响应禁止泄露内部实现细节
 
## 文件命名
- 模块目录：src/modules/{moduleName}/
- 控制器：controller.ts
- 服务层：service.ts
- 数据访问：repository.ts
- DTO/验证：dto.ts
- 测试：*.test.ts

---
inclusion: always
description: 安全强制规则，适用于所有后端代码
globs: "src/**/*.ts"
---
 
# 安全强制规则
 
## SQL 注入防护
- 禁止字符串拼接 SQL 查询
- 动态查询条件使用白名单验证
- ORM 的 raw query 必须使用参数占位符
 
## 认证与授权
- JWT 使用 RS256 签名，access token ≤ 15 分钟
- 每个端点必须检查用户权限（不仅仅是认证）
- 密码使用 bcrypt（cost ≥ 12）或 argon2id
 
## 密钥管理
- 所有密钥通过环境变量或密钥管理服务注入
- .env 必须在 .gitignore 中
- 禁止在日志或错误响应中暴露连接字符串
 
## 输入验证
- 所有外部输入必须在控制器层用 Zod 验证
- 文件上传：类型白名单 + 大小限制 + 文件名清洗
- 禁止直接将 req.body 传递给数据库操作
 
## 输出安全
- 生产环境禁止返回堆栈跟踪
- 响应中禁止包含数据库内部 ID
- 设置安全响应头（Helmet 中间件）

---
inclusion: auto
description: 数据库访问和查询规则
globs: "src/**/*.ts"
---
 
# 数据库规则
 
## 查询优化
- 禁止在循环中执行数据库查询（N+1 问题）
- 使用 Prisma include/select 进行关联查询
- 列表查询必须分页（默认 20，最大 100）
- 禁止 SELECT *，显式指定需要的字段
- 频繁查询的字段必须建立索引
 
## 事务与并发
- 涉及关键数据更新必须使用数据库事务
- 使用乐观锁（version 字段）或悲观锁防止竞态
- 批量操作使用 createMany/updateMany
 
## 迁移
- 每次 schema 变更必须生成迁移文件
- 迁移文件必须可回滚
- 禁止在迁移中执行不可逆的数据删除（先软删除）

---
inclusion: auto
description: API 设计规范
globs: "src/modules/**/controller.ts,src/modules/**/routes.ts"
---
 
# API 设计规范
 
## RESTful 约定
- URL 使用复数名词：/users, /orders, /products
- HTTP 动词：GET（读）POST（创建）PUT（全量更新）PATCH（部分更新）DELETE（删除）
- 版本化：/api/v1/ 前缀
- 嵌套资源最多 2 层：/users/:id/orders
 
## 响应格式
- 成功：{ data: T, meta?: { total, page, pageSize } }
- 错误：{ error: { code: string, message: string, requestId: string } }
- 分页：使用 page + pageSize 参数，返回 total 和 totalPages
- 日期：ISO 8601 UTC 格式
- ID：UUID v7 或 CUID2
 
## 限流
- 所有公开端点必须配置速率限制
- 返回标准限流头：X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After

---
inclusion: auto
description: 错误处理规范
globs: "src/**/*.ts"
---
 
# 错误处理规范
 
## 错误类
- 自定义 AppError 基类，包含 statusCode、errorCode、message
- 业务错误继承 AppError：NotFoundError、ValidationError、UnauthorizedError、ForbiddenError
- 区分可预期错误（业务逻辑）和不可预期错误（系统故障）
 
## 错误中间件
- 全局错误处理中间件捕获所有未处理错误
- 可预期错误：返回具体错误信息和对应 HTTP 状态码
- 不可预期错误：记录完整堆栈，返回 500 + 通用错误消息
- 禁止空 catch 块
 
## 日志
- 错误日志必须包含：requestId、userId、错误类型、堆栈跟踪
- 禁止在日志中记录敏感数据（密码、token、PII）

---
description: 后端开发通用规则
globs: ["src/**/*.ts", "prisma/**/*.prisma"]
---
 
# 后端开发规则
 
## 技术栈约束
- 运行时：Node.js 22 + TypeScript（strict mode）
- 框架：Express 5 / Fastify 5 / NestJS 11
- 数据库：PostgreSQL 17 + Prisma ORM 6
- 缓存：Redis 8
- 测试：Vitest + Supertest
 
## 安全规则（最高优先级）
1. 所有数据库查询使用参数化查询或 ORM，禁止字符串拼接 SQL
2. 所有密钥通过环境变量注入，禁止硬编码
3. 所有外部输入必须用 Zod 验证
4. JWT 使用 RS256 签名，access token ≤ 15 分钟
5. 每个端点必须检查认证和授权
6. 所有公开 API 必须配置速率限制
7. 错误响应禁止泄露堆栈跟踪和内部路径
8. 禁止 eval()、new Function() 处理用户输入
 
## 数据库规则
1. 禁止在循环中执行查询（N+1）
2. 列表查询必须分页
3. 禁止 SELECT *
4. 关键数据更新使用事务 + 锁
5. 频繁查询字段建立索引
 
## API 设计
1. RESTful 命名：复数名词 + HTTP 动词
2. 版本化：/api/v1/
3. 统一响应格式：{ data, meta, error }
4. 日期使用 ISO 8601 UTC
 
## 错误处理
1. 使用自定义错误类（AppError）
2. 全局错误中间件
3. 禁止空 catch 块
4. 生产环境不返回堆栈跟踪

# 检查项目技术栈
cat package.json | jq '.dependencies, .devDependencies'
 
# 检查是否有硬编码密钥
grep -rn "password\|secret\|api_key\|apiKey\|API_KEY\|token" src/ --include="*.ts" | grep -v "node_modules\|.test.\|.spec."
 
# 检查是否有字符串拼接 SQL
grep -rn "queryRawUnsafe\|sql\.raw\|\`SELECT.*\${\|\`INSERT.*\${\|\`UPDATE.*\${\|\`DELETE.*\${" src/ --include="*.ts"
 
# 检查是否有 eval 或 Function
grep -rn "eval(\|new Function(" src/ --include="*.ts"
 
# 检查依赖漏洞
npx audit-ci --critical
# 或
pnpm audit --audit-level=critical
 
# 检查现有 AI 规则文件
ls -la CLAUDE.md .cursorrules .cursor/rules/ .kiro/steering/

请分析我的后端项目并生成适合的 Steering 规则。

项目信息：
- package.json 中的依赖：[粘贴依赖列表]
- 目录结构：[粘贴 tree 输出]
- 数据库类型：[PostgreSQL / MySQL / MongoDB]
- ORM：[Prisma / Drizzle / TypeORM / Sequelize]
- 认证方案：[JWT / Session / OAuth]
- 部署环境：[AWS / GCP / Vercel / Railway / 自建服务器]
- 团队规模：[人数]
- 目标 AI 工具：[Claude Code / Kiro / Cursor]

请生成：
1. 安全强制规则（SQL 注入、认证、密钥管理、输入验证）
2. 数据库访问规则（N+1 防护、分页、事务）
3. API 设计规范（RESTful、响应格式、版本化）
4. 错误处理规范（错误类、中间件、日志）
5. 限流与防护规则
6. 禁止行为清单

输出格式：[CLAUDE.md / Kiro Steering / Cursor Rules]

# 检测字符串拼接 SQL（模板字符串）
grep -rn "\`SELECT.*\${\|\`INSERT.*\${\|\`UPDATE.*\${\|\`DELETE.*\${" src/ --include="*.ts"
 
# 检测 Prisma 不安全原生查询
grep -rn "queryRawUnsafe\|executeRawUnsafe" src/ --include="*.ts"
 
# 检测 Drizzle 不安全原生 SQL
grep -rn "sql\.raw\b" src/ --include="*.ts" | grep -v "sql\.raw\`"
 
# 使用 Semgrep 自动检测
npx semgrep --config "p/sql-injection" src/
 
# 使用 ESLint 安全插件
npx eslint src/ --rule '{"no-eval": "error"}'

## SQL 注入防护规则
- 所有数据库查询必须使用参数化查询或 ORM 方法
- 禁止：`SELECT * FROM users WHERE id = '${id}'`
- 正确：prisma.user.findUnique({ where: { id } })
- 禁止：Prisma.$queryRawUnsafe() 拼接用户输入
- 正确：Prisma.$queryRaw`SELECT * FROM users WHERE id = ${id}`（tagged template）
- 动态排序字段必须使用白名单：
  const ALLOWED_SORT = ['createdAt', 'name', 'email'] as const
  if (!ALLOWED_SORT.includes(sortBy)) throw new ValidationError()
- 搜索功能使用 ORM 的 contains/like 方法，不要手写 LIKE 查询

请审查以下后端代码，检测并修复所有 SQL 注入漏洞：

[粘贴代码]

检查项：
1. 是否有字符串拼接构建的 SQL 查询？→ 改为参数化查询或 ORM 方法
2. 是否有 $queryRawUnsafe 或 sql.raw 拼接用户输入？→ 改为 tagged template
3. 动态排序/筛选字段是否经过白名单验证？→ 添加白名单
4. 搜索功能是否安全？→ 使用 ORM 的 contains 方法
5. 是否有其他用户输入直接进入数据库操作的路径？

请输出修复后的代码，并解释每处修改的安全原因。

# 检测硬编码 JWT 密钥
grep -rn "jwt\.sign.*['\"].*['\"]" src/ --include="*.ts"
grep -rn "jwt\.verify.*['\"].*['\"]" src/ --include="*.ts"
 
# 检测弱哈希算法
grep -rn "md5\|sha1\|sha256" src/ --include="*.ts" | grep -i "password\|hash"
 
# 检测缺少过期时间的 JWT
grep -rn "jwt\.sign" src/ --include="*.ts" | grep -v "expiresIn"
 
# 检测缺少权限检查的路由
grep -rn "router\.\(get\|post\|put\|patch\|delete\)" src/ --include="*.ts" | grep -v "auth\|guard\|middleware\|protect"
 
# 使用 Semgrep 检测认证问题
npx semgrep --config "p/jwt" src/

## 认证与授权规则
- JWT 签名算法必须使用 RS256（非对称），禁止 HS256 + 硬编码密钥
- JWT 密钥必须从环境变量加载：process.env.JWT_PRIVATE_KEY
- access token 过期时间 ≤ 15 分钟，refresh token ≤ 7 天
- 每个路由必须有认证中间件，公开路由必须显式标注 @Public()
- 认证之后必须检查授权：用户是否有权访问该资源
  - 示例：GET /users/:id 必须验证 req.user.id === params.id 或 req.user.role === 'admin'
- 密码哈希使用 bcrypt（cost ≥ 12）或 argon2id，禁止 MD5/SHA 系列
- 重置密码 token 必须一次性使用且 15 分钟过期
- 登录失败 5 次后锁定账户 15 分钟

请审查以下认证相关代码，检测并修复认证绕过漏洞：

[粘贴认证相关代码]

检查项：
1. JWT 签名算法是否安全？→ 改为 RS256
2. JWT 密钥是否硬编码？→ 改为环境变量
3. token 是否有合理的过期时间？→ access ≤ 15min, refresh ≤ 7d
4. 是否所有端点都有认证检查？→ 添加认证中间件
5. 是否有授权检查（不仅仅是认证）？→ 添加权限验证
6. 密码哈希算法是否安全？→ 使用 bcrypt/argon2id
7. 是否有登录失败限制？→ 添加账户锁定机制

请输出修复后的代码。

# 检测硬编码密钥（通用模式）
grep -rn "password.*=.*['\"].*['\"]" src/ --include="*.ts" | grep -v "test\|spec\|mock\|example"
grep -rn "secret.*=.*['\"].*['\"]" src/ --include="*.ts"
grep -rn "api_key\|apiKey\|API_KEY" src/ --include="*.ts" | grep -v "process\.env"
 
# 检测数据库连接字符串
grep -rn "postgresql://\|mysql://\|mongodb://" src/ --include="*.ts"
 
# 检测 .env 是否在 .gitignore 中
grep "\.env" .gitignore
 
# 使用 git-secrets 扫描
git secrets --scan
 
# 使用 trufflehog 扫描 Git 历史
trufflehog git file://. --only-verified
 
# 使用 Gitleaks 扫描
gitleaks detect --source . --verbose

## 密钥管理规则
- 所有密钥、密码、API key 必须通过 process.env 读取
- 禁止在代码中出现任何硬编码的密钥值（包括示例值如 'your-api-key'）
- 配置文件模板使用占位符：DATABASE_URL=postgresql://user:${DB_PASSWORD}@host/db
- .env 文件必须在 .gitignore 中，提供 .env.example 作为模板
- .env.example 中的值必须是占位符，不能是真实密钥
- Docker Compose 中的密钥使用 ${VAR} 引用环境变量
- 测试代码使用 mock 值或测试专用密钥，不使用生产密钥
- 日志中禁止打印：密码、token、连接字符串、API 密钥
- 错误响应中禁止包含连接字符串或内部配置信息
- 生产环境使用密钥管理服务（Vault、AWS Secrets Manager、Doppler）

请审查以下代码，检测并修复所有密钥泄露问题：

[粘贴代码]

检查项：
1. 是否有硬编码的密码、API 密钥、连接字符串？→ 改为 process.env
2. .env 文件是否在 .gitignore 中？→ 添加到 .gitignore
3. 是否提供了 .env.example？→ 创建模板文件
4. 日志中是否打印了敏感信息？→ 过滤敏感字段
5. 错误响应中是否泄露了内部配置？→ 返回通用错误消息
6. Docker Compose 中是否硬编码了密码？→ 使用环境变量引用
7. 测试代码是否使用了真实密钥？→ 改为 mock 值

请输出修复后的代码，并提供 .env.example 模板。

# 检测循环中的数据库查询
grep -rn "for.*await.*prisma\|forEach.*await.*prisma\|map.*await.*prisma" src/ --include="*.ts"
 
# 检测 Promise.all 包裹的多次查询（可能是 N+1 的"优化"版本）
grep -rn "Promise\.all.*map.*prisma\|Promise\.all.*map.*findUnique\|Promise\.all.*map.*findFirst" src/ --include="*.ts"
 
# 使用 Prisma 查询日志检测
# 在 prisma client 初始化时启用日志：
# new PrismaClient({ log: ['query'] })
# 然后观察单个 API 请求产生的查询数量
 
# 使用 prisma-query-log 中间件
# 或在测试中使用 jest-prisma 检测查询次数

## N+1 查询防护规则
- 禁止在循环（for/forEach/map）中执行数据库查询
- 需要关联数据时使用 Prisma include 或 Drizzle with 一次性加载
  - 错误：users.map(u => prisma.order.findMany({ where: { userId: u.id } }))
  - 正确：prisma.user.findMany({ include: { orders: true } })
- 需要部分字段时使用 select 限制返回字段
- 批量查询使用 WHERE IN：prisma.user.findMany({ where: { id: { in: userIds } } })
- GraphQL 使用 DataLoader 批量加载关联数据
- 列表 API 的关联数据在 repository 层一次性加载，不在 controller 层逐条查询
- 开发环境启用 Prisma 查询日志，监控每个请求的查询次数
- 单个 API 请求的数据库查询次数不应超过 10 次

请审查以下数据库访问代码，检测并修复 N+1 查询问题：

[粘贴代码]

项目使用 [Prisma / Drizzle / TypeORM] ORM。

检查项：
1. 是否有循环中的数据库查询？→ 改为 include/with 关联查询
2. 是否有 Promise.all + map 的批量单条查询？→ 改为 WHERE IN 批量查询
3. 关联数据是否在正确的层级加载？→ 在 repository 层一次性加载
4. 是否有不必要的嵌套查询？→ 合并为单次查询
5. 列表 API 是否高效？→ 使用 include + select 限制字段

请输出优化后的代码，并估算优化前后的查询次数对比。

# 检测直接使用 req.body 的数据库操作
grep -rn "req\.body" src/ --include="*.ts" | grep -i "create\|update\|insert"
 
# 检测缺少验证的路由处理函数
# 查找直接从 req 取值而没有经过验证中间件的路由
grep -rn "req\.body\.\|req\.query\.\|req\.params\." src/ --include="*.ts" | grep -v "validate\|schema\|zod\|class-validator\|joi"
 
# 检测文件上传是否有限制
grep -rn "multer\|upload\|formidable" src/ --include="*.ts" | grep -v "limits\|fileFilter\|maxFileSize"
 
# 使用 Semgrep 检测缺少验证的端点
npx semgrep --config "p/express" src/

## 输入验证规则
- 所有 API 端点的输入必须在控制器层使用 Zod schema 验证
- 每个端点定义独立的请求 schema：CreateUserSchema、UpdateUserSchema
- 验证规则必须包含：
  - 类型检查（string, number, boolean, array）
  - 必填/可选标记
  - 字符串长度限制（name: z.string().min(1).max(100)）
  - 数字范围限制（age: z.number().int().min(0).max(150)）
  - 格式校验（email: z.string().email()）
  - 枚举值限制（role: z.enum(['user', 'admin'])）
- 禁止直接将 req.body 传递给数据库操作
- 使用 schema.parse(req.body) 的返回值（经过验证和类型转换的数据）
- 路径参数必须验证格式：id 必须是有效的 UUID
- 文件上传必须配置：
  - 类型白名单：['image/jpeg', 'image/png', 'application/pdf']
  - 大小限制：≤ 10MB
  - 文件名清洗：移除特殊字符和路径遍历字符
- 分页参数必须有默认值和上限：page ≥ 1, pageSize ∈ [1, 100]

请为以下 API 端点添加完整的输入验证：

[粘贴路由和控制器代码]

要求：
1. 使用 Zod 定义请求 schema（body、query、params 分别验证）
2. 包含类型检查、长度限制、格式校验、枚举值限制
3. 路径参数 id 验证为 UUID 格式
4. 分页参数有默认值和上限
5. 验证失败返回 400 + 具体的错误信息
6. 使用验证后的数据（而非原始 req.body）进行数据库操作

请输出完整的 Zod schema 定义和验证中间件代码。

# 检测直接返回错误消息
grep -rn "err\.message\|error\.message\|e\.message" src/ --include="*.ts" | grep "res\.\|json\|send"
 
# 检测返回堆栈跟踪
grep -rn "err\.stack\|error\.stack\|e\.stack" src/ --include="*.ts" | grep "res\.\|json\|send"
 
# 检测空 catch 块
grep -rn "catch.*{.*}" src/ --include="*.ts" | grep -v "log\|throw\|return\|console\|next"
 
# 检测缺少 async 错误处理
grep -rn "async.*req.*res" src/ --include="*.ts" | grep -v "try\|asyncHandler\|catchAsync"
 
# 检测所有错误都返回 500
grep -rn "status(500)" src/ --include="*.ts" | wc -l
grep -rn "status(4[0-9][0-9])" src/ --include="*.ts" | wc -l
# 如果 500 远多于 4xx，说明错误分类不足

## 错误处理规则
- 定义自定义错误基类 AppError，包含 statusCode、errorCode、message
- 业务错误类：
  - NotFoundError (404)
  - ValidationError (400)
  - UnauthorizedError (401)
  - ForbiddenError (403)
  - ConflictError (409)
  - RateLimitError (429)
- 全局错误处理中间件：
  - AppError 实例：返回对应 statusCode + errorCode + message
  - Zod 验证错误：返回 400 + 格式化的字段错误
  - Prisma 已知错误（P2002 唯一约束）：返回 409 + 友好消息
  - 未知错误：记录完整堆栈，返回 500 + 通用消息 "Internal Server Error"
- 生产环境禁止返回：堆栈跟踪、SQL 错误详情、文件路径、环境变量
- 所有错误响应包含 requestId 用于追踪
- 禁止空 catch 块：至少记录日志或重新抛出
- Express async 路由必须使用 asyncHandler 包装或 express-async-errors
- 未捕获异常和未处理 Promise rejection 必须有全局处理器

请审查以下后端代码的错误处理，检测并修复问题：

[粘贴代码]

检查项：
1. 是否泄露了内部错误信息（SQL 错误、堆栈跟踪、文件路径）？→ 返回通用消息
2. 是否有空 catch 块？→ 添加日志记录
3. 是否区分了客户端错误和服务端错误？→ 使用自定义错误类
4. 是否有全局错误处理中间件？→ 添加统一错误处理
5. async 路由的错误是否被正确捕获？→ 使用 asyncHandler
6. 是否有未处理的 Promise rejection？→ 添加全局处理器

请输出：
1. 自定义错误类定义
2. 全局错误处理中间件
3. 修复后的路由代码

# 检测先读后写模式（潜在竞态）
grep -rn "findUnique\|findFirst" src/ --include="*.ts" -A 5 | grep "update\|delete"
 
# 检测余额/库存相关操作（高风险区域）
grep -rn "balance\|stock\|inventory\|quantity\|credits" src/ --include="*.ts" | grep "update\|decrement\|increment"
 
# 检测缺少事务的多步操作
grep -rn "await.*prisma\." src/ --include="*.ts" -A 3 | grep -B 1 "await.*prisma\." | grep -v "\$transaction"
 
# 检测缺少幂等键的创建操作
grep -rn "create(" src/ --include="*.ts" | grep -i "order\|payment\|transaction" | grep -v "idempotency\|idempotent"

## 并发与竞态防护规则
- 涉及余额、库存、积分等关键数据的更新必须使用以下方式之一：
  1. 数据库原子操作：prisma.user.update({ data: { balance: { decrement: amount } } })
  2. 事务 + 悲观锁：$transaction + SELECT FOR UPDATE
  3. 乐观锁：version 字段 + WHERE version = expectedVersion
- 禁止先读后写模式（Read-Modify-Write）处理关键数据
- 支付、订单创建等操作必须实现幂等性：
  - 客户端生成幂等键（Idempotency-Key header）
  - 服务端在处理前检查幂等键是否已处理
  - 使用数据库唯一约束保证幂等
- 分布式环境使用 Redis 分布式锁（Redlock）
- 数据库事务使用 Serializable 隔离级别处理关键业务
- 所有涉及金额的操作必须在事务中完成
- 并发测试：关键业务逻辑必须有并发测试用例

请审查以下代码的并发安全性，检测并修复竞态条件：

[粘贴代码]

业务场景：[描述业务场景，如"用户余额扣减"、"商品库存扣减"、"订单创建"]

检查项：
1. 是否有先读后写模式？→ 改为原子操作或事务+锁
2. 关键数据更新是否在事务中？→ 添加 $transaction
3. 是否需要幂等性保护？→ 添加幂等键机制
4. 是否需要分布式锁？→ 添加 Redis 锁
5. 并发场景下数据是否一致？→ 添加并发测试

请输出修复后的代码，并解释选择的并发控制策略。

# 检测是否安装了限流中间件
grep -rn "rate-limit\|throttle\|rateLimit" package.json
 
# 检测路由是否配置了限流
grep -rn "rateLimit\|throttle\|RateLimit" src/ --include="*.ts"
 
# 检测登录/注册端点是否有特殊限流
grep -rn "login\|signin\|register\|signup" src/ --include="*.ts" | grep -i "rate\|limit\|throttle"
 
# 检测是否返回限流头
grep -rn "X-RateLimit\|Retry-After\|RateLimit-" src/ --include="*.ts"
 
# 使用 OWASP ZAP 测试限流
# 或使用 ab/wrk 进行压力测试
# ab -n 1000 -c 50 http://localhost:3000/api/v1/login

## 限流与防护规则
- 所有 API 必须配置速率限制，使用 express-rate-limit 或 @nestjs/throttler
- 默认限流策略（按 IP）：
  - 全局：100 请求/分钟
  - 登录：10 请求/分钟
  - 注册：5 请求/分钟
  - 密码重置：3 请求/分钟
  - 文件上传：20 请求/分钟
  - 搜索：30 请求/分钟
- 认证用户可以有更高的限额（按用户 ID 限流）
- 返回标准限流响应头：
  - X-RateLimit-Limit：限额
  - X-RateLimit-Remaining：剩余次数
  - X-RateLimit-Reset：重置时间
  - Retry-After：429 响应时的等待时间
- 限流存储使用 Redis（分布式环境）
- 关键端点（登录、支付）使用滑动窗口算法
- 超过限流返回 429 Too Many Requests + 友好错误消息
- Webhook 端点使用签名验证 + IP 白名单

请为以下 API 项目添加完整的限流配置：

[粘贴路由配置或 app 入口文件]

项目框架：[Express / Fastify / NestJS]
部署环境：[单实例 / 多实例（需要 Redis）]

要求：
1. 全局默认限流：100 请求/分钟/IP
2. 登录端点：10 请求/分钟/IP
3. 注册端点：5 请求/分钟/IP
4. 文件上传：20 请求/分钟/用户
5. 返回标准限流响应头
6. 超过限流返回 429 + 友好错误消息
7. [如果多实例] 使用 Redis 作为限流存储

请输出完整的限流中间件配置代码。

# 检测日志中可能包含敏感数据
grep -rn "log.*password\|log.*token\|log.*secret\|log.*apiKey\|log.*creditCard" src/ --include="*.ts"
 
# 检测 console.log 使用（应使用结构化日志）
grep -rn "console\.log\|console\.error\|console\.warn" src/ --include="*.ts" | grep -v "node_modules\|test\|spec"
 
# 检测日志中记录完整请求体
grep -rn "log.*req\.body\|log.*request\.body" src/ --include="*.ts"
 
# 检测是否有请求 ID 中间件
grep -rn "requestId\|request-id\|correlationId\|x-request-id" src/ --include="*.ts"
 
# 检测日志库使用
grep -rn "pino\|winston\|bunyan\|log4js" package.json

## 日志安全规则
- 使用结构化日志库（pino 推荐，性能最优），禁止 console.log
- 日志格式：JSON，包含 timestamp、level、message、requestId、context
- 敏感字段自动脱敏（使用 pino 的 redact 配置）：
  - 密码：password, passwd, pwd
  - Token：token, accessToken, refreshToken, authorization
  - 密钥：secret, apiKey, api_key, privateKey
  - PII：ssn, creditCard, cardNumber
- 禁止在日志中记录完整的请求体（仅记录非敏感字段）
- 每个请求必须有唯一 requestId（通过中间件注入）
- 日志级别规范：
  - error：系统错误、未捕获异常、第三方服务故障
  - warn：业务异常、降级、接近限额
  - info：请求开始/结束、关键业务操作（登录、支付、权限变更）
  - debug：详细调试信息（仅开发环境）
- 生产环境日志级别：info
- 安全审计日志必须记录：认证事件、权限变更、数据修改、管理员操作

请审查以下代码的日志实现，检测并修复日志安全问题：

[粘贴代码]

检查项：
1. 日志中是否记录了敏感数据（密码、token、PII）？→ 添加脱敏
2. 是否使用了 console.log？→ 改为结构化日志库（pino）
3. 是否有请求 ID 追踪？→ 添加 requestId 中间件
4. 日志级别是否合理？→ 按规范调整
5. 是否记录了必要的安全审计事件？→ 添加审计日志
6. 生产环境日志级别是否正确？→ 设为 info

请输出：
1. pino 日志配置（含 redact 脱敏规则）
2. requestId 中间件
3. 修复后的日志代码

# 检测宽松的 CORS 配置
grep -rn "origin.*\*\|origin.*true\|cors()" src/ --include="*.ts"
 
# 检测是否使用了 Helmet（安全头中间件）
grep -rn "helmet" package.json src/ --include="*.ts"
 
# 检测安全响应头
curl -I http://localhost:3000/api/v1/health | grep -i "x-content-type\|strict-transport\|content-security\|x-frame"
 
# 检测 CSRF 防护
grep -rn "csrf\|csurf\|csrfToken" src/ --include="*.ts" package.json

## CORS 与安全头规则
- CORS origin 必须使用白名单，禁止 origin: '*'（生产环境）
  - 正确：origin: ['https://app.example.com', 'https://admin.example.com']
  - 开发环境可以使用 origin: 'http://localhost:5173'
- 使用 Helmet 中间件设置安全响应头
- 必须配置的安全头：
  - Strict-Transport-Security: max-age=31536000; includeSubDomains
  - X-Content-Type-Options: nosniff
  - X-Frame-Options: DENY（或 SAMEORIGIN）
  - Content-Security-Policy: default-src 'self'
  - X-XSS-Protection: 0（现代浏览器已内置，设为 0 避免旧版浏览器的 XSS 过滤器问题）
  - Referrer-Policy: strict-origin-when-cross-origin
- 仅允许必要的 HTTP 方法：GET, POST, PUT, PATCH, DELETE, OPTIONS
- 使用 cookie 认证时必须配置 CSRF 防护
- API 响应禁止包含 X-Powered-By 头（Helmet 默认移除）

请审查以下后端应用的 CORS 和安全头配置：

[粘贴 app 入口文件或中间件配置]

部署环境：
- 前端域名：[https://app.example.com]
- API 域名：[https://api.example.com]
- 认证方式：[JWT Bearer / Cookie Session]

检查项：
1. CORS origin 是否使用白名单？→ 配置具体域名
2. 是否使用了 Helmet 中间件？→ 添加 Helmet
3. 安全响应头是否完整？→ 检查 CSP、HSTS、X-Frame-Options 等
4. 是否允许了不必要的 HTTP 方法？→ 限制为必要方法
5. [如果使用 cookie] 是否有 CSRF 防护？→ 添加 CSRF token
6. 是否暴露了 X-Powered-By？→ 使用 Helmet 移除

请输出完整的安全中间件配置代码。

# .github/workflows/backend-security.yml
name: Backend Security Gate
 
on:
  pull_request:
    paths:
      - 'src/**'
      - 'prisma/**'
      - 'package.json'
 
jobs:
  security-check:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:17
        env:
          POSTGRES_USER: test
          POSTGRES_PASSWORD: test
          POSTGRES_DB: test
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
 
    steps:
      - uses: actions/checkout@v4
 
      - uses: pnpm/action-setup@v4
        with:
          version: 9
 
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: 'pnpm'
 
      - run: pnpm install --frozen-lockfile
 
      # TypeScript 类型检查
      - name: Type Check
        run: pnpm tsc --noEmit
 
      # ESLint 安全规则
      - name: Lint
        run: pnpm eslint src/ --max-warnings 0
 
      # 依赖漏洞扫描
      - name: Dependency Audit
        run: pnpm audit --audit-level=high
 
      # Semgrep 安全扫描
      - name: Semgrep Security Scan
        uses: semgrep/semgrep-action@v1
        with:
          config: >-
            p/sql-injection
            p/jwt
            p/secrets
            p/nodejs
            p/express
 
      # 密钥泄露检测
      - name: Secret Scan
        uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
      # 单元测试
      - name: Unit Tests
        run: pnpm vitest run --coverage
        env:
          DATABASE_URL: postgresql://test:test@localhost:5432/test
 
      # 检查测试覆盖率
      - name: Coverage Check
        run: |
          COVERAGE=$(pnpm vitest run --coverage --reporter=json | jq '.total.lines.pct')
          echo "Coverage: $COVERAGE%"
          if (( $(echo "$COVERAGE < 80" | bc -l) )); then
            echo "❌ Coverage below 80%!"
            exit 1
          fi

# .semgrep/backend-rules.yml
rules:
  # 检测字符串拼接 SQL
  - id: no-sql-string-concat
    patterns:
      - pattern: |
          $QUERY = `... ${$VAR} ...`
      - metavariable-regex:
          metavariable: $QUERY
          regex: ".*(SELECT|INSERT|UPDATE|DELETE|FROM|WHERE).*"
    message: "禁止字符串拼接 SQL 查询，使用参数化查询或 ORM"
    severity: ERROR
    languages: [typescript, javascript]
 
  # 检测硬编码密钥
  - id: no-hardcoded-secrets
    patterns:
      - pattern-either:
          - pattern: |
              jwt.sign($PAYLOAD, "...")
          - pattern: |
              jwt.verify($TOKEN, "...")
    message: "禁止硬编码 JWT 密钥，使用环境变量"
    severity: ERROR
    languages: [typescript, javascript]
 
  # 检测缺少输入验证的路由
  - id: missing-input-validation
    patterns:
      - pattern: |
          $ROUTER.$METHOD($PATH, async ($REQ, $RES) => {
            ...
            $ORM.create({ data: $REQ.body })
            ...
          })
    message: "禁止直接将 req.body 传递给数据库操作，必须先验证"
    severity: WARNING
    languages: [typescript, javascript]
 
  # 检测空 catch 块
  - id: no-empty-catch
    pattern: |
      catch ($ERR) { }
    message: "禁止空 catch 块，至少记录日志"
    severity: WARNING
    languages: [typescript, javascript]
 
  # 检测 console.log
  - id: no-console-log
    pattern: console.log(...)
    message: "使用结构化日志库（pino），禁止 console.log"
    severity: WARNING
    languages: [typescript, javascript]
    paths:
      exclude:
        - "**/*.test.ts"
        - "**/*.spec.ts"
 
  # 检测宽松 CORS
  - id: no-wildcard-cors
    pattern: |
      cors({ origin: "*" })
    message: "生产环境禁止 CORS origin: '*'，使用域名白名单"
    severity: ERROR
    languages: [typescript, javascript]

// package.json
{
  "lint-staged": {
    "src/**/*.ts": [
      "eslint --fix --max-warnings 0",
      "prettier --write"
    ],
    "prisma/**/*.prisma": [
      "prisma validate"
    ]
  }
}

# .husky/pre-commit
pnpm lint-staged
 
# 检测硬编码密钥
if grep -rn "password.*=.*['\"].*['\"]" src/ --include="*.ts" | grep -v "test\|spec\|mock\|example\|process\.env" | grep -q .; then
  echo "❌ 检测到硬编码密钥，请使用环境变量"
  exit 1
fi

请作为后端安全审查员，审查以下 PR diff，检查十大后端反模式：

[粘贴 git diff 输出]

检查清单：
1. ❌ SQL 注入：是否有字符串拼接 SQL？是否有未参数化的查询？
2. ❌ 认证绕过：JWT 算法是否安全？是否有权限检查？密码哈希是否安全？
3. ❌ 密钥泄露：是否有硬编码密钥？.env 是否在 .gitignore 中？
4. ❌ N+1 查询：是否有循环中的数据库查询？关联数据是否一次性加载？
5. ❌ 缺少验证：所有输入是否经过 Zod 验证？文件上传是否有限制？
6. ❌ 错误处理不当：是否泄露内部信息？是否有空 catch？是否区分 4xx/5xx？
7. ❌ 竞态条件：关键数据更新是否有锁？是否有幂等性保护？
8. ❌ 缺少限流：公开 API 是否有速率限制？登录端点是否有特殊限制？
9. ❌ 日志安全：日志中是否有敏感数据？是否使用结构化日志？
10. ❌ CORS/安全头：CORS 是否使用白名单？是否配置了安全响应头？

对每个发现的问题，请标注：
- 严重程度：🔴 必须修复（安全漏洞）/ 🟡 建议修复（性能/质量）/ 🟢 可选优化
- 具体位置：文件名 + 行号
- 修复建议：具体的代码修改方案
- OWASP 分类：对应的 OWASP API Security Top 10 编号（如适用）

---
inclusion: always
description: 电商后端项目安全与业务规则
globs: "src/**/*.ts"
---
 
# 电商后端规则
 
## 技术栈
- NestJS 11 + TypeScript strict
- Prisma ORM 6 + PostgreSQL 17
- Redis 8（缓存 + 分布式锁 + 限流存储）
- Stripe / 支付宝 支付集成
 
## 电商特定安全规则
- 所有金额使用整数（分/cents），禁止浮点数
- 金额计算禁止使用 JavaScript 浮点运算，使用 Decimal.js 或整数运算
- 订单创建必须实现幂等性（Idempotency-Key）
- 库存扣减必须使用数据库原子操作 + 事务
- 支付回调必须验证签名（Stripe webhook signature / 支付宝签名验证）
- 支付金额必须与订单金额一致（服务端校验，不信任客户端传递的金额）
- 订单状态变更必须记录审计日志
- 退款操作必须有管理员审批 + 二次确认
- 用户只能查看和操作自己的订单（ABAC 权限检查）
- 订单查询必须分页，禁止一次返回全部订单

请为电商系统生成订单创建服务。

需求：
- 用户提交购物车商品列表，创建订单
- 验证库存充足
- 扣减库存（原子操作）
- 创建订单记录
- 发起支付
- 支持幂等性（重复提交不创建重复订单）

技术栈：NestJS + Prisma + PostgreSQL + Redis
请遵循项目 Steering 规则生成代码。

请审查以下订单创建服务代码，检查十大后端反模式：

[AI 生成的订单服务代码]

重点检查：
1. 库存扣减是否有竞态条件？（并发下单可能超卖）
2. 订单创建是否有幂等性保护？
3. 金额计算是否使用整数？
4. 输入验证是否完整？
5. 错误处理是否安全？
6. 是否有 N+1 查询？
7. 日志是否安全（不泄露支付信息）？