前端代理技能
⚠️ 预生成检查清单(必须执行)
在创建任何 UI 组件之前,请完成以下清单:
PRE_GENERATION_CHECKLIST:
1. READ_DESIGN_SYSTEM:
- [ ] 阅读 /DESIGN-SYSTEM.md 了解禁止模式
- [ ] 检查 /src/app/globals.css 中的 @theme 块以获取令牌
- [ ] 注意:accent-500 = #ff6b35 (橙色)
2. CHECK_EXISTING_COMPONENTS:
- [ ] 查看 /src/components/ui/ 目录(共 48 个组件)
- [ ] 检查 components.json 中的 shadcn 配置
- [ ] 审查着陆页中的现有模式
3. REFERENCE_UI_LIBRARIES:
- [ ] 参阅 /docs/UI-LIBRARY-INDEX.md 获取高级组件
- [ ] 优先级:项目 → StyleUI/KokonutUI/Cult UI → shadcn 基础
- [ ] 切勿未经自定义直接使用 shadcn 默认样式
4. VERIFY_NO_FORBIDDEN_PATTERNS:
- [ ] 禁止使用 bg-white、text-gray-600 或通用悬停样式
- [ ] 禁止使用统一的 grid-cols-3 gap-4 布局
- [ ] 禁止使用未设置样式的 <Card className="p-6">
- [ ] 禁止使用不带品牌颜色的图标
禁止的代码模式:
// ❌ 切勿生成这些
className="bg-white rounded-lg shadow p-4" // 通用卡片
className="grid grid-cols-3 gap-4" // 统一网格
className="text-gray-600" // 默认弱化
className="hover:bg-gray-100" // 通用悬停
<Card className="p-6"> // 无样式 shadcn
必需的代码模式:
// ✅ 始终使用设计令牌
className="bg-bg-card border border-border-base hover:border-accent-500"
className="text-text-primary"
className="text-text-secondary"
className="bg-accent-500 hover:bg-accent-400"
概述
前端代理负责 Unite-Hub Next.js 应用程序的所有 UI/UX 工作:
- React 19 / Next.js 16 开发,使用 App Router
- shadcn/ui 组件的实现和自定义
- Tailwind CSS 样式和响应式设计
- 路由创建和面包屑设置
- 客户端状态管理(React Context、hooks)
- 辅助功能和性能优化
如何使用此代理
触发方式
用户说:“修复仪表盘布局”、“添加新的联系人页面”、“更新导航”、“创建模态组件”
代理的操作
1. 理解请求
需要提出的问题:
- 需要处理哪个页面/组件?
- 期望的行为是什么?
- 是否有设计参考(截图、线框图)?
- 优先级是什么(P0/P1/P2)?
2. 分析当前实现
步骤 A:定位文件
# 查找组件或页面
find src/app -name "*.tsx" | grep -i "contacts"
find src/components -name "*.tsx" | grep -i "hotleads"
步骤 B:读取当前代码
// 使用 text_editor 工具
text_editor.view("src/app/dashboard/contacts/page.tsx")
步骤 C:识别依赖
- 使用了哪些 shadcn/ui 组件?
- 消费了哪些上下文(AuthContext 等)?
- 调用了哪些 API 路由?
- 执行了哪些数据库查询?
3. 实现更改
步骤 A:组件更新
对于现有组件:
// src/components/HotLeadsPanel.tsx
import { Button } from "@/components/ui/button";
import { Card } from "@/components/ui/card";
import { useAuth } from "@/contexts/AuthContext";
export function HotLeadsPanel({ workspaceId }: { workspaceId: string }) {
const { currentOrganization } = useAuth();
// 获取热门线索
const [leads, setLeads] = useState([]);
useEffect(() => {
async function fetchLeads() {
const res = await fetch("/api/agents/contact-intelligence", {
method: "POST",
body: JSON.stringify({ action: "get_hot_leads", workspaceId }),
});
const data = await res.json();
setLeads(data.leads || []);
}
if (workspaceId) fetchLeads();
}, [workspaceId]);
return (
<Card>
{/* UI 实现 */}
</Card>
);
}
步骤 B:路由创建
对于新页面:
// src/app/dashboard/new-page/page.tsx
import { Metadata } from "next";
export const metadata: Metadata = {
title: "新页面 | Unite Hub",
description: "新页面的描述"
};
export default async function NewPage() {
return (
<div className="container mx-auto py-8">
<h1 className="text-3xl font-bold">新页面</h1>
{/* 内容 */}
</div>
);
}
步骤 C:shadcn/ui 组件
如有需要,安装新组件:
npx shadcn@latest add dialog
npx shadcn@latest add dropdown-menu
npx shadcn@latest add toast
按照 shadcn 模式使用组件:
import {
Dialog,
DialogContent,
DialogDescription,
DialogHeader,
DialogTitle,
DialogTrigger,
} from "@/components/ui/dialog";
<Dialog>
<DialogTrigger asChild>
<Button>打开对话框</Button>
</DialogTrigger>
<DialogContent>
<DialogHeader>
<DialogTitle>标题</DialogTitle>
<DialogDescription>描述</DialogDescription>
</DialogHeader>
{/* 内容 */}
</DialogContent>
</Dialog>
4. 添加工作区过滤(V1 关键)
所有数据库查询必须按工作区过滤:
// ❌ 错误 - 显示所有工作区的数据
const { data: contacts } = await supabase
.from("contacts")
.select("*");
// ✅ 正确 - 只显示用户工作区的数据
const { data: contacts } = await supabase
.from("contacts")
.select("*")
.eq("workspace_id", workspaceId);
以下表必须过滤:
contacts-.eq("workspace_id", workspaceId)campaigns-.eq("workspace_id", workspaceId)drip_campaigns-.eq("workspace_id", workspaceId)emails-.eq("workspace_id", workspaceId)generatedContent-.eq("workspace_id", workspaceId)
5. 处理加载和错误状态
加载状态:
const [isLoading, setIsLoading] = useState(true);
const [error, setError] = useState<string | null>(null);
useEffect(() => {
async function fetchData() {
try {
setIsLoading(true);
const data = await fetch("...");
setData(data);
} catch (err) {
setError(err.message);
} finally {
setIsLoading(false);
}
}
fetchData();
}, []);
if (isLoading) return <Spinner />;
if (error) return <ErrorBanner message={error} />;
return <DataDisplay data={data} />;
6. 响应式设计
Tailwind 断点:
<div className="
grid grid-cols-1 // 手机:1 列
md:grid-cols-2 // 平板:2 列
lg:grid-cols-3 // 桌面:3 列
gap-4
">
{/* 卡片 */}
</div>
移动优先方法:
- 从移动布局开始(默认类)
- 添加
md:类用于平板 - 添加
lg:和xl:类用于桌面
7. 测试更改
步骤 A:视觉测试
# 启动开发服务器
npm run dev
# 在浏览器中导航到页面
# 在移动视口下测试(开发者工具)
# 测试深色主题
步骤 B:辅助功能
// 检查:
// - 适当的 ARIA 标签
// - 键盘导航
// - 聚焦状态
// - 屏幕阅读器支持
<button aria-label="关闭对话框">×</button>
<input aria-describedby="email-help" />
<div role="alert" aria-live="polite">{error}</div>
步骤 C:性能
// 对昂贵组件使用 React.memo
import { memo } from "react";
export const ExpensiveComponent = memo(function ExpensiveComponent({ data }) {
return <div>{/* 渲染 */}</div>;
});
// 对重量级组件使用动态导入
import dynamic from "next/dynamic";
const HeavyChart = dynamic(() => import("@/components/HeavyChart"), {
loading: () => <Spinner />,
ssr: false
});
常见任务
任务 1:修复缺失的工作区过滤
示例:仪表盘概览页面显示所有联系人
步骤:
- 读取
src/app/dashboard/overview/page.tsx - 查找所有 Supabase 查询
- 为每个查询添加
.eq("workspace_id", workspaceId) - 在查询前添加 workspaceId 的空检查
- 使用多个工作区进行测试
代码:
// 之前
const { data: contacts } = await supabase.from("contacts").select("*");
// 之后
if (!workspaceId) {
return <div>未选择工作区</div>;
}
const { data: contacts, error } = await supabase
.from("contacts")
.select("*")
.eq("workspace_id", workspaceId);
if (error) {
console.error("获取联系人时出错:", error);
return <ErrorBanner />;
}
任务 2:创建新的仪表盘页面
示例:向仪表盘添加“分析”页面
步骤:
- 创建
src/app/dashboard/analytics/page.tsx - 在
src/app/dashboard/layout.tsx的导航中添加链接 - 使用 shadcn/ui 组件实现页面内容
- 添加面包屑导航
- 测试导航
代码:
// src/app/dashboard/analytics/page.tsx
import { Metadata } from "next";
import { Card } from "@/components/ui/card";
export const metadata: Metadata = {
title: "分析 | Unite Hub",
};
export default async function AnalyticsPage() {
return (
<div className="container mx-auto py-8 space-y-6">
<div>
<h1 className="text-3xl font-bold">分析</h1>
<p className="text-muted-foreground">跟踪您的营销活动表现</p>
</div>
<div className="grid grid-cols-1 md:grid-cols-3 gap-6">
<Card>
{/* 统计卡片 1 */}
</Card>
<Card>
{/* 统计卡片 2 */}
</Card>
<Card>
{/* 统计卡片 3 */}
</Card>
</div>
</div>
);
}
// src/app/dashboard/layout.tsx - 添加到导航
const navigation = [
{ name: "仪表盘", href: "/dashboard/overview", icon: HomeIcon },
{ name: "联系人", href: "/dashboard/contacts", icon: UsersIcon },
{ name: "营销活动", href: "/dashboard/campaigns", icon: MailIcon },
{ name: "分析", href: "/dashboard/analytics", icon: ChartIcon }, // 新增
];
任务 3:实现按钮功能
示例:热门线索面板中的“发送邮件”按钮
步骤:
- 读取
src/components/HotLeadsPanel.tsx - 找到按钮位置
- 实现 onClick 处理函数
- 调用相应的 API 端点
- 显示成功/错误提示
代码:
import { useToast } from "@/components/ui/use-toast";
function HotLeadsPanel() {
const { toast } = useToast();
async function handleSendEmail(contactId: string) {
try {
const res = await fetch("/api/emails/send", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ contactId, templateType: "followup" }),
});
if (!res.ok) throw new Error("发送邮件失败");
toast({
title: "邮件已发送",
description: "您的邮件已加入发送队列。",
});
} catch (error) {
toast({
variant: "destructive",
title: "错误",
description: error.message,
});
}
}
return (
<Button onClick={() => handleSendEmail(contact.id)}>
发送邮件
</Button>
);
}
样式指南
Tailwind CSS 最佳实践
使用工具类:
// ✅ 好
<div className="flex items-center justify-between p-4 bg-background border rounded-lg">
// ❌ 坏(自定义 CSS)
<div style={{ display: "flex", padding: "16px" }}>
使用主题中的 CSS 变量:
// 定义在 globals.css 中
@layer base {
:root {
--background: 0 0% 100%;
--foreground: 222.2 84% 4.9%;
--card: 0 0% 100%;
--primary: 222.2 47.4% 11.2%;
}
}
// 在组件中使用
<div className="bg-background text-foreground">
<div className="bg-card text-card-foreground">
<div className="bg-primary text-primary-foreground">
响应式设计:
<div className="
text-sm md:text-base lg:text-lg
p-2 md:p-4 lg:p-6
grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3
">
组件库参考
可用的 shadcn/ui 组件
accordion- 可折叠内容面板alert-dialog- 模态确认对话框avatar- 用户个人资料图片badge- 状态徽章button- 交互按钮card- 内容容器checkbox- 表单复选框dialog- 模态对话框dropdown-menu- 下拉菜单input- 文本输入框label- 表单标签popover- 浮动内容progress- 进度指示器radio-group- 单选按钮组select- 选择下拉框switch- 切换开关tabs- 标签页界面toast- 通知提示tooltip- 悬停提示
安装新组件:
npx shadcn@latest add [组件名称]
错误处理模式
API 错误
try {
const res = await fetch("/api/...");
const data = await res.json();
if (!res.ok) {
throw new Error(data.error || "出了点问题");
}
return data;
} catch (error) {
console.error("API 错误:", error);
toast({
variant: "destructive",
title: "错误",
description: error.message,
});
return null;
}
Supabase 错误
const { data, error } = await supabase.from("contacts").select("*");
if (error) {
console.error("Supabase 错误:", error);
return <ErrorBanner message="加载联系人失败" />;
}
if (!data || data.length === 0) {
return <EmptyState message="未找到联系人" />;
}
return <ContactsList contacts={data} />;
版本 1 约束
V1 中我们修复的内容:
- ✅ 所有页面的工作区过滤
- ✅ 热门线索按钮功能
- ✅ 联系人详情页面导航
- ✅ 仪表盘统计卡片
- ✅ 加载和错误状态
- ✅ 响应式设计修复
V1 中我们不构建的内容:
- ❌ 高级动画
- ❌ 自定义主题构建器
- ❌ 拖放界面
- ❌ 实时协作 UI
- ❌ 移动应用程序
关键要点
- 始终按工作区过滤 - 数据隔离至关重要
- 使用 shadcn/ui 组件 - 不要重复造轮子
- 遵循 Tailwind 约定 - 实用优先方法
- 处理加载/错误状态 - 永远不要显示空白屏幕
- 测试响应式设计 - 手机、平板、桌面