企业官网建设流程全解析

Refine CRM 应用详解：基于 Refine、Ant Design 与 GraphQL 构建完整 React CRM

【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards & B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine

本文以 Refine 官方的 CRM 示例应用为主线，系统梳理其核心功能模块（Dashboard、Calendar、Scrumboard/Kanban、Sales Pipeline、Companies、Contacts、Quotes、Administration、认证授权）、所使用的技术栈（Refine 框架、Ant Design、GraphQL 与 GraphQL Subscriptions），并结合当前仓库中examples/app-crm-minimal示例的实际源码，讲解 Refine 的 provider 组合、资源声明、GraphQL 客户端封装、类型生成等实现细节，读完后可掌握如何将这一 CRM 模板适配到 B2B 应用、内部工具或任意 CRUD 应用的开发中。

一、概述：一个功能完整的 React CRM 示例

该 CRM（Customer Relationship Management，客户关系管理）应用是 Refine 团队的最新示例应用之一，基于Refine + Ant Design + GraphQL构建。它覆盖了 CRM 业务的典型场景：客户数据管理、交互跟踪、销售流程管理、项目任务管理与系统配置，全部集中在一个平台内完成。

仓库中examples/app-crm/README.md说明了重要前提：完整版的app-crm示例已迁移至企业版（Enterprise Edition），社区仍可使用精简版示例，即examples/app-crm-minimal。本仓库中的app-crm-minimal保留了 CRM 的核心骨架——Dashboard、Tasks（Scrumboard 看板）、Companies 等模块，是理解整个 CRM 应用架构的最佳入手点。

从 README 与源码结构看，该应用提供的能力包括：

• Dashboard：交互式图表与业务分析，提供关键指标、近期动态与即将到来的事件；
• Calendar：日程、会议与重要事件的管理；
• Scrumboard：Kanban 风格的任务看板，可视化项目进度；
• Companies：公司档案的创建、更新与删除，包含联系信息、沟通历史与关联联系人；
• Contacts：联系人管理与交互跟踪；
• Quotes：报价单的创建、发送与状态跟踪，可将报价转化为销售；
• Sales Pipeline：从线索到成交的销售阶段可视化，帮助团队优先排序线索、跟踪转化；
• Administration：用户角色、访问权限与系统设置的管理；
• Authentication & Authorization：登录鉴权与受保护路由。

二、关键功能模块详解

Dashboard：指标总览

Dashboard 提供 CRM 活动的一览式视图，展示关键指标（如公司、联系人、商机总数）、近期客户交互与即将到来的事件。在app-crm-minimal中，Dashboard 被拆分为多个独立组件：总计数卡片、交易图表、最新动态与即将事件，每个组件拥有自己的查询文件，例如 DASHBOARD_TOTAL_COUNTS_QUERY：

query DashboardTotalCounts { companies { totalCount } contacts { totalCount } deals { totalCount } }

组件目录结构（见examples/app-crm-minimal/src/routes/dashboard/components/下的deals-chart、latest-activities、total-count-card、upcoming-events）体现了"每个指标块自包含查询与渲染"的拆分思路，便于独立维护与替换。

Calendar：日程集成

Calendar 功能用于管理预约、会议与重要事件，保证不遗漏任何一次关键客户交互。在 Refine 中，日历通常作为自定义路由页面接入（参见examples/calendar-app示例），并通过 resources 配置纳入侧边栏导航。

Scrumboard / Project Kanban：任务看板

Scrumboard（项目看板）页面用于项目管理：可视化项目进度、管理任务，并通过可自定义的看板列让任务在状态间流转。app-crm-minimal的看板实现位于 Kanban 组件，配套column.tsx、card.tsx、item.tsx等文件，拖拽能力由@dnd-kit/core、@dnd-kit/sortable、@dnd-kit/modifiers提供（见 package.json 中的依赖声明）。

编辑页同样按字段拆分为独立表单：标题、描述、截止日期、所属阶段（stage）与负责人，位于examples/app-crm-minimal/src/routes/tasks/edit/forms/目录，这种"每字段一个 form"的结构是 CRM 这类字段较多场景下的实用组织方式。

Sales Pipeline：销售管道

Sales Pipeline 将销售流程从线索获取到成交闭合阶段化展示，帮助团队按阶段优先排序线索并跟踪转化情况。它本质上是 Kanban 模式在销售域的应用：每个阶段一列，商机卡片在列间拖拽移动。

