crm-builder

CRM 构建器技能

此技能的作用

此技能定义了如何构建 CRM 工具——一种用于管理联系人、公司、交易及其相互关系的系统。

CRM 在结构上与 CPQ 和 Trades 构建器不同：

• CPQ / Trades = 一条记录依次经过各个阶段（步进导航）
• CRM = 多种实体类型彼此关联（实体导航）

左侧边栏使用导航器模式（联系人、公司、交易、销售管道、活动），而非步进器。用户在不同实体视图之间切换，而不是依次经过各个阶段。

常见垂直领域： 销售团队、咨询公司、代理机构、专业服务、房地产、招聘、B2B 服务，以及任何需要跟踪关系和交易的企业。

构建器会读取此技能，读取 DOMAIN.md 中关于特定业务术语和销售管道阶段的内容，并使用客户实际的实体、字段和工作流生成可运行的原型。

何时使用此技能

当对话记录或 DOMAIN.md 中包含以下信号时，使用此技能：

信号	示例
联系人/人员跟踪	“客户数据到处都是”、“找不到之前联系过的人”、“联系人信息在电子表格里”
销售管道	“交易”、“商机”、“销售管道”、“阶段”、“赢单/输单”
后续跟进跟踪	“后续跟进总是被遗漏”、“没人知道上次是谁打的电话”
关系管理	“转介绍”、“谁认识谁”、“客户管理”
线索管理	“来自网站的线索”、“主动咨询”、“线索来源跟踪”

请勿在以下情况下使用此技能：

• 带定价的产品配置 → 使用 cpq-builder
• 建筑/工种项目跟踪 → 使用 trades-builder
• 库存和存货管理 → 使用 erp-builder（未来推出）

---

模板约定

开始构建之前，请了解模板提供的内容，以及此技能要补充的内容。约定如下：

模板（app/layouts/MainLayout.tsx）自带：

• SidebarProvider、Sidebar、SidebarContent、SidebarInset、SidebarTrigger — 已完成连接
• SidebarContent 为空 — 这是你的填充区域
• 页眉中有一个品牌栏位（徽标占位符 + 公司名称）
• 页眉右侧区域有 ModeToggle 和用户菜单

此技能补充以下内容：

• SidebarContent — 添加实体导航（销售管道、联系人、公司、交易、活动）、快捷筛选器和最近记录（见下文的布局模式）
• 页眉中的品牌栏位 — 使用 DOMAIN.md 中客户的徽标和公司名称
• 页眉右侧区域 — 在现有用户菜单前添加角色切换器 DropdownMenu，如果空间允许，再添加全局搜索输入框
• <main> 中的 <Outlet /> — 通过各实体视图的路由组件实现（默认显示销售管道）

此技能不会：

• 添加第二个 Sidebar 组件。这里只有一个侧边栏。
• 在 SidebarContent 中放置品牌块。品牌仅位于页眉中。
• 重新连接 SidebarProvider 或替换可折叠行为。使用现有配置。
• 构建步进器。CRM 使用实体导航——并行视图，而非依次经过各个阶段。
• 默认将详情视图折叠为弹出层或模态框。列表/详情采用整页模式（列表视图 → 点击 → 在主内容区域显示详情视图）。

如果你发现自己想要重构 MainLayout.tsx，请停下来——答案几乎总是填充 SidebarContent。

---

区块定义

CRM 工具有五个区块。与 CPQ/trades-builder 不同，这些区块不是依次经过的阶段，而是并行的实体视图。用户可以在它们之间自由切换。

第 1 节：销售管道

功能： 以可视化看板展示交易在各个阶段的推进情况。

显示内容：

• 看板式列布局，每个销售管道阶段对应一列，阶段取自 DOMAIN.md
• 如果 DOMAIN.md 未定义阶段，则使用：潜在客户 → 合格客户 → 提案 → 谈判 → 赢单 / 输单
• 每笔交易显示：交易名称、公司、金额、负责人、处于该阶段的天数
• 可在列之间拖放交易（或点击以变更阶段）
• 每列上都有“添加交易”按钮
• 按负责人、日期范围或交易金额筛选

如果 DOMAIN.md 中没有销售管道阶段，则使用上述默认阶段。客户在查看原型后可以进一步调整。

