IDE 配置与 Rules 记忆体系

<!-- .cursor/rules/api-routes.mdc -->
---
globs: app/api/**/*.ts
---
# API Route Rules
- Always validate request body with zod
- Return proper HTTP status codes (400, 401, 403, 404, 500)
- Include rate limiting headers
- Log errors to Sentry

<!-- .cursor/rules/server-actions.mdc -->
---
globs: lib/actions/**/*.ts
---
# Server Action Rules
- Every action must start with requirePermission() check
- Use 'use server' directive at the top
- Validate all inputs with zod
- Revalidate affected paths after mutations
- Return typed results, not throw errors

<!-- .cursor/rules/components.mdc -->
---
globs: components/**/*.tsx
---
# Component Rules
- Use Server Components by default
- Add 'use client' only when using hooks, event handlers, or browser APIs
- Import UI primitives from @/components/ui/
- Use cn() for conditional classNames
- Props interface must be exported

<!-- .cursorrules -->
# Project: NextSaaS Platform
 
## Tech Stack
- Next.js 15 with App Router (NOT Pages Router)
- TypeScript in strict mode
- Drizzle ORM with PostgreSQL (NOT Prisma, NOT raw SQL)
- Tailwind CSS v4 + shadcn/ui components
- Clerk for authentication
- Stripe for billing
- Inngest for background jobs
- Upstash Redis for caching and rate limiting
- Vercel for deployment
 
## Architecture
- app/(dashboard)/ - Authenticated routes with sidebar layout
- app/(marketing)/ - Public marketing pages
- app/(admin)/admin/ - Super admin panel
- app/api/ - REST APIs and webhooks only
- lib/actions/ - All mutations via Server Actions
- lib/db/schema.ts - Single source of truth for database schema
- lib/ai/ - AI feature modules
- components/ui/ - shadcn primitives (do not modify)
- components/ - App-level components
 
## Code Conventions
- Server Components by default; 'use client' only when required
- Server Actions for mutations; API routes only for webhooks and external APIs
- All DB queries must include tenantId (multi-tenant isolation)
- Use zod for validation everywhere (forms, API inputs, env vars)
- Error handling: return { error: string } from actions, never throw
- Use nanoid() for short IDs, uuid for database primary keys
- Prefer const arrow functions: const fn = () => {}
- Use path aliases: @/lib/, @/components/, @/app/
 
## Auth & Security
- requirePermission('resource:action') at the start of every Server Action
- Never expose sensitive data in Client Components
- Environment variables: validated with zod at startup
- API routes: validate auth token from headers
 
## Testing
- Vitest for unit tests
- Playwright for E2E tests
- Test files: __tests__/*.test.ts
- Mock database with drizzle-mock
 
## Common Patterns
- Pagination: use cursor-based pagination with startAfter
- Forms: React Hook Form + zod resolver + Server Action
- Optimistic updates: useOptimistic() hook
- Loading states: Suspense boundaries with skeleton fallbacks

# NextSaaS Platform
 
## Quick Start
```bash
pnpm install          # Install dependencies
pnpm dev              # Start dev server at localhost:3000
pnpm db:generate      # Generate Drizzle migrations
pnpm db:push          # Push schema to database
pnpm db:studio        # Open Drizzle Studio
pnpm test             # Run Vitest tests
pnpm test:e2e         # Run Playwright E2E tests
pnpm lint             # ESLint + TypeScript check
pnpm build            # Production build

<!-- .windsurf/rules/testing.md -->
---
trigger: glob
globs: **/*.test.ts, **/*.spec.ts
---
# Testing Rules
- Use Vitest with describe/it pattern
- Mock external services, never call real APIs in tests
- Test both success and error paths

# Global AI Rules
 
## Behavior
- Think step by step before writing code
- Ask for clarification if the task is ambiguous
- Prefer editing existing code over creating new files
- Never delete tests or weaken assertions
- Always preserve existing comments
 
## Security
- Never hardcode secrets, API keys, or passwords
- Never expose server-only data in client components
- Validate all external inputs
- Use parameterized queries, never string concatenation for SQL

# Project Rules
(内容同 2.2 节和 3.3 节的模板)

<!-- .cursor/rules/database.mdc -->
---
globs: lib/db/**/*.ts
---
# Database Module Rules
- Schema changes: add fields as nullable first, then backfill, then add NOT NULL
- All tables must have: id, tenantId, createdAt, updatedAt
- Use Drizzle's .returning() for INSERT/UPDATE
- Index all foreign keys and frequently queried columns
- Soft delete: add deletedAt column instead of DELETE

// scripts/generate-rules.ts
import fs from 'fs'
import path from 'path'
 
// 单一数据源
const PROJECT_RULES = {
  name: 'NextSaaS',
  stack: {
    framework: 'Next.js 15 (App Router)',
    language: 'TypeScript (strict)',
    orm: 'Drizzle ORM + PostgreSQL',
    styling: 'Tailwind CSS v4 + shadcn/ui',
    auth: 'Clerk',
    payments: 'Stripe',
  },
  conventions: [
    'Server Components by default',
    'Server Actions for mutations',
    'All DB queries must include tenantId',
    'zod for all input validation',
    'requirePermission() at start of every Server Action',
  ],
  commands: {
    dev: 'pnpm dev',
    test: 'pnpm test',
    build: 'pnpm build',
    dbGenerate: 'pnpm db:generate',
    dbPush: 'pnpm db:push',
  },
}
 
// 生成 .cursorrules
function generateCursorRules(): string {
  return `# ${PROJECT_RULES.name}
 
## Tech Stack
${Object.entries(PROJECT_RULES.stack).map(([k, v]) => `- ${v}`).join('\n')}
 
## Code Conventions
${PROJECT_RULES.conventions.map(c => `- ${c}`).join('\n')}
`
}
 
// 生成 CLAUDE.md
function generateClaudeMd(): string {
  return `# ${PROJECT_RULES.name}
 
## Commands
${Object.entries(PROJECT_RULES.commands).map(([k, v]) => `- \`${v}\``).join('\n')}
 
## Tech Stack
${Object.entries(PROJECT_RULES.stack).map(([k, v]) => `- ${v}`).join('\n')}
 
## Conventions
${PROJECT_RULES.conventions.map(c => `- ${c}`).join('\n')}
`
}
 
fs.writeFileSync('.cursorrules', generateCursorRules())
fs.writeFileSync('CLAUDE.md', generateClaudeMd())
console.log('Rules generated for all tools.')