第 10 课：工程化与全栈化

┌─────────────────────────────────────────────────────────────────┐
│  🎯 核心观点：AI 时代的工程化 = 更简单的工具 + 更完整的数据流   │
├─────────────────────────────────────────────────────────────────┤
│  📚 你将学到：                                                   │
│    • 掌握 AI 驱动的 CI/CD 流水线设计                             │
│    • 学习项目配置与规范化的最佳实践                               │
│    • 理解 Biome 替代 ESLint + Prettier 的优势                    │
│    • 掌握前端全栈化趋势（Server Actions + tRPC + Supabase）     │
│    • 学习技术选型的评估矩阵方法                                   │
└─────────────────────────────────────────────────────────────────┘

# .github/workflows/ci.yml
- name: Smart Test Selection
  run: |
    # 分析变更文件
    CHANGED_FILES=$(git diff --name-only HEAD~1)
    # AI 分析影响范围，只运行相关测试
    turbo run test --filter=...[HEAD~1]

# 在 PR 中自动运行 AI Code Review
- name: AI Code Review
  uses: coderabbitai/ai-pr-reviewer@latest
  with:
    model: claude-sonnet-4-20250514

# .github/workflows/ai-ci.yml
name: AI-Driven CI/CD Pipeline

on:
  pull_request:
    branches: [main, develop]
  push:
    branches: [main]