第 2 节：联系人

功能： 以列表/详情视图展示人员。

列表视图：

• 联系人表格或精简列表
• 列：姓名、邮箱、电话、公司、最近活动、标签
• 搜索和筛选
• “添加联系人”按钮

详情视图（点击联系人后）：

• 联系人详情：姓名、邮箱、电话、公司（可点击链接）、角色/职位、来源、备注
• 下方显示活动时间线：电话、邮件、会议、备注——按最近时间优先排列
• 关联交易：与此联系人关联的交易列表
• “记录活动”按钮：快速添加电话、邮件、会议或备注，并填写日期和描述

DOMAIN.md 中的字段：

• 实体注册表 → Contact 实体字段作为联系人详情字段
• 术语表 → 使用准确的字段名称和标签
• 如果 DOMAIN.md 未定义联系人字段，则使用：姓名、邮箱、电话、公司、角色、来源、备注

第 3 节：公司

功能： 以列表/详情视图展示组织。

列表视图：

• 公司表格
• 列：公司名称、行业、联系人数、交易数、交易总金额
• 搜索和筛选
• “添加公司”按钮

详情视图（点击公司后）：

• 公司详情：名称、行业、规模、网站、地址、备注
• 联系人标签页：与此公司关联的人员列表
• 交易标签页：与此公司关联的交易列表
• 活动时间线：汇总此公司所有联系人的活动

DOMAIN.md 中的字段：

• 实体注册表 → Company/Account 实体字段
• 如果未定义，则使用：名称、行业、规模、网站、地址、备注

第 4 节：交易

功能： 以列表/详情视图展示交易/商机。

列表视图：

• 交易表格
• 列：交易名称、公司、联系人、金额、阶段（徽标）、预计成交日期、负责人
• 按金额、阶段、预计成交日期排序
• 按阶段、负责人筛选
• “添加交易”按钮

详情视图（点击交易后）：

• 交易详情：名称、金额、阶段（可选择的下拉菜单）、预计成交日期、成交概率、负责人
• 关联联系人和公司（可点击链接）
• 此交易专属的活动时间线
• 备注区
• 处于最终阶段时显示“标记为赢单”/“标记为输单”操作按钮

阶段推进：

• 交易阶段是一个 Select 下拉菜单，选项取自 DOMAIN.md 中的销售管道阶段
• 更改阶段后，销售管道看板视图会自动更新
• 赢单/输单是终止阶段——选中时显示赢单/输单原因字段

第 5 节：活动

功能： 按时间顺序展示 CRM 中的所有活动。

显示内容：

• 时间线/动态视图，按最近时间优先排列
• 每项活动显示：类型图标（电话/邮件/会议/备注）、描述、关联联系人、关联交易、日期、记录人
• 按活动类型、日期范围、人员筛选
• 顶部显示“记录活动”按钮

活动类型： 电话、邮件、会议、备注、任务。使用图标加以区分。

• 如果 DOMAIN.md 定义了其他活动类型，则使用那些类型。

布局模式

CRM 工具默认采用双栏布局（左侧边栏 + 主内容区）。查看记录详情时，会根据需要显示右侧边栏。

这不是分步布局。 左侧边栏用于实体导航，而非按顺序展示阶段。

左侧边栏（始终可见，可折叠）

模板中已配置好 SidebarProvider、Sidebar、SidebarContent 和 SidebarTrigger，位于 app/layouts/MainLayout.tsx。SidebarContent 为空 — 此技能会在其中填入实体导航。不要重新配置边栏，不要添加第二个 Sidebar 组件，也不要在其中放置品牌标识。品牌标识只放在页眉中（见上文的模板约定）。

边栏标题： 使用类似“CRM”或“企业名称 + CRM”的上下文标签 — 不要使用工作流描述。如果企业名称较短，“[Business] CRM”读起来很自然；如果名称较长，只用“CRM”即可。标题应描述导航的性质。