Companies / Contacts / Quotes：核心业务对象

这三个模块是典型 CRUD 应用的核心资源。以 Companies 为例，app-crm-minimal中的路由组织为：

• 列表页：分页展示公司档案，支持新建弹窗；
• 创建页；
• 编辑页：包含公司表单与关联的 联系人表格，体现"公司—联系人"的关联关系管理。

Quotes 模块则支持创建、发送与管理报价单，跟踪状态并转化为销售；src/components/tags/下的quote-status-tag.tsx即为报价状态的标签展示组件。

Administration 与 Authentication & Authorization

Administration 部分负责用户角色、访问权限与系统设置的配置。认证授权在app-crm-minimal中通过authProvider实现，见 auth.ts：

• login：通过 GraphQLmutation Login换取accessToken并写入localStorage；
• check：调用query Me验证会话是否有效，无效则重定向到/login；
• getIdentity：拉取当前用户信息（name、email、phone、jobTitle、avatarUrl 等）供头部区域展示；
• onError：捕获UNAUTHENTICATED状态码并自动登出。

配合App.tsx中的<Authenticated>组件，登录页与受保护路由被清晰分离（详见下节）。

三、技术栈与源码实现

3.1 Refine：应用的骨架

Refine 是开源的 React 框架，为数据密集型应用（内部工具、管理面板、仪表盘、B2B 应用）提供认证、访问控制、路由、网络请求、状态管理与 i18n 等行业标准能力。CRM 示例中<Refine>的组合方式是整个应用的"骨架"，见 App.tsx：

<Refine routerProvider={routerProvider} // @refinedev/react-router dataProvider={dataProvider} // GraphQL data provider liveProvider={liveProvider} // GraphQL Subscriptions 实时通道 notificationProvider={useNotificationProvider} authProvider={authProvider} resources={resources} options={{ syncWithLocation: true, // 路由与表格状态同步 warnWhenUnsavedChanges: true, // 未保存变更提醒 liveMode: "auto", // 自动应用实时数据推送 }} >

各 provider 的来源在 providers 目录 中汇总，资源声明则在 resources.tsx：

export const resources: IResourceItem[] = [ { name: "dashboard", list: "/", meta: { label: "Dashboard", icon: <DashboardOutlined /> }, }, { name: "companies", list: "/companies", show: "/companies/:id", create: "/companies/new", edit: "/companies/edit/:id", meta: { label: "Companies", icon: <ShopOutlined /> }, }, { name: "tasks", list: "/tasks", create: "/tasks/new", edit: "/tasks/edit/:id", meta: { label: "Tasks", icon: <ProjectOutlined /> }, }, ];

resources声明驱动了侧边栏菜单、路由辅助（如useNavigate到资源页）与列表/编辑等页面映射，是 Refine 应用"配置即导航"的核心。

路由层面还挂载了三个实用组件：<UnsavedChangesNotifier />（表单未保存离开提醒）、<DocumentTitleHandler />（文档标题同步）与<CatchAllNavigate to="/login" />（未登录兜底跳转）。

3.2 Ant Design：界面层

Ant Design 提供了 CRM 所需的一致、精致的响应式 UI 组件。Refine 内置 Ant Design 集成包@refinedev/antd，在App.tsx中通过ConfigProvider应用官方主题：

<ConfigProvider theme={RefineThemes.Blue}> <AntdApp> ...

并引入@refinedev/antd/dist/reset.css与 React 19 的兼容补丁（@ant-design/v5-patch-for-react-19）。业务组件方面，示例中封装了标签（contact-status-tag、quote-status-tag、user-tag）、头像选择器（select-option-with-avatar）、分页总数（pagination-total）等可复用组件，位于examples/app-crm-minimal/src/components/目录。

3.3 GraphQL：数据层与实时更新

数据层使用 GraphQL 做高效的数据获取与更新，并集成 GraphQL Subscriptions 处理实时修改。典型场景就是项目看板：卡片在分区之间拖拽后，任务会自动更新——这正是liveProvider+liveMode: "auto"的效果。

app-crm-minimal的数据层实现值得细看，见 providers/data/index.ts：