# 同一个 PR 只保留最新的运行，取消之前的
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  # ============================================
  # 第一步：智能变更分析
  # ============================================
  analyze-changes:
    runs-on: ubuntu-latest
    outputs:
      affected-packages: ${{ steps.affected.outputs.packages }}
      has-frontend-changes: ${{ steps.affected.outputs.frontend }}
      has-backend-changes: ${{ steps.affected.outputs.backend }}
      risk-level: ${{ steps.risk.outputs.level }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # 需要完整历史来分析变更

      - name: Analyze affected packages
        id: affected
        run: |
          # 用 Turborepo 分析受影响的包
          AFFECTED=$(npx turbo run build --dry-run=json \
            --filter='...[origin/main...HEAD]' | \
            jq -r '.packages | join(",")')
          echo "packages=$AFFECTED" >> $GITHUB_OUTPUT

          # 判断前端/后端是否有变更
          if echo "$AFFECTED" | grep -q "web\|ui"; then
            echo "frontend=true" >> $GITHUB_OUTPUT
          fi
          if echo "$AFFECTED" | grep -q "api\|server"; then
            echo "backend=true" >> $GITHUB_OUTPUT
          fi

      - name: Assess risk level
        id: risk
        run: |
          # 根据变更范围评估风险等级
          CHANGED_FILES=$(git diff --name-only origin/main...HEAD)
          FILE_COUNT=$(echo "$CHANGED_FILES" | wc -l)

          if echo "$CHANGED_FILES" | grep -qE "schema\.prisma|migration"; then
            echo "level=high" >> $GITHUB_OUTPUT
          elif [ "$FILE_COUNT" -gt 20 ]; then
            echo "level=high" >> $GITHUB_OUTPUT
          elif [ "$FILE_COUNT" -gt 5 ]; then
            echo "level=medium" >> $GITHUB_OUTPUT
          else
            echo "level=low" >> $GITHUB_OUTPUT
          fi

  # ============================================
  # 第二步：AI 代码审查（并行）
  # ============================================
  ai-review:
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    permissions:
      pull-requests: write
      contents: read
    steps:
      - uses: actions/checkout@v4

      - name: AI Code Review
        uses: coderabbitai/ai-pr-reviewer@latest
        with:
          model: claude-sonnet-4-20250514
          review_comment_lgtm: false
          path_filters: |
            !dist/**
            !node_modules/**
            !*.lock
          extra_prompt: |
            重点关注以下方面：
            1. 类型安全：是否有 any 类型或类型断言
            2. 错误处理：async 函数是否有 try-catch
            3. 性能：是否有不必要的重渲染
            4. 安全：是否有 XSS 或注入风险
            5. 可访问性：交互元素是否有 aria 标签

  # ============================================
  # 第三步：智能测试（只测受影响的包）
  # ============================================
  smart-test:
    needs: analyze-changes
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'

      - run: pnpm install --frozen-lockfile

      - name: Run affected tests only
        run: |
          echo "受影响的包: ${{ needs.analyze-changes.outputs.affected-packages }}"
          echo "风险等级: ${{ needs.analyze-changes.outputs.risk-level }}"

          # 低风险：只跑受影响的包的测试
          # 高风险：跑全量测试
          if [ "${{ needs.analyze-changes.outputs.risk-level }}" = "high" ]; then
            echo "高风险变更，运行全量测试..."
            pnpm turbo run test
          else
            echo "运行受影响包的测试..."
            pnpm turbo run test --filter='...[origin/main...HEAD]'
          fi

      - name: Run E2E tests (only if frontend changed)
        if: needs.analyze-changes.outputs.has-frontend-changes == 'true'
        run: pnpm turbo run test:e2e --filter=web

  # ============================================
  # 第四步：构建和部署
  # ============================================
  deploy:
    needs: [analyze-changes, smart-test]
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'

      - run: pnpm install --frozen-lockfile
      - run: pnpm turbo run build

      - name: Deploy to Vercel
        uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
          vercel-args: '--prod'

# .coderabbit.yaml（放在项目根目录）
language: "zh-CN"
tone_instructions: "用中文回复，语气专业但友好"
early_access: true

reviews:
  # 自动审查设置
  auto_review:
    enabled: true
    # 忽略这些文件的审查
    ignore_title_keywords:
      - "WIP"
      - "DO NOT MERGE"
    drafts: false

  # 审查重点
  path_instructions:
    - path: "src/components/**"
      instructions: |
        审查 React 组件时重点关注：
        - 是否使用了 memo/useMemo/useCallback 优化性能
        - Props 类型是否完整定义
        - 是否有可访问性问题（aria 标签、键盘导航）
        - 是否正确处理了 loading/error 状态

    - path: "src/server/**"
      instructions: |
        审查服务端代码时重点关注：
        - 输入验证是否使用了 zod
        - 是否有 SQL 注入风险
        - 错误处理是否完善
        - 是否有敏感信息泄露

    - path: "prisma/**"
      instructions: |
        审查数据库变更时重点关注：
        - 迁移是否可逆
        - 是否需要数据回填
        - 索引是否合理
        - 是否有破坏性变更

apps/
  web/          # 前端应用
  admin/        # 管理后台
packages/
  ui/           # 共享 UI 组件库
  utils/        # 工具函数库
  database/     # Prisma 数据库层

# Turborepo 分析依赖图
$ pnpm turbo run test --filter='...[HEAD~1]' --dry-run

# 输出：
# - packages/ui        (直接变更)
# - apps/web           (依赖 ui)
# - apps/admin         (依赖 ui)
# - packages/utils     (不受影响，跳过 ✓)
# - packages/database  (不受影响，跳过 ✓)

// turbo.json
{
  "tasks": {
    "test": {
      "dependsOn": ["^build"],
      "inputs": ["src/**/*.ts", "src/**/*.tsx", "tests/**"],
      "outputs": ["coverage/**"],
      "cache": true
    },
    "test:affected": {
      "dependsOn": ["^build"],
      "cache": false
    }
  }
}

# 在 CI 中使用
pnpm turbo run test --filter='...[origin/main...HEAD]' --cache-dir=.turbo

# Turborepo 会：
# 1. 分析 origin/main 到 HEAD 之间的变更
# 2. 根据依赖图找出受影响的包
# 3. 检查缓存，跳过没有变化的测试
# 4. 只运行真正需要运行的测试

# 使用 pnpm 作为包管理器
package-manager=pnpm

# 严格的 peer dependencies 检查
strict-peer-dependencies=false
auto-install-peers=true

# 保存精确版本号（避免版本漂移）
save-exact=true

# 提升幽灵依赖
shamefully-hoist=false

# 公共提升模式（某些工具需要）
public-hoist-pattern[]=*eslint*
public-hoist-pattern[]=*prettier*

20.18.0

root = true

[*]
end_of_line = lf
insert_final_newline = true
charset = utf-8
trim_trailing_whitespace = true

[*.{js,jsx,ts,tsx,json,css,md}]
indent_style = space
indent_size = 2

[*.md]
trim_trailing_whitespace = false

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "biomejs.biome",
  "editor.codeActionsOnSave": {
    "quickfix.biome": "explicit",
    "source.organizeImports.biome": "explicit"
  },
  "files.eol": "\n",
  "files.insertFinalNewline": true,
  "tailwindCSS.experimental.classRegex": [
    ["cva\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"],
    ["cn\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"]
  ]
}

{
  "recommendations": [
    "biomejs.biome",
    "bradlc.vscode-tailwindcss",
    "usernamehw.errorlens",
    "christian-kohler.path-intellisense"
  ]
}

* text=auto

*.js text eol=lf
*.ts text eol=lf
*.json text eol=lf

*.png binary
*.jpg binary

node_modules
.next
out
dist
*.log
.env
.env.local
.DS_Store
*.tsbuildinfo

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      [
        'feat',     // 新功能
        'fix',      // 修复 bug
        'docs',     // 文档变更
        'style',    // 代码格式
        'refactor', // 重构
        'perf',     // 性能优化
        'test',     // 测试
        'chore',    // 构建/工具变动
      ],
    ],
    'subject-empty': [2, 'never'],
    'header-max-length': [2, 'always', 100],
  },
}

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npx --no -- commitlint --edit ${1}

# 项目名称

> 简短描述

## 快速开始

\`\`\`bash
pnpm install
pnpm dev
\`\`\`

## 技术栈

- Next.js 15
- Tailwind CSS v4
- shadcn/ui
- ...

## 项目结构

\`\`\`
src/
├── app/
├── components/
└── lib/
\`\`\`

# Changelog

## [Unreleased]

### Added
- 初始化项目

## [0.1.0] - 2026-03-27

### Added
- 项目初始化

---
name: Bug 报告
title: '[BUG] '
labels: bug
---

## Bug 描述
<!-- 清晰简洁地描述这个 bug -->

## 复现步骤
1. 访问 '...'
2. 点击 '...'

## 期望行为
<!-- 描述你期望发生什么 -->

## 环境信息
- 浏览器: [例如 Chrome 120]
- Node.js 版本: [例如 20.18.0]

## 摘要
<!-- 简要描述这个 PR 做了什么 -->

## 变更类型
- [ ] 🎉 新功能
- [ ] 🐛 Bug 修复
- [ ] 📝 文档更新

## 测试计划
- [ ] 本地测试通过
- [ ] Lint 检查通过

// ❌ 不好：依赖默认行为
{
  "scripts": {
    "build": "next build"
  }
}

// ✅ 好：显式声明环境
{
  "scripts": {
    "build": "NODE_ENV=production next build"
  },
  "engines": {
    "node": ">=20.18.0",
    "pnpm": ">=9.0.0"
  }
}

// ❌ 不好
{
  "shamefully-hoist": false
}

// ✅ 好
{
  // 不提升幽灵依赖，避免隐式依赖问题
  "shamefully-hoist": false
}

# 1. 初始化 package.json
pnpm init

# 2. 安装开发依赖
pnpm add -D @biomejs/biome husky @commitlint/cli @commitlint/config-conventional

# 3. 初始化 Biome
pnpm biome init

# 4. 初始化 Git Hooks
pnpm exec husky init

# 5. 创建配置文件（可以用 AI 生成）
# 在 Cursor 里输入：
# "帮我创建一套完整的项目配置文件，包括 .editorconfig、.npmrc、
#  commitlint.config.js、README.md、CHANGELOG.md"

// .eslintrc.json - 配置复杂
{
  "extends": [
    "eslint:recommended",
    "plugin:react/recommended",
    "plugin:@typescript-eslint/recommended",
    "prettier"
  ],
  "plugins": ["react", "@typescript-eslint", "import"],
  "rules": {
    "react/react-in-jsx-scope": "off",
    "import/order": ["error", { "groups": [...] }]
  }
}

// .prettierrc - 又一个配置文件
{
  "semi": false,
  "singleQuote": true,
  "trailingComma": "es5"
}

// biome.json - 一个文件搞定
{
  "$schema": "https://biomejs.dev/schemas/1.9.0/schema.json",
  "organizeImports": { "enabled": true },
  "linter": {
    "enabled": true,
    "rules": { "recommended": true }
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2
  }
}

// biome.json - 生产级完整配置
{
  "$schema": "https://biomejs.dev/schemas/2.0.0/schema.json",
  "vcs": {
    "enabled": true,
    "clientKind": "git",
    "useIgnoreFile": true,
    "defaultBranch": "main"
  },
  "organizeImports": {
    "enabled": true
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100,
    "lineEnding": "lf",
    "attributePosition": "auto"
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "trailingCommas": "all",
      "semicolons": "asNeeded",
      "arrowParentheses": "always",
      "bracketSpacing": true,
      "jsxQuoteStyle": "double"
    }
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "complexity": {
        "noExcessiveCognitiveComplexity": {
          "level": "warn",
          "options": { "maxAllowedComplexity": 15 }
        },
        "noForEach": "warn",
        "useFlatMap": "error"
      },
      "correctness": {
        "noUnusedVariables": "error",
        "noUnusedImports": "error",
        "useExhaustiveDependencies": "warn",
        "noUndeclaredVariables": "error"
      },
      "style": {
        "noNonNullAssertion": "warn",
        "useConst": "error",
        "useTemplate": "error",
        "noParameterAssign": "error"
      },
      "suspicious": {
        "noExplicitAny": "warn",
        "noConsoleLog": "warn",
        "noDebugger": "error"
      },
      "performance": {
        "noAccumulatingSpread": "warn",
        "noDelete": "warn"
      },
      "a11y": {
        "useButtonType": "error",
        "useAltText": "error",
        "noBlankTarget": "error"
      }
    }
  },
  "overrides": [
    {
      "include": ["**/*.test.ts", "**/*.test.tsx", "**/*.spec.ts"],
      "linter": {
        "rules": {
          "suspicious": {
            "noExplicitAny": "off",
            "noConsoleLog": "off"
          }
        }
      }
    },
    {
      "include": ["**/*.config.ts", "**/*.config.js"],
      "linter": {
        "rules": {
          "style": {
            "noDefaultExport": "off"
          }
        }
      }
    }
  ]
}

