Cursor Agent 端到端开发实战

Normal 模式：
  你: "添加用户搜索功能"
  AI: [生成 3 个文件的修改]
  你: [逐个确认] → 发现缺少 import → 手动修复

Agent 模式：
  你: "添加用户搜索功能"
  AI: [读取相关文件] → [生成代码] → [运行 TypeScript 检查]
      → [发现类型错误] → [自动修复] → [运行 lint] → 完成

需求：
- 系统事件（成员加入、任务分配、文件上传）触发通知
- 用户在导航栏看到未读通知数
- 点击通知铃铛展开通知列表
- 标记单条/全部已读
- 通知持久化到数据库

Prompt:
我要实现站内通知系统。第一步：设计数据库 schema。

参考 @lib/db/schema.ts 中已有表的风格，
创建 notifications 表，包含：
- id (uuid PK)
- tenantId (关联 tenants)
- userId (接收者，关联 users)
- type (通知类型：member_joined, task_assigned, file_uploaded, system)
- title (通知标题)
- body (通知内容，可选)
- metadata (jsonb，存事件相关数据如 taskId, fileId)
- isRead (是否已读)
- readAt (已读时间)
- createdAt

同时创建索引：userId + isRead（查未读通知）、tenantId + createdAt（按时间查询）

Prompt:
基于刚创建的 notifications 表，实现通知的 Server Actions。

文件：lib/actions/notification.ts
参考 @lib/actions/project.ts 的权限检查模式。

实现以下功能：
1. createNotification(data) - 内部使用，不需要权限检查
   参数：tenantId, userId, type, title, body?, metadata?
   
2. getNotifications(page?) - 获取当前用户通知列表
   分页，每页 20 条，最新的在前
   
3. getUnreadCount() - 获取未读通知数量
   返回数字，用于导航栏角标
   
4. markAsRead(notificationId) - 标记单条已读
   验证通知属于当前用户
   
5. markAllAsRead() - 标记所有未读为已读
   只更新当前用户当前租户的通知

Prompt:
实现通知触发逻辑——在业务事件发生时自动创建通知。

文件：lib/notifications/triggers.ts

实现：
1. notifyMemberJoined(tenantId, newMember)
   - 通知租户下所有 admin："[name] 加入了团队"
   
2. notifyTaskAssigned(task, assignee)
   - 通知被分配者："你有新任务：[task.title]"
   
3. notifyFileUploaded(file, uploader)
   - 通知项目所有成员："[uploader.name] 上传了 [file.name]"

然后修改现有的 Server Actions，在适当位置调用这些触发器：
- @lib/actions/invitation.ts 的 acceptInvitation 后调用 notifyMemberJoined
- @lib/actions/task.ts 的 createTask 后调用 notifyTaskAssigned（如果有 assignee）

注意：通知创建不应阻塞主流程，用 Promise 但不 await。

Prompt:
实现通知 UI 组件。

1. components/notification-bell.tsx (Client Component)
   - 铃铛图标 + 未读数角标（红色圆点）
   - 每 30 秒轮询 getUnreadCount()
   - 点击展开通知面板

2. components/notification-panel.tsx (Client Component)
   - Popover 面板，从铃铛下方弹出
   - 通知列表，每条显示：图标（按 type）+ title + 时间
   - 未读通知左侧有蓝色竖线标记
   - 点击通知 → 标记已读 + 跳转到相关页面（用 metadata 中的链接）
   - 顶部"Mark all as read"按钮
   - 底部"View all notifications"链接

3. 将 NotificationBell 集成到 @app/(dashboard)/layout.tsx 的顶部导航栏

使用 @components/ui/ 的 Popover, Button, ScrollArea 组件
图标用 lucide-react 的 Bell, Check, Circle

Prompt:
给通知系统做以下优化：

1. 用 React useOptimistic 实现标记已读的乐观更新
   - 点击后立即在 UI 上标记为已读
   - 后台调用 Server Action
   - 失败时回退

2. 给 lib/actions/notification.ts 编写单元测试
   文件：lib/actions/__tests__/notification.test.ts
   测试场景：
   - 创建通知 → 验证数据库记录
   - 获取通知列表 → 验证分页和排序
   - 标记已读 → 验证 isRead 和 readAt 更新
   - 标记非自己的通知 → 应该报错

// 单文件引用——精确
"参考 @lib/db/schema.ts 的 users 表"

// 目录引用——理解模块
"分析 @lib/actions/ 目录下所有文件的错误处理模式"

// Codebase 搜索——探索
"@Codebase 找到所有使用 tenantId 过滤的查询"

// Web 引用——查文档
"@Web 查找 Next.js 15 的 useOptimistic 用法"

// Docs 引用——官方文档
"@Docs shadcn/ui Popover 组件的 API"