组件	内容
实体导航	SidebarContent 内的垂直导航列表，包含五个版块：Pipeline、Contacts、Companies、Deals、Activities。每个导航项显示：图标、标签和记录数量徽标。点击后跳转到相应实体的视图。这是导航器，不是步骤条 — 不要显示步骤编号、完成状态，也不要采用顺序流程。
快捷筛选器	在导航下方显示用户创建的已保存筛选器或视图。例如：“我的商机”“热门潜在客户”“本周跟进”。
最近访问的记录	在筛选器下方显示最近访问的 3–5 条记录（任意实体类型），方便快速导航。每条记录显示名称和实体类型徽标。将此版块固定在边栏靠近底部的位置，以便无需滚动即可查看。

主内容区（中间 — 随版块变化）

根据选中的导航项渲染当前版块。 同一时间仅显示一个版块。

{activeSection === "pipeline" && <PipelineView />}
{activeSection === "contacts" && <ContactsView />}
{activeSection === "companies" && <CompaniesView />}
{activeSection === "deals" && <DealsView />}
{activeSection === "activities" && <ActivitiesView />}

各版块中的列表/详情模式：

• 默认视图：根据实体类型显示列表、表格或轻量看板。
• 点击记录：进入详情视图，显示全宽版块、活动时间线和关联记录。
• 使用“返回列表”按钮或面包屑导航返回。
• 这是标准的 Salesforce/HubSpot 模式。

右侧边栏（上下文信息 — 在详情视图中显示）

查看记录详情（联系人、公司或商机）时，右侧边栏可以显示：

• 快速摘要 — 一目了然地查看关键字段
• 关联记录 — 相关联系人、商机或公司
• 即将进行的活动 — 下一次安排的电话/会议

此边栏对原型而言是可选的。如果主内容区空间充足，详情视图也可以采用单面板布局。只有当记录详情受益于同时显示上下文信息时，才添加右侧边栏。

RBAC 行为

• 使用 DOMAIN.md 中的 User Roles 或 Stakeholder Map 角色为 localStorage 填充初始数据。
• 角色切换器是页眉栏中的单个 DropdownMenu 下拉菜单。
• 按分配对象筛选：启用某个角色后，可选择将 Pipeline 和 Deal 视图筛选为仅显示分配给该用户的记录。
• 活动归属：记录的活动应归属于当前启用的角色。
• 与 CPQ 相比，CRM 通常较少设置严格的权限限制 — 大多数用户都能查看所有内容，但只能管理分配给自己的记录。

价格/价值显示

• 在 Pipeline 项、Deal 列表和 Deal 详情中显示商机金额。
• 在 Pipeline 视图顶部显示各阶段的商机总金额。
• 使用 DOMAIN.md 中指定的货币。
• 格式：“$25,000”或“$25,000 CAD”，具体取决于 DOMAIN.md。

shadcn/ui 组件映射

将卡片视为例外，而不是默认布局元素。尽可能将内容直接放入页面主体。只有在确实需要强调、分隔、重复呈现或用于对话框／详情框架时，才使用卡片。不要构建卡片繁多的仪表板、卡片中套卡片，或由悬浮面板组成的通用网格。

CRM 元素	shadcn 组件	用法说明
实体导航项	垂直堆叠的 Button variant="ghost"	放在 SidebarContent 中。活动项使用强调色背景。包含图标、标签和计数徽章。
管道列	列分区；交易较多时使用 ScrollArea	列标题显示阶段名称、交易数量和总金额。只有在项目需要明确分隔时才使用卡片。
交易项（管道中）	紧凑的可点击行或低调的项目块	交易名称、公司、金额、负责人头像。
联系人／公司列表	Table	可排序列，上方放置搜索输入框。
记录详情	带 Separator 的全宽分区	详情直接放在页面主体中。
活动时间线	带图标的自定义列表	每项包含：类型图标、描述、日期、关联记录。人物使用 Avatar。
阶段徽章	Badge	按阶段使用颜色：潜在客户＝灰色、已确认＝蓝色、提案＝琥珀色、谈判中＝紫色、已赢单＝绿色、已输单＝红色。
交易金额	text-lg font-semibold	在管道项目和详情视图中突出显示。
负责人下拉框	Select	使用 DOMAIN.md 中的利益相关者姓名填充。不能使用自由文本。
活动类型选择器	Select 或 RadioGroup	电话、电子邮件、会议、备注、任务。
搜索输入框	带搜索图标的 Input	放在每个列表视图的顶部。
操作按钮	Button	主要操作：“添加联系人”“记录活动”。破坏性操作：“删除”“标记为已输单”。
关联记录标签	Badge variant="outline"	可点击，可导航至关联记录。
快速添加表单	Dialog 或内联表单	使用模态框快速添加联系人／交易，无需离开当前视图。
空状态	居中显示文本和操作的内联空状态块	“暂无联系人。添加您的第一位联系人。”
确认对话框	AlertDialog	删除记录、将交易标记为已输单。
Toast 通知	Sonner / toast()	创建、更新、删除或记录活动后显示。

确定性映射规则

实体 → CRM 记录映射

DOMAIN.md 实体模式	映射到	所属分区
联系人／人员／潜在客户／客户	联系人记录	联系人
公司／账户／组织／企业	公司记录	公司
交易／商机／销售／潜在客户	交易记录	交易 + 管道
活动／电话／会议／电子邮件／备注	活动条目	活动 + 记录时间线
管道／阶段／状态	管道阶段列	管道
推荐／来源／潜在客户来源	联系人或交易上的来源字段	联系人／交易详情

关系映射

DOMAIN.md 关系	实现方式
联系人隶属于公司	联系人设有公司字段（Select 下拉框）。公司详情显示关联联系人。
交易关联联系人	交易设有联系人字段（Select 下拉框）。联系人详情显示关联交易。
交易关联公司	交易设有公司字段（从联系人的公司自动填充，可编辑）。
活动关联联系人／交易	活动设有联系人和交易字段（Select 下拉框）。

业务规则 → 行为映射

DOMAIN.md 规则模式	实现方式
“管道阶段：X、Y、Z”	管道列使用这些确切名称
“只有[角色]可以关闭交易”	在“标记为已赢单／已输单”按钮上实施 RBAC 限制
“在 X 天内跟进”	对近期没有活动的联系人／交易显示逾期徽章
“金额超过 $X 的交易需要审批”	在高金额交易上显示审批要求说明
“跟踪推荐来源”	联系人设有来源字段，使用预定义的下拉选项
货币／税费／条款	在交易金额和所有开票视图中显示

流水线阶段默认值

如果 DOMAIN.md 未定义流水线阶段，请使用以下默认值：

阶段	颜色	含义
潜在客户	灰色	尚未确认资格的新咨询
已确认	蓝色	已确认是真实商机
提案	琥珀色	已发送提案或报价
谈判中	紫色	正在讨论并敲定条款
已赢单	绿色	已签约并确认收入
已丢单	红色	交易未能达成

这些默认值可以被 DOMAIN.md 中的状态模型覆盖。

真实 CRM 的关键用户体验模式

这些模式参考了 Salesforce、HubSpot、Pipedrive 和 Freshsales。遵循这些模式，打造让 CRM 用户倍感熟悉的原型：

1. 所有内容彼此关联

联系人关联到公司。交易关联到联系人和公司。活动关联到联系人和交易。每个关联名称都可点击——点击后会跳转到对应记录的详情视图。

2. 活动时间线是核心

每条记录（联系人、公司、交易）都会显示活动时间线。最近的互动最为重要。“我们上次什么时候和这个人交谈？”应当一目了然。

3. 流水线是首页

流水线看板视图是默认的着陆页。销售团队日常都在这里工作。每个阶段的流水线总金额会显示在顶部。

4. 随处可快速添加

“记录通话”和“添加交易”应能从任何视图访问——通过悬浮操作按钮，或在页眉中始终显示“快速添加”。用户不必离开当前页面就能记录互动。

5. 搜索覆盖全局

使用一个搜索栏，按名称查找联系人、公司和交易。搜索结果按实体类型分组。

6. 空状态引导用户采取行动

当某个部分没有记录时，显示有帮助的空状态提示：“还没有交易。添加第一笔交易，开始跟踪流水线进展。”同时提供主要操作按钮。

参考文件

此技能要求存在以下文件：

文件	用途
DOMAIN.md 或 .tasks/domain.md	业务术语、实体、流水线阶段、角色和品牌数据

编写任何代码前，构建者都应先读取 DOMAIN.md 或 .tasks/domain.md。