# 安装 Biome
pnpm add -D @biomejs/biome

# 初始化配置文件
pnpm biome init

# 从 ESLint 配置自动迁移
pnpm biome migrate eslint --write

# 从 Prettier 配置自动迁移
pnpm biome migrate prettier --write

{
  "scripts": {
    // 旧的（删掉）
    // "lint": "eslint . --ext .ts,.tsx",
    // "format": "prettier --write .",

    // 新的
    "lint": "biome lint .",
    "format": "biome format --write .",
    "check": "biome check --write .",
    "ci": "biome ci ."
  }
}

// .vscode/settings.json
{
  // 禁用旧的
  "eslint.enable": false,
  "prettier.enable": false,

  // 启用 Biome
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "quickfix.biome": "explicit",
    "source.organizeImports.biome": "explicit"
  },
  "[javascript]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[typescript]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[typescriptreact]": {
    "editor.defaultFormatter": "biomejs.biome"
  }
}

# 删除 ESLint 和 Prettier 相关依赖
pnpm remove eslint prettier \
  @typescript-eslint/eslint-plugin \
  @typescript-eslint/parser \
  eslint-config-prettier \
  eslint-plugin-react \
  eslint-plugin-import \
  eslint-plugin-react-hooks

# 删除旧配置文件
rm .eslintrc.json .prettierrc .eslintignore .prettierignore

