// ✅ 好：使用 CSS 变量
<div className="bg-primary text-primary-foreground">
<button className="bg-accent hover:bg-accent/90">

// ❌ 差：硬编码颜色
<div className="bg-blue-500 text-white">
<button className="bg-green-600 hover:bg-green-700">

/* global.css */
:root {
  --background: 0 0% 100%;  /* 白色 */
  --foreground: 222 47% 11%;  /* 深色文本 */
}

.dark {
  --background: 224 71% 4%;  /* 深色背景 */
  --foreground: 213 31% 91%;  /* 浅色文本 */
}

<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3">
  {/* 移动端 1 列，平板 2 列，桌面 3 列 */}
</div>

// 所有交互元素必须可通过键盘访问
<button onClick={handleClick}>点击我</button>  ✅
<div onClick={handleClick}>点击我</div>        ❌

button:focus-visible {
  outline: 2px solid hsl(var(--primary));
  outline-offset: 2px;
}

<img src="/logo.png" alt="ProductReady Logo" />

✅ <nav>, <main>, <article>, <button>
❌ <div className="nav">, <div onClick={...}>

// src/lib/demo.ts
export function isDemoMode(searchParams?: URLSearchParams): boolean {
  return searchParams?.get('demo') === '1';
}

// 在 tRPC 路由器中
export const tasksRouter = createTRPCRouter({
  list: publicProcedure
    .input(z.object({ demo: z.boolean().optional() }))
    .query(async ({ ctx, input }) => {
      if (input.demo) {
        return { tasks: getDemoTasks() };  // 模拟数据
      }
      
      return { tasks: await ctx.db.select().from(tasks) };
    }),
});

/**
 * 创建带有 AI 生成描述的新任务
 * @param input - 任务标题和优先级
 * @returns 带有生成描述的创建任务
 * @throws {Error} 如果 AI 服务不可用
 */
export async function createTaskWithAI(
  input: CreateTaskInput
): Promise<Task> {
  const description = await generateDescription(input.title);
  return db.insert(tasks).values({ ...input, description });
}

# 检查更新
pnpm outdated

# 交互式更新
pnpm update -i

# 更新后测试
pnpm typecheck
pnpm lint
pnpm test
pnpm build

# 检查漏洞
pnpm audit

# 自动修复
pnpm audit --fix

// ✅ 好：完全类型安全
interface CreateTaskInput {
  title: string;
  description?: string;
  priority: 'low' | 'medium' | 'high' | 'urgent';
}

function createTask(input: CreateTaskInput): Promise<Task> {
  // TypeScript 确切知道 input 包含什么
  return db.insert(tasks).values(input).returning();
}

// ❌ 差：使用 `any` 失去所有安全性
function createTask(input: any) {
  // 不知道 input 包含什么 - 运行时错误！
  return db.insert(tasks).values(input);
}

import { z } from 'zod';

// 定义架构
const CreateTaskSchema = z.object({
  title: z.string().min(1).max(255),
  description: z.string().optional(),
  priority: z.enum(['low', 'medium', 'high', 'urgent']).default('medium'),
});

// 在 tRPC 中使用
export const tasksRouter = createTRPCRouter({
  create: protectedProcedure
    .input(CreateTaskSchema)  // ✅ 验证输入
    .mutation(async ({ input }) => {
      // 这里的 input 保证是有效的
      return db.insert(tasks).values(input);
    }),
});

// 数据库层 (PO) - 永远不要直接暴露！
const userPO = await db.query.users.findFirst({ 
  where: eq(users.id, userId) 
});
// 包含: passwordHash, stripeCustomerId 等

// API 层 (DTO) - 验证输入
const CreateUserDTO = z.object({
  email: z.string().email(),
  password: z.string().min(8),
  name: z.string(),
});

// UI 层 (VO) - 可以安全地返回到前端
interface UserVO {
  id: string;
  email: string;
  name: string;
  avatar: string | null;
  createdAt: string;  // ISO 字符串，不是 Date 对象
}

// 返回之前将 PO → VO 转换
function toUserVO(po: UserPO): UserVO {
  return {
    id: po.id,
    email: po.email,
    name: po.name,
    avatar: po.image,
    createdAt: po.createdAt.toISOString(),
  };
}

