37 · 综合实战项目

前端（React + Vite）
├── React 18 + TypeScript
├── React Router v6 —— 路由管理
├── Tailwind CSS —— 样式框架
├── React Markdown —— Markdown 渲染
├── Zustand —— 轻量状态管理
└── Vitest —— 单元测试

后端（Node.js）
├── Express + TypeScript
├── Prisma —— ORM / 数据库迁移
├── SQLite —— 本地数据库（开发）
├── JWT —— 身份认证
├── Zod —— 请求校验
└── Supertest —— API 测试

用户：我需要设计 NoteFlow 的数据库模型。用户有注册登录功能，
每篇笔记属于一个用户，可以有多个标签。标签也可以被多个笔记共享。
帮我设计 Prisma schema。

Plan Mode：分析需求，给出 schema 设计

model User {
  id        String   @id @default(cuid())
  email     String   @unique
  name      String
  password  String
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
  notes     Note[]
  tags      Tag[]
}
 
model Note {
  id        String      @id @default(cuid())
  title     String
  content   String
  archived  Boolean     @default(false)
  createdAt DateTime    @default(now())
  updatedAt DateTime    @updatedAt
  authorId  String
  author    User        @relation(fields: [authorId], references: [id])
  tags      NoteTag[]
}
 
model Tag {
  id        String   @id @default(cuid())
  name      String
  color     String   @default("#6366f1")
  userId    String
  user      User     @relation(fields: [userId], references: [id])
  notes     NoteTag[]
  @@unique([name, userId])
}
 
model NoteTag {
  noteId String
  note   Note @relation(fields: [noteId], references: [id])
  tagId  String
  tag    Tag  @relation(fields: [tagId], references: [id])
  @@id([noteId, tagId])
}

需求清单：
- POST /api/auth/register —— 注册
- POST /api/auth/login —— 登录
- GET /api/notes —— 获取笔记列表（支持搜索、标签过滤、分页）
- POST /api/notes —— 创建笔记
- GET /api/notes/:id —— 获取单篇笔记
- PUT /api/notes/:id —— 更新笔记
- DELETE /api/notes/:id —— 软删除（归档）
- GET /api/tags —— 获取用户的所有标签
- POST /api/tags —— 创建标签

/               → 首页 / 登录跳转
/login          → 登录页
/register       → 注册页
/dashboard      → 笔记列表（主页面）
/notes/new      → 新建笔记
/notes/:id      → 编辑笔记
/tags           → 标签管理

noteflow/
├── server/                 # 后端
│   ├── prisma/
│   │   └── schema.prisma   # 数据模型
│   ├── src/
│   │   ├── routes/         # 路由
│   │   ├── middleware/     # 中间件（auth, validation）
│   │   ├── lib/            # 工具函数
│   │   └── index.ts        # 入口
│   ├── package.json
│   └── tsconfig.json
├── client/                 # 前端
│   ├── src/
│   │   ├── components/     # 通用组件
│   │   ├── pages/          # 页面
│   │   ├── stores/         # Zustand 状态
│   │   ├── lib/            # API 调用封装
│   │   └── App.tsx
│   ├── package.json
│   ├── vite.config.ts
│   └── tailwind.config.js
├── .github/
│   └── workflows/          # CI/CD
└── README.md

┌─────────┐          ┌──────────┐          ┌─────────┐
│  Client  │          │  Server  │          │  DB     │
└────┬────┘          └────┬─────┘          └────┬────┘
     │  POST /login       │                     │
     │  {email, password} │                     │
     │───────────────────>│                     │
     │                    │  SELECT user         │
     │                    │─────────────────────>│
     │                    │  user data           │
     │                    │<─────────────────────│
     │                    │  bcrypt.compare()    │
     │                    │  sign JWT            │
     │  {token, user}     │                     │
     │<───────────────────│                     │
     │                    │                     │
     │  GET /notes        │                     │
     │  Authorization:    │                     │
     │  Bearer <token>    │                     │
     │───────────────────>│                     │
     │                    │  verify JWT          │
     │                    │  attach req.user     │
     │                    │  SELECT notes        │
     │                    │─────────────────────>│
     │  [{id, title...}]  │                     │
     │<───────────────────│                     │