# 用 Biome 格式化整个项目
pnpm biome check --write .

# 提交这次格式化变更
git add -A
git commit -m "chore: migrate from ESLint+Prettier to Biome"

// tsconfig.json - AI 时代的完整配置
{
  "compilerOptions": {
    // ========== 严格模式（全部开启）==========
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "noImplicitOverride": true,
    "noPropertyAccessFromIndexSignature": true,
    "exactOptionalPropertyTypes": true,
    "forceConsistentCasingInFileNames": true,

    // ========== 模块系统 ==========
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "verbatimModuleSyntax": true,

    // ========== 路径别名 ==========
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
      "@/components/*": ["./src/components/*"],
      "@/lib/*": ["./src/lib/*"],
      "@/types/*": ["./src/types/*"]
    },

    // ========== 输出 ==========
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "outDir": "./dist",
    "skipLibCheck": true,

    // ========== JSX ==========
    "jsx": "react-jsx",
    "lib": ["DOM", "DOM.Iterable", "ES2022"]
  },
  "include": ["src/**/*.ts", "src/**/*.tsx"],
  "exclude": ["node_modules", "dist", "**/*.test.ts"]
}

const arr = [1, 2, 3]

// 没开这个选项：arr[5] 的类型是 number（但实际是 undefined！）
// 开了这个选项：arr[5] 的类型是 number | undefined（必须检查）

const value = arr[5]
if (value !== undefined) {
  console.log(value * 2) // 安全
}

interface Config {
  theme?: 'light' | 'dark'
}

// 没开：可以写 { theme: undefined }（语义不清）
// 开了：只能写 { theme: 'light' } 或 { theme: 'dark' } 或 {}

// 好的写法（开启后强制要求）
import type { User } from './types'
import { createUser } from './actions'

// 不好的写法（开启后会报错）
import { User, createUser } from './types'

// AI 生成的代码（有一些格式问题）
import {useState,useEffect} from 'react'
import {User} from './types'

export default function UserList(){
  const [users,setUsers] = useState<User[]>([])
  var loading = true

  useEffect(()=>{
    fetch('/api/users').then(res=>res.json()).then(data=>{
      setUsers(data)
      loading = false
    })
  },[])

  return <div>
    {users.map(u=><div key={u.id}>{u.name}</div>)}
  </div>
}

// Biome 自动修复后
import { useState, useEffect } from 'react'

import type { User } from './types'

export default function UserList() {
  const [users, setUsers] = useState<User[]>([])
  // ⚠️ Biome 报错：使用 const 替代 var
  // ⚠️ Biome 报错：useExhaustiveDependencies - loading 不在依赖数组中
  const loading = true

  useEffect(() => {
    fetch('/api/users')
      .then((res) => res.json())
      .then((data) => {
        setUsers(data)
      })
  }, [])

  return (
    <div>
      {users.map((u) => (
        <div key={u.id}>{u.name}</div>
      ))}
    </div>
  )
}

# .github/workflows/quality.yml
name: Code Quality

on: [pull_request]

jobs:
  biome-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: pnpm install --frozen-lockfile

      # 先用 Biome 检查，快速反馈（< 1秒）
      - name: Biome Check
        run: pnpm biome ci .

      # Biome 通过后，再用 AI 做深度审查
      - name: AI Review
        if: success()
        uses: coderabbitai/ai-pr-reviewer@latest
        with:
          model: claude-sonnet-4-20250514

前端（React）→ API 层（REST/GraphQL）→ 后端（Node/Java）→ 数据库

Next.js（前端 + 后端 + API）→ 数据库

// app/actions.ts
'use server'

import { prisma } from '@/lib/prisma'
import { z } from 'zod'

const createUserSchema = z.object({
  name: z.string().min(2),
  email: z.string().email(),
})

export async function createUser(formData: FormData) {
  const data = createUserSchema.parse({
    name: formData.get('name'),
    email: formData.get('email'),
  })

  const user = await prisma.user.create({ data })
  return user
}

// app/page.tsx
import { createUser } from './actions'
import { Button } from '@/components/ui/button'
import { Input } from '@/components/ui/input'

export default function Page() {
  return (
    <form action={createUser} className="space-y-4 max-w-md mx-auto p-8">
      <Input name="name" placeholder="姓名" />
      <Input name="email" type="email" placeholder="邮箱" />
      <Button type="submit">创建用户</Button>
    </form>
  )
}

// app/actions/user.ts
'use server'

import { prisma } from '@/lib/prisma'
import { revalidatePath } from 'next/cache'
import { redirect } from 'next/navigation'
import { z } from 'zod'

// ========== Schema 定义 ==========
const userSchema = z.object({
  name: z.string().min(2, '姓名至少 2 个字符'),
  email: z.string().email('请输入有效的邮箱地址'),
  role: z.enum(['admin', 'user', 'editor']).default('user'),
})

// 统一的返回类型
type ActionResult<T = void> =
  | { success: true; data: T }
  | { success: false; error: string }

// ========== Create ==========
export async function createUser(
  formData: FormData
): Promise<ActionResult<{ id: string }>> {
  try {
    const parsed = userSchema.safeParse({
      name: formData.get('name'),
      email: formData.get('email'),
      role: formData.get('role'),
    })

    if (!parsed.success) {
      return {
        success: false,
        error: parsed.error.issues[0].message,
      }
    }

    const user = await prisma.user.create({
      data: parsed.data,
    })

    revalidatePath('/users')
    return { success: true, data: { id: user.id } }
  } catch (error) {
    if (error instanceof Error && error.message.includes('Unique')) {
      return { success: false, error: '该邮箱已被注册' }
    }
    return { success: false, error: '创建用户失败' }
  }
}

// ========== Read ==========
export async function getUsers(params?: {
  page?: number
  pageSize?: number
  search?: string
}) {
  const page = params?.page ?? 1
  const pageSize = params?.pageSize ?? 10
  const search = params?.search ?? ''

  const where = search
    ? {
        OR: [
          { name: { contains: search, mode: 'insensitive' as const } },
          { email: { contains: search, mode: 'insensitive' as const } },
        ],
      }
    : {}

  const [users, total] = await Promise.all([
    prisma.user.findMany({
      where,
      skip: (page - 1) * pageSize,
      take: pageSize,
      orderBy: { createdAt: 'desc' },
      select: {
        id: true,
        name: true,
        email: true,
        role: true,
        createdAt: true,
        _count: { select: { posts: true } },
      },
    }),
    prisma.user.count({ where }),
  ])

  return { users, total, totalPages: Math.ceil(total / pageSize) }
}

// ========== Update ==========
export async function updateUser(
  id: string,
  formData: FormData
): Promise<ActionResult> {
  try {
    const parsed = userSchema.partial().safeParse({
      name: formData.get('name') || undefined,
      email: formData.get('email') || undefined,
      role: formData.get('role') || undefined,
    })

    if (!parsed.success) {
      return { success: false, error: parsed.error.issues[0].message }
    }

    await prisma.user.update({
      where: { id },
      data: parsed.data,
    })

    revalidatePath('/users')
    return { success: true, data: undefined }
  } catch {
    return { success: false, error: '更新用户失败' }
  }
}

// ========== Delete ==========
export async function deleteUser(id: string): Promise<ActionResult> {
  try {
    await prisma.user.delete({ where: { id } })
    revalidatePath('/users')
    return { success: true, data: undefined }
  } catch {
    return { success: false, error: '删除用户失败' }
  }
}

// app/users/page.tsx
import { getUsers, deleteUser } from '@/app/actions/user'
import { UserTable } from './user-table'

export default async function UsersPage({
  searchParams,
}: {
  searchParams: Promise<{ page?: string; search?: string }>
}) {
  const params = await searchParams
  const page = Number(params.page) || 1
  const { users, total, totalPages } = await getUsers({
    page,
    search: params.search,
  })

  return (
    <div className="container mx-auto py-8">
      <h1 className="text-2xl font-bold mb-6">用户管理</h1>
      <UserTable
        users={users}
        total={total}
        totalPages={totalPages}
        currentPage={page}
        deleteAction={deleteUser}
      />
    </div>
  )
}

// server/routers/user.ts
import { router, publicProcedure } from '../trpc'
import { z } from 'zod'

export const userRouter = router({
  getById: publicProcedure
    .input(z.object({ id: z.string() }))
    .query(async ({ input }) => {
      return await prisma.user.findUnique({ where: { id: input.id } })
    }),

  create: publicProcedure
    .input(z.object({
      name: z.string(),
      email: z.string().email(),
    }))
    .mutation(async ({ input }) => {
      return await prisma.user.create({ data: input })
    }),
})

// 前端调用，完全类型安全
const user = trpc.user.getById.useQuery({ id: '123' })
// user 的类型自动推导，不需要手动定义

// server/trpc.ts
import { initTRPC, TRPCError } from '@trpc/server'
import superjson from 'superjson'
import { ZodError } from 'zod'