// 组合引用——最强
"参考 @lib/actions/project.ts 的模式，
 使用 @lib/db/schema.ts 中的 notifications 表，
 @Docs Next.js Server Actions 的最新用法"

// 选中一个函数 → Cmd+K
"添加 try-catch 错误处理，错误时返回 { error: message }"

// 选中一段 JSX → Cmd+K
"添加 loading 状态，显示 Skeleton"

// 选中 SQL 查询 → Cmd+K
"添加 tenantId 过滤条件"

// 选中类型定义 → Cmd+K
"添加 avatar 和 bio 可选字段"

方法 1：红线修复
  → 鼠标悬停错误红线 → 点击 "Fix with AI"
  → Cursor 自动理解错误并修复

方法 2：终端错误
  → 终端输出错误 → 选中错误文本 → Cmd+L 发送到 Chat
  → "修复这个错误"

方法 3：Composer 全局修复
  → Cmd+I 打开 Composer
  → "运行 pnpm build，修复所有 TypeScript 错误"
  → Agent 会自动运行 build → 读取错误 → 逐个修复 → 重新 build

// 1. 给负面约束
"不要使用 any 类型，不要使用 useEffect 获取数据"

// 2. 指定文件路径
"创建文件：app/(dashboard)/notifications/page.tsx"
（不指定路径，AI 可能放到错误位置）

// 3. 先生成类型，再生成实现
"先定义 Notification 的 TypeScript 类型，然后再写查询函数"

// 4. 分步验证
"先只做数据库 schema，我验证后再继续"

Prompt:
实现订阅计划管理功能，需要以下文件：

1. lib/db/schema.ts → 添加 plans 和 subscriptions 表
2. lib/actions/subscription.ts → CRUD Server Actions
3. app/(dashboard)/settings/billing/page.tsx → 计费设置页面
4. app/(dashboard)/settings/billing/plan-selector.tsx → 套餐选择器组件
5. app/api/stripe/webhook/route.ts → 修改现有 Webhook，处理订阅事件

参考现有的文件风格：
- Schema: @lib/db/schema.ts
- Actions: @lib/actions/project.ts
- Pages: @app/(dashboard)/settings/page.tsx

Prompt:
将所有硬编码的错误消息提取为常量。

1. 创建 lib/constants/errors.ts，定义错误消息常量
2. 扫描 @lib/actions/ 目录下所有文件
3. 将 throw new Error('xxx') 替换为使用常量
4. 将 return { error: 'xxx' } 替换为使用常量
5. 不要改变任何业务逻辑

示例：
  之前: return { error: 'Project not found' }
  之后: return { error: ERRORS.PROJECT_NOT_FOUND }

Prompt:
运行 pnpm build 后有以下 TypeScript 错误：

[粘贴终端输出]

请逐一修复这些错误。要求：
- 不要改变业务逻辑
- 不要使用 @ts-ignore 或 as any
- 如果需要修改类型定义，请说明原因

Prompt:
@app/(dashboard)/projects/page.tsx 这个页面加载很慢（>3s）。
@lib/actions/project.ts 是它的数据获取逻辑。

请分析可能的性能瓶颈：
1. 是否有 N+1 查询？
2. 是否缺少数据库索引？
3. 是否有不必要的数据获取？
4. 能否用 React Suspense 做并行加载？

给出具体的优化方案和代码修改。

Prompt:
页面出现 Hydration mismatch 错误：

"Text content does not match server-rendered HTML"

相关组件：@components/user-avatar.tsx

这通常是因为 Server 和 Client 渲染的 HTML 不一致。
请分析原因并修复，常见原因：
- 使用了 Date.now() 或 Math.random()
- 条件渲染依赖浏览器 API（window, localStorage）
- CSS-in-JS 的样式注入顺序

不要用 suppressHydrationWarning 作为修复方案。

1. 开始新功能
   → 打开 Composer Agent
   → 用 CRAFT 模板描述需求
   → 指定参考文件

2. 代码生成后
   → 扫一眼 diff（不用逐行，看结构是否合理）
   → Accept 所有文件
   → 运行 pnpm build 检查类型
   → 如有错误 → 在 Composer 继续修复

3. 功能验证
   → 在浏览器测试基本流程
   → 如发现问题 → Inline Chat 局部修复

4. 收尾
   → "给这个功能添加必要的 loading 和 error 状态"
   → "检查是否遗漏了权限检查和输入验证"
   → Git commit

1. 收集信息
   → 复制完整错误信息
   → 确认复现步骤

2. 发送给 Chat（Cmd+L）
   → 粘贴错误 + 相关文件引用
   → "分析根因，不要直接修复"

3. 确认根因后
   → 在 Composer 中修复
   → "修复 [具体问题]，参考刚才的分析"

4. 验证
   → 运行测试
   → 手动复现确认修复