Agent prompt：帮我搭建 NoteFlow 后端项目骨架。
使用 Express + TypeScript + Prisma + SQLite。
初始化 npm，配置 tsconfig，安装所有依赖，创建 Prisma schema，
并实现以下 API：
- POST /api/auth/register
- POST /api/auth/login
- GET /api/notes（带搜索和标签过滤）
- POST /api/notes
- PUT /api/notes/:id
- DELETE /api/notes/:id（软删除）
- GET /api/tags
- POST /api/tags
需要 JWT 认证中间件，密码用 bcrypt 加密，请求用 Zod 校验。

cd server
npx prisma migrate dev --name init
npm run dev

# 注册
curl -X POST http://localhost:3001/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","name":"测试用户","password":"123456"}'
 
# 登录
curl -X POST http://localhost:3001/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"123456"}'
 
# 用返回的 token 创建笔记
curl -X POST http://localhost:3001/api/notes \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"title":"我的第一篇笔记","content":"# Hello World\n这是一篇测试笔记。","tags":["学习"]}'

Agent prompt：为 NoteFlow 创建 React + Vite + TypeScript 前端。
配置 Tailwind CSS，安装 React Router、Zustand、react-markdown。
创建以下页面组件（先用模拟数据占位）：
- LoginPage —— 登录表单
- RegisterPage —— 注册表单
- DashboardPage —— 笔记列表
- NoteEditorPage —— Markdown 编辑器 + 预览
- TagsPage —— 标签管理
并在 App.tsx 中配置路由。

// 你输入：
interface NoteCardProps {
  note: Note;
  onEdit: (id: string) => void;
  onDelete: (id: string) => void;
}
 
// 输入完 interface 后开始写组件：
export function NoteCard({ note, onEdit, onDelete }: NoteCardProps) {
  return (
    // 在这里输入 <div 后，Cursor 会预测整个卡片结构
    <div className="bg-white rounded-lg shadow p-4 hover:shadow-md transition-shadow">
      <div className="flex justify-between items-start">
        <h3 className="text-lg font-semibold text-gray-900">{note.title}</h3>
        <div className="flex space-x-2">
          <button onClick={() => onEdit(note.id)} className="...">编辑</button>
          <button onClick={() => onDelete(note.id)} className="...">删除</button>
        </div>
      </div>
      <p className="text-gray-600 mt-2 line-clamp-3">{note.content}</p>
      <div className="flex gap-1 mt-3">
        {note.tags.map(tag => (
          <span key={tag.id} className="...">{tag.name}</span>
        ))}
      </div>
    </div>
  );
}

// 你已经写了 createNote 的 handler，现在写 updateNote：
export const updateNote: RequestHandler = async (req, res) => {
  const { id } = req.params;
  const { title, content, tags } = req.body;
  // 输入 const note = await 后，Cursor 会预测：
  const note = await prisma.note.update({
    where: { id },
    data: {
      title,
      content,
      tags: {
        set: [],
        connectOrCreate: tags?.map(name => ({
          where: { name_userId: { name, userId: req.user!.id } },
          create: { name, userId: req.user!.id }
        }))
      }
    },
    include: { tags: { include: { tag: true } } }
  });
  res.json(note);
};

在 Cursor 的 Chat 中切换到 Debug 模式（Cmd + Shift + D），
粘贴错误信息：

POST /api/notes 401 (Unauthorized)
{"error":"未授权访问"}

提示：Debug 模式

Access to fetch at 'http://localhost:3001/api/notes' from origin 
'http://localhost:5173' has been blocked by CORS policy.