import type { Session } from 'next-auth'
import { prisma } from '@/lib/prisma'

// 上下文类型：每个请求都能访问到 prisma 和 session
interface CreateContextOptions {
  session: Session | null
}

export const createTRPCContext = (opts: CreateContextOptions) => {
  return {
    prisma,
    session: opts.session,
  }
}

const t = initTRPC.context<typeof createTRPCContext>().create({
  transformer: superjson,
  errorFormatter({ shape, error }) {
    return {
      ...shape,
      data: {
        ...shape.data,
        // 把 Zod 验证错误格式化成友好的消息
        zodError:
          error.cause instanceof ZodError
            ? error.cause.flatten()
            : null,
      },
    }
  },
})

export const router = t.router
export const publicProcedure = t.procedure

// 需要登录的 procedure
export const protectedProcedure = t.procedure.use(({ ctx, next }) => {
  if (!ctx.session?.user) {
    throw new TRPCError({ code: 'UNAUTHORIZED' })
  }
  return next({
    ctx: {
      session: { ...ctx.session, user: ctx.session.user },
    },
  })
})

// server/routers/user.ts
import { router, publicProcedure, protectedProcedure } from '../trpc'
import { z } from 'zod'
import { TRPCError } from '@trpc/server'

export const userRouter = router({
  // 公开接口：获取用户列表
  list: publicProcedure
    .input(
      z.object({
        page: z.number().min(1).default(1),
        pageSize: z.number().min(1).max(100).default(10),
        search: z.string().optional(),
      })
    )
    .query(async ({ ctx, input }) => {
      const where = input.search
        ? {
            OR: [
              { name: { contains: input.search } },
              { email: { contains: input.search } },
            ],
          }
        : {}

      const [users, total] = await Promise.all([
        ctx.prisma.user.findMany({
          where,
          skip: (input.page - 1) * input.pageSize,
          take: input.pageSize,
          orderBy: { createdAt: 'desc' },
        }),
        ctx.prisma.user.count({ where }),
      ])

      return { users, total, totalPages: Math.ceil(total / input.pageSize) }
    }),

  // 公开接口：获取单个用户
  getById: publicProcedure
    .input(z.object({ id: z.string() }))
    .query(async ({ ctx, input }) => {
      const user = await ctx.prisma.user.findUnique({
        where: { id: input.id },
        include: { posts: { orderBy: { createdAt: 'desc' }, take: 5 } },
      })

      if (!user) {
        throw new TRPCError({ code: 'NOT_FOUND', message: '用户不存在' })
      }

      return user
    }),

  // 需要登录：创建用户
  create: protectedProcedure
    .input(
      z.object({
        name: z.string().min(2),
        email: z.string().email(),
        role: z.enum(['admin', 'user', 'editor']).default('user'),
      })
    )
    .mutation(async ({ ctx, input }) => {
      return await ctx.prisma.user.create({ data: input })
    }),

  // 需要登录：更新用户
  update: protectedProcedure
    .input(
      z.object({
        id: z.string(),
        data: z.object({
          name: z.string().min(2).optional(),
          email: z.string().email().optional(),
          role: z.enum(['admin', 'user', 'editor']).optional(),
        }),
      })
    )
    .mutation(async ({ ctx, input }) => {
      return await ctx.prisma.user.update({
        where: { id: input.id },
        data: input.data,
      })
    }),

  // 需要登录：删除用户
  delete: protectedProcedure
    .input(z.object({ id: z.string() }))
    .mutation(async ({ ctx, input }) => {
      return await ctx.prisma.user.delete({ where: { id: input.id } })
    }),
})

// server/routers/_app.ts
import { router } from '../trpc'
import { userRouter } from './user'
import { postRouter } from './post'

export const appRouter = router({
  user: userRouter,
  post: postRouter,
})

// 导出类型给前端用
export type AppRouter = typeof appRouter

// lib/trpc.ts
import { createTRPCReact } from '@trpc/react-query'
import type { AppRouter } from '@/server/routers/_app'

export const trpc = createTRPCReact<AppRouter>()

// app/providers.tsx
'use client'

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { httpBatchLink } from '@trpc/client'
import { useState } from 'react'
import superjson from 'superjson'

import { trpc } from '@/lib/trpc'

export function TRPCProvider({ children }: { children: React.ReactNode }) {
  const [queryClient] = useState(() => new QueryClient())
  const [trpcClient] = useState(() =>
    trpc.createClient({
      links: [
        httpBatchLink({
          url: '/api/trpc',
          transformer: superjson,
        }),
      ],
    })
  )

  return (
    <trpc.Provider client={trpcClient} queryClient={queryClient}>
      <QueryClientProvider client={queryClient}>
        {children}
      </QueryClientProvider>
    </trpc.Provider>
  )
}

// app/users/user-list.tsx
'use client'

import { trpc } from '@/lib/trpc'

export function UserList() {
  // 查询 - 完全类型安全，input 和 output 都有类型提示
  const { data, isLoading, error } = trpc.user.list.useQuery({
    page: 1,
    pageSize: 10,
  })

  // 创建 - mutation 也是类型安全的
  const createUser = trpc.user.create.useMutation({
    onSuccess: () => {
      // 创建成功后自动刷新列表
      utils.user.list.invalidate()
    },
  })

  const utils = trpc.useUtils()

  if (isLoading) return <div>加载中...</div>
  if (error) return <div>错误: {error.message}</div>

  return (
    <div>
      <button
        onClick={() =>
          createUser.mutate({
            name: '张三',
            email: 'zhangsan@example.com',
          })
        }
      >
        添加用户
      </button>

      {data?.users.map((user) => (
        <div key={user.id}>
          {user.name} - {user.email}
        </div>
      ))}
    </div>
  )
}

// prisma/schema.prisma
model User {
  id        String   @id @default(cuid())
  name      String
  email     String   @unique
  posts     Post[]
  createdAt DateTime @default(now())
}

model Post {
  id        String   @id @default(cuid())
  title     String
  content   String
  author    User     @relation(fields: [authorId], references: [id])
  authorId  String
}

// prisma/schema.prisma
generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

// ========== 用户系统 ==========
model User {
  id        String   @id @default(cuid())
  name      String
  email     String   @unique
  avatar    String?
  role      Role     @default(USER)
  posts     Post[]
  comments  Comment[]
  profile   Profile?
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  @@index([email])
  @@index([role])
}

model Profile {
  id     String  @id @default(cuid())
  bio    String?
  github String?
  user   User    @relation(fields: [userId], references: [id], onDelete: Cascade)
  userId String  @unique
}

enum Role {
  USER
  EDITOR
  ADMIN
}

// ========== 内容系统 ==========
model Post {
  id          String    @id @default(cuid())
  title       String
  slug        String    @unique
  content     String
  excerpt     String?
  published   Boolean   @default(false)
  publishedAt DateTime?
  author      User      @relation(fields: [authorId], references: [id])
  authorId    String
  category    Category  @relation(fields: [categoryId], references: [id])
  categoryId  String
  tags        Tag[]
  comments    Comment[]
  viewCount   Int       @default(0)
  createdAt   DateTime  @default(now())
  updatedAt   DateTime  @updatedAt

  @@index([authorId])
  @@index([categoryId])
  @@index([published, publishedAt])
  @@index([slug])
}

model Category {
  id    String @id @default(cuid())
  name  String @unique
  slug  String @unique
  posts Post[]
}

model Tag {
  id    String @id @default(cuid())
  name  String @unique
  posts Post[]
}

model Comment {
  id        String   @id @default(cuid())
  content   String
  author    User     @relation(fields: [authorId], references: [id])
  authorId  String
  post      Post     @relation(fields: [postId], references: [id], onDelete: Cascade)
  postId    String
  createdAt DateTime @default(now())

  @@index([postId])
  @@index([authorId])
}

// lib/queries/post.ts
import { prisma } from '@/lib/prisma'

// 获取文章列表（带分页、筛选、关联查询）
export async function getPosts(params: {
  page?: number
  pageSize?: number
  categorySlug?: string
  tag?: string
  authorId?: string
  published?: boolean
}) {
  const {
    page = 1,
    pageSize = 10,
    categorySlug,
    tag,
    authorId,
    published = true,
  } = params

  const where = {
    published,
    ...(categorySlug && {
      category: { slug: categorySlug },
    }),
    ...(tag && {
      tags: { some: { name: tag } },
    }),
    ...(authorId && { authorId }),
  }

  const [posts, total] = await Promise.all([
    prisma.post.findMany({
      where,
      skip: (page - 1) * pageSize,
      take: pageSize,
      orderBy: { publishedAt: 'desc' },
      include: {
        author: {
          select: { id: true, name: true, avatar: true },
        },
        category: {
          select: { name: true, slug: true },
        },
        tags: {
          select: { name: true },
        },
        _count: {
          select: { comments: true },
        },
      },
    }),
    prisma.post.count({ where }),
  ])

  return { posts, total, totalPages: Math.ceil(total / pageSize) }
}

// 获取单篇文章（同时增加浏览量）
export async function getPostBySlug(slug: string) {
  const post = await prisma.post.update({
    where: { slug },
    data: { viewCount: { increment: 1 } },
    include: {
      author: {
        select: { id: true, name: true, avatar: true },
      },
      category: true,
      tags: true,
      comments: {
        include: {
          author: {
            select: { id: true, name: true, avatar: true },
          },
        },
        orderBy: { createdAt: 'desc' },
      },
    },
  })

  return post
}

// 事务操作：创建文章并关联标签
export async function createPost(data: {
  title: string
  content: string
  authorId: string
  categoryId: string
  tags: string[]
}) {
  const slug = data.title
    .toLowerCase()
    .replace(/[^a-z0-9]+/g, '-')
    .replace(/(^-|-$)/g, '')

  return await prisma.$transaction(async (tx) => {
    // 确保标签存在（不存在则创建）
    const tagRecords = await Promise.all(
      data.tags.map((name) =>
        tx.tag.upsert({
          where: { name },
          create: { name },
          update: {},
        })
      )
    )

    // 创建文章并关联标签
    return await tx.post.create({
      data: {
        title: data.title,
        slug,
        content: data.content,
        authorId: data.authorId,
        categoryId: data.categoryId,
        tags: {
          connect: tagRecords.map((tag) => ({ id: tag.id })),
        },
      },
      include: {
        tags: true,
        author: { select: { name: true } },
      },
    })
  })
}

import { createClient } from '@supabase/supabase-js'

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
)

// 查询数据
const { data: users } = await supabase
  .from('users')
  .select('*')
  .order('created_at', { ascending: false })

// 插入数据
const { data } = await supabase
  .from('users')
  .insert({ name: '张三', email: 'zhang@example.com' })
  .select()

// 实时订阅
supabase
  .channel('users')
  .on('postgres_changes', { event: '*', schema: 'public', table: 'users' }, (payload) => {
    console.log('Change received!', payload)
  })
  .subscribe()

// Vector 语义搜索
const { data: results } = await supabase.rpc('match_documents', {
  query_embedding: embedding,
  match_threshold: 0.78,
  match_count: 10,
})

前端代码库：
  src/api/user.ts      → fetch('/api/users')  → ???
  src/types/user.ts    → 手动定义 User 类型   → 可能和后端不一致

后端代码库：
  routes/user.ts       → 处理 /api/users      → ???
  models/user.ts       → 数据库模型            → 前端看不到

同一个代码库：
  prisma/schema.prisma → 数据结构（唯一真相源）
  server/routers/*.ts  → API 逻辑（类型自动推导）
  app/**/*.tsx         → 前端页面（类型自动传递）

全栈化的错误链：
  TypeScript 编译错误
    → "Property 'phone' does not exist on type 'User'"
    → 直接定位到 prisma schema 缺少字段
    → AI 自动修复

传统架构的错误：
  运行时错误
    → "Cannot read property 'phone' of undefined"
    → 是前端的问题？后端的问题？API 文档的问题？
    → AI 无法判断

Next.js 15 (App Router)
  → Server Actions (后端逻辑)
  → Prisma (数据库 ORM) / Supabase (BaaS)
  → shadcn/ui + Tailwind (前端 UI)
  → Vercel AI SDK (AI 功能)
  → Biome (代码质量)
  → Turborepo (Monorepo)

CSS Modules:
  (3×3) + (4×3) + (2×2) + (3×2) + (3×2) + (3×1)
  = 9 + 12 + 4 + 6 + 6 + 3 = 40 分

Tailwind CSS:
  (4×3) + (5×3) + (5×2) + (5×2) + (5×2) + (5×1)
  = 12 + 15 + 10 + 10 + 10 + 5 = 62 分

styled-components:
  (3×3) + (3×3) + (4×2) + (4×2) + (3×2) + (4×1)
  = 9 + 9 + 8 + 8 + 6 + 4 = 44 分

目标：团队对齐，环境准备

□ 技术调研报告（用评估矩阵的结果）
□ 团队内部分享会（30 分钟，讲清楚为什么要迁移）
□ 搭建 Demo 项目（用新技术栈实现一个小功能）
□ 编写团队编码规范（新技术的 do's and don'ts）
□ 配置开发环境
  - IDE 插件安装指南
  - biome.json / tsconfig.json 配置
  - CI/CD 流水线更新
□ 确定试点项目（选一个低风险的新功能或新页面）

目标：小范围验证，积累经验

□ 在试点项目中使用新技术栈
□ 安排 1-2 个有经验的人先行，其他人 pair programming
□ 每天 15 分钟站会，分享遇到的问题和解决方案
□ 收集反馈：
  - 开发效率对比（新 vs 旧）
  - AI 辅助效果对比
  - 遇到的坑和解决方案
□ 输出试点报告：
  - 实际开发效率数据
  - 团队满意度
  - 需要调整的配置或规范

目标：全面推广，新项目全部使用新技术栈

□ 根据试点反馈调整编码规范
□ 全团队培训（基于试点期积累的经验）
□ 新功能/新页面全部使用新技术栈
□ 旧代码按需迁移（不强制，遇到修改时顺便迁移）
□ 建立代码模板库（常用模式的代码片段）
□ 更新 AI 工具的 Rules/Instructions
  - 告诉 AI 使用新技术栈
  - 提供项目的编码规范作为上下文

目标：清理旧代码，沉淀最佳实践

□ 制定旧代码迁移优先级（高频修改的文件优先）
□ 利用 AI 辅助批量迁移旧代码
□ 删除旧依赖和配置文件
□ 更新项目文档
□ 输出迁移总结：
  - 总耗时和人力成本
  - 迁移前后的效率对比数据
  - 最佳实践和踩坑记录
  - 给其他团队的建议