// ✅ 始终对敏感操作使用 protectedProcedure
export const tasksRouter = createTRPCRouter({
  delete: protectedProcedure  // 需要身份验证
    .input(z.object({ id: z.number() }))
    .mutation(async ({ ctx, input }) => {
      // ctx.session.user 保证存在
      const userId = ctx.session.user.id;
      
      // ✅ 删除前检查所有权
      const task = await db.query.tasks.findFirst({
        where: eq(tasks.id, input.id),
      });
      
      if (!task || task.userId !== userId) {
        throw new Error('未授权');
      }
      
      await db.delete(tasks).where(eq(tasks.id, input.id));
    }),
});

# ✅ 好：使用 .env 文件（git 忽略）
PG_DATABASE_URL="postgresql://..."
BETTER_AUTH_SECRET="..."

# ❌ 差：代码中硬编码
const secret = "super-secret-key-123";  // 永远不要这样做！

# ✅ 在浏览器中可用
NEXT_PUBLIC_APP_NAME="ProductReady"

# ✅ 仅服务器（安全）
PG_DATABASE_URL="postgresql://..."
STRIPE_SECRET_KEY="sk_live_..."

// ❌ 差：N+1 查询 (1 + N 个查询)
const tasks = await db.select().from(tasks);
for (const task of tasks) {
  const user = await db.select().from(users)
    .where(eq(users.id, task.userId));  // N 个查询！
}

// ✅ 好：使用连接的单个查询
const tasksWithUsers = await db
  .select({
    task: tasks,
    user: users,
  })
  .from(tasks)
  .leftJoin(users, eq(tasks.userId, users.id));

export const tasksRouter = createTRPCRouter({
  list: protectedProcedure
    .input(z.object({
      page: z.number().min(1).default(1),
      limit: z.number().min(1).max(100).default(20),
    }))
    .query(async ({ ctx, input }) => {
      const offset = (input.page - 1) * input.limit;
      
      const tasks = await ctx.db
        .select()
        .from(tasks)
        .limit(input.limit)
        .offset(offset);
      
      return { tasks, page: input.page, limit: input.limit };
    }),
});

# Neon - 使用端口 6543（池化）而不是 5432
PG_DATABASE_URL="postgresql://user:pass@host:6543/db"

# Supabase - 使用"连接池"字符串
PG_DATABASE_URL="postgresql://...pooler.supabase.com:6543/..."

// tests/e2e/auth.spec.ts
import { test, expect } from '@playwright/test';

test.describe('身份验证', () => {
  test('用户可以注册', async ({ page }) => {
    await page.goto('/signup');
    
    await page.fill('input[name="email"]', 'test@example.com');
    await page.fill('input[name="password"]', 'password123');
    await page.fill('input[name="name"]', '测试用户');
    
    await page.click('button[type="submit"]');
    
    // 应该重定向到仪表板
    await expect(page).toHaveURL('/dashboard');
  });
});

pnpm test:e2e       # 无头模式
pnpm test:e2e:ui    # 交互模式

// src/lib/utils.test.ts
import { describe, it, expect } from 'vitest';
import { formatCurrency } from './utils';

describe('formatCurrency', () => {
  it('正确格式化 USD', () => {
    expect(formatCurrency(1000, 'USD')).toBe('$1,000.00');
  });
  
  it('处理零', () => {
    expect(formatCurrency(0, 'USD')).toBe('$0.00');
  });
});

# 格式化和检查
pnpm lint

# 自动修复问题
pnpm lint --write

// tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true
  }
}

// ✅ 好：单一职责
function TaskCard({ task }: { task: Task }) {
  return (
    <div className="card">
      <h3>{task.title}</h3>
      <p>{task.description}</p>
    </div>
  );
}

function TaskList({ tasks }: { tasks: Task[] }) {
  return (
    <div className="grid gap-4">
      {tasks.map(task => <TaskCard key={task.id} task={task} />)}
    </div>
  );
}

// ❌ 差：太多职责
function TaskPage() {
  // 在一个组件中获取、过滤、排序、渲染
  // 500 行代码...
}

// src/app/api/health/route.ts
export async function GET() {
  return Response.json({
    status: 'healthy',
    timestamp: new Date().toISOString(),
    service: 'productready',
    version: process.env.VERSION || 'unknown',
    buildNumber: process.env.NEXT_PUBLIC_BUILD_NUMBER || '0',
  });
}

// src/app/layout.tsx
import * as Sentry from '@sentry/nextjs';

if (process.env.NODE_ENV === 'production') {
  Sentry.init({
    dsn: process.env.SENTRY_DSN,
    tracesSampleRate: 0.1,
  });
}