Debug 提示：prisma.note.create 调用中 tags 的 connectOrCreate 逻辑有误。

create: { name, userId: req.user!.id }

cd noteflow
git init
git add -A
git commit -m "chore: init project structure with backend + frontend"

main           —— 生产分支
  └─ develop   —— 开发分支
       ├─ feat/auth       —— 用户认证模块
       ├─ feat/notes      —— 笔记管理模块
       ├─ feat/search     —— 搜索功能
       └─ fix/cors        —— CORS 修复

# 从 develop 切出功能分支
git checkout -b feat/auth develop
 
# 开发完成后合并回 develop
git checkout develop
git merge feat/auth
 
# 发布时合并到 main
git checkout main
git merge develop
git tag v0.1.0

在 Chat 中输入：
"Review the diff of this branch. 
Check for: security issues, error handling gaps, 
TypeScript type safety, and SQL injection risks."

feat: implement JWT auth with register and login endpoints
feat: add note CRUD API with tag association
feat: create React frontend with routing and auth pages
feat: implement Markdown editor with preview
fix: resolve token storage key mismatch in frontend
fix: add CORS config for development environment
feat: add note search by title and content
refactor: extract API client into reusable module
feat: add dark mode support with Tailwind
docs: update README with setup instructions
chore: configure CI with GitHub Actions

Agent prompt：为 NoteFlow 前端配置 Vercel 部署。
需要：
1. 在 client/ 目录下创建 vercel.json
2. 配置 rewrites 让所有路由 fallback 到 index.html
3. 设置 build command 和 output directory
4. 添加 .env.example 说明需要的环境变量

{
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "devCommand": "npm run dev",
  "rewrites": [
    { "source": "/(.*)", "destination": "/index.html" }
  ]
}

cd client
npx vercel --prod

# .env (本地开发)
DATABASE_URL="file:./dev.db"
JWT_SECRET="dev-secret-key"
PORT=3001
FRONTEND_URL="http://localhost:5173"

# 生产环境 (Railway)
DATABASE_URL="postgresql://user:pass@host:5432/noteflow"
JWT_SECRET="<随机生成的强密钥>"
PORT=8080
FRONTEND_URL="https://noteflow.vercel.app"

# .github/workflows/ci.yml
name: CI
 
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]
 
jobs:
  test:
    runs-on: ubuntu-latest
    
    services:
      postgres:
        image: postgres:15
        env:
          POSTGRES_DB: noteflow_test
          POSTGRES_USER: test
          POSTGRES_PASSWORD: test
        ports:
          - 5432:5432
    
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      
      - name: Install dependencies
        run: |
          cd server && npm ci
          cd ../client && npm ci
      
      - name: Run backend tests
        run: cd server && npm test
      
      - name: Run frontend tests
        run: cd client && npm test
      
      - name: Build check
        run: |
          cd server && npm run build
          cd ../client && npm run build

Cursor 能力树
│
├── 规划层 ◄ Plan Mode
│   ├── 数据库建模
│   ├── API 设计
│   ├── 路由规划
│   └── 架构决策
│
├── 开发层 ◄ Agent + Tab
│   ├── 项目脚手架搭建
│   ├── 后端功能实现
│   ├── 前端页面开发
│   └── 接口联调
│
├── 质量层 ◄ Debug + Code Review
│   ├── 认证 Bug 修复
│   ├── CORS 配置修复
│   ├── 数据库查询修复
│   └── 代码安全审查
│
└── 部署层 ◄ Agent + Terminal
    ├── 构建配置
    ├── 环境变量管理
    ├── CI/CD 配置
    └── 自动化部署

Plan Mode（5 分钟） → 讨论方案
Agent（15 分钟） → 实现功能
手动测试（3 分钟） → 验证正确性
Tab 补全 + 手动编码（10 分钟） → 打磨细节
Debug 模式（如果有问题） → 修复 Bug
Git 提交（2 分钟） → 保存工作