export const API_BASE_URL = "https://api.crm.refine.dev"; export const API_URL = `${API_BASE_URL}/graphql`; export const WS_URL = "wss://api.crm.refine.dev/graphql"; // HTTP：Refine 的 GraphQLClient 封装 export const client = new GraphQLClient(API_URL, { fetch: (url: string, options: RequestInit) => { try { return fetchWrapper(url, options); } catch (error) { return Promise.reject(error as Error); } }, }); // WebSocket：graphql-ws 客户端，用于 Subscriptions export const wsClient = typeof window !== "undefined" ? createClient({ url: WS_URL, connectionParams: () => { const accessToken = localStorage.getItem("access_token"); return { headers: { Authorization: `Bearer ${accessToken}`, }, }; }, }) : undefined; export const dataProvider = graphqlDataProvider(client); export const liveProvider = wsClient ? graphqlLiveProvider(wsClient) : undefined;

几个关键点：

• graphqlDataProvider与graphqlLiveProvider来自 Refine 生态的@refinedev/nestjs-query包（该后端为 NestJS Query 风格 GraphQL API 提供 data/live provider），Refine 本身也提供通用的@refinedev/graphqldata provider，均可在创建项目阶段配置；
• WebSocket 连接参数注入 Bearer Token：从localStorage读取access_token，保证订阅通道同样经过认证；
• 错误拦截：fetch-wrapper.ts 对响应体克隆解析，把 GraphQL 协议级errors统一转换为携带message与statusCode（取自extensions.code）的错误对象抛出，供authProvider.onError等上层逻辑消费。

GraphQL 的类型安全通过 codegen 保证，配置见 graphql.config.ts：从https://api.crm.refine.dev/graphql拉取 schema，用typescript插件生成src/graphql/schema.types.ts，用import-types+typescript-operations生成src/graphql/types.ts（覆盖src/**/*.{ts,tsx}中的操作），并处理了DateTime自定义标量映射。npm run codegen即可在 schema 变更后重新生成类型。

四、最佳实践与生态集成

CRM 示例由 Refine 核心团队维护，开发过程遵循 Refine 生态的最佳实践，可归纳为：

• Provider 解耦：认证、数据、路由、通知、实时推送各自独立实现，可单独替换（例如把@refinedev/react-router换成@refinedev/nextjs-router即可迁移到 Next.js）；
• 资源驱动开发：新增一个业务对象 = 声明一个 resource + 编写 list/create/edit 页面，菜单、导航、面包屑自动跟上；
• GraphQL 类型生成而非手写：schema.types.ts与操作类型全部 codegen，编译期即可捕获字段错误；
• 实时能力内建：liveMode: "auto"让看板等页面在数据被他人/本端修改时自动刷新，无需手写轮询；
• DevTools 集成：@refinedev/devtools（DevtoolsProvider+DevtoolsPanel）提供运行时调试面板，降低排查成本。

五、这个 CRM 模板可以用在哪里

CRM 模板并不局限于单一场景，其模块化结构（Refine + Ant Design + GraphQL 的组合）可以直接复用于：

• B2B 应用：在面向企业客户的场景中管理客户交互与商机；
• 内部工具：管理员工、部门级任务与内部交互记录；
• 各类 CRUD 应用：模板的 Companies/Contacts/Quotes/Tasks 四组资源即是标准 CRUD 骨架，替换资源与字段即可衍生出新的业务系统。

由于app-crm完整版已进入企业版，社区用户建议以 app-crm-minimal 为起点：先熟悉其App.tsx的 provider 组合、resources声明与 GraphQL 数据层封装，再按需扩展 Calendar、Sales Pipeline、Quotes 等模块。

结语

这篇概览介绍了 Refine 团队基于 Refine、Ant Design 与 GraphQL 构建的 CRM 应用：功能上覆盖 Dashboard、Calendar、Scrumboard、Sales Pipeline、Companies、Contacts、Quotes 与 Administration；实现上依托 Refine 的 provider 架构（路由、数据、实时、认证、通知）与 Ant Design 内置集成，辅以 GraphQL codegen 的类型安全与 graphql-ws 的订阅能力。结合examples/app-crm-minimal的源码（provider 封装、fetch wrapper、resources 配置、Kanban 组件拆分），可以直接把它作为 B2B 应用、内部工具或通用 CRUD 项目的参考模板，按业务需要裁剪与扩展。

【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards & B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine