CodeBuddy

客户报备管理系统 (Customer Registration CRM)

📋 项目简介

基于 Node.js + Express + MySQL + React + Ant Design 的企业级客户报备管理系统，实现标准化客户报备流程，防止销售撞单抢单，实现客户资源公司化、流程规范化、管理可视化。

技术栈

• 后端: Node.js + Express + MySQL
• 前端: React 18 + Ant Design 5 + Vite
• 认证: JWT Token
• 图表: Recharts

核心功能

• ✅ 客户报备与查重 - 支持精确匹配和模糊匹配，防止重复报备
• ✅ 保护期管理 - 默认30天保护期，自动到期提醒
• ✅ 公海池管理 - 客户释放、领取，限制每日领取次数
• ✅ 审批流程 - 延期申请、强制释放、协同跟进
• ✅ 数据报表 - 个人仪表盘、团队统计、来源分析
• ✅ 角色权限 - 销售、销售经理、销售总监、系统管理员
• ✅ 自动化任务 - 定时检查保护期到期、自动提醒

🚀 快速开始

环境要求

• Node.js >= 14.x
• MySQL >= 5.7
• npm 或 yarn

方式一：完整启动（推荐）

查看详细启动指南：START_GUIDE.md

快速启动命令：

# 1. 安装后端依赖
npm install

# 2. 配置数据库（编辑 .env 文件）
# DB_PASSWORD=你的MySQL密码

# 3. 初始化数据库
npm run init-db

# 4. 启动后端服务
npm run dev

# 5. 启动前端界面（新终端窗口）
cd client
npm install
npm run dev

访问系统：

• 🎨 前端界面：http://localhost:3001 （推荐）
• 📡 后端 API：http://localhost:3000

方式二：仅后端服务

1. 安装依赖

   npm install
   

2. 配置环境变量

   cp .env.example .env
   

编辑 .env 文件，配置数据库连接信息：

PORT=3000
NODE_ENV=development

DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=customer_crm

JWT_SECRET=your_jwt_secret_key_change_this_in_production
JWT_EXPIRES_IN=7d

DEFAULT_PROTECTION_DAYS=30
MAX_DAILY_LEADS=5
SIMILARITY_THRESHOLD=0.8

1. 初始化数据库

   npm run init-db
   

这将自动创建数据库表结构，并生成默认管理员账号：

• 用户名：admin
• 密码：admin123

1. 启动服务

开发环境（带热重载）：

npm run dev

生产环境：

npm start

1. 访问系统

• 简单界面：http://localhost:3000
• API 基础路径：http://localhost:3000/api
• 完整管理界面：启动前端服务（见上方"方式一"）

📚 API 文档

认证接口

用户登录

POST /api/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "admin123"
}

响应：

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "uuid",
      "username": "admin",
      "real_name": "系统管理员",
      "role": "admin"
    }
  }
}

获取当前用户信息

GET /api/auth/me
Authorization: Bearer {token}

客户管理接口

客户查重

GET /api/customers/check-duplicate?customer_name=测试公司
Authorization: Bearer {token}

创建客户报备

POST /api/customers
Authorization: Bearer {token}
Content-Type: application/json

{
  "customer_name": "XX有限公司",
  "industry": "互联网/软件",
  "region": "北京",
  "contact_person": "张三",
  "contact_phone": "13800138000",
  "demand_description": "需要CRM系统",
  "source": "转介绍"
}

获取客户列表

GET /api/customers?page=1&limit=20&status=following&keyword=测试
Authorization: Bearer {token}

参数说明：

• page: 页码（默认1）
• limit: 每页数量（默认20）
• status: 客户状态（following/won/lost/released）
• keyword: 搜索关键词

获取客户详情

GET /api/customers/{customer_id}
Authorization: Bearer {token}

添加跟进记录

POST /api/customers/followup
Authorization: Bearer {token}
Content-Type: application/json

{
  "customer_id": "uuid",
  "followup_type": "call",
  "content": "电话沟通，客户表示有兴趣",
  "next_plan": "下周上门拜访"
}

公海池接口

获取公海池客户

GET /api/pool/customers?page=1&limit=20&industry=互联网
Authorization: Bearer {token}

领取客户

POST /api/pool/claim
Authorization: Bearer {token}
Content-Type: application/json

{
  "customer_id": "uuid"
}

释放客户到公海池

POST /api/pool/release
Authorization: Bearer {token}
Content-Type: application/json

{
  "customer_id": "uuid",
  "release_reason": "客户暂无需求"
}

审批流程接口

创建审批申请

POST /api/approvals
Authorization: Bearer {token}
Content-Type: application/json

{
  "type": "extension",
  "customer_id": "uuid",
  "reason": "客户决策周期较长，需要延长跟进时间",
  "extension_days": 15
}

审批类型：

• extension: 延期申请
• force_release: 强制释放
• collaboration: 协同跟进

获取待审批列表

GET /api/approvals/pending?page=1&limit=20
Authorization: Bearer {token}

处理审批

POST /api/approvals/{approval_id}/process
Authorization: Bearer {token}
Content-Type: application/json

{
  "status": "approved",
  "result_comment": "同意延期"
}

统计报表接口

个人仪表盘

GET /api/stats/dashboard
Authorization: Bearer {token}

团队统计

GET /api/stats/team?start_date=2024-01-01&end_date=2024-01-31&period=day
Authorization: Bearer {token}

客户来源分析

GET /api/stats/source-analysis
Authorization: Bearer {token}

🎭 角色权限说明

销售（sales）

• 报备客户
• 查看和管理自己的客户
• 添加跟进记录
• 从公海池领取客户
• 提交延期申请

销售经理（sales_manager）

• 销售的所有权限
• 查看团队所有客户
• 审批延期申请
• 强制释放客户
• 查看团队统计报表

销售总监（sales_director）

• 销售经理的所有权限
• 查看部门所有客户
• 查看更高级别的统计报表

系统管理员（admin）

• 所有权限
• 用户管理
• 系统配置

🗄️ 数据库设计

主要数据表

• users - 用户表
• customers - 客户报备表
• followup_records - 跟进记录表
• pool_claim_records - 公海池领取记录表
• approvals - 审批流程表
• operation_logs - 操作日志表
• attachments - 附件表

⏰ 定时任务

系统包含以下自动化任务：

1. 保护期检查 - 每小时执行

   • 自动释放到期的客户到公海池

2. 到期提醒 - 每天 09:00 执行

   • 提醒3天后到期的客户
   • 提醒1天后到期的客户

🔒 安全性

• JWT Token 认证
• 密码 bcrypt 加密
• 角色权限控制
• 数据权限隔离
• 操作日志完整记录
• SQL 注入防护（参数化查询）

🛠️ 技术栈

• 后端框架: Express.js
• 数据库: MySQL
• 认证: JWT (jsonwebtoken)
• 密码加密: bcryptjs
• 定时任务: node-cron
• 日期处理: moment
• 字符串相似度: string-similarity

📦 项目结构

customer-crm/
├── src/
│   ├── config/
│   │   └── database.js          # 数据库配置
│   ├── controllers/
│   │   ├── authController.js    # 认证控制器
│   │   ├── customerController.js # 客户管理控制器
│   │   ├── poolController.js    # 公海池控制器
│   │   ├── approvalController.js # 审批流程控制器
│   │   └── statsController.js   # 统计报表控制器
│   ├── middleware/
│   │   ├── auth.js              # 认证中间件
│   │   └── logger.js            # 日志中间件
│   ├── routes/
│   │   └── index.js             # 路由配置
│   ├── utils/
│   │   └── scheduler.js         # 定时任务
│   └── server.js                # 服务器入口
├── scripts/
│   └── initDatabase.js          # 数据库初始化脚本
├── public/
│   └── index.html               # 前端页面
├── package.json
├── .env.example
└── README.md

🔧 配置说明

业务配置

在 .env 文件中可配置：

• DEFAULT_PROTECTION_DAYS: 默认保护期天数（默认30天）
• MAX_DAILY_LEADS: 每日最大领取客户数（默认5个）
• SIMILARITY_THRESHOLD: 客户名称相似度阈值（默认0.8）

定时任务配置

在 src/utils/scheduler.js 中可修改定时任务执行时间。

🐛 常见问题

数据库连接失败

检查 .env 文件中的数据库配置是否正确，确保 MySQL 服务已启动。

JWT Token 过期

重新登录获取新的 Token。

领取客户失败

检查是否达到每日领取上限，或客户是否已被其他人领取。

📝 开发计划

第一期（MVP）✅

• 客户报备与查重
• 30天保护期管理
• 基础公海池
• 个人客户列表
• 团队报备统计

第二期规划

• 微信/钉钉通知集成
• 更丰富的数据报表
• 移动端 App
• 与主流 CRM 系统集成
• 客户标签系统
• 智能客户分配

📄 许可证

MIT License

👥 贡献

欢迎提交 Issue 和 Pull Request！

📧 联系方式

如有问题，请提交 Issue 或联系开发团队。

---

祝您使用愉快！